Agora RTC Objective-C API Reference  Refactor
Data Structures | Public Member Functions
IExtensionVideoFilter Class Referenceabstract

Inherits IVideoFilter.

Data Structures

class  Control
 

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 isExtensionFilter ()
 
virtual bool adaptVideoFrame (const media::base::VideoFrame &capturedFrame, media::base::VideoFrame &adaptedFrame)
 
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 ()
 

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 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 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 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 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 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 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 getRotationApplied ( )
inlinevirtual

◆ isExtensionFilter()

virtual bool 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 IVideoFilter.

◆ adaptVideoFrame() [2/2]

virtual bool 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 IVideoFilterBase.

◆ setEnabled()

virtual void setEnabled ( bool  enable)
inlinevirtualinherited

Enables or disables the video filter.

Parameters
enableWhether to enable the video filter:
  • true: (Default) Enable the video filter.
  • false: Do not enable the video filter. If the filter is disabled, frames will be passed without adaption.

◆ isEnabled()

virtual bool isEnabled ( )
inlinevirtualinherited

Checks whether the video filter is enabled.

Returns
  • true: The video filter is enabled.
  • false: The video filter is not enabled.

◆ setProperty()

virtual int setProperty ( const char *  key,
const void *  buf,
size_t  buf_size 
)
inlinevirtualinherited

Sets a private property in the IVideoFilter class.

Parameters
keyThe pointer to the property name.
bufThe pointer to the buffer of this private property.
buf_sizeThe buffer size of this private property.
Returns
  • The actual size of the private property, if the method call succeeds.
  • -1, if the method call fails.

◆ getProperty()

virtual int getProperty ( const char *  key,
void *  buf,
size_t  buf_size 
)
inlinevirtualinherited

Gets a private property in the IVideoFilter class.

Parameters
keyThe pointer to the property name.
bufThe pointer to the buffer of this private property.
buf_sizeThe buffer size of this private property.
Returns
  • The actual size of the private property, if the method call succeeds.
  • -1, if the method call fails.

◆ onDataStreamWillStart()

virtual bool onDataStreamWillStart ( )
inlinevirtualinherited

This function is invoked right before data stream starts. Custom filter can override this function for initialization.

Returns
  • true: The initialization succeeds.
  • false: The initialization fails.

◆ onDataStreamWillStop()

virtual void onDataStreamWillStop ( )
inlinevirtualinherited

This function is invoked right before data stream stops. Custom filter can override this function for deinitialization.

◆ isExternal()

virtual bool isExternal ( )
inlinevirtualinherited

This function indicates if the filter is for internal use.

Note
Do not override this function.
Returns
  • true: The filter is implemented by external users.
  • false: The filter is implemented by internal users.

◆ AddRef()

virtual void AddRef ( ) const
pure virtualinherited

◆ Release()

virtual RefCountReleaseStatus Release ( ) const
pure virtualinherited

◆ HasOneRef()

virtual bool HasOneRef ( ) const
pure virtualinherited