slapin/qtmultimedia
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Improve the QCameraFocus and QCameraImageProcessing documentation.

Browse Source 
Also adds documentation for QCameraFocusZone.

Change-Id: I805806e9a683244b0c03553e00bebb41e6767ff1
Reviewed-by: Dmytro Poplavskiy <dmytro.poplavskiy@nokia.com>
This commit is contained in:
Michael Goddard
2012-01-11 14:48:52 +10:00
committed by Qt by Nokia
parent 3d88a055d0
commit 24589b341c
4 changed files with 242 additions and 32 deletions
Download Patch File Download Diff File Expand all files Collapse all files

149
src/multimedia/camera/qcamerafocus.cpp
View File

@@ -103,60 +103,134 @@ public:
QCameraFocusZone::FocusZoneStatus status;
};
/*!
\class QCameraFocusZone
\brief The QCameraFocusZone class provides information on zones used for autofocusing a camera.
\inmodule QtMultimedia
\ingroup camera
\since 1.1
For cameras that support autofocusing, in order for a camera to autofocus on
part of a sensor frame, it considers different zones within the frame. Which
zones to use, and where the zones are located vary between different cameras.
This class exposes what zones are used by a particular camera, and a list of the
zones can be retrieved by a \l QCameraFocus instance.
You can use this information to present visual feedback - for example, drawing
rectangles around areas of the camera frame that are in focus, or changing the
color of a zone as it comes into focus.
\snippet doc/src/snippets/multimedia-snippets/camera.cpp Camera focus zones
\sa QCameraFocus
*/
/*!
\enum QCameraFocusZone::Status
\value Invalid This zone is not valid
\value Unused This zone may be used for autofocusing, but is not currently.
\value Selected This zone is currently being used for autofocusing, but is not in focus.
\value Focused This zone is being used for autofocusing and is currently in focus.
*/
/*!
* \internal
* Creates a new, empty QCameraFocusZone.
*/
QCameraFocusZone::QCameraFocusZone()
:d(new QCameraFocusZoneData)
{
}
/*!
* \internal
* Creates a new QCameraFocusZone with the supplied \a area and \a status.
*/
QCameraFocusZone::QCameraFocusZone(const QRectF &area, QCameraFocusZone::FocusZoneStatus status)
:d(new QCameraFocusZoneData(area, status))
{
}
/*!
* Creates a new QCameraFocusZone as a copy of \a other.
*/
QCameraFocusZone::QCameraFocusZone(const QCameraFocusZone &other)
:d(other.d)
{
}
/*!
* Destroys this QCameraFocusZone.
*/
QCameraFocusZone::~QCameraFocusZone()
{
}
/*!
* Assigns \a other to this QCameraFocusZone.
*/
QCameraFocusZone& QCameraFocusZone::operator=(const QCameraFocusZone &other)
{
d = other.d;
return *this;
}
/*!
* Returns true if this focus zone is the same as \a other.
*/
bool QCameraFocusZone::operator==(const QCameraFocusZone &other) const
{
return d == other.d ||
(d->area == other.d->area && d->status == other.d->status);
}
/*!
* Returns true if this focus zone is not the same as \a other.
*/
bool QCameraFocusZone::operator!=(const QCameraFocusZone &other) const
{
return !(*this == other);
}
/*!
* Returns true if this focus zone has a valid area and status.
*/
bool QCameraFocusZone::isValid() const
{
return d->status != Invalid && !d->area.isValid();
}
/*!
* Returns the area of the camera frame that this focus zone encompasses.
*
* Coordinates are in frame relative coordinates - \c QPointF(0,0) is the top
* left of the frame, and \c QPointF(1,1) is the bottom right.
*/
QRectF QCameraFocusZone::area() const
{
return d->area;
}
/*!
* Returns the current status of this focus zone.
*/
QCameraFocusZone::FocusZoneStatus QCameraFocusZone::status() const
{
return d->status;
}
/*!
* \internal
* Sets the current status of this focus zone to \a status.
*/
void QCameraFocusZone::setStatus(QCameraFocusZone::FocusZoneStatus status)
{
d->status = status;
@@ -166,14 +240,50 @@ void QCameraFocusZone::setStatus(QCameraFocusZone::FocusZoneStatus status)
/*!
\class QCameraFocus
\brief The QCameraFocus class provides interface for
focus and zoom related camera settings.
\brief The QCameraFocus class provides an interface for focus and zoom related camera settings.
\inmodule QtMultimedia
\ingroup camera
\since 1.1
On hardware that supports it, this class lets you adjust the focus
or zoom (both optical and digital). This also includes things
like "Macro" mode for close up work (e.g. reading barcodes, or
recognising letters), or "touch to focus" - indicating an
interesting area of the viewfinder for the hardware to attempt
to focus on.
\snippet doc/src/snippets/multimedia-snippets/camera.cpp Camera custom zoom
Zooming can be accomplished in a number of ways - usually the more
expensive but higher quality approach is an optical zoom, which allows
using the full extent of the camera sensor to gather image pixels. In
addition it is possible to digitally zoom, which will generally just
enlarge part of the sensor frame and throw away other parts. If the
camera hardware supports optical zoom this should generally always
be used first. The \l maximumOpticalZoom() method allows this to be
checked. The \l zoomTo() method allows changing both optical and
digital zoom at once.
\snippet doc/src/snippets/multimedia-snippets/camera.cpp Camera combined zoom
\section2 Some notes on autofocus
Some hardware supports a movable focus lens assembly, and typically
this hardware also supports automatically focusing via some heuristic.
You can influence this via the \l FocusPointMode setting - typically
the center of the frame is brought into focus, but some hardware
also supports focusing on any faces detected in the frame, or on
a specific point (usually provided by a user in a "touch to focus"
scenario).
This class (in combination with \l QCameraFocusZone)
can expose information on what parts of the camera sensor image
are in focus or are being used for autofocusing via the \l focusZones()
property:
\snippet doc/src/snippets/multimedia-snippets/camera.cpp Camera focus zones
\sa QCameraFocusZone
*/
@@ -212,6 +322,7 @@ void QCameraFocusPrivate::initControls()
}
/*!
\internal
Construct a QCameraFocus for \a camera.
*/
@@ -235,6 +346,8 @@ QCameraFocus::~QCameraFocus()
/*!
Returns true if focus related settings are supported by this camera.
You may need to also check if any specific features are supported.
\since 1.1
*/
bool QCameraFocus::isAvailable() const
@@ -247,6 +360,9 @@ bool QCameraFocus::isAvailable() const
\brief The current camera focus mode.
\since 1.1
This controls the way the camera lens assembly is configured.
\sa QCameraFocus::isFocusModeSupported()
*/
@@ -274,9 +390,13 @@ bool QCameraFocus::isFocusModeSupported(QCameraFocus::FocusMode mode) const
/*!
\property QCameraFocus::focusPointMode
\brief The current camera focus point selection mode.
\since 1.1
If the camera focus mode is set to use an autofocusing mode,
this property controls the way the camera will select areas
of the frame to use for autofocusing.
\sa QCameraFocus::isFocusPointModeSupported()
\since 1.1
*/
QCameraFocus::FocusPointMode QCameraFocus::focusPointMode() const
@@ -309,10 +429,10 @@ bool QCameraFocus::isFocusPointModeSupported(QCameraFocus::FocusPointMode mode)
/*!
\property QCameraFocus::customFocusPoint
Position of custom focus point, in relative frame coordinates:
This property represents the position of the custom focus point, in relative frame coordinates:
QPointF(0,0) points to the left top frame point, QPointF(0.5,0.5) points to the frame center.
Custom focus point is used only in FocusPointCustom focus mode.
The custom focus point property is used only in \c FocusPointCustom focus mode.
\since 1.1
*/
@@ -352,7 +472,9 @@ QCameraFocusZoneList QCameraFocus::focusZones() const
}
/*!
Returns the maximum optical zoom
Returns the maximum optical zoom.
This will be \c 1.0 on cameras that do not support optical zoom.
\since 1.1
*/
@@ -363,6 +485,8 @@ qreal QCameraFocus::maximumOpticalZoom() const
/*!
Returns the maximum digital zoom
This will be \c 1.0 on cameras that do not support digital zoom.
\since 1.1
*/
@@ -399,6 +523,10 @@ qreal QCameraFocus::digitalZoom() const
/*!
Set the camera \a optical and \a digital zoom values.
Since there may be a physical component to move, the change in
zoom value may not be instantaneous.
\since 1.1
*/
void QCameraFocus::zoomTo(qreal optical, qreal digital)
@@ -416,7 +544,7 @@ void QCameraFocus::zoomTo(qreal optical, qreal digital)
\value AutoFocus One-shot auto focus mode.
\value ContinuousFocus Continuous auto focus mode.
\value InfinityFocus Focus strictly to infinity.
\value HyperfocalFocus Focus to hyperfocal distance, with with the maximum depth of field achieved.
\value HyperfocalFocus Focus to hyperfocal distance, with the maximum depth of field achieved.
All objects at distances from half of this
distance out to infinity will be acceptably sharp.
\value MacroFocus One shot auto focus to objects close to camera.
@@ -467,9 +595,10 @@ void QCameraFocus::zoomTo(qreal optical, qreal digital)
/*!
\fn QCameraFocus::focusZonesChanged()
Signal is emitted when the set of zones, camera focused on is changed.
This signal is emitted when the set of zones used in autofocusing is changed.
Usually the zones list is changed when the camera is focused.
This can change when a zone is focused or loses focus, or new focus zones
have been detected.
\since 1.1
*/

