AgoraVideoSinkProtocol Protocol Reference
Conforms to | NSObject |
---|---|
Declared in | AgoraMediaIO.h |
Overview
AgoraVideoSinkProtocol 定义了一套协议,开发者通过实现该接口,来创建自定义的视频渲染器,并设置给声网底层的 Media Engine。
实时通讯过程中,SDK 通常会启动默认的视频渲染器进行视频渲染。 AgoraVideoSinkProtocol 可以自定义视频渲染器,再通过调用 设置本地视频渲染器 setLocalVideoRenderer 和 设置远端视频渲染器 setRemoteVideoRenderer 接口,改变并控制默认的视频渲染器。
AgoraVideoSinkProtocol 由以下方法组成:
- 初始化渲染器(shouldInitialize)
- 启动渲染器 (shouldStart)
- 停止渲染器 (shouldStop)
- 释放渲染器 (shouldDispose)
- 获取 Buffer 类型 (AgoraVideoBufferType)
- 获取像素格式 (AgoraVideoPixelFormat)
- (可选) 输出视频像素 Buffer (renderPixelBuffer)
- (可选) 输出视频裸数据 (renderRawData)
Note: AgoraVideoSinkProtocol 接口中定义的所有方法都是回调方法,Media Engine 内部维护着状态机,并使用这些方法将自定义视频源及渲染器的状态传给 Media Engine。因此请避免直接在 App 中直接调用这些接口。 下面这个例子给出了自定义 video sink 的步骤:
- 调用 bufferType 和 AgoraVideoPixelFormat 方法设置视频帧的 Buffer 类型和像素格式。
- 实现 shouldInitialize、shouldStart、shouldStop 和 shouldDispose 管理自定义的 Video Sink。
- 根据 AgoraVideoFrameConsumer 实现 buffer 类型和像素格式。
- 创建 AgoraVideoFrameConsumer 自定义的 Video Sink 对象。
- 调用 setLocalVideoRenderer 和 setRemoteVideoRenderer 方法设置本地和远端视频渲染器。
- Media Engine 会根据内部状态调用 AgoraVideoSinkProtocol 接口中的方法。
– shouldInitialize
required method
初始化渲染器
- (BOOL)shouldInitialize
Return Value
- YES: Media Engine 会认为自定义的渲染器已经初始化好
- NO: Media Engine 会认为自定义的渲染器初始化失败,不继续往下运行
Discussion
Media Engine 初始化渲染器的时候调用这个方法。开发者可以在这个方法中做渲染器的初始化工作。如果是耗时操作,也可以提前初始化好,然后在这个方法中通过返回值告知 Media Engine 自定义渲染器已初始化好。 该方法需要开发者手动输入 YES 或 NO,告知 Media Engine 自定义渲染器的状态。
Declared In
AgoraMediaIO.h
– shouldStart
required method
启动渲染器
- (void)shouldStart
Discussion
Media Engine 在开启渲染功能的时候会回调这个方法。开发者可以在这个方法中启动渲染器。 该方法需要开发者手动输入 YES 或 NO,Media Engine 会根据输入值做对应的动作:
- YES: Media Engine 继续进行渲染
- NO:Media Engine 认为出错而停止渲染器的功能
Declared In
AgoraMediaIO.h
– shouldStop
required method
停止渲染器
- (void)shouldStop
Discussion
Media Engine 在停止渲染功能的时候会回调这个方法。开发者可以在这个方法中停止渲染。
Declared In
AgoraMediaIO.h
– shouldDispose
required method
释放渲染器
- (void)shouldDispose
Discussion
Media Engine 通知开发者渲染器即将被废弃。在 shouldDispose
返回之后,开发者就可以释放掉资源了。
Declared In
AgoraMediaIO.h
– bufferType
required method
获取 Buffer 类型
- (AgoraVideoBufferType)bufferType
Return Value
bufferType AgoraVideoBufferType
Discussion
用于在自定义渲染器的时候,需要指定 Buffer 类型,通过返回值告知引擎。Media Engine 会调用这个方法并检查返回值类型。
Declared In
AgoraMediaIO.h
– pixelFormat
required method
获取像素格式
- (AgoraVideoPixelFormat)pixelFormat
Return Value
pixelFormat AgoraVideoPixelFormat
Discussion
用于自定义渲染器的时候,还需要指定视频数据的像素格式。
Declared In
AgoraMediaIO.h
– renderPixelBuffer:rotation:
(可选)输出视频的 PixelBuffer
- (void)renderPixelBuffer:(CVPixelBufferRef _Nonnull)pixelBuffer rotation:(AgoraVideoRotation)rotation
Parameters
pixelBuffer |
视频的 PixelBuffer |
---|---|
rotation |
视频像素的顺时针旋转角度, AgoraVideoRotation |
Discussion
该方法输出视频的 PixelBuffer。
Declared In
AgoraMediaIO.h
– renderRawData:size:rotation:
输出视频裸数据
- (void)renderRawData:(void *_Nonnull)rawData size:(CGSize)size rotation:(AgoraVideoRotation)rotation
Parameters
rawData |
RawData 格式的视频 |
---|---|
size |
视频的尺寸 |
rotation |
视频的顺时针旋转角度, AgoraVideoRotation |
Declared In
AgoraMediaIO.h