New QCameraInfo class.

The class allows to get the list of available cameras on the system as
well as getting some static information about them such as their unique
ID, display name, physical position and sensor orientation.

This makes QCamera::availableDevices() and QCamera::deviceDescription()
obsolete.

This patch contains the API, documentation and auto-tests but not the
actual implementation by each backend (except for retrieving the default
camera device).

[ChangeLog][QtMultimedia] Added new QCameraInfo class
[ChangeLog][QtMultimedia] QCamera: availableDevices() and
deviceDescription() are deprecated, use QCameraInfo instead

Change-Id: I64fd65729ab26a789468979ed5444ee90bb82cd0
Reviewed-by: Christian Stromme <christian.stromme@digia.com>

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

@@ -42,11 +42,15 @@
 /* Camera snippets */
 
 #include "qcamera.h"
+#include "qcamerainfo.h"
 #include "qcameraviewfinder.h"
 #include "qmediarecorder.h"
 #include "qcameraimagecapture.h"
 #include "qcameraimageprocessing.h"
 #include "qabstractvideosurface.h"
+#include <QtGui/qscreen.h>
+#include <QtGui/qguiapplication.h>
+#include <QtGui/qimage.h>
 
 /* Globals so that everything is consistent. */
 QCamera *camera = 0;
@@ -94,6 +98,32 @@ void overview_surface()
     //! [Camera overview surface]
 }
 
+void overview_viewfinder_orientation()
+{
+    QCamera camera;
+
+    //! [Camera overview viewfinder orientation]
+    // Assuming a QImage has been created from the QVideoFrame that needs to be presented
+    QImage videoFrame;
+    QCameraInfo cameraInfo(camera); // needed to get the camera sensor position and orientation
+
+    // Get the current display orientation
+    const QScreen *screen = QGuiApplication::primaryScreen();
+    const int screenAngle = screen->angleBetween(screen->nativeOrientation(), screen->orientation());
+
+    int rotation;
+    if (cameraInfo.position() == QCamera::BackFace) {
+        rotation = (cameraInfo.orientation() - screenAngle) % 360;
+    } else {
+        // Front position, compensate the mirror
+        rotation = (360 - cameraInfo.orientation() + screenAngle) % 360;
+    }
+
+    // Rotate the frame so it always shows in the correct orientation
+    videoFrame = videoFrame.transformed(QTransform().rotate(rotation));
+    //! [Camera overview viewfinder orientation]
+}
+
 void overview_still()
 {
     //! [Camera overview capture]
@@ -130,6 +160,41 @@ void overview_movie()
     //! [Camera overview movie]
 }
 
+void camera_listing()
+{
+    //! [Camera listing]
+    QList<QCameraInfo> cameras = QCameraInfo::availableCameras();
+    foreach (const QCameraInfo &cameraInfo, cameras)
+        qDebug() << cameraInfo.deviceName();
+    //! [Camera listing]
+}
+
+void camera_selection()
+{
+    //! [Camera selection]
+    QList<QCameraInfo> cameras = QCameraInfo::availableCameras();
+    foreach (const QCameraInfo &cameraInfo, cameras) {
+        if (cameraInfo.deviceName() == "mycamera")
+            camera = new QCamera(cameraInfo);
+    }
+    //! [Camera selection]
+}
+
+void camera_info()
+{
+    //! [Camera info]
+    QCamera myCamera;
+    QCameraInfo cameraInfo(myCamera);
+
+    if (cameraInfo.position() == QCamera::FrontFace)
+        qDebug() << "The camera is on the front face of the hardware system.";
+    else if (cameraInfo.position() == QCamera::BackFace)
+        qDebug() << "The camera is on the back face of the hardware system.";
+
+    qDebug() << "The camera sensor orientation is " << cameraInfo.orientation() << " degrees.";
+    //! [Camera info]
+}
+
 void camera_blah()
 {
     //! [Camera]

src/multimedia/doc/src/cameraoverview.qdoc

@@ -118,7 +118,7 @@ VideoOutput {
 \endqml
 
 In C++, your choice depends on whether you are using widgets, or QGraphicsView.
-The \l QVideoWidget class is used in the widgets case, and \l QGraphicsVideoItem
+The \l QCameraViewfinder class is used in the widgets case, and \l QGraphicsVideoItem
 is useful for QGraphicsView.
 
     \snippet multimedia-snippets/camera.cpp Camera overview viewfinder
@@ -130,6 +130,15 @@ need to render the viewfinder image yourself.
 
     \snippet multimedia-snippets/camera.cpp Camera overview surface
 
+On mobile devices, the viewfinder image might not always be in the orientation you would expect.
+The camera sensors on these devices are often mounted in landscape while the natural
+orientation of the screen is portrait. This results in the image appearing sideways or inverted
+depending on the device orientation. In order to reflect on screen what the user actually sees, you
+should make sure the viewfinder frames are always rotated to the correct orientation, taking into
+account the camera sensor orientation and the current display orientation.
+
+    \snippet multimedia-snippets/camera.cpp Camera overview viewfinder orientation
+
 \section2 Still Images
 
 After setting up a viewfinder and finding something photogenic,