<?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-2A6AAD9C-BB99-5145-B4A2-FCEF6BECCFD4"><title>Client Viewfinder</title><prolog><metadata><keywords/></metadata></prolog><conbody><p>This tutorial introduces to the Client Viewfinder API of the Ecam component. </p> <section><title>Purpose</title> <p>This documents provides a detailed description about the Client 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 Client Viewfinder implementation: </p> <ul><li id="GUID-FB7B0565-6139-5A1D-B53A-E4F309626131"><p>Client needs to implement the dedicated observer <xref href="GUID-C4F40144-7132-309A-B648-E366786B4DE4.dita"><apiname>MclientViewFinderObserver</apiname></xref> to use the client viewfinder API. </p> <p>The Ecam implementation will issue the call-backs in this observer class, when the client viewfinder operations are ready to be notified. </p> </li> <li id="GUID-A233A435-14CE-5469-A7EB-8A2517F5A045"><p>Licensee must provide concrete implementation for an interface class <xref href="GUID-4C8C5C49-B5DE-363A-93FE-099BB1413844.dita"><apiname>McameraClientViewFinder</apiname></xref> and <xref href="GUID-3B71FBB0-4F32-3CDE-931E-4A1428761E23.dita"><apiname>McameraViewFinder</apiname></xref>. </p> </li> </ul> </section> <section><title>Client Viewfinder </title> <p><b>Client Viewfinder Implementation</b> </p> <p>The following tasks will be covered during Client Viewfinder implementation: </p> <ul><li id="GUID-D84A7292-DC2A-586A-A123-8B98793FAEEB"><p>Create an instance of class <xref href="GUID-B43EAE70-1B2C-3B41-B9A8-7FBB1A87C804.dita"><apiname>CcameraClientViewFinder</apiname></xref> through <xref href="GUID-B43EAE70-1B2C-3B41-B9A8-7FBB1A87C804.dita#GUID-B43EAE70-1B2C-3B41-B9A8-7FBB1A87C804/GUID-F94E946B-34DD-377D-A010-766E638D1958"><apiname>CcameraClientViewFinder::NewL()</apiname></xref> factory method. Client also needs to pass the reference to the instance of class for providing concrete implementation of <xref href="GUID-E88979A4-EC0E-3198-8474-38711C8CA5D1.dita"><apiname>MClientViewFinderObserver</apiname></xref>. </p> <p>This class maps the exported call to an internal object of class <xref href="GUID-4C8C5C49-B5DE-363A-93FE-099BB1413844.dita"><apiname>McameraClientViewFinder</apiname></xref>, which provides the camera version2 client viewfinder functionality. </p> </li> <li id="GUID-7475A895-2055-591C-BCD9-2FB9A6EEE48B"><p>In second phase construction for class <xref href="GUID-4E8A5141-5E4A-322A-9892-8DC49D04986E.dita#GUID-4E8A5141-5E4A-322A-9892-8DC49D04986E/GUID-BF6CDD75-C370-31B0-89A8-6BA3237C1B58"><apiname>Ccamera::CcameraClientViewFinder</apiname></xref>, do the following: </p> <ol id="GUID-CE3B3BC7-665A-5510-973A-0CCF52E5A3E6"><li id="GUID-24C5E026-7DCC-5861-BBF8-9A3729943684"><p>When appropriate UIDs are provided, retrieve the handle to the concrete implementation for <xref href="GUID-06A2DDCE-3296-3773-A2D0-74460E216F39.dita"><apiname>MCameraClientViewFinder</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-CC199F00-9390-39A3-89C8-6C13EF0B82CB"><apiname>Ccamera::CustomInterface</apiname></xref>. </p> </li> <li id="GUID-A1313257-FCBB-595C-AF5D-FD0DFD29A60F"><p> <xref href="GUID-EE1F2D79-0C38-3A3F-A81E-24872ADF9BFB.dita"><apiname>KECamMCameraClientViewFinderUid</apiname></xref> UID is used to retrieve the handle for concrete implementation of <xref href="GUID-06A2DDCE-3296-3773-A2D0-74460E216F39.dita"><apiname>MCameraClientViewFinder</apiname></xref>. </p> <p> <xref href="GUID-23CB6900-72E3-3D32-B799-27F9A1A92AC3.dita"><apiname>KECamMCameraBaseClientViewFinderUid</apiname></xref> UID is used to retrieve the handle to concrete implementation for <xref href="GUID-BCB44358-0774-3D07-BCD8-E54E7055D6F2.dita"><apiname>MCameraViewFinder.</apiname></xref>  </p> </li> <li id="GUID-57130901-B151-5EBF-BF7B-9FA84F72CF5D"><p>Pass the reference to the client viewfinder observer to the concrete implementation of <xref href="GUID-06A2DDCE-3296-3773-A2D0-74460E216F39.dita"><apiname>MCameraClientViewFinder</apiname></xref> through <xref href="GUID-06A2DDCE-3296-3773-A2D0-74460E216F39.dita#GUID-06A2DDCE-3296-3773-A2D0-74460E216F39/GUID-EB4A2E90-B246-3EFE-9DE9-102A17A83B9C"><apiname>MCameraClientViewFinder::SetClientViewFinderObserver()</apiname></xref>. </p> </li> <li id="GUID-B0F96D78-0F9E-5E09-A41B-075CBD8DE425"><p>Pass the handle of the <xref href="GUID-4E8A5141-5E4A-322A-9892-8DC49D04986E.dita#GUID-4E8A5141-5E4A-322A-9892-8DC49D04986E/GUID-7ACD280E-0347-3248-970E-22FC22163FBD"><apiname>Ccamera::CcameraClientViewFinder()</apiname></xref> to the concrete implementation of <xref href="GUID-06A2DDCE-3296-3773-A2D0-74460E216F39.dita"><apiname>MCameraClientViewFinder</apiname></xref> through <xref href="GUID-06A2DDCE-3296-3773-A2D0-74460E216F39.dita#GUID-06A2DDCE-3296-3773-A2D0-74460E216F39/GUID-FF80D575-6449-35C8-B0D7-46883C098C79"><apiname>MCameraClientViewFinder::SetClienttViewFinderHandle()</apiname></xref>. </p> <p>Implementation can use this handle to implement <xref href="GUID-0ED13F2A-A4C1-34B6-ADAA-6D04EA60802C.dita#GUID-0ED13F2A-A4C1-34B6-ADAA-6D04EA60802C/GUID-A3F93566-047A-3741-A6E4-3E62704E6E7C"><apiname>MCameraViewFinder::GetViewFinderHandleL()</apiname></xref> and provide a unique identity to the given viewfinder handle. </p> <p>Implementation passes this handle to the client through client viewfinder observer callbacks, and allows the client to identify the actual client viewfinder instance that should receive the notification. </p> <p> <b>Note</b>:Implementation should not 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 client viewfinder instance. </p> </li> </ol> </li> <li id="GUID-7E38BDFE-3575-54EB-82B6-0663CE691D8E"><p>If multiple client viewfinders need to be run, client needs to create a new object for CcameraClientViewFinder each time. </p> </li> <li id="GUID-A0726C56-CC32-57C3-A57F-851D3F4E419E"><p>Ecam implementation keeps track of <xref href="GUID-B43EAE70-1B2C-3B41-B9A8-7FBB1A87C804.dita"><apiname>CcameraClientViewFinder</apiname></xref> object deletion. </p> <p>Makes sure that a call-back is not sent, if the client destroys the particular <xref href="GUID-B43EAE70-1B2C-3B41-B9A8-7FBB1A87C804.dita"><apiname>CcameraClientViewFinder</apiname></xref> class 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> </ul> <p> <b>Note:</b>  </p> <ul><li id="GUID-E568505D-C47C-51A4-B2A1-EEB4BA40A00C"><p>Client retains the ownership of <xref href="GUID-B43EAE70-1B2C-3B41-B9A8-7FBB1A87C804.dita"><apiname>CcameraClientViewFinder</apiname></xref> class object. </p> </li> <li id="GUID-58F6480E-3287-5A14-932C-1E440B77CB7D"><p> <xref href="GUID-09C6DDB6-A208-3C81-9F54-697D4865D99F.dita#GUID-09C6DDB6-A208-3C81-9F54-697D4865D99F/GUID-E9CFF09B-5B14-3F6B-BC45-92238D6EEA06"><apiname>MCameraObserver2::ViewFinderReady()</apiname></xref> will not be used with <xref href="GUID-ED7C0789-5243-3EB2-8206-98F26DEDEA6D.dita"><apiname>CCameraClientViewFinder</apiname></xref> class. </p> </li> </ul>  <p><b>Working with Client Viewfinder</b> </p> <p>The following steps describes working with client viewfinder: </p> <ol id="GUID-25D4FB61-43F4-5F60-887A-F19864C4565E"><li id="GUID-1352F5AE-2986-57B5-BA96-1907DCE46FB9"><p>Before starting the client viewfinder, client has the following options: </p> <ul><li id="GUID-767FD277-EEAB-5EBB-9C8C-7B44513345E3"><p>Client can use specific histogram over the client viewfinder frame by creating a dedicated histogram object through <xref href="GUID-4618B02E-CD2E-3DEA-979F-4C55AE3D45EC.dita#GUID-4618B02E-CD2E-3DEA-979F-4C55AE3D45EC/GUID-5B1F42C4-8FDF-3DDD-9411-21CFBD88EFE3"><apiname>CCamera::CCameraClientViewFinder::CreateHistogramHandleL()</apiname></xref>. Concrete implementation for <xref href="GUID-06A2DDCE-3296-3773-A2D0-74460E216F39.dita"><apiname>MCameraClientViewFinder</apiname></xref> provides the concrete factory handle of type MImplementationFactory, for the histogram implementation of a particular viewfinder. </p> <p>Histogram related callbacks which would eventually be issued to the client are <xref href="GUID-E88979A4-EC0E-3198-8474-38711C8CA5D1.dita#GUID-E88979A4-EC0E-3198-8474-38711C8CA5D1/GUID-8A46D664-C7F6-3ADC-A210-74E678B9D5D4"><apiname>MClientViewFinderObserver::DirectHistogramDisplayed()</apiname></xref> and <xref href="GUID-E88979A4-EC0E-3198-8474-38711C8CA5D1.dita#GUID-E88979A4-EC0E-3198-8474-38711C8CA5D1/GUID-28253408-A559-3E90-91B8-34B408E4B24C"><apiname>MClientViewFinderObserver::ClientHistogramReady()</apiname></xref>. </p> </li> <li id="GUID-F897AF7E-7F7A-5F52-986F-678BC3EAF0F6"><p>Client can also use specific image processing over the client viewfinder frame by creating a dedicated image processing object through <xref href="GUID-4618B02E-CD2E-3DEA-979F-4C55AE3D45EC.dita#GUID-4618B02E-CD2E-3DEA-979F-4C55AE3D45EC/GUID-BD18568F-16B1-3A52-A935-C47B52103629"><apiname>CCamera::CCameraClientViewFinder::GetTransformationHandleL()</apiname></xref>. Concrete implementation for <xref href="GUID-06A2DDCE-3296-3773-A2D0-74460E216F39.dita"><apiname>MCameraClientViewFinder</apiname></xref> provides the concrete factory handle of type MImplementationFactory, for the image processing implementation to use it specifically for a particular viewfinder. </p> <p>Image processing related callbacks which 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-8AC79B9B-7AF6-5145-814B-27989B113369"><p>Use <xref href="GUID-ED7C0789-5243-3EB2-8206-98F26DEDEA6D.dita#GUID-ED7C0789-5243-3EB2-8206-98F26DEDEA6D/GUID-FF9702B4-1530-371E-8EA3-75D4117B4ED2"><apiname>CCameraClientViewFinder::StartClientViewFinderL()</apiname></xref> to start client viewfinder and to retrieve viewfinder frames in the specified format and size. Client specifies the format and size for the viewfinder frames. </p> </li> <li id="GUID-0B9E890C-6ED5-5C60-A4EC-7B1E5BAA611B"><p>ECam adaptation owns the buffer that passes the viewfinder frames to the client through <xref href="GUID-2E8D5B41-2E0F-3296-AC3B-762C9E94C66B.dita"><apiname>McameraOberver2</apiname></xref> notification. The client releases the buffers passed to it by the adaptation, when it has handled the viewfinder frame. The adaptation should not reuse the buffers passed, until the client releases them. The Ecam adaptation secures it against the clients that do not release the buffers within a specific time interval. </p> </li> <li id="GUID-549369CC-3335-55CD-B1D4-0B754E8A8D13"><p>Implementation issues callback <xref href="GUID-DAD2AA62-442A-32DF-AD98-2CBC1AD9B7F1.dita"><apiname>ViewFinderBufferReady()</apiname></xref> to notify the client that viewfinder frames of client are available. Implementation passes the viewfinder handle along with the callback. Client identifies the actual client viewfinder object and retrieve the viewfinder data through C<xref href="GUID-8B6B6B32-D6D7-3628-967F-37CF57C9125A.dita#GUID-8B6B6B32-D6D7-3628-967F-37CF57C9125A/GUID-35782E1D-D373-316F-8BCE-9AAD2823AA34"><apiname>CameraClientViewFinder::GetViewFinderBufferL()</apiname></xref>. </p> <p> </p> </li> </ol> <p>A client calls the following functions to control the view finder: </p> <ul><li id="GUID-4AB95DAA-7A85-5E95-A5A3-66BD603C54E3"><p> <xref href="GUID-021C509B-C821-3401-B2F4-DE7F52BB16D4.dita#GUID-021C509B-C821-3401-B2F4-DE7F52BB16D4/GUID-11019EB4-5496-33F9-AB46-0C8A18EC8E57"><apiname>CCamera::StartViewFinderBitmapsL()</apiname></xref>  </p> </li> <li id="GUID-15B17F9D-3BA5-5AA3-BAC5-3AB3A82B0DE8"><p> <xref href="GUID-021C509B-C821-3401-B2F4-DE7F52BB16D4.dita#GUID-021C509B-C821-3401-B2F4-DE7F52BB16D4/GUID-FD7C01CC-8993-33D7-8ADA-9C56FEDEE791"><apiname>CCamera::SetViewFinderMirrorL()</apiname></xref>  </p> </li> <li id="GUID-48E872FB-6441-51CF-B910-54F5A4B0D686"><p> <xref href="GUID-021C509B-C821-3401-B2F4-DE7F52BB16D4.dita#GUID-021C509B-C821-3401-B2F4-DE7F52BB16D4/GUID-E762211D-2528-3850-9DE2-84282066644C"><apiname>CCamera::StopViewFinder()</apiname></xref>  </p> </li> </ul> <p>If the implementation finds any error during client viewfinder operation, it stops the specific client viewfinder and issue the callback <xref href="GUID-3E9347CF-F172-3E7B-B209-7F9836090F61.dita#GUID-3E9347CF-F172-3E7B-B209-7F9836090F61/GUID-CD4AF71F-1C85-31A0-B378-FFDD228C1F67"><apiname>MDirectViewFinderObserver::ViewFinderBufferReady()</apiname></xref> with the appropriate error code. </p> </section> <section><title>See also</title> <p><xref href="GUID-367ADFD7-A0F5-59D3-BF83-913CB8126B9D.dita">Overview</xref> of Viewfinder API </p> <p>The <xref href="GUID-2CC30ECA-053D-57FF-8E9D-8FA733A031C9.dita">Viewfinder</xref> Tutorial </p> <p>The <xref href="GUID-BFE8B989-8B73-5D3E-B5F4-13AC016C122C.dita">Direct Viewfinder</xref> Tutorial </p> </section> </conbody></concept>