Improve the QCameraFocus and QCameraImageProcessing documentation.

Also adds documentation for QCameraFocusZone.

Change-Id: I805806e9a683244b0c03553e00bebb41e6767ff1
Reviewed-by: Dmytro Poplavskiy <dmytro.poplavskiy@nokia.com>

4 files changed, 241 insertions, 31 deletions

diff --git a/doc/src/snippets/multimedia-snippets/camera.cpp b/doc/src/snippets/multimedia-snippets/camera.cpp
index 2cfaf41cc..f3b668f44 100644
--- a/doc/src/snippets/multimedia-snippets/camera.cpp
+++ b/doc/src/snippets/multimedia-snippets/camera.cpp
@@ -45,6 +45,7 @@
 #include "qcameraviewfinder.h"
 #include "qmediarecorder.h"
 #include "qcameraimagecapture.h"
+#include "qcameraimageprocessing.h"
 
 void camera()
 {
@@ -78,5 +79,52 @@ void camera()
     //on shutter button released
     camera->unlock();
     //! [Camera keys]
+}
+
+void cameraimageprocessing()
+{
+    QCamera *camera = 0;
+
+    //! [Camera image whitebalance]
+    camera = new QCamera;
+    QCameraImageProcessing *imageProcessing = camera->imageProcessing();
+
+    if (imageProcessing->isAvailable()) {
+        imageProcessing->setWhiteBalanceMode(QCameraImageProcessing::WhiteBalanceFluorescent);
+    }
+    //! [Camera image whitebalance]
+
+    //! [Camera image denoising]
+    if (imageProcessing->isDenoisingSupported()) {
+        imageProcessing->setDenoisingLevel(3);
+    }
+    //! [Camera image denoising]
+}
+
+void camerafocus()
+{
+    QCamera *camera = 0;
+
+    //! [Camera custom zoom]
+    QCameraFocus *focus = camera->focus();
+    focus->setFocusPointMode(QCameraFocus::FocusPointCustom);
+    focus->setCustomFocusPoint(QPointF(0.25f, 0.75f)); // A point near the bottom left, 25% away from the corner, near that shiny vase
+    //! [Camera custom zoom]
+
+    //! [Camera combined zoom]
+    focus->zoomTo(3.0, 4.0); // Super zoom!
+    //! [Camera combined zoom]
 
+    //! [Camera focus zones]
+    focus->setFocusPointMode(QCameraFocus::FocusPointAuto);
+    QList<QCameraFocusZone> zones = focus->focusZones();
+    foreach (QCameraFocusZone zone, zones) {
+        if (zone.status() == QCameraFocusZone::Focused) {
+            // Draw a green box at zone.area()
+        } else if (zone.status() == QCameraFocusZone::Selected) {
+            // This area is selected for autofocusing, but is not in focus
+            // Draw a yellow box at zone.area()
+        }
+    }
+    //! [Camera focus zones]
 }
diff --git a/src/multimedia/camera/qcamerafocus.cpp b/src/multimedia/camera/qcamerafocus.cpp
index 9b9caed9e..a0b5fc965 100644
--- a/src/multimedia/camera/qcamerafocus.cpp
+++ b/src/multimedia/camera/qcamerafocus.cpp
@@ -103,60 +103,134 @@ public:
     QCameraFocusZone::FocusZoneStatus status;
 };
 
+
+/*!
+    \class QCameraFocusZone
+
+    \brief The QCameraFocusZone class provides information on zones used for autofocusing a camera.
+
+    \inmodule QtMultimedia
+    \ingroup camera
+    \since 1.1
+
+    For cameras that support autofocusing, in order for a camera to autofocus on
+    part of a sensor frame, it considers different zones within the frame.  Which
+    zones to use, and where the zones are located vary between different cameras.
+
+    This class exposes what zones are used by a particular camera, and a list of the
+    zones can be retrieved by a \l QCameraFocus instance.
+
+    You can use this information to present visual feedback - for example, drawing
+    rectangles around areas of the camera frame that are in focus, or changing the
+    color of a zone as it comes into focus.
+
+    \snippet doc/src/snippets/multimedia-snippets/camera.cpp Camera focus zones
+
+    \sa QCameraFocus
+*/
+
+/*!
+    \enum QCameraFocusZone::Status
+
+    \value Invalid      This zone is not valid
+    \value Unused       This zone may be used for autofocusing, but is not currently.
+    \value Selected     This zone is currently being used for autofocusing, but is not in focus.
+    \value Focused      This zone is being used for autofocusing and is currently in focus.
+*/
+
+/*!
+ * \internal
+ * Creates a new, empty QCameraFocusZone.
+ */
 QCameraFocusZone::QCameraFocusZone()
     :d(new QCameraFocusZoneData)
 {
 
 }
 
