<?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>