73
src/multimedia/camera/qcameraimageprocessing.cpp
View File

@@ -70,14 +70,35 @@ QT_BEGIN_NAMESPACE
/*!
\class QCameraImageProcessing
\brief The QCameraImageProcessing class provides interface for
focus and zoom related camera settings.
\brief The QCameraImageProcessing class provides an interface for
image processing related camera settings.
\inmodule QtMultimedia
\ingroup camera
\since 1.1
After capturing the data for a camera frame, the camera hardware and
software performs various image processing tasks to produce a final
image. This includes compensating for ambient light color, reducing
noise, as well as making some other adjustments to the image.
You can retrieve this class from an instance of a \l QCamera object.
For example, you can set the white balance (or color temperature) used
for processing images:
\snippet doc/src/snippets/multimedia-snippets/camera.cpp Camera image whitebalance
Or adjust the amount of denoising performed:
\snippet doc/src/snippets/multimedia-snippets/camera.cpp Camera image denoising
In some cases changing these settings may result in a longer delay
before an image is ready.
For more information on image processing of camera frames, see \l {Camera Image Processing}.
\sa QCameraImageProcessingControl
*/
@@ -169,7 +190,7 @@ bool QCameraImageProcessing::isWhiteBalanceModeSupported(QCameraImageProcessing:
/*!
Returns the current color temperature if the
manual white balance is active, otherwise the
current white balance mode is \c WhiteBalanceManual. For other modes the
return value is undefined.
\since 1.1
*/
@@ -185,7 +206,8 @@ int QCameraImageProcessing::manualWhiteBalance() const
}
/*!
Sets manual white balance to \a colorTemperature
Sets manual white balance to \a colorTemperature. This is used
when whiteBalanceMode() is set to \c WhiteBalanceManual. The units are Kelvin.
\since 1.1
*/
@@ -199,7 +221,7 @@ void QCameraImageProcessing::setManualWhiteBalance(int colorTemperature)
}
/*!
Return the contrast.
Returns the contrast adjustment setting.
\since 1.1
*/
int QCameraImageProcessing::contrast() const
@@ -213,9 +235,9 @@ int QCameraImageProcessing::contrast() const
}
/*!
Set the contrast to \a value.
Set the contrast adjustment to \a value.
Valid contrast values range between -100 and 100, the default is 0.
Valid contrast adjustment values range between -100 and 100, with a default of 0.
\since 1.1
*/
void QCameraImageProcessing::setContrast(int value)
@@ -226,7 +248,7 @@ void QCameraImageProcessing::setContrast(int value)
}
/*!
Returns the saturation value.
Returns the saturation adjustment value.
\since 1.1
*/
int QCameraImageProcessing::saturation() const
@@ -240,9 +262,9 @@ int QCameraImageProcessing::saturation() const
}
/*!
Sets the saturation value to \a value.
Sets the saturation adjustment value to \a value.
Valid saturation values range between -100 and 100, the default is 0.
Valid saturation values range between -100 and 100, with a default of 0.
\since 1.1
*/
@@ -269,6 +291,9 @@ bool QCameraImageProcessing::isSharpeningSupported() const
/*!
Returns the sharpening level.
This may be \c DefaultSharpening if no particular sharpening level has been applied.
\since 1.1
*/
int QCameraImageProcessing::sharpeningLevel() const
@@ -279,7 +304,7 @@ int QCameraImageProcessing::sharpeningLevel() const
value = d_func()->imageControl->processingParameter(QCameraImageProcessingControl::Sharpening);
if (value.isNull())
return -1;
return DefaultSharpening;
else
return value.toInt();
}
@@ -287,8 +312,10 @@ int QCameraImageProcessing::sharpeningLevel() const
/*!
Sets the sharpening \a level.
Valid sharpening level values range between -1 for default sharpening level,
0 for sharpening disabled and 100 for maximum sharpening applied.
If \c DefaultSharpening is supplied, the camera will decide what sharpening
to perform. Otherwise a level of 0 will disable sharpening, and a level of 100
corresponds to maximum sharpening applied.
\since 1.1
*/
@@ -297,7 +324,7 @@ void QCameraImageProcessing::setSharpeningLevel(int level)
Q_D(QCameraImageProcessing);
if (d->imageControl)
d->imageControl->setProcessingParameter(QCameraImageProcessingControl::Sharpening,
level == -1 ? QVariant() : QVariant(level));
level == DefaultSharpening ? QVariant() : QVariant(level));
}
/*!
@@ -313,7 +340,9 @@ bool QCameraImageProcessing::isDenoisingSupported() const
}
/*!
Returns the denoising level.
Returns the denoising level. This may be \c DefaultDenoising if no
particular value has been set.
\since 1.1
*/
int QCameraImageProcessing::denoisingLevel() const
@@ -324,7 +353,7 @@ int QCameraImageProcessing::denoisingLevel() const
value = d_func()->imageControl->processingParameter(QCameraImageProcessingControl::Denoising);
if (value.isNull())
return -1;
return DefaultDenoising;
else
return value.toInt();
}
@@ -332,8 +361,10 @@ int QCameraImageProcessing::denoisingLevel() const
/*!
Sets the denoising \a level.
Valid denoising level values range between -1 for default denoising level,
0 for denoising disabled and 100 for maximum denoising applied.
If \c DefaultDenoising is supplied, the camera will decide what denoising
to perform. Otherwise a level of 0 will disable denoising, and a level of 100
corresponds to maximum denoising applied.
\since 1.1
*/
void QCameraImageProcessing::setDenoisingLevel(int level)
@@ -341,7 +372,7 @@ void QCameraImageProcessing::setDenoisingLevel(int level)
Q_D(QCameraImageProcessing);
if (d->imageControl)
d->imageControl->setProcessingParameter(QCameraImageProcessingControl::Denoising,
level == -1 ? QVariant() : QVariant(level));
level == DefaultDenoising ? QVariant() : QVariant(level));
}
@@ -354,7 +385,7 @@ void QCameraImageProcessing::setDenoisingLevel(int level)
\value WhiteBalanceSunlight Sunlight white balance mode.
\value WhiteBalanceCloudy Cloudy white balance mode.
\value WhiteBalanceShade Shade white balance mode.
\value WhiteBalanceTungsten Tungsten white balance mode.
\value WhiteBalanceTungsten Tungsten (incandescent) white balance mode.
\value WhiteBalanceFluorescent Fluorescent white balance mode.
\value WhiteBalanceFlash Flash white balance mode.
\value WhiteBalanceSunset Sunset white balance mode.

2
src/multimedia/camera/qcameraimageprocessing.h
View File

@@ -95,10 +95,12 @@ public:
int saturation() const;
void setSaturation(int value);
static const int DefaultSharpening = -1;
bool isSharpeningSupported() const;
int sharpeningLevel() const;
void setSharpeningLevel(int value);
static const int DefaultDenoising = -1;
bool isDenoisingSupported() const;
int denoisingLevel() const;
void setDenoisingLevel(int value);