+/*!
+ * \internal
+ * Creates a new QCameraFocusZone with the supplied \a area and \a status.
+ */
 QCameraFocusZone::QCameraFocusZone(const QRectF &area, QCameraFocusZone::FocusZoneStatus status)
     :d(new QCameraFocusZoneData(area, status))
 {
 }
 
+/*!
+ * Creates a new QCameraFocusZone as a copy of \a other.
+ */
 QCameraFocusZone::QCameraFocusZone(const QCameraFocusZone &other)
     :d(other.d)
 {
 
 }
 
+/*!
+ * Destroys this QCameraFocusZone.
+ */
 QCameraFocusZone::~QCameraFocusZone()
 {
 
 }
 
+/*!
+ * Assigns \a other to this QCameraFocusZone.
+ */
 QCameraFocusZone& QCameraFocusZone::operator=(const QCameraFocusZone &other)
 {
     d = other.d;
     return *this;
 }
 
+/*!
+ * Returns true if this focus zone is the same as \a other.
+ */
 bool QCameraFocusZone::operator==(const QCameraFocusZone &other) const
 {
     return d == other.d ||
            (d->area == other.d->area && d->status == other.d->status);
 }
 
+/*!
+ * Returns true if this focus zone is not the same as \a other.
+ */
 bool QCameraFocusZone::operator!=(const QCameraFocusZone &other) const
 {
     return !(*this == other);
 }
 
+/*!
+ * Returns true if this focus zone has a valid area and status.
+ */
 bool QCameraFocusZone::isValid() const
 {
     return d->status != Invalid && !d->area.isValid();
 }
 
+/*!
+ * Returns the area of the camera frame that this focus zone encompasses.
+ *
+ * Coordinates are in frame relative coordinates - \c QPointF(0,0) is the top
+ * left of the frame, and \c QPointF(1,1) is the bottom right.
+ */
 QRectF QCameraFocusZone::area() const
 {
     return d->area;
 }
 
+/*!
+ * Returns the current status of this focus zone.
+ */
 QCameraFocusZone::FocusZoneStatus QCameraFocusZone::status() const
 {
     return d->status;
 }
 
+/*!
+ * \internal
+ * Sets the current status of this focus zone to \a status.
+ */
 void QCameraFocusZone::setStatus(QCameraFocusZone::FocusZoneStatus status)
 {
     d->status = status;
@@ -166,14 +240,50 @@ void QCameraFocusZone::setStatus(QCameraFocusZone::FocusZoneStatus status)
 /*!
     \class QCameraFocus
 
-
-    \brief The QCameraFocus class provides interface for
-    focus and zoom related camera settings.
+    \brief The QCameraFocus class provides an interface for focus and zoom related camera settings.
 
     \inmodule QtMultimedia
     \ingroup camera
     \since 1.1
 
+    On hardware that supports it, this class lets you adjust the focus
+    or zoom (both optical and digital).  This also includes things
+    like "Macro" mode for close up work (e.g. reading barcodes, or
+    recognising letters), or "touch to focus" - indicating an
+    interesting area of the viewfinder for the hardware to attempt
+    to focus on.
+
+    \snippet doc/src/snippets/multimedia-snippets/camera.cpp Camera custom zoom
+
+    Zooming can be accomplished in a number of ways - usually the more
+    expensive but higher quality approach is an optical zoom, which allows
+    using the full extent of the camera sensor to gather image pixels. In
+    addition it is possible to digitally zoom, which will generally just
+    enlarge part of the sensor frame and throw away other parts.  If the
+    camera hardware supports optical zoom this should generally always
+    be used first.  The \l maximumOpticalZoom() method allows this to be
+    checked.  The \l zoomTo() method allows changing both optical and
+    digital zoom at once.
+
+    \snippet doc/src/snippets/multimedia-snippets/camera.cpp Camera combined zoom
+
+    \section2 Some notes on autofocus
+    Some hardware supports a movable focus lens assembly, and typically
+    this hardware also supports automatically focusing via some heuristic.
+    You can influence this via the \l FocusPointMode setting - typically
+    the center of the frame is brought into focus, but some hardware
+    also supports focusing on any faces detected in the frame, or on
+    a specific point (usually provided by a user in a "touch to focus"
+    scenario).
+
+    This class (in combination with \l QCameraFocusZone)
+    can expose information on what parts of the camera sensor image
+    are in focus or are being used for autofocusing via the \l focusZones()
+    property:
+
+    \snippet doc/src/snippets/multimedia-snippets/camera.cpp Camera focus zones
+
+    \sa QCameraFocusZone
 */
 
 
@@ -212,6 +322,7 @@ void QCameraFocusPrivate::initControls()
 }
 
 /*!
+    \internal
     Construct a QCameraFocus for \a camera.
 */
 
