<?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-BFE8B989-8B73-5D3E-B5F4-13AC016C122C"><title>Direct Viewfinder Tutorials</title><prolog><metadata><keywords/></metadata></prolog><conbody><p>This tutorial introduces you to the Direct Viewfinder API of the Ecam component. </p> <section><title>Purpose</title> <p>This documents provides a detailed description about the Direct Viewfinder API. </p> <p><b>Setup and Configuration Requirements</b> </p> <p>The following are the setup and configuration requirements you need to follow before Direct Viewfinder implementation: </p> <ul><li id="GUID-3978F378-FC87-5848-BD7F-CD2ECC4D2FB6"><p>Client needs to implement the <xref href="GUID-05EEF6CC-E007-348C-8643-AA02D634F90C.dita"><apiname>MdirectViewFinderObserver</apiname></xref>, an observer class to use version 2 direct viewfinder API. This class contains the call-backs necessary to provide notifications in relation to version2 direct viewfinder operations. </p> </li> <li id="GUID-4DDF9DCB-5111-5DEB-A69A-78CF42EF8A8E"><p>Licensee must provide concrete implementation for an interface class <xref href="GUID-4C71BD28-FCB9-33CE-8FAA-A9525350E0E1.dita"><apiname>MCameraV2DirectViewFinder</apiname></xref>, and <xref href="GUID-3B71FBB0-4F32-3CDE-931E-4A1428761E23.dita"><apiname>McameraViewFinder</apiname></xref>. </p> </li> </ul> </section> <section><title>Direct viewfinder</title> <p>Direct viewfinder provides the necessary framework for multiple direct viewfinder support. The direct viewfinder classes are provided as a part of Version2 direct viewfinder implementation. </p> <p><b> Direct Viewfinder Implementation</b> </p> <p>The following tasks will be covered during Direct Viewfinder implementation: </p> <ul><li id="GUID-26D10C6B-2BA0-5C45-B21F-FFDC77D9D368"><p>Create an instance of class <xref href="GUID-9DE13B2C-F605-348F-8056-519DDE4CAE1B.dita"><apiname>CcameraV2DirectViewFinder</apiname></xref> using <xref href="GUID-9DE13B2C-F605-348F-8056-519DDE4CAE1B.dita#GUID-9DE13B2C-F605-348F-8056-519DDE4CAE1B/GUID-7627ECE8-0029-353E-BA20-A1EFCEB7371A"><apiname>CcameraV2DirectViewFinder::NewL()</apiname></xref> method. Client also needs to pass the reference to the instance of class that provides concrete implementation for <xref href="GUID-05EEF6CC-E007-348C-8643-AA02D634F90C.dita"><apiname>MdirectViewFinderObserver</apiname></xref>. </p> </li> <li id="GUID-C5EF0B3A-C9E1-59ED-B650-3B6E0E1564BD"><p>In second phase construction for class <xref href="GUID-4E8A5141-5E4A-322A-9892-8DC49D04986E.dita#GUID-4E8A5141-5E4A-322A-9892-8DC49D04986E/GUID-E0A0EECD-1150-3BC4-B3C6-307B7CE5A1C0"><apiname>Ccamera::CcameraV2DirectViewFinder</apiname></xref>, do the following: </p> <ol id="GUID-AAC445FA-7D43-5695-8BE1-0140C751FFBF"><li id="GUID-3684726A-C33F-5E12-9E61-2F7ACB23C530"><p>Retrieve the handle to the concrete implementation for <xref href="GUID-4C71BD28-FCB9-33CE-8FAA-A9525350E0E1.dita"><apiname>MCameraV2DirectViewFinder</apiname></xref> and <xref href="GUID-0ED13F2A-A4C1-34B6-ADAA-6D04EA60802C.dita"><apiname>MCameraViewFinder</apiname></xref> through a call to <xref href="GUID-4E8A5141-5E4A-322A-9892-8DC49D04986E.dita#GUID-4E8A5141-5E4A-322A-9892-8DC49D04986E/GUID-1F537D7D-5451-3834-869D-3092A4773B83"><apiname>Ccamera::CustomInterface()</apiname></xref>, when appropriate UIDs are provided. </p> <p>UID <xref href="GUID-2789C380-3855-3D91-8ED9-95AF2BFEF8D6.dita"><apiname>KECamMCameraV2DirectViewFinderUid</apiname></xref> is used to retrieve the handle for concrete implementation of <xref href="GUID-4C71BD28-FCB9-33CE-8FAA-A9525350E0E1.dita"><apiname>MCameraV2DirectViewFinder</apiname></xref>. </p> <p>Uid <xref href="GUID-4D9485FF-BA60-3B47-B18C-2E68F907EA62.dita"><apiname>KECamMCameraBaseV2DirectViewFinderUid</apiname></xref> is used to retrieve the handle to concrete implementation for <xref href="GUID-0ED13F2A-A4C1-34B6-ADAA-6D04EA60802C.dita"><apiname>MCameraViewFinder</apiname></xref>. </p> </li> <li id="GUID-3A3B21DC-9D53-5D1D-9252-3E829E29C617"><p>Pass the reference to the direct viewfinder observer to the concrete implementation of <xref href="GUID-4C71BD28-FCB9-33CE-8FAA-A9525350E0E1.dita"><apiname>MCameraV2DirectViewFinder</apiname></xref> through <xref href="GUID-4C71BD28-FCB9-33CE-8FAA-A9525350E0E1.dita#GUID-4C71BD28-FCB9-33CE-8FAA-A9525350E0E1/GUID-A4ED722C-7C61-3194-84D5-98FF12C6C03D"><apiname>MCameraV2DirectViewFinder::SetDirectViewFinderObserver()</apiname></xref>. </p> </li> <li id="GUID-4FB2F394-B7AA-5326-9D80-0626D7105F32"><p>The next step includes the following steps: </p> <ul><li id="GUID-5495C37A-12CF-5613-920F-0107467265C3"><p>Pass the handle of the <xref href="GUID-4E8A5141-5E4A-322A-9892-8DC49D04986E.dita#GUID-4E8A5141-5E4A-322A-9892-8DC49D04986E/GUID-E0A0EECD-1150-3BC4-B3C6-307B7CE5A1C0"><apiname>Ccamera::CcameraV2DirectViewFinder</apiname></xref> to the concrete implementation of <xref href="GUID-4C71BD28-FCB9-33CE-8FAA-A9525350E0E1.dita"><apiname>MCameraV2DirectViewFinder</apiname></xref> through <xref href="GUID-4C71BD28-FCB9-33CE-8FAA-A9525350E0E1.dita#GUID-4C71BD28-FCB9-33CE-8FAA-A9525350E0E1/GUID-25FA000B-3AFC-31A6-8615-3371A92FD8FA"><apiname>MCameraV2DirectViewFinder::SetDirectViewFinderHandle()</apiname></xref>. </p> </li> <li id="GUID-26EA34F3-B1CB-5BF5-BA7E-A8688D16DDBE"><p>Implementation might use this handle in implementing <xref href="GUID-0ED13F2A-A4C1-34B6-ADAA-6D04EA60802C.dita#GUID-0ED13F2A-A4C1-34B6-ADAA-6D04EA60802C/GUID-11B4B0DB-85BB-3CDF-980E-E1F2E25FC3B4"><apiname>MCameraViewFinder:: GetViewFinderHandleL()</apiname></xref> and provide a unique identity to the given viewfinder handle. </p> </li> <li id="GUID-AE796035-D29A-5775-B641-60EA9119BD34"><p>The implementation passes this handle back to the client through direct viewfinder observer callbacks and allows the client to identify the actual direct viewfinder instance that should receive the notification. </p> </li> <li id="GUID-DAF6ED1C-49FA-59A1-9E3E-87DFC2D5667A"><p>Implementation is not supposed to destroy this object. Client will use <xref href="GUID-24FF5ADF-77FD-3F0C-9905-CE9F3AC0144A.dita#GUID-24FF5ADF-77FD-3F0C-9905-CE9F3AC0144A/GUID-C60C6C01-EDE8-3A5D-803C-348FF4263CD3"><apiname>CCameraViewFinder::GetViewFinderHandleL()</apiname></xref> to distinguish a particular direct viewfinder instance. </p> </li> </ul> </li> <li id="GUID-CBD24403-842E-52EB-A211-85A9CBF1635B"><p>Client creates a new instance of the class <xref href="GUID-9DE13B2C-F605-348F-8056-519DDE4CAE1B.dita"><apiname>CcameraV2DirectViewFinder</apiname></xref> for every new direct viewfinder. </p> </li> <li id="GUID-5278C078-CFED-5636-928E-A77FB1E0E8C2"><p>Ecam implementation should keep track of <xref href="GUID-9DE13B2C-F605-348F-8056-519DDE4CAE1B.dita"><apiname>CcameraV2DirectViewFinder</apiname></xref> object deletion. </p> <p>Makes sure that a call-back is not sent, if the client destroys the particular version2 direct viewfinder object. </p> <p>This situation may arise when the call-back gets queued by the Ecam implementation in order to send it across to the client. </p> </li> </ol> <p> <b>Note:</b> Client retains the ownership of <xref href="GUID-9DE13B2C-F605-348F-8056-519DDE4CAE1B.dita"><apiname>CcameraV2DirectViewFinder</apiname></xref> class object. </p> </li> </ul> <p><b>Working with Direct Viewfinder</b> </p> <p>The following steps describe working with direct viewfinder. </p> <ol id="GUID-3824BA16-BF08-5FAE-89D1-FC1E33C078D9"><li id="GUID-3D385A86-D2B3-5522-BE49-E91A49E32E9E"><p>Before starting the direct viewfinder, client has the following options: </p> <ul><li id="GUID-1227612B-E4F9-5792-A9E3-DC4949589BFB"><p>Client can use specific histogram over a direct viewfinder frame by creating specific histogram object through <xref href="GUID-5E76AB90-FE62-37B2-BAAE-A39EA6CE51DA.dita#GUID-5E76AB90-FE62-37B2-BAAE-A39EA6CE51DA/GUID-623EB26C-B5B6-3251-A079-2AC74489042A"><apiname>CCamera::CCameraV2DirectViewFinder::CreateHistogramHandleL()</apiname></xref>. Concrete implementation for <xref href="GUID-4C71BD28-FCB9-33CE-8FAA-A9525350E0E1.dita"><apiname>MCameraV2DirectViewFinder</apiname></xref> provides the concrete factory handle (of type MImplementationFactory*) for the histogram implementation to use it for a particular viewfinder. </p> <p>Histogram related callbacks that would be issued to the client are <xref href="GUID-3E9347CF-F172-3E7B-B209-7F9836090F61.dita#GUID-3E9347CF-F172-3E7B-B209-7F9836090F61/GUID-62EA446B-24AF-37CB-B08B-F261023F12DD"><apiname>MDirectViewFinderObserver::DirectHistogramDisplayed()</apiname></xref> and <xref href="GUID-3E9347CF-F172-3E7B-B209-7F9836090F61.dita#GUID-3E9347CF-F172-3E7B-B209-7F9836090F61/GUID-007D1D36-2EB2-333E-83EB-88E0C024C7C9"><apiname>MDirectViewFinderObserver::ClientHistogramReady()</apiname></xref>. </p> </li> <li id="GUID-864B3109-39E7-52DD-BC26-58F4C257D44E"><p>Client can also use specific image processing over the direct viewfinder frame by creating a dedicated image processing object using <xref href="GUID-34696DA2-68E3-36CB-9B38-61DD25DA89C3.dita#GUID-34696DA2-68E3-36CB-9B38-61DD25DA89C3/GUID-94A6EC52-0218-3DDA-AAE5-70623DFCDC14"><apiname>CCamera:: CCameraV2DirectViewFinder

                        ::GetTransformationHandleL()</apiname></xref>. </p> <p> <xref href="GUID-4C71BD28-FCB9-33CE-8FAA-A9525350E0E1.dita"><apiname>MCameraV2DirectViewFinder</apiname></xref> concrete implementation provides the concrete factory handle of type <xref href="GUID-6BD89347-671F-3518-9777-55801A090C79.dita"><apiname/></xref>, for the image processing implementation to use it for a particular viewfinder. Image processing related callbacks would be issued to the client through <xref href="GUID-09C6DDB6-A208-3C81-9F54-697D4865D99F.dita#GUID-09C6DDB6-A208-3C81-9F54-697D4865D99F/GUID-AA5629D4-6228-3EAE-86DB-CE8A735557B0"><apiname>MCameraObserver2::HandleEvent()</apiname></xref>. </p> </li> </ul> </li> <li id="GUID-D8A60B15-1F68-5E67-877E-DF0418D70BE0"><p>Use <xref href="GUID-A1E81FF5-3F58-3D41-8FE2-9D6D21004B08.dita#GUID-A1E81FF5-3F58-3D41-8FE2-9D6D21004B08/GUID-FC7D1C16-7619-35C2-91B6-B180440C4521"><apiname>CCameraV2DirectViewFinder::StartViewFinderDirectL()</apiname></xref> method to start direct viewfinder. In case of direct viewfinder, you can specify the in-screen co-ordinates, to which view finder data is to be transferred. The in-screen co-ordinates can be modified, for example, the camera requires the destination to have a certain byte alignment. </p> </li> <li id="GUID-B810E08C-37E5-57B5-A39E-7A6AD0BE3DF1"><p>If there is a conflict, the size of image returned by the view finder will not be the exact size requested. This occurs when the requirement of the view finder to show the unclipped view in the ratio required for image capture or video capture. The camera will return the best match. </p> </li> <li id="GUID-6579DEA2-D08A-5C65-983A-2E45F715A8C6"><p>Implementation issues callback <xref href="GUID-3E9347CF-F172-3E7B-B209-7F9836090F61.dita#GUID-3E9347CF-F172-3E7B-B209-7F9836090F61/GUID-163D5092-A013-3477-8459-CEC9FFF1EDBA"><apiname>MDirectViewFinderObserver::DirectViewFinderFirstFrameDisplayed()</apiname></xref> and notifies the client that the first viewfinder frame has been displayed successfully. Implementation passes the viewfinder handle along with the callback. </p> </li> <li id="GUID-22758BBB-526D-55B5-9CF1-368A4DB5E8A3"><p>If the implementation finds any error during direct viewfinder processing, it stops the specific direct viewfinder and issue the callback <xref href="GUID-3E9347CF-F172-3E7B-B209-7F9836090F61.dita#GUID-3E9347CF-F172-3E7B-B209-7F9836090F61/GUID-B02ED9B8-B195-36F4-BA0F-489DD677B080"><apiname>MDirectViewFinderObserver::DirectViewFinderFailed()</apiname></xref>. </p> </li> <li id="GUID-65DAA94C-554D-5815-85E9-27912404ED5F"><p>Client can use direct snapshot for still images captured over the direct viewfinder screen by creating a dedicated direct snapshot object through <xref href="GUID-5E76AB90-FE62-37B2-BAAE-A39EA6CE51DA.dita#GUID-5E76AB90-FE62-37B2-BAAE-A39EA6CE51DA/GUID-54FCD3DA-8255-33A5-9181-F8817226A821"><apiname>CCamera::CCameraV2DirectViewFinder::GetDirectSnapshotHandleL()</apiname></xref>. </p> <p>See also <xref href="GUID-021C509B-C821-3401-B2F4-DE7F52BB16D4.dita#GUID-021C509B-C821-3401-B2F4-DE7F52BB16D4/GUID-880B1BDF-C42F-3190-81C2-B2DD555AC8FE"><apiname>CCamera::CCameraDirectSnapshot</apiname></xref> and their related M class <xref href="GUID-E75CBA2D-933F-33CF-9F66-0868D6BC0649.dita"><apiname>MCameraDirectSnapshot</apiname></xref>. </p> </li> </ol> </section> <section><title>See also</title> <p><xref href="GUID-367ADFD7-A0F5-59D3-BF83-913CB8126B9D.dita">Viewfinder API Overview</xref>  </p> <p><xref href="GUID-2CC30ECA-053D-57FF-8E9D-8FA733A031C9.dita">Viewfinder Tutorial</xref>  </p> <p><xref href="GUID-2A6AAD9C-BB99-5145-B4A2-FCEF6BECCFD4.dita">Client Viewfinder Tutorials</xref>  </p> </section> </conbody></concept>