QCamera Class

The QCamera class provides interface for system camera devices. More...

Header: #include <QCamera>
CMake: find_package(Qt6 REQUIRED COMPONENTS Multimedia)
target_link_libraries(mytarget PRIVATE Qt6::Multimedia)
qmake: QT += multimedia
In QML: Camera
Inherits: QObject

Public Types

enum Error { NoError, CameraError }
enum ExposureMode { ExposureAuto, ExposureManual, ExposurePortrait, ExposureNight, ExposureSports, …, ExposureBarcode }
enum class Feature { ColorTemperature, ExposureCompensation, IsoSensitivity, ManualExposureTime, CustomFocusPoint, FocusDistance }
flags Features
enum FlashMode { FlashOff, FlashOn, FlashAuto }
enum FocusMode { FocusModeAuto, FocusModeAutoNear, FocusModeAutoFar, FocusModeHyperfocal, FocusModeInfinity, FocusModeManual }
enum TorchMode { TorchOff, TorchOn, TorchAuto }
enum WhiteBalanceMode { WhiteBalanceAuto, WhiteBalanceManual, WhiteBalanceSunlight, WhiteBalanceCloudy, WhiteBalanceShade, …, WhiteBalanceSunset }

Properties

Public Functions

QCamera(QObject *parent = nullptr)
QCamera(QCameraDevice::Position position, QObject *parent = nullptr)
QCamera(const QCameraDevice &cameraDevice, QObject *parent = nullptr)
virtual ~QCamera()
QCameraDevice cameraDevice() const
QCameraFormat cameraFormat() const
QMediaCaptureSession *captureSession() const
int colorTemperature() const
QPointF customFocusPoint() const
QCamera::Error error() const
QString errorString() const
float exposureCompensation() const
QCamera::ExposureMode exposureMode() const
float exposureTime() const
QCamera::FlashMode flashMode() const
float focusDistance() const
QCamera::FocusMode focusMode() const
QPointF focusPoint() const
bool isActive() const
bool isAvailable() const
bool isExposureModeSupported(QCamera::ExposureMode mode) const
bool isFlashModeSupported(QCamera::FlashMode mode) const
bool isFlashReady() const
bool isFocusModeSupported(QCamera::FocusMode mode) const
bool isTorchModeSupported(QCamera::TorchMode mode) const
bool isWhiteBalanceModeSupported(QCamera::WhiteBalanceMode mode) const
int isoSensitivity() const
float manualExposureTime() const
int manualIsoSensitivity() const
float maximumExposureTime() const
int maximumIsoSensitivity() const
float maximumZoomFactor() const
float minimumExposureTime() const
int minimumIsoSensitivity() const
float minimumZoomFactor() const
void setCameraDevice(const QCameraDevice &cameraDevice)
void setCameraFormat(const QCameraFormat &format)
void setCustomFocusPoint(const QPointF &point)
void setFocusDistance(float d)
void setFocusMode(QCamera::FocusMode mode)
void setZoomFactor(float factor)
QCamera::Features supportedFeatures() const
QCamera::TorchMode torchMode() const
QCamera::WhiteBalanceMode whiteBalanceMode() const
float zoomFactor() const

Public Slots

void setActive(bool active)
void setAutoExposureTime()
void setAutoIsoSensitivity()
void setColorTemperature(int colorTemperature)
void setExposureCompensation(float ev)
void setExposureMode(QCamera::ExposureMode mode)
void setFlashMode(QCamera::FlashMode mode)
void setManualExposureTime(float seconds)
void setManualIsoSensitivity(int iso)
void setTorchMode(QCamera::TorchMode mode)
void setWhiteBalanceMode(QCamera::WhiteBalanceMode mode)
void start()
void stop()
void zoomTo(float factor, float rate)

Signals

