Agora C++ API Reference for All Platforms
Classes | Public Types | Public Member Functions | List of all members
agora::rtc::IExtensionVideoFilter Class Referenceabstract

Inherits agora::rtc::IVideoFilter.

Classes

class  Control
 

Public Types

enum  ProcessMode { kSync, kAsync }
 
enum  ProcessResult { kSuccess, kBypass, kDrop }
 

Public Member Functions

virtual void getProcessMode (ProcessMode &mode, bool &independent_thread)=0
 
virtual int start (agora::agora_refptr< Control > control)=0
 
virtual int stop ()=0
 
virtual void getVideoFormatWanted (VideoFrameData::Type &type, RawPixelBuffer::Format &format)=0
 
virtual ProcessResult pendVideoFrame (agora::agora_refptr< IVideoFrame > frame)
 
virtual ProcessResult adaptVideoFrame (agora::agora_refptr< IVideoFrame > in, agora::agora_refptr< IVideoFrame > &out)
 
virtual bool getRotationApplied ()
 
virtual bool isExtensionFilter ()
 
virtual bool adaptVideoFrame (const media::base::VideoFrame &capturedFrame, media::base::VideoFrame &adaptedFrame)
 
- Public Member Functions inherited from agora::rtc::IVideoFilter
virtual void setEnabled (bool enable)
 
virtual bool isEnabled ()
 
virtual int setProperty (const char *key, const void *buf, size_t buf_size)
 
virtual int getProperty (const char *key, void *buf, size_t buf_size)
 
virtual bool onDataStreamWillStart ()
 
virtual void onDataStreamWillStop ()
 
virtual bool isExternal ()
 
- Public Member Functions inherited from agora::RefCountInterface
virtual void AddRef () const =0
 
virtual RefCountReleaseStatus Release () const =0
 
virtual bool HasOneRef () const =0
 

Additional Inherited Members

- Protected Member Functions inherited from agora::RefCountInterface
virtual ~RefCountInterface ()
 

Detailed Description

The IExtensionVideoFilter class.

This class defines the interfaces that a external video extension provider can implement so as to be loaded by SDK as an "3rd party extension" for video pre- or post- processing.

Member Enumeration Documentation

◆ ProcessMode

Enumerator
kSync 
kAsync 

◆ ProcessResult

Enumerator
kSuccess 
kBypass 
kDrop 

Member Function Documentation

◆ getProcessMode()

virtual void agora::rtc::IExtensionVideoFilter::getProcessMode ( ProcessMode mode,
bool &  independent_thread 
)
pure virtual

SDK will invoke this API first to get the filter's requested process mode ProcessMode and threading model.

Parameters
mode[out] filter assign its desired the process mode ProcessMode
independent_thread[out] filter assign its desired threading model. When this boolean is set "true", an indepent thread will be assigned to the current filter and all invocations from SDK afterwards are ensured to happen on that fixed thread. If this boolean flag is set "false", the filter will re-use the thread of the SDK's data path. All invocations from SDK afterwards are also ensured to be on the same thread, however that thread is shared.
Note
If the filter implementation is not thread sensitive, we recommend to set the boolean to "false" to reduce thread context switching.

◆ start()

virtual int agora::rtc::IExtensionVideoFilter::start ( agora::agora_refptr< Control control)
pure virtual

SDK will invoke this API before feeding video frame data to the filter. Filter can perform its initialization/preparation job in this step.

Parameters
controlobject to IExtensionFilter::Control that pass to the filter which can be used for future interaction with the SDK
Returns
error code

◆ stop()

virtual int agora::rtc::IExtensionVideoFilter::stop ( )
pure virtual

SDK will invoke this API when the data stream is about to stop. Filter can perform cleanup jobs in this step.

Returns
error code

◆ getVideoFormatWanted()

virtual void agora::rtc::IExtensionVideoFilter::getVideoFormatWanted ( VideoFrameData::Type type,
RawPixelBuffer::Format format 
)
pure virtual

SDK will invoke this API every time before sending data to the filter. Filter can desigante the type VideoFrameInfo::Type and format MemPixelBuffer::Format of the next frame. SDK will then try to perform type / format conversion before sending data to the filter.

Parameters
typerequested type of the next frame
formatrequested formant of the next frame

◆ pendVideoFrame()

virtual ProcessResult agora::rtc::IExtensionVideoFilter::pendVideoFrame ( agora::agora_refptr< IVideoFrame frame)
inlinevirtual

SDK will invoke this API to send video frame to the filter if process mode is "Async". Filter invokes control's "deliverFrame" to send back the frame after processing.

Parameters
frameframe pending for processing

◆ adaptVideoFrame() [1/2]

virtual ProcessResult agora::rtc::IExtensionVideoFilter::adaptVideoFrame ( agora::agora_refptr< IVideoFrame in,
agora::agora_refptr< IVideoFrame > &  out 
)
inlinevirtual

SDK will invoke this API to send video frame to the filter if process mode is "Sync".

Parameters
frameframe pending for processing

◆ getRotationApplied()

virtual bool agora::rtc::IExtensionVideoFilter::getRotationApplied ( )
inlinevirtual

◆ isExtensionFilter()

virtual bool agora::rtc::IExtensionVideoFilter::isExtensionFilter ( )
inlinevirtual

This function indicates if the filter is implemented by third-party providers.

Note
Do not override this function.
Returns
  • true: The filter is implemented by third-party providers.
  • false: otherwise.

Reimplemented from agora::rtc::IVideoFilter.

◆ adaptVideoFrame() [2/2]

virtual bool agora::rtc::IExtensionVideoFilter::adaptVideoFrame ( const media::base::VideoFrame capturedFrame,
media::base::VideoFrame adaptedFrame 
)
inlinevirtual

Adapts the video frame.

Parameters
capturedFrameThe reference to the captured video frame that you want to adapt.
adaptedFrameThe reference to the adapted video frame.
Returns
  • true: Success.
  • false: Failure, if, for example, the IVideofilter object drops the video frame.

Implements agora::rtc::IVideoFilterBase.