@@ -235,6 +346,8 @@ QCameraFocus::~QCameraFocus()
 
 /*!
     Returns true if focus related settings are supported by this camera.
+
+    You may need to also check if any specific features are supported.
     \since 1.1
 */
 bool QCameraFocus::isAvailable() const
@@ -247,6 +360,9 @@ bool QCameraFocus::isAvailable() const
   \brief The current camera focus mode.
 
   \since 1.1
+
+  This controls the way the camera lens assembly is configured.
+
   \sa QCameraFocus::isFocusModeSupported()
 */
 
@@ -274,9 +390,13 @@ bool QCameraFocus::isFocusModeSupported(QCameraFocus::FocusMode mode) const
 /*!
   \property QCameraFocus::focusPointMode
   \brief The current camera focus point selection mode.
+  \since 1.1
+
+  If the camera focus mode is set to use an autofocusing mode,
+  this property controls the way the camera will select areas
+  of the frame to use for autofocusing.
 
   \sa QCameraFocus::isFocusPointModeSupported()
-  \since 1.1
 */
 
 QCameraFocus::FocusPointMode QCameraFocus::focusPointMode() const
@@ -309,10 +429,10 @@ bool QCameraFocus::isFocusPointModeSupported(QCameraFocus::FocusPointMode mode)
 /*!
   \property QCameraFocus::customFocusPoint
 
-  Position of custom focus point, in relative frame coordinates:
+  This property represents the position of the custom focus point, in relative frame coordinates:
   QPointF(0,0) points to the left top frame point, QPointF(0.5,0.5) points to the frame center.
 
-  Custom focus point is used only in FocusPointCustom focus mode.
+  The custom focus point property is used only in \c FocusPointCustom focus mode.
   \since 1.1
  */
 
@@ -352,7 +472,9 @@ QCameraFocusZoneList QCameraFocus::focusZones() const
 }
 
 /*!
-    Returns the maximum optical zoom
+    Returns the maximum optical zoom.
+
+    This will be \c 1.0 on cameras that do not support optical zoom.
     \since 1.1
 */
 
@@ -363,6 +485,8 @@ qreal QCameraFocus::maximumOpticalZoom() const
 
 /*!
     Returns the maximum digital zoom
+
+    This will be \c 1.0 on cameras that do not support digital zoom.
     \since 1.1
 */
 
@@ -399,6 +523,10 @@ qreal QCameraFocus::digitalZoom() const
 
 /*!
     Set the camera \a optical and \a digital zoom values.
+
+    Since there may be a physical component to move, the change in
+    zoom value may not be instantaneous.
+
     \since 1.1
 */
 void QCameraFocus::zoomTo(qreal optical, qreal digital)
@@ -416,7 +544,7 @@ void QCameraFocus::zoomTo(qreal optical, qreal digital)
     \value AutoFocus            One-shot auto focus mode.
     \value ContinuousFocus      Continuous auto focus mode.
     \value InfinityFocus        Focus strictly to infinity.
-    \value HyperfocalFocus      Focus to hyperfocal distance, with with the maximum depth of field achieved.
+    \value HyperfocalFocus      Focus to hyperfocal distance, with the maximum depth of field achieved.
                                 All objects at distances from half of this
                                 distance out to infinity will be acceptably sharp.
     \value MacroFocus           One shot auto focus to objects close to camera.
