# 视频设备管理 (/zh-CN/api-reference/rtc/ios/device-management/video-device)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
## enableMultiCamera\:config: [#enablemulticameraconfig]
启用或关闭多摄像头采集模式。
```objc
- (int)enableMultiCamera:(BOOL)enabled config:(AgoraCameraCapturerConfiguration* _Nullable)config NS_SWIFT_NAME(enableMultiCamera(_:config:));
```
声网建议你在已有摄像头用于视频采集的场景中,按照以下步骤使用多摄像头进行视频采集和发布:
1. 调用该方法启用多摄像头采集模式。
2. 调用 [startPreview:](/zh-CN/api-reference/rtc/ios/video/video-basic#api_irtcengine_startpreview2) 启动本地视频预览。
3. 调用 [startCameraCapture\:config:](/zh-CN/api-reference/rtc/ios/video/camera-capture#api_irtcengine_startcameracapture),并设置 `sourceType` 以使用第二个摄像头进行视频采集。
4. 调用 [joinChannelExByToken\:connection\:delegate\:mediaOptions\:joinSuccess:](/zh-CN/api-reference/rtc/ios/channel#api_irtcengineex_joinchannelex),并将 `publishSecondaryCameraTrack` 设置为 YES,以在频道中发布第二个摄像头采集的视频流。
如果你想关闭多摄像头采集模式,请按以下步骤操作:
1. 调用 [stopCameraCapture:](/zh-CN/api-reference/rtc/ios/video/camera-capture#api_irtcengine_stopcameracapture)。
2. 调用该方法并将 `enabled` 设置为 NO。
使用该功能时,请确保系统版本为 iOS 13.0 或更高。支持多摄像头采集的最低 iOS 设备型号如下:
- iPhone XR
- iPhone XS
- iPhone XS Max
- iPad Pro 第三代及更新机型
:::note
注: 你可以在调用 [startPreview:](/zh-CN/api-reference/rtc/ios/video/video-basic#api_irtcengine_startpreview2) 之前或之后调用该方法启用多摄像头采集:
- 如果在 [startPreview:](/zh-CN/api-reference/rtc/ios/video/video-basic#api_irtcengine_startpreview2) 之前启用,本地视频预览会同时显示两个摄像头采集的画面。
- 如果在 [startPreview:](/zh-CN/api-reference/rtc/ios/video/video-basic#api_irtcengine_startpreview2) 之后启用,SDK 会先停止当前摄像头采集,然后启用主摄像头和第二个摄像头。本地视频预览会短暂变黑,然后自动恢复正常。
:::
### 参数 [#参数]
是否启用多摄像头视频采集模式:
- YES:启用多摄像头采集模式,SDK 使用多个摄像头进行视频采集。
- NO:关闭多摄像头采集模式,SDK 使用单个摄像头进行视频采集。
第二个摄像头的采集配置。详见 [AgoraCameraCapturerConfiguration](/zh-CN/api-reference/rtc/ios/class-cameracapturerconfiguration)。
### 返回值 [#返回值]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类]
- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)
## cameraMaxZoomFactor [#cameramaxzoomfactor]
获取摄像头支持的最大变焦倍数。
```objc
- (CGFloat)cameraMaxZoomFactor NS_SWIFT_NAME(cameraMaxZoomFactor());
```
:::note
注: 你必须在 SDK 触发 [rtcEngine\:localVideoStateChangedOfState\:reason\:sourceType:](/zh-CN/api-reference/rtc/ios/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 回调,并返回本地视频状态为 `AgoraVideoLocalStateCapturing`(1)后调用该方法。
:::
### 返回值 [#返回值-1]
方法调用成功,返回摄像头支持的最大变焦倍数。
### 所属接口类 [#所属接口类-1]
- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)
## isCameraAutoExposureFaceModeSupported [#iscameraautoexposurefacemodesupported]
检查设备是否支持自动曝光。
```objc
- (BOOL)isCameraAutoExposureFaceModeSupported NS_SWIFT_NAME(isCameraAutoExposureFaceModeSupported());
```
:::note
注: [isCameraAutoExposureFaceModeSupported](/zh-CN/api-reference/rtc/ios/device-management/video-device#api_irtcengine_iscameraautoexposurefacemodesupported) 方法必须在 SDK 触发 [rtcEngine\:localVideoStateChangedOfState\:reason\:sourceType:](/zh-CN/api-reference/rtc/ios/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 回调并返回本地视频状态为 `AgoraVideoLocalStateCapturing`(1)后调用。
:::
### 返回值 [#返回值-2]
- YES:设备支持自动曝光。
- NO:设备不支持自动曝光。
### 所属接口类 [#所属接口类-2]
- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)
## isCameraAutoFocusFaceModeSupported [#iscameraautofocusfacemodesupported]
检查设备是否支持人脸自动对焦功能。
```objc
- (BOOL)isCameraAutoFocusFaceModeSupported NS_SWIFT_NAME(isCameraAutoFocusFaceModeSupported());
```
:::note
注: 你必须在 SDK 触发 [rtcEngine\:localVideoStateChangedOfState\:reason\:sourceType:](/zh-CN/api-reference/rtc/ios/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 回调并返回本地视频状态为 `AgoraVideoLocalStateCapturing`(1)后调用此方法。
:::
### 返回值 [#返回值-3]
- YES:设备支持人脸自动对焦功能。
- NO:设备不支持人脸自动对焦功能。
### 所属接口类 [#所属接口类-3]
- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)
## isCameraExposurePositionSupported [#iscameraexposurepositionsupported]
检查设备是否支持手动曝光。
```objc
- (BOOL)isCameraExposurePositionSupported NS_SWIFT_NAME(isCameraExposurePositionSupported());
```
:::note
注: 必须在 SDK 触发 [rtcEngine\:localVideoStateChangedOfState\:reason\:sourceType:](/zh-CN/api-reference/rtc/ios/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 回调并返回本地视频状态为 `AgoraVideoLocalStateCapturing`(1)后调用此方法。
:::
### 返回值 [#返回值-4]
- YES:设备支持手动曝光。
- NO:设备不支持手动曝光。
### 所属接口类 [#所属接口类-4]
- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)
## isCameraExposureSupported [#iscameraexposuresupported]
查询当前摄像头是否支持调节曝光值。
```objc
- (BOOL)isCameraExposureSupported NS_SWIFT_NAME(isCameraExposureSupported());
```
:::info[自从]
自 v4.2.2 版本新增。
:::
:::note
注:
- 你必须在 SDK 触发 [rtcEngine\:localVideoStateChangedOfState\:reason\:sourceType:](/zh-CN/api-reference/rtc/ios/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 回调并返回本地视频状态为 `AgoraVideoLocalStateCapturing`(1)后调用该方法。
- 在调用 [setCameraExposureFactor:](/zh-CN/api-reference/rtc/ios/device-management/video-device#api_irtcengine_setcameraexposurefactor) 之前,建议你先调用该方法,确认当前摄像头是否支持调节曝光值。
- 该方法用于调节当前激活摄像头的曝光值,即调用 [setCameraCapturerConfiguration:](/zh-CN/api-reference/rtc/ios/device-management/video-device#api_irtcengine_setcameracapturerconfiguration) 时指定的摄像头。
:::
### 返回值 [#返回值-5]
- YES:查询成功,当前摄像头支持调节曝光值。
- NO:查询失败,当前摄像头不支持调节曝光值。
### 所属接口类 [#所属接口类-5]
- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)
## isCameraFocusPositionInPreviewSupported [#iscamerafocuspositioninpreviewsupported]
检查设备是否支持手动对焦功能。
```objc
- (BOOL)isCameraFocusPositionInPreviewSupported NS_SWIFT_NAME(isCameraFocusPositionInPreviewSupported());
```
:::note
注: 必须在 SDK 触发 [rtcEngine\:localVideoStateChangedOfState\:reason\:sourceType:](/zh-CN/api-reference/rtc/ios/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 回调并返回本地视频状态为 `AgoraVideoLocalStateCapturing`(1)后调用此方法。
:::
### 返回值 [#返回值-6]
- YES:设备支持手动对焦功能。
- NO:设备不支持手动对焦功能。
### 所属接口类 [#所属接口类-6]
- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)
## isCameraTorchSupported [#iscameratorchsupported]
检查设备是否支持相机闪光灯。
```objc
- (BOOL)isCameraTorchSupported NS_SWIFT_NAME(isCameraTorchSupported());
```
:::note
注: 你必须在 SDK 触发 [rtcEngine\:localVideoStateChangedOfState\:reason\:sourceType:](/zh-CN/api-reference/rtc/ios/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 回调并返回本地视频状态为 `AgoraVideoLocalStateCapturing`(1)后调用该方法。App 默认启用前置摄像头。如果前置摄像头不支持闪光灯,该方法返回 NO。如果你想检查后置摄像头是否支持闪光灯功能,请在调用该方法前调用 [switchCamera](/zh-CN/api-reference/rtc/ios/device-management/video-device#api_irtcengine_switchcamera)。在系统版本为 15 的 iPad 上,即使 [isCameraTorchSupported](/zh-CN/api-reference/rtc/ios/device-management/video-device#api_irtcengine_iscameratorchsupported) 返回 YES,你也可能因系统问题调用 [setCameraTorchOn:](/zh-CN/api-reference/rtc/ios/device-management/video-device#api_irtcengine_setcameratorchon) 启用闪光灯失败。
:::
### 返回值 [#返回值-7]
- YES:设备支持相机闪光灯。
- NO:设备不支持相机闪光灯。
### 所属接口类 [#所属接口类-7]
- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)
## isCameraZoomSupported [#iscamerazoomsupported]
检查设备是否支持摄像头变焦。
```objc
- (BOOL)isCameraZoomSupported NS_SWIFT_NAME(isCameraZoomSupported());
```
### 调用时机 [#调用时机]
你必须在 SDK 触发 [rtcEngine\:localVideoStateChangedOfState\:reason\:sourceType:](/zh-CN/api-reference/rtc/ios/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 回调并返回本地视频状态为 `AgoraVideoLocalStateCapturing`(1)后调用该方法。
### 返回值 [#返回值-8]
- YES:设备支持摄像头变焦。
- NO:设备不支持摄像头变焦。
### 所属接口类 [#所属接口类-8]
- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)
## queryCameraFocalLengthCapability [#querycamerafocallengthcapability]
查询摄像头支持的焦距能力。
```objc
- (NSArray* _Nullable)queryCameraFocalLengthCapability NS_SWIFT_NAME(queryCameraFocalLengthCapability());
```
如果你希望在视频采集中启用广角或超广角模式,建议你首先调用 [queryCameraFocalLengthCapability](/zh-CN/api-reference/rtc/ios/device-management/video-device#api_irtcengine_querycamerafocallengthcapability) 方法检查设备是否支持所需的焦距能力。然后,根据查询结果调用 [setCameraCapturerConfiguration:](/zh-CN/api-reference/rtc/ios/device-management/video-device#api_irtcengine_setcameracapturerconfiguration) 方法调整摄像头的焦距配置,以确保最佳的视频采集性能。
### 返回值 [#返回值-9]
- 方法调用成功,返回一个 [AgoraFocalLengthInfo](/zh-CN/api-reference/rtc/ios/class-focallengthinfo) 对象数组,包含摄像头的方向和焦距类型,详见 [AgoraFocalLengthInfo](/zh-CN/api-reference/rtc/ios/class-focallengthinfo)。
- 方法调用失败,返回 nil。
### 所属接口类 [#所属接口类-9]
- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)
## queryCodecCapability [#querycodeccapability]
查询设备支持的视频编解码能力。
```objc
- (NSArray *_Nullable)queryCodecCapability;
```
### 返回值 [#返回值-10]
- 方法调用成功时,返回一个 [AgoraVideoCodecCapInfo](/zh-CN/api-reference/rtc/ios/class-codeccapinfo) 数组,表示设备的视频编码能力,详见 [AgoraVideoCodecCapInfo](/zh-CN/api-reference/rtc/ios/class-codeccapinfo)。
- 方法调用失败时,返回 nil。如果调用超时,请调整调用逻辑,避免在主线程中调用该方法。
### 所属接口类 [#所属接口类-10]
- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)
## setCameraAutoExposureFaceModeEnabled: [#setcameraautoexposurefacemodeenabled]
设置是否启用自动曝光。
```objc
- (BOOL)setCameraAutoExposureFaceModeEnabled:(BOOL)enable NS_SWIFT_NAME(setCameraAutoExposureFaceModeEnabled(_:));
```
:::note
注: 你必须在调用 [enableVideo](/zh-CN/api-reference/rtc/ios/video/video-basic#api_irtcengine_enablevideo) 方法之后再调用此方法。设置结果将在摄像头成功开启后生效,即 SDK 触发 [rtcEngine\:localVideoStateChangedOfState\:reason\:sourceType:](/zh-CN/api-reference/rtc/ios/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 回调并返回本地视频状态为 `AgoraVideoLocalStateCapturing`(1)之后。
:::
### 参数 [#参数-1]
是否启用自动曝光:
- YES:启用自动曝光。
- NO:关闭自动曝光。
### 返回值 [#返回值-11]
- YES:设置成功。
- NO:设置失败。
### 所属接口类 [#所属接口类-11]
- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)
## setCameraAutoFocusFaceModeEnabled: [#setcameraautofocusfacemodeenabled]
启用或关闭摄像头人像自动对焦功能。
```objc
- (BOOL)setCameraAutoFocusFaceModeEnabled:(BOOL)enable NS_SWIFT_NAME(setCameraAutoFocusFaceModeEnabled(_:));
```
你可以通过调用该方法关闭人像自动对焦功能。SDK 默认启用该功能。
### 调用时机 [#调用时机-1]
必须在 SDK 触发 [rtcEngine\:localVideoStateChangedOfState\:reason\:sourceType:](/zh-CN/api-reference/rtc/ios/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 回调并返回本地视频状态为 `AgoraVideoLocalStateCapturing`(1)后调用。
### 参数 [#参数-2]
是否启用摄像头人像自动对焦功能:
- YES:启用摄像头人像自动对焦功能。
- NO:关闭人像自动对焦功能。
### 返回值 [#返回值-12]
- YES:设置成功。
- NO:设置失败。
### 所属接口类 [#所属接口类-12]
- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)
## setCameraCapturerConfiguration: [#setcameracapturerconfiguration]
设置视频采集配置。
```objc
- (int)setCameraCapturerConfiguration:(AgoraCameraCapturerConfiguration * _Nullable)config NS_SWIFT_NAME(setCameraCapturerConfiguration(_:));
```
在启用本地摄像头采集前调用此方法,例如在调用 [startPreview:](/zh-CN/api-reference/rtc/ios/video/video-basic#api_irtcengine_startpreview2) 和 `joinChannelByToken` 之前。
:::note
注: 如需调整摄像头焦距配置,建议先调用 [queryCameraFocalLengthCapability](/zh-CN/api-reference/rtc/ios/device-management/video-device#api_irtcengine_querycamerafocallengthcapability) 查询设备的焦距能力,并根据查询结果进行配置。
:::
### 调用时机 [#调用时机-2]
在启用本地摄像头采集前调用,例如在调用 [startPreview:](/zh-CN/api-reference/rtc/ios/video/video-basic#api_irtcengine_startpreview2) 和 `joinChannelByToken` 之前。
### 参数 [#参数-3]
摄像头采集配置。详见 [AgoraCameraCapturerConfiguration](/zh-CN/api-reference/rtc/ios/class-cameracapturerconfiguration)。
:::note
注: 在此方法中,无需设置 `deviceId` 参数。
:::
### 返回值 [#返回值-13]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-13]
- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)
## setCameraExposureFactor: [#setcameraexposurefactor]
设置摄像头曝光值。
```objc
- (CGFloat)setCameraExposureFactor:(CGFloat)exposureFactor NS_SWIFT_NAME(setCameraExposureFactor(_:));
```
:::info[自从]
自 v4.2.2 版本新增。
:::
你可以通过此方法调整摄像头的曝光值,以获得最佳的视频质量。
:::note
注:
- 你必须在调用 [enableVideo](/zh-CN/api-reference/rtc/ios/video/video-basic#api_irtcengine_enablevideo) 方法之后再调用此方法。设置结果在摄像头成功开启后生效,即 SDK 触发 [rtcEngine\:localVideoStateChangedOfState\:reason\:sourceType:](/zh-CN/api-reference/rtc/ios/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 回调并返回本地视频状态为 `AgoraVideoLocalStateCapturing`(1)后。
- 在调用此方法前,建议你调用 [isCameraExposureSupported](/zh-CN/api-reference/rtc/ios/device-management/video-device#api_irtcengine_iscameraexposuresupported) 方法检查当前摄像头是否支持调整曝光值。
- 该方法调整的是当前正在使用的摄像头的曝光值,即调用 [setCameraCapturerConfiguration:](/zh-CN/api-reference/rtc/ios/device-management/video-device#api_irtcengine_setcameracapturerconfiguration) 方法时指定的摄像头。
:::
### 参数 [#参数-4]
摄像头曝光值(默认值为 0)。值越大,曝光越强。当视频图像过曝时,可以降低曝光值;当视频图像曝光不足且暗部细节丢失时,可以提高曝光值。如果设置的曝光值超出设备支持的范围,SDK 会自动将其调整为设备实际支持的范围。取值范围为 [-8.0, 8.0]。
### 返回值 [#返回值-14]
无实际意义。
### 所属接口类 [#所属接口类-14]
- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)
## setCameraExposurePosition: [#setcameraexposureposition]
设置摄像头曝光位置。
```objc
- (BOOL)setCameraExposurePosition:(CGPoint)positionInView NS_SWIFT_NAME(setCameraExposurePosition(_:));
```
:::note
注: 你必须在调用 [enableVideo](/zh-CN/api-reference/rtc/ios/video/video-basic#api_irtcengine_enablevideo) 方法之后再调用该方法。设置结果会在摄像头成功开启后生效,即 SDK 触发 [rtcEngine\:localVideoStateChangedOfState\:reason\:sourceType:](/zh-CN/api-reference/rtc/ios/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 回调并返回本地视频状态为 `AgoraVideoLocalStateCapturing`(1)后生效。成功调用该方法后,SDK 会触发 [rtcEngine\:cameraExposureDidChangedToRect:](/zh-CN/api-reference/rtc/ios/device-management/video-device#callback_irtcengineeventhandler_oncameraexposureareachanged) 回调。
:::
### 参数 [#参数-5]
视图中触摸点的横坐标。
### 返回值 [#返回值-15]
- YES:设置成功。
- NO:设置失败。
### 所属接口类 [#所属接口类-15]
- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)
## setCameraFocusPositionInPreview: [#setcamerafocuspositioninpreview]
设置摄像头的手动对焦位置。
```objc
- (BOOL)setCameraFocusPositionInPreview:(CGPoint)position NS_SWIFT_NAME(setCameraFocusPositionInPreview(_:));
```
:::note
注: 你必须在调用 [enableVideo](/zh-CN/api-reference/rtc/ios/video/video-basic#api_irtcengine_enablevideo) 方法之后再调用本方法。设置结果会在摄像头成功开启后生效,即 SDK 触发 [rtcEngine\:localVideoStateChangedOfState\:reason\:sourceType:](/zh-CN/api-reference/rtc/ios/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 回调并返回本地视频状态为 `AgoraVideoLocalStateCapturing`(1)后生效。成功调用该方法后,SDK 会触发 [rtcEngine\:cameraFocusDidChangedToRect:](/zh-CN/api-reference/rtc/ios/device-management/video-device#callback_irtcengineeventhandler_oncamerafocusareachanged) 回调。
:::
### 参数 [#参数-6]
视图中触摸点的坐标。
### 返回值 [#返回值-16]
- YES:设置成功。
- NO:设置失败。
### 所属接口类 [#所属接口类-16]
- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)
## setCameraTorchOn: [#setcameratorchon]
启用摄像头闪光灯。
```objc
- (BOOL)setCameraTorchOn:(BOOL)isOn NS_SWIFT_NAME(setCameraTorchOn(_:));
```
:::note
注: 你必须在调用 [enableVideo](/zh-CN/api-reference/rtc/ios/video/video-basic#api_irtcengine_enablevideo) 后再调用此方法。设置结果将在摄像头成功开启后生效,即 SDK 触发 [rtcEngine\:localVideoStateChangedOfState\:reason\:sourceType:](/zh-CN/api-reference/rtc/ios/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 回调并返回本地视频状态为 `AgoraVideoLocalStateCapturing`(1)后。
:::
### 参数 [#参数-7]
是否打开摄像头闪光灯:
- YES:打开闪光灯。
- NO:(默认)关闭闪光灯。
### 返回值 [#返回值-17]
- YES:设置成功。
- NO:设置失败。
### 所属接口类 [#所属接口类-17]
- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)
## setCameraZoomFactor: [#setcamerazoomfactor]
设置摄像头的缩放因子。
```objc
- (CGFloat)setCameraZoomFactor:(CGFloat)zoomFactor NS_SWIFT_NAME(setCameraZoomFactor(_:));
```
你可以调用 [setCameraCapturerConfiguration:](/zh-CN/api-reference/rtc/ios/device-management/video-device#api_irtcengine_setcameracapturerconfiguration) 方法,将 `cameraFocalLengthType` 设置为 `AgoraFocalLengthDefault`(0),然后将摄像头缩放因子设置为小于 1.0 的值,以实现超广角视角的视频采集。该方法适用于配备多镜头后置摄像头的 iOS 设备,例如配有广角、超广角和长焦镜头的设备。
:::note
注: 你必须在调用 [enableVideo](/zh-CN/api-reference/rtc/ios/video/video-basic#api_irtcengine_enablevideo) 之后再调用此方法。设置结果将在摄像头成功开启后生效,即 SDK 触发 [rtcEngine\:localVideoStateChangedOfState\:reason\:sourceType:](/zh-CN/api-reference/rtc/ios/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 回调并返回本地视频状态为 `AgoraVideoLocalStateCapturing`(1)之后。
:::
### 参数 [#参数-8]
摄像头缩放因子。对于不支持超广角的设备,该值范围为 1.0 到最大缩放因子;对于支持超广角的设备,该值范围为 0.5 到最大缩放因子。你可以通过调用 [cameraMaxZoomFactor](/zh-CN/api-reference/rtc/ios/device-management/video-device#api_irtcengine_getcameramaxzoomfactor) 方法获取设备支持的最大缩放因子。
### 返回值 [#返回值-18]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-18]
- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)
## switchCamera [#switchcamera]
切换前后摄像头。
```objc
- (int)switchCamera NS_SWIFT_NAME(switchCamera());
```
你可以调用此方法,根据应用运行时实际可用的摄像头动态切换前后摄像头,无需重新启动视频流或重新配置视频源。
:::note
注: 此方法仅切换由第一个摄像头采集的视频流的摄像头,即调用 [startCameraCapture\:config:](/zh-CN/api-reference/rtc/ios/video/camera-capture#api_irtcengine_startcameracapture) 时视频源设置为 `AgoraVideoSourceTypeCamera`(0)的视频流。
:::
### 调用时机 [#调用时机-3]
必须在摄像头成功启用后调用,即 SDK 触发 [rtcEngine\:localVideoStateChangedOfState\:reason\:sourceType:](/zh-CN/api-reference/rtc/ios/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 回调并返回本地视频状态为 `AgoraVideoLocalStateCapturing`(1)之后。
### 返回值 [#返回值-19]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-19]
- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)
## rtcEngine\:cameraExposureDidChangedToRect: [#rtcenginecameraexposuredidchangedtorect]
摄像头曝光区域发生变化回调。
```objc
- (void)rtcEngine:(AgoraRtcEngineKit* _Nonnull)engine cameraExposureDidChangedToRect:(CGRect)rect NS_SWIFT_NAME(rtcEngine(_:cameraExposureDidChangedTo:));
```
当你调用 [setCameraExposurePosition:](/zh-CN/api-reference/rtc/ios/device-management/video-device#api_irtcengine_setcameraexposureposition) 方法更改摄像头曝光位置时,SDK 会触发该回调。
### 触发时机 [#触发时机]
该回调在你调用 [setCameraExposurePosition:](/zh-CN/api-reference/rtc/ios/device-management/video-device#api_irtcengine_setcameraexposureposition) 更改摄像头曝光位置时被触发。
### 参数 [#参数-9]
[AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine) 对象,详见 [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)。
本地预览中的曝光矩形区域。
### 所属接口类 [#所属接口类-20]
- [AgoraRtcEngineDelegate](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengineeventhandler)
## rtcEngine\:cameraFocusDidChangedToRect: [#rtcenginecamerafocusdidchangedtorect]
摄像头对焦区域发生变化时的回调。
```objc
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine cameraFocusDidChangedToRect:(CGRect)rect NS_SWIFT_NAME(rtcEngine(_:cameraFocusDidChangedTo:));
```
调用 [setCameraFocusPositionInPreview:](/zh-CN/api-reference/rtc/ios/device-management/video-device#api_irtcengine_setcamerafocuspositioninpreview) 方法更改摄像头对焦位置时,SDK 会触发该回调。
### 触发时机 [#触发时机-1]
该回调在你调用 [setCameraFocusPositionInPreview:](/zh-CN/api-reference/rtc/ios/device-management/video-device#api_irtcengine_setcamerafocuspositioninpreview) 更改摄像头对焦位置时被触发。
### 参数 [#参数-10]
本地预览画面中的对焦矩形区域。
[AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine) 对象,详见 [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)。
### 所属接口类 [#所属接口类-21]
- [AgoraRtcEngineDelegate](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengineeventhandler)
## rtcEngineCameraDidReady: [#rtcenginecameradidready]
摄像头准备就绪回调。
```objc
- (void)rtcEngineCameraDidReady:(AgoraRtcEngineKit * _Nonnull)engine NS_SWIFT_NAME(rtcEngineCameraDidReady(_:)) __deprecated_msg("Use rtcEngine:localVideoStateChangedOfState:reason:sourceType: instead");
```
:::error[废弃]
该方法已废弃,请改用 [rtcEngine\:localVideoStateChangedOfState\:reason\:sourceType:](/zh-CN/api-reference/rtc/ios/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged)。
:::
### 触发时机 [#触发时机-2]
该回调在摄像头成功打开并准备好采集视频时触发。
### 参数 [#参数-11]
[AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine) 对象。详见 [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)。
### 所属接口类 [#所属接口类-22]
- [AgoraRtcEngineDelegate](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengineeventhandler)