1 <?xml version="1.0" encoding="utf-8"?>

     2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

     3 <!-- This component and the accompanying materials are made available under the terms of the License 

     4 "Eclipse Public License v1.0" which accompanies this distribution, 

     5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

     6 <!-- Initial Contributors:

     7     Nokia Corporation - initial contribution.

     8 Contributors: 

     9 -->

    10 <!DOCTYPE concept

    11   PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

    12 <concept id="GUID-A1D2C673-3B91-403A-800B-5E1504FB19EE" xml:lang="en"><title>Capturing still images</title><prolog><metadata><keywords/></metadata></prolog><conbody>

    13 <p>To capture still images or to use the display as a viewfinder, build

    14 your application around the Symbian Ecam camera utility. To make use of the

    15 device camera to capture an image, the application needs to repeat the steps

    16 described in the illustration below.</p>

    17 <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_d0e266838_href.png"/></fig>

    18 <note>

    19 <p>The settings you can use in your application depend on what the camera

    20 hardware on the device supports.</p>

    21 </note>

    22 <p>To capture images, use the methods of the <xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Camera_Framework/CCameraClass.html" format="application/java-archive"><codeph>CCamera</codeph></xref> and <xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Camera_Framework/MCameraObserver2Class.html" format="application/java-archive"><codeph>MCameraObserver2</codeph></xref> classes to construct your application. <codeph>MCameraObserver2</codeph> uses

    23 the advanced camera features of the <xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Camera_Framework/CCameraClass.html#%3a%3aCCamera%3a%3aCCameraAdvancedSettings" format="application/java-archive"><codeph>CCamera::CCameraAdvancedSettings</codeph></xref> class. </p>

    24 <p>For a reference example, see <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>

    25 <section><title>To capture still images on a mobile device</title>

    26 <ol>

    27 <li id="GUID-9E819F98-B4C6-4C0B-A723-F82494E8655B"><p>Initialize

    28 the onboard camera.</p>

    29 <ul>

    30 <li><p>Create a camera object using the <xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Camera_Framework/CCameraClass.html#%3a%3aCCamera%3a%3aNew2L%28MCameraObserver2%20%26amp%3b%2cTInt%2cTInt%29" format="application/java-archive"><codeph>CCamera::New2L()</codeph></xref> method.</p></li>

    31 <li><p>Reserve the camera for your application using the <xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Camera_Framework/CCameraClass.html#%3a%3aCCamera%3a%3aReserve%28%29" format="application/java-archive"><codeph>CCamera::Reserve()</codeph></xref> method. <xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Camera_Framework/MCameraObserver2Class.html#%3a%3aMCameraObserver2%3a%3aHandleEvent%28const%20TECAMEvent%20%26amp%3b%29" format="application/java-archive"><codeph>MCameraObserver2::HandleEvent</codeph></xref> is called upon

    32 completion.</p></li>

    33 <li><p>Switch on the camera power using the <xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Camera_Framework/CCameraClass.html#%3a%3aCCamera%3a%3aPowerOn%28%29" format="application/java-archive"><codeph>CCamera::PowerOn()</codeph></xref> method. <xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Camera_Framework/MCameraObserver2Class.html#%3a%3aMCameraObserver2%3a%3aHandleEvent%28const%20TECAMEvent%20%26amp%3b%29" format="application/java-archive"><codeph>MCameraObserver2::HandleEvent</codeph></xref> is called upon

    34 completion.</p></li>

    35 <li><p>If needed, share the camera between multiple clients using

    36 the <xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Camera_Framework/CCameraClass.html#%3a%3aCCamera%3a%3aNewDuplicate2L%28MCameraObserver2%20%26amp%3b%2cTInt%29" format="application/java-archive"><codeph>CCamera::NewDuplicate2L()</codeph></xref> function. This function

    37 needs the handle of an existing camera object (use <xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Camera_Framework/CCameraClass.html#%3a%3aCCamera%3a%3aHandle%28%29" format="application/java-archive"><codeph>CCamera::Handle()</codeph></xref>).</p></li>

    38 </ul>

    39 </li>

    40 <li id="GUID-1A42718C-0158-4BB6-B99F-48278369C3F3"><p>Configure

    41 the camera settings.</p>

    42 <ul>

    43 <li><p>Before you adjust the settings, make sure the camera hardware

    44 supports the particular option. Use <xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Camera_Framework/CCameraClass.html#%3a%3aCCamera%3a%3aCameraInfo%28TCameraInfo%20%26amp%3b%29const" format="application/java-archive"><codeph>CCamera::CameraInfo()</codeph></xref> to retrieve and <xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Camera_Framework/TCameraInfoClass.html" format="application/java-archive"><codeph>TCameraInfo</codeph></xref> to

    45 specify the camera information.</p><p>For example, to find out what

    46 image formats are supported by the onboard camera, use the <xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Camera_Framework/TCameraInfoClass.html#%3a%3aTCameraInfo%3a%3aiImageFormatsSupported" format="application/java-archive"><codeph>TCameraInfo::iImageFormatsSupported</codeph></xref> member variable.</p></li>

    47 <li><p>Specify the image format using the <xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Camera_Framework/CCameraClass.html#%3a%3aCCamera%3a%3aPrepareImageCaptureL%28TFormat%2cTInt%29" format="application/java-archive"><codeph>CCamera::PrepareImageCaptureL</codeph></xref> method. For a list of

    48 possible formats, see <xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Camera_Framework/CCameraClass.html#%3a%3aCCamera%3a%3aTFormat" format="application/java-archive"><codeph>CCamera::TFormat</codeph></xref>.</p><p>Devices support image capture in EXIF JPEG format (<xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Camera_Framework/CCameraClass.html#%3a%3aCCamera%3a%3aEFormatExif" format="application/java-archive"><codeph>CCamera::EFormatExif</codeph></xref>), which is encoded with

    49 JPEG and requires no additional conversion.</p></li>

    50 <li><p>Specify the desired image size using the <xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Camera_Framework/CCameraClass.html#%3a%3aCCamera%3a%3aEnumerateCaptureSizes%28TSize%20%26amp%3b%2cTInt%2cTFormat%29const" format="application/java-archive"><codeph>CCamera::EnumerateCaptureSizes()</codeph></xref> method.</p>

    51 </li>

    52 <li><p>Additionally, you can set, for example, the brightness, contrast,

    53 zoom level, flash mode, exposure and white balance of the image. For more

    54 information on the options, see the <xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Camera_Framework/CCameraClass.html#%3a%3aCCamera%3a%3aCCameraAdvancedSettings" format="application/java-archive"><codeph>CCamera::CCameraAdvancedSettings</codeph></xref> class. You can also use the settings directly under <codeph>CCamera</codeph>.</p>

    55 </li>

    56 </ul>

    57 <ul>

    58 <li><p>Before you can call <codeph>CCamera::CaptureImage()</codeph>,

    59 allocate memory and set up image format, size and clipping rectangle using

    60 the <xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Camera_Framework/CCameraClass.html#%3a%3aCCamera%3a%3aPrepareImageCaptureL%28TFormat%2cTInt%29" format="application/java-archive"><codeph>CCamera::PrepareImageCaptureL()</codeph></xref> method. This

    61 needs to be called only once for multiple captures.</p></li>

    62 </ul>

    63 </li>

    64 <li id="GUID-A7ED7A90-1432-4905-A0A5-0CC725997127"><p>Use the display

    65 of the device as a viewfinder by transferring image data from the camera to

    66 the display memory.</p>

    67 <ul>

    68 <li><p>Start the transfer of viewfinder data with direct screen

    69 access using the <xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Camera_Framework/CCameraClass.html#%3a%3aCCamera%3a%3aStartViewFinderDirectL%28RWsSession%20%26amp%3b%2cCWsScreenDevice%20%26amp%3b%2cRWindowBase%20%26amp%3b%2cTRect%20%26amp%3b%29" format="application/java-archive"><codeph>CCamera::StartViewFinderDirectL()</codeph></xref> method.</p>

    70 </li>

    71 <li><p>Transfer viewfinder data as a bitmap using the <xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Camera_Framework/CCameraClass.html#%3a%3aCCamera%3a%3aStartViewFinderBitmapsL%28TSize%20%26amp%3b%29" format="application/java-archive"><codeph>CCamera::StartViewFinderBitmapsL()</codeph></xref> method.

    72  <xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Camera_Framework/MCameraObserver2Class.html#%3a%3aMCameraObserver2%3a%3aViewFinderReady%28MCameraBuffer%20%26amp%3b%2cTInt%29" format="application/java-archive"><codeph>MCameraObserver2::ViewFinderReady</codeph></xref> is called

    73 upon completion.</p></li>

    74 <li><p>Set viewfinder mirroring on and flip the image horizontally

    75 using the <xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Camera_Framework/CCameraClass.html#%3a%3aCCamera%3a%3aSetViewFinderMirrorL%28TBool%29" format="application/java-archive"><codeph>CCamera::SetViewFinderMirrorL()</codeph></xref> method.</p>

    76 </li>

    77 <li><p>Stop the transfer of viewfinder data to the screen using

    78 the <xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Camera_Framework/CCameraClass.html#%3a%3aCCamera%3a%3aStopViewFinder%28%29" format="application/java-archive"><codeph>CCamera::StopViewFinder()</codeph></xref> method.</p></li>

    79 </ul>

    80 </li>

    81 <li id="GUID-136AEB7B-B618-456E-A7AA-27105A50B9DE"><p>Capture one

    82 or multiple images using the <xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Camera_Framework/CCameraClass.html#%3a%3aCCamera%3a%3aCaptureImage%28%29" format="application/java-archive"><codeph>CCamera::CaptureImage()</codeph></xref> method. <xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Camera_Framework/MCameraObserver2Class.html#%3a%3aMCameraObserver2%3a%3aImageBufferReady%28MCameraBuffer%20%26amp%3b%2cTInt%29" format="application/java-archive"><codeph>MCameraObserver2::ImageBufferReady()</codeph></xref> is called

    83 upon completion.</p></li>

    84 <li id="GUID-9EF06D1B-EB64-4406-A97F-FE0C9DA1664F"><p>To exit the

    85 application or to switch it to the background, switch off the camera power

    86 using the <xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Camera_Framework/CCameraClass.html#%3a%3aCCamera%3a%3aPowerOff%28%29" format="application/java-archive"><codeph>CCamera::PowerOff()</codeph></xref> method and release the

    87 camera for other applications using the <xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Camera_Framework/CCameraClass.html#%3a%3aCCamera%3a%3aRelease%28%29" format="application/java-archive"><codeph>CCamera::Release()</codeph></xref> method.</p></li>

    88 <li id="GUID-DDC63446-DACC-434D-B6EE-E661C4FC2813"><p>The <xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Camera_Framework/CCameraClass.html" format="application/java-archive"><codeph>CCamera</codeph></xref> and <xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Camera_Framework/MCameraObserver2Class.html" format="application/java-archive"><codeph>MCameraObserver2</codeph></xref> classes

    89 are defined in the <codeph>ecam.h</codeph> header file. Add the following

    90 line to the <codeph>.h</codeph> file, which is used to deploy the API:</p>

    91 <codeblock id="GUID-BB25E774-4122-47AE-BDDD-6691BEAEB15E" xml:space="preserve">#include &lt;ecam.h&gt;</codeblock>

    92 </li>

    93 <li id="GUID-0053A8A8-8664-4E35-8D80-EA579503C463"><p>Make sure

    94 you have correct <xref href="GUID-6971B0A2-F79B-4E05-8AF3-BB1FC1932A22.dita">capabilities</xref> information

    95 set for your application. You need at least the <codeph>UserEnvironment</codeph> capability.</p>

    96 </li>

    97 <li id="GUID-CE8449BB-25A8-462A-8010-6B64F0120603"><p>Make sure <codeph>ecam.lib</codeph> is

    98 accessible to your linker when compiling your application by including it

    99 in your <codeph>mmp</codeph> file or by editing the project properties in

   100 your IDE, depending on your build environment.</p></li>

   101 </ol>

   102 </section>

   103 <section><title>See also</title>

   104 <p><xref href="GUID-DA26D246-D74A-529F-9F81-11B45669103F.dita">Capturing Image</xref></p>

   105 <p><xref href="GUID-6C8507F7-FE70-5654-91B5-53E356CFF67C.dita">Controlling Pre-Image

   106 Capture </xref></p>

   107 <p><xref href="GUID-3C3BBE1F-D7A2-5021-830B-78084334C883.dita">Controlling Captured

   108 Image</xref></p>

   109 <p><xref href="GUID-BFDDCE4E-FE4F-5815-9D0B-A0967EA53B11.dita">Controlling Still-image

   110 Capture</xref></p>

   111 <p><xref href="GUID-36BD6059-6547-5754-8BE0-F8051A838C14.dita">Using Time Nudge

   112 Capture Drive Mode </xref></p>

   113 <p><xref href="GUID-E9E21C82-13F6-50D4-A271-F9E5F1BD982F.dita">Background Processing

   114 for Ecam</xref></p>

   115 </section>

   116 </conbody></concept>