Agora C++ API Reference for All Platforms

Classes | Public Types | Public Member Functions | Protected Member Functions | List of all members
agora::rtc::ICameraCapturer Class Referenceabstract

Inherits agora::RefCountInterface.

Inherited by agora::rtc::ICameraCapturerEx.

## Classes
class | IDeviceInfo

## Public Types
enum | CAMERA_SOURCE { CAMERA_BACK, CAMERA_FRONT, CAMERA_EXTRA }
enum | CAMERA_STATE { CAMERA_STARTED, CAMERA_STOPPED }

## Public Member Functions
virtual int | setCameraSource (CAMERA_SOURCE source, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual CAMERA_SOURCE | getCameraSource ()=0
virtual int | switchCamera (aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual bool | isZoomSupported ()=0
virtual int32_t | setCameraZoom (float zoomValue, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual float | getCameraMaxZoom ()=0
virtual bool | isFocusSupported ()=0
virtual int32_t | setCameraFocus (float x, float y, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual bool | isAutoFaceFocusSupported ()=0
virtual int32_t | setCameraAutoFaceFocus (bool enable, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int32_t | enableFaceDetection (bool enable, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual bool | isCameraFaceDetectSupported ()=0
virtual bool | isCameraTorchSupported ()=0
virtual int | setCameraTorchOn (bool on, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual bool | isCameraExposurePositionSupported ()=0
virtual int | setCameraExposurePosition (float positionXinView, float positionYinView, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual bool | isCameraExposureSupported ()=0
virtual int | setCameraExposureFactor (float value, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual bool | enableMultiCamera (bool enable, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual bool | isCameraAutoExposureFaceModeSupported ()=0
virtual int | setCameraAutoExposureFaceModeEnabled (bool enabled, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | setCameraStabilizationMode (CAMERA_STABILIZATION_MODE mode)=0
virtual IDeviceInfo * | createDeviceInfo ()=0
virtual int | initWithDeviceId (const char *deviceId)=0
virtual int | initWithDeviceName (const char *deviceName)=0
virtual bool | isCenterStageSupported ()=0
virtual int | enableCenterStage (bool enabled)=0
virtual int | setDeviceOrientation (VIDEO_ORIENTATION orientation, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | setCaptureFormat (const VideoFormat &capture_format, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual VideoFormat | getCaptureFormat ()=0
virtual int | registerCameraObserver (ICameraCaptureObserver *observer, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | unregisterCameraObserver (ICameraCaptureObserver *observer)=0
Public Member Functions inherited from agora::RefCountInterface
virtual void | AddRef () const =0
virtual RefCountReleaseStatus | Release () const =0
virtual bool | HasOneRef () const =0

## Protected Member Functions
| ~ICameraCapturer ()
Protected Member Functions inherited from agora::RefCountInterface
virtual | ~RefCountInterface ()

## Detailed Description

The ICameraCapturer class, which provides access to a camera capturer.

## Member Enumeration Documentation

## ◆ CAMERA_SOURCE

enum agora::rtc::ICameraCapturer::CAMERA_SOURCE

The camera source.

Enumerator
CAMERA_BACK | The camera source is the rear camera.
CAMERA_FRONT | The camera source is the front camera.
CAMERA_EXTRA | The camera source is the extra camera.

## ◆ CAMERA_STATE

enum agora::rtc::ICameraCapturer::CAMERA_STATE

The camera state.

Enumerator
CAMERA_STARTED | The camera source is started.
CAMERA_STOPPED | The camera source is stopped.

## Constructor & Destructor Documentation

## ◆ ~ICameraCapturer()

agora::rtc::ICameraCapturer::~ICameraCapturer | ( |  | ) |
| inline protected

## Member Function Documentation

## ◆ setCameraSource()

virtual int agora::rtc::ICameraCapturer::setCameraSource | ( | CAMERA_SOURCE | source,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

Sets the camera source.

Note
  This method applies to Android and iOS only.

Parameters

  source | The camera source that you want to capture. See CAMERA_SOURCE.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ getCameraSource()

virtual CAMERA_SOURCE agora::rtc::ICameraCapturer::getCameraSource | ( |  | ) |
| pure virtual

Gets the camera source.

Note
  This method applies to Android and iOS only.

Returns
  The camera source. See CAMERA_SOURCE.

## ◆ switchCamera()

virtual int agora::rtc::ICameraCapturer::switchCamera | ( | aosl_ref_t | ares = `AOSL_REF_INVALID` | ) |
| pure virtual

Switch the camera source

Note
  This method applies to Android and iOS only.

## ◆ isZoomSupported()

virtual bool agora::rtc::ICameraCapturer::isZoomSupported | ( |  | ) |
| pure virtual

Returns whether zooming is supported by the current device.

Note
  This method applies to Android and iOS only. This interface returns valid values only after the device is initialized.

Returns
  - true: zooming is supported.
  - false: zooming is not supported or device is not initialized.

## ◆ setCameraZoom()

virtual int32_t agora::rtc::ICameraCapturer::setCameraZoom | ( | float | zoomValue,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

Sets the zooming factor of the device.

Note
  This method applies to Android and iOS only.

Parameters

  zoomValue | The zooming factor of the device.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ getCameraMaxZoom()

virtual float agora::rtc::ICameraCapturer::getCameraMaxZoom | ( |  | ) |
| pure virtual

Gets the max zooming factor of the device.

Note
  This method applies to Android and iOS only.

Returns
  - The max zooming factor of the device

## ◆ isFocusSupported()

virtual bool agora::rtc::ICameraCapturer::isFocusSupported | ( |  | ) |
| pure virtual

Returns whether auto-focus is supported by the current device.

Note
  This method applies to Android and iOS only. This interface returns valid values only after device is initialized.

Returns
  - true: auto-focus is supported.
  - false: auto-focus is not supported or device is not initialized.

## ◆ setCameraFocus()

virtual int32_t agora::rtc::ICameraCapturer::setCameraFocus | ( | float | x,
|  | float | y,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

Sets the focus area of the current device.

Note
  This method applies to Android and iOS only.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ isAutoFaceFocusSupported()

virtual bool agora::rtc::ICameraCapturer::isAutoFaceFocusSupported | ( |  | ) |
| pure virtual

Returns whether auto face focus is supported by the current device.

Note
  This method applies to Android and iOS only. This interface returns valid values only after device is initialized.

Returns
  - true: auto-face-focus is supported.
  - false: auto-face-focus is not supported or device is not initialized.

## ◆ setCameraAutoFaceFocus()

virtual int32_t agora::rtc::ICameraCapturer::setCameraAutoFaceFocus | ( | bool | enable,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

Enables or disables auto face focus.

Note
  This method applies to Android and iOS only. This interface returns valid values only after device is initialized.

Returns
  - 0: Success.

- < 0: Failure.

## ◆ enableFaceDetection()

virtual int32_t agora::rtc::ICameraCapturer::enableFaceDetection | ( | bool | enable,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

Enables or disables auto face detection.

Note
  This method applies to Android and iOS only. This interface returns valid values only after device is initialized.

Returns
  - 0: Success.

- < 0: Failure.

## ◆ isCameraFaceDetectSupported()

virtual bool agora::rtc::ICameraCapturer::isCameraFaceDetectSupported | ( |  | ) |
| pure virtual

Checks whether the camera face detect is supported.

Returns
  - true: The camera face detect is supported.
  - false: The camera face detect is not supported.

## ◆ isCameraTorchSupported()

virtual bool agora::rtc::ICameraCapturer::isCameraTorchSupported | ( |  | ) |
| pure virtual

Checks whether the camera flash function is supported.

The SDK uses the front camera by default, so if you call `isCameraTorchSupported` directly, you can find out from the return value whether the device supports enabling the flash when using the front camera. If you want to check whether the device supports enabling the flash when using the rear camera, call switchCamera to switch the camera used by the SDK to the rear camera, and then call `isCameraTorchSupported`.

Note
  - Call this method after the camera is started.
  - This method is for Android and iOS only.
  - On iPads with system version 15, even if `isCameraTorchSupported` returns true, you might fail to successfully enable the flash by calling setCameraTorchOn due to system issues.

Returns
  - true: The device supports enabling the flash.
  - false: The device does not support enabling the flash.

## ◆ setCameraTorchOn()

virtual int agora::rtc::ICameraCapturer::setCameraTorchOn | ( | bool | on,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

Note
  - Call this method after the camera is started.
  - This method is for Android and iOS only.
  - On iPads with system version 15, even if isCameraTorchSupported returns true, you might fail to successfully enable the flash by calling `setCameraTorchOn` due to system issues.

Parameters

  isOn | Determines whether to enable the flash: true: Enable the flash. false: Disable the flash.

Returns
  - 0: Success
  - < 0: Failure

## ◆ isCameraExposurePositionSupported()

virtual bool agora::rtc::ICameraCapturer::isCameraExposurePositionSupported | ( |  | ) |
| pure virtual

Checks whether the camera exposure function is supported.

Ensure that you call this method after the camera starts, for example, by calling `startPreview` or `joinChannel`.

Since
  v2.3.2.

Returns
  - true: The device supports the camera exposure function.
  - false: The device does not support the camera exposure function.

## ◆ setCameraExposurePosition()

virtual int agora::rtc::ICameraCapturer::setCameraExposurePosition | ( | float | positionXinView,
|  | float | positionYinView,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

Sets the camera exposure position.

Ensure that you call this method after the camera starts, for example, by calling `startPreview` or `joinChannel`.

A successful setCameraExposurePosition method call triggers the onCameraExposureAreaChanged callback on the local client.

Since
  v2.3.2.

Parameters

  positionXinView | The horizontal coordinate of the touch point in the view.
  positionYinView | The vertical coordinate of the touch point in the view.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ isCameraExposureSupported()

virtual bool agora::rtc::ICameraCapturer::isCameraExposureSupported | ( |  | ) |
| pure virtual

Returns whether exposure value adjusting is supported by the current device. Exposure compensation is in auto exposure mode.

Since
  v4.2.2.

Note
  This method only supports Android and iOS. This interface returns valid values only after the device is initialized.

Returns
  - true: exposure value adjusting is supported.
  - false: exposure value adjusting is not supported or device is not initialized.

## ◆ setCameraExposureFactor()

virtual int agora::rtc::ICameraCapturer::setCameraExposureFactor | ( | float | value,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

Sets the camera exposure ratio.

Since
  v4.2.2.

Parameters

  value | Absolute EV bias will set to camera.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ enableMultiCamera()

virtual bool agora::rtc::ICameraCapturer::enableMultiCamera | ( | bool | enable,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

Enables or disables the AVCaptureMultiCamSession.

Parameters

  enable | Determines whether to use the AVCaptureMultiCamSession: true: Enable the AVCaptureMultiCamSession. false: Disable the AVCaptureMultiCamSession.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ isCameraAutoExposureFaceModeSupported()

virtual bool agora::rtc::ICameraCapturer::isCameraAutoExposureFaceModeSupported | ( |  | ) |
| pure virtual

Checks whether the camera auto exposure function is supported.

Returns
  - true: The camera auto exposure function is supported.
  - false: The camera auto exposure function is not supported.

## ◆ setCameraAutoExposureFaceModeEnabled()

virtual int agora::rtc::ICameraCapturer::setCameraAutoExposureFaceModeEnabled | ( | bool | enabled,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

Enables the camera auto exposure face function.

Parameters

  enabled | Determines whether to enable the camera auto exposure face mode. true: Enable the auto exposure face function. false: Do not enable the auto exposure face function.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setCameraStabilizationMode()

virtual int agora::rtc::ICameraCapturer::setCameraStabilizationMode | ( | CAMERA_STABILIZATION_MODE | mode | ) |
| pure virtual

set camera stabilization mode.If open stabilization mode, fov will be smaller and capture latency will be longer.

Parameters

  mode | specifies the camera stabilization mode.

## ◆ createDeviceInfo()

virtual IDeviceInfo* agora::rtc::ICameraCapturer::createDeviceInfo | ( |  | ) |
| pure virtual

Creates a DeviceInfo object.

Note
  This method applies to Windows, macOS, and Linux only.

Returns
  - The pointer to IDeviceInfo: Success.
  - An empty pointer NULL: Failure.

## ◆ initWithDeviceId()

virtual int agora::rtc::ICameraCapturer::initWithDeviceId | ( | const char * | deviceId | ) |
| pure virtual

Initializes the device with the device ID.

Note
  This method applies to Windows, macOS, and Linux only.

Parameters

  deviceId | The pointer to the device ID.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ initWithDeviceName()

virtual int agora::rtc::ICameraCapturer::initWithDeviceName | ( | const char * | deviceName | ) |
| pure virtual

Initializes the device with the device name.

Note
  This method applies to Windows, macOS, and Linux only.

Parameters

  deviceName | The pointer to the device name.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ isCenterStageSupported()

virtual bool agora::rtc::ICameraCapturer::isCenterStageSupported | ( |  | ) |
| pure virtual

Checks whether the center stage is supported. Use this method after starting the camera.

Returns
  - true: The center stage is supported.
  - false: The center stage is not supported.

## ◆ enableCenterStage()

virtual int agora::rtc::ICameraCapturer::enableCenterStage | ( | bool | enabled | ) |
| pure virtual

Enables the camera Center Stage.

Parameters

  enabled | enable Center Stage: true: Enable Center Stage. false: Disable Center Stage.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setDeviceOrientation()

virtual int agora::rtc::ICameraCapturer::setDeviceOrientation | ( | VIDEO_ORIENTATION | orientation,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

Set the device orientation of the capture device

Parameters

  VIDEO_ORIENTATION | orientaion of the device 0(by default), 90, 180, 270

## ◆ setCaptureFormat()

virtual int agora::rtc::ICameraCapturer::setCaptureFormat | ( | const VideoFormat & | capture_format,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

Sets the format of the video captured by the camera.

If you do not set the video capturing format, the SDK automatically chooses a proper format according to the video encoder configuration of the video track.

Parameters

  capture_format | The reference to the video format: VideoFormat.

## ◆ getCaptureFormat()

virtual VideoFormat agora::rtc::ICameraCapturer::getCaptureFormat | ( |  | ) |
| pure virtual

Gets the format of the video captured by the camera.

Returns
  VideoFormat.

## ◆ registerCameraObserver()

virtual int agora::rtc::ICameraCapturer::registerCameraObserver | ( | ICameraCaptureObserver * | observer,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

Register a camera observer.

Parameters

  observer | Instance of the capture observer.

## ◆ unregisterCameraObserver()

virtual int agora::rtc::ICameraCapturer::unregisterCameraObserver | ( | ICameraCaptureObserver * | observer | ) |
| pure virtual

Unregisters the camera observer.

Parameters

  observer | Instance of the capture observer.