视频渲染

enableInstantMediaRendering

开启音视频帧加速渲染。

Objective-C

- (int)enableInstantMediaRendering NS_SWIFT_NAME(enableInstantMediaRendering());

自从

v4.1.1

成功调用该方法后，SDK 会开启加速出图和出声模式，可加快用户加入频道后的首帧出图与出声速度。 注意：

• 一旦开启快速渲染功能，只能通过调用 destroy 方法销毁 AgoraRtcEngineKit 对象来取消。

• 在该模式下，SDK 启用声网自定义加密算法来缩短建立传输链路的耗时，安全性相对于标准 DTLS (Datagram Transport Layer Security) 有所降低。如果业务场景对安全标准要求较高，请谨慎调用该方法。

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

  • -7: AgoraRtcEngineKit 尚未初始化就调用方法。

所属接口类

• AgoraRtcEngineKit

setLocalRenderMode [1/2]

设置本地视图显示模式。

Objective-C

- (int)setLocalRenderMode:(NSUInteger)uid
                     mode:(AgoraVideoRenderMode) mode;

弃用

该方法已废弃，请使用 setLocalRenderMode [2/2] 作为替代。

该方法设置本地视图显示模式。 App 可以多次调用此方法更改显示模式。

参数

参数名	描述
mode	本地视图显示模式。详见 AgoraVideoRenderMode。
uid	用户 ID。

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• AgoraRtcEngineKit

setLocalRenderMode [2/2]

更新本地视图显示模式。

Objective-C

- (int)setLocalRenderMode:(AgoraVideoRenderMode)mode
                   mirror:(AgoraVideoMirrorMode)mirror;

初始化本地用户视图后，你可以调用该方法更新本地用户视图的渲染和镜像模式。该方法只影响本地用户看到的视频画面，不影响本地发布视频。

注意：

• 请在调用 setupLocalVideo 方法初始化本地视图后，调用该方法。

• 你可以在通话中多次调用该方法，多次更新本地用户视图的显示模式。

参数

参数名	描述
mode	本地视图显示模式。详见 AgoraVideoRenderMode。
mirror	本地视图的镜像模式，详见 AgoraVideoMirrorMode。 注意： 如果你使用前置摄像头，默认启动本地用户视图镜像模式；如果你使用后置摄像头，默认关闭本地视图镜像模式。

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• AgoraRtcEngineKit

setLocalVideoMirrorMode

设置本地视频镜像。

Objective-C

- (int)setLocalVideoMirrorMode:(AgoraVideoMirrorMode)mode;

弃用:

该方法已废弃。

参数

参数名	描述
mode	本地视频镜像模式。详见 AgoraVideoMirrorMode。

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• AgoraRtcEngineKit

setRemoteRenderMode [1/2]

设置远端视图显示模式。

Objective-C

- (int)setRemoteRenderMode:(NSUInteger)uid
                      mode:(AgoraVideoRenderMode) mode;

弃用

该方法已废弃，请使用 setRemoteRenderMode [2/2]。

该方法设置远端视图显示模式。App 可以多次调用此方法更改显示模式。

参数

参数名	描述
userId	远端用户 ID。
renderMode	远端用户视图的渲染模式，详见 AgoraVideoRenderMode。

返回值

• 0：方法调用成功。

• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• AgoraRtcEngineKit

setRemoteRenderMode [2/2]

更新远端视图显示模式。

Objective-C

- (int)setRemoteRenderMode:(NSUInteger)uid
                      mode:(AgoraVideoRenderMode)mode
                    mirror:(AgoraVideoMirrorMode)mirror;

初始化远端用户视图后，你可以调用该方法更新远端用户视图在本地显示时的渲染和镜像模式。该方法只影响本地用户看到的视频画面。

注意：

• 请在调用 setupRemoteVideo 方法初始化远端视图后，调用该方法。

• 你可以在通话中多次调用该方法，多次更新远端用户视图的显示模式。

参数

