<?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 xml:lang="en" id="GUID-1C0707F8-9E2A-58C6-997B-23B57C7EFA93"><title>Working with Snapshots </title><prolog><metadata><keywords/></metadata></prolog><conbody><section><title>Introduction</title> <p>Snapshot shows the captured images on the display almost instantaneously. Snapshots may be created for video as well and the client may further specify the video frames from which the snapshot can be generated. </p> <p>The client can specify the properties of the snapshot, such as size, background colour and position to be used if the snapshot has been scaled and so on. </p> <p><b>Setup and Configuration Requirements</b> </p> <p>The following are the setup and configuration requirements you need to follow before doing snapshot implementation: </p> <ul><li id="GUID-CE84B0A7-DF2A-5EAF-AFBB-FC9FC2EA97E7"><p>Make sure that you provide a concrete implementation of <xref href="GUID-B0E7BDE5-2303-3547-93FB-DE0F2BC8E5FA.dita"><apiname>McameraSnapshot</apiname></xref> interface class, which provides the functionality. </p> </li> <li id="GUID-DC3C6970-C967-5E33-90AB-5F0EE981DFE9"><p>Make sure that providers of the extension API for camera direct snapshot provides the implementation of <xref href="GUID-E75CBA2D-933F-33CF-9F66-0868D6BC0649.dita"><apiname>MCameraDirectSnapshot</apiname></xref> mixin class. </p> </li> </ul> </section> <section><title> Snapshot Implementation</title> <p>The <xref href="GUID-021C509B-C821-3401-B2F4-DE7F52BB16D4.dita#GUID-021C509B-C821-3401-B2F4-DE7F52BB16D4/GUID-7DB06650-199E-3B00-A19A-1B48D671E46E"><apiname>CCamera::CCameraSnapshot</apiname></xref> class allows a client to request snapshot data in a specified image format for both still images and video. The following tasks will be covered during snapshot implementation: </p> <ol id="GUID-EC9A66AE-DC72-5A3A-8F14-8D536EE24831"><li id="GUID-A2C0332D-B266-5763-910A-08B18D30D66A"><p>Create specific snapshot object using <codeph>CCamera::CCameraImageCapture::GetSnapshotHandleL(TInt

                aClientViewFinderId)</codeph> or <codeph>CCamera::CCameraVideoCaptureControl::GetSnapshotHandleL(TInt

                aClientViewFinderId)</codeph>. Each client snapshot is linked to a specific client viewfinder handle. </p> </li> <li id="GUID-3058595E-7668-50B8-8E17-ED3D30870E11"><p>Concrete implementation for <xref href="GUID-BC75A950-7188-3A8B-BB25-49A119F23E06.dita"><apiname>MCameraImageCapture</apiname></xref> or <xref href="GUID-11495CEA-9F67-3B9A-A35C-E7555ED28316.dita"><apiname>MCameraVideoCaptureControl</apiname></xref> provides the implementation factory used to retrieve concrete implementation for <xref href="GUID-CBB8D575-A12F-32C4-BC19-55AEB51D2601.dita"><apiname>MCameraSnapshot</apiname></xref> and <xref href="GUID-A048086C-0481-3E68-9B96-70943917B3FB.dita"><apiname>MCameraSnapshot2</apiname></xref> based on the values of the passed UIDs . </p> <p>The UID values can be <xref href="GUID-3822F287-490F-3753-8929-17AC67B9F7F0.dita"><apiname>KECamMCameraSnapshotUid</apiname></xref> and <xref href="GUID-8672CBE3-4037-30C7-92A3-496CB36BBB77.dita"><apiname>KECamMCameraSnapshot2Uid</apiname></xref>. </p> </li> <li id="GUID-D2F2EE28-0322-519B-8CA4-FB220175174B"><p>Snapshot data is passed to the client using the observer callbacks <xref href="GUID-430C206E-24D7-30BE-98E9-ACD176DDA3A8.dita#GUID-430C206E-24D7-30BE-98E9-ACD176DDA3A8/GUID-0D0984E6-D2CD-3079-8BD8-568403346E70"><apiname>MCaptureImageObserver::ClientSnapshotForImageReady()</apiname></xref> and <xref href="GUID-7FAEB878-52B1-3A54-9607-69AE09AB8AEB.dita#GUID-7FAEB878-52B1-3A54-9607-69AE09AB8AEB/GUID-91CCC70F-5EE9-30C4-912E-CB9D11EA5C74"><apiname>MCaptureVideoObserver::ClientSnapshotReady()</apiname></xref>. </p> </li> <li id="GUID-408CDAC6-2F0A-5E0E-9756-9323B591610F"><p>After the snapshot is instantiated, client can request for camera formats supported by the snapshot feature in the camera. </p> </li> <li id="GUID-31746768-33D8-58F4-AEE5-F5F3DAC31033"><p>Set the properties of the snapshot using <xref href="GUID-9749B0DF-B887-3798-9185-481DF8E2F7C2.dita#GUID-9749B0DF-B887-3798-9185-481DF8E2F7C2/GUID-B8A44662-C452-3B3F-8B7E-58E1F2902356"><apiname>CCameraSnapshot::PrepareSnapshotL</apiname></xref> call. Use <codeph>PrepareSnapshotL(const CCamera::CCameraSnapshot::TSnapshotParameters&amp;

                aSnapshotParameters)</codeph> to set the properties of snapshot. </p> <p>The following example shows how to do this: </p> <codeblock id="GUID-9DFEFA71-9475-54DF-B940-B15D420343A9" xml:space="preserve">// Gets the list of supported formats for snapshots

