CopperSpice API  1.9.1
QCamera Class Reference

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

Inheritance diagram for QCamera:
QMediaObject QObject

Classes

class  FrameRateRange
 Represents a range of frame rates as minimum and maximum rate More...
 

Public Typedefs

using CaptureModes = QFlags< CaptureMode >
 
using LockTypes = QFlags< LockType >
 

Public Types

enum  CaptureMode
 
enum  Error
 
enum  LockChangeReason
 
enum  LockStatus
 
enum  LockType
 
enum  Position
 
enum  State
 
enum  Status
 

Public Signals

void captureModeChanged (QCamera::CaptureModes mode)
 
void error (QCamera::Error error)
 
void locked ()
 
void lockFailed ()
 
void lockStatusChanged (QCamera::LockStatus status, QCamera::LockChangeReason reason)
 
void lockStatusChanged (QCamera::LockType type, QCamera::LockStatus status, QCamera::LockChangeReason reason)
 
void stateChanged (QCamera::State state)
 
void statusChanged (QCamera::Status status)
 
- Public Signals inherited from QMediaObject
void availabilityChanged (bool available)
 
void availabilityChanged (QMultimedia::AvailabilityStatus availability)
 
void metaDataAvailableChanged (bool available)
 
void metaDataChanged ()
 
void metaDataChanged (const QString &key, const QVariant &value)
 
void notifyIntervalChanged (int milliSeconds)
 
- Public Signals inherited from QObject
void destroyed (QObject *obj=nullptr)
 
void objectNameChanged (const QString &objectName)
 

Public Slots

void load ()
 
void searchAndLock ()
 
void searchAndLock (QCamera::LockTypes locks)
 
void setCaptureMode (QCamera::CaptureModes mode)
 
void start ()
 
void stop ()
 
void unload ()
 
void unlock ()
 
void unlock (QCamera::LockTypes locks)
 
- Public Slots inherited from QObject
void deleteLater ()
 

Public Methods

 QCamera (const QByteArray &deviceName, QObject *parent=nullptr)
 
 QCamera (const QCameraInfo &cameraInfo, QObject *parent=nullptr)
 
 QCamera (QCamera::Position position, QObject *parent=nullptr)
 
 QCamera (QObject *parent=nullptr)
 
 ~QCamera ()
 
QMultimedia::AvailabilityStatus availability () const override
 
CaptureModes captureMode () const
 
QCamera::Error error () const
 
QString errorString () const
 
QCameraExposureexposure () const
 
QCameraFocusfocus () const
 
QCameraImageProcessingimageProcessing () const
 
bool isCaptureModeSupported (CaptureModes mode) const
 
QCamera::LockStatus lockStatus () const
 
QCamera::LockStatus lockStatus (QCamera::LockType lockType) const
 
QCamera::LockTypes requestedLocks () const
 
void setViewfinder (QAbstractVideoSurface *surface)
 
void setViewfinder (QGraphicsVideoItem *viewfinder)
 
void setViewfinder (QVideoWidget *viewfinder)
 
void setViewfinderSettings (const QCameraViewfinderSettings &settings)
 
State state () const
 
Status status () const
 
QCamera::LockTypes supportedLocks () const
 
QList< FrameRateRangesupportedViewfinderFrameRateRanges (const QCameraViewfinderSettings &settings=QCameraViewfinderSettings ()) const
 
QList< QVideoFrame::PixelFormatsupportedViewfinderPixelFormats (const QCameraViewfinderSettings &settings=QCameraViewfinderSettings ()) const
 
QList< QSizesupportedViewfinderResolutions (const QCameraViewfinderSettings &settings=QCameraViewfinderSettings ()) const
 
QList< QCameraViewfinderSettingssupportedViewfinderSettings (const QCameraViewfinderSettings &settings=QCameraViewfinderSettings ()) const
 
QCameraViewfinderSettings viewfinderSettings () const
 
- Public Methods inherited from QMediaObject
 ~QMediaObject ()
 
QStringList availableMetaData () const
 
virtual bool bind (QObject *object)
 
virtual bool isAvailable () const
 
bool isMetaDataAvailable () const
 
