屏幕采集

getScreenCaptureSourcesWithThumbSize

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

Objective-C

- (NSArray<AgoraScreenCaptureSourceInfo*>* _Nullable)getScreenCaptureSourcesWithThumbSize:(NSSize)thumbSize iconSize:(NSSize)iconSize includeScreen:(BOOL)includeScreen;

屏幕共享或窗口共享前，你可以调用该方法获取可共享的屏幕和窗口的对象列表，方便用户通过列表中的缩略图选择共享某个显示器的屏幕或某个窗口。列表中包含窗口 ID 和屏幕 ID 等重要信息，你可以获取到 ID 后再调用 startScreenCaptureByWindowId 或 startScreenCaptureByDisplayId 开启共享。

参数

参数名	描述
thumbSize	屏幕或窗口的缩略图的目标尺寸（宽高单位为像素）。 SDK 会在保证原图不变形的前提下，缩放原图，使图片最长边和目标尺寸的最长边的长度一致。例如，原图宽高为 400 × 300，thumbSize 为 100 x 100，缩略图实际尺寸为 100 × 75。如果目标尺寸大于原图尺寸，缩略图即为原图，SDK 不进行缩放操作。
iconSize	程序所对应的图标的目标尺寸（宽高单位为像素）。SDK 会在保证原图不变形的前提下，缩放原图，使图片最长边和目标尺寸的最长边的长度一致。例如，原图宽高为 400 × 300，iconSize 为 100 × 100，图标实际尺寸为 100 × 75。如果目标尺寸大于原图尺寸，图标即为原图，SDK 不进行缩放操作。
includeScreen	除了窗口信息外，SDK 是否返回屏幕信息： YES：SDK 返回屏幕和窗口信息。 NO：SDK 仅返回窗口信息。

返回值

AgoraScreenCaptureSourceInfo 数组。

所属接口类

• AgoraRtcEngineKit

setScreenCaptureScenario

设置屏幕共享的场景。

Objective-C

- (int)setScreenCaptureScenario:(AgoraScreenScenarioType)scenarioType
  NS_SWIFT_NAME(setScreenCaptureScenario(_:));

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

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

参数

参数名	描述
scenarioType	屏幕共享的场景，详见 AgoraScreenScenarioType。

返回值

• 0: 方法调用成功。

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

所属接口类

• AgoraRtcEngineKit

startScreenCaptureByDisplayId

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

Objective-C

- (int)startScreenCaptureByDisplayId:(UInt32)displayId
                regionRect:(CGRect)regionRect
                captureParams:(AgoraScreenCaptureParameters *_Nonnull)captureParams;

共享一个屏幕或该屏幕的部分区域。

开启屏幕共享有如下两种方案，你可以根据实际场景进行选择：

• 在加入频道前调用该方法，然后调用 joinChannelByToken [2/4] 加入频道并设置 publishScreenTrack 或 publishSecondaryScreenTrack 为 YES，即可开始屏幕共享。

• 在加入频道后调用该方法，然后调用 updateChannelWithMediaOptions 设置 publishScreenTrack 或 publishSecondaryScreenTrack 为 YES，即可开始屏幕共享。

参数

参数名	描述
displayId	指定待共享的屏幕 ID。
captureParams	屏幕共享的参数配置。默认的视频编码分辨率为 1920 × 1080，即 2073600 像素。该像素值为计费标准。详见 AgoraScreenCaptureParameters。

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。

  • -2：传入的参数无效。

  • -8：屏幕共享状态无效。可能因为你已经共享了其他屏幕或窗口。尝试调用 stopScreenCapture [1/2] 停止当前共享，再重新开始共享屏幕。

所属接口类

• AgoraRtcEngineKit

startScreenCaptureByWindowId

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

Objective-C

- (int)startScreenCaptureByWindowId:(UInt32)windowId
                regionRect:(CGRect)regionRect
                captureParams:(AgoraScreenCaptureParameters *_Nonnull)captureParams;

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

开启屏幕共享有如下两种方案，你可以根据实际场景进行选择：

• 在加入频道前调用该方法，然后调用 joinChannelByToken [2/4] 加入频道并设置 publishScreenTrack 或 publishSecondaryScreenTrack 为 YES，即可开始屏幕共享。

• 在加入频道后调用该方法，然后调用 updateChannelWithMediaOptions 设置 publishScreenTrack 或 publishSecondaryScreenTrack 为 YES，即可开始屏幕共享。

注意：

• SDK 的窗口共享功能依赖于 WGC（Windows Graphics Capture）或 GDI（Graphics Device Interface）采集，WGC 在早于 Windows 10 2004 的系统上无法设置关闭鼠标采集，因此，当你在搭载早于 Windows 10 2004 系统的设备上进行窗口共享时，可能出现 captureMouseCursor(false) 不生效的现象。详见 AgoraScreenCaptureParameters。

参数

参数名	描述
windowId	指定待共享的窗口 ID。
regionRect	（可选）待共享区域相对于整个窗口的位置。如不填，则表示共享整个窗口。由如下参数组成： x：左上角的横向偏移。 y：左上角的纵向偏移。 width：待共享区域的宽。 height：待共享区域的高。 如果设置的共享区域超出了窗口的边界，则只共享窗口内的内容；如果宽或高设为 0，则共享整个窗口。
captureParams	屏幕共享的参数配置。默认的分辨率为 1920 x 1080，即 2073600 像素。该像素值为计费标准。详见 AgoraScreenCaptureParameters。

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。

  • -2：传入的参数无效。

  • -8：屏幕共享状态无效。可能因为你已经共享了其他屏幕或窗口。尝试调用 stopScreenCapture [1/2] 停止当前共享，再重新开始共享屏幕。

所属接口类

• AgoraRtcEngineKit

stopScreenCapture [1/2]

停止屏幕采集。

Objective-C

- (int)stopScreenCapture NS_SWIFT_NAME(stopScreenCapture());

返回值

• 0: 方法调用成功。

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

所属接口类

• AgoraRtcEngineKit

updateScreenCaptureParameters

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

Objective-C

- (int)updateScreenCaptureParameters:(AgoraScreenCaptureParameters * _Nonnull)captureParams;

注意：

• 请在开启屏幕共享或窗口共享后调用该方法。

参数

参数名	描述
captureParams	屏幕共享的编码参数配置。默认的分辨率为 1920 x 1080，即 2073600 像素。该像素值为计费标准。详见 AgoraScreenCaptureParameters。

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。

  • -2：传入的参数无效。

  • -8：屏幕共享状态无效。可能因为你已经共享了其他屏幕或窗口。尝试调用 stopScreenCapture [1/2] 停止当前共享，再重新开始共享屏幕。

所属接口类

• AgoraRtcEngineKit

updateScreenCaptureRegion

更新屏幕采集的区域。

Objective-C

- (int)updateScreenCaptureRegion:(CGRect)rect;

参数

参数名	描述
rect	待共享区域相对于整个屏幕的位置，如不填，则表示共享整个屏幕。如果设置的共享区域超出了屏幕或窗口的边界，则只共享屏幕或窗口内的内容；如果将 width 或 height 设为 0 ，则共享整个屏幕或窗口。

返回值

• 0: 方法调用成功。

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