1 files changed, 262 insertions, 0 deletions
diff --git a/src/multimedia/doc/src/cameraoverview.qdoc b/src/multimedia/doc/src/cameraoverview.qdoc
new file mode 100644
index 000000000..a3698ed4b
--- /dev/null
+++ b/src/multimedia/doc/src/cameraoverview.qdoc
@@ -0,0 +1,262 @@
+/****************************************************************************
+**
+** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** GNU Free Documentation License
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file.
+**
+** Other Usage
+** Alternatively, this file may be used in accordance with the terms
+** and conditions contained in a signed written agreement between you
+** and Nokia.
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+\page cameraoverview.html
+\title Camera Overview
+\brief Camera viewfinder, still image capture, and video recording.
+
+The Qt Multimedia API provides a number of camera related classes, so you
+can access images and videos from mobile device cameras or webcameras.
+There are both C++ and QML APIs for common tasks.
+
+\section1 Camera Features
+
+In order to use the camera classes a quick overview of the way a camera
+works is needed.  If you're already familiar with this, you can skip ahead to
+\l {camera-tldr}{Camera implementation details}.
+
+[TBD - this needs a diagram]
+* Camera features
+ * lens -> sensors -> image processing -> capture/recording
+
+\section2 The Lens Assembly
+At one end of the camera assembly is the lens assembly (one or
+more lenses, arranged to focus light onto the sensor).  The lenses
+themselves can sometimes be moved to adjust things like focus and zoom,
+or they might be fixed in an arrangement to give a good balance between
+objects in focus, and cost.
+
+Some lens assemblies can automatically be adjusted so that
+an object at different distances from the camera can be kept in focus.
+This is usually done by measuring how sharp a particular area of the
+frame is, and by adjusting the lens assembly until it is maximally
+sharp.  In some cases the camera will always use the center of the
+frame for this.  Other cameras may also allow the region to focus
+to be specified (for "touch to zoom", or "face zoom" features).
+
+\section2 The Sensor
+Once light arrives at the sensor, it gets converted into digital pixels.
+This process can depend on a number of things but ultimately comes down
+to two things - how long the conversion is allowed to take, and how
+bright the light is.  The longer a conversion can take, the better the
+quality.  Using a flash can assist with letting more light hit the sensor,
+allowing it to convert pixels faster, giving better quality for the same
+amount of time.  Conversely, allowing a longer conversion time can let you
+take photos in darker environments, as long as the camera is steady.
+
+\section2 Image Processing
+After the image has been captured by the sensor, the camera firmware performs
+various image processing tasks on it to compensate for various sensor
+characteristics, current lighting, and desired image properties.  Faster sensor
+pixel conversion times tend to introduce digital noise, so some amount of image
+processing can be done to remove this based on the camera sensor settings.
+
+The color of the image can also be adjusted at this stage to compensate for
+different light sources - fluorescent lights and sunlight give very different
+appearances to the same object, so the image can be adjusted based on the
+white balance of the picture (due to the different color temperatures of the
+light sources).
+
+Some forms of "special effects" can also be performed at this stage.  Black
+and white, sepia, or "negative" style images can be produced.
+
+\section2 Recording for Posterity
+Finally, once a perfectly focused, exposed and processed image has been
+created, it can be put to good use.  Camera images can be further processed
+by application code (for example, to detect barcodes, or to stitch together a
+panoramic image), or saved to a common format like JPEG, or used to create a movie.
+Many of these tasks have classes to assist them.
+
+\target camera-tldr
+\section1 Camera Implementation Details
+\section2 Viewfinder
+
+While not strictly necessary, it's often useful to be able to see
+what the camera is pointing at.  Most digital cameras allow an image
+feed from the camera sensor at a lower resolution (usually up to
+the size of the display of the camera) so you can compose
+a photo or video, and then switch to a slower but higher resolution
+mode for capturing the image.
+
+Depending on whether you're using QML or C++, you can do this in multiple ways.
+In QML, you can use \l Camera and \l VideoOutput together to show a
+simple viewfinder:
+
+\qml
+    Camera {
+        id: camera
+        // You can adjust various settings in here
+    }
+
+    VideoOutput {
+        source: camera
+    }
+\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
+is useful for QGraphicsView.
+
+    \snippet doc/src/snippets/multimedia-snippets/camera.cpp Camera overview viewfinder
+
+For advanced usage (like processing viewfinder frames as they come, to detect
+objects or patterns), you can also derive from \l QAbstractVideoSurface and
+set that as the viewfinder for the QCamera object.  In this case you will
+need to render the viewfinder image yourself.
+
+    \snippet doc/src/snippets/multimedia-snippets/camera.cpp Camera overview surface
+
+\section2 Still Images
+
+After setting up a viewfinder and finding something photogenic,
+to capture an image we need to initialize a new QCameraImageCapture
+object. All that is then needed is to start the camera, lock it so
+that things are in focus and the settings are not different from the
+viewfinder while the image capture occurs, capture the image, and
+finally unlock the camera ready for the next photo.
+
+    \snippet doc/src/snippets/multimedia-snippets/camera.cpp Camera overview capture
+
+\section2 Movies
+
+Previously we saw code that allowed the capture of a still image. Recording
+video requires the use of a \l QMediaRecorder object.
+
+To record video we need to create a camera object as before but this time as
+well as creating a viewfinder, we will also initialize a media recorder object.
+
+    \snippet doc/src/snippets/multimedia-snippets/camera.cpp Camera overview movie
+
+Signals from the \e mediaRecorder can be connected to slots to react to
+changes in the state of the recorder or error events. Recording itself
+starts with the \l {QMediaRecorder::record()}{record()} function of
+mediaRecorder being called, this causes the signal \l
+{QMediaRecorder::stateChanged()}{stateChanged()} to be emitted. The
+recording process can be changed with the \l {QMediaRecorder::record()}{record()},
+\l {QMediaRecorder::stop()}{stop()} and \l {QMediaRecorder::setMuted()}{setMuted()}
+slots in \l QMediaRecorder.
+
+\section2 Controlling the Imaging Pipeline
+
+Now that the basics of capturing images or movies are covered, there are a number
+of ways to control the imaging pipeline to implement some interesting techniques.
+As explained earlier, several physical and electronic elements combine to determine
+the final images, and you can control them with different classes.
+
+\section3 Focus and Zoom
+
+Focusing (and zoom) is managed primarily by the \l QCameraFocus class.
+QCameraFocus allows the developer to set the general policy by means of the
+enums for the \l {QCameraFocus::FocusMode}{FocusMode} and the
+\l {QCameraFocus::FocusPointMode}{FocusPointMode}. \l {QCameraFocus::FocusMode}{FocusMode}
+deals with settings such as \l {QCameraFocus::FocusMode}{AutoFocus},
+\l {QCameraFocus::FocusMode}{ContinuousFocus} and \l {QCameraFocus::FocusMode}{InfinityFocus},
+whereas \l {QCameraFocus::FocusMode}{FocusPointMode} deals with the
+various focus zones within the view that are used for autofocus modes. \l {QCameraFocus::FocusMode}{FocusPointMode}
+has support for face recognition (where the camera supports it), center focus and a custom
+focus where the focus point can be specified.
+
+For camera hardware that supports it, \l {QCameraFocus::FocusMode}{Macro focus} allows
+imaging of things that are close to the sensor.  This is useful in applications like
+barcode recognition, or business card scanning.
+
+In addition to focus, QCameraFocus allows you to control any available optical or
+digital zoom.  In general, optical zoom is higher quality, but more expensive to
+manufacture, so the available zoom range might be limited (or fixed to unity).
+
+\section3 Exposure, Aperture, Shutter Speed and Flash
+
+There are a number of settings that affect the amount of light that hits the
+camera sensor, and hence the quality of the resulting image.  The \l QCameraExposure
+class allows you to adjust these settings.  You can use this class to implement
+some techniques like High Dynamic Range (HDR) photos by locking the exposure
+parameters (with \l {QCamera::searchAndLock()}), or motion blur by setting slow shutter speeds
+with small apertures.
+
+The main settings for automatic image taking are the \l {QCameraExposure::ExposureMode}{exposure mode}
+and \l {QCameraExposure::FlashMode}{flash mode}.  Several other settings (aperture, ISO setting,
+ shutter speed) are usually managed automatically but can also be overridden if desired.
+
+You can also adjust the \l {QCameraExposure::meteringMode()} to control which parts
+of the camera frame to measure exposure at.  Some camera implementations also allow
+you to specify a specific point that should be used for exposure metering - this is
+useful if you can let the user touch or click on an interesting part of the viewfinder,
+and then use this point so that the image exposure is best at that point.
+
+Finally, you can control the flash hardware (if present) using this class.  In some cases
+the hardware may also double as a torch (typically when the flash is LED based, rather than
+a xenon or other bulb).  See also \l {Torch} for an easy to use API for
+torch functionality.
+
+\target camera_image_processing
+\section3 Image Processing
+
+The QCameraImageProcessing class lets you adjust the image processing
+part of the pipeline.  This includes the \l {QCameraImageProcessing::WhiteBalanceMode}{white balance}
+(or color temperature), \l {QCameraImageProcessing::contrast()}{contrast},
+\l {QCameraImageProcessing::saturation()}{saturation}, \l {QCameraImageProcessing::setSharpeningLevel()}{sharpening}
+and \l {QCameraImageProcessing::setDenoisingLevel()}{denoising}.  Most cameras support automatic settings
+for all of these, so you shouldn't need to adjust them unless the user wants a specific setting.
+
+If you're taking a series of images (for example, to stitch them together for
+a panoramic image), you should lock the image processing settings so that all the
+images taken appear similar with \e {QCamera::lock(QCamera::LockWhiteBalance)}/
+
+\section3 Canceling Asynchronous Operations
+
+Various operations such as image capture and auto focusing occur
+asynchrously. These operations can often be canceled by the start of a new
+operation as long as this is supported by the camera. For image capture,
+the operation can be canceled by calling
+\l {QCameraImageCapture::cancelCapture()}{cancelCapture()}. For AutoFocus,
+autoexposure or white balance cancellation can be done by calling
+\e {QCamera::unlock(QCamera::LockFocus)}.
+
+\section1 Examples
+
+There are both C++ and QML examples available.
+
+\section2 C++ Examples
+
+\annotatedlist camera_examples
+
+\section2 QML Examples
+
+\annotatedlist camera_examples_qml
+
+\section1 Reference Documentation
+
+\section2 C++ Classes
+
+\annotatedlist multimedia_camera
+
+\section2 QML Types
+
+\annotatedlist camera_qml
+
+*/