void activeChanged(bool)
void cameraDeviceChanged()
void cameraFormatChanged()
void colorTemperatureChanged() const
void customFocusPointChanged()
void errorChanged()
void errorOccurred(QCamera::Error error, const QString &errorString)
void exposureCompensationChanged(float value)
void exposureModeChanged()
void exposureTimeChanged(float speed)
void flashModeChanged()
void flashReady(bool ready)
void focusDistanceChanged(float)
void focusModeChanged()
void focusPointChanged()
void isoSensitivityChanged(int value)
void manualExposureTimeChanged(float speed)
void manualIsoSensitivityChanged(int)
void maximumZoomFactorChanged(float)
void minimumZoomFactorChanged(float)
void supportedFeaturesChanged()
void torchModeChanged()
void whiteBalanceModeChanged() const
void zoomFactorChanged(float)

Detailed Description

QCamera can be used within a QMediaCaptureSession for video recording and image taking.

You can use QCameraDevice to list available cameras and choose which one to use.

const QList<QCameraDevice> cameras = QMediaDevices::videoInputs();
for (const QCameraDevice &cameraDevice : cameras) {
    if (cameraDevice.description() == "mycamera")
        camera = new QCamera(cameraDevice);
}

On hardware that supports it, QCamera lets you adjust the focus and zoom. This also includes functionality such as a "Macro" mode for close up work (e.g. reading barcodes, or recognizing letters), or "touch to focus" - indicating an interesting area of the image for the hardware to attempt to focus on.

camera->setFocusPointMode(QCamera::FocusModeManual);
camera->setCustomFocusPoint(QPointF(0.25f, 0.75f)); // A point near the bottom left, 25% away from the corner, near that shiny vase

The minimumZoomFactor() and maximumZoomFactor() methods provide the range of supported zoom factors. The zoomTo() method allows changing the zoom factor.

camera->setZoomFactor(3.0);

After capturing the raw data for a camera frame, the camera hardware and software performs various image processing tasks to produce the final image. This includes compensating for ambient light color, reducing noise, as well as making some other adjustments to the image.

You can control many of these processing steps through the Camera properties. For example, you can set the white balance (or color temperature) used for processing images:

camera->setWhiteBalanceMode(QCamera::WhiteBalanceFluorescent);

For more information on image processing of camera frames, see Camera Image Processing.

See the camera overview for more information.

Member Type Documentation

enum QCamera::Error

This enum holds the last error code.

ConstantValueDescription
QCamera::NoError0No errors have occurred.
QCamera::CameraError1An error has occurred.

enum QCamera::ExposureMode

ConstantValueDescription
QCamera::ExposureAuto0Automatic mode.
QCamera::ExposureManual1Manual mode.
QCamera::ExposurePortrait2Portrait exposure mode.
QCamera::ExposureNight3Night mode.
QCamera::ExposureSports4Spots exposure mode.
QCamera::ExposureSnow5Snow exposure mode.
QCamera::ExposureBeach6Beach exposure mode.
QCamera::ExposureAction7Action mode. Since 5.5
QCamera::ExposureLandscape8Landscape mode. Since 5.5
QCamera::ExposureNightPortrait9Night portrait mode. Since 5.5
QCamera::ExposureTheatre10Theatre mode. Since 5.5
QCamera::ExposureSunset11Sunset mode. Since 5.5
QCamera::ExposureSteadyPhoto12Steady photo mode. Since 5.5
QCamera::ExposureFireworks13Fireworks mode. Since 5.5
QCamera::ExposureParty14Party mode. Since 5.5
QCamera::ExposureCandlelight15Candlelight mode. Since 5.5
QCamera::ExposureBarcode16Barcode mode. Since 5.5

enum class QCamera::Feature
flags QCamera::Features

Describes a set of features supported by the camera. The returned value can be a combination of:

