# 视频设备管理 (/zh-CN/api-reference/rtc/cpp-all-platforms/device-management/video-device)

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

<a id="toc_video_device"></a>

<a id="api_irtcengine_enablemulticamera"></a>

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

## enableMultiCamera [#enablemulticamera]

启用或关闭多摄像头采集功能。

<a id="api_irtcengine_enablemulticamera__prototype"></a>

```cpp
virtual int enableMultiCamera(bool enabled, const CameraCapturerConfiguration& config) = 0;
```

<a id="api_irtcengine_enablemulticamera__detailed_desc"></a>

声网建议你在已有摄像头用于视频采集的场景中，按照以下步骤使用多个摄像头进行视频采集和发布：

1. 调用该方法启用多摄像头采集。
2. 调用 `startPreview` 启动本地视频预览。
3. 调用 [startCameraCapture](/zh-CN/api-reference/rtc/cpp-all-platforms/video/camera-capture#api_irtcengine_startcameracapture)，并设置 `sourceType`，以使用第二个摄像头开始采集。
4. 调用 [joinChannelEx](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#api_irtcengineex_joinchannelex)，并将 `publishSecondaryCameraTrack` 设置为 true，以发布第二个摄像头采集的视频流。

若需关闭多摄像头采集，请按以下步骤操作：

1. 调用 [stopCameraCapture](/zh-CN/api-reference/rtc/cpp-all-platforms/video/camera-capture#api_irtcengine_stopcameracapture)。
2. 调用该方法并将 `enabled` 设置为 false。

该方法仅适用于 iOS 平台。使用该功能时，请确保系统版本为 13.0 或更高。支持多摄像头采集的最低 iOS 设备型号如下：

- iPhone XR。
- iPhone XS。
- iPhone XS Max。
- iPad Pro 第三代及更新机型。

:::note
注： 你可以在调用 `startPreview` 之前或之后调用该方法启用多摄像头采集：

- 如果在调用 `startPreview` 之前启用，则本地视频预览会同时显示两个摄像头采集的画面。
- 如果在调用 `startPreview` 之后启用，SDK 会先停止当前摄像头采集，然后启用主摄像头和第二个摄像头。本地视频预览会短暂变黑，随后自动恢复。
:::

<a id="api_irtcengine_enablemulticamera__parameters"></a>

### 参数 [#参数]

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

是否启用多摄像头视频采集模式：

- true：启用多摄像头采集模式，SDK 使用多个摄像头进行视频采集。
- false：关闭多摄像头采集模式，SDK 使用单个摄像头进行视频采集。

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

第二个摄像头的采集配置，详见 [CameraCapturerConfiguration](/zh-CN/api-reference/rtc/cpp-all-platforms/class-cameracapturerconfiguration)。

</Parameter>
</ParameterList>

<a id="api_irtcengine_enablemulticamera__return_values"></a>

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

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

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

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

<a id="api_ivideodevicemanager_enumeratevideodevices"></a>

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

## enumerateVideoDevices [#enumeratevideodevices]

枚举系统中的视频设备。

<a id="api_ivideodevicemanager_enumeratevideodevices__prototype"></a>

```cpp
virtual IVideoDeviceCollection* enumerateVideoDevices() = 0;
```

<a id="api_ivideodevicemanager_enumeratevideodevices__detailed_desc"></a>

该方法返回一个 [IVideoDeviceCollection](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_ivideodevicecollection) 对象，包含系统中所有可用的视频设备。你可以通过该对象枚举视频设备。使用完该对象后，必须调用 [release](/zh-CN/api-reference/rtc/cpp-all-platforms/device-management/video-device#api_ivideodevicemanager_release_ivideodevicemanager) 方法释放资源。

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

<a id="api_ivideodevicemanager_enumeratevideodevices__return_values"></a>

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

- 方法调用成功，返回 [IVideoDeviceCollection](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_ivideodevicecollection) 对象，详见 [IVideoDeviceCollection](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_ivideodevicecollection)。
- 方法调用失败，返回 NULL。

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

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

<a id="api_irtcengine_getcameramaxzoomfactor"></a>

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

## getCameraMaxZoomFactor [#getcameramaxzoomfactor]

获取摄像头支持的最大变焦倍数。

<a id="api_irtcengine_getcameramaxzoomfactor__prototype"></a>

```cpp
virtual float getCameraMaxZoomFactor() = 0;
```

<a id="api_irtcengine_getcameramaxzoomfactor__detailed_desc"></a>

:::note
注： 该方法仅适用于 Android 和 iOS 平台。必须在 SDK 触发 [onLocalVideoStateChanged](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 回调，并返回本地视频状态为 `LOCAL_VIDEO_STREAM_STATE_CAPTURING`（1）后调用该方法。
:::

<a id="api_irtcengine_getcameramaxzoomfactor__return_values"></a>

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

方法调用成功，返回摄像头支持的最大变焦倍数。

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

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

<a id="api_ivideodevicemanager_getcapability"></a>

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

## getCapability [#getcapability]

获取指定视频格式下的视频采集设备的帧信息。

<a id="api_ivideodevicemanager_getcapability__prototype"></a>

```cpp
virtual int getCapability(const char* deviceIdUTF8, const uint32_t deviceCapabilityNumber, VideoFormat& capability) = 0;
```

<a id="api_ivideodevicemanager_getcapability__detailed_desc"></a>

调用 [numberOfCapabilities](/zh-CN/api-reference/rtc/cpp-all-platforms/device-management/video-device#api_ivideodevicemanager_numberofcapabilities) 获取视频采集设备支持的视频格式数量后，可调用该方法获取指定索引对应的视频帧信息。

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

<a id="api_ivideodevicemanager_getcapability__parameters"></a>

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

<ParameterList>
<a id="deviceidutf8"></a>
<Parameter name="deviceIdUTF8">

视频采集设备的 ID。

</Parameter>
<a id="devicecapabilitynumber"></a>
<Parameter name="deviceCapabilityNumber">

视频格式的索引号。若 [numberOfCapabilities](/zh-CN/api-reference/rtc/cpp-all-platforms/device-management/video-device#api_ivideodevicemanager_numberofcapabilities) 的返回值为 i，则该参数的取值范围为 [0, i)。

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

输出参数，表示指定视频格式的详细信息，包括宽度（px）、高度（px）和帧率（fps）。详见 [VideoFormat](/zh-CN/api-reference/rtc/cpp-all-platforms/class-videoformat)。

</Parameter>
</ParameterList>

<a id="api_ivideodevicemanager_getcapability__return_values"></a>

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

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

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

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

<a id="api_ivideodevicecollection_getcount_ivideodevicecollection"></a>

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

## getCount [#getcount]

获取系统中已索引的视频采集设备总数。

<a id="api_ivideodevicecollection_getcount_ivideodevicecollection__prototype"></a>

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

<a id="api_ivideodevicecollection_getcount_ivideodevicecollection__detailed_desc"></a>

<a id="api_ivideodevicecollection_getcount_ivideodevicecollection__return_values"></a>

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

方法调用成功，返回系统中已索引的视频采集设备总数。

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

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

<a id="api_ivideodevicecollection_getdevice_ivideodevicecollection"></a>

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

## getDevice [#getdevice]

获取指定索引的视频设备的信息。

<a id="api_ivideodevicecollection_getdevice_ivideodevicecollection__prototype"></a>

```cpp
virtual int getDevice(int index, char deviceNameUTF8[MAX_DEVICE_ID_LENGTH], char deviceIdUTF8[MAX_DEVICE_ID_LENGTH]) = 0;
```

<a id="api_ivideodevicecollection_getdevice_ivideodevicecollection__detailed_desc"></a>

<a id="api_ivideodevicecollection_getdevice_ivideodevicecollection__parameters"></a>

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

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

视频设备的索引值。该值必须小于 [getCount](/zh-CN/api-reference/rtc/cpp-all-platforms/device-management/video-device#api_ivideodevicecollection_getcount_ivideodevicecollection) 返回的值。

</Parameter>
<a id="devicenameutf8"></a>
<Parameter name="deviceNameUTF8">

输出参数，表示设备名称。最大长度为 `MAX_DEVICE_ID_LENGTH`。

</Parameter>
<a id="deviceidutf8-1"></a>
<Parameter name="deviceIdUTF8">

输出参数，表示视频设备的设备 ID。最大长度为 `MAX_DEVICE_ID_LENGTH`。

</Parameter>
</ParameterList>

<a id="api_ivideodevicecollection_getdevice_ivideodevicecollection__return_values"></a>

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

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

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

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

<a id="api_ivideodevicemanager_getdevice_ivideodevicemanager"></a>

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

## getDevice [#getdevice-1]

获取当前的视频采集设备。

<a id="api_ivideodevicemanager_getdevice_ivideodevicemanager__prototype"></a>

```cpp
virtual int getDevice(char deviceIdUTF8[MAX_DEVICE_ID_LENGTH]) = 0;
```

<a id="api_ivideodevicemanager_getdevice_ivideodevicemanager__detailed_desc"></a>

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

<a id="api_ivideodevicemanager_getdevice_ivideodevicemanager__parameters"></a>

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

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

输出参数，当前视频采集设备的设备 ID。

</Parameter>
</ParameterList>

<a id="api_ivideodevicemanager_getdevice_ivideodevicemanager__return_values"></a>

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

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

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

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

<a id="api_irtcengine_iscameraautoexposurefacemodesupported"></a>

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

## isCameraAutoExposureFaceModeSupported [#iscameraautoexposurefacemodesupported]

检查设备是否支持自动曝光功能。

<a id="api_irtcengine_iscameraautoexposurefacemodesupported__prototype"></a>

```cpp
virtual bool isCameraAutoExposureFaceModeSupported() = 0;
```

<a id="api_irtcengine_iscameraautoexposurefacemodesupported__detailed_desc"></a>

:::note
注： [isCameraAutoExposureFaceModeSupported](/zh-CN/api-reference/rtc/cpp-all-platforms/device-management/video-device#api_irtcengine_iscameraautoexposurefacemodesupported) 仅适用于 iOS 平台。必须在 SDK 触发 [onLocalVideoStateChanged](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 回调并返回本地视频状态为 `LOCAL_VIDEO_STREAM_STATE_CAPTURING`（1）后调用。
:::

<a id="api_irtcengine_iscameraautoexposurefacemodesupported__return_values"></a>

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

true：设备支持自动曝光功能。
false：设备不支持自动曝光功能。

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

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

<a id="api_irtcengine_iscameraautofocusfacemodesupported"></a>

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

## isCameraAutoFocusFaceModeSupported [#iscameraautofocusfacemodesupported]

检查设备是否支持人脸自动对焦功能。

<a id="api_irtcengine_iscameraautofocusfacemodesupported__prototype"></a>

```cpp
virtual bool isCameraAutoFocusFaceModeSupported() = 0;
```

<a id="api_irtcengine_iscameraautofocusfacemodesupported__detailed_desc"></a>

:::note
注： [isCameraAutoFocusFaceModeSupported](/zh-CN/api-reference/rtc/cpp-all-platforms/device-management/video-device#api_irtcengine_iscameraautofocusfacemodesupported) 仅适用于 Android 和 iOS 平台。必须在 SDK 触发 [onLocalVideoStateChanged](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 回调，并返回本地视频状态为 `LOCAL_VIDEO_STREAM_STATE_CAPTURING`（1）后调用该方法。
:::

<a id="api_irtcengine_iscameraautofocusfacemodesupported__return_values"></a>

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

true：设备支持人脸自动对焦功能。
false：设备不支持人脸自动对焦功能。

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

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

<a id="api_irtcengine_iscameraexposurepositionsupported"></a>

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

## isCameraExposurePositionSupported [#iscameraexposurepositionsupported]

检查设备是否支持手动曝光。

<a id="api_irtcengine_iscameraexposurepositionsupported__prototype"></a>

```cpp
virtual bool isCameraExposurePositionSupported() = 0;
```

<a id="api_irtcengine_iscameraexposurepositionsupported__detailed_desc"></a>

:::info[自从]
自 v2.3.2 版本新增。
:::

:::note
注： [isCameraExposurePositionSupported](/zh-CN/api-reference/rtc/cpp-all-platforms/device-management/video-device#api_irtcengine_iscameraexposurepositionsupported) 方法仅适用于 Android 和 iOS 平台。你必须在 SDK 触发 [onLocalVideoStateChanged](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 回调，并返回本地视频状态为 `LOCAL_VIDEO_STREAM_STATE_CAPTURING`（1）后调用该方法。
:::

<a id="api_irtcengine_iscameraexposurepositionsupported__return_values"></a>

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

- true：设备支持手动曝光。
- false：设备不支持手动曝光。

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

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

<a id="api_irtcengine_iscameraexposuresupported"></a>

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

## isCameraExposureSupported [#iscameraexposuresupported]

查询当前摄像头是否支持调节曝光值。

<a id="api_irtcengine_iscameraexposuresupported__prototype"></a>

```cpp
virtual bool isCameraExposureSupported() = 0;
```

<a id="api_irtcengine_iscameraexposuresupported__detailed_desc"></a>

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

:::note
注：

- 该方法仅适用于 Android 和 iOS 平台。
- 必须在 SDK 触发 [onLocalVideoStateChanged](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 回调并返回本地视频状态为 `LOCAL_VIDEO_STREAM_STATE_CAPTURING`（1）后调用。
- 在调用 [setCameraExposureFactor](/zh-CN/api-reference/rtc/cpp-all-platforms/device-management/video-device#api_irtcengine_setcameraexposurefactor) 之前，建议你先调用该方法查询当前摄像头是否支持调节曝光值。
- 该方法用于调节当前激活摄像头的曝光值，即调用 [setCameraCapturerConfiguration](/zh-CN/api-reference/rtc/cpp-all-platforms/device-management/video-device#api_irtcengine_setcameracapturerconfiguration) 时指定的摄像头。
:::

<a id="api_irtcengine_iscameraexposuresupported__return_values"></a>

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

- true：查询成功。
- false：查询失败。

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

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

<a id="api_irtcengine_iscamerafacedetectsupported"></a>

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

## isCameraFaceDetectSupported [#iscamerafacedetectsupported]

检查设备摄像头是否支持人脸检测。

<a id="api_irtcengine_iscamerafacedetectsupported__prototype"></a>

```cpp
virtual bool isCameraFaceDetectSupported() = 0;
```

<a id="api_irtcengine_iscamerafacedetectsupported__detailed_desc"></a>

:::note
注： [isCameraFaceDetectSupported](/zh-CN/api-reference/rtc/cpp-all-platforms/device-management/video-device#api_irtcengine_iscamerafacedetectsupported) 仅适用于 Android 和 iOS 平台。必须在 SDK 触发 [onLocalVideoStateChanged](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 回调，并返回本地视频状态为 `LOCAL_VIDEO_STREAM_STATE_CAPTURING`（1）后调用该方法。
:::

<a id="api_irtcengine_iscamerafacedetectsupported__return_values"></a>

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

true：设备摄像头支持人脸检测。
false：设备摄像头不支持人脸检测。

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

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

<a id="api_irtcengine_iscamerafocussupported"></a>

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

## isCameraFocusSupported [#iscamerafocussupported]

检查设备是否支持手动对焦功能。

<a id="api_irtcengine_iscamerafocussupported__prototype"></a>

```cpp
virtual bool isCameraFocusSupported() = 0;
```

<a id="api_irtcengine_iscamerafocussupported__detailed_desc"></a>

:::note
注： [isCameraFocusSupported](/zh-CN/api-reference/rtc/cpp-all-platforms/device-management/video-device#api_irtcengine_iscamerafocussupported) 仅适用于 Android 和 iOS 平台。你必须在 SDK 触发 [onLocalVideoStateChanged](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 回调并返回本地视频状态为 `LOCAL_VIDEO_STREAM_STATE_CAPTURING`（1）后调用该方法。
:::

<a id="api_irtcengine_iscamerafocussupported__return_values"></a>

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

- true：设备支持手动对焦功能。
- false：设备不支持手动对焦功能。

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

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

<a id="api_irtcengine_iscameratorchsupported"></a>

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

## isCameraTorchSupported [#iscameratorchsupported]

检查设备是否支持摄像头闪光灯。

<a id="api_irtcengine_iscameratorchsupported__prototype"></a>

```cpp
virtual bool isCameraTorchSupported() = 0;
```

<a id="api_irtcengine_iscameratorchsupported__detailed_desc"></a>

:::note
注： [isCameraTorchSupported](/zh-CN/api-reference/rtc/cpp-all-platforms/device-management/video-device#api_irtcengine_iscameratorchsupported) 仅适用于 Android 和 iOS 平台。必须在 SDK 触发 [onLocalVideoStateChanged](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 回调并返回本地视频状态为 `LOCAL_VIDEO_STREAM_STATE_CAPTURING`（1）后调用该方法。App 默认启用前置摄像头。如果前置摄像头不支持闪光灯，该方法返回 false。如果你想检查后置摄像头是否支持闪光灯功能，请在调用该方法前调用 [switchCamera](/zh-CN/api-reference/rtc/cpp-all-platforms/device-management/video-device#api_irtcengine_switchcamera)。iOS 15 系统版本的 iPad 上，即使 [isCameraTorchSupported](/zh-CN/api-reference/rtc/cpp-all-platforms/device-management/video-device#api_irtcengine_iscameratorchsupported) 返回 true，由于系统问题，调用 [setCameraTorchOn](/zh-CN/api-reference/rtc/cpp-all-platforms/device-management/video-device#api_irtcengine_setcameratorchon) 可能无法成功打开闪光灯。
:::

<a id="api_irtcengine_iscameratorchsupported__return_values"></a>

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

- true：设备支持摄像头闪光灯。
- false：设备不支持摄像头闪光灯。

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

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

<a id="api_irtcengine_iscamerazoomsupported"></a>

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

## isCameraZoomSupported [#iscamerazoomsupported]

检查设备是否支持摄像头变焦。

<a id="api_irtcengine_iscamerazoomsupported__prototype"></a>

```cpp
virtual bool isCameraZoomSupported() = 0;
```

<a id="api_irtcengine_iscamerazoomsupported__detailed_desc"></a>

:::note
注： [isCameraZoomSupported](/zh-CN/api-reference/rtc/cpp-all-platforms/device-management/video-device#api_irtcengine_iscamerazoomsupported) 方法仅适用于 Android 和 iOS 平台。
:::

<a id="api_irtcengine_iscamerazoomsupported__timing"></a>

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

必须在 SDK 触发 [onLocalVideoStateChanged](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 回调并返回本地视频状态为 `LOCAL_VIDEO_STREAM_STATE_CAPTURING`（1）后调用该方法。

<a id="api_irtcengine_iscamerazoomsupported__return_values"></a>

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

true：设备支持摄像头变焦。
false：设备不支持摄像头变焦。

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

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

<a id="api_ivideodevicemanager_numberofcapabilities"></a>

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

## numberOfCapabilities [#numberofcapabilities]

获取指定视频采集设备支持的视频格式数量。

<a id="api_ivideodevicemanager_numberofcapabilities__prototype"></a>

```cpp
virtual int numberOfCapabilities(const char* deviceIdUTF8) = 0;
```

<a id="api_ivideodevicemanager_numberofcapabilities__detailed_desc"></a>

你可以调用该方法获取指定视频采集设备支持的视频格式数量，然后调用 [getCapability](/zh-CN/api-reference/rtc/cpp-all-platforms/device-management/video-device#api_ivideodevicemanager_getcapability) 获取对应的视频帧信息。视频采集设备可能支持多种视频格式，每种格式包含不同的视频帧宽度、高度和帧率组合。

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

<a id="api_ivideodevicemanager_numberofcapabilities__parameters"></a>

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

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

视频采集设备的 ID。

</Parameter>
</ParameterList>

<a id="api_ivideodevicemanager_numberofcapabilities__return_values"></a>

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

- &gt; 0：方法调用成功，返回该设备支持的视频格式数量。例如，如果指定摄像头支持 10 种不同的视频格式，返回值为 10。
- ≤ 0：方法调用失败。

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

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

<a id="api_irtcengine_querycamerafocallengthcapability"></a>

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

## queryCameraFocalLengthCapability [#querycamerafocallengthcapability]

查询摄像头支持的焦距能力。

<a id="api_irtcengine_querycamerafocallengthcapability__prototype"></a>

```cpp
virtual int queryCameraFocalLengthCapability(agora::rtc::FocalLengthInfo* focalLengthInfos, int& size) = 0;
```

<a id="api_irtcengine_querycamerafocallengthcapability__detailed_desc"></a>

如果你希望在视频采集中启用广角或超广角模式，建议先调用该方法检查设备是否支持所需的焦距能力。然后根据查询结果调用 [setCameraCapturerConfiguration](/zh-CN/api-reference/rtc/cpp-all-platforms/device-management/video-device#api_irtcengine_setcameracapturerconfiguration) 方法调整摄像头的焦距配置，以获得最佳的视频采集效果。

:::note
注： 该方法仅适用于 Android 和 iOS 平台。
:::

<a id="api_irtcengine_querycamerafocallengthcapability__parameters"></a>

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

<ParameterList>
<a id="focallengthinfos"></a>
<Parameter name="focalLengthInfos">

输入和输出参数，表示 [FocalLengthInfo](/zh-CN/api-reference/rtc/cpp-all-platforms/class-focallengthinfo) 对象数组的指针。方法执行后，填充查询到的焦距信息。详见 [FocalLengthInfo](/zh-CN/api-reference/rtc/cpp-all-platforms/class-focallengthinfo)。

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

输入和输出参数，表示焦距信息项的数量。输入时指定 `focalLengthInfos` 可容纳的最大焦距信息项数量，该值应不小于 8。输出时返回实际获取的焦距信息项数量。

</Parameter>
</ParameterList>

<a id="api_irtcengine_querycamerafocallengthcapability__return_values"></a>

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

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

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

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

<a id="api_irtcengine_querycodeccapability"></a>

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

## queryCodecCapability [#querycodeccapability]

查询 SDK 支持的视频编解码器能力。

<a id="api_irtcengine_querycodeccapability__prototype"></a>

```cpp
virtual int queryCodecCapability(CodecCapInfo* codecInfo, int& size) = 0;
```

<a id="api_irtcengine_querycodeccapability__detailed_desc"></a>

<a id="api_irtcengine_querycodeccapability__parameters"></a>

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

<ParameterList>
<a id="codecinfo"></a>
<Parameter name="codecInfo">

输入和输出参数，表示 SDK 支持的视频编解码器能力数组。你在调用该方法时传入一个 [CodecCapInfo](/zh-CN/api-reference/rtc/cpp-all-platforms/class-codeccapinfo) 数组，表示要查询的视频编解码器能力。方法执行完毕后，该数组将被填充为 SDK 实际支持的视频编解码器能力。详见 [CodecCapInfo](/zh-CN/api-reference/rtc/cpp-all-platforms/class-codeccapinfo)。

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

输入和输出参数，表示 `codecInfo` 数组的大小。你在调用该方法时传入 `codecInfo` 的大小。方法执行完毕后，该值将被更新为实际返回的 `codecInfo` 数组大小。

</Parameter>
</ParameterList>

<a id="api_irtcengine_querycodeccapability__return_values"></a>

### 返回值 [#返回值-17]

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

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

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

<a id="api_ivideodevicecollection_release_ivideodevicecollection"></a>

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

## release [#release]

释放 [IVideoDeviceCollection](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_ivideodevicecollection) 对象占用的所有资源。

<a id="api_ivideodevicecollection_release_ivideodevicecollection__prototype"></a>

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

<a id="api_ivideodevicecollection_release_ivideodevicecollection__detailed_desc"></a>

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

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

<a id="api_ivideodevicemanager_release_ivideodevicemanager"></a>

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

## release [#release-1]

释放 [IVideoDeviceManager](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_ivideodevicemanager) 对象占用的所有资源。

<a id="api_ivideodevicemanager_release_ivideodevicemanager__prototype"></a>

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

<a id="api_ivideodevicemanager_release_ivideodevicemanager__detailed_desc"></a>

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

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

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

<a id="api_irtcengine_setcameraautoexposurefacemodeenabled"></a>

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

## setCameraAutoExposureFaceModeEnabled [#setcameraautoexposurefacemodeenabled]

设置是否启用自动曝光功能。

<a id="api_irtcengine_setcameraautoexposurefacemodeenabled__prototype"></a>

```cpp
virtual int setCameraAutoExposureFaceModeEnabled(bool enabled) = 0;
```

<a id="api_irtcengine_setcameraautoexposurefacemodeenabled__detailed_desc"></a>

:::note
注： 该方法仅适用于 iOS 平台。你必须在调用 [enableVideo](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#api_irtcengine_enablevideo) 方法之后再调用本方法。设置将在成功开启摄像头后生效，即 SDK 触发 [onLocalVideoStateChanged](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 回调并返回本地视频状态为 `LOCAL_VIDEO_STREAM_STATE_CAPTURING`（1）后。
:::

<a id="api_irtcengine_setcameraautoexposurefacemodeenabled__parameters"></a>

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

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

是否启用自动曝光：

- true：启用自动曝光。
- false：关闭自动曝光。

</Parameter>
</ParameterList>

<a id="api_irtcengine_setcameraautoexposurefacemodeenabled__return_values"></a>

### 返回值 [#返回值-18]

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

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

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

<a id="api_irtcengine_setcameraautofocusfacemodeenabled"></a>

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

## setCameraAutoFocusFaceModeEnabled [#setcameraautofocusfacemodeenabled]

启用摄像头人脸自动对焦功能。

<a id="api_irtcengine_setcameraautofocusfacemodeenabled__prototype"></a>

```cpp
virtual int setCameraAutoFocusFaceModeEnabled(bool enabled) = 0;
```

<a id="api_irtcengine_setcameraautofocusfacemodeenabled__detailed_desc"></a>

默认情况下，SDK 在 Android 上禁用人脸自动对焦，在 iOS 上启用。你可以调用该方法设置是否启用人脸自动对焦功能。

:::note
注： 此方法仅适用于 Android 和 iOS 平台。
:::

<a id="api_irtcengine_setcameraautofocusfacemodeenabled__timing"></a>

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

必须在 SDK 触发 [onLocalVideoStateChanged](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 回调并返回本地视频状态为 `LOCAL_VIDEO_STREAM_STATE_CAPTURING`（1）后调用。

<a id="api_irtcengine_setcameraautofocusfacemodeenabled__parameters"></a>

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

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

是否启用人脸自动对焦功能：

- true：启用摄像头人脸自动对焦功能。
- false：关闭人脸自动对焦功能。

</Parameter>
</ParameterList>

<a id="api_irtcengine_setcameraautofocusfacemodeenabled__return_values"></a>

### 返回值 [#返回值-19]

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

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

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

<a id="api_irtcengine_setcameracapturerconfiguration"></a>

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

## setCameraCapturerConfiguration [#setcameracapturerconfiguration]

设置摄像头采集配置。

<a id="api_irtcengine_setcameracapturerconfiguration__prototype"></a>

```cpp
virtual int setCameraCapturerConfiguration(const CameraCapturerConfiguration& config) = 0;
```

<a id="api_irtcengine_setcameracapturerconfiguration__detailed_desc"></a>

在启用本地摄像头采集之前调用该方法，例如调用 `startPreview` 或 `joinChannel` 之前。

:::note
注： 如需调整摄像头焦距配置，建议先调用 [queryCameraFocalLengthCapability](/zh-CN/api-reference/rtc/cpp-all-platforms/device-management/video-device#api_irtcengine_querycamerafocallengthcapability) 查询设备的焦距能力，并根据查询结果进行配置。由于部分 Android 设备的限制，即使根据 [queryCameraFocalLengthCapability](/zh-CN/api-reference/rtc/cpp-all-platforms/device-management/video-device#api_irtcengine_querycamerafocallengthcapability) 返回的结果设置了焦距类型，设置也可能不会生效。
:::

<a id="api_irtcengine_setcameracapturerconfiguration__timing"></a>

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

在启用本地摄像头采集之前调用，例如调用 `startPreview` 或 `joinChannel` 之前。

<a id="api_irtcengine_setcameracapturerconfiguration__parameters"></a>

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

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

摄像头采集配置。详见 [CameraCapturerConfiguration](/zh-CN/api-reference/rtc/cpp-all-platforms/class-cameracapturerconfiguration)。

:::note
注： 在该方法中，无需设置 `deviceId` 参数。
:::

</Parameter>
</ParameterList>

<a id="api_irtcengine_setcameracapturerconfiguration__return_values"></a>

### 返回值 [#返回值-20]

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

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

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

<a id="api_irtcengine_setcameradeviceorientation"></a>

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

## setCameraDeviceOrientation [#setcameradeviceorientation]

设置采集视频的旋转角度。

<a id="api_irtcengine_setcameradeviceorientation__prototype"></a>

```cpp
virtual int setCameraDeviceOrientation(VIDEO_SOURCE_TYPE type, VIDEO_ORIENTATION orientation) = 0;
```

<a id="api_irtcengine_setcameradeviceorientation__detailed_desc"></a>

:::note
注： 该方法仅适用于 Windows 平台。你必须在调用 [enableVideo](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#api_irtcengine_enablevideo) 之后再调用该方法。设置将在摄像头成功开启后生效，即 SDK 触发 [onLocalVideoStateChanged](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 回调并返回本地视频状态为 `LOCAL_VIDEO_STREAM_STATE_CAPTURING`（1）后生效。当视频采集设备不具备重力感应功能时，你可以调用该方法手动调整采集视频的旋转角度。
:::

<a id="api_irtcengine_setcameradeviceorientation__parameters"></a>

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

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

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

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

顺时针旋转角度，详见 [VIDEO_ORIENTATION](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-videoorientation)。

</Parameter>
</ParameterList>

<a id="api_irtcengine_setcameradeviceorientation__return_values"></a>

### 返回值 [#返回值-21]

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

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

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

<a id="api_irtcengine_setcameraexposurefactor"></a>

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

## setCameraExposureFactor [#setcameraexposurefactor]

设置摄像头曝光值。

<a id="api_irtcengine_setcameraexposurefactor__prototype"></a>

```cpp
virtual int setCameraExposureFactor(float factor) = 0;
```

<a id="api_irtcengine_setcameraexposurefactor__detailed_desc"></a>

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

:::note
注：

- 该方法仅适用于 Android 和 iOS 平台。
- 你必须在调用 [enableVideo](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#api_irtcengine_enablevideo) 后再调用该方法。设置结果在摄像头成功开启后生效，即 SDK 触发 [onLocalVideoStateChanged](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 回调并返回本地视频状态为 `LOCAL_VIDEO_STREAM_STATE_CAPTURING`（1）后。
- 在调用该方法前，声网建议调用 [isCameraExposureSupported](/zh-CN/api-reference/rtc/cpp-all-platforms/device-management/video-device#api_irtcengine_iscameraexposuresupported) 检查当前摄像头是否支持调整曝光值。
- 该方法用于调整当前激活摄像头的曝光值，即调用 [setCameraCapturerConfiguration](/zh-CN/api-reference/rtc/cpp-all-platforms/device-management/video-device#api_irtcengine_setcameracapturerconfiguration) 时指定的摄像头。
:::

<a id="api_irtcengine_setcameraexposurefactor__parameters"></a>

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

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

摄像头曝光值。默认值为 0，表示使用摄像头的默认曝光值。值越大，曝光越强。当视频图像过曝时，可以降低曝光值；当视频图像曝光不足且暗部细节丢失时，可以提高曝光值。如果设置的曝光值超出设备支持的范围，SDK 会自动将其调整为设备实际支持的范围。

:::note
注：

- 在 Android 上，取值范围为 [-20.0, 20.0]。
- 在 iOS 上，取值范围为 [-8.0, 8.0]。
:::

</Parameter>
</ParameterList>

<a id="api_irtcengine_setcameraexposurefactor__return_values"></a>

### 返回值 [#返回值-22]

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

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

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

<a id="api_irtcengine_setcameraexposureposition"></a>

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

## setCameraExposurePosition [#setcameraexposureposition]

设置相机曝光位置。

<a id="api_irtcengine_setcameraexposureposition__prototype"></a>

```cpp
virtual int setCameraExposurePosition(float positionXinView, float positionYinView) = 0;
```

<a id="api_irtcengine_setcameraexposureposition__detailed_desc"></a>

:::info[自从]
自 v2.3.2 版本新增。
:::

:::note
注：

- [setCameraExposurePosition](/zh-CN/api-reference/rtc/cpp-all-platforms/device-management/video-device#api_irtcengine_setcameraexposureposition) 仅适用于 Android 和 iOS 平台。
- 你必须在调用 [enableVideo](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#api_irtcengine_enablevideo) 方法之后再调用该方法。
- 设置将在相机成功开启后生效，即 SDK 触发 [onLocalVideoStateChanged](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 回调并返回本地视频状态为 `LOCAL_VIDEO_STREAM_STATE_CAPTURING`（1）时生效。
:::

<a id="api_irtcengine_setcameraexposureposition__related"></a>

### 相关回调 [#相关回调]

成功调用该方法后，SDK 会触发 [onCameraExposureAreaChanged](/zh-CN/api-reference/rtc/cpp-all-platforms/device-management/video-device#callback_irtcengineeventhandler_oncameraexposureareachanged) 回调。

<a id="api_irtcengine_setcameraexposureposition__parameters"></a>

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

<ParameterList>
<a id="positionxinview"></a>
<Parameter name="positionXinView">

视图中触摸点的水平坐标。

</Parameter>
<a id="positionyinview"></a>
<Parameter name="positionYinView">

视图中触摸点的垂直坐标。

</Parameter>
</ParameterList>

<a id="api_irtcengine_setcameraexposureposition__return_values"></a>

### 返回值 [#返回值-23]

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

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

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

<a id="api_irtcengine_setcamerafocuspositioninpreview"></a>

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

## setCameraFocusPositionInPreview [#setcamerafocuspositioninpreview]

设置摄像头手动对焦位置。

<a id="api_irtcengine_setcamerafocuspositioninpreview__prototype"></a>

```cpp
virtual int setCameraFocusPositionInPreview(float positionX, float positionY) = 0;
```

<a id="api_irtcengine_setcamerafocuspositioninpreview__detailed_desc"></a>

你必须在调用 [enableVideo](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#api_irtcengine_enablevideo) 之后再调用该方法。设置将在摄像头成功开启后生效，即 SDK 触发 [onLocalVideoStateChanged](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 回调并返回本地视频状态为 `LOCAL_VIDEO_STREAM_STATE_CAPTURING`（1）时。方法调用成功后，SDK 会触发 [onCameraFocusAreaChanged](/zh-CN/api-reference/rtc/cpp-all-platforms/device-management/video-device#callback_irtcengineeventhandler_oncamerafocusareachanged) 回调。

:::note
注： 该方法仅适用于 Android 和 iOS 平台。
:::

<a id="api_irtcengine_setcamerafocuspositioninpreview__related"></a>

### 相关回调 [#相关回调-1]

成功调用该方法后，SDK 会触发 [onCameraFocusAreaChanged](/zh-CN/api-reference/rtc/cpp-all-platforms/device-management/video-device#callback_irtcengineeventhandler_oncamerafocusareachanged) 回调。

<a id="api_irtcengine_setcamerafocuspositioninpreview__parameters"></a>

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

<ParameterList>
<a id="positionx"></a>
<Parameter name="positionX">

视图中触摸点的水平坐标。

</Parameter>
<a id="positiony"></a>
<Parameter name="positionY">

视图中触摸点的垂直坐标。

</Parameter>
</ParameterList>

<a id="api_irtcengine_setcamerafocuspositioninpreview__return_values"></a>

### 返回值 [#返回值-24]

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

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

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

<a id="api_irtcengine_setcameratorchon"></a>

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

## setCameraTorchOn [#setcameratorchon]

打开或关闭摄像头闪光灯。

<a id="api_irtcengine_setcameratorchon__prototype"></a>

```cpp
virtual int setCameraTorchOn(bool isOn) = 0;
```

<a id="api_irtcengine_setcameratorchon__detailed_desc"></a>

:::note
注： [setCameraTorchOn](/zh-CN/api-reference/rtc/cpp-all-platforms/device-management/video-device#api_irtcengine_setcameratorchon) 仅适用于 Android 和 iOS 平台。你必须在调用 [enableVideo](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#api_irtcengine_enablevideo) 之后再调用该方法。设置结果会在摄像头成功开启后生效，即 SDK 触发 [onLocalVideoStateChanged](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 回调并返回本地视频状态为 `LOCAL_VIDEO_STREAM_STATE_CAPTURING`（1）之后。
:::

<a id="api_irtcengine_setcameratorchon__parameters"></a>

### 参数 [#参数-14]

<ParameterList>
<a id="ison"></a>
<Parameter name="isOn">

是否打开摄像头闪光灯：

- true：打开闪光灯。
- false：（默认）关闭闪光灯。

</Parameter>
</ParameterList>

<a id="api_irtcengine_setcameratorchon__return_values"></a>

### 返回值 [#返回值-25]

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

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

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

<a id="api_irtcengine_setcamerazoomfactor"></a>

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

## setCameraZoomFactor [#setcamerazoomfactor]

设置摄像头变焦倍数。

<a id="api_irtcengine_setcamerazoomfactor__prototype"></a>

```cpp
virtual int setCameraZoomFactor(float factor) = 0;
```

<a id="api_irtcengine_setcamerazoomfactor__detailed_desc"></a>

对于配备多镜头后置摄像头的 iOS 设备，例如双摄（广角和超广角）或三摄（广角、超广角和长焦）设备，你可以先调用 [setCameraCapturerConfiguration](/zh-CN/api-reference/rtc/cpp-all-platforms/device-management/video-device#api_irtcengine_setcameracapturerconfiguration) 方法，将 `cameraFocalLengthType` 设置为 `CAMERA_FOCAL_LENGTH_DEFAULT`（0）（标准镜头），然后将变焦倍数设置为小于 1.0 的值，以实现超广角视角的视频采集。

:::note
注：

- 该方法仅适用于 Android 和 iOS 平台。
- 你必须在调用 [enableVideo](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#api_irtcengine_enablevideo) 方法之后再调用该方法。设置将在摄像头成功开启后生效，即 SDK 触发 [onLocalVideoStateChanged](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 回调并返回本地视频状态为 `LOCAL_VIDEO_STREAM_STATE_CAPTURING`（1）之后。
:::

<a id="api_irtcengine_setcamerazoomfactor__parameters"></a>

### 参数 [#参数-15]

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

摄像头变焦倍数。你可以调用 [getCameraMaxZoomFactor](/zh-CN/api-reference/rtc/cpp-all-platforms/device-management/video-device#api_irtcengine_getcameramaxzoomfactor) 方法获取设备支持的最大变焦倍数。

:::note
注： 对于不支持超广角的设备，该值范围为 1.0 到设备支持的最大变焦倍数；对于支持超广角的设备，该值范围为 0.5 到设备支持的最大变焦倍数。
:::

</Parameter>
</ParameterList>

<a id="api_irtcengine_setcamerazoomfactor__return_values"></a>

### 返回值 [#返回值-26]

- 0：方法调用成功，返回设置的摄像头变焦倍数。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

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

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

<a id="api_ivideodevicecollection_setdevice"></a>

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

## setDevice [#setdevice]

指定设备 ID 对应的设备。

<a id="api_ivideodevicecollection_setdevice__prototype"></a>

```cpp
virtual int setDevice(const char deviceIdUTF8[MAX_DEVICE_ID_LENGTH]) = 0;
```

<a id="api_ivideodevicecollection_setdevice__detailed_desc"></a>

<a id="api_ivideodevicecollection_setdevice__parameters"></a>

### 参数 [#参数-16]

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

设备 ID。插拔音频设备不会改变该值。

</Parameter>
</ParameterList>

<a id="api_ivideodevicecollection_setdevice__return_values"></a>

### 返回值 [#返回值-27]

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

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

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

<a id="api_ivideodevicemanager_setdevice_ivideodevicemanager"></a>

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

## setDevice [#setdevice-1]

指定视频采集设备的设备 ID。

<a id="api_ivideodevicemanager_setdevice_ivideodevicemanager__prototype"></a>

```cpp
virtual int setDevice(const char deviceIdUTF8[MAX_DEVICE_ID_LENGTH]) = 0;
```

<a id="api_ivideodevicemanager_setdevice_ivideodevicemanager__detailed_desc"></a>

<a id="api_ivideodevicemanager_setdevice_ivideodevicemanager__parameters"></a>

### 参数 [#参数-17]

<ParameterList>
<a id="deviceidutf8-5"></a>
<Parameter name="deviceIdUTF8">

`设备 ID`。你可以通过调用 [enumerateVideoDevices](/zh-CN/api-reference/rtc/cpp-all-platforms/device-management/video-device#api_ivideodevicemanager_enumeratevideodevices) 获取该值。最大长度为 `MAX_DEVICE_ID_LENGTH`。

</Parameter>
</ParameterList>

<a id="api_ivideodevicemanager_setdevice_ivideodevicemanager__return_values"></a>

### 返回值 [#返回值-28]

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

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

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

<a id="api_irtcengine_switchcamera"></a>

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

## switchCamera [#switchcamera]

切换前后摄像头。

<a id="api_irtcengine_switchcamera__prototype"></a>

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

<a id="api_irtcengine_switchcamera__detailed_desc"></a>

你可以调用此方法在应用运行过程中根据实际可用的摄像头动态切换前后摄像头，无需重启视频流或重新配置视频源。

:::note
注：

- 此方法仅切换由第一个摄像头采集的视频流的摄像头，即调用 [startCameraCapture](/zh-CN/api-reference/rtc/cpp-all-platforms/video/camera-capture#api_irtcengine_startcameracapture) 时视频源设置为 `VIDEO_SOURCE_CAMERA`（0）的视频流。
- 此方法仅适用于 Android 和 iOS 平台。
:::

<a id="api_irtcengine_switchcamera__timing"></a>

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

必须在摄像头成功启用后调用，即 SDK 触发 [onLocalVideoStateChanged](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 回调并返回本地视频状态为 `LOCAL_VIDEO_STREAM_STATE_CAPTURING`（1）之后。

<a id="api_irtcengine_switchcamera__return_values"></a>

### 返回值 [#返回值-29]

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

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

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

<a id="callback_irtcengineeventhandler_oncameraexposureareachanged"></a>

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

## onCameraExposureAreaChanged [#oncameraexposureareachanged]

摄像头曝光区域发生变化回调。

<a id="callback_irtcengineeventhandler_oncameraexposureareachanged__prototype"></a>

```cpp
virtual void onCameraExposureAreaChanged(int x, int y, int width, int height)
```

<a id="callback_irtcengineeventhandler_oncameraexposureareachanged__detailed_desc"></a>

当本地用户调用 [setCameraExposurePosition](/zh-CN/api-reference/rtc/cpp-all-platforms/device-management/video-device#api_irtcengine_setcameraexposureposition) 更改摄像头曝光位置时，SDK 会触发该回调。

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

<a id="callback_irtcengineeventhandler_oncameraexposureareachanged__parameters"></a>

### 参数 [#参数-18]

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

更改后曝光区域的 x 坐标。

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

更改后曝光区域的 y 坐标。

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

更改后曝光区域的宽度。

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

更改后曝光区域的高度。

</Parameter>
</ParameterList>

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

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

<a id="callback_irtcengineeventhandler_oncamerafocusareachanged"></a>

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

## onCameraFocusAreaChanged [#oncamerafocusareachanged]

[onCameraFocusAreaChanged](/zh-CN/api-reference/rtc/cpp-all-platforms/device-management/video-device#callback_irtcengineeventhandler_oncamerafocusareachanged) 回调。当摄像头对焦区域发生变化时触发。

<a id="callback_irtcengineeventhandler_oncamerafocusareachanged__prototype"></a>

```cpp
virtual void onCameraFocusAreaChanged(int x, int y, int width, int height)
```

<a id="callback_irtcengineeventhandler_oncamerafocusareachanged__detailed_desc"></a>

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

<a id="callback_irtcengineeventhandler_oncamerafocusareachanged__parameters"></a>

### 参数 [#参数-19]

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

对焦区域变化后的 x 坐标。

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

对焦区域变化后的 y 坐标。

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

对焦区域变化后的宽度。

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

对焦区域变化后的高度。

</Parameter>
</ParameterList>

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

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

<a id="callback_irtcengineeventhandler_oncameraready"></a>

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

## onCameraReady [#oncameraready]

[onCameraReady](/zh-CN/api-reference/rtc/cpp-all-platforms/device-management/video-device#callback_irtcengineeventhandler_oncameraready) 回调：当摄像头打开并准备好采集视频时触发。

<a id="callback_irtcengineeventhandler_oncameraready__prototype"></a>

```cpp
virtual void onCameraReady() __deprecated {}
```

<a id="callback_irtcengineeventhandler_oncameraready__detailed_desc"></a>

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

:::error[废弃]
该方法已废弃，请改用 [onLocalVideoStateChanged](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 中的 `LOCAL_VIDEO_STREAM_STATE_CAPTURING`。
:::

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

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

<a id="callback_irtcengineeventhandler_onvideodevicestatechanged"></a>

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

## onVideoDeviceStateChanged [#onvideodevicestatechanged]

视频设备状态变化回调。

<a id="callback_irtcengineeventhandler_onvideodevicestatechanged__prototype"></a>

```cpp
virtual void onVideoDeviceStateChanged(const char* deviceId, int deviceType, int deviceState)
```

<a id="callback_irtcengineeventhandler_onvideodevicestatechanged__detailed_desc"></a>

该回调用于报告系统视频设备的状态变化，例如设备被拔出或移除。在 Windows 设备上，如果使用外接摄像头进行视频采集，当外接摄像头被拔出时，视频功能将被禁用。

:::note
注： 该回调仅适用于 Windows 和 macOS 平台。
:::

<a id="callback_irtcengineeventhandler_onvideodevicestatechanged__parameters"></a>

### 参数 [#参数-20]

<ParameterList>
<a id="deviceid"></a>
<Parameter name="deviceId">

设备 ID。

</Parameter>
<a id="devicetype"></a>
<Parameter name="deviceType">

媒体设备类型，详见 [MEDIA_DEVICE_TYPE](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-mediadevicetype)。

</Parameter>
<a id="devicestate"></a>
<Parameter name="deviceState">

媒体设备状态，详见 [MEDIA_DEVICE_STATE_TYPE](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-mediadevicestatetype)。

</Parameter>
</ParameterList>

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

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