<?xml version="1.0" encoding="utf-8"?>
<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
<!-- This component and the accompanying materials are made available under the terms of the License 
"Eclipse Public License v1.0" which accompanies this distribution, 
and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
<!-- Initial Contributors:
    Nokia Corporation - initial contribution.
Contributors: 
-->
<!DOCTYPE concept
  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="GUID-A1D2C673-3B91-403A-800B-5E1504FB19EE" xml:lang="en"><title>Capturing
Still Images</title><prolog><metadata><keywords/></metadata></prolog><conbody>
<p>To capture still images or to use the display as a viewfinder, build
your application around the Symbian Ecam camera utility. To make use of the
device camera to capture an image, the application needs to repeat the steps
described in the illustration below.</p>
<fig id="GUID-65212152-6862-4990-9869-CF643B9A5845"><title>The steps required to capture a still image</title><image href="GUID-5FE10ECA-1FAB-4E4F-A1D9-67D379EE8CB3_d0e290304_href.png"/></fig>
<p>Important implementation considerations include:</p>
<ul>
<li><p>The settings you can use in your application depend on what
the camera hardware on the device supports.</p></li>
<li><p>To capture images, use the methods of the <xref href="GUID-021C509B-C821-3401-B2F4-DE7F52BB16D4.dita"><apiname>CCamera</apiname></xref> and <xref href="GUID-09C6DDB6-A208-3C81-9F54-697D4865D99F.dita"><apiname>MCameraObserver2</apiname></xref> classes
to construct your application. <codeph>MCameraObserver2</codeph> uses the
advanced camera features of the <xref href="GUID-021C509B-C821-3401-B2F4-DE7F52BB16D4.dita#GUID-021C509B-C821-3401-B2F4-DE7F52BB16D4/GUID-E31AEB11-B7A0-3637-BB31-866306F78118"><apiname>CCamera::CCameraAdvancedSettings</apiname></xref> class.
The <codeph>CCamera</codeph> and <codeph>MCameraObserver2</codeph> classes
are defined in the <codeph>ecam.h</codeph> header file. Add the following
line to the <codeph>.h</codeph> file, which is used to deploy the API:</p>
<codeblock id="GUID-BB25E774-4122-47AE-BDDD-6691BEAEB15E" xml:space="preserve">#include &lt;ecam.h&gt;</codeblock>
</li>
<li><p>Make sure you have correct <xref href="GUID-6971B0A2-F79B-4E05-8AF3-BB1FC1932A22.dita">capabilities</xref> information
set for your application. You need at least the <codeph>UserEnvironment</codeph> capability.</p>
</li>
<li><p>Make sure <codeph>ecam.lib</codeph> is accessible to your
linker when compiling your application by including it in your <codeph>mmp</codeph> file
or by editing the project properties in your IDE, depending on your build
environment.</p></li>
</ul>
<section id="GUID-7AE307AA-8E1E-4F6C-AFC7-4CED1341D785"><title>To capture still
images on a mobile device</title>
<ol>
<li id="GUID-9E819F98-B4C6-4C0B-A723-F82494E8655B"><p>Initialize
the onboard camera.</p>
<ul>
<li><p>Create a camera object using the <codeph>CCamera::New2L()</codeph> method.</p>
</li>
<li><p>Reserve the camera for your application using the <codeph>CCamera::Reserve()</codeph> method. <codeph>MCameraObserver2::HandleEvent</codeph> is called upon completion.</p></li>
<li><p>Switch on the camera power using the <codeph>CCamera::PowerOn()</codeph> method. <codeph>MCameraObserver2::HandleEvent</codeph> is
called upon completion.</p></li>
<li><p>If needed, share the camera between multiple clients using
the <codeph>CCamera::NewDuplicate2L()</codeph> function. This function needs
the handle of an existing camera object (use <codeph>CCamera::Handle()</codeph>).</p>
</li>
</ul>
</li>
<li id="GUID-1A42718C-0158-4BB6-B99F-48278369C3F3"><p>Configure
the camera settings.</p>
<ul>
<li><p>Before you adjust the settings, make sure the camera hardware
supports the particular option. Use <codeph>CCamera::CameraInfo()</codeph> to
retrieve and <codeph>TCameraInfo</codeph> to specify the camera information.</p>
<p>For example, to find out what image formats are supported by the onboard
camera, use the <codeph>TCameraInfo::iImageFormatsSupported</codeph> member
variable.</p></li>
<li><p>Specify the image format using the <codeph>CCamera::PrepareImageCaptureL</codeph> method.
For a list of possible formats, see <codeph>CCamera::TFormat</codeph>.</p>
<p>Devices support image capture in EXIF JPEG format (<codeph>CCamera::EFormatExif</codeph>),
which is encoded with JPEG and requires no additional conversion.</p></li>
<li><p>Specify the desired image size using the <codeph>CCamera::EnumerateCaptureSizes()</codeph> method.</p>
</li>
<li><p>Additionally, you can set, for example, the brightness, contrast,
zoom level, flash mode, exposure and white balance of the image. For more
information on the options, see the <codeph>CCamera::CCameraAdvancedSettings</codeph> class.
You can also use the settings directly under <codeph>CCamera</codeph>.</p>
</li>
</ul>
<ul>
<li><p>Before you can call <codeph>CCamera::CaptureImage()</codeph>,
allocate memory and set up image format, size and clipping rectangle using
the <codeph>CCamera::PrepareImageCaptureL()</codeph> method. This needs to
be called only once for multiple captures.</p></li>
</ul>
</li>
<li id="GUID-A7ED7A90-1432-4905-A0A5-0CC725997127"><p>Use the display
of the device as a viewfinder by transferring image data from the camera to
the display memory.</p>
<ul>
<li><p>Start the transfer of viewfinder data with direct screen
access using the <codeph>CCamera::StartViewFinderDirectL()</codeph> method.</p>
</li>
<li><p>Transfer viewfinder data as a bitmap using the <codeph>CCamera::StartViewFinderBitmapsL()</codeph> method.
 <codeph>MCameraObserver2::ViewFinderReady</codeph> is called upon completion.</p>