@@ -467,9 +595,10 @@ void QCameraFocus::zoomTo(qreal optical, qreal digital)
 /*!
   \fn QCameraFocus::focusZonesChanged()
 
-  Signal is emitted when the set of zones, camera focused on is changed.
+  This signal is emitted when the set of zones used in autofocusing is changed.
 
-  Usually the zones list is changed when the camera is focused.
+  This can change when a zone is focused or loses focus, or new focus zones
+  have been detected.
   \since 1.1
 */
 
diff --git a/src/multimedia/camera/qcameraimageprocessing.cpp b/src/multimedia/camera/qcameraimageprocessing.cpp
index 850606792..eb1818cb1 100644
--- a/src/multimedia/camera/qcameraimageprocessing.cpp
+++ b/src/multimedia/camera/qcameraimageprocessing.cpp
@@ -70,14 +70,35 @@ QT_BEGIN_NAMESPACE
 /*!
     \class QCameraImageProcessing
 
-
-    \brief The QCameraImageProcessing class provides interface for
-    focus and zoom related camera settings.
+    \brief The QCameraImageProcessing class provides an interface for
+    image processing related camera settings.
 
     \inmodule QtMultimedia
     \ingroup camera
     \since 1.1
 
+    After capturing the data for a camera frame, the camera hardware and
+    software performs various image processing tasks to produce a final
+    image.  This includes compensating for ambient light color, reducing
+    noise, as well as making some other adjustments to the image.
+
+    You can retrieve this class from an instance of a \l QCamera object.
+
+    For example, you can set the white balance (or color temperature) used
+    for processing images:
+
+    \snippet doc/src/snippets/multimedia-snippets/camera.cpp Camera image whitebalance
+
+    Or adjust the amount of denoising performed:
+
+    \snippet doc/src/snippets/multimedia-snippets/camera.cpp Camera image denoising
+
+    In some cases changing these settings may result in a longer delay
+    before an image is ready.
+
+    For more information on image processing of camera frames, see \l {Camera Image Processing}.
+
+    \sa QCameraImageProcessingControl
 */
 
 
@@ -169,7 +190,7 @@ bool QCameraImageProcessing::isWhiteBalanceModeSupported(QCameraImageProcessing:
 
 /*!
     Returns the current color temperature if the
-    manual white balance is active, otherwise the
+    current white balance mode is \c WhiteBalanceManual.  For other modes the
     return value is undefined.
     \since 1.1
 */
@@ -185,7 +206,8 @@ int QCameraImageProcessing::manualWhiteBalance() const
 }
 
 /*!
-    Sets manual white balance to \a colorTemperature
+    Sets manual white balance to \a colorTemperature.  This is used
+    when whiteBalanceMode() is set to \c WhiteBalanceManual.  The units are Kelvin.
     \since 1.1
 */
 
@@ -199,7 +221,7 @@ void QCameraImageProcessing::setManualWhiteBalance(int colorTemperature)
 }
 
 /*!
-    Return the contrast.
+    Returns the contrast adjustment setting.
     \since 1.1
 */
 int QCameraImageProcessing::contrast() const
@@ -213,9 +235,9 @@ int QCameraImageProcessing::contrast() const
 }
 
 /*!
-    Set the contrast to \a value.
+    Set the contrast adjustment to \a value.
 
-    Valid contrast values range between -100 and 100, the default is 0.
+    Valid contrast adjustment values range between -100 and 100, with a default of 0.
     \since 1.1
 */
 void QCameraImageProcessing::setContrast(int value)
@@ -226,7 +248,7 @@ void QCameraImageProcessing::setContrast(int value)
 }
 
 /*!
-    Returns the saturation value.
+    Returns the saturation adjustment value.
     \since 1.1
 */
 int QCameraImageProcessing::saturation() const
@@ -240,9 +262,9 @@ int QCameraImageProcessing::saturation() const
 }
 
 /*!
-    Sets the saturation value to \a value.
+    Sets the saturation adjustment value to \a value.
 
-    Valid saturation values range between -100 and 100, the default is 0.
+    Valid saturation values range between -100 and 100, with a default of 0.
     \since 1.1
 */
 
@@ -269,6 +291,9 @@ bool QCameraImageProcessing::isSharpeningSupported() const
 
 /*!
     Returns the sharpening level.
+
+    This may be \c DefaultSharpening if no particular sharpening level has been applied.
+
     \since 1.1
 */
 int QCameraImageProcessing::sharpeningLevel() const
