Revision control
++ // Copyright (C) 2021 The Qt Company Ltd.
++ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
++ #include <qimagecapture.h>
++ #include <private/qplatformimagecapture_p.h>
++ #include <qmediametadata.h>
++ #include <private/qplatformmediacapture_p.h>
++ #include <private/qplatformmediaintegration_p.h>
++ #include <private/qplatformmediaformatinfo_p.h>
++ #include <qmediacapturesession.h>
++
++ #include "private/qobject_p.h"
++ #include <qcamera.h>
++ #include <private/qplatformcamera_p.h>
++ #include <QtCore/qdebug.h>
++ #include <QtCore/qurl.h>
++ #include <QtCore/qstringlist.h>
++ #include <QtCore/qmetaobject.h>
++
++ QT_BEGIN_NAMESPACE
++
++ /*!
++ \class QImageCapture
++ \inmodule QtMultimedia
++ \ingroup multimedia
++ \ingroup multimedia_camera
++
++
++ \brief The QImageCapture class is used for the recording of media content.
++
++ The QImageCapture class is a high level images recording class.
++ It's not intended to be used alone but for accessing the media
++ recording functions of other media objects, like QCamera.
++
++ \snippet multimedia-snippets/camerasnippets.cpp Camera
++
++ \snippet multimedia-snippets/camerasnippets.cpp Camera keys
++
++ \sa QCamera
++ */
++
++ class QImageCapturePrivate
++ {
++ Q_DECLARE_PUBLIC(QImageCapture)
++ public:
++ QCamera *camera = nullptr;
++
++ QMediaCaptureSession *captureSession = nullptr;
++ QPlatformImageCapture *control = nullptr;
++
++ QImageCapture::Error error = QImageCapture::NoError;
++ QString errorString;
++ QMediaMetaData metaData;
++
++ void _q_error(int id, int error, const QString &errorString);
++
++ void unsetError() { error = QImageCapture::NoError; errorString.clear(); }
++
++ QImageCapture *q_ptr;
++ };
++
++ void QImageCapturePrivate::_q_error(int id, int error, const QString &errorString)
++ {
++ Q_Q(QImageCapture);
++
++ this->error = QImageCapture::Error(error);
++ this->errorString = errorString;
++
++ Q_EMIT q->errorChanged();
++ Q_EMIT q->errorOccurred(id, this->error, errorString);
++ }
++
++ /*!
++ Constructs a image capture object, from a \a parent, that can capture
++ individual still images produced by a camera.
++
++ You must connect both an image capture object and a QCamera to a capture
++ session to capture images.
++ */
++
++ QImageCapture::QImageCapture(QObject *parent)
++ : QObject(parent), d_ptr(new QImageCapturePrivate)
++ {
++ Q_D(QImageCapture);
++ d->q_ptr = this;
++
++ auto maybeControl = QPlatformMediaIntegration::instance()->createImageCapture(this);
++ if (!maybeControl) {
++ qWarning() << "Failed to initialize QImageCapture" << maybeControl.error();
++ d->errorString = maybeControl.error();
++ d->error = NotReadyError;
++ return;
++ }
++
++ d->control = maybeControl.value();
++ connect(d->control, &QPlatformImageCapture::imageExposed, this, &QImageCapture::imageExposed);
++ connect(d->control, &QPlatformImageCapture::imageCaptured, this, &QImageCapture::imageCaptured);
++ connect(d->control, &QPlatformImageCapture::imageMetadataAvailable, this,
++ &QImageCapture::imageMetadataAvailable);
++ connect(d->control, &QPlatformImageCapture::imageAvailable, this,
++ &QImageCapture::imageAvailable);
++ connect(d->control, &QPlatformImageCapture::imageSaved, this, &QImageCapture::imageSaved);
++ connect(d->control, &QPlatformImageCapture::readyForCaptureChanged, this,
++ &QImageCapture::readyForCaptureChanged);
++ connect(d->control, SIGNAL(error(int,int,QString)),
++ this, SLOT(_q_error(int,int,QString)));
++ }
++
++ /*!
++ \fn void QImageCapture::imageMetadataAvailable(int id, const QMediaMetaData &metaData)
++
++ Signals that an image identified by \a id has \a metaData.
++ */
++
++ /*!
++ \internal
++ */
++ void QImageCapture::setCaptureSession(QMediaCaptureSession *session)
++ {
++ Q_D(QImageCapture);
++ d->captureSession = session;
++ }
++
++ /*!
++ Destroys images capture object.
++ */
++
++ QImageCapture::~QImageCapture()
++ {
++ if (d_ptr->captureSession)
++ d_ptr->captureSession->setImageCapture(nullptr);
++ delete d_ptr;
++ }
++
++ /*!
++ Returns true if the images capture service ready to use.
++ */
++ bool QImageCapture::isAvailable() const
++ {
++ return d_func()->control && d_func()->captureSession && d_func()->captureSession->camera();
++ }
++
++ /*!
++ Returns the capture session this camera is connected to, or
++ a nullptr if the camera is not connected to a capture session.
++
++ Use QMediaCaptureSession::setImageCapture() to connect the image capture to
++ a session.
++ */
++ QMediaCaptureSession *QImageCapture::captureSession() const
++ {
++ return d_ptr->captureSession;
++ }
++
++ /*!
++ \qmlproperty enumeration QtMultimedia::ImageCapture::error
++
++ This property holds the last error type that occurred. It can be one of the following.
++
++ \value ImageCapture.NoError No esrrors.
++ \value ImageCapture.NotReadyError The service is not ready for capture yet.
++ \value ImageCapture.ResourceError Device is not ready or not available.
++ \value ImageCapture.OutOfSpaceError No space left on device.
++ \value ImageCapture.NotSupportedFeatureError Device does not support stillimages capture.
++ \value ImageCapture.FormatError Current format is not supported.
++
++ \sa errorString
++ */
++
++ /*!
++ \property QImageCapture::error
++
++ Returns the current error state.
++
++ \sa errorString()
++ */
++
++ QImageCapture::Error QImageCapture::error() const
++ {
++ return d_func()->error;
++ }
++
++ /*!
++ \qmlproperty string QtMultimedia::ImageCapture::errorString
++
++ This property holds the last error message that occurred.
++
++ \sa error
++ */
++
++ /*!
++ \property QImageCapture::errorString
++
++ Returns a string describing the current error state.
++
++ \sa error()
++ */
++
++ QString QImageCapture::errorString() const
++ {
++ return d_func()->errorString;
++ }
++
++ /*!
++ \qmlproperty mediaMetaData QtMultimedia::ImageCapture::metaData
++
++ This property holds the metadata that wil be embedded into the image.
++ */
++
++ /*!
++ \property QImageCapture::metaData
++ \brief The meta data that will get embedded into the image.
++
++ \note Additional fields such as a time stamp or location may get added by
++ the camera back end.
++ */
++ QMediaMetaData QImageCapture::metaData() const
++ {
++ Q_D(const QImageCapture);
++ return d->metaData;
++ }
++
++ /*!
++ Replaces any existing meta data, to be embedded into the captured image,
++ with a set of \a metaData.
++ */
++ void QImageCapture::setMetaData(const QMediaMetaData &metaData)
++ {
++ Q_D(QImageCapture);
++ d->metaData = metaData;
++ if (d->control)
++ d->control->setMetaData(d->metaData);
++ Q_EMIT metaDataChanged();
++ }
++
++ /*!
++ Adds additional \a metaData to any existing meta data, that is embedded
++ into the captured image.
++ */
++ void QImageCapture::addMetaData(const QMediaMetaData &metaData)
++ {
++ Q_D(QImageCapture);
++ auto data = d->metaData;
++ for (auto &&[key, value] : metaData.asKeyValueRange())
++ data.insert(key, value);
++ setMetaData(data);
++ }
++
++ /*!
++ \property QImageCapture::readyForCapture
++
++ Holds \c true if the camera is ready to capture an image immediately.
++ Calling capture() while \c readyForCapture is \c false is not
++ permitted and results in an error.
++ */
++ bool QImageCapture::isReadyForCapture() const
++ {
++ Q_D(const QImageCapture);
++ if (!d->control || !d->captureSession || !d->control->isReadyForCapture())
++ return false;
++ auto *camera = d->captureSession->camera();
++ if (!camera || !camera->isActive())
++ return false;
++ return true;
++ }
++
++ /*!
++ \fn QImageCapture::readyForCaptureChanged(bool ready)
++
++ Signals that a camera's \a ready for capture state has changed.
++ */
++
++
++ /*!
++ Capture the image and save it to \a file.
++ This operation is asynchronous in majority of cases,
++ followed by signals QImageCapture::imageExposed(),
++ QImageCapture::imageCaptured(), QImageCapture::imageSaved()
++ or QImageCapture::error().
++
++ If an empty \a file is passed, the camera back end chooses
++ the default location and naming scheme for photos on the system,
++ if only file name without full path is specified, the image will be saved to
++ the default directory, with a full path reported with imageCaptured() and imageSaved() signals.
++
++ QCamera saves all the capture parameters like exposure settings or
++ image processing parameters, so changes to camera parameters after
++ capture() is called do not affect previous capture requests.
++
++ QImageCapture::capture returns the capture Id parameter, used with
++ imageExposed(), imageCaptured() and imageSaved() signals.
++
++ \sa isReadyForCapture()
++ */
++ int QImageCapture::captureToFile(const QString &file)
++ {
++ Q_D(QImageCapture);
++ if (!d->control) {
++ d->_q_error(-1, d->error, d->errorString);
++ return -1;
++ }
++
++ d->unsetError();
++
++ if (!isReadyForCapture()) {
++ d->_q_error(-1, NotReadyError, tr("Could not capture in stopped state"));
++ return -1;
++ }
++
++ return d->control->capture(file);
++ }
++
++ /*!
++ Capture the image and make it available as a QImage.
++ This operation is asynchronous in majority of cases,
++ followed by signals QImageCapture::imageExposed(),
++ QImageCapture::imageCaptured()
++ or QImageCapture::error().
++
++ QImageCapture::capture returns the capture Id parameter, used with
++ imageExposed(), imageCaptured() and imageSaved() signals.
++
++ \sa isReadyForCapture()
++ */
++ int QImageCapture::capture()
++ {
++ Q_D(QImageCapture);
++ if (!d->control) {
++ d->_q_error(-1, d->error, d->errorString);
++ return -1;
++ } else {
++ d->unsetError();
++ return d->control->captureToBuffer();
++ }
++ }
++
++ /*!
++ \enum QImageCapture::Error
++
++ \value NoError No Errors.
++ \value NotReadyError The service is not ready for capture yet.
++ \value ResourceError Device is not ready or not available.
++ \value OutOfSpaceError No space left on device.
++ \value NotSupportedFeatureError Device does not support stillimages capture.
++ \value FormatError Current format is not supported.
++ */
++
++ /*!
++ \fn QImageCapture::errorOccurred(int id, QImageCapture::Error error, const QString &errorString);
++
++ Signals that the capture request \a id has failed with an \a error
++ and \a errorString description.
++ */
++
++ /*!
++ \fn QImageCapture::imageExposed(int id)
++
++ Signal emitted when the frame with request \a id was exposed.
++ */
++
++ /*!
++ \fn QImageCapture::imageCaptured(int id, const QImage &preview);
++
++ Signal emitted when the frame with request \a id was captured, but not
++ processed and saved yet. Frame \a preview can be displayed to user.
++ */
++
++ /*!
++ \fn QImageCapture::imageAvailable(int id, const QVideoFrame &frame)
++
++ Signal emitted when the \a frame with request \a id is available.
++ */
++
++ /*!
++ \fn QImageCapture::imageSaved(int id, const QString &fileName)
++
++ Signal emitted when QImageCapture::CaptureToFile is set and
++ the frame with request \a id was saved to \a fileName.
++ */
++
++ /*!
++ \enum QImageCapture::FileFormat
++
++ Choose one of the following image formats:
++
++ \value UnspecifiedFormat No format specified
++ \value JPEG \c .jpg or \c .jpeg format
++ \value PNG \c .png format
++ \value WebP \c .webp format
++ \value Tiff \c .tiff format
++ \omitvalue LastFileFormat
++ */
++
++ /*!
++ \qmlproperty enumeration QtMultimedia::ImageCapture::fileFormat
++
++ This property holds the file format for which the image will be
++ written. It can be one of the following.
++
++ \value UnspecifiedFormat No format specified
++ \value JPEG \c .jpg or \c .jpeg format
++ \value PNG \c .png format
++ \value WebP \c .webp format
++ \value Tiff \c .tiff format
++ */
++
++ /*!
++ \property QImageCapture::fileFormat
++ \brief The image format.
++ */
++
++ QImageCapture::FileFormat QImageCapture::fileFormat() const
++ {
++ Q_D(const QImageCapture);
++ return d->control ? d->control->imageSettings().format() : UnspecifiedFormat;
++ }
++
++ /*!
++ Sets the image \a format.
++
++ Assigning an unsupported \l FileFormat has no effect.
++
++ \sa supportedFormats
++ */
++ void QImageCapture::setFileFormat(QImageCapture::FileFormat format)
++ {
++ Q_D(QImageCapture);
++ if (!d->control)
++ return;
++ auto fmt = d->control->imageSettings();
++ const FileFormat oldFormat = fmt.format();
++ if (oldFormat == format)
++ return;
++ fmt.setFormat(format);
++ d->control->setImageSettings(fmt);
++ // Only fire the signal if the format was applied.
++ if (oldFormat != fileFormat())
++ Q_EMIT fileFormatChanged();
++ }
++
++ /*!
++ \qmlproperty list<FileFormat> QtMultimedia::ImageCapture::supportedFormats
++ \since 6.10
++
++ Contains a list of supported file formats.
++
++ \sa fileFormat
++ */
++
++ /*!
++ \property QImageCapture::supportedFormats
++ \brief a list of supported file formats.
++ */
++
++ /*!
++ Returns a list of supported file formats.
++
++ \sa {QImageCapture::}{FileFormat}
++ */
++ QList<QImageCapture::FileFormat> QImageCapture::supportedFormats()
++ {
++ return QPlatformMediaIntegration::instance()->formatInfo()->imageFormats;
++ }
++
++ /*!
++ Returns the name of the given format, \a f.
++ */
++ QString QImageCapture::fileFormatName(QImageCapture::FileFormat f)
++ {
++ const char *name = nullptr;
++ switch (f) {
++ case UnspecifiedFormat:
++ name = "Unspecified image format";
++ break;
++ case JPEG:
++ name = "JPEG";
++ break;
++ case PNG:
++ name = "PNG";
++ break;
++ case WebP:
++ name = "WebP";
++ break;
++ case Tiff:
++ name = "Tiff";
++ break;
++ }
++ return QString::fromUtf8(name);
++ }
++
++ /*!
++ Returns the description of the given file format, \a f.
++ */
++ QString QImageCapture::fileFormatDescription(QImageCapture::FileFormat f)
++ {
++ const char *name = nullptr;
++ switch (f) {
++ case UnspecifiedFormat:
++ name = "Unspecified image format";
++ break;
++ case JPEG:
++ name = "JPEG";
++ break;
++ case PNG:
++ name = "PNG";
++ break;
++ case WebP:
++ name = "WebP";
++ break;
++ case Tiff:
++ name = "Tiff";
++ break;
++ }
++ return QString::fromUtf8(name);
++ }
++
++ /*!
++ \qmlproperty size QtMultimedia::ImageCapture::resolution
++ \since 6.13
++
++ The resolution of captured images.
++
++ An empty size (the default) lets the backend choose. When the image source is a camera,
++ a size from \l {QtMultimedia::cameraDevice::photoResolutions}{photoResolutions} makes the
++ camera capture stills at that size.
++
++ \sa QtMultimedia::cameraDevice::photoResolutions
++ */
++
++ /*!
++ \property QImageCapture::resolution
++ \brief The resolution of captured images
++
++ Set this property to request a specific capture resolution.
++
++ When the image source is a camera, use a size from
++ \l {QCameraDevice::photoResolutions}{photoResolutions} to capture at a resolution the camera
++ supports natively. This might be limited based on the current
++ \l {QCamera::cameraFormat}{camera format}.
++
++ If the source cannot provide the requested resolution, the backend may use the closest
++ supported resolution, and scale the captured image to the requested size.
++
++ \sa QCameraDevice::photoResolutions, QCameraFormat
++ */
++ QSize QImageCapture::resolution() const
++ {
++ Q_D(const QImageCapture);
++ return d->control ? d->control->imageSettings().resolution() : QSize{};
++ }
++
++ /*!
++ \fn void QImageCapture::resolutionChanged()
++
++ Signals when the image resolution changes.
++ */
++
++ /*!
++ Sets the requested \a resolution of captured images.
++
++ An empty QSize indicates the backend should make an optimal choice based on
++ what is available from the image source.
++ */
++ void QImageCapture::setResolution(const QSize &resolution)
++ {
++ Q_D(QImageCapture);
++ if (!d->control)
++ return;
++ auto fmt = d->control->imageSettings();
++ if (fmt.resolution() == resolution)
++ return;
++ fmt.setResolution(resolution);
++ d->control->setImageSettings(fmt);
++ Q_EMIT resolutionChanged();
++ }
++
++ /*!
++ Sets the \a width and \a height of the requested resolution of captured images.
++
++ \overload
++ */
++ void QImageCapture::setResolution(int width, int height)
++ {
++ setResolution(QSize(width, height));
++ }
++
++ /*!
++ Resets the requested resolution of captured images to the default.
++
++ \sa setResolution()
++ */
++ void QImageCapture::resetResolution()
++ {
++ setResolution(QSize{});
++ }
++
++ /*!
++ \enum QImageCapture::Quality
++
++ Enumerates quality encoding levels.
++
++ \value VeryLowQuality
++ \value LowQuality
++ \value NormalQuality
++ \value HighQuality
++ \value VeryHighQuality
++ */
++
++ /*!
++ \qmlproperty enumeration QtMultimedia::ImageCapture::quality
++
++ This property holds the quality hint when storing the captured
++ image. It can be one of the following values.
++
++ \value VeryLowQuality Very low
++ \value LowQuality Low
++ \value NormalQuality Normal
++ \value HighQuality High
++ \value VeryHighQuality Very high
++ */
++
++ /*!
++ \property QImageCapture::quality
++ \brief The image encoding quality.
++ */
++ QImageCapture::Quality QImageCapture::quality() const
++ {
++ Q_D(const QImageCapture);
++ return d->control ? d->control->imageSettings().quality() : NormalQuality;
++ }
++
++ /*!
++ Sets the image encoding \a quality.
++ */
++ void QImageCapture::setQuality(Quality quality)
++ {
++ Q_D(QImageCapture);
++ if (!d->control)
++ return;
++ auto fmt = d->control->imageSettings();
++ if (fmt.quality() == quality)
++ return;
++ fmt.setQuality(quality);
++ d->control->setImageSettings(fmt);
++ Q_EMIT qualityChanged();
++ }
++
++ /*!
++ \internal
++ */
++ QPlatformImageCapture *QImageCapture::platformImageCapture()
++ {
++ Q_D(QImageCapture);
++ return d->control;
++ }
++
++ QT_END_NAMESPACE
++
++ #include "moc_qimagecapture.cpp"