ConstantValueDescription
QCamera::Feature::ColorTemperature0x1The Camera supports setting a custom colorTemperature.
QCamera::Feature::ExposureCompensation0x2The Camera supports setting a custom exposureCompensation.
QCamera::Feature::IsoSensitivity0x4The Camera supports setting a custom isoSensitivity.
QCamera::Feature::ManualExposureTime0x8The Camera supports setting a manual exposure Time.
QCamera::Feature::CustomFocusPoint0x10The Camera supports setting a custom focus point.
QCamera::Feature::FocusDistance0x20The Camera supports setting the focusDistance property.

The Features type is a typedef for QFlags<Feature>. It stores an OR combination of Feature values.

enum QCamera::FlashMode

ConstantValueDescription
QCamera::FlashOff0Flash is Off.
QCamera::FlashOn1Flash is On.
QCamera::FlashAuto2Automatic flash.

enum QCamera::FocusMode

ConstantValueDescription
QCamera::FocusModeAuto0Continuous auto focus mode.
QCamera::FocusModeAutoNear1Continuous auto focus mode on near objects.
QCamera::FocusModeAutoFar2Continuous auto focus mode on objects far away.
QCamera::FocusModeHyperfocal3Focus to hyperfocal distance, with the maximum depth of field achieved. All objects at distances from half of this distance out to infinity will be acceptably sharp.
QCamera::FocusModeInfinity4Focus strictly to infinity.
QCamera::FocusModeManual5Manual or fixed focus mode.

enum QCamera::TorchMode

ConstantValueDescription
QCamera::TorchOff0Torch is Off.
QCamera::TorchOn1Torch is On.
QCamera::TorchAuto2Automatic torch.

enum QCamera::WhiteBalanceMode

ConstantValueDescription
QCamera::WhiteBalanceAuto0Auto white balance mode.
QCamera::WhiteBalanceManual1Manual white balance. In this mode the white balance should be set with setColorTemperature()
QCamera::WhiteBalanceSunlight2Sunlight white balance mode.
QCamera::WhiteBalanceCloudy3Cloudy white balance mode.
QCamera::WhiteBalanceShade4Shade white balance mode.
QCamera::WhiteBalanceTungsten5Tungsten (incandescent) white balance mode.
QCamera::WhiteBalanceFluorescent6Fluorescent white balance mode.
QCamera::WhiteBalanceFlash7Flash white balance mode.
QCamera::WhiteBalanceSunset8Sunset white balance mode.

Property Documentation

active : bool

Describes whether the camera is currently active.

Access functions:

bool isActive() const
void setActive(bool active)

Notifier signal:

void activeChanged(bool)

cameraDevice : QCameraDevice

Returns the QCameraDevice object associated with this camera.

Access functions:

QCameraDevice cameraDevice() const
void setCameraDevice(const QCameraDevice &cameraDevice)

Notifier signal:

void cameraDeviceChanged()

cameraFormat : QCameraFormat

Returns the camera format currently used by the camera.

Note: When using the FFMPEG backend on an Android target device if you request YUV420P format, you will receive either a fully planar 4:2:0 YUV420P or a semi-planar NV12/NV21. This depends on the codec implemented by the device OEM.

Access functions:

QCameraFormat cameraFormat() const
void setCameraFormat(const QCameraFormat &format)

Notifier signal:

void cameraFormatChanged()

See also QCameraDevice::videoFormats.

colorTemperature : int

Returns the current color temperature if the current white balance mode is WhiteBalanceManual. For other modes the return value is undefined.

Access functions:

int colorTemperature() const
void setColorTemperature(int colorTemperature)

Notifier signal:

void colorTemperatureChanged() const

customFocusPoint : QPointF

This property represents the position of the custom focus point, in relative frame coordinates: QPointF(0,0) points to the left top frame point, QPointF(0.5,0.5) points to the frame center.

The custom focus point property is used only in FocusPointCustom focus mode.

You can check whether custom focus points are supported by querying supportedFeatures() with the Feature.CustomFocusPoint flag.