QVariant metaData (const QString &key) const
 
int notifyInterval () const
 
virtual QMediaServiceservice () const
 
void setNotifyInterval (int milliSeconds)
 
virtual void unbind (QObject *object)
 
- Public Methods inherited from QObject
 QObject (QObject *parent=nullptr)
 
 ~QObject ()
 
bool blockSignals (bool block)
 
const QList< QObject * > & children () const
 
bool connect (const QObject *sender, const QString &signalMethod, const QString &location, const QString &slotMethod, Qt::ConnectionType type=Qt::AutoConnection)
 
bool connect (const QObject *sender, const QString &signalMethod, const QString &slotMethod, Qt::ConnectionType type=Qt::AutoConnection)
 
bool disconnect (const QObject *receiver, const QString &slotMethod=QString ()) const
 
bool disconnect (const QString &signalMethod, const QString &location, const QObject *receiver=nullptr, const QString &slotMethod=QString ()) const
 
bool disconnect (const QString &signalMethod=QString (), const QObject *receiver=nullptr, const QString &slotMethod=QString ()) const
 
void dumpObjectInfo ()
 
void dumpObjectTree ()
 
QList< QStringdynamicPropertyNames () const
 
virtual bool event (QEvent *event)
 
virtual bool eventFilter (QObject *watched, QEvent *event)
 
template<typename T >
findChild (const QString &childName=QString ()) const
 
