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 |
Inherits: | QObject |
Public Types
enum | Error { NoError, CameraError } |
enum | ExposureMode { ExposureAuto, ExposureManual, ExposurePortrait, ExposureNight, ExposureSports, …, ExposureBarcode } |
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(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 |
qreal | 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 |
float | maximumExposureTime() const |
float | maximumZoomFactor() const |
float | minimumExposureTime() 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(qreal 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(qreal value) |
void | exposureModeChanged() |
void | exposureTimeChanged(float speed) |
void | flashModeChanged() |
void | flashReady(bool ready) |
void | focusDistanceChanged(float) |
void | isoSensitivityChanged(int value) |
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 things like "Macro" mode for close up work (e.g. reading barcodes, or recognising letters), or "touch to focus" - indicating an interesting area of the viewfinder 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 allows checking the range of allowed zoom factors. The zoomTo() method allows changing the zoom factor.
camera->setZoomFactor(3.0);
After capturing the data for a camera frame, the camera hardware and software performs various image processing tasks to produce a final image. This includes compensating for ambient light color, reducing noise, as well as making some other adjustments to the image.
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 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. |
Property Documentation
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.
Access functions:
QPointF | customFocusPoint() const |
void | setCustomFocusPoint(const QPointF &point) |
Notifier signal:
void | customFocusPointChanged() |
exposureCompensation : qreal
Exposure compensation in EV units.
Exposure compensation property allows to adjust the automatically calculated exposure.
Access functions:
qreal | exposureCompensation() const |
void | setExposureCompensation(qreal ev) |
Notifier signal:
void | exposureCompensationChanged(qreal 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 qreal
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::isFlashModeSupported() and QCamera::isFlashReady().
[read-only]
flashReady : const bool
Indicates if the flash is charged and ready to use.
Access functions:
bool | isFlashReady() const |
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) |
See also QCamera::isFocusModeSupported().
[read-only]
isoSensitivity : const int
This property holds the sensor ISO sensitivity.
Access functions:
int | isoSensitivity() const |
Notifier signal:
void | isoSensitivityChanged(int value) |
See also supportedIsoSensitivities(), setAutoIsoSensitivity(), and setManualIsoSensitivity().
torchMode : QCamera::TorchMode
This property holds the torch mode being used.
A torch is a continuous light source used for low light video recording. 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::isTorchModeSupported() and QCamera::flashMode.
zoomFactor : float
This property holds the current zoom factor.
Access functions:
float | zoomFactor() const |
void | setZoomFactor(float factor) |
Notifier signal:
void | zoomFactorChanged(float) |
Member Function Documentation
[since 5.3]
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.
This function was introduced in Qt 5.3.
[since 5.3]
QCamera::QCamera(const QCameraDevice &cameraDevice, QObject *parent = nullptr)
Construct a QCamera from a camera description cameraDevice and parent.
This function was introduced in Qt 5.3.
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(qreal 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 time 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 or off.
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
See also manualExposureTime().
[slot]
void QCamera::setManualIsoSensitivity(int iso)
Sets the manual sensitivity to iso
[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.
See also unload().
[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. A rate of 1 would take two seconds to zoom from a zoom factor of 1 to a zoom factor of 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().
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 object.
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.
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.
bool QCamera::isExposureModeSupported(QCamera::ExposureMode mode) const
Returns true if the exposure mode is supported.
bool QCamera::isFlashModeSupported(QCamera::FlashMode mode) const
Returns true if the flash mode is supported.
bool QCamera::isFlashReady() const
Returns true if flash is charged.
Note: Getter function for property flashReady.
bool QCamera::isFocusModeSupported(QCamera::FocusMode mode) const
Returns true if the focus mode is supported by camera.
bool QCamera::isTorchModeSupported(QCamera::TorchMode mode) const
Returns true if the torch mode is supported.
[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.
See also setManualExposureTime().
float QCamera::maximumExposureTime() const
The maximal exposure time in seconds.
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.
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)
Sets the camera object to use the physical camera described by cameraDevice.
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 as specific resolution and frame rate to be used for recording and image capture.
Note: Setter function for property cameraFormat.
See also cameraFormat().
QCamera::WhiteBalanceMode QCamera::whiteBalanceMode() const
Returns the white balance mode being used.
Note: Getter function for property whiteBalanceMode.
See also setWhiteBalanceMode().