Access functions:

QPointF customFocusPoint() const
void setCustomFocusPoint(const QPointF &point)

Notifier signal:

void customFocusPointChanged()

[read-only] error : const Error

Returns the error state of the camera.

Access functions:

QCamera::Error error() const

Notifier signal:

void errorChanged()

[read-only] errorString : const QString

Returns a human readable string describing a camera's error state.

Access functions:

QString errorString() const

Notifier signal:

void errorChanged()

exposureCompensation : float

Exposure compensation in EV units.

Exposure compensation property allows to adjust the automatically calculated exposure.

Access functions:

float exposureCompensation() const
void setExposureCompensation(float ev)

Notifier signal:

void exposureCompensationChanged(float value)

exposureMode : QCamera::ExposureMode

This property holds the exposure mode being used.

Access functions:

QCamera::ExposureMode exposureMode() const
void setExposureMode(QCamera::ExposureMode mode)

Notifier signal:

void exposureModeChanged()

See also QCamera::isExposureModeSupported.

[read-only] exposureTime : const float

Camera's exposure time in seconds.

Access functions:

float exposureTime() const

Notifier signal:

void exposureTimeChanged(float speed)

See also minimumExposureTime(), maximumExposureTime(), and setManualExposureTime().

flashMode : QCamera::FlashMode

This property holds the flash mode being used.

Enables a certain flash mode if the camera has a flash.

Access functions:

QCamera::FlashMode flashMode() const
void setFlashMode(QCamera::FlashMode mode)

Notifier signal:

void flashModeChanged()

See also QCamera::FlashMode, QCamera::isFlashModeSupported, and QCamera::isFlashReady.

[read-only] flashReady : const bool

Indicates if the flash is charged and ready to use.

Access functions:

bool isFlashReady() const[see note below]

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

Notifier signal:

void flashReady(bool ready)

focusDistance : float

This property return an approximate focus distance of the camera. The value reported is between 0 and 1, 0 being the closest possible focus distance, 1 being as far away as possible. Note that 1 is often, but not always infinity.

Setting the focus distance will be ignored unless the focus mode is set to FocusModeManual.

Access functions:

float focusDistance() const
void setFocusDistance(float d)

Notifier signal:

void focusDistanceChanged(float)

focusMode : FocusMode

This property holds the current camera focus mode.

Sets up different focus modes for the camera. All auto focus modes will focus continuously. Locking the focus is possible by setting the focus mode to FocusModeManual. This will keep the current focus and stop any automatic focusing.

Access functions:

QCamera::FocusMode focusMode() const
void setFocusMode(QCamera::FocusMode mode)

Notifier signal:

See also isFocusModeSupported.

[read-only] focusPoint : const QPointF

Returns the point currently used by the auto focus system to focus onto.

Access functions:

QPointF focusPoint() const

Notifier signal:

void focusPointChanged()

[read-only] isoSensitivity : const int

This property holds the sensor ISO sensitivity.

Describes the ISO sensitivity currently used by the camera.

Access functions:

int isoSensitivity() const

Notifier signal:

void isoSensitivityChanged(int value)

See also setAutoIsoSensitivity() and setManualIsoSensitivity().

manualExposureTime : int

Set the manual exposure time to seconds

Access functions:

float manualExposureTime() const
void setManualExposureTime(float seconds)

Notifier signal:

void manualExposureTimeChanged(float speed)

manualIsoSensitivity : int

Describes a manually set ISO sensitivity

Setting this property to -1 (the default), implies that the camera automatically adjusts the ISO sensitivity.

Access functions:

int manualIsoSensitivity() const
void setManualIsoSensitivity(int iso)

Notifier signal:

void manualIsoSensitivityChanged(int)

[read-only] maximumZoomFactor : const float

Returns the maximum zoom factor.

This will be 1.0 on cameras that do not support zooming.

Access functions:

float maximumZoomFactor() const

