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 IDeviceInfocreateDeviceInfo ()=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

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

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 ( )
inlineprotected

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
sourceThe 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
zoomValueThe 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
isOnDetermines 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
positionXinViewThe horizontal coordinate of the touch point in the view.
positionYinViewThe 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
valueAbsolute 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
enableDetermines 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
enabledDetermines 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
modespecifies 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
deviceIdThe 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
deviceNameThe 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
enabledenable 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_ORIENTATIONorientaion 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_formatThe 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
observerInstance of the capture observer.

◆ unregisterCameraObserver()

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

Unregisters the camera observer.

Parameters
observerInstance of the capture observer.