Document QCameraFormat and expose it to QML

QCameraFormat didn't have any documentation, and was not
available in QML, even though it's required to change the
resolution or framerate of the camera from QML.

Change-Id: I8ad60fe71b3c65ecb9eb737d8a5e52ca0be196e2
Reviewed-by: Piotr Srebrny <piotr.srebrny@qt.io>
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
(cherry picked from commit dbf2172ccd1554652d55652557b85155024b20d7)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

3 files changed, 132 insertions, 2 deletions

diff --git a/src/multimedia/camera/qcameradevice.cpp b/src/multimedia/camera/qcameradevice.cpp
index 8fa60dfa9..096ee314d 100644
--- a/src/multimedia/camera/qcameradevice.cpp
+++ b/src/multimedia/camera/qcameradevice.cpp
@@ -43,40 +43,153 @@
 
 QT_BEGIN_NAMESPACE
 
+
+/*!
+    \class QCameraFormat
+    \since 6.2
+    \brief The QCameraFormat class describes a video format supported by a camera device.
+    \inmodule QtMultimedia
+    \ingroup multimedia
+    \ingroup multimedia_camera
+
+    QCameraFormat represents a certain video format supported by a camera device.
+
+    The format is a combination of a
+    \l{QVideoFrameFormat::PixelFormat}{pixel format}, resolution and a range of frame
+    rates.
+
+    QCameraFormat objects can be queried from QCameraDevice to inspect the set of
+    supported video formats.
+
+    \sa QCameraDevice, QCamera
+*/
+
+/*!
+    \qmltype cameraFormat
+    \inqmlmodule QtMultimedia
+    \since 6.2
+    \instantiates QCameraFormat
+    \brief Describes a video format supported by a camera device.
+    \ingroup multimedia_qml
+    \ingroup multimedia_video_qml
+
+    CameraFormat represents a certain video format supported by a camera device.
+
+    The format is a combination of a
+    \l{pixel format}{QVideoFrameFormat::PixelFormat}, resolution and a range of frame
+    rates.
+
+    CameraFormat objects can be queried from \l CameraDevice to inspect the set of
+    supported video formats.
+
+    \sa CameraDevice, Camera
+*/
+
+/*!
+    Constructs a null camera format.
+
+    \sa isNull()
+*/
 QCameraFormat::QCameraFormat() noexcept = default;
 
+/*!
+    Copy constructs a camera format from the \a other format.
+*/
 QCameraFormat::QCameraFormat(const QCameraFormat &other) noexcept = default;
 
+/*!
+    Assign \a other to this.
+*/
 QCameraFormat &QCameraFormat::operator=(const QCameraFormat &other) noexcept = default;
 
+/*!
+    Destructs the camera format object.
+*/
 QCameraFormat::~QCameraFormat() = default;
 
+/*!
+    \qmlproperty enumeration QtMultimedia::CameraFormat::pixelFormat
+
+    Returns the pixel format.
+
+    Most commonly this is either QVideoFrameFormat::Format_Jpeg or QVideoFrameFormat::Format_YUVY
+    but other formats could also be supported by the camera.
+
+    \sa QVideoFrameFormat::PixelFormat
+*/
+
+/*!
+    Returns the pixel format.
+
+    Most commonly this is either QVideoFrameFormat::Format_Jpeg or QVideoFrameFormat::Format_YUVY
+    but other formats could also be supported by the camera.
+
+    \sa QVideoFrameFormat::PixelFormat
+*/
 QVideoFrameFormat::PixelFormat QCameraFormat::pixelFormat() const noexcept
 {
     return d ? d->pixelFormat : QVideoFrameFormat::Format_Invalid;
 }
 
+/*!
+    \qmlproperty size QtMultimedia::CameraFormat::resolution
+
+    Returns the resolution.
+*/
+
+/*!
+    Returns the resolution.
+*/
 QSize QCameraFormat::resolution() const noexcept
 {
     return d ? d->resolution : QSize();
 }
 
+/*!
+    \qmlproperty real QtMultimedia::CameraFormat::minFrameRate
+
+    Returns the lowest frame rate defined by this format.
+*/
+
+/*!
+    Returns the lowest frame rate defined by this format.
+*/
 float QCameraFormat::minFrameRate() const noexcept
 {
     return d ? d->minFrameRate : 0;
 }
 
+/*!
+    \qmlproperty real QtMultimedia::CameraFormat::maxFrameRate
+
+    Returns the highest frame rate defined by this format.
+
+    In 6.2, the camera will always try to use the maximum frame rate supported by a
+    certain video format.
+*/
+
+/*!
+    Returns the highest frame rate defined by this format.
+
+    In 6.2, the camera will always try to use the highest frame rate supported by a
+    certain video format.
+*/
 float QCameraFormat::maxFrameRate() const noexcept
 {
     return d ? d->maxFrameRate : 0;
 }
 
-
+/*!
+    \internal
+*/
 QCameraFormat::QCameraFormat(QCameraFormatPrivate *p)
     : d(p)
 {
 }
 
+/*!
+    Returns \c true if the \a other format is equal to this camera format, otherwise \c false.
+*/
 bool QCameraFormat::operator==(const QCameraFormat &other) const
 {
     if (d == other.d)
@@ -90,9 +203,14 @@ bool QCameraFormat::operator==(const QCameraFormat &other) const
 }
 
 /*!
+    \fn bool QCameraFormat::operator!=(const QCameraFormat &other) const
+
+    Returns \c false if the \a other format is equal to this camera format, otherwise \c true.
+*/
+
+/*!
     \class QCameraDevice
     \brief The QCameraDevice class provides general information about camera devices.
-    \since 5.3
     \inmodule QtMultimedia
     \ingroup multimedia
     \ingroup multimedia_camera
diff --git a/src/multimedia/camera/qcameradevice.h b/src/multimedia/camera/qcameradevice.h
index 02dfdf6b5..b58a49687 100644
--- a/src/multimedia/camera/qcameradevice.h
+++ b/src/multimedia/camera/qcameradevice.h
@@ -48,6 +48,11 @@ QT_BEGIN_NAMESPACE
 class QCameraFormatPrivate;
 class Q_MULTIMEDIA_EXPORT QCameraFormat
 {
+    Q_GADGET
+    Q_PROPERTY(QSize resolution READ resolution CONSTANT)
+    Q_PROPERTY(QVideoFrameFormat::PixelFormat pixelFormat READ pixelFormat CONSTANT)
+    Q_PROPERTY(float minFrameRate READ minFrameRate CONSTANT)
+    Q_PROPERTY(float maxFrameRate READ maxFrameRate CONSTANT)
 public:
     QCameraFormat() noexcept;
     QCameraFormat(const QCameraFormat &other) noexcept;
diff --git a/src/multimediaquick/qtmultimediaquicktypes_p.h b/src/multimediaquick/qtmultimediaquicktypes_p.h
index c4051e0b5..d202efd1f 100644
--- a/src/multimediaquick/qtmultimediaquicktypes_p.h
+++ b/src/multimediaquick/qtmultimediaquicktypes_p.h
@@ -176,6 +176,13 @@ namespace QMediaFormatNamespaceForeign
     QML_NAMED_ELEMENT(MediaFormat)
 };
 
+struct QCameraFormatForeign
+{
+    Q_GADGET
+    QML_FOREIGN(QCameraFormat)
+    QML_NAMED_ELEMENT(cameraFormat)
+};
+
 QT_END_NAMESPACE
 
 #endif