# 视频渲染 (/zh-CN/api-reference/rtc/flutter/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>

```dart
Future<void> enableInstantMediaRendering();
```

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

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

:::note
注： 主播端和观众端都需调用该方法开启音视频帧加速渲染才可体验该功能。
一旦成功调用该方法，只能通过调用 [release](/zh-CN/api-reference/rtc/flutter/initialize#api_irtcengine_release) 方法销毁 [RtcEngine](/zh-CN/api-reference/rtc/flutter/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>

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

方法成功调用时，无返回值；方法调用失败时，会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常，你需要捕获异常并进行处理。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

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

- [RtcEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengine)

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

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

## setLocalRenderMode [#setlocalrendermode]

更新本地视图显示模式。

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

```dart
Future<void> setLocalRenderMode(
    {required RenderModeType renderMode,
    VideoMirrorModeType mirrorMode =
        VideoMirrorModeType.videoMirrorModeAuto});
```

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

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

:::note
注： 该方法仅对第一个摄像头 `(primaryCameraSource)` 生效。在自定义视频采集或使用其他类型视频源的场景下，你需要使用 [setupLocalVideo](/zh-CN/api-reference/rtc/flutter/video/video-rendering#api_irtcengine_setuplocalvideo) 方法替代该方法。
:::

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

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

- 请在调用 [setupLocalVideo](/zh-CN/api-reference/rtc/flutter/video/video-rendering#api_irtcengine_setuplocalvideo) 方法初始化本地视图后，调用该方法。
- 你可以在通话中多次调用该方法，多次更新本地用户视图的显示模式。

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

### 参数 [#参数]

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

本地视图显示模式。详见 [RenderModeType](/zh-CN/api-reference/rtc/flutter/enum-rendermodetype)。

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

本地视图的镜像模式，详见 [VideoMirrorModeType](/zh-CN/api-reference/rtc/flutter/enum-videomirrormodetype)。

:::note
注： 如果你使用前置摄像头，默认启动本地用户视图镜像模式；如果你使用后置摄像头，默认关闭本地视图镜像模式。
:::

</Parameter>
</ParameterList>

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

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

方法成功调用时，无返回值；方法调用失败时，会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常，你需要捕获异常并进行处理。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

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

- [RtcEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengine)

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

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

## setLocalRenderTargetFps [#setlocalrendertargetfps]

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

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

```dart
Future<void> setLocalRenderTargetFps(
      {required VideoSourceType sourceType, required int targetFps});
```

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

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

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

视频源的类型，详见 [VideoSourceType](/zh-CN/api-reference/rtc/flutter/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>

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

方法成功调用时，无返回值；方法调用失败时，会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常，你需要捕获异常并进行处理。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

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

- [RtcEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengine)

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

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

## setLocalVideoMirrorMode [#setlocalvideomirrormode]

设置本地视频镜像。

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

```dart
Future<void> setLocalVideoMirrorMode(VideoMirrorModeType mirrorMode);
```

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

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

:::error[废弃]
弃用: 该方法已废弃。
:::

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

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

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

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

</Parameter>
</ParameterList>

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

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

方法成功调用时，无返回值；方法调用失败时，会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常，你需要捕获异常并进行处理。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

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

- [RtcEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengine)

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

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

## setRemoteRenderMode [#setremoterendermode]

更新远端视图显示模式。

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

```dart
Future<void> setRemoteRenderMode(
    {required int uid,
    required RenderModeType renderMode,
    required VideoMirrorModeType mirrorMode});
```

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

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

:::note
注：

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

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

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

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

远端用户 ID。

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

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

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

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

</Parameter>
</ParameterList>

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

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

方法成功调用时，无返回值；方法调用失败时，会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常，你需要捕获异常并进行处理。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

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

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

- [RtcEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengine)

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

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

## setRemoteRenderModeEx [#setremoterendermodeex]

设置远端视图显示模式。

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

```dart
Future<void> setRemoteRenderModeEx(
      {required int uid,
      required RenderModeType renderMode,
      required VideoMirrorModeType mirrorMode,
      required RtcConnection connection});
```

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

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

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

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

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

远端用户 ID。

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

远端视图显示模式，详见 [RenderModeType](/zh-CN/api-reference/rtc/flutter/enum-rendermodetype)。

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

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

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

Connection 信息。详见 [RtcConnection](/zh-CN/api-reference/rtc/flutter/class-rtcconnection)。

</Parameter>
</ParameterList>

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

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

方法成功调用时，无返回值；方法调用失败时，会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常，你需要捕获异常并进行处理。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

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

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

- [RtcEngineEx](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengineex)

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

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

## setRemoteRenderTargetFps [#setremoterendertargetfps]

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

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

```dart
Future<void> setRemoteRenderTargetFps(int targetFps);
```

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

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

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

在对视频渲染帧率要求不高的场景（例如：屏幕共享、在线教育）或者远端使用中低端设备的场景下，你可以调用该方法设置视频在远端渲染的最大帧率，SDK 进行远端视频渲染的实际帧率会尽量接近该值，从而减小 CPU 消耗、提升系统性能。

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

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

该方法在加入频道前后均可调用。

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

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

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

最大渲染帧率 (fps)。支持的参数值为：1、7、10、15、24、30、60。

:::note
注： 请将此参数设置为低于视频实际帧率的渲染帧率，否则设置将不会生效。
:::

</Parameter>
</ParameterList>

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

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

方法成功调用时，无返回值；方法调用失败时，会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常，你需要捕获异常并进行处理。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

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

- [RtcEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengine)

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

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

## setRenderMode [#setrendermode]

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

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

```dart
Future<void> setRenderMode(RenderModeType renderMode);
```

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

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

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

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

播放器视图的渲染模式。详见 [RenderModeType](/zh-CN/api-reference/rtc/flutter/enum-rendermodetype)。

</Parameter>
</ParameterList>

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

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

方法成功调用时，无返回值；方法调用失败时，会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常，你需要捕获异常并进行处理。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

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

- [MediaPlayer](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_imediaplayer)

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

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

## setupLocalVideo [#setuplocalvideo]

初始化本地视图。

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

```dart
Future<void> setupLocalVideo(VideoCanvas canvas);
```

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

该方法初始化本地视图并设置本地用户视频显示属性，只影响本地用户看到的视频画面，不影响本地视频的发布。调用该方法绑定本地视频流的显示视窗 (`view`)，并设置本地用户视图的渲染模式和镜像模式。
退出频道后绑定仍然有效。如果需要停止渲染或解除绑定，可以调用该方法将参数 `view` 设为 NULL，以停止渲染并清理渲染缓存。

:::note
注：

- 在 Flutter 中你不需要主动调用该方法，请使用 [AgoraVideoView](/zh-CN/api-reference/rtc/flutter/class-agoravideoview) 渲染本地和远端视图。
- 如果你希望在通话中仅更新本地用户视图的渲染或镜像模式，请使用 [setLocalRenderMode](/zh-CN/api-reference/rtc/flutter/video/video-rendering#api_irtcengine_setlocalrendermode2) 方法。
:::

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

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

在 App 开发中，通常在初始化后调用该方法进行本地视频设置，然后再加入频道。
如果你需要在本地视频预览的画面中同时看到多个预览画面、且不同画面分别处于视频链路上不同观测点，可以重复调用该方法设置不同的 `view`，并针对每个 `view` 设置不同的观测位置。例如：将视频源设置为摄像头，然后对应两个 `view` 分别设置 `position` 为 PositionPostCapturerOrigin 和 PositionPostCapturer，即可在本地视频预览中同时看到没有经过视频前处理的原始画面和已经过视频前处理（美颜、虚拟背景、水印本地预览）的画面。

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

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

该方法在加入频道前后均可调用。

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

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

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

本地视频显示属性。详见 [VideoCanvas](/zh-CN/api-reference/rtc/flutter/class-videocanvas)。

</Parameter>
</ParameterList>

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

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

方法成功调用时，无返回值；方法调用失败时，会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常，你需要捕获异常并进行处理。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

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

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

- [RtcEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengine)

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

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

## setupRemoteVideo [#setupremotevideo]

初始化远端用户视图。

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

```dart
Future<void> setupRemoteVideo(VideoCanvas canvas);
```

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

该方法绑定远端用户和显示视图，并设置远端用户视图在本地显示时的渲染模式和镜像模式，只影响本地用户看到的视频画面。
调用该方法时需要指定远端视频的用户 ID，一般可以在进频道前提前设置好。如果无法在加入频道前得到远端用户的 ID，可以在收到 [onUserJoined](/zh-CN/api-reference/rtc/flutter/channel#callback_irtcengineeventhandler_onuserjoined) 回调时调用该方法。
如需解除某个远端用户的绑定视图，可以调用该方法并将 `view` 设置为空。
离开频道后，SDK 会清除远端用户视图的绑定关系。
在移动端自定义合图布局场景下，你可以调用该方法并针对合图视频流的每一路子视频流设置一个单独的 `view` 进行渲染。

:::note
注：

- 在 Flutter 中你不需要主动调用该方法，请使用 [AgoraVideoView](/zh-CN/api-reference/rtc/flutter/class-agoravideoview) 渲染本地和远端视图。
- 如果你希望在通话中更新远端用户视图的渲染或镜像模式，请使用 [setRemoteRenderMode](/zh-CN/api-reference/rtc/flutter/video/video-rendering#api_irtcengine_setremoterendermode2) 方法。
- 当使用录制服务时，由于它不会发送视频流，App 无需为它绑定视图。如果 App 无法识别录制服务，可以在收到 [onFirstRemoteVideoDecoded](/zh-CN/api-reference/rtc/flutter/video/video-basic#callback_irtcengineeventhandler_onfirstremotevideodecoded) 回调时再绑定远端用户视图。
:::

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

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

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

远端视频显示属性。详见 [VideoCanvas](/zh-CN/api-reference/rtc/flutter/class-videocanvas)。

</Parameter>
</ParameterList>

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

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

方法成功调用时，无返回值；方法调用失败时，会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常，你需要捕获异常并进行处理。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

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

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

- [RtcEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengine)

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

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

## setupRemoteVideoEx [#setupremotevideoex]

初始化远端用户视图。

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

```dart
Future<void> setupRemoteVideoEx(
    {required VideoCanvas canvas, required RtcConnection connection});
```

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

该方法绑定远端用户和显示视图，并设置远端用户视图在本地显示时的渲染模式和镜像模式，只影响本地用户看到的视频画面。
调用该方法时需要在 [VideoCanvas](/zh-CN/api-reference/rtc/flutter/class-videocanvas) 中指定远端视频的用户 ID，一般可以在进频道前提前设置好。
如果无法在加入频道前得到远端用户的 uid，可以在收到 [onUserJoined](/zh-CN/api-reference/rtc/flutter/channel#callback_irtcengineeventhandler_onuserjoined) 回调时调用该方法。如果启用了视频录制功能，视频录制服务会做为一个哑客户端加入频道，因此其他客户端也会收到它的 [onUserJoined](/zh-CN/api-reference/rtc/flutter/channel#callback_irtcengineeventhandler_onuserjoined) 事件， App 不应给它绑定视图（因为它不会发送视频流）。
如需解除某个远端用户的绑定视图，可以调用该方法并将 `view` 设置为空。
离开频道后，SDK 会清除远端用户视图的绑定关系。

:::note
注：

- 该方法需要在 [joinChannelEx](/zh-CN/api-reference/rtc/flutter/channel#api_irtcengineex_joinchannelex) 之后调用。
- 在 Flutter 中你不需要主动调用该方法，请使用 [AgoraVideoView](/zh-CN/api-reference/rtc/flutter/class-agoravideoview) 渲染本地和远端视图。
- 如果你希望在通话中更新远端用户视图的渲染或镜像模式，请使用 [setRemoteRenderModeEx](/zh-CN/api-reference/rtc/flutter/video/video-rendering#api_irtcengineex_setremoterendermodeex) 方法。
:::

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

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

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

视频画布信息。详见 [VideoCanvas](/zh-CN/api-reference/rtc/flutter/class-videocanvas)。

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

Connection 信息。详见 [RtcConnection](/zh-CN/api-reference/rtc/flutter/class-rtcconnection)。

</Parameter>
</ParameterList>

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

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

方法成功调用时，无返回值；方法调用失败时，会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常，你需要捕获异常并进行处理。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

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

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

- [RtcEngineEx](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengineex)

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

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

## startMediaRenderingTracing [#startmediarenderingtracing]

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

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

```dart
Future<void> startMediaRenderingTracing();
```

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

成功调用该方法后，SDK 会以调用该方法的时刻作为起点，并通过 [onVideoRenderingTracingResult](/zh-CN/api-reference/rtc/flutter/video/video-rendering#callback_irtcengineeventhandler_onvideorenderingtracingresult) 回调报告视频帧渲染的相关信息。

:::note
注：

- 如果你未调用该方法，SDK 默认以调用 [joinChannel](/zh-CN/api-reference/rtc/flutter/channel#api_irtcengine_joinchannel2) 加入频道的时刻为起始点开始打点，自动开始跟踪视频的渲染事件。你可以根据实际业务场景，在合适的时机调用该方法，进行自定义打点。
- 离开当前频道后，SDK 会自动重置该时间点为下一次加入频道的时刻。
:::

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

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

声网推荐你将该方法和 App 中的 UI 设置（按钮、滑动条等）结合使用，用于获取符合终端用户实际体验的首帧出图耗时的场景。例如：在终端用户在点击 加入频道 按钮的时刻调用该方法进行打点，然后通过 `onVideoRenderingTracingResult` 回调获取视频帧渲染过程中的各阶段耗时，从而针对各阶段耗时进行专项优化。

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

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

方法成功调用时，无返回值；方法调用失败时，会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常，你需要捕获异常并进行处理。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

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

- [RtcEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengine)

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

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

## startMediaRenderingTracingEx [#startmediarenderingtracingex]

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

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

```dart
Future<void> startMediaRenderingTracingEx(RtcConnection connection);
```

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

成功调用该方法后，SDK 会以调用该方法的时刻作为起点，并通过 [onVideoRenderingTracingResult](/zh-CN/api-reference/rtc/flutter/video/video-rendering#callback_irtcengineeventhandler_onvideorenderingtracingresult) 回调报告视频帧渲染的相关信息。

:::note
注：

- 如果你未调用该方法，SDK 默认以调用 [joinChannel](/zh-CN/api-reference/rtc/flutter/channel#api_irtcengine_joinchannel2) 加入频道的时刻为起始点开始打点，自动开始跟踪视频的渲染事件。你可以根据实际业务场景，在合适的时机调用该方法，进行自定义打点。
- 离开当前频道后，SDK 会自动重置该时间点为下一次加入频道的时刻。
:::

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

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

声网推荐你将该方法和 App 中的 UI 设置（按钮、滑动条等）结合使用，用于获取符合终端用户实际体验的首帧出图耗时的场景。例如：在终端用户在点击 加入频道 按钮的时刻调用该方法进行打点，然后通过 `onVideoRenderingTracingResult` 回调获取视频帧渲染过程中的各阶段耗时，从而针对各阶段耗时进行专项优化。

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

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

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

Connection 信息。详见 [RtcConnection](/zh-CN/api-reference/rtc/flutter/class-rtcconnection)。

</Parameter>
</ParameterList>

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

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

方法成功调用时，无返回值；方法调用失败时，会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常，你需要捕获异常并进行处理。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

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

- [RtcEngineEx](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengineex)

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

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

## onTranscodedStreamLayoutInfo [#ontranscodedstreamlayoutinfo]

已接收携带布局信息的合图视频流回调。

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

```dart
final void Function(
    RtcConnection connection,
    int uid,
    int width,
    int height,
    int layoutCount,
    List<VideoLayout> layoutlist)? onTranscodedStreamLayoutInfo;
```

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

当本地第一次接收到合图服务器发送的合图视频流，或者合图流的布局信息有变化时，SDK 会触发该回调，报告合图视频流中每一路子视频流的布局信息。

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

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

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

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

Connection 信息。详见 [RtcConnection](/zh-CN/api-reference/rtc/flutter/class-rtcconnection)。

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

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

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

合图视频流的宽度 (px)。

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

合图视频流的高度 (px)。

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

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

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

某一路合图视频流的详细布局信息。详见 [VideoLayout](/zh-CN/api-reference/rtc/flutter/class-videolayout)。

</Parameter>
</ParameterList>

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

- [RtcEngineEventHandler](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengineeventhandler)

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

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

## onVideoRenderingTracingResult [#onvideorenderingtracingresult]

视频帧渲染事件回调。

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

```dart
final void Function(
      RtcConnection connection,
      int uid,
      MediaTraceEvent currentEvent,
      VideoRenderingTracingInfo tracingInfo)? onVideoRenderingTracingResult;
```

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

调用 [startMediaRenderingTracing](/zh-CN/api-reference/rtc/flutter/video/video-rendering#api_irtcengine_startmediarenderingtracing) 方法或加入频道后，SDK 会触发该回调，报告视频帧渲染的事件和渲染过程中的指标。开发者可以针对指标进行专项优化，以提高出图效率。

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

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

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

Connection 信息。详见 [RtcConnection](/zh-CN/api-reference/rtc/flutter/class-rtcconnection)。

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

用户 ID。

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

当前视频帧渲染事件。详见 [MediaTraceEvent](/zh-CN/api-reference/rtc/flutter/enum-mediatraceevent)。

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

视频帧渲染过程中的指标。开发者需要尽可能降低指标值，以提高出图效率。详见 [VideoRenderingTracingInfo](/zh-CN/api-reference/rtc/flutter/class-videorenderingtracinginfo)。

</Parameter>
</ParameterList>

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

- [RtcEngineEventHandler](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengineeventhandler)