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

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

  frame | frame 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

  frame | frame 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

  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 | ) |
| inlinevirtualinherited

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

  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
| ) |  |
| inlinevirtualinherited

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