Notifier signal:

void maximumZoomFactorChanged(float)

[read-only] minimumZoomFactor : const float

Returns the minimum zoom factor.

This will be 1.0 on cameras that do not support zooming.

Access functions:

float minimumZoomFactor() const

Notifier signal:

void minimumZoomFactorChanged(float)

[read-only] supportedFeatures : const Features

Returns the features supported by this camera.

Access functions:

QCamera::Features supportedFeatures() const

Notifier signal:

void supportedFeaturesChanged()

See also QCamera::Feature.

torchMode : QCamera::TorchMode

This property holds the torch mode being used.

A torch is a continuous source of light. It can be used during video recording in low light conditions. Enabling torch mode will usually override any currently set flash mode.

Access functions:

QCamera::TorchMode torchMode() const
void setTorchMode(QCamera::TorchMode mode)

Notifier signal:

void torchModeChanged()

See also QCamera::TorchMode, QCamera::isTorchModeSupported, and QCamera::flashMode.

whiteBalanceMode : WhiteBalanceMode

Returns the white balance mode being used.

Access functions:

QCamera::WhiteBalanceMode whiteBalanceMode() const
void setWhiteBalanceMode(QCamera::WhiteBalanceMode mode)

Notifier signal:

void whiteBalanceModeChanged() const

zoomFactor : float

This property holds the current zoom factor.

Gets or sets the current zoom factor. Values will be clamped between minimumZoomFactor and maximumZoomFactor.

Access functions:

float zoomFactor() const
void setZoomFactor(float factor)

Notifier signal:

void zoomFactorChanged(float)

Member Function Documentation

[explicit] QCamera::QCamera(QObject *parent = nullptr)

Construct a QCamera with a parent.

Selects the default camera on the system if more than one camera is available.

[explicit] QCamera::QCamera(QCameraDevice::Position position, QObject *parent = nullptr)

Construct a QCamera which uses a hardware camera located a the specified position.

For example on a mobile phone it can be used to easily choose between front-facing and back-facing cameras.

If no camera is available at the specified position or if position is QCameraDevice::UnspecifiedPosition, the default camera is used.

[explicit] QCamera::QCamera(const QCameraDevice &cameraDevice, QObject *parent = nullptr)

Construct a QCamera from a camera description cameraDevice and parent.

[virtual noexcept] QCamera::~QCamera()

Destroys the camera object.

QMediaCaptureSession *QCamera::captureSession() const

Returns the capture session this camera is connected to, or a nullptr if the camera is not connected to a capture session.

use QMediaCaptureSession::setCamera() to connect the camera to a session.

[signal] void QCamera::errorOccurred(QCamera::Error error, const QString &errorString)

This signal is emitted when error state changes to error. A description of the error is provided as errorString.

[signal] void QCamera::exposureCompensationChanged(float value)

Signal emitted when the exposure compensation changes to value.

Note: Notifier signal for property exposureCompensation.

float QCamera::exposureTime() const

Returns the current exposure time in seconds.

Note: Getter function for property exposureTime.

[signal] void QCamera::exposureTimeChanged(float speed)

Signals that a camera's exposure speed has changed.

Note: Notifier signal for property exposureTime.

[signal] void QCamera::flashReady(bool ready)

Signal the flash ready status has changed.

Note: Notifier signal for property flashReady.

[signal] void QCamera::focusModeChanged()

Signals when the focusMode changes.

Note: Notifier signal for property focusMode.

bool QCamera::isActive() const

Returns true if the camera is currently active.

Note: Getter function for property active.

bool QCamera::isAvailable() const

Returns true if the camera can be used.

[invokable] bool QCamera::isExposureModeSupported(QCamera::ExposureMode mode) const

Returns true if the exposure mode is supported.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

[invokable] bool QCamera::isFlashModeSupported(QCamera::FlashMode mode) const

Returns true if the flash mode is supported.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

