QCamera Class

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

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

• List of all members, including inherited members

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

active : bool customFocusPoint : QPointF exposureCompensation : float exposureMode : QCamera::ExposureMode exposureTime : const float flashMode : QCamera::FlashMode flashReady : const bool

focusDistance : float focusMode : FocusMode isoSensitivity : const int manualIsoSensitivity : int torchMode : QCamera::TorchMode zoomFactor : float

Public Functions

	QCamera(QCameraDevice::Position position, QObject *parent = nullptr)
	QCamera(const QCameraDevice &cameraDevice, QObject *parent = nullptr)
	QCamera(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	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.

Constant	Value	Description
QCamera::NoError	0	No errors have occurred.
QCamera::CameraError	1	An error has occurred.

enum QCamera::ExposureMode

Constant	Value	Description
QCamera::ExposureAuto	0	Automatic mode.
QCamera::ExposureManual	1	Manual mode.
QCamera::ExposurePortrait	2	Portrait exposure mode.
QCamera::ExposureNight	3	Night mode.
QCamera::ExposureSports	4	Spots exposure mode.
QCamera::ExposureSnow	5	Snow exposure mode.
QCamera::ExposureBeach	6	Beach exposure mode.
QCamera::ExposureAction	7	Action mode. Since 5.5
QCamera::ExposureLandscape	8	Landscape mode. Since 5.5
QCamera::ExposureNightPortrait	9	Night portrait mode. Since 5.5
QCamera::ExposureTheatre	10	Theatre mode. Since 5.5
QCamera::ExposureSunset	11	Sunset mode. Since 5.5
QCamera::ExposureSteadyPhoto	12	Steady photo mode. Since 5.5
QCamera::ExposureFireworks	13	Fireworks mode. Since 5.5
QCamera::ExposureParty	14	Party mode. Since 5.5
QCamera::ExposureCandlelight	15	Candlelight mode. Since 5.5
QCamera::ExposureBarcode	16	Barcode mode. Since 5.5

enum class QCamera::Featureflags QCamera::Features

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

Constant	Value	Description
QCamera::Feature::ColorTemperature	0x1	The Camera supports setting a custom colorTemperature.
QCamera::Feature::ExposureCompensation	0x2	The Camera supports setting a custom exposureCompensation.
QCamera::Feature::IsoSensitivity	0x4	The Camera supports setting a custom isoSensitivity.
QCamera::Feature::ManualExposureTime	0x8	The Camera supports setting a manual exposure Time.
QCamera::Feature::CustomFocusPoint	0x10	The Camera supports setting a custom focus point.
QCamera::Feature::FocusDistance	0x20	The 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

Constant	Value	Description
QCamera::FlashOff	0	Flash is Off.
QCamera::FlashOn	1	Flash is On.
QCamera::FlashAuto	2	Automatic flash.

enum QCamera::FocusMode

Constant	Value	Description
QCamera::FocusModeAuto	0	Continuous auto focus mode.
QCamera::FocusModeAutoNear	1	Continuous auto focus mode on near objects.
QCamera::FocusModeAutoFar	2	Continuous auto focus mode on objects far away.
QCamera::FocusModeHyperfocal	3	Focus 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::FocusModeInfinity	4	Focus strictly to infinity.
QCamera::FocusModeManual	5	Manual or fixed focus mode.

enum QCamera::TorchMode

Constant	Value	Description
QCamera::TorchOff	0	Torch is Off.
QCamera::TorchOn	1	Torch is On.
QCamera::TorchAuto	2	Automatic torch.

enum QCamera::WhiteBalanceMode

Constant	Value	Description
QCamera::WhiteBalanceAuto	0	Auto white balance mode.
QCamera::WhiteBalanceManual	1	Manual white balance. In this mode the white balance should be set with setColorTemperature()
QCamera::WhiteBalanceSunlight	2	Sunlight white balance mode.
QCamera::WhiteBalanceCloudy	3	Cloudy white balance mode.
QCamera::WhiteBalanceShade	4	Shade white balance mode.
QCamera::WhiteBalanceTungsten	5	Tungsten (incandescent) white balance mode.
QCamera::WhiteBalanceFluorescent	6	Fluorescent white balance mode.
QCamera::WhiteBalanceFlash	7	Flash white balance mode.
QCamera::WhiteBalanceSunset	8	Sunset white balance mode.

Member Function Documentation

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.

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

Construct a QCamera from a camera description cameraDevice and parent.

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.

[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.

[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::isoSensitivityChanged(int value)

Signal emitted when sensitivity changes to value.

Note: Notifier signal for property isoSensitivity.

[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

[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::setManualExposureTime(float seconds)

Set the manual exposure time to seconds

Note: Setter function for property manualExposureTime.

See also manualExposureTime().

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

Sets the white balance to mode.

Note: Setter function for property whiteBalanceMode.

See also whiteBalanceMode().

[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.

[virtual] QCamera::~QCamera()

Destroys the camera object.

QCameraDevice QCamera::cameraDevice() const

Returns the QCameraDevice object associated with this camera.

Note: Getter function for property cameraDevice.

See also setCameraDevice().

QCameraFormat QCamera::cameraFormat() const

Returns the camera format currently used by the camera.

Note: Getter function for property cameraFormat.

See also setCameraFormat() and QCameraDevice::videoFormats.

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.

int QCamera::colorTemperature() const

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

Note: Getter function for property colorTemperature.

See also setColorTemperature().

QCamera::Error QCamera::error() const

Returns the error state of the camera.

Note: Getter function for property error.

QString QCamera::errorString() const

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

Note: Getter function for property errorString.

float QCamera::exposureTime() const

Returns the current exposure time in seconds.

Note: Getter function for property exposureTime.

QPointF QCamera::focusPoint() const

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

Note: Getter function for property focusPoint.

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.

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::maximumZoomFactor() const

Returns the maximum zoom factor.

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

Note: Getter function for property maximumZoomFactor.

float QCamera::minimumExposureTime() const

The minimal exposure time in seconds.

int QCamera::minimumIsoSensitivity() const

Returns the minimum ISO sensitivity supported by the camera.

float QCamera::minimumZoomFactor() const

Returns the minimum zoom factor.

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

Note: Getter function for property minimumZoomFactor.

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 desribed by format. This can be used to define as specific resolution and frame rate to be used for recording and image capture.

Note: Setter function for property cameraFormat.

See also cameraFormat().

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

QCamera::Features QCamera::supportedFeatures() const

Returns the features supported by this camera.

Note: Getter function for property supportedFeatures.

See also QCamera::Feature.

QCamera::WhiteBalanceMode QCamera::whiteBalanceMode() const

Returns the white balance mode being used.

Note: Getter function for property whiteBalanceMode.

See also setWhiteBalanceMode().