</li>
<li><p>Set viewfinder mirroring on and flip the image horizontally
using the <codeph>CCamera::SetViewFinderMirrorL()</codeph> method.</p>
</li>
<li><p>Stop the transfer of viewfinder data to the screen using
the <codeph>CCamera::StopViewFinder()</codeph> method.</p></li>
</ul>
</li>
<li id="GUID-136AEB7B-B618-456E-A7AA-27105A50B9DE"><p>Capture one
or multiple images using the <codeph>CCamera::CaptureImage()</codeph> method. <codeph>MCameraObserver2::ImageBufferReady()</codeph> is
called upon completion.</p></li>
<li id="GUID-9EF06D1B-EB64-4406-A97F-FE0C9DA1664F"><p>To exit the
application or to switch it to the background, switch off the camera power
using the <codeph>CCamera::PowerOff()</codeph> method and release the camera
for other applications using the <codeph>CCamera::Release()</codeph> method.</p>
</li>
</ol>
</section>
<section id="GUID-6DC48744-EF5E-4234-8C48-7A9692338F76"><title>Additional information
on capturing still images</title>
<p>For reference examples, see: </p>
<ul>
<li><p><xref href="GUID-55BF8452-F9FF-5CF3-9D74-3BC7F5447551.dita">Camera
Example: Capturing and controlling the images using Camera</xref></p></li>
<li><p><xref href="http://developer.symbian.org/wiki/index.php/Introduction_to_the_Camera_API" scope="external">Introduction to the Camera API</xref> on the Symbian Foundation</p>
</li>
<li><p><xref href="http://www.forum.nokia.com/info/sw.nokia.com/id/9a3e1226-79db-4c8e-bd70-7d9d22aaa6eb/S60_Platform_Camera_Example.html" scope="external">S60 Platform: Camera Example</xref> on Forum Nokia.</p></li>
</ul>
<p>For information on how to capture an image using Time-Nudge-Capture
drive mode, see <xref href="GUID-36BD6059-6547-5754-8BE0-F8051A838C14.dita">Using
Time Nudge Capture Drive Mode </xref>.</p>
<p>For information on how to capture an image using standalone background
processing, see <xref href="GUID-E9E21C82-13F6-50D4-A271-F9E5F1BD982F.dita">Background
Processing for Ecam</xref>.</p>
<p>For information on displaying images on the screen, see <xref href="GUID-27220B08-B2E7-5106-9BCC-C86938D3E37D.dita">Image
Display Library Overview</xref></p>
</section>
</conbody></concept>