template<class T >
QList< T > findChildren (const QRegularExpression &regExp, Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
 
template<class T >
QList< T > findChildren (const QString &childName=QString (), Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
 
bool inherits (const QString &className) const
 
void installEventFilter (QObject *filterObj)
 
bool isWidgetType () const
 
bool isWindowType () const
 
void killTimer (int id)
 
const QMetaObjectmetaObject () const
 
void moveToThread (QThread *targetThread)
 
QString objectName () const
 
QObject * parent () const
 
template<class T = QVariant>
property (const QString &name) const
 
void removeEventFilter (QObject *obj)
 
void setObjectName (const QString &name)
 
void setParent (QObject *parent)
 
bool setProperty (const QString &name, const QVariant &value)
 
bool signalsBlocked () const
 
int startTimer (int interval, Qt::TimerType timerType=Qt::CoarseTimer)
 
QThreadthread () const
 

Properties

 captureMode
 
 lockStatus
 
 state
 
 status
 
- Properties inherited from QMediaObject
 notifyInterval
 
- Properties inherited from QObject
 objectName
 

Friends

class QCameraInfo
 

Additional Inherited Members

- Static Public Methods inherited from QObject
static bool connect (const QObject *sender, const QMetaMethod &signalMethod, const QObject *receiver, const QMetaMethod &slotMethod, Qt::ConnectionType type=Qt::AutoConnection)
 
static bool connect (const QObject *sender, const QString &signalMethod, const QObject *receiver, const QString &slotMethod, Qt::ConnectionType type=Qt::AutoConnection, const QString &location=QString ())
 
static bool connect (const QObject *sender, const QString &signalMethod, const QString &location, const QObject *receiver, const QString &slotMethod, Qt::ConnectionType type=Qt::AutoConnection)
 
template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class SlotClass , class... SlotArgs, class SlotReturn >
static bool connect (const Sender *sender, void (SignalClass::*signalMethod)(SignalArgs...), const Receiver *receiver, SlotReturn (SlotClass::*slotMethod)(SlotArgs...), Qt::ConnectionType type=Qt::AutoConnection)
 
template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class T >
static bool connect (const Sender *sender, void (SignalClass::*signalMethod)(SignalArgs...), const Receiver *receiver, T slotLambda, Qt::ConnectionType type=Qt::AutoConnection)
 
static bool disconnect (const QObject *sender, const QMetaMethod &signalMethod, const QObject *receiver, const QMetaMethod &slotMethod)
 
static bool disconnect (const QObject *sender, const QString &signalMethod, const QObject *receiver, const QString &slotMethod)
 
static bool disconnect (const QObject *sender, const QString &signalMethod, const QString &location, const QObject *receiver, const QString &slotMethod)
 
static bool disconnect (const QObject *sender, std::nullptr_t, const QObject *receiver, std::nullptr_t)
 
template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class SlotClass , class... SlotArgs, class SlotReturn >
static bool disconnect (const Sender *sender, void (SignalClass::*signalMethod)(SignalArgs...), const Receiver *receiver, SlotReturn (SlotClass::*slotMethod)(SlotArgs...))
 
template<class Sender , class SignalClass , class... SignalArgs, class Receiver >
static bool disconnect (const Sender *sender, void (SignalClass::*signalMethod)(SignalArgs...), const Receiver *receiver, std::nullptr_t slotMethod=nullptr)
 
template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class T >
static bool disconnect (const Sender *sender, void (SignalClass::*signalMethod)(SignalArgs...), const Receiver *receiver, T slotMethod)
 
static QMetaObjectstaticMetaObject ()
 
static QString tr (const char *text, const char *comment=nullptr, std::optional< int > numArg=std::optional< int >())
 
- Protected Methods inherited from QMediaObject
 QMediaObject (QObject *parent, QMediaService *service)
 
template<typename T >
void addPropertyWatch (const QString &name)
 
void removePropertyWatch (const QString &name)
 
- Protected Methods inherited from QObject
virtual void childEvent (QChildEvent *event)
 
virtual void connectNotify (const QMetaMethod &signalMethod) const
 
virtual void customEvent (QEvent *event)
 
virtual void disconnectNotify (const QMetaMethod &signalMethod) const
 
bool isSignalConnected (const QMetaMethod &signalMethod) const
 
int receivers (const QString &signal) const
 
QObject * sender () const
 
int senderSignalIndex () const
 
virtual void timerEvent (QTimerEvent *event)
 

Detailed Description

The QCamera class provides an interface for system camera devices. QCamera can be used with QCameraViewfinder for viewfinder display, QMediaRecorder for video recording, and QCameraImageCapture for image taking.

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

for (const QCameraInfo &cameraInfo : cameras) {
if (cameraInfo.deviceName() == "mycamera") {
camera = new QCamera(cameraInfo);
}
}

Member Typedef Documentation

Typedef for QFlags<CaptureMode>. Refer to QCamera::CaptureMode for documentation.

Typedef for QFlags<LockType>. Refer to QCamera::LockType for documentation.

Member Enumeration Documentation

Enum containing camera capture modes.

Constant Value Description
QCamera::CaptureViewfinder 0 Camera is only configured to display viewfinder.
QCamera::CaptureStillImage 0x01 Camera is configured for still frames capture.
QCamera::CaptureVideo 0x02 Camera is configured for video capture.

Error codes.

Constant Value Description
QCamera::NoError 0 No errors have occurred.
QCamera::CameraError 1 An error has occurred.
QCamera::InvalidRequestError 2 System resource does not support requested functionality.
QCamera::ServiceMissingError 3 No camera service available.
QCamera::NotSupportedFeatureError 4 Feature is not supported.

Enum containing reasons a lock status has changed.

Constant Value Description
QCamera::UserRequest 0 Lock status changed in result of user request, usually to unlock camera settings.
QCamera::LockAcquired 1 Lock status successfully changed to QCamera::Locked.
QCamera::LockFailed 2 Camera failed to acquire the requested lock in result of autofocus failure, exposure out of supported range, etc.
QCamera::LockLost 3 Camera is not able to maintain the requested lock any more. Lock status is changed to QCamera::Unlocked.
QCamera::LockTemporaryLost 4 Lock is lost but the camera is working to reacquire it. This value may be used in continuous focusing mode, when the camera loses the focus, the focus lock state is changed to QCamera::Searching with LockTemporaryLost reason.

Enum contains values indicating the status of the camera setting.

Constant Value Description
QCamera::Unlocked 0 Application is not interested in camera settings value.
QCamera::Searching 1 Application has requested the camera focus, exposure, or white balance lock with QCamera::searchAndLock(). This state indicates the camera is focusing or calculating exposure and white balance.
QCamera::Locked 2 Camera focus, exposure, or white balance is locked. The camera is ready to capture.

Used to specify a camera setting indicating how the camera should focus.

Constant Value Description
QCamera::NoLock 0
QCamera::LockExposure 0x01 Lock camera exposure.
QCamera::LockWhiteBalance 0x02 Lock the white balance.
QCamera::LockFocus 0x04 Lock camera focus.

This enum specifies the physical position of the camera on the system.

Constant Value Description
QCamera::UnspecifiedPosition 0 Camera position is unspecified or unknown.
QCamera::BackFace 1 Camera is on the back face of the system hardware. For example on a mobile device, it means it is on the opposite side to that of the screen.
QCamera::FrontFace 2 Camera is on the front face of the system hardware. For example on a mobile device, it means it is on the same side as that of the screen. Viewfinder frames of front-facing cameras are mirrored horizontally, so the users can see themselves as looking into a mirror. Captured images or videos are not mirrored.
See also
QCameraInfo::position()

Specifies the current state of the camera.

Constant Value Description
Camera::UnloadedState 0 Initial state with the camera not loaded. While the supported settings are unknown in this state, you can set the camera capture settings like codec, resolution, or frame rate.
QCamera::LoadedState 1 Camera is loaded and ready to be configured.
QCamera::ActiveState 2 When the camera is started the viewfinder displays video frames and the camera is ready for capture.

Enum contains camera status information.

Depending on which backend is used, changing some of the camera settings like capture mode, codecs, or resolution in the ActiveState may change the camera status.

Constant Value Description
QCamera::ActiveStatus 8 Camera has been started and can produce data. The viewfinder displays video frames in active state.
QCamera::StartingStatus 6 Camera is starting in result of state transition to QCamera::ActiveState. The camera service is not ready to capture yet.
QCamera::StoppingStatus 7 Camera is stopping in result of state transition from QCamera::ActiveState to QCamera::LoadedState or QCamera::UnloadedState.
QCamera::StandbyStatus 5 Camera is in the power saving standby mode. The camera may come to the standby mode after some time of inactivity in the QCamera::LoadedState state.
QCamera::LoadedStatus 4 Camera is loaded and ready to be configured. This status indicates the camera device is opened and it is possible to query for supported image and video capture settings, like resolution, framerate and codecs.
QCamera::LoadingStatus 3 Camera device loading in result of state transition from QCamera::UnloadedState to QCamera::LoadedState or QCamera::ActiveState.
QCamera::UnloadingStatus 2 Camera device is unloading in result of state transition from QCamera::LoadedState or QCamera::ActiveState to QCamera::UnloadedState.
QCamera::UnloadedStatus 1 Initial camera status, with camera not loaded. The camera capabilities including supported capture settings may be unknown.
QCamera::UnavailableStatus 0 Camera or camera backend is not available.

Constructor & Destructor Documentation

QCamera::QCamera ( QObject parent = nullptr)
explicit

Construct a QCamera with a parent.

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

Construct a QCamera from deviceName and parent. If no camera with that deviceName exists, the camera object will be invalid.

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

Construct a QCamera from a camera description cameraInfo and parent.

QCamera::QCamera ( QCamera::Position  position,
QObject parent = nullptr 
)
explicit

Construct a QCamera which uses a hardware camera located at 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.

QCamera::~QCamera ( )

Destroys the camera object.

Method Documentation

QMultimedia::AvailabilityStatus QCamera::availability ( ) const
overridevirtual

Returns the availability state of the camera service.

Reimplemented from QMediaObject::availability()

CaptureModes QCamera::captureMode ( ) const

Returns the value of the property.

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

Signals the capture mode has changed.

Error QCamera::error ( ) const

Returns the error state of the object.

void QCamera::error ( QCamera::Error  error)
signal

Signal emitted when error state changes to error.

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 ( CaptureModes  mode) const

Returns true if the capture mode is supported.

void QCamera::load ( )
slot

Opens the camera device. The camera status is changed to QCamera::LoadedStatus.

It is not necessary to explicitly call this method unless the application needs to read the supported camera settings and change the defaults. If the default settings are acceptable start the camera directly from the unloaded state.

void QCamera::locked ( )
signal

Signals all the requested camera settings are locked.

void QCamera::lockFailed ( )
signal

Signals locking of at least one requested camera settings failed.

QCamera::LockStatus QCamera::lockStatus ( ) const
inline

Returns the status of requested camera settings locks.

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

Returns the lock status for a given lockType.

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

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

void QCamera::lockStatusChanged ( QCamera::LockType  type,
QCamera::LockStatus  status,
QCamera::LockChangeReason  reason 
)
signal

Signals the type and status was changed with specified reason.

QCamera::LockTypes QCamera::requestedLocks ( ) const

Returns the requested lock types.

void QCamera::searchAndLock ( )
slot

Lock all the supported camera settings.

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

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 response 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:

  • Initializes calculation of automatic parameters (focusing, calculating the correct exposure and white balance)
  • Allows keeping some or all of those parameters fixed during multiple shots

If the camera does not support keeping one of parameters between shots the related lock state changes to QCamera::Unlocked. It is also acceptable to relock already locked settings, depending on the lock parameter this initiates new focusing, exposure or white balance calculation.

void QCamera::setCaptureMode ( QCamera::CaptureModes  mode)
slot

Sets the value of the property to mode.

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::setViewfinder ( QGraphicsVideoItem viewfinder)

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

void QCamera::setViewfinder ( QVideoWidget viewfinder)

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

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.

See also
viewfinderSettings(), supportedViewfinderResolutions(), supportedViewfinderFrameRateRanges(), supportedViewfinderPixelFormats()
void QCamera::start ( )
slot

Starts the camera. State is changed to QCamera::ActiveState if camera is started successfully, otherwise error() 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.

State QCamera::state ( ) const

Returns the value of the property.

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

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.

Status QCamera::status ( ) const

Returns the value of the property.

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

Signals the camera status has changed.

void QCamera::stop ( )
slot

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

QCamera::LockTypes QCamera::supportedLocks ( ) const

Returns the lock types the current camera supports.

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

Returns a list of supported viewfinder frame rate ranges. 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.

See also
QCameraViewfinderSettings::minimumFrameRate(), QCameraViewfinderSettings::maximumFrameRate(), setViewfinderSettings()
QList< QVideoFrame::PixelFormat > QCamera::supportedViewfinderPixelFormats ( const QCameraViewfinderSettings settings = QCameraViewfinderSettings()) const

Returns a list of supported viewfinder pixel formats. 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 method otherwise the returned list is empty.

See also
QCameraViewfinderSettings::pixelFormat(), setViewfinderSettings()
QList< QSize > QCamera::supportedViewfinderResolutions ( const QCameraViewfinderSettings settings = QCameraViewfinderSettings()) const

Returns a list of supported viewfinder resolutions. 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 method, otherwise the returned list is empty.

See also
QCameraViewfinderSettings::resolution(), 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 camera must be loaded before calling this function, otherwise the returned list is empty.

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.

See also
setViewfinderSettings(), supportedViewfinderResolutions(), supportedViewfinderFrameRateRanges(), supportedViewfinderPixelFormats()
void QCamera::unload ( )
slot

Close the camera device and deallocate the related resources. The camera state is changed to QCamera::UnloadedStatus.

void QCamera::unlock ( )
slot

Unlock all the requested camera locks.

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

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

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.

See also
setViewfinderSettings()

Property Documentation

QCamera::captureMode

The type of media (video or still images), the camera is configured to capture.

It is allowed to change capture mode in any camera state, but if the camera is currently active, changing capture mode is likely to lead to camera status changed to QCamera::LoadedStatus, QCamera::LoadingStatus, and when the camera is ready to QCamera::ActiveStatus.

PropertiesClass Methods
read captureMode
write setCaptureMode
notify captureModeChanged
QCamera::lockStatus

This property holds the overall status for all the requested camera locks.

PropertiesClass Methods
read lockStatus
notify lockStatusChanged
QCamera::state

This property holds the current state of the camera object.

PropertiesClass Methods
read state
notify stateChanged
QCamera::status

This property holds the current status of the camera object.

PropertiesClass Methods
read status
notify statusChanged