TUint suppFormats = snap->SupportedFormats();

    snap->PrepareSnapshotL(aSnapshotParameters);

</codeblock> </li> <li id="GUID-BF654290-2A23-5D29-834E-DE2BAABB3453"><p>The client uses <xref href="GUID-9749B0DF-B887-3798-9185-481DF8E2F7C2.dita#GUID-9749B0DF-B887-3798-9185-481DF8E2F7C2/GUID-9CE4346E-AE44-3D23-83F9-A4FB6AF8DF8E"><apiname>CCameraSnapshot::EnableSnapshotL</apiname></xref> API to activate snapshot feature and to get snapshot notifications from Ecam implementation. </p> <p>If a call to <xref href="GUID-9749B0DF-B887-3798-9185-481DF8E2F7C2.dita#GUID-9749B0DF-B887-3798-9185-481DF8E2F7C2/GUID-9CE4346E-AE44-3D23-83F9-A4FB6AF8DF8E"><apiname>CCameraSnapshot::EnableSnapshotL</apiname></xref> is made without a successful call to , then the callback returns <xref href="GUID-25493BDC-2D2E-3CC5-A5FE-A36804A4388A.dita"><apiname>KErrBadHandle</apiname></xref>. </p> </li> <li id="GUID-6F2459E2-4007-5B60-B707-8AA221E60448"><p>Client should implement the observers; <xref href="GUID-430C206E-24D7-30BE-98E9-ACD176DDA3A8.dita"><apiname>MCaptureImageObserver</apiname></xref> and <xref href="GUID-7FAEB878-52B1-3A54-9607-69AE09AB8AEB.dita"><apiname>MCaptureVideoObserver</apiname></xref>. </p> <p> <b>Note</b>: Snapshot notifications will be send to the clients through these observers and not through events. </p> </li> <li id="GUID-C894DBBA-57E3-5666-8DA4-7E1D64BCFC29"><p>Snapshot data is retrieved using <xref href="GUID-430C206E-24D7-30BE-98E9-ACD176DDA3A8.dita#GUID-430C206E-24D7-30BE-98E9-ACD176DDA3A8/GUID-0D0984E6-D2CD-3079-8BD8-568403346E70"><apiname>MCaptureImageObserver::ClientSnapshotForImageReady()</apiname></xref> or <xref href="GUID-7FAEB878-52B1-3A54-9607-69AE09AB8AEB.dita#GUID-7FAEB878-52B1-3A54-9607-69AE09AB8AEB/GUID-91CCC70F-5EE9-30C4-912E-CB9D11EA5C74"><apiname>MCaptureVideoObserver::ClientSnapshotReady()</apiname></xref> depending on whether snapshot is for image or video. </p> </li> <li id="GUID-121C6D12-AA94-57A7-8749-C72716C661A2"><p>The client uses <xref href="GUID-9749B0DF-B887-3798-9185-481DF8E2F7C2.dita#GUID-9749B0DF-B887-3798-9185-481DF8E2F7C2/GUID-475C869C-2C6E-33C4-9B5C-26ADB000D992"><apiname>CCameraSnapshot::DisableSnapshotL</apiname></xref> call to stop getting notifications from Ecam implementation. It deactivates the snapshot feature if active. </p> </li> </ol> <p>You can also perform the above tasks using direct snapshot. The high level steps are explained below: </p> <ul><li id="GUID-7F798D1B-4B9D-5C8E-B701-1D2623EB01A8"><p>Create a new direct snapshot object using <xref href="GUID-880B1BDF-C42F-3190-81C2-B2DD555AC8FE.dita#GUID-880B1BDF-C42F-3190-81C2-B2DD555AC8FE/GUID-AA8DE98A-6720-379B-AD6E-FF7AE67C170A"><apiname>CCamera::CCameraDirectSnapshot::CreateL</apiname></xref>. </p> </li> <li id="GUID-85B08C9B-F982-500C-9E89-454818F2B303"><p>Retrieve the information about the direct viewfinder object for which direct snapshot is created using <xref href="GUID-880B1BDF-C42F-3190-81C2-B2DD555AC8FE.dita#GUID-880B1BDF-C42F-3190-81C2-B2DD555AC8FE/GUID-06315048-5BCE-3F1C-87E8-4F80C72FD08E"><apiname>CCamera::CCameraDirectSnapshot::GetDirectViewFinderL</apiname></xref> method. </p> </li> <li id="GUID-DF6AAC2E-612F-5E8C-BE44-9040BC52F493"><p>Enable direct snapshot using <xref href="GUID-880B1BDF-C42F-3190-81C2-B2DD555AC8FE.dita#GUID-880B1BDF-C42F-3190-81C2-B2DD555AC8FE/GUID-723AC69A-2D8E-3088-8615-420109250982"><apiname>CCamera::CCameraDirectSnapshot::EnableDirectSnapshotL</apiname></xref>. </p> </li> <li id="GUID-FA031B49-B6EB-5BA4-A0D0-A2BE46B10935"><p>Disable direct snapshot using <xref href="GUID-880B1BDF-C42F-3190-81C2-B2DD555AC8FE.dita#GUID-880B1BDF-C42F-3190-81C2-B2DD555AC8FE/GUID-C7CCB37D-5EB3-3661-B2C0-AB5E08336F95"><apiname>CCamera::CCameraDirectSnapshot::DisableDirectSnapshot</apiname></xref>. </p> </li> <li id="GUID-5E3EFC74-4AB6-5CD2-8FE8-EA98223F59DD"><p>Get the current state of the direct snapshot using <xref href="GUID-880B1BDF-C42F-3190-81C2-B2DD555AC8FE.dita#GUID-880B1BDF-C42F-3190-81C2-B2DD555AC8FE/GUID-EEE03403-7919-3DFB-932E-C40908072BC4"><apiname>CCamera::CCameraDirectSnapshot::GetDirectSnapshotStateL</apiname></xref>. </p> </li> <li id="GUID-2A55C006-E2BB-5BB3-AA04-B4A825FC9461"><p>Retrieve the direct snapshot parameters using <xref href="GUID-880B1BDF-C42F-3190-81C2-B2DD555AC8FE.dita#GUID-880B1BDF-C42F-3190-81C2-B2DD555AC8FE/GUID-E0B87B4C-57ED-3E35-8FFD-C45846E28B1A"><apiname>CCamera::CCameraDirectSnapshot::GetDirectSnapshotParametersL</apiname></xref>. </p> </li> <li id="GUID-B6C4857D-66B4-5B92-9026-55EA8FCC1462"><p>Set the direct snapshot parameters using <xref href="GUID-880B1BDF-C42F-3190-81C2-B2DD555AC8FE.dita#GUID-880B1BDF-C42F-3190-81C2-B2DD555AC8FE/GUID-68726125-8244-329A-8534-C3AA3C5D6EC4"><apiname>CCamera::CCameraDirectSnapshot::SetDirectSnapshotParametersL</apiname></xref>. </p> </li> </ul> <p>You can create the following types of snapshots: </p> <ul><li id="GUID-B40ADDDD-7C1E-5A13-8729-6EEE14DEE42A"><p>Direct snapshot for still images </p> </li> <li id="GUID-29DC32E9-9AA9-54A7-8E37-986469FE7CA9"><p>Client snapshot for still images </p> </li> <li id="GUID-7A3DB8CC-D4A5-5D57-A549-F9112DD86D55"><p>Client snapshot for video </p> </li> </ul> <p> <b> Note</b>: You cannot create direct snapshot for video. </p> <p><b>Direct snapshot for still images</b> </p> <p>This section explains how the implementation notifies about display for direct snapshot for still images. </p> <ul><li id="GUID-E926FD01-3D47-5531-8180-927DAA369EE0"><p>The client enables the direct snapshot through successful call of <xref href="GUID-7447D695-51D8-3F41-A4FA-EAA01DC8555D.dita#GUID-7447D695-51D8-3F41-A4FA-EAA01DC8555D/GUID-7D34F144-E777-3881-992D-A0DFA6FBC9FC"><apiname>Ccamera::CCameraDirectSnapshot::EnableDirectSnapshotL()</apiname></xref>. If the implementation displays the snapshot for individual still images, it notifies the client through observer <xref href="GUID-3E9347CF-F172-3E7B-B209-7F9836090F61.dita#GUID-3E9347CF-F172-3E7B-B209-7F9836090F61/GUID-380EC4D1-B944-331F-8FB5-A7509E75EFE5"><apiname>MDirectViewFinderObserver::DirectSnapshotForImageDisplayed()</apiname></xref>. </p> </li> <li id="GUID-A4D6E76A-A458-52FA-99C2-1E3BB007B2A0"><p>This provides reference to <xref href="GUID-A1E81FF5-3F58-3D41-8FE2-9D6D21004B08.dita"><apiname>CCameraV2DirectViewFinder</apiname></xref> class object which refers a particular direct viewfinder on which the direct snapshot data for still images have been displayed. </p> </li> <li id="GUID-C266C2CD-0211-5F24-9411-39AD676496A4"><p>Identify the specific still image for which the direct snapshot is displayed using<codeph>CCamera::CCameraImageCapture&amp;</codeph> and <xref href="GUID-6579058A-1B31-3F85-AD35-274DA4CF7E69.dita"><apiname>TPostCaptureControlId</apiname></xref>. </p> </li> </ul> <p><b>Client snapshot for still images</b> </p> <p>In client snapshot, the buffer containing snapshot data is sent to the camera client, and you can view the still image captured in the client side. </p> <ul><li id="GUID-8D4643D9-8521-51BB-BBC4-A67FBDF2F778"><p>Display the captured still image in the client side using <xref href="GUID-430C206E-24D7-30BE-98E9-ACD176DDA3A8.dita#GUID-430C206E-24D7-30BE-98E9-ACD176DDA3A8/GUID-AA613F13-7C04-3FBC-9CDF-385E02DE419E"><apiname>MCaptureImageObserver::ClientSnapshotForImageReady</apiname></xref> callback. </p> </li> <li id="GUID-905D9686-3323-5F73-8DAC-697B5C45D9F2"><p>This provides reference to <xref href="GUID-992BCFCD-9F06-35A5-B166-3058F650E360.dita"><apiname>CCameraImageCapture</apiname></xref> class object which was used to issue the capture image operation. </p> </li> <li id="GUID-840E3DC6-9B9F-5C70-A3AE-D6F19936F640"><p>This provides a pointer to <xref href="GUID-3662B571-F84F-34F5-BC8A-AB3B36DEA23E.dita"><apiname>MCameraBuffer2</apiname></xref> which retrieves the snapshot data for the individual still image. </p> </li> <li id="GUID-3A0A532B-73CE-5023-A1D8-AA934F5A2A19"><p>Identify the individual still image for which the implementation has provided the snapshot data using <xref href="GUID-6579058A-1B31-3F85-AD35-274DA4CF7E69.dita"><apiname>TPostCaptureControlId</apiname></xref>. </p> </li> </ul> <p><b>Client snapshot for video</b> </p> <p>In client snapshot, the buffer containing snapshot data is sent to the camera client, and you can view the video captured in the client side. </p> <ul><li id="GUID-2BFAF378-9E39-5D4D-AE7C-615D9AA5A211"><p>Notify the client about the snapshot data for the captured video using <xref href="GUID-7FAEB878-52B1-3A54-9607-69AE09AB8AEB.dita#GUID-7FAEB878-52B1-3A54-9607-69AE09AB8AEB/GUID-61D01CF2-182D-3C64-9518-7708F193963C"><apiname>MCaptureVideoObserver::ClientSnapshotReady</apiname></xref> callback. </p> </li> <li id="GUID-D23E5237-0CD6-5302-84E7-33E09C7DC86D"><p>This provides pointer to <xref href="GUID-3662B571-F84F-34F5-BC8A-AB3B36DEA23E.dita"><apiname>MCameraBuffer2</apiname></xref> class object which retrieves the snapshot for the video being captured. </p> </li> </ul> </section> <section><title>See also</title> <p><xref href="GUID-0B24B36D-F4C5-508A-A65B-18E4E4C45C37.dita">Overview</xref> of Camera SnapShot </p> <p><xref href="GUID-F89F92BA-763D-5531-BF74-C6BF36A589CD.dita">Creating Snapshots</xref>  </p> </section> </conbody></concept>