QCameraExposure API refactoring

QCameraExposureControl:
 Separated requested from actual exposure values.
 Removed ParameterFlags, it's confusing and seldom used.
 Moved ExposureMode and MeteringMode to parameters.

QCameraExposure:
 Added requestedAperture/ShutterSpeed/Iso getters

Change-Id: I408586d85e6c9de0c8a711c32b3c90ea46052270
Reviewed-by: Michael Goddard <michael.goddard@nokia.com>

2 files changed, 62 insertions, 103 deletions

diff --git a/src/multimedia/controls/qcameraexposurecontrol.cpp b/src/multimedia/controls/qcameraexposurecontrol.cpp
index 8bae85dd0..da0ebd3a9 100644
--- a/src/multimedia/controls/qcameraexposurecontrol.cpp
+++ b/src/multimedia/controls/qcameraexposurecontrol.cpp
@@ -90,53 +90,14 @@ QCameraExposureControl::QCameraExposureControl(QObject *parent):
 }
 
 /*!
-    Destroys the camera control object.
+    Destroys the camera exposure control object.
 */
 QCameraExposureControl::~QCameraExposureControl()
 {
 }
 
 /*!
-  \fn QCamera::ExposureMode QCameraExposureControl::exposureMode() const
-
-  Returns the exposure mode.
-*/
-
-
-/*!
-  \fn void QCameraExposureControl::setExposureMode(QCameraExposure::ExposureMode mode)
-
-  Set the exposure mode to \a mode.
-*/
-
-
-/*!
-  \fn bool QCameraExposureControl::isExposureModeSupported(QCameraExposure::ExposureMode mode) const
-
-  Returns true if the exposure \a mode is supported.
-*/
-
-
-/*!
-  \fn QCameraExposure::MeteringMode QCameraExposureControl::meteringMode() const
-  Returns the current metering mode.
-*/
-
-/*!
-  \fn void QCameraExposureControl::setMeteringMode(QCameraExposure::MeteringMode mode)
-
-  Set the metering mode to \a mode.
-*/
-
-/*!
-  \fn bool QCameraExposureControl::isMeteringModeSupported(QCameraExposure::MeteringMode mode) const
-    Returns true if the metering \a mode is supported.
-*/
-
-/*!
   \enum QCameraExposureControl::ExposureParameter
-  \value InvalidParameter
-         Parameter is invalid.
   \value ISO
          Camera ISO sensitivity, specified as integer value.
   \value Aperture
@@ -153,84 +114,97 @@ QCameraExposureControl::~QCameraExposureControl()
          with 0 value means no flash and 1.0 corresponds to full flash power.
 
          This value is only used in the \l{QCameraExposure::FlashManual}{manual flash mode}.
+  \value TorchPower
+         Manual torch power, specified as qreal value.
+         Accepted power range is [0..1.0],
+         with 0 value means no light and 1.0 corresponds to full torch power.
+
+         This value is only used in the \l{QCameraExposure::FlashTorch}{torch flash mode}.
   \value FlashCompensation
          Flash compensation, specified as qreal EV value.
   \value SpotMeteringPoint
          The relative frame coordinate of the point to use for exposure metering
          in spot metering mode, specified as a QPointF.
+  \value ExposureMode
+         Camera exposure mode.
+  \value MeteringMode
+         Camera metering mode.
   \value ExtendedExposureParameter
          The base value for platform specific extended parameters.
          For such parameters the sequential values starting from ExtendedExposureParameter shuld be used.
 */
 
 /*!
-  \enum QCameraExposureControl::ParameterFlag
-  \value AutomaticValue
-         Use the automatic values for parameters.
-  \value ReadOnly
-         Parameters are read only.
-  \value ContinuousRange
-         Parameters are continuous in their range.
-*/
-
-/*!
   \fn QCameraExposureControl::isParameterSupported(ExposureParameter parameter) const
 
   Returns true is exposure \a parameter is supported by backend.
+  \since 5.0
 */
 
 /*!
-  \fn QCameraExposureControl::exposureParameter(ExposureParameter parameter) const
+  \fn QCameraExposureControl::requestedValue(ExposureParameter parameter) const
+
+  Returns the requested exposure \a parameter value.
 
-  Returns the exposure \a parameter value, or invalid QVariant() if the value is unknown or not supported.
+  \since 5.0
 */
 
 /*!
-  \fn QCameraExposureControl::exposureParameterFlags(ExposureParameter parameter) const
+  \fn QCameraExposureControl::actualValue(ExposureParameter parameter) const
 
-  Returns the properties of exposure \a parameter.
+  Returns the actual exposure \a parameter value, or invalid QVariant() if the value is unknown or not supported.
+
+  The actual parameter value may differ for the requested one if automatic mode is selected or
+  camera supports only limited set of values within the supported range.
+  \since 5.0
 */
 
 
 /*!
-  \fn QCameraExposureControl::supportedParameterRange(ExposureParameter parameter) const
+  \fn QCameraExposureControl::supportedParameterRange(ExposureParameter parameter, bool *continuous = 0) const
 
   Returns the list of supported \a parameter values;
+
+  If the camera supports arbitrary exposure parameter value within the supported range,
+  *\a continuous is set to true, otherwise *\a continuous is set to false.
+
+  \since 5.0
 */
 
 /*!
-  \fn bool QCameraExposureControl::setExposureParameter(ExposureParameter parameter, const QVariant& value)
+  \fn bool QCameraExposureControl::setValue(ExposureParameter parameter, const QVariant& value)
 
   Set the exposure \a parameter to \a value.
   If a null or invalid QVariant is passed, backend should choose the value automatically,
-  and if possible report the actual value to user with QCameraExposureControl::exposureParameter().
+  and if possible report the actual value to user with QCameraExposureControl::actualValue().
 
   Returns true if parameter is supported and value is correct.
+  \since 5.0
 */
 
 /*!
-  \fn QCameraExposureControl::extendedParameterName(ExposureParameter parameter)
+    \fn void QCameraExposureControl::requestedValueChanged(int parameter)
 
-  Returns the extended exposure \a parameter name.
+    Signal emitted when the requested exposure \a parameter value has changed,
+    usually in result of setValue() call.
+    \since 5.0
 */
 
 /*!
-    \fn void QCameraExposureControl::flashReady(bool ready)
-
-    Signal emitted when flash state changes, flash is charged \a ready.
-*/
+    \fn void QCameraExposureControl::actualValueChanged(int parameter)
 