参数名	描述
uid	远端用户 ID。
mode	远端用户视图的渲染模式，详见 AgoraVideoRenderMode。
mirror	远端用户视图的镜像模式，详见 AgoraVideoMirrorMode。

返回值

• 0：方法调用成功。

• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• AgoraRtcEngineKit

setRemoteRenderModeEx

设置远端视图显示模式。

Objective-C

- (int)setRemoteRenderModeEx:(NSUInteger)uid
                        mode:(AgoraVideoRenderMode)mode
                      mirror:(AgoraVideoMirrorMode)mirror
                  connection:(AgoraRtcConnection * _Nonnull)connection;

初始化远端用户视图后，你可以调用该方法更新远端用户视图在本地显示时的渲染和镜像模式。该方法只影响本地用户看到的视频画面。 注意：

• 请在调用 setupRemoteVideo 方法初始化远端视图后，调用该方法。

• 你可以在通话中多次调用该方法，多次更新远端用户视图的显示模式。

参数

参数名	描述
uid	远端用户 ID。
renderMode	远端视图显示模式，详见 AgoraVideoRenderMode。
mirrorMode	远端用户视图的镜像模式，详见 AgoraVideoMirrorMode。
connection	Connection 信息。详见 AgoraRtcConnection。

返回值

• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• AgoraRtcEngineKit(Ex)

setRenderMode

设置播放器视图的渲染模式。

Objective-C

- (void)setRenderMode:(AgoraMediaPlayerRenderMode)mode;

参数

参数名	描述
mode	播放器视图的渲染模式。详见 AgoraVideoRenderMode。

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• AgoraRtcMediaPlayerProtocol

setupLocalVideo

初始化本地视图。

Objective-C

- (int)setupLocalVideo:(AgoraRtcVideoCanvas * _Nullable)local;

该方法初始化本地视图并设置本地用户视频显示属性，只影响本地用户看到的视频画面，不影响本地发布视频。调用该方法绑定本地视频流的显示视窗(view)，并设置本地用户视图的渲染模式和镜像模式。

在 App 开发中，通常在初始化后调用该方法进行本地视频设置，然后再加入频道。退出频道后，绑定仍然有效，如果需要解除绑定，可以调用该方法将参数 view 设为 nil。

注意：

• 该方法在加入频道前后都能调用。

• 如果你希望在通话中更新本地用户视图的渲染或镜像模式，请使用 setLocalRenderMode [2/2] 方法。

参数

参数名	描述
local	本地视频显示属性。详见 AgoraRtcVideoCanvas。

返回值

• 0：方法调用成功。

• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• AgoraRtcEngineKit

setupRemoteVideo

初始化远端用户视图。

Objective-C

- (int)setupRemoteVideo:(AgoraRtcVideoCanvas * _Nonnull)remote;

该方法绑定远端用户和显示视图，并设置远端用户视图在本地显示时的渲染模式和镜像模式，只影响本地用户看到的视频画面。

调用该方法时需要指定远端视频的用户 ID，一般可以在进频道前提前设置好。如果无法在加入频道前得到远端用户的 ID，可以在收到 didJoinedOfUid 回调时调用该方法。

如需解除某个远端用户的绑定视图，可以调用该方法并将 view 设置为空。

离开频道后，SDK 会清除远端用户视图的绑定关系。

注意：

• 如果你希望在通话中更新远端用户视图的渲染或镜像模式，请使用 setRemoteRenderMode [2/2] 方法。

• 如果你使用了录制服务，录制服务会作为一个哑客户端加入频道，因此也会触发 didJoinedOfUid 回调。由于录制服务不会发送视频流，app 无需为它绑定视图。如果 app 无法识别哑客户端，可以在收到 firstRemoteVideoDecodedOfUid 回调时再绑定远端用户视图。

参数

参数名	描述
remote	远端视频显示属性。详见 AgoraRtcVideoCanvas。

返回值

• 0：方法调用成功。

• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• AgoraRtcEngineKit

setupRemoteVideoEx

初始化远端用户视图。

Objective-C

