From bd9484ddca2780c4b1266849c00b1024e9b1c7cf Mon Sep 17 00:00:00 2001 From: Michael Goddard Date: Mon, 13 Feb 2012 21:05:35 +1000 Subject: Tweak some more documentation. A lot of the previous Qt Mobility API methods were still present, so they are gone now. Also removed some of the C++ documentation since it's not public API anyway. Made a group for camera QML APIs and used that for the list in the camera overview documentation. Change-Id: I0864bd2230a42596e951b68d0df1211766c90dfc Reviewed-by: Jonas Rabbe --- src/imports/multimedia/qdeclarativecamera.cpp | 222 ++++++++------------- .../multimedia/qdeclarativecameracapture.cpp | 1 + .../multimedia/qdeclarativecameraexposure.cpp | 22 +- src/imports/multimedia/qdeclarativecameraflash.cpp | 1 + src/imports/multimedia/qdeclarativecamerafocus.cpp | 1 + .../qdeclarativecameraimageprocessing.cpp | 1 + .../multimedia/qdeclarativecamerarecorder.cpp | 1 + 7 files changed, 106 insertions(+), 143 deletions(-) (limited to 'src') diff --git a/src/imports/multimedia/qdeclarativecamera.cpp b/src/imports/multimedia/qdeclarativecamera.cpp index 31f7d825e..b03067f77 100644 --- a/src/imports/multimedia/qdeclarativecamera.cpp +++ b/src/imports/multimedia/qdeclarativecamera.cpp @@ -70,13 +70,18 @@ void QDeclarativeCamera::_q_updateState(QCamera::State state) /*! \qmlclass Camera QDeclarativeCamera - \brief The Camera element allows you to add camera viewfinder to a scene. + \brief The Camera element allows you to access viewfinder frames, and take photos and movies. \ingroup multimedia_qml + \ingroup camera_qml \inherits Item This element is part of the \bold{QtMultimedia 5.0} module. + You can use the \c Camera element to capture images and movies from a camera, and manipulate + the capture and processing settings that get applied to the images. To display the + viewfinder you can use a \l VideoOutput element with the Camera element set as the source. + \qml import QtQuick 2.0 import QtMultimedia 5.0 @@ -93,8 +98,10 @@ void QDeclarativeCamera::_q_updateState(QCamera::State state) flash.mode: Camera.FlashRedEyeReduction - onImageCaptured: { - photoPreview.source = preview // Show the preview in an Image element + imageCapture { + onImageCaptured: { + photoPreview.source = preview // Show the preview in an Image element + } } } @@ -108,8 +115,35 @@ void QDeclarativeCamera::_q_updateState(QCamera::State state) } \endqml - You can use the \c Camera element to capture images from a camera, and manipulate the capture and - processing settings that get applied to the image. + The various settings and functionality of the Camera stack is spread + across a few different child properties of Camera. + + \table + \header \o Property \o Description + \row \o \l {CameraCapture} {imageCapture} + \o Methods and properties for capturing still images. + \row \o \l {CameraRecorder} {videoRecording} + \o Methods and properties for capturing movies. + \row \o \l {CameraExposure} {exposure} + \o Methods and properties for adjusting exposure (aperture, shutter speed etc). + \row \o \l {CameraFocus} {focus} + \o Methods and properties for adjusting focus and providing feedback on autofocus progress. + \row \o \l {CameraFlash} {flash} + \o Methods and properties for controlling the camera flash. + \row \o \l {CameraImageProcessing} {imageProcessing} + \o Methods and properties for adjusting camera image processing parameters. + \endtable + + Basic camera state management, error reporting, and simple zoom properties are + available in the Camera element itself. For integration with C++ code, the + \l mediaObject property allows you to access the standard QtMultimedia camera + controls. + + Many of the camera settings may take some time to apply, and might be limited + to certain supported values depending on the hardware. Several camera settings + support both automatic and manual modes, with the current actual setting being + used being exposed. + */ /*! @@ -214,51 +248,30 @@ void QDeclarativeCamera::setCaptureMode(QDeclarativeCamera::CaptureMode mode) \table \header \o Value \o Description \row \o UnloadedState - \o The initial camera state, with camera not loaded, - the camera capabilities except of supported capture modes - are unknown. + \o The initial camera state, with the camera not loaded. + The camera capabilities (with the exception of supported capture modes) + are unknown. This state saves the most power, but takes the longest + time to be ready for capture. + While the supported settings are unknown in this state, - it's allowed to set the camera capture settings like codec, + you can still set the camera capture settings like codec, resolution, or frame rate. \row \o LoadedState \o The camera is loaded and ready to be configured. - In the Idle state it's allowed to query camera capabilities, - set capture resolution, codecs, etc. + In the Idle state you can query camera capabilities, + set capture resolution, codecs, and so on. The viewfinder is not active in the loaded state. \row \o ActiveState - \o In the active state as soon as camera is started - the viewfinder displays video frames and the - camera is ready for capture. + \o In the active state the viewfinder frames are available + and the camera is ready for capture. \endtable The default camera state is ActiveState. */ -/*! - \enum QDeclarativeCamera::State - \value UnloadedState - The initial camera state, with camera not loaded, - the camera capabilities except of supported capture modes - are unknown. - While the supported settings are unknown in this state, - it's allowed to set the camera capture settings like codec, - resolution, or frame rate. - - \value LoadedState - The camera is loaded and ready to be configured. - In the Idle state it's allowed to query camera capabilities, - set capture resolution, codecs, etc. - The viewfinder is not active in the loaded state. - - \value ActiveState - In the active state as soon as camera is started - the viewfinder displays video frames and the - camera is ready for capture. -*/ - QDeclarativeCamera::State QDeclarativeCamera::cameraState() const { return m_componentComplete ? QDeclarativeCamera::State(m_camera->state()) : m_pendingState; @@ -288,7 +301,9 @@ void QDeclarativeCamera::setCameraState(QDeclarativeCamera::State state) \qmlmethod Camera::start() \fn QDeclarativeCamera::start() - Starts the camera. + Starts the camera. Viewfinder frames will + be available and image or movie capture will + be possible. */ void QDeclarativeCamera::start() { @@ -299,7 +314,8 @@ void QDeclarativeCamera::start() \qmlmethod Camera::stop() \fn QDeclarativeCamera::stop() - Stops the camera. + Stops the camera, but leaves the camera + stack loaded. */ void QDeclarativeCamera::stop() { @@ -359,26 +375,6 @@ void QDeclarativeCamera::stop() and the object is in focus, even while the actual focusing distance may be constantly changing. \endtable */ -/*! - \enum QDeclarativeCamera::LockStatus - \value Unlocked - The application is not interested in camera settings value. - The camera may keep this parameter without changes, this is common with camera focus, - or adjust exposure and white balance constantly to keep the viewfinder image nice. - - \value Searching - The application has requested the camera focus, exposure or white balance lock with - searchAndLock(). This state indicates the camera is focusing or calculating exposure and white balance. - - \value Locked - The camera focus, exposure or white balance is locked. - The camera is ready to capture, application may check the exposure parameters. - - The locked state usually means the requested parameter stays the same, - except in the cases when the parameter is requested to be constantly updated. - For example in continuous focusing mode, the focus is considered locked as long - and the object is in focus, even while the actual focusing distance may be constantly changing. -*/ QDeclarativeCamera::LockStatus QDeclarativeCamera::lockStatus() const { return QDeclarativeCamera::LockStatus(m_camera->lockStatus()); @@ -389,8 +385,11 @@ QDeclarativeCamera::LockStatus QDeclarativeCamera::lockStatus() const \fn QDeclarativeCamera::searchAndLock() Start focusing, exposure and white balance calculation. - If the camera has keyboard focus, searchAndLock() is called - automatically when the camera focus button is pressed. + + This is appropriate to call when the camera focus button is pressed + (or on a camera capture button half-press). If the camera supports + autofocusing, information on the focus zones is available through + the \l {CameraFocus}{focus} property. */ void QDeclarativeCamera::searchAndLock() { @@ -401,10 +400,7 @@ void QDeclarativeCamera::searchAndLock() \qmlmethod Camera::unlock() \fn QDeclarativeCamera::unlock() - Unlock focus. - - If the camera has keyboard focus, unlock() is called automatically - when the camera focus button is released. + Unlock focus, exposure and white balance locks. */ void QDeclarativeCamera::unlock() { @@ -469,7 +465,6 @@ void QDeclarativeCamera::setDigitalZoom(qreal value) /*! \qmlsignal Camera::onError(error, errorString) - This handler is called when an error occurs. The enumeration value \a error is one of the values defined below, and a descriptive string value is available in \a errorString. @@ -487,109 +482,52 @@ void QDeclarativeCamera::setDigitalZoom(qreal value) \fn void QDeclarativeCamera::lockStatusChanged() \qmlsignal Camera::lockStatusChanged() -*/ - -/*! - \fn void QDeclarativeCamera::stateChanged(QDeclarativeCamera::State) - \qmlsignal Camera::stateChanged(Camera::State) + This signal is emitted when the lock status (focus, exposure etc) changes. + This can happen when locking (e.g. autofocusing) is complete or has failed. */ /*! - \fn void QDeclarativeCamera::imageCaptured(const QString &) + \fn void QDeclarativeCamera::stateChanged(QDeclarativeCamera::State state) + \qmlsignal Camera::stateChanged(state) - \qmlsignal Camera::imageCaptured(string) -*/ - -/*! - \fn void QDeclarativeCamera::imageSaved(const QString &) - - \qmlsignal Camera::imageSaved(string) -*/ - -/*! - \fn void QDeclarativeCamera::error(QDeclarativeCamera::Error , const QString &) - - \qmlsignal Camera::error(Camera::Error, string) -*/ - -/*! - \fn void QDeclarativeCamera::errorChanged() - -*/ -/*! - \qmlsignal Camera::errorChanged() -*/ - -/*! - \fn void QDeclarativeCamera::isoSensitivityChanged(int) -*/ -/*! - \qmlsignal Camera::isoSensitivityChanged(int) -*/ - -/*! - \fn void QDeclarativeCamera::apertureChanged(qreal) - - \qmlsignal Camera::apertureChanged(real) -*/ - -/*! - \fn void QDeclarativeCamera::shutterSpeedChanged(qreal) - -*/ -/*! - \qmlsignal Camera::shutterSpeedChanged(real) -*/ - -/*! - \fn void QDeclarativeCamera::exposureCompensationChanged(qreal) - -*/ -/*! - \qmlsignal Camera::exposureCompensationChanged(real) + This signal is emitted when the camera state has changed to \a state. Since the + state changes may take some time to occur this signal may arrive sometime + after the state change has been requested. */ /*! \fn void QDeclarativeCamera:opticalZoomChanged(qreal zoom) + \qmlsignal Camera::opticalZoomChanged(zoom) - Optical zoom changed to \a zoom. -*/ -/*! - \qmlsignal Camera::opticalZoomChanged(real) + The optical zoom setting has changed to \a zoom. */ /*! \fn void QDeclarativeCamera::digitalZoomChanged(qreal) + \qmlsignal Camera::digitalZoomChanged(zoom) - \qmlsignal Camera::digitalZoomChanged(real) + The digital zoom setting has changed to \a zoom. */ /*! - \fn void QDeclarativeCamera::maximumOpticalZoomChanged(qreal) + \fn void QDeclarativeCamera::maximumOpticalZoomChanged(zoom) + \qmlsignal Camera::maximumOpticalZoomChanged(zoom) - \qmlsignal Camera::maximumOpticalZoomChanged(real) + The maximum optical zoom setting has changed to \a zoom. This + can occur when you change between video and still image capture + modes, or the capture settings are changed. */ /*! \fn void QDeclarativeCamera::maximumDigitalZoomChanged(qreal) + \qmlsignal Camera::maximumDigitalZoomChanged(zoom) - \qmlsignal Camera::maximumDigitalZoomChanged(real) + The maximum digital zoom setting has changed to \a zoom. This + can occur when you change between video and still image capture + modes, or the capture settings are changed. */ - -/*! - \fn void QDeclarativeCamera::captureResolutionChanged(const QSize &) - - \qmlsignal Camera::captureResolutionChanged(Item) -*/ - -/*! - \fn QDeclarativeCamera::cameraStateChanged(QDeclarativeCamera::State) - -*/ - - QT_END_NAMESPACE #include "moc_qdeclarativecamera_p.cpp" diff --git a/src/imports/multimedia/qdeclarativecameracapture.cpp b/src/imports/multimedia/qdeclarativecameracapture.cpp index 72ef59de3..f211d60ff 100644 --- a/src/imports/multimedia/qdeclarativecameracapture.cpp +++ b/src/imports/multimedia/qdeclarativecameracapture.cpp @@ -53,6 +53,7 @@ QT_BEGIN_NAMESPACE \qmlclass CameraCapture QDeclarativeCameraCapture \brief The CameraCapture element provides an interface for capturing camera images \ingroup multimedia_qml + \ingroup camera_qml This element allows you to capture still images and be notified when they are available or saved to disk. You can adjust the resolution of the captured diff --git a/src/imports/multimedia/qdeclarativecameraexposure.cpp b/src/imports/multimedia/qdeclarativecameraexposure.cpp index e5c9e21e8..5bf030576 100644 --- a/src/imports/multimedia/qdeclarativecameraexposure.cpp +++ b/src/imports/multimedia/qdeclarativecameraexposure.cpp @@ -48,6 +48,7 @@ QT_BEGIN_NAMESPACE \qmlclass CameraExposure QDeclarativeCameraExposure \brief The CameraExposure element provides interface for exposure related camera settings. \ingroup multimedia_qml + \ingroup camera_qml This element is part of the \bold{QtMultimedia 5.0} module. @@ -69,6 +70,25 @@ QT_BEGIN_NAMESPACE } \endqml + + Several settings have both an automatic and a manual mode. In + the automatic modes the camera software itself will decide what + a reasonable setting is, but in most cases these settings can + be overridden with a specific manual setting. + + For example, to select automatic shutter speed selection: + + \qml + camera.exposure.setAutoShutterSpeed(); + \endqml + + Or for a specific shutter speed: + + \qml + camera.exposure.manualShutterSpeed = 0.01; // 10ms + \endqml + + You can only choose one or the other mode. */ /*! @@ -187,7 +207,7 @@ void QDeclarativeCameraExposure::setManualIsoSensitivity(int iso) \property QDeclarativeCameraExposure::manualShutterSpeed This property allows you to set the shutter speed to - use during capture. If the value is less than zero, + use during capture (in seconds). If the value is less than zero, then an automatic value is used and the camera will determine an appropriate shutter speed. diff --git a/src/imports/multimedia/qdeclarativecameraflash.cpp b/src/imports/multimedia/qdeclarativecameraflash.cpp index c1456d5dd..6ef2da273 100644 --- a/src/imports/multimedia/qdeclarativecameraflash.cpp +++ b/src/imports/multimedia/qdeclarativecameraflash.cpp @@ -48,6 +48,7 @@ QT_BEGIN_NAMESPACE \qmlclass CameraFlash QDeclarativeCameraFlash \brief The CameraFlash element provides interface for flash related camera settings. \ingroup multimedia_qml + \ingroup camera_qml This element is part of the \bold{QtMultimedia 5.0} module. diff --git a/src/imports/multimedia/qdeclarativecamerafocus.cpp b/src/imports/multimedia/qdeclarativecamerafocus.cpp index 707a26152..e25ebc10b 100644 --- a/src/imports/multimedia/qdeclarativecamerafocus.cpp +++ b/src/imports/multimedia/qdeclarativecamerafocus.cpp @@ -48,6 +48,7 @@ QT_BEGIN_NAMESPACE \qmlclass CameraFocus QDeclarativeCameraFocus \brief The CameraFocus element provides interface for focus related camera settings. \ingroup multimedia_qml + \ingroup camera_qml This element is part of the \bold{QtMultimedia 5.0} module. diff --git a/src/imports/multimedia/qdeclarativecameraimageprocessing.cpp b/src/imports/multimedia/qdeclarativecameraimageprocessing.cpp index f764bf6cf..acbd1780e 100644 --- a/src/imports/multimedia/qdeclarativecameraimageprocessing.cpp +++ b/src/imports/multimedia/qdeclarativecameraimageprocessing.cpp @@ -48,6 +48,7 @@ QT_BEGIN_NAMESPACE \qmlclass CameraImageProcessing QDeclarativeCameraImageProcessing \brief The CameraCapture element provides an interface for camera capture related settings \ingroup multimedia_qml + \ingroup camera_qml The CameraImageProcessing element provides control over post-processing done by the camera middleware, including white balance adjustments, diff --git a/src/imports/multimedia/qdeclarativecamerarecorder.cpp b/src/imports/multimedia/qdeclarativecamerarecorder.cpp index a1adb8a59..c0351fb05 100644 --- a/src/imports/multimedia/qdeclarativecamerarecorder.cpp +++ b/src/imports/multimedia/qdeclarativecamerarecorder.cpp @@ -50,6 +50,7 @@ QT_BEGIN_NAMESPACE \qmlclass CameraRecorder QDeclarativeCameraRecorder \brief The CameraRecorder element controls video recording with the Camera. \ingroup multimedia_qml + \ingroup camera_qml This element allows recording camera streams to files, and adjusting recording settings and metadata for videos. -- cgit v1.2.3