# 屏幕采集 (/zh-CN/api-reference/rtc/unreal-cpp/video/screencapture)

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

<a id="toc_screencapture"></a>

<a id="api_iscreencapturesourcelist_getcount"></a>

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

## getCount [#getcount]

获取可共享的窗口和屏幕的个数。

<a id="api_iscreencapturesourcelist_getcount__prototype"></a>

```cpp
virtual unsigned int getCount() = 0;
```

<a id="api_iscreencapturesourcelist_getcount__detailed_desc"></a>

### 详情 [#详情]

:::note
注： 该方法仅适用于 macOS 和 Windows。
:::

<a id="api_iscreencapturesourcelist_getcount__return_values"></a>

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

可共享的窗口和屏幕的个数。

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

- [IScreenCaptureSourceList](/zh-CN/api-reference/rtc/unreal-cpp/rtc-interface-class#class_iscreencapturesourcelist)

<a id="api_irtcengine_getscreencapturesources"></a>

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

## getScreenCaptureSources [#getscreencapturesources]

获取可共享的屏幕和窗口对象列表。

<a id="api_irtcengine_getscreencapturesources__prototype"></a>

```cpp
virtual IScreenCaptureSourceList* getScreenCaptureSources(const SIZE& thumbSize, const SIZE& iconSize, const bool includeScreen) = 0;
```

<a id="api_irtcengine_getscreencapturesources__detailed_desc"></a>

### 详情 [#详情-1]

屏幕共享或窗口共享前，你可以调用该方法获取可共享的屏幕和窗口的对象列表，方便用户通过列表中的缩略图选择共享某个显示器的屏幕或某个窗口。列表中包含窗口 ID 和屏幕 ID 等重要信息，你可以获取到 ID 后再调用 [startScreenCaptureByWindowId](/zh-CN/api-reference/rtc/unreal-cpp/video/screencapture#api_irtcengine_startscreencapturebywindowid) 或 [startScreenCaptureByDisplayId](/zh-CN/api-reference/rtc/unreal-cpp/video/screencapture#api_irtcengine_startscreencapturebydisplayid) 开启共享。

:::note
注： 该方法仅适用于 macOS 和 Windows。
:::

<a id="api_irtcengine_getscreencapturesources__parameters"></a>

### 参数 [#参数]

<ParameterList>
<a id="thumbsize"></a>
<Parameter name="thumbSize">

屏幕或窗口的缩略图的目标尺寸（宽高单位为像素）。详见 [SIZE](https://docs.microsoft.com/en-us/windows/win32/api/windef/ns-windef-size)。SDK 会在保证原图不变形的前提下，缩放原图，使图片最长边和目标尺寸的最长边的长度一致。例如，原图宽高为 400 × 300，thumbSize 为 100 x 100，缩略图实际尺寸为 100 × 75。如果目标尺寸大于原图尺寸，缩略图即为原图，SDK 不进行缩放操作。

</Parameter>
<a id="iconsize"></a>
<Parameter name="iconSize">

程序所对应的图标的目标尺寸（宽高单位为像素）。详见 [SIZE](https://docs.microsoft.com/en-us/windows/win32/api/windef/ns-windef-size)。SDK 会在保证原图不变形的前提下，缩放原图，使图片最长边和目标尺寸的最长边的长度一致。例如，原图宽高为 400 × 300，iconSize 为 100 × 100，图标实际尺寸为 100 × 75。如果目标尺寸大于原图尺寸，图标即为原图，SDK 不进行缩放操作。

</Parameter>
<a id="includescreen"></a>
<Parameter name="includeScreen">

除了窗口信息外，SDK 是否返回屏幕信息：

- `true`：SDK 返回屏幕和窗口信息。
- `false`：SDK 仅返回窗口信息。

</Parameter>
</ParameterList>

<a id="api_irtcengine_getscreencapturesources__return_values"></a>

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

[IScreenCaptureSourceList](/zh-CN/api-reference/rtc/unreal-cpp/rtc-interface-class#class_iscreencapturesourcelist)

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

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

<a id="api_iscreencapturesourcelist_getsourceinfo"></a>

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

## getSourceInfo [#getsourceinfo]

获取指定的可共享窗口或屏幕的信息。

<a id="api_iscreencapturesourcelist_getsourceinfo__prototype"></a>

```cpp
virtual ScreenCaptureSourceInfo getSourceInfo(unsigned int index) = 0;
```

<a id="api_iscreencapturesourcelist_getsourceinfo__detailed_desc"></a>

### 详情 [#详情-2]

获取到 [IScreenCaptureSourceList](/zh-CN/api-reference/rtc/unreal-cpp/rtc-interface-class#class_iscreencapturesourcelist) 后，你可以传入指定的可共享窗口或屏幕的索引值，以获取到该窗口或屏幕的信息 ScreenCaptureSourceInfo。

:::note
注： 该方法仅适用于 macOS 和 Windows。
:::

<a id="api_iscreencapturesourcelist_getsourceinfo__parameters"></a>

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

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

指定的可共享窗口或屏幕的索引。索引值范围为 [0,[getCount](/zh-CN/api-reference/rtc/unreal-cpp/video/screencapture#api_iscreencapturesourcelist_getcount)`()`)。

</Parameter>
</ParameterList>

<a id="api_iscreencapturesourcelist_getsourceinfo__return_values"></a>

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

[ScreenCaptureSourceInfo](/zh-CN/api-reference/rtc/unreal-cpp/class-screencapturesourceinfo)

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

- [IScreenCaptureSourceList](/zh-CN/api-reference/rtc/unreal-cpp/rtc-interface-class#class_iscreencapturesourcelist)

<a id="api_irtcengine_queryscreencapturecapability"></a>

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

## queryScreenCaptureCapability [#queryscreencapturecapability]

查询设备在屏幕共享时支持的最高帧率。

<a id="api_irtcengine_queryscreencapturecapability__prototype"></a>

```cpp
#if defined(__ANDROID__) || (defined(__APPLE__) && TARGET_OS_IOS)
    virtual int queryScreenCaptureCapability() = 0;
#endif
```

<a id="api_irtcengine_queryscreencapturecapability__detailed_desc"></a>

### 详情 [#详情-3]

<a id="api_irtcengine_queryscreencapturecapability__scenario"></a>

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

该方法仅适用于 Android 和 iOS。

在屏幕共享场景下，如果你想启用高帧率（如 60 fps）、但不确定设备是否支持时，可以先调用该方法查询设备支持的最高帧率。如果设备不支持高帧率，你可以在开启屏幕共享时适当调低屏幕共享流的帧率，以确保共享场景的效果符合预期。

<a id="api_irtcengine_queryscreencapturecapability__return_values"></a>

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

- 方法调用成功时，返回设备支持的最高帧率。详见 SCREEN_CAPTURE_FRAMERATE_CAPABILITY。
- &lt;0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

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

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

<a id="api_iscreencapturesourcelist_release"></a>

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

## release [#release]

释放 [IScreenCaptureSourceList](/zh-CN/api-reference/rtc/unreal-cpp/rtc-interface-class#class_iscreencapturesourcelist)。

<a id="api_iscreencapturesourcelist_release__prototype"></a>

```cpp
virtual void release() = 0;
```

<a id="api_iscreencapturesourcelist_release__detailed_desc"></a>

### 详情 [#详情-4]

获取可共享的窗口和屏幕对象列表后，为避免内存泄露，请调用该方法释放 IScreenCaptureSourceList，不要直接删除 IScreenCaptureSourceList。

:::note
注： 该方法仅适用于 macOS 和 Windows。
:::

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

- [IScreenCaptureSourceList](/zh-CN/api-reference/rtc/unreal-cpp/rtc-interface-class#class_iscreencapturesourcelist)

<a id="api_irtcengine_setexternalmediaprojection"></a>

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

## setExternalMediaProjection [#setexternalmediaprojection]

设置 SDK 外部的 `MediaProjection` 采集屏幕视频流。

<a id="api_irtcengine_setexternalmediaprojection__prototype"></a>

```cpp
virtual int setExternalMediaProjection(void* mediaProjection) = 0;
```

<a id="api_irtcengine_setexternalmediaprojection__detailed_desc"></a>

:::caution
注意： 该方法仅适用于 Android。
:::

成功调用该方法后，你设置的外部 `MediaProjection` 会替换掉 SDK 申请的 `MediaProjection` 采集屏幕视频流。

当停止屏幕共享或销毁 [IRtcEngine](/zh-CN/api-reference/rtc/unreal-cpp/rtc-interface-class#class_irtcengine) 时，SDK 会自动释放 MediaProjection。

<a id="api_irtcengine_setexternalmediaprojection__scenario"></a>

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

如果你具备自行申请 `MediaProjection` 的开发能力，可以直接使用该 `MediaProjection` 取代 SDK 申请的 `MediaProjection` 。以下列出两种使用场景：

- 在定制系统的设备上，可避免系统弹窗（即需要用户授予屏幕采集权限），直接开始采集屏幕视频流。
- 一个屏幕共享进程中存在一个或多个子进程，避免在子进程中自行创建对象的过程出错而导致采集失败。

<a id="api_irtcengine_setexternalmediaprojection__timing"></a>

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

该方法需要在 [startScreenCapture [1/2]](/zh-CN/api-reference/rtc/unreal-cpp/video/screencapture#api_irtcengine_startscreencapture) 之前调用。

<a id="api_irtcengine_setexternalmediaprojection__restriction"></a>

### 调用限制 [#调用限制]

在调用该方法前，必须先申请 `MediaProjection` 权限。

<a id="api_irtcengine_setexternalmediaprojection__parameters"></a>

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

<ParameterList>
<a id="mediaprojection"></a>
<Parameter name="mediaProjection">

一个 [MediaProjection](https://developer.android.com/reference/android/media/projection/MediaProjection) 对象，用于采集屏幕视频流。

</Parameter>
</ParameterList>

<a id="api_irtcengine_setexternalmediaprojection__return_values"></a>

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

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

<a id="api_irtcengine_setscreencapturecontenthint"></a>

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

## setScreenCaptureContentHint [#setscreencapturecontenthint]

设置屏幕共享内容类型。

<a id="api_irtcengine_setscreencapturecontenthint__prototype"></a>

```cpp
virtual int setScreenCaptureContentHint(VIDEO_CONTENT_HINT contentHint) = 0;

```

<a id="api_irtcengine_setscreencapturecontenthint__detailed_desc"></a>

### 详情 [#详情-5]

<a id="api_irtcengine_setscreencapturecontenthint__desc"></a>

SDK 会根据不同的内容类型，使用不同的算法对共享效果进行优化。如果不调用该方法，SDK 会将屏幕共享的内容默认为 CONTENT_HINT_NONE，即无指定的内容类型。

<a id="api_irtcengine_setscreencapturecontenthint__note"></a>

:::caution
注意： 该方法在开始屏幕共享前后都能调用。
:::

<a id="api_irtcengine_setscreencapturecontenthint__parameters"></a>

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

<ParameterList>
<a id="contenthint"></a>
<Parameter name="contentHint">

屏幕共享的内容类型。详见 [VIDEO_CONTENT_HINT](/zh-CN/api-reference/rtc/unreal-cpp/enum-videocontenthint)。

</Parameter>
</ParameterList>

<a id="api_irtcengine_setscreencapturecontenthint__return_values"></a>

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

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

  - -2：传入的参数无效。
  - -8：屏幕共享状态无效。可能因为你已经共享了其他屏幕或窗口。尝试调用 [stopScreenCapture [1/2]](/zh-CN/api-reference/rtc/unreal-cpp/video/screencapture#api_irtcengine_stopscreencapture) 停止当前共享，再重新开始共享屏幕。

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

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

<a id="api_irtcengine_setscreencapturescenario"></a>

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

## setScreenCaptureScenario [#setscreencapturescenario]

设置屏幕共享的场景。

<a id="api_irtcengine_setscreencapturescenario__prototype"></a>

```cpp
virtual int setScreenCaptureScenario(SCREEN_SCENARIO_TYPE screenScenario) = 0;
```

<a id="api_irtcengine_setscreencapturescenario__detailed_desc"></a>

### 详情 [#详情-6]

开启屏幕共享或窗口共享时，你可以调用该方法设置屏幕共享的场景，SDK 会根据你设置的场景调整共享画面的画质。

:::note
注： 声网建议你在加入频道前调用该方法。
:::

<a id="api_irtcengine_setscreencapturescenario__parameters"></a>

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

<ParameterList>
<a id="screenscenario"></a>
<Parameter name="screenScenario">

屏幕共享的场景，详见 [SCREEN_SCENARIO_TYPE](/zh-CN/api-reference/rtc/unreal-cpp/enum-screenscenariotype)。

</Parameter>
</ParameterList>

<a id="api_irtcengine_setscreencapturescenario__return_values"></a>

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

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

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

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

<a id="api_irtcengine_startscreencapture"></a>

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

## startScreenCapture [1/2] [#startscreencapture-12]

开始屏幕采集。

<a id="api_irtcengine_startscreencapture__prototype"></a>

```cpp
#if defined(__ANDROID__) || (defined(__APPLE__) && TARGET_OS_IOS)
                virtual int startScreenCapture(const ScreenCaptureParameters2& captureParams) = 0;
              #endif
```

<a id="api_irtcengine_startscreencapture__detailed_desc"></a>

:::caution
注意：

- 该方法仅适用于 Android 和 iOS 平台。
- 屏幕共享流的计费标准以 ScreenVideoParameters 中的 dimensions 值为准：

  - 当你未传值时，以 1280 × 720 计费。
  - 当你传值时，以你传入的值计费。
:::

<a id="api_irtcengine_startscreencapture__scenario"></a>

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

在屏幕共享场景下，你需要调用该方法开始采集屏幕视频流。有关屏幕共享的实现方法，详见[屏幕共享](/zh-CN/realtime-media/rtc/build/video/screen-share)。

<a id="api_irtcengine_startscreencapture__timing"></a>

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

<a id="api_irtcengine_startscreencapture__apisequence"></a>

该方法在加入频道前后均可调用，区别如下：

- 如果在加入频道前调用该方法，然后调用 [joinChannel [2/2]](/zh-CN/api-reference/rtc/unreal-cpp/channel#api_irtcengine_joinchannel2) 加入频道，并设置 publishScreenCaptureVideo 为 `true`，即可开始屏幕共享。
- 如果在加入频道后调用该方法，然后调用 [updateChannelMediaOptions](/zh-CN/api-reference/rtc/unreal-cpp/channel#api_irtcengine_updatechannelmediaoptions) 更新频道媒体选项，并设置 publishScreenCaptureVideo 为 `true`，即可开始屏幕共享。

<a id="api_irtcengine_startscreencapture__restriction"></a>

### 调用限制 [#调用限制-1]

- 在 iOS 平台上，屏幕共享仅适用于 iOS 12.0 及以上。
- 在 iOS 平台上，如果你使用音频自采集而非 SDK 采集音频，为避免应用退后台后屏幕共享停止，建议你对应用添加保活处理逻辑。
- 在 iOS 平台上，该功能对设备性能要求较高，建议你在 iPhone X 及之后机型上使用。
- 在 iOS 平台上，该方法依赖于屏幕共享动态库 `AgoraReplayKitExtension.xcframework`，如果删除该动态库会导致无法正常开启屏幕共享。
- 在 Android 平台上，如果用户未授予 App 屏幕采集权限，SDK 会上报 [onPermissionError](/zh-CN/api-reference/rtc/unreal-cpp/network#callback_irtcengineeventhandler_onpermissionerror)`(2)` 回调。
- 在 Android 9 及之后版本上，为避免应用退后台后被系统杀死，建议你在 `/app/Manifests/AndroidManifest.xml` 文件中添加前台服务权限：`android.permission.FOREGROUND_SERVICE`。
- 因 Android 性能限制，屏幕共享不支持 Android TV。
- 因 Android 系统限制，使用华为手机进行屏幕共享时，为避免崩溃，请不要在共享过程中调节屏幕共享流的视频编码分辨率。
- 因 Android 系统限制，部分小米手机不支持屏幕共享时采集系统音频。
- 为提高屏幕共享时采集系统音频的成功率，建议你在加入频道前通过 [setAudioScenario](/zh-CN/api-reference/rtc/unreal-cpp/audio/audio-basic#api_irtcengine_setaudioscenario) 方法设置音频场景为 AUDIO_SCENARIO_GAME_STREAMING。

<a id="api_irtcengine_startscreencapture__related"></a>

<a id="api_irtcengine_startscreencapture__parameters"></a>

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

<ParameterList>
<a id="captureparams"></a>
<Parameter name="captureParams">

屏幕共享的编码参数配置。详见 [ScreenCaptureParameters2](/zh-CN/api-reference/rtc/unreal-cpp/class-screencaptureparameters2)。

</Parameter>
</ParameterList>

<a id="api_irtcengine_startscreencapture__return_values"></a>

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

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

  - -2 (iOS 平台): 参数为空。
  - -2 (Anroid 平台): 系统版本过低，请确保 Android API 级别不低于 21。
  - -3 (Anroid 平台): 无法采集系统音频，请确保 Android API 级别不低于 29。

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

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

<a id="api_irtcengine_startscreencapture2"></a>

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

## startScreenCapture [2/2] [#startscreencapture-22]

开始屏幕采集并指定视频源。

<a id="api_irtcengine_startscreencapture2__prototype"></a>

```cpp
virtual int startScreenCapture(VIDEO_SOURCE_TYPE sourceType, const ScreenCaptureConfiguration& config) = 0;
```

<a id="api_irtcengine_startscreencapture2__detailed_desc"></a>

:::caution
注意： 该方法仅适用于 macOS 和 Windows 平台。
:::

<a id="api_irtcengine_startscreencapture2__scenario"></a>

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

在屏幕共享场景下，你需要调用该方法开始采集屏幕视频流。

SDK 支持一系列开启屏幕采集的方法，它们之间存在以下区别，请根据实际场景选用：

- [startScreenCapture [1/2]](/zh-CN/api-reference/rtc/unreal-cpp/video/screencapture#api_irtcengine_startscreencapture)/[startScreenCaptureByDisplayId](/zh-CN/api-reference/rtc/unreal-cpp/video/screencapture#api_irtcengine_startscreencapturebydisplayid)/[startScreenCaptureByWindowId](/zh-CN/api-reference/rtc/unreal-cpp/video/screencapture#api_irtcengine_startscreencapturebywindowid)：仅支持采集单个屏幕或窗口，适合仅共享单个屏幕的场景。
- [startScreenCapture [2/2]](/zh-CN/api-reference/rtc/unreal-cpp/video/screencapture#api_irtcengine_startscreencapture2)：支持指定多个视频源，以采集多路屏幕共享流，用于本地合图或者多频道发布场景。

<a id="api_irtcengine_startscreencapture2__timing"></a>

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

该方法在加入频道前后均可调用，区别如下：

- 如果在加入频道前调用该方法，然后调用 [joinChannel [2/2]](/zh-CN/api-reference/rtc/unreal-cpp/channel#api_irtcengine_joinchannel2) 加入频道，并设置 publishScreenCaptureVideo 为 `true`，即可开始屏幕共享。
- 如果在加入频道后调用该方法，然后调用 [updateChannelMediaOptions](/zh-CN/api-reference/rtc/unreal-cpp/channel#api_irtcengine_updatechannelmediaoptions) 更新频道媒体选项，并设置 publishScreenCaptureVideo 为 `true`，即可开始屏幕共享。

<a id="api_irtcengine_startscreencapture2__restriction"></a>

### 调用限制 [#调用限制-2]

- 如果调用该方法开始屏幕采集，则停止屏幕采集时需要调用 [stopScreenCapture [2/2]](/zh-CN/api-reference/rtc/unreal-cpp/video/screencapture#api_irtcengine_stopscreencapture2)。
- 在 Windows 平台上，最多支持 4 路屏幕采集的视频流。
- 在 macOS 平台上，最多支持 1 路屏幕采集的视频流。

<a id="api_irtcengine_startscreencapture2__parameters"></a>

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

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

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

:::caution
注意： 在 macOS 平台上，仅支持将该参数设置为 VIDEO_SOURCE_SCREEN (2)。
:::

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

屏幕采集配置。详见 [ScreenCaptureConfiguration](/zh-CN/api-reference/rtc/unreal-cpp/class-screencaptureconfiguration)。

</Parameter>
</ParameterList>

<a id="api_irtcengine_startscreencapture2__return_values"></a>

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

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

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

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

<a id="api_irtcengine_startscreencapturebydisplayid"></a>

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

## startScreenCaptureByDisplayId [#startscreencapturebydisplayid]

开始采集指定屏幕的视频流。

<a id="api_irtcengine_startscreencapturebydisplayid__prototype"></a>

```cpp
virtual int startScreenCaptureByDisplayId(int64_t displayId, const Rectangle& regionRect,
                                            const ScreenCaptureParameters& captureParams) = 0;
```

<a id="api_irtcengine_startscreencapturebydisplayid__detailed_desc"></a>

采集一个屏幕或该屏幕部分区域的视频流。

:::caution
注意： 该方法仅适用于 Windows 和 macOS。
:::

<a id="api_irtcengine_startscreencapturebydisplayid__scenario"></a>

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

在屏幕共享场景下，你需要调用该方法开始采集屏幕视频流。有关屏幕共享的实现方法，详见[屏幕共享](/zh-CN/realtime-media/rtc/build/video/screen-share)。

<a id="api_irtcengine_startscreencapturebydisplayid__timing"></a>

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

<a id="api_irtcengine_startscreencapturebydisplayid__apisequence"></a>

该方法在加入频道前后均可调用，区别如下：

- 如果在加入频道前调用该方法，然后调用 [joinChannel [2/2]](/zh-CN/api-reference/rtc/unreal-cpp/channel#api_irtcengine_joinchannel2) 加入频道，并设置 publishScreenTrack 或 publishSecondaryScreenTrack 为 `true`，即可开始屏幕共享。
- 如果在加入频道后调用该方法，然后调用 [updateChannelMediaOptions](/zh-CN/api-reference/rtc/unreal-cpp/channel#api_irtcengine_updatechannelmediaoptions) 更新频道媒体选项，并设置 publishScreenTrack 或 publishSecondaryScreenTrack 为 `true`，即可开始屏幕共享。

<a id="api_irtcengine_startscreencapturebydisplayid__restriction"></a>

### 调用限制 [#调用限制-3]

无。

<a id="api_irtcengine_startscreencapturebydisplayid__parameters"></a>

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

<ParameterList>
<a id="displayid"></a>
<Parameter name="displayId">

指定待共享的屏幕 ID。

:::note
注： 对于 Windows 平台，如果你需要同时共享两个屏幕（主屏 + 副屏），可以在调用该方法时，将 displayId 设置为 `-1`。
:::

</Parameter>
<a id="regionrect"></a>
<Parameter name="regionRect">

（可选）指定待共享区域相对于整个屏幕的位置。如需共享整个屏幕，则填 `nil`。详见 [Rectangle](/zh-CN/api-reference/rtc/unreal-cpp/class-rectangle)。

如果设置的共享区域超出了屏幕的边界，则只共享屏幕内的内容；如果宽或高设为 0，则共享整个屏幕。

</Parameter>
<a id="captureparams-1"></a>
<Parameter name="captureParams">

屏幕共享的参数配置。默认的视频编码分辨率为 1920 × 1080，即 2073600 像素。该像素值为计费标准。详见 [ScreenCaptureParameters](/zh-CN/api-reference/rtc/unreal-cpp/class-screencaptureparameters)。

:::caution
注意： 屏幕共享流的视频属性只需通过该参数设置，与 [setVideoEncoderConfiguration](/zh-CN/api-reference/rtc/unreal-cpp/video/video-basic#api_irtcengine_setvideoencoderconfiguration) 无关。
:::

</Parameter>
</ParameterList>

<a id="api_irtcengine_startscreencapturebydisplayid__return_values"></a>

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

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

  - -2：传入的参数无效。
  - -8：屏幕共享状态无效。可能因为你已经共享了其他屏幕或窗口。尝试调用 [stopScreenCapture [1/2]](/zh-CN/api-reference/rtc/unreal-cpp/video/screencapture#api_irtcengine_stopscreencapture) 停止当前共享，再重新开始共享屏幕。

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

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

<a id="api_irtcengine_startscreencapturebyscreenrect"></a>

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

## startScreenCaptureByScreenRect [#startscreencapturebyscreenrect]

开始采集指定屏幕区域的视频流。

<a id="api_irtcengine_startscreencapturebyscreenrect__prototype"></a>

```cpp
virtual int startScreenCaptureByScreenRect(const Rectangle& screenRect,
     const Rectangle& regionRect,
     const ScreenCaptureParameters& captureParams) = 0;
```

<a id="api_irtcengine_startscreencapturebyscreenrect__detailed_desc"></a>

### 详情 [#详情-7]

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

:::error[弃用：]
该方法已废弃。请改用 [startScreenCaptureByDisplayId](/zh-CN/api-reference/rtc/unreal-cpp/video/screencapture#api_irtcengine_startscreencapturebydisplayid)。如果你需要在设备外接其他显示屏的情况下开启屏幕共享，强烈建议你使用 startScreenCaptureByDisplayId。
:::

<a id="api_irtcengine_startscreencapturebyscreenrect__desc"></a>

共享一个屏幕或该屏幕的部分区域。你需要在该方法中指定想要共享的屏幕区域。

该方法在加入频道前后均可调用，区别如下：

- 如果在加入频道前调用该方法，然后调用 [joinChannel [2/2]](/zh-CN/api-reference/rtc/unreal-cpp/channel#api_irtcengine_joinchannel2) 加入频道，并设置 publishScreenTrack 或 publishSecondaryScreenTrack 为 `true`，即可开始屏幕共享。
- 如果在加入频道后调用该方法，然后调用 [updateChannelMediaOptions](/zh-CN/api-reference/rtc/unreal-cpp/channel#api_irtcengine_updatechannelmediaoptions) 更新频道媒体选项，并设置 publishScreenTrack 或 publishSecondaryScreenTrack 为 `true`，即可开始屏幕共享。

<a id="api_irtcengine_startscreencapturebyscreenrect__note"></a>

:::caution
注意： 该方法仅适用于 Windows 平台。
:::

<a id="api_irtcengine_startscreencapturebyscreenrect__parameters"></a>

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

<ParameterList>
<a id="screenrect"></a>
<Parameter name="screenRect">

指定待共享的屏幕相对于虚拟屏的位置。

</Parameter>
<a id="regionrect-1"></a>
<Parameter name="regionRect">

（可选）指定待共享区域相对于整个屏幕的位置。如不填，则表示共享整个屏幕。详见 [Rectangle](/zh-CN/api-reference/rtc/unreal-cpp/class-rectangle)。如果设置的共享区域超出了屏幕的边界，则只共享屏幕内的内容；如果将 width 或 height 设为 0 ，则共享整个屏幕。

</Parameter>
<a id="captureparams-2"></a>
<Parameter name="captureParams">

屏幕共享的编码参数配置。默认的分辨率为 1920 x 1080，即 2073600 像素。该像素值为计费标准。详见 [ScreenCaptureParameters](/zh-CN/api-reference/rtc/unreal-cpp/class-screencaptureparameters)。

</Parameter>
</ParameterList>

<a id="api_irtcengine_startscreencapturebyscreenrect__return_values"></a>

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

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

  - -2：传入的参数无效。
  - -8：屏幕共享状态无效。可能因为你已经共享了其他屏幕或窗口。尝试调用 [stopScreenCapture [1/2]](/zh-CN/api-reference/rtc/unreal-cpp/video/screencapture#api_irtcengine_stopscreencapture) 停止当前共享，再重新开始共享屏幕。

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

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

<a id="api_irtcengine_startscreencapturebywindowid"></a>

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

## startScreenCaptureByWindowId [#startscreencapturebywindowid]

开始采集指定窗口的视频流。

<a id="api_irtcengine_startscreencapturebywindowid__prototype"></a>

```cpp
virtual int startScreenCaptureByWindowId(int64_t windowId,
                const Rectangle& regionRect,
                const ScreenCaptureParameters& captureParams) = 0;
```

<a id="api_irtcengine_startscreencapturebywindowid__detailed_desc"></a>

<a id="api_irtcengine_startscreencapturebywindowid__desc"></a>

共享一个窗口或该窗口的部分区域。用户需要在该方法中指定想要共享的窗口 ID。

<a id="api_irtcengine_startscreencapturebywindowid__note"></a>

:::caution
注意： 该方法仅适用于 macOS 和 Windows 平台。
:::

该方法支持共享通用 Windows 平台（UWP）应用窗口。声网使用最新版 SDK 对主流的 UWP 应用进行了测试，结果如下：

<a id="api_irtcengine_startscreencapturebywindowid__table_lvk_tfs_r4b"></a>

<DocsTable>
<thead>
<tr>
<th scope="col">**系统版本**</th>
<th scope="col">**软件**</th>
<th scope="col">**软件版本**</th>
<th scope="col">**是否支持**</th>
</tr>
</thead>
<tbody>
<tr>
<td rowSpan={8}>win10</td>
<td>Chrome</td>
<td>76.0.3809.100</td>
<td>否</td>
</tr>
<tr>
<td>Office Word</td>
<td rowSpan={3}>18.1903.1152.0</td>
<td>是</td>
</tr>
<tr>
<td>Office Excel</td>
<td>否</td>
</tr>
<tr>
<td>Office PPT</td>
<td>是</td>
</tr>
<tr>
<td>WPS Word</td>
<td rowSpan={3}>11.1.0.9145</td>
<td rowSpan={3}>是</td>
</tr>
<tr>
<td>WPS Excel</td>
</tr>
<tr>
<td>WPS PPT</td>
</tr>
<tr>
<td>Media Player（系统自带）</td>
<td>全部</td>
<td>是</td>
</tr>
<tr>
<td rowSpan={8}>win8</td>
<td>Chrome</td>
<td>全部</td>
<td>是</td>
</tr>
<tr>
<td>Office Word</td>
<td rowSpan={3}>全部</td>
<td rowSpan={3}>是</td>
</tr>
<tr>
<td>Office Excel</td>
</tr>
<tr>
<td>Office PPT</td>
</tr>
<tr>
<td>WPS Word</td>
<td rowSpan={3}>11.1.0.9098</td>
<td rowSpan={3}>是</td>
</tr>
<tr>
<td>WPS Excel</td>
</tr>
<tr>
<td>WPS PPT</td>
</tr>
<tr>
<td>Media Player（系统自带）</td>
<td>全部</td>
<td>是</td>
</tr>
<tr>
<td rowSpan={8}>win7</td>
<td>Chrome</td>
<td>73.0.3683.103</td>
<td>否</td>
</tr>
<tr>
<td>Office Word</td>
<td rowSpan={3}>全部</td>
<td rowSpan={3}>是</td>
</tr>
<tr>
<td>Office Excel</td>
</tr>
<tr>
<td>Office PPT</td>
</tr>
<tr>
<td>WPS Word</td>
<td rowSpan={2}>11.1.0.9098</td>
<td rowSpan={2}>否</td>
</tr>
<tr>
<td>WPS Excel</td>
</tr>
<tr>
<td>WPS PPT</td>
<td>11.1.0.9098</td>
<td>是</td>
</tr>
<tr>
<td>Media Player（系统自带）</td>
<td>全部</td>
<td>否</td>
</tr>
</tbody>
</DocsTable>

<a id="api_irtcengine_startscreencapturebywindowid__scenario"></a>

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

在屏幕共享场景下，你需要调用该方法开始采集屏幕视频流。有关屏幕共享的实现方法，详见[屏幕共享](/zh-CN/realtime-media/rtc/build/video/screen-share)。

<a id="api_irtcengine_startscreencapturebywindowid__timing"></a>

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

该方法在加入频道前后均可调用，区别如下：

- 如果在加入频道前调用该方法，然后调用 [joinChannel [2/2]](/zh-CN/api-reference/rtc/unreal-cpp/channel#api_irtcengine_joinchannel2) 加入频道，并设置 publishScreenTrack 或 publishSecondaryScreenTrack 为 `true`，即可开始屏幕共享。
- 如果在加入频道后调用该方法，然后调用 [updateChannelMediaOptions](/zh-CN/api-reference/rtc/unreal-cpp/channel#api_irtcengine_updatechannelmediaoptions) 更新频道媒体选项，并设置 publishScreenTrack 或 publishSecondaryScreenTrack 为 `true`，即可开始屏幕共享。

<a id="api_irtcengine_startscreencapturebywindowid__restriction"></a>

### 调用限制 [#调用限制-4]

SDK 的窗口共享功能依赖于 WGC（Windows Graphics Capture）或 GDI（Graphics Device Interface）采集，WGC 在早于 Windows 10 2004 的系统上无法设置关闭鼠标采集，因此，当你在搭载早于 Windows 10 2004 系统的设备上进行窗口共享时，可能出现 `captureMouseCursor(false)` 不生效的现象。详见 [ScreenCaptureParameters](/zh-CN/api-reference/rtc/unreal-cpp/class-screencaptureparameters)。

<a id="api_irtcengine_startscreencapturebywindowid__parameters"></a>

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

<ParameterList>
<a id="windowid"></a>
<Parameter name="windowId">

指定待共享的窗口 ID。

</Parameter>
<a id="regionrect-2"></a>
<Parameter name="regionRect">

（可选）指定待共享区域相对于整个屏幕的位置。如不填，则表示共享整个屏幕。详见 [Rectangle](/zh-CN/api-reference/rtc/unreal-cpp/class-rectangle)。如果设置的共享区域超出了窗口的边界，则只共享窗口内的内容；如果宽或高为 0，则共享整个窗口。

</Parameter>
<a id="captureparams-3"></a>
<Parameter name="captureParams">

屏幕共享的参数配置。默认的分辨率为 1920 x 1080，即 2073600 像素。该像素值为计费标准。详见 [ScreenCaptureParameters](/zh-CN/api-reference/rtc/unreal-cpp/class-screencaptureparameters)。

</Parameter>
</ParameterList>

<a id="api_irtcengine_startscreencapturebywindowid__return_values"></a>

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

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

  - -2：传入的参数无效。
  - -8：屏幕共享状态无效。可能因为你已经共享了其他屏幕或窗口。尝试调用 [stopScreenCapture [1/2]](/zh-CN/api-reference/rtc/unreal-cpp/video/screencapture#api_irtcengine_stopscreencapture) 停止当前共享，再重新开始共享屏幕。

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

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

<a id="api_irtcengine_stopscreencapture"></a>

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

## stopScreenCapture [1/2] [#stopscreencapture-12]

停止屏幕采集。

<a id="api_irtcengine_stopscreencapture__prototype"></a>

```cpp
#if defined(_WIN32) || defined(__APPLE__) || defined(__ANDROID__)
  virtual int stopScreenCapture() = 0;
#endif
```

<a id="api_irtcengine_stopscreencapture__detailed_desc"></a>

<a id="api_irtcengine_stopscreencapture__scenario"></a>

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

如果你调用了 [startScreenCapture [1/2]](/zh-CN/api-reference/rtc/unreal-cpp/video/screencapture#api_irtcengine_startscreencapture)、[startScreenCaptureByWindowId](/zh-CN/api-reference/rtc/unreal-cpp/video/screencapture#api_irtcengine_startscreencapturebywindowid) 或 [startScreenCaptureByDisplayId](/zh-CN/api-reference/rtc/unreal-cpp/video/screencapture#api_irtcengine_startscreencapturebydisplayid) 开启屏幕采集，则停止屏幕采集时需要调用该方法。

<a id="api_irtcengine_stopscreencapture__timing"></a>

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

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

<a id="api_irtcengine_stopscreencapture__restriction"></a>

### 调用限制 [#调用限制-5]

无。

<a id="api_irtcengine_stopscreencapture__return_values"></a>

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

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

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

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

<a id="api_irtcengine_stopscreencapture2"></a>

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

## stopScreenCapture [2/2] [#stopscreencapture-22]

停止对指定的视频源进行屏幕采集。

<a id="api_irtcengine_stopscreencapture2__prototype"></a>

```cpp
virtual int stopScreenCapture(VIDEO_SOURCE_TYPE sourceType) = 0;
```

<a id="api_irtcengine_stopscreencapture2__detailed_desc"></a>

:::caution
注意： 该方法仅适用于 macOS 和 Windows 平台。
:::

<a id="api_irtcengine_stopscreencapture2__scenario"></a>

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

如果你调用了 [startScreenCapture [2/2]](/zh-CN/api-reference/rtc/unreal-cpp/video/screencapture#api_irtcengine_startscreencapture2) 开启一路或多路屏幕采集，则停止屏幕采集时需要调用该方法，并通过 sourceType 参数指定屏幕。

<a id="api_irtcengine_stopscreencapture2__timing"></a>

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

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

<a id="api_irtcengine_stopscreencapture2__restriction"></a>

### 调用限制 [#调用限制-6]

无。

<a id="api_irtcengine_stopscreencapture2__parameters"></a>

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

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

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

</Parameter>
</ParameterList>

<a id="api_irtcengine_stopscreencapture2__return_values"></a>

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

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

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

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

<a id="api_irtcengine_updatescreencapture"></a>

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

## updateScreenCapture [#updatescreencapture]

更新屏幕采集的参数配置。

<a id="api_irtcengine_updatescreencapture__prototype"></a>

```cpp
virtual int updateScreenCapture(const ScreenCaptureParameters2& captureParams) = 0;
```

<a id="api_irtcengine_updatescreencapture__detailed_desc"></a>

### 详情 [#详情-8]

如果在开启屏幕共享时未采集系统音频、然后想要更新参数配置、发布系统音频，可参考以下步骤：

1. 调用该方法并设置 captureAudio 为 `true`。
2. 调用 [updateChannelMediaOptions](/zh-CN/api-reference/rtc/unreal-cpp/channel#api_irtcengine_updatechannelmediaoptions) 设置 publishScreenCaptureAudio 为 `true`，即可发布屏幕采集的音频。

:::caution
注意：

- 该方法仅适用于 Android 和 iOS 平台。
- 在 iOS 平台上，屏幕共享仅适用于 iOS 12.0 及以上。
:::

<a id="api_irtcengine_updatescreencapture__parameters"></a>

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

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

屏幕共享的编码参数配置。详见 [ScreenCaptureParameters2](/zh-CN/api-reference/rtc/unreal-cpp/class-screencaptureparameters2)。

</Parameter>
</ParameterList>

<a id="api_irtcengine_updatescreencapture__return_values"></a>

### 返回值 [#返回值-14]

- 0: 方法调用成功。
- &lt; 0: 方法调用失败。

  - -2：传入的参数无效。
  - -8：屏幕共享状态无效。可能因为你已经共享了其他屏幕或窗口。尝试调用 [stopScreenCapture [1/2]](/zh-CN/api-reference/rtc/unreal-cpp/video/screencapture#api_irtcengine_stopscreencapture) 停止当前共享，再重新开始共享屏幕。

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

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

<a id="api_irtcengine_updatescreencaptureparameters"></a>

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

## updateScreenCaptureParameters [#updatescreencaptureparameters]

更新屏幕采集的参数配置。

<a id="api_irtcengine_updatescreencaptureparameters__prototype"></a>

```cpp
virtual int updateScreenCaptureParameters(const ScreenCaptureParameters& captureParams) = 0;
```

<a id="api_irtcengine_updatescreencaptureparameters__detailed_desc"></a>

### 详情 [#详情-9]

:::caution
注意：

- 该方法仅适用于 Windows 和 macOS 平台。
- 请在开启屏幕共享或窗口共享后调用该方法。
:::

<a id="api_irtcengine_updatescreencaptureparameters__parameters"></a>

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

<ParameterList>
<a id="captureparams-5"></a>
<Parameter name="captureParams">

屏幕共享的编码参数配置。详见 [ScreenCaptureParameters](/zh-CN/api-reference/rtc/unreal-cpp/class-screencaptureparameters)。

:::caution
注意： 屏幕共享流的视频属性只需通过该参数设置，与 [setVideoEncoderConfiguration](/zh-CN/api-reference/rtc/unreal-cpp/video/video-basic#api_irtcengine_setvideoencoderconfiguration) 无关。
:::

</Parameter>
</ParameterList>

<a id="api_irtcengine_updatescreencaptureparameters__return_values"></a>

### 返回值 [#返回值-15]

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

  - -2：传入的参数无效。
  - -8：屏幕共享状态无效。可能因为你已经共享了其他屏幕或窗口。尝试调用 [stopScreenCapture [1/2]](/zh-CN/api-reference/rtc/unreal-cpp/video/screencapture#api_irtcengine_stopscreencapture) 停止当前共享，再重新开始共享屏幕。

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

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

<a id="api_irtcengine_updatescreencaptureregion"></a>

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

## updateScreenCaptureRegion [#updatescreencaptureregion]

更新屏幕采集的区域。

<a id="api_irtcengine_updatescreencaptureregion__prototype"></a>

```cpp
virtual int updateScreenCaptureRegion(const Rectangle& regionRect) = 0;
```

<a id="api_irtcengine_updatescreencaptureregion__detailed_desc"></a>

### 详情 [#详情-10]

:::caution
注意： 请在开启屏幕共享或窗口共享后调用该方法。
:::

<a id="api_irtcengine_updatescreencaptureregion__parameters"></a>

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

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

待共享区域相对于整个屏幕或窗口的位置，如不填，则表示共享整个屏幕或窗口。详见 [Rectangle](/zh-CN/api-reference/rtc/unreal-cpp/class-rectangle)。如果设置的共享区域超出了屏幕或窗口的边界，则只共享屏幕或窗口内的内容；如果将 width 或 height 设为 0，则共享整个屏幕或窗口。

</Parameter>
</ParameterList>

<a id="api_irtcengine_updatescreencaptureregion__return_values"></a>

### 返回值 [#返回值-16]

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

  - -2：传入的参数无效。
  - -8：屏幕共享状态无效。可能因为你已经共享了其他屏幕或窗口。尝试调用 [stopScreenCapture [1/2]](/zh-CN/api-reference/rtc/unreal-cpp/video/screencapture#api_irtcengine_stopscreencapture) 停止当前共享，再重新开始共享屏幕。

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

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