- (int)setupRemoteVideoEx:(AgoraRtcVideoCanvas* _Nonnull)remote
               connection:(AgoraRtcConnection * _Nonnull)connection;

该方法绑定远端用户和显示视图，并设置远端用户视图在本地显示时的渲染模式和镜像模式，只影响本地用户看到的视频画面。

调用该方法时需要在 AgoraRtcVideoCanvas 中指定远端视频的用户 ID，一般可以在进频道前提前设置好。

如果无法在加入频道前得到远端用户的 uid，可以在收到 didJoinedOfUid 回调时调用该方法。如果启用了视频录制功能，视频录制服务会做为一个哑客户端加入频道，因此其他客户端也会收到它的 onUserJoined 事件， app 不应给它绑定视图（因为它不会发送视频流）。

如需解除某个远端用户的绑定视图，可以调用该方法并将 view 设置为空。

离开频道后，SDK 会清除远端用户视图的绑定关系。

注意：
如果你希望在通话中更新远端用户视图的渲染或镜像模式，请使用 setRemoteRenderModeEx 方法。

参数

参数名	描述
remote	视频画布信息。详见 AgoraRtcVideoCanvas。
connection	Connection 信息。详见 AgoraRtcConnection。

返回值

• 0：方法调用成功。

• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• AgoraRtcEngineKit(Ex)

startMediaRenderingTracing

开启视频帧渲染数据打点。

Objective-C

- (int)startMediaRenderingTracing NS_SWIFT_NAME(startMediaRenderingTracing());

自从

v4.1.1

成功调用该方法后，SDK 会以调用该方法的时刻作为起点，并通过 videoRenderingTracingResultOfUid 回调报告视频帧渲染的相关信息。

注：

• SDK 默认在成功加入频道的时刻起打点，自动开始跟踪视频频的渲染事件。你可以根据实际业务场景，在合适的时机调用该方法，进行自定义打点。

• 离开当前频道后，SDK 会自动重置该时间点为下一次成功加入频道的时刻。

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

  • -7: AgoraRtcEngineKit 尚未初始化就调用方法。

所属接口类

• AgoraRtcEngineKit

startMediaRenderingTracingEx

开启视频帧渲染数据打点。

Objective-C

- (int)startMediaRenderingTracingEx:(AgoraRtcConnection * _Nonnull)connection NS_SWIFT_NAME(startMediaRenderingTracingEx(_:));

自从

v4.1.1

成功调用该方法后，SDK 会以调用该方法的时刻作为起点，并通过 videoRenderingTracingResultOfUid 回调报告视频帧渲染的相关信息。

注：

• SDK 默认在成功加入频道的时刻起打点，自动开始跟踪视频频的渲染事件。你可以根据实际业务场景，在合适的时机调用该方法，进行自定义打点。

• 离开当前频道后，SDK 会自动重置该时间点为下一次成功加入频道的时刻。

参数

参数名	描述
connection	Connection 信息。详见 AgoraRtcConnection。

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• AgoraRtcEngineKit(Ex)

videoRenderingTracingResultOfUid

视频帧渲染事件回调。

Objective-C

- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine videoRenderingTracingResultOfUid:(NSUInteger)uid currentEvent:(AgoraMediaRenderTraceEvent)currentEvent tracingInfo:(AgoraVideoRenderingTracingInfo * _Nonnull)tracingInfo NS_SWIFT_NAME(rtcEngine(_:videoRenderingTracingResultOfUid:currentEvent:tracingInfo:));

自从

v4.1.1

调用 startMediaRenderingTracing 方法或加入频道后，SDK 会触发该回调，报告视频帧渲染的事件和渲染过程中的指标。开发者可以针对指标进行专项优化，以提高出图效率。

参数

参数名	描述
uid	用户 ID。
currentEvent	当前视频帧渲染事件。详见 AgoraMediaTraceEvent。
tracingInfo	视频帧渲染过程中的指标。开发者需要尽可能降低指标值，以提高出图效率。详见 AgoraVideoRenderingTracingInfo。

所属接口类

• AgoraRtcEngineDelegate