@@ -279,7 +304,7 @@ int QCameraImageProcessing::sharpeningLevel() const
         value = d_func()->imageControl->processingParameter(QCameraImageProcessingControl::Sharpening);
 
     if (value.isNull())
-        return -1;
+        return DefaultSharpening;
     else
         return value.toInt();
 }
@@ -287,8 +312,10 @@ int QCameraImageProcessing::sharpeningLevel() const
 /*!
     Sets the sharpening \a level.
 
-    Valid sharpening level values range between -1 for default sharpening level,
-    0 for sharpening disabled and 100 for maximum sharpening applied.
+    If \c DefaultSharpening is supplied, the camera will decide what sharpening
+    to perform.  Otherwise a level of 0 will disable sharpening, and a level of 100
+    corresponds to maximum sharpening applied.
+
     \since 1.1
 */
 
@@ -297,7 +324,7 @@ void QCameraImageProcessing::setSharpeningLevel(int level)
     Q_D(QCameraImageProcessing);
     if (d->imageControl)
         d->imageControl->setProcessingParameter(QCameraImageProcessingControl::Sharpening,
-                                                level == -1 ? QVariant() : QVariant(level));
+                                                level == DefaultSharpening ? QVariant() : QVariant(level));
 }
 
 /*!
@@ -313,7 +340,9 @@ bool QCameraImageProcessing::isDenoisingSupported() const
 }
 
 /*!
-    Returns the denoising level.
+    Returns the denoising level.  This may be \c DefaultDenoising if no
+    particular value has been set.
+
     \since 1.1
 */
 int QCameraImageProcessing::denoisingLevel() const
@@ -324,7 +353,7 @@ int QCameraImageProcessing::denoisingLevel() const
         value = d_func()->imageControl->processingParameter(QCameraImageProcessingControl::Denoising);
 
     if (value.isNull())
-        return -1;
+        return DefaultDenoising;
     else
         return value.toInt();
 }
@@ -332,8 +361,10 @@ int QCameraImageProcessing::denoisingLevel() const
 /*!
     Sets the denoising \a level.
 
-    Valid denoising level values range between -1 for default denoising level,
-    0 for denoising disabled and 100 for maximum denoising applied.
+    If \c DefaultDenoising is supplied, the camera will decide what denoising
+    to perform.  Otherwise a level of 0 will disable denoising, and a level of 100
+    corresponds to maximum denoising applied.
+
     \since 1.1
 */
 void QCameraImageProcessing::setDenoisingLevel(int level)
@@ -341,7 +372,7 @@ void QCameraImageProcessing::setDenoisingLevel(int level)
     Q_D(QCameraImageProcessing);
     if (d->imageControl)
         d->imageControl->setProcessingParameter(QCameraImageProcessingControl::Denoising,
-                                                level == -1 ? QVariant() : QVariant(level));
+                                                level == DefaultDenoising ? QVariant() : QVariant(level));
 }
 
 
@@ -354,7 +385,7 @@ void QCameraImageProcessing::setDenoisingLevel(int level)
     \value WhiteBalanceSunlight     Sunlight white balance mode.
     \value WhiteBalanceCloudy       Cloudy white balance mode.
     \value WhiteBalanceShade        Shade white balance mode.
-    \value WhiteBalanceTungsten     Tungsten white balance mode.
+    \value WhiteBalanceTungsten     Tungsten (incandescent) white balance mode.
     \value WhiteBalanceFluorescent  Fluorescent white balance mode.
     \value WhiteBalanceFlash        Flash white balance mode.
     \value WhiteBalanceSunset       Sunset white balance mode.
diff --git a/src/multimedia/camera/qcameraimageprocessing.h b/src/multimedia/camera/qcameraimageprocessing.h
index 42a7eb589..8eec7b583 100644
--- a/src/multimedia/camera/qcameraimageprocessing.h
+++ b/src/multimedia/camera/qcameraimageprocessing.h
@@ -95,10 +95,12 @@ public:
     int saturation() const;
     void setSaturation(int value);
 
+    static const int DefaultSharpening = -1;
     bool isSharpeningSupported() const;
     int sharpeningLevel() const;
     void setSharpeningLevel(int value);
 
+    static const int DefaultDenoising = -1;
     bool isDenoisingSupported() const;
     int denoisingLevel() const;
     void setDenoisingLevel(int value);