[invokable] bool QCamera::isFlashReady() const

Returns true if flash is charged.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

Note: Getter function for property flashReady.

[invokable] bool QCamera::isFocusModeSupported(QCamera::FocusMode mode) const

Returns true if the focus mode is supported by the camera.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

[invokable] bool QCamera::isTorchModeSupported(QCamera::TorchMode mode) const

Returns true if the torch mode is supported.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

[invokable] bool QCamera::isWhiteBalanceModeSupported(QCamera::WhiteBalanceMode mode) const

Returns true if the white balance mode is supported.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

[signal] void QCamera::isoSensitivityChanged(int value)

Signal emitted when sensitivity changes to value.

Note: Notifier signal for property isoSensitivity.

float QCamera::manualExposureTime() const

Returns the manual exposure time in seconds, or -1 if the camera is using automatic exposure times.

Note: Getter function for property manualExposureTime.

See also setManualExposureTime().

float QCamera::maximumExposureTime() const

The maximal exposure time in seconds.

int QCamera::maximumIsoSensitivity() const

Returns the maximum ISO sensitivity supported by the camera.

float QCamera::minimumExposureTime() const

The minimal exposure time in seconds.

int QCamera::minimumIsoSensitivity() const

Returns the minimum ISO sensitivity supported by the camera.

[slot] void QCamera::setActive(bool active)

Turns the camera on if active is true, or off if it's false.

Note: Setter function for property active.

See also isActive().

[slot] void QCamera::setAutoExposureTime()

Use automatically calculated exposure time

[slot] void QCamera::setAutoIsoSensitivity()

Turn on auto sensitivity

void QCamera::setCameraDevice(const QCameraDevice &cameraDevice)

Connects the camera object to the physical camera device described by cameraDevice. Using a default constructed QCameraDevice object as cameraDevice will connect the camera to the system default camera device.

Note: Setter function for property cameraDevice.

See also cameraDevice().

void QCamera::setCameraFormat(const QCameraFormat &format)

Tells the camera to use the format described by format. This can be used to define a specific resolution and frame rate to be used for recording and image capture.

Note: When using the FFMPEG backend on an Android target device if you request YUV420P format, you will receive either a fully planar 4:2:0 YUV420P or a semi-planar NV12/NV21. This depends on the codec implemented by the device OEM.

Note: Setter function for property cameraFormat.

See also cameraFormat().

[slot] void QCamera::setColorTemperature(int colorTemperature)

Sets manual white balance to colorTemperature. This is used when whiteBalanceMode() is set to WhiteBalanceManual. The units are Kelvin.

Setting a color temperature will only have an effect if WhiteBalanceManual is supported. In this case, setting a temperature greater 0 will automatically set the white balance mode to WhiteBalanceManual. Setting the temperature to 0 will reset the white balance mode to WhiteBalanceAuto.

Note: Setter function for property colorTemperature.

See also colorTemperature().

[slot] void QCamera::setWhiteBalanceMode(QCamera::WhiteBalanceMode mode)

Sets the white balance to mode.

Note: Setter function for property whiteBalanceMode.

See also whiteBalanceMode().

void QCamera::setZoomFactor(float factor)

Zooms to a zoom factor factor at a rate of 1 factor per second.

Note: Setter function for property zoomFactor.

See also zoomFactor().

[slot] void QCamera::start()

Starts the camera.

Same as setActive(true).

If the camera can't be started for some reason, the errorOccurred() signal is emitted.

[slot] void QCamera::stop()

Stops the camera. Same as setActive(false).

[slot] void QCamera::zoomTo(float factor, float rate)

Zooms to a zoom factor factor using rate.

The rate is specified in powers of two per second. At a rate of 1 it would take 2 seconds to go from a zoom factor of 1 to 4.

Note: Using a specific rate is not supported on all cameras. If not supported, zooming will happen as fast as possible.

© 2024 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.