New camera selection API in QML.

Also added a new QtMultimedia global object which makes it possible
to retrieve the list of available cameras. It can be extended with
new utility functions in the future.

Includes documentation, example and auto tests.

Task-number: QTBUG-23770
Change-Id: Ifea076329c3582ea99246ee1131853344a7b773f
Reviewed-by: Christian Stromme <christian.stromme@digia.com>

src/multimedia/doc/snippets/multimedia-snippets/camera.cpp

@@ -58,6 +58,16 @@ QCameraViewfinder *viewfinder = 0;
 QMediaRecorder *recorder = 0;
 QCameraImageCapture *imageCapture = 0;
 
+//! [Camera overview check]
+bool checkCameraAvailability()
+{
+    if (QCameraInfo::availableCameras().count() > 0)
+        return true;
+    else
+        return false;
+}
+//! [Camera overview check]
+
 void overview_viewfinder()
 {
     //! [Camera overview viewfinder]
@@ -70,6 +80,13 @@ void overview_viewfinder()
     //! [Camera overview viewfinder]
 }
 
+void overview_camera_by_position()
+{
+    //! [Camera overview position]
+    camera = new QCamera(QCamera::FrontFace);
+    //! [Camera overview position]
+}
+
 // -.-
 class MyVideoSurface : public QAbstractVideoSurface
 {

src/multimedia/doc/src/cameraoverview.qdoc

@@ -90,6 +90,65 @@ Many of these tasks have classes to assist them.
 
 \target camera-tldr
 \section1 Camera Implementation Details
+\section2 Detecting and Selecting Camera
+
+Before using the camera APIs, you should check that a camera is available at runtime. If there
+is none, you could for example disable camera related features in your application. To perform this
+check in C++, use the \l QCameraInfo::availableCameras() function, as shown in the example below:
+
+    \snippet multimedia-snippets/camera.cpp Camera overview check
+
+In QML, use the \l{QtMultimedia::QtMultimedia::availableCameras}{QtMultimedia.availableCameras}
+property:
+
+\qml
+import QtQuick 2.0
+import QtMultimedia 5.4
+
+Item {
+    property bool isCameraAvailable: QtMultimedia.availableCameras.length > 0
+}
+\endqml
+
+After determining whether a camera is available, access it using the \l QCamera class in C++ or
+the \l Camera type in QML.
+
+When multiple cameras are available, you can specify which one to use.
+
+In C++:
+
+     \snippet multimedia-snippets/camera.cpp Camera selection
+
+In QML, you can set the \c Camera \l{Camera::deviceId}{deviceId} property. All available IDs can
+be retrieved from \l{QtMultimedia::QtMultimedia::availableCameras}{QtMultimedia.availableCameras}:
+
+\qml
+Camera {
+    deviceId: QtMultimedia.availableCameras[0].deviceId
+}
+\endqml
+
+You can also select the camera by its physical position on the system rather than its device ID.
+This is useful on mobile devices, which often have a front-facing and a back-facing camera.
+
+In C++:
+
+    \snippet multimedia-snippets/camera.cpp Camera overview position
+
+In QML:
+
+\qml
+Camera {
+    position: Camera.FrontFace
+}
+\endqml
+
+If neither device ID nor position is specified, the default camera will be used. On desktop
+platforms, the default camera is set by the user in the system settings. On a mobile device, the
+back-facing camera is usually the default camera. You can get information about the default camera
+using \l QCameraInfo::defaultCamera() in C++ or
+\l{QtMultimedia::QtMultimedia::defaultCamera}{QtMultimedia.defaultCamera} in QML.
+
 \section2 Viewfinder
 
 While not strictly necessary, it's often useful to be able to see
@@ -105,7 +164,7 @@ simple viewfinder:
 
 \qml
 import QtQuick 2.0
-import QtMultimedia 5.0
+import QtMultimedia 5.4
 
 VideoOutput {
     source: camera

src/multimedia/doc/src/multimedia.qdoc

@@ -177,7 +177,7 @@ what changed, and what you might need to change when porting code.
 \section2 QML Types
 The QML types are accessed by using:
 \code
-import QtMultimedia 5.0
+import QtMultimedia 5.4
 \endcode
 \annotatedlist multimedia_qml
 The following types are accessed by using \l{Qt Audio Engine QML Types}{Qt Audio Engine}:

src/multimedia/doc/src/qtmultimedia-index.qdoc

@@ -46,7 +46,7 @@
     import statement in your \c {.qml} file.
 
     \code
-     import QtMultimedia 5.0
+     import QtMultimedia 5.4
     \endcode
 
     If you intend to use the C++ classes in your application, include the C++

src/multimedia/doc/src/qtmultimedia5.qdoc

@@ -26,7 +26,7 @@
 ****************************************************************************/
 
 /*!
-\qmlmodule QtMultimedia 5.0
+\qmlmodule QtMultimedia 5.4
 \title Qt Multimedia QML Types
 \ingroup qmlmodules
 \brief Provides QML types for multimedia support.
@@ -42,7 +42,7 @@ The QML types for \l{Qt Multimedia} support the basic use cases such as:
 The QML types can be imported into your application using the following import
 statement in your .qml file:
 \code
-import QtMultimedia 5.0
+import QtMultimedia 5.4
 \endcode
 
 \section1 QML types