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

enum ProcessMode

Enumerator
kSync |
kAsync |

## ◆ ProcessResult

enum 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.

Parameters

  mode | [out] filter assign its desired the process mode ProcessMode
  independent_thread | deprecated. SDK will ignore this parameter.

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

  control | object 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

  type | requested type of the next frame
  format | requested formant of the next frame

## ◆ pendVideoFrame()

virtual ProcessResult pendVideoFrame | ( | agora::agora_refptr< IVideoFrame > | frame | ) |
| inline virtual

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

  frame | frame pending for processing

## ◆ adaptVideoFrame() [1/2]

virtual ProcessResult adaptVideoFrame | ( | agora::agora_refptr< IVideoFrame > | in,
|  | agora::agora_refptr< IVideoFrame > & | out
| ) |  |
| inline virtual

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

Parameters

  frame | frame pending for processing

## ◆ getRotationApplied()

virtual bool getRotationApplied | ( |  | ) |
| inline virtual

## ◆ isExtensionFilter()

virtual bool isExtensionFilter | ( |  | ) |
| inline virtual

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
| ) |  |
| inline virtual

Adapts the video frame.

Parameters

  capturedFrame | The reference to the captured video frame that you want to adapt.
  adaptedFrame | The 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 | ) |
| inline virtual inherited

Enables or disables the video filter.

Parameters

  enable | Whether 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 | ( |  | ) |
| inline virtual inherited

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
| ) |  |
| inline virtual inherited

Sets a private property in the `IVideoFilter` class.

Parameters

  key | The pointer to the property name.
  buf | The pointer to the buffer of this private property.
  buf_size | The 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
| ) |  |
| inline virtual inherited

Gets a private property in the IVideoFilter class.

Parameters

  key | The pointer to the property name.
  buf | The pointer to the buffer of this private property.
  buf_size | The 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 | ( |  | ) |
| inline virtual inherited

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 | ( |  | ) |
| inline virtual inherited

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

## ◆ isExternal()

virtual bool isExternal | ( |  | ) |
| inline virtual inherited

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 virtual inherited

## ◆ Release()

virtual RefCountReleaseStatus Release | ( |  | ) | const
| pure virtual inherited

## ◆ HasOneRef()

virtual bool HasOneRef | ( |  | ) | const
| pure virtual inherited