-/*!
-    \fn void QCameraExposureControl::exposureParameterChanged(int parameter)
+    Signal emitted when the actual exposure \a parameter value has changed,
+    usually in result of auto exposure algorithms or manual exposure parameter applied.
 
-    Signal emitted when the exposure \a parameter has changed.
+    \since 5.0
 */
 
 /*!
+    \fn void QCameraExposureControl::parameterRangeChanged(int parameter)
 
-    \fn void QCameraExposureControl::exposureParameterRangeChanged(int parameter)
+    Signal emitted when the supported range of exposure \a parameter values has changed.
 
-    Signal emitted when the exposure \a parameter range has changed.
+    \since 5.0
 */
 
 
diff --git a/src/multimedia/controls/qcameraexposurecontrol.h b/src/multimedia/controls/qcameraexposurecontrol.h
index 6c5b768b6..76c97b391 100644
--- a/src/multimedia/controls/qcameraexposurecontrol.h
+++ b/src/multimedia/controls/qcameraexposurecontrol.h
@@ -65,45 +65,30 @@ public:
     ~QCameraExposureControl();
 
     enum ExposureParameter {
-        InvalidParameter = 0,
-        ISO = 1,
-        Aperture = 2,
-        ShutterSpeed = 3,
-        ExposureCompensation = 4,
-        FlashPower = 5,
-        FlashCompensation = 6,
-        SpotMeteringPoint = 7,
+        ISO,
+        Aperture,
+        ShutterSpeed,
+        ExposureCompensation,
+        FlashPower,
+        FlashCompensation,
+        TorchPower,
+        SpotMeteringPoint,
+        ExposureMode,
+        MeteringMode,
         ExtendedExposureParameter = 1000
     };
 
-    enum ParameterFlag {
-        AutomaticValue = 0x01,
-        ReadOnly = 0x02,
-        ContinuousRange = 0x04
-    };
-    Q_DECLARE_FLAGS(ParameterFlags, ParameterFlag)
-
-    virtual QCameraExposure::ExposureMode exposureMode() const = 0;
-    virtual void setExposureMode(QCameraExposure::ExposureMode mode) = 0;
-    virtual bool isExposureModeSupported(QCameraExposure::ExposureMode mode) const = 0;
-
-    virtual QCameraExposure::MeteringMode meteringMode() const = 0;
-    virtual void setMeteringMode(QCameraExposure::MeteringMode mode) = 0;
-    virtual bool isMeteringModeSupported(QCameraExposure::MeteringMode mode) const = 0;
-
     virtual bool isParameterSupported(ExposureParameter parameter) const = 0;
-    virtual QVariant exposureParameter(ExposureParameter parameter) const = 0;
-    virtual ParameterFlags exposureParameterFlags(ExposureParameter parameter) const = 0;
-    virtual QVariantList supportedParameterRange(ExposureParameter parameter) const = 0;
-    virtual bool setExposureParameter(ExposureParameter parameter, const QVariant& value) = 0;
+    virtual QVariantList supportedParameterRange(ExposureParameter parameter, bool *continuous) const = 0;
 
-    virtual QString extendedParameterName(ExposureParameter parameter) = 0;
+    virtual QVariant requestedValue(ExposureParameter parameter) const = 0;
+    virtual QVariant actualValue(ExposureParameter parameter) const = 0;
+    virtual bool setValue(ExposureParameter parameter, const QVariant& value) = 0;
 
 Q_SIGNALS:
-    void flashReady(bool);
-
-    void exposureParameterChanged(int parameter);
-    void exposureParameterRangeChanged(int parameter);
+    void requestedValueChanged(int parameter);
+    void actualValueChanged(int parameter);
+    void parameterRangeChanged(int parameter);
 
 protected:
     QCameraExposureControl(QObject* parent = 0);
@@ -112,11 +97,11 @@ protected:
 #define QCameraExposureControl_iid "com.nokia.Qt.QCameraExposureControl/1.0"
 Q_MEDIA_DECLARE_CONTROL(QCameraExposureControl, QCameraExposureControl_iid)
 
-Q_DECLARE_OPERATORS_FOR_FLAGS(QCameraExposureControl::ParameterFlags)
+QT_END_NAMESPACE
 
-Q_MEDIA_ENUM_DEBUG(QCameraExposureControl, ExposureParameter)
+Q_DECLARE_METATYPE(QCameraExposureControl::ExposureParameter)
 
-QT_END_NAMESPACE
+Q_MEDIA_ENUM_DEBUG(QCameraExposureControl, ExposureParameter)
 
 QT_END_HEADER