QCamera capture documentation fixes

Added documentation for camera capture queue behavior.

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

3 files changed, 33 insertions, 1 deletions

diff --git a/src/imports/multimedia/qdeclarativecameracapture.cpp b/src/imports/multimedia/qdeclarativecameracapture.cpp
index 9dd036ba8..585b39223 100644
--- a/src/imports/multimedia/qdeclarativecameracapture.cpp
+++ b/src/imports/multimedia/qdeclarativecameracapture.cpp
@@ -124,6 +124,12 @@ QDeclarativeCameraCapture::~QDeclarativeCameraCapture()
     \property QDeclarativeCameraCapture::ready
 
     Indicates camera is ready to capture photo.
+
+   It's permissible to call capture() while the camera is active
+   regardless of isReadyForCapture property value.
+   If camera is not ready to capture image immediately,
+   the capture request is queued with all the related camera settings
+   to be executed as soon as possible.
 */
 bool QDeclarativeCameraCapture::isReadyForCapture() const
 {
@@ -139,6 +145,10 @@ bool QDeclarativeCameraCapture::isReadyForCapture() const
 
     The image will be captured to the default system location.
 
+    Camera saves all the capture parameters like exposure settings or
+    image processing parameters, so changes to camera paramaters after
+    capture() is called do not affect previous capture requests.
+
     CameraCapture::capture returns the capture requestId parameter, used with
     imageExposed(), imageCaptured(), imageMetadataAvailable() and imageSaved() signals.
 */
diff --git a/src/multimedia/camera/qcameraimagecapture.cpp b/src/multimedia/camera/qcameraimagecapture.cpp
index 0754963ae..fd516c0e4 100644
--- a/src/multimedia/camera/qcameraimagecapture.cpp
+++ b/src/multimedia/camera/qcameraimagecapture.cpp
@@ -493,6 +493,12 @@ void QCameraImageCapture::setCaptureDestination(QCameraImageCapture::CaptureDest
 /*!
   \property QCameraImageCapture::readyForCapture
    Indicates the service is ready to capture a an image immediately.
+
+   It's permissible to call capture() while the camera status is QCamera::ActiveStatus
+   regardless of isReadyForCapture property value.
+   If camera is not ready to capture image immediately,
+   the capture request is queued with all the related camera settings
+   to be executed as soon as possible.
 */
 
 bool QCameraImageCapture::isReadyForCapture() const
@@ -513,7 +519,8 @@ bool QCameraImageCapture::isReadyForCapture() const
 /*!
     Capture the image and save it to \a file.
     This operation is asynchronous in majority of cases,
-    followed by signals QCameraImageCapture::imageCaptured(), QCameraImageCapture::imageSaved()
+    followed by signals QCameraImageCapture::imageExposed(),
+    QCameraImageCapture::imageCaptured(), QCameraImageCapture::imageSaved()
     or QCameraImageCapture::error().
 
     If an empty \a file is passed, the camera backend choses
@@ -521,6 +528,10 @@ bool QCameraImageCapture::isReadyForCapture() const
     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 paramaters after
+    capture() is called do not affect previous capture requests.
+
     QCameraImageCapture::capture returns the capture Id parameter, used with
     imageExposed(), imageCaptured() and imageSaved() signals.
 */
diff --git a/src/multimedia/controls/qcameraimagecapturecontrol.cpp b/src/multimedia/controls/qcameraimagecapturecontrol.cpp
index 3609479fa..5a731682d 100644
--- a/src/multimedia/controls/qcameraimagecapturecontrol.cpp
+++ b/src/multimedia/controls/qcameraimagecapturecontrol.cpp
@@ -95,6 +95,12 @@ QCameraImageCaptureControl::~QCameraImageCaptureControl()
     hardware initialized, flash is charged, etc).
 
     Returns true if the camera is ready for capture; and false if it is not.
+
+    It's permissible to call capture() while the camera status is QCamera::ActiveStatus
+    regardless of isReadyForCapture property value.
+    If camera is not ready to capture image immediately,
+    the capture request is queued with all the related camera settings
+    to be executed as soon as possible.
 */
 
 /*!
@@ -111,6 +117,11 @@ QCameraImageCaptureControl::~QCameraImageCaptureControl()
     in this case the service should use the system specific place
     and file naming scheme.
 
+    The Camera service should save all the capture parameters
+    like exposure settings or image processing parameters,
+    so changes to camera paramaters after capture() is called
+    do not affect previous capture requests.
+
     Returns the capture request id number, which is used later
     with imageExposed(), imageCaptured() and imageSaved() signals.
 */