# 视频渲染 (/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-rendering)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

<a id="toc_video_rendering"></a>

<a id="api_irtcengine_enableinstantmediarendering"></a>

<a id="ariaid-title2"></a>

## enableInstantMediaRendering [#enableinstantmediarendering]

启用音视频帧的极速渲染。

<a id="api_irtcengine_enableinstantmediarendering__prototype"></a>

```cpp
virtual int enableInstantMediaRendering() = 0;
```

<a id="api_irtcengine_enableinstantmediarendering__detailed_desc"></a>

:::info[自从]
自 v4.1.1 版本新增。
:::

调用该方法后，SDK 会启用极速帧渲染模式，从而加快用户加入频道后首帧的渲染速度。

:::note
注： 主播和观众都需要调用该方法，才能体验音视频帧的极速渲染。如需关闭该模式，只能通过调用 [release](/zh-CN/api-reference/rtc/cpp-all-platforms/initialize#api_irtcengine_release) 销毁 [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine) 对象。
:::

<a id="api_irtcengine_enableinstantmediarendering__scenario"></a>

### 适用场景 [#适用场景]

声网建议在直播场景中为观众开启该模式。

<a id="api_irtcengine_enableinstantmediarendering__timing"></a>

### 调用时机 [#调用时机]

该方法需要在加入频道前调用。

<a id="api_irtcengine_enableinstantmediarendering__return_values"></a>

### 返回值 [#返回值]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

  - -7：在 [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine) 初始化之前调用了该方法。

### 所属接口类 [#所属接口类]

- [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_setlocalrendermode1"></a>

<a id="ariaid-title3"></a>

## setLocalRenderMode [1/2] [#setlocalrendermode-12]

更新本地视频画面的显示模式。

<a id="api_irtcengine_setlocalrendermode1__prototype"></a>

```cpp
virtual int setLocalRenderMode(media::base::RENDER_MODE_TYPE renderMode) __deprecated = 0;
```

<a id="api_irtcengine_setlocalrendermode1__detailed_desc"></a>

<a id="废弃"></a>

:::error[废弃]
自 v4.0.0 版本废弃，请改用 [setLocalRenderMode [2/2]](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-rendering#api_irtcengine_setlocalrendermode2)。
:::

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

:::note
注：

- 请确保在调用该方法前已调用 [setupLocalVideo](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-rendering#api_irtcengine_setuplocalvideo) 初始化本地视频画面。
- 通话过程中，你可以多次调用该方法以更新本地视频画面。
:::

<a id="api_irtcengine_setlocalrendermode1__parameters"></a>

### 参数 [#参数]

<ParameterList>
<a id="rendermode"></a>
<Parameter name="renderMode">

本地画面的显示模式。详见 [RENDER_MODE_TYPE](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-rendermodetype)。

</Parameter>
</ParameterList>

<a id="api_irtcengine_setlocalrendermode1__return_values"></a>

### 返回值 [#返回值-1]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-1]

- [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_setlocalrendermode2"></a>

<a id="ariaid-title4"></a>

## setLocalRenderMode [2/2] [#setlocalrendermode-22]

更新本地视频画面的显示模式。

<a id="api_irtcengine_setlocalrendermode2__prototype"></a>

```cpp
virtual int setLocalRenderMode(media::base::RENDER_MODE_TYPE renderMode, VIDEO_MIRROR_MODE_TYPE mirrorMode) = 0;
```

<a id="api_irtcengine_setlocalrendermode2__detailed_desc"></a>

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

:::note
注： `setLocalRenderMode` 仅对主摄像头（`PRIMARY_CAMERA_SOURCE`）生效。在使用自定义视频采集或其他视频源的场景中，请使用 [setupLocalVideo](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-rendering#api_irtcengine_setuplocalvideo) 代替。
:::

<a id="api_irtcengine_setlocalrendermode2__timing"></a>

### 调用时机 [#调用时机-1]

- 请确保在调用该方法前已调用 [setupLocalVideo](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-rendering#api_irtcengine_setuplocalvideo) 初始化本地视频画面。
- 通话过程中，可多次调用该方法更新本地视频画面的显示模式。

<a id="api_irtcengine_setlocalrendermode2__parameters"></a>

### 参数 [#参数-1]

<ParameterList>
<a id="rendermode-1"></a>
<Parameter name="renderMode">

本地视频画面的显示模式。详见 [RENDER_MODE_TYPE](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-rendermodetype)。

</Parameter>
<a id="mirrormode"></a>
<Parameter name="mirrorMode">

本地视频画面的镜像模式。详见 [VIDEO_MIRROR_MODE_TYPE](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-videomirrormodetype)。

:::note
注： 如果使用前置摄像头，SDK 默认开启镜像模式；如果使用后置摄像头，SDK 默认关闭镜像模式。
:::

</Parameter>
</ParameterList>

<a id="api_irtcengine_setlocalrendermode2__return_values"></a>

### 返回值 [#返回值-2]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-2]

- [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_setlocalrendertargetfps"></a>

<a id="ariaid-title5"></a>

## setLocalRenderTargetFps [#setlocalrendertargetfps]

设置本地视频渲染的最大帧率。

<a id="api_irtcengine_setlocalrendertargetfps__prototype"></a>

```cpp
virtual int setLocalRenderTargetFps(VIDEO_SOURCE_TYPE sourceType, int targetFps) = 0;
```

<a id="api_irtcengine_setlocalrendertargetfps__detailed_desc"></a>

<a id="api_irtcengine_setlocalrendertargetfps__scenario"></a>

### 适用场景 [#适用场景-1]

在对视频渲染帧率要求不高的场景（如屏幕共享或在线教育）中，你可以调用该方法设置本地视频渲染的最大帧率。SDK 会尝试将本地渲染的实际帧率保持在该值附近，以降低 CPU 消耗并提升系统性能。

<a id="api_irtcengine_setlocalrendertargetfps__timing"></a>

### 调用时机 [#调用时机-2]

你可以在加入频道前或加入频道后调用该方法。

<a id="api_irtcengine_setlocalrendertargetfps__parameters"></a>

### 参数 [#参数-2]

<ParameterList>
<a id="sourcetype"></a>
<Parameter name="sourceType">

视频源类型，详见 [VIDEO_SOURCE_TYPE](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-videosourcetype)。

</Parameter>
<a id="targetfps"></a>
<Parameter name="targetFps">

本地视频的采集帧率（fps）。支持的值包括：1、7、10、15、24、30、60。

:::note
注： 将该参数设置为低于实际视频帧率的值，否则设置无效。
:::

</Parameter>
</ParameterList>

<a id="api_irtcengine_setlocalrendertargetfps__return_values"></a>

### 返回值 [#返回值-3]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-3]

- [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_setlocalvideomirrormode"></a>

<a id="ariaid-title6"></a>

## setLocalVideoMirrorMode [#setlocalvideomirrormode]

设置本地视频镜像模式。

<a id="api_irtcengine_setlocalvideomirrormode__prototype"></a>

```cpp
virtual int setLocalVideoMirrorMode(VIDEO_MIRROR_MODE_TYPE mirrorMode) __deprecated = 0;
```

<a id="api_irtcengine_setlocalvideomirrormode__detailed_desc"></a>

<a id="废弃-1"></a>

:::error[废弃]
该方法已废弃，请改用 [setupLocalVideo](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-rendering#api_irtcengine_setuplocalvideo) 或 `setLocalRenderMode`。
:::

<a id="api_irtcengine_setlocalvideomirrormode__parameters"></a>

### 参数 [#参数-3]

<ParameterList>
<a id="mirrormode-1"></a>
<Parameter name="mirrorMode">

本地视频镜像模式。详见 [VIDEO_MIRROR_MODE_TYPE](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-videomirrormodetype)。

</Parameter>
</ParameterList>

<a id="api_irtcengine_setlocalvideomirrormode__return_values"></a>

### 返回值 [#返回值-4]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-4]

- [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_setremoterendermode2"></a>

<a id="ariaid-title7"></a>

## setRemoteRenderMode [#setremoterendermode]

更新远端用户视频视图的显示模式。

<a id="api_irtcengine_setremoterendermode2__prototype"></a>

```cpp
virtual int setRemoteRenderMode(uid_t uid, media::base::RENDER_MODE_TYPE renderMode, VIDEO_MIRROR_MODE_TYPE mirrorMode) = 0;
```

<a id="api_irtcengine_setremoterendermode2__detailed_desc"></a>

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

:::note
注：

- 请在调用 [setupRemoteVideo](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-rendering#api_irtcengine_setupremotevideo) 初始化远端视图后再调用此方法。
- 通话过程中，你可以根据需要多次调用此方法更新远端用户视频视图的显示模式。
:::

<a id="api_irtcengine_setremoterendermode2__parameters"></a>

### 参数 [#参数-4]

<ParameterList>
<a id="uid"></a>
<Parameter name="uid">

远端用户 ID。

</Parameter>
<a id="rendermode-2"></a>
<Parameter name="renderMode">

远端用户视图的渲染模式，详见 [RENDER_MODE_TYPE](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-rendermodetype)。

</Parameter>
<a id="mirrormode-2"></a>
<Parameter name="mirrorMode">

远端用户视图的镜像模式，详见 [VIDEO_MIRROR_MODE_TYPE](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-videomirrormodetype)。

</Parameter>
</ParameterList>

<a id="api_irtcengine_setremoterendermode2__return_values"></a>

### 返回值 [#返回值-5]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-5]

- [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine)

<a id="api_irtcengineex_setremoterendermodeex"></a>

<a id="ariaid-title8"></a>

## setRemoteRenderModeEx [#setremoterendermodeex]

设置指定远端用户的视频显示模式。

<a id="api_irtcengineex_setremoterendermodeex__prototype"></a>

```cpp
virtual int setRemoteRenderModeEx(uid_t uid, media::base::RENDER_MODE_TYPE renderMode, VIDEO_MIRROR_MODE_TYPE mirrorMode, const RtcConnection& connection) = 0;
```

<a id="api_irtcengineex_setremoterendermodeex__detailed_desc"></a>

调用 [setupRemoteVideo](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-rendering#api_irtcengine_setupremotevideo) 初始化远端用户的视频视图后，可以调用该方法更新其渲染模式和镜像模式。该方法仅影响本地用户看到的视频视图。

:::note
注：

- 请在调用 [setupRemoteVideo](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-rendering#api_irtcengine_setupremotevideo) 初始化远端视图后调用此方法。
- 通话过程中，可以多次调用此方法更新远端用户视频视图的显示模式。
:::

<a id="api_irtcengineex_setremoterendermodeex__scenario"></a>

### 适用场景 [#适用场景-2]

该方法适用于多频道场景。

<a id="api_irtcengineex_setremoterendermodeex__parameters"></a>

### 参数 [#参数-5]

<ParameterList>
<a id="uid-1"></a>
<Parameter name="uid">

远端用户的用户 ID。

</Parameter>
<a id="rendermode-3"></a>
<Parameter name="renderMode">

视频显示模式，详见 [RENDER_MODE_TYPE](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-rendermodetype)。

</Parameter>
<a id="mirrormode-3"></a>
<Parameter name="mirrorMode">

镜像模式，详见 [VIDEO_MIRROR_MODE_TYPE](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-videomirrormodetype)。

</Parameter>
<a id="connection"></a>
<Parameter name="connection">

连接信息，详见 [RtcConnection](/zh-CN/api-reference/rtc/cpp-all-platforms/class-rtcconnection)。

</Parameter>
</ParameterList>

<a id="api_irtcengineex_setremoterendermodeex__return_values"></a>

### 返回值 [#返回值-6]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-6]

- [IRtcEngineEx](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengineex)

<a id="api_irtcengine_setremoterendertargetfps"></a>

<a id="ariaid-title9"></a>

## setRemoteRenderTargetFps [#setremoterendertargetfps]

设置远端视频渲染的最大帧率。

<a id="api_irtcengine_setremoterendertargetfps__prototype"></a>

```cpp
virtual int setRemoteRenderTargetFps(int targetFps) = 0;
```

<a id="api_irtcengine_setremoterendertargetfps__detailed_desc"></a>

<a id="api_irtcengine_setremoterendertargetfps__scenario"></a>

### 适用场景 [#适用场景-3]

在视频渲染帧率要求不高的场景（例如屏幕共享、在线教育）或远端用户使用中低端设备的情况下，你可以调用该方法设置远端客户端的视频渲染最大帧率。SDK 会尽可能将实际渲染帧率控制在该值附近，从而降低 CPU 消耗并提升系统性能。

<a id="api_irtcengine_setremoterendertargetfps__timing"></a>

### 调用时机 [#调用时机-3]

你可以在加入频道前或加入频道后调用该方法。

<a id="api_irtcengine_setremoterendertargetfps__parameters"></a>

### 参数 [#参数-6]

<ParameterList>
<a id="targetfps-1"></a>
<Parameter name="targetFps">

远端视频的渲染最大帧率（fps）。支持的取值包括：1、7、10、15、24、30、60。

- 请将该参数设置为低于实际视频帧率的值，否则设置不会生效。

</Parameter>
</ParameterList>

<a id="api_irtcengine_setremoterendertargetfps__return_values"></a>

### 返回值 [#返回值-7]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-7]

- [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine)

<a id="api_imediaplayer_setrendermode"></a>

<a id="ariaid-title10"></a>

## setRenderMode [#setrendermode]

设置媒体播放器的渲染模式。

<a id="api_imediaplayer_setrendermode__prototype"></a>

```cpp
virtual int setRenderMode(media::base::RENDER_MODE_TYPE renderMode) = 0;
```

<a id="api_imediaplayer_setrendermode__detailed_desc"></a>

<a id="api_imediaplayer_setrendermode__parameters"></a>

### 参数 [#参数-7]

<ParameterList>
<a id="rendermode-4"></a>
<Parameter name="renderMode">

渲染模式，详见 [RENDER_MODE_TYPE](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-rendermodetype)。

</Parameter>
</ParameterList>

<a id="api_imediaplayer_setrendermode__return_values"></a>

### 返回值 [#返回值-8]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-8]

- [IMediaPlayer](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_imediaplayer)

<a id="api_irtcengine_setuplocalvideo"></a>

<a id="ariaid-title11"></a>

## setupLocalVideo [#setuplocalvideo]

初始化本地视频画面。

<a id="api_irtcengine_setuplocalvideo__prototype"></a>

```cpp
virtual int setupLocalVideo(const VideoCanvas& canvas) = 0;
```

<a id="api_irtcengine_setuplocalvideo__detailed_desc"></a>

该方法在本地设备上初始化本地视频流的画面视图，仅影响本地用户看到的视频画面，不影响本地视频的发布。你可以调用该方法将本地视频流绑定到指定的视频视图（`view`），并设置该视图的渲染模式和镜像模式。
绑定关系在离开频道后仍然有效。若需停止渲染或解绑本地视频与视图的绑定关系，可将 `view` 设置为 NULL。
在实时互动场景中，如果你需要在本地视频预览中同时查看多个不同观察位置的画面，可以多次调用该方法，为每个 `view` 设置不同的观察位置。例如，将视频源设置为摄像头后，配置两个 `view`，其 `position` 分别设置为 `POSITION_POST_CAPTURER_ORIGIN` 和 `POSITION_POST_CAPTURER`，即可同时预览原始未处理的视频帧和经过美颜特效、虚拟背景、水印等预处理后的视频帧。

:::note
注： 若仅需在通话中更新本地视频视图的渲染模式或镜像模式，请改用 `setLocalRenderMode`。
:::

<a id="api_irtcengine_setuplocalvideo__scenario"></a>

### 适用场景 [#适用场景-4]

初始化后调用该方法设置本地视频，然后加入频道。在实时互动场景中，如需在本地预览中同时查看多个不同观察位置的画面，可多次调用该方法设置不同的 `view` 和观察位置。

<a id="api_irtcengine_setuplocalvideo__timing"></a>

### 调用时机 [#调用时机-4]

你可以在加入频道前或后调用该方法。

<a id="api_irtcengine_setuplocalvideo__parameters"></a>

### 参数 [#参数-8]

<ParameterList>
<a id="canvas"></a>
<Parameter name="canvas">

本地视频视图及相关设置，详见 [VideoCanvas](/zh-CN/api-reference/rtc/cpp-all-platforms/class-videocanvas)。

</Parameter>
</ParameterList>

<a id="api_irtcengine_setuplocalvideo__return_values"></a>

### 返回值 [#返回值-9]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-9]

- [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_setupremotevideo"></a>

<a id="ariaid-title12"></a>

## setupRemoteVideo [#setupremotevideo]

初始化远端用户的视频视图。

<a id="api_irtcengine_setupremotevideo__prototype"></a>

```cpp
virtual int setupRemoteVideo(const VideoCanvas& canvas) = 0;
```

<a id="api_irtcengine_setupremotevideo__detailed_desc"></a>

该方法在本地设备上初始化远端视频流的视频视图，仅影响本地用户所见的视频画面。你可以通过该方法将远端视频流绑定到指定视图，并设置该视图的渲染模式和镜像模式。你需要在调用该方法时指定远端用户的 ID。如果应用尚未获取远端用户的 ID，请在收到 [onUserJoined](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#callback_irtcengineeventhandler_onuserjoined) 回调后再设置。若要解绑远端用户与视图的绑定关系，可将 `view` 参数设置为 NULL。当远端用户离开频道时，SDK 会自动解绑该用户。在移动端进行视频合流布局自定义的场景中，你可以调用该方法，并为合流视频流中的每个子视频流设置独立的 `view` 进行渲染。

:::note
注：

- 若需在通话过程中更新远端视频视图的渲染模式或镜像模式，请使用 [setRemoteRenderMode](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-rendering#api_irtcengine_setremoterendermode2) 方法。
- 使用录制服务时，应用无需绑定视图，因为录制服务不会发送视频流。如果你的应用无法识别录制服务，请在 SDK 触发 [onFirstRemoteVideoDecoded](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#callback_irtcengineeventhandler_onfirstremotevideodecoded) 回调时将远端用户绑定到视图。
:::

<a id="api_irtcengine_setupremotevideo__parameters"></a>

### 参数 [#参数-9]

<ParameterList>
<a id="canvas-1"></a>
<Parameter name="canvas">

远端视频视图及其相关设置。详见 [VideoCanvas](/zh-CN/api-reference/rtc/cpp-all-platforms/class-videocanvas)。

</Parameter>
</ParameterList>

<a id="api_irtcengine_setupremotevideo__return_values"></a>

### 返回值 [#返回值-10]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-10]

- [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine)

<a id="api_irtcengineex_setupremotevideoex"></a>

<a id="ariaid-title13"></a>

## setupRemoteVideoEx [#setupremotevideoex]

初始化远端用户的视频视图。

<a id="api_irtcengineex_setupremotevideoex__prototype"></a>

```cpp
virtual int setupRemoteVideoEx(const VideoCanvas& canvas, const RtcConnection& connection) = 0;
```

<a id="api_irtcengineex_setupremotevideoex__detailed_desc"></a>

该方法在本地设备上初始化远端视频流的视图，仅影响你本地看到的画面。调用该方法可以将远端视频流绑定到指定视图，并设置该视图的渲染模式和镜像模式。

你需要在远端用户加入频道前，通过 [VideoCanvas](/zh-CN/api-reference/rtc/cpp-all-platforms/class-videocanvas) 设置远端用户的用户 ID。如果你尚未获取远端用户 ID，可以在收到 [onUserJoined](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#callback_irtcengineeventhandler_onuserjoined) 回调后再设置。

如果启用了视频录制功能，录制服务会以虚拟客户端身份加入频道，其他客户端也会因此收到 [onUserJoined](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#callback_irtcengineeventhandler_onuserjoined) 回调。不要将该虚拟客户端绑定到视图，因为它不会发送任何视频流。

若要解除远端用户与视图的绑定，可将 `view` 参数设置为 NULL。当远端用户离开频道后，SDK 会自动解除绑定。

:::note
注： 若需在通话过程中更新远端视频视图的渲染模式或镜像模式，请使用 [setRemoteRenderModeEx](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-rendering#api_irtcengineex_setremoterendermodeex) 方法。
:::

<a id="api_irtcengineex_setupremotevideoex__scenario"></a>

### 适用场景 [#适用场景-5]

该方法适用于多频道场景。

<a id="api_irtcengineex_setupremotevideoex__parameters"></a>

### 参数 [#参数-10]

<ParameterList>
<a id="canvas-2"></a>
<Parameter name="canvas">

远端视频视图的设置。详见 [VideoCanvas](/zh-CN/api-reference/rtc/cpp-all-platforms/class-videocanvas)。

</Parameter>
<a id="connection-1"></a>
<Parameter name="connection">

连接信息。详见 [RtcConnection](/zh-CN/api-reference/rtc/cpp-all-platforms/class-rtcconnection)。

</Parameter>
</ParameterList>

<a id="api_irtcengineex_setupremotevideoex__return_values"></a>

### 返回值 [#返回值-11]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-11]

- [IRtcEngineEx](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengineex)

<a id="api_irtcengine_startmediarenderingtracing"></a>

<a id="ariaid-title14"></a>

## startMediaRenderingTracing [#startmediarenderingtracing]

启用视频帧渲染过程的追踪功能。

<a id="api_irtcengine_startmediarenderingtracing__prototype"></a>

```cpp
virtual int startMediaRenderingTracing() = 0;
```

<a id="api_irtcengine_startmediarenderingtracing__detailed_desc"></a>

:::info[自从]
自 v4.1.1 版本新增。
:::

从成功调用该方法开始，SDK 会追踪频道中视频帧的渲染状态，并通过 [onVideoRenderingTracingResult](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-rendering#callback_irtcengineeventhandler_onvideorenderingtracingresult) 回调报告相关信息。

:::note
注：

- 如果你未调用该方法，SDK 会从调用 `joinChannel` 加入频道时开始追踪视频帧的渲染事件。你可以根据实际应用场景在合适的时间调用该方法，以设置追踪视频渲染事件的起始位置。
- 本地用户离开当前频道后，SDK 会自动从你再次加入频道时开始追踪视频渲染事件。
:::

<a id="api_irtcengine_startmediarenderingtracing__scenario"></a>

### 适用场景 [#适用场景-6]

你可以结合应用中的 UI 设置（如按钮、滑块）调用该方法，以提升用户体验。例如，在用户点击“加入频道”按钮时调用该方法，然后通过 [onVideoRenderingTracingResult](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-rendering#callback_irtcengineeventhandler_onvideorenderingtracingresult) 回调获取视频帧渲染过程所耗费的时间，从而优化相关指标。

<a id="api_irtcengine_startmediarenderingtracing__return_values"></a>

### 返回值 [#返回值-12]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

  - -7：在初始化 [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine) 之前调用了该方法。

### 所属接口类 [#所属接口类-12]

- [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine)

<a id="api_irtcengineex_startmediarenderingtracingex"></a>

<a id="ariaid-title15"></a>

## startMediaRenderingTracingEx [#startmediarenderingtracingex]

启用视频帧渲染过程的追踪。

<a id="api_irtcengineex_startmediarenderingtracingex__prototype"></a>

```cpp
virtual int startMediaRenderingTracingEx(const RtcConnection& connection) = 0;
```

<a id="api_irtcengineex_startmediarenderingtracingex__detailed_desc"></a>

:::info[自从]
自 v4.1.1 版本新增。
:::

调用该方法后，SDK 会从调用时刻开始追踪频道中视频帧的渲染状态，并通过 [onVideoRenderingTracingResult](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-rendering#callback_irtcengineeventhandler_onvideorenderingtracingresult) 回调报告相关信息。你可以结合应用中的 UI 控件（如按钮、滑块）调用该方法，以优化用户体验，例如在用户点击“加入频道”按钮时调用该方法，并通过 [onVideoRenderingTracingResult](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-rendering#callback_irtcengineeventhandler_onvideorenderingtracingresult) 回调获取视频帧渲染过程所耗时间，从而优化相关指标。

:::note
注：

- 如果你未调用该方法，SDK 会从调用 `joinChannel` 加入频道时开始追踪视频帧的渲染事件。你可以根据实际应用场景在合适的时间调用该方法，以设置追踪视频渲染事件的起始位置。
- 本地用户离开当前频道后，SDK 会自动从你加入频道的时刻开始追踪视频渲染事件。
:::

<a id="api_irtcengineex_startmediarenderingtracingex__scenario"></a>

### 适用场景 [#适用场景-7]

该方法适用于多频道场景。

<a id="api_irtcengineex_startmediarenderingtracingex__parameters"></a>

### 参数 [#参数-11]

<ParameterList>
<a id="connection-2"></a>
<Parameter name="connection">

连接信息。详见 [RtcConnection](/zh-CN/api-reference/rtc/cpp-all-platforms/class-rtcconnection)。

</Parameter>
</ParameterList>

<a id="api_irtcengineex_startmediarenderingtracingex__return_values"></a>

### 返回值 [#返回值-13]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-13]

- [IRtcEngineEx](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengineex)

<a id="callback_irtcengineeventhandler_ontranscodedstreamlayoutinfo"></a>

<a id="ariaid-title16"></a>

## onTranscodedStreamLayoutInfo [#ontranscodedstreamlayoutinfo]

本地用户接收到携带视频合图布局信息的合图视频时触发。

<a id="callback_irtcengineeventhandler_ontranscodedstreamlayoutinfo__prototype"></a>

```cpp
virtual void onTranscodedStreamLayoutInfo(uid_t uid, int width, int height, int layoutCount,const VideoLayout* layoutlist)
```

<a id="callback_irtcengineeventhandler_ontranscodedstreamlayoutinfo__detailed_desc"></a>

当你首次接收到视频合图服务器发送的合图视频，或合图布局信息发生变化时，SDK 会触发该回调，报告合图视频中每个子视频流的布局信息。

:::note
注： 该回调仅适用于 Android 和 iOS 平台。
:::

<a id="callback_irtcengineeventhandler_ontranscodedstreamlayoutinfo__timing"></a>

### 触发时机 [#触发时机]

当本地用户首次接收到视频合流服务器发送的合图视频，或混合流的布局信息发生变化时触发。

<a id="callback_irtcengineeventhandler_ontranscodedstreamlayoutinfo__parameters"></a>

### 参数 [#参数-12]

<ParameterList>
<a id="uid-2"></a>
<Parameter name="uid">

发布该合图视频的用户 ID。

</Parameter>
<a id="width"></a>
<Parameter name="width">

合图视频的宽度（单位为像素）。

</Parameter>
<a id="height"></a>
<Parameter name="height">

合图视频的高度（单位为像素）。

</Parameter>
<a id="layoutcount"></a>
<Parameter name="layoutCount">

合图视频中包含的布局信息数量。

</Parameter>
<a id="layoutlist"></a>
<Parameter name="layoutlist">

子视频流的布局信息数组。详见 [VideoLayout](/zh-CN/api-reference/rtc/cpp-all-platforms/class-videolayout)。

</Parameter>
</ParameterList>

### 所属接口类 [#所属接口类-14]

- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengineeventhandler)

<a id="callback_irtcengineeventhandler_onvideorenderingtracingresult"></a>

<a id="ariaid-title17"></a>

## onVideoRenderingTracingResult [#onvideorenderingtracingresult]

视频帧渲染事件回调。

<a id="callback_irtcengineeventhandler_onvideorenderingtracingresult__prototype"></a>

```cpp
virtual void onVideoRenderingTracingResult(uid_t uid, MEDIA_TRACE_EVENT currentEvent, VideoRenderingTracingInfo tracingInfo)
```

<a id="callback_irtcengineeventhandler_onvideorenderingtracingresult__detailed_desc"></a>

调用 [startMediaRenderingTracing](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-rendering#api_irtcengine_startmediarenderingtracing) 方法或加入频道后，SDK 会触发该回调，用于上报视频帧渲染事件及渲染过程中的各项指标。你可以通过优化这些指标，提高首帧视频的渲染效率。

<a id="callback_irtcengineeventhandler_onvideorenderingtracingresult__timing"></a>

### 触发时机 [#触发时机-1]

调用 [startMediaRenderingTracing](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-rendering#api_irtcengine_startmediarenderingtracing) 方法或加入频道后触发。

<a id="callback_irtcengineeventhandler_onvideorenderingtracingresult__parameters"></a>

### 参数 [#参数-13]

<ParameterList>
<a id="uid-3"></a>
<Parameter name="uid">

用户 ID。

</Parameter>
<a id="currentevent"></a>
<Parameter name="currentEvent">

当前视频帧渲染事件，详见 [MEDIA_TRACE_EVENT](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-mediatraceevent)。

</Parameter>
<a id="tracinginfo"></a>
<Parameter name="tracingInfo">

视频帧渲染过程中的各项指标，详见 [VideoRenderingTracingInfo](/zh-CN/api-reference/rtc/cpp-all-platforms/class-videorenderingtracinginfo)。

</Parameter>
</ParameterList>

### 所属接口类 [#所属接口类-15]

- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengineeventhandler)