QCamera Class

Member Function Documentation

QCamera::QCamera(QCamera::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 QCamera::UnspecifiedPosition, the default camera is used.

This function was introduced in Qt 5.3.

QCamera::QCamera(const QCameraInfo &cameraInfo, QObject *parent = nullptr)

Construct a QCamera from a camera description cameraInfo and parent.

This function was introduced in Qt 5.3.

QCamera::QCamera(const QByteArray &deviceName, QObject *parent = nullptr)

Construct a QCamera from deviceName and parent.

If no camera with that deviceName exists, the camera object will be invalid.

QCamera::QCamera(QObject *parent = nullptr)

Construct a QCamera with a parent.

[signal] void QCamera::captureModeChanged(QCamera::CaptureModes mode)

Signals the capture mode has changed.

Note: Notifier signal for property captureMode.

[signal] void QCamera::errorOccurred(QCamera::Error value)

Signal emitted when error state changes to value.

This function was introduced in Qt 5.15.

[slot] void QCamera::load()

Opens the camera device. The camera state is changed to QCamera::LoadedState.

It's not necessary to explicitly load the camera, unless the application needs to read the supported camera settings and change the default values according to the camera capabilities.

In all the other cases, it's possible to start the camera directly from the unloaded state.

/sa QCamera::UnloadedState

[signal] void QCamera::lockFailed()

Signals locking of at least one requested camera settings failed.

[signal] void QCamera::lockStatusChanged(QCamera::LockType lock, QCamera::LockStatus status, QCamera::LockChangeReason reason)

Signals the lock status was changed with specified reason.

Note: Notifier signal for property lockStatus.

Note: Signal lockStatusChanged is overloaded in this class. To connect to this signal by using the function pointer syntax, Qt provides a convenient helper for obtaining the function pointer as shown in this example:

connect(camera, QOverload<QCamera::LockType, QCamera::LockStatus, QCamera::LockChangeReason>::of(&QCamera::lockStatusChanged),
    [=](QCamera::LockType lock, QCamera::LockStatus status, QCamera::LockChangeReason reason){ /* ... */ });

[signal] void QCamera::lockStatusChanged(QCamera::LockStatus status, QCamera::LockChangeReason reason)

Signals the overall status for all the requested camera locks was changed with specified reason.

Note: Notifier signal for property lockStatus.

Note: Signal lockStatusChanged is overloaded in this class. To connect to this signal by using the function pointer syntax, Qt provides a convenient helper for obtaining the function pointer as shown in this example:

connect(camera, QOverload<QCamera::LockStatus, QCamera::LockChangeReason>::of(&QCamera::lockStatusChanged),
    [=](QCamera::LockStatus status, QCamera::LockChangeReason reason){ /* ... */ });

[signal] void QCamera::locked()

Signals all the requested camera settings are locked.

[slot] void QCamera::searchAndLock(QCamera::LockTypes locks)

Locks the camera settings with the requested locks, including focusing in the single autofocus mode, exposure and white balance if the exposure and white balance modes are not manual.

The camera settings are usually locked before taking one or multiple still images, in responce to the shutter button being half pressed.

The QCamera::locked() signal is emitted when camera settings are successfully locked, otherwise QCamera::lockFailed() is emitted.

QCamera also emits lockStatusChanged(QCamera::LockType, QCamera::LockStatus) on individual lock status changes and lockStatusChanged(QCamera::LockStatus) signal on composite status changes.

Locking serves two roles: it initializes calculation of automatic parameter (focusing, calculating the correct exposure and white balance) and allows to keep some or all of those parameters during number of shots.

If the camera doesn't support keeping one of parameters between shots, the related lock state changes to QCamera::Unlocked.

It's also acceptable to relock already locked settings, depending on the lock parameter this initiates new focusing, exposure or white balance calculation.

[slot] void QCamera::searchAndLock()

Lock all the supported camera settings.

[slot] void QCamera::start()

Starts the camera.

State is changed to QCamera::ActiveState if camera is started successfully, otherwise errorOccurred() signal is emitted.

While the camera state is changed to QCamera::ActiveState, starting the camera service can be asynchronous with the actual status reported with QCamera::status property.

[signal] void QCamera::stateChanged(QCamera::State state)

Signals the camera state has changed.

Usually the state changes is caused by calling load(), unload(), start() and stop(), but the state can also be changed change as a result of camera error.

Note: Notifier signal for property state.

[signal] void QCamera::statusChanged(QCamera::Status status)

Signals the camera status has changed.

Note: Notifier signal for property status.

[slot] void QCamera::stop()

Stops the camera. The camera state is changed from QCamera::ActiveState to QCamera::LoadedState.

In this state, the camera still consumes power.

See also unload() and QCamera::UnloadedState.

[slot] void QCamera::unload()

Closes the camera device and deallocates the related resources. The camera state is changed to QCamera::UnloadedState.

[slot] void QCamera::unlock(QCamera::LockTypes locks)

Unlocks the camera settings specified with locks or cancel the current locking if one is active.

[slot] void QCamera::unlock()

Unlock all the requested camera locks.

[virtual] QCamera::~QCamera()

Destroys the camera object.

[override virtual] QMultimedia::AvailabilityStatus QCamera::availability() const

Reimplements: QMediaObject::availability() const.

Returns the availability state of the camera service.

QCamera::Error QCamera::error() const

Returns the error state of the object.

QString QCamera::errorString() const

Returns a string describing a camera's error state.

QCameraExposure *QCamera::exposure() const

Returns the camera exposure control object.

QCameraFocus *QCamera::focus() const

Returns the camera focus control object.

QCameraImageProcessing *QCamera::imageProcessing() const

Returns the camera image processing control object.

bool QCamera::isCaptureModeSupported(QCamera::CaptureModes mode) const

Returns true if the capture mode is suported.

QCamera::LockStatus QCamera::lockStatus() const

Returns the status of requested camera settings locks.

Note: Getter function for property lockStatus.

QCamera::LockStatus QCamera::lockStatus(QCamera::LockType lockType) const

Returns the lock status for a given lockType.

Note: Getter function for property lockStatus.

QCamera::LockTypes QCamera::requestedLocks() const

Returns the requested lock types.

void QCamera::setViewfinder(QVideoWidget *viewfinder)

Sets the QVideoWidget based camera viewfinder. The previously set viewfinder is detached.

void QCamera::setViewfinder(QGraphicsVideoItem *viewfinder)

Sets the QGraphicsVideoItem based camera viewfinder. The previously set viewfinder is detached.

void QCamera::setViewfinder(QAbstractVideoSurface *surface)

Sets a video surface as the viewfinder of a camera.

If a viewfinder has already been set on the camera the new surface will replace it.

void QCamera::setViewfinderSettings(const QCameraViewfinderSettings &settings)

Sets the viewfinder settings.

If some parameters are not specified, or null settings are passed, the camera will choose default values.

If the camera is used to capture videos or images, the viewfinder settings might be ignored if they conflict with the capture settings. You can check the actual viewfinder settings once the camera is in the QCamera::ActiveStatus status.

Changing the viewfinder settings while the camera is in the QCamera::ActiveState state may cause the camera to be restarted.

This function was introduced in Qt 5.5.

See also viewfinderSettings(), supportedViewfinderResolutions(), supportedViewfinderFrameRateRanges(), and supportedViewfinderPixelFormats().

QCamera::LockTypes QCamera::supportedLocks() const

Returns the lock types that the camera supports.

QList<QCamera::FrameRateRange> QCamera::supportedViewfinderFrameRateRanges(const QCameraViewfinderSettings &settings = QCameraViewfinderSettings()) const

Returns a list of supported viewfinder frame rate ranges.

This is a convenience function which retrieves unique frame rate ranges from the supported settings.

If non null viewfinder settings are passed, the returned list is reduced to frame rate ranges supported with partial settings applied.

The camera must be loaded before calling this function, otherwise the returned list is empty.

This function was introduced in Qt 5.5.

See also QCameraViewfinderSettings::minimumFrameRate(), QCameraViewfinderSettings::maximumFrameRate(), and setViewfinderSettings().

QList<QVideoFrame::PixelFormat> QCamera::supportedViewfinderPixelFormats(const QCameraViewfinderSettings &settings = QCameraViewfinderSettings()) const

Returns a list of supported viewfinder pixel formats.

This is a convenience function which retrieves unique pixel formats from the supported settings.

If non null viewfinder settings are passed, the returned list is reduced to pixel formats supported with partial settings applied.

The camera must be loaded before calling this function, otherwise the returned list is empty.

This function was introduced in Qt 5.5.

See also QCameraViewfinderSettings::pixelFormat() and setViewfinderSettings().

QList<QSize> QCamera::supportedViewfinderResolutions(const QCameraViewfinderSettings &settings = QCameraViewfinderSettings()) const

Returns a list of supported viewfinder resolutions.

This is a convenience function which retrieves unique resolutions from the supported settings.

If non null viewfinder settings are passed, the returned list is reduced to resolutions supported with partial settings applied.

The camera must be loaded before calling this function, otherwise the returned list is empty.

This function was introduced in Qt 5.5.

See also QCameraViewfinderSettings::resolution() and setViewfinderSettings().

QList<QCameraViewfinderSettings> QCamera::supportedViewfinderSettings(const QCameraViewfinderSettings &settings = QCameraViewfinderSettings()) const

Returns a list of supported viewfinder settings.

The list is ordered by preference; preferred settings come first.

The optional settings argument can be used to conveniently filter the results. If settings is non null, the returned list is reduced to settings matching the given partial settings.

The status of the camera must be LoadedStatus before calling this function, otherwise the returned list is empty.

This function was introduced in Qt 5.5.

See also setViewfinderSettings(), supportedViewfinderResolutions(), supportedViewfinderFrameRateRanges(), and supportedViewfinderPixelFormats().

QCameraViewfinderSettings QCamera::viewfinderSettings() const

Returns the viewfinder settings being used by the camera.

Settings may change when the camera is started, for example if the viewfinder settings are undefined or if unsupported values are set.

If viewfinder settings are not supported by the camera, it always returns a null QCameraViewfinderSettings object.

This function was introduced in Qt 5.5.

See also setViewfinderSettings().