<?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-8B7ABDB0-B016-5106-824E-D823F1D2959F"><title>Working with Overlays</title><prolog><metadata><keywords/></metadata></prolog><conbody><p>This tutorials describes about the APIs used with Overlays. </p> <section><title>Purpose</title> <p>This documents provides detailed description about creating and working with Overlays. </p> <p><b>Setup and Configuration Requirements</b> </p> <p>The following are the setup and configuration requirements you need to follow before Overlay implementation: </p> <ul><li id="GUID-80EF2621-E99E-5A6A-A45E-6BABE63A12BA"><p>Licensee need to provide <xref href="GUID-D54E15C8-4952-3A9C-807A-BC7DABB087D4.dita"><apiname>McameraOverlay</apiname></xref>, interface class implementation. </p> </li> <li id="GUID-3C86F967-D172-593D-82E9-ADADD64D0BA4"><p>The providers of the camera extension API for extra features of image overlays, must provide <xref href="GUID-9C5233B4-6BD6-3139-B0B7-B01B14C18D2B.dita"><apiname>MCameraOverlay2</apiname></xref>, interface class implementation. </p> </li> </ul> </section> <section><title>Creating Overlays </title> <p>The following tasks cover the creation of overlays: </p> <ol id="GUID-8BFAC0B2-5EDE-5307-9349-2ADAF73C3C14"><li id="GUID-5C74F98A-3C76-50AB-90CD-170A45A3D830"><p>Create an object of class <xref href="GUID-4E8A5141-5E4A-322A-9892-8DC49D04986E.dita#GUID-4E8A5141-5E4A-322A-9892-8DC49D04986E/GUID-B37E8556-885D-3BDD-B4F2-3788CC242A7D"><apiname>Ccamera::CCameraOverlay</apiname></xref> using the <xref href="GUID-1F37AA0E-FFB6-3A85-B17A-303D3500C275.dita#GUID-1F37AA0E-FFB6-3A85-B17A-303D3500C275/GUID-2306CE6E-BA4B-33A1-8E05-2CBEE7F74E8F"><apiname>CcameraOverlay::NewL()</apiname></xref> factory method. </p> <p>This class maps the exported call to <xref href="GUID-D54E15C8-4952-3A9C-807A-BC7DABB087D4.dita"><apiname>McameraOverlay</apiname></xref> class and <xref href="GUID-3C1A0001-1653-391E-88E6-3844EF68C7ED.dita"><apiname>McameraOverlay2</apiname></xref>, which provides the overlay functionality. </p> </li> <li id="GUID-29884B0D-B736-5D21-8B19-4652DBD92BDB"><p>In second phase construction for <xref href="GUID-75F14618-727C-340C-B34A-ECEEA5F612F9.dita"><apiname>CCameraOverlay</apiname></xref>, </p> <ul><li id="GUID-2D552178-5650-5D10-A007-3F900732FC1B"><p>retrieve the handle to the concrete implementation for <xref href="GUID-D54E15C8-4952-3A9C-807A-BC7DABB087D4.dita"><apiname>McameraOverlay</apiname></xref> and <xref href="GUID-3C1A0001-1653-391E-88E6-3844EF68C7ED.dita"><apiname>McameraOverlay2</apiname></xref> using <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> method, when specific UIDS are passed. </p> </li> <li id="GUID-63D351BC-D785-5CDE-B1DE-C30CB0390A7E"><p> <xref href="GUID-A2495EB1-B50B-3557-BF43-098A1098371D.dita"><apiname>KECamMCameraOverlayUid</apiname></xref> and <xref href="GUID-7B0B09F8-AD72-3BD5-9D54-936666A15BCB.dita"><apiname>KECamMCameraOverlay2Uid</apiname></xref> are used to retrieve handle for <xref href="GUID-D54E15C8-4952-3A9C-807A-BC7DABB087D4.dita"><apiname>McameraOverlay</apiname></xref> and <xref href="GUID-3C1A0001-1653-391E-88E6-3844EF68C7ED.dita"><apiname>McameraOverlay2</apiname></xref> derived class objects respectively. </p> </li> </ul> </li> <li id="GUID-F8743483-77D7-56BF-AF45-89695A3770E0"><p>Get information about the overlay functionality supported by the ECam implementation server using <xref href="GUID-5CF1EE7D-EAED-39F7-AF9D-73DD813B64F9.dita#GUID-5CF1EE7D-EAED-39F7-AF9D-73DD813B64F9/GUID-3420058A-A1E3-3E80-99D3-CD0314B0227F"><apiname>CCamera::CCameraOverlay::GetOverlaySupport()</apiname></xref> method. </p> <ul><li id="GUID-1771B0D9-020B-5AA2-B5A4-3CFA723CBBC6"><p>Class <xref href="GUID-B78627FD-EE23-3814-B5F2-6CED8547734C.dita#GUID-B78627FD-EE23-3814-B5F2-6CED8547734C/GUID-E30DFE88-9F92-3848-9D61-E26EB6FC1317"><apiname>Ccamera::CcameraOverlay::ToverlaySupportInfo</apiname></xref> retrieves the supported color formats. </p> </li> <li id="GUID-27966949-6A01-5675-BAAB-BA3A09FE452F"><p>ECam implementation uses <xref href="GUID-FE6C2803-1928-34A9-A048-E92E2A4A2D80.dita#GUID-FE6C2803-1928-34A9-A048-E92E2A4A2D80/GUID-8C901E94-2828-38F2-A0C1-D23246D24416"><apiname>ToverlaySupportInfo::Size()</apiname></xref> and <xref href="GUID-FE6C2803-1928-34A9-A048-E92E2A4A2D80.dita#GUID-FE6C2803-1928-34A9-A048-E92E2A4A2D80/GUID-F0D764AD-96DA-3444-8BFE-A9D36F895433"><apiname>ToverlaySupportInfo::Version()</apiname></xref> to verify if client requires the same version of <xref href="GUID-FE6C2803-1928-34A9-A048-E92E2A4A2D80.dita"><apiname>ToverlaySupportInfo</apiname></xref>. Client retrieves the overlay support per camera mode by passing the desired camera mode through <xref href="GUID-FE6C2803-1928-34A9-A048-E92E2A4A2D80.dita#GUID-FE6C2803-1928-34A9-A048-E92E2A4A2D80/GUID-520DC7A2-5E3C-37F5-B7C3-3CFFF6F38E95"><apiname>ToverlaySupportInfo::iDesiredCameraMode</apiname></xref>. </p> </li> <li id="GUID-3B2B03DA-F106-5926-9E26-9D17AACA37D1"><p>In viewfinder mode, client also passes the viewfinder handle <xref href="GUID-FE6C2803-1928-34A9-A048-E92E2A4A2D80.dita#GUID-FE6C2803-1928-34A9-A048-E92E2A4A2D80/GUID-08F63ED9-DCE8-39FC-870E-1018F6B8A689"><apiname>ToverlaySupportInfo::iViewFinderHandle</apiname></xref>, for which the overlay support information is required. </p> </li> <li id="GUID-33D59B7F-B15E-554C-A5D3-E556D88BC45E"><p>If client specifies <xref href="GUID-FE6C2803-1928-34A9-A048-E92E2A4A2D80.dita#GUID-FE6C2803-1928-34A9-A048-E92E2A4A2D80/GUID-FEA78F59-AB9A-3AB7-B2D9-FC3F1AE45C60"><apiname>ToverlaySupportInfo::
                     iDesiredCameraMode</apiname></xref> as <xref href="GUID-5CF1EE7D-EAED-39F7-AF9D-73DD813B64F9.dita#GUID-5CF1EE7D-EAED-39F7-AF9D-73DD813B64F9/GUID-E73C6D08-FFA7-3BF1-A652-E801D3AB0855"><apiname>CCamera::CCameraOverlay::EmodeNone</apiname></xref> and <xref href="GUID-FE6C2803-1928-34A9-A048-E92E2A4A2D80.dita#GUID-FE6C2803-1928-34A9-A048-E92E2A4A2D80/GUID-ABE7B284-CB29-3D8E-872A-6B20F43E015B"><apiname>ToverlaySupportInfo:: iViewFinderHandle</apiname></xref> as <xref href="GUID-C028D6F6-B893-3B7B-A1A2-BD42F868E647.dita"><apiname>KECamOverlayNoSpecificViewFinderHandle</apiname></xref>, ECAM implementation provides the overlay support information applicable to every camera mode. </p> </li> </ul> </li> <li id="GUID-2286C915-17D9-5605-8974-1D2C835C9F38"><p>Create an image overlay object using <xref href="GUID-5CF1EE7D-EAED-39F7-AF9D-73DD813B64F9.dita#GUID-5CF1EE7D-EAED-39F7-AF9D-73DD813B64F9/GUID-197F2DA4-6184-31C4-ABF5-D33207C65DE5"><apiname>CCamera::CCameraOverlay::CreateOverlayL()</apiname></xref> method. After successful creation of overlay object on the ECam implementation, client receives a specific overlay handle as return value of <xref href="GUID-5CF1EE7D-EAED-39F7-AF9D-73DD813B64F9.dita#GUID-5CF1EE7D-EAED-39F7-AF9D-73DD813B64F9/GUID-197F2DA4-6184-31C4-ABF5-D33207C65DE5"><apiname>CCamera::CCameraOverlay::CreateOverlayL()</apiname></xref>. Client also passes the parameters representing the overlay and the image to be used as an overlay. </p> </li> </ol> </section> <section><title>Working with Overlays</title> <p>You can do the following tasks when working with overlays. </p> <ol id="GUID-D0C94817-4057-5A18-8839-AC776C2AED5D"><li id="GUID-CC0ED63E-E99B-51ED-85E2-5047C15F4FF1"><p>Make sure that you create an overlay object using <xref href="GUID-5CF1EE7D-EAED-39F7-AF9D-73DD813B64F9.dita#GUID-5CF1EE7D-EAED-39F7-AF9D-73DD813B64F9/GUID-197F2DA4-6184-31C4-ABF5-D33207C65DE5"><apiname>CCamera::CCameraOverlay::CreateOverlayL()</apiname></xref> method. Multiple overlays may be created by the client. The specific overlay handle represents a particular overlay. </p> </li> <li id="GUID-1A9E9D8B-B9A9-5AF7-AB8A-65749AAE99AE"><p>Get the overlay image data for a specified overlay using <xref href="GUID-5CF1EE7D-EAED-39F7-AF9D-73DD813B64F9.dita#GUID-5CF1EE7D-EAED-39F7-AF9D-73DD813B64F9/GUID-8028C077-13AA-3214-92E9-6AE19570B931"><apiname>CCamera::CCameraOverlay::GetOverlayBitmapL()</apiname></xref> method. ECam implementation transfers the ownership of the overlay image to the client. </p> </li> <li id="GUID-49DA8F5B-68BB-540F-9F44-8D241DFD8A5E"><p>Get the overlay image parameters for a specified overlay using <xref href="GUID-5CF1EE7D-EAED-39F7-AF9D-73DD813B64F9.dita#GUID-5CF1EE7D-EAED-39F7-AF9D-73DD813B64F9/GUID-1C26E162-3263-38C2-9690-CBAE2272EBF6"><apiname>CCamera::CCameraOverlay::GetOverlayParametersL()</apiname></xref> method. </p> <ul><li id="GUID-3D8BE4C5-E3FB-5526-821B-AFEE385F4776"><p>ECam implementation uses <xref href="GUID-AB5877A3-45BB-3E01-9037-86AB3C3F8CC3.dita"><apiname>ToverlayParameters</apiname></xref> object passed by the client to provide the relevant information. If overlay type specified by <xref href="GUID-AB5877A3-45BB-3E01-9037-86AB3C3F8CC3.dita#GUID-AB5877A3-45BB-3E01-9037-86AB3C3F8CC3/GUID-C3155F45-35C4-35BF-9E7E-50607975A25D"><apiname>ToverlayParameters::iCurrentTypes</apiname></xref> is <xref href="GUID-9ED27C17-4F9B-3A2B-BCB6-AA10BB750531.dita#GUID-9ED27C17-4F9B-3A2B-BCB6-AA10BB750531/GUID-EAF2E2ED-2462-3D19-B18F-D4041CA4FE9A"><apiname>CCamera::CCameraOverlay::ToverlayType::EperPixel</apiname></xref>, alpha value given by <xref href="GUID-AB5877A3-45BB-3E01-9037-86AB3C3F8CC3.dita#GUID-AB5877A3-45BB-3E01-9037-86AB3C3F8CC3/GUID-6F18CD5F-36D9-332B-A00A-43BD42FED139"><apiname>ToverlayParameters::iAlphaValue</apiname></xref> will not be used. </p> </li> <li id="GUID-DF011E1E-B74E-5E09-B971-66351874E486"><p> <xref href="GUID-AB5877A3-45BB-3E01-9037-86AB3C3F8CC3.dita#GUID-AB5877A3-45BB-3E01-9037-86AB3C3F8CC3/GUID-7EFA28BE-D922-3D3A-BA1A-BFDF0F7F9D0B"><apiname>ToverlayParameters:: iViewFinderHandle</apiname></xref> provides the handle for the viewfinder on which the overlay is supposed to be applied. </p> </li> <li id="GUID-FB60F04F-26D8-5B2F-85E8-5661FEB1ED4F"><p>Only one viewfinder handle can be passed. If <xref href="GUID-C028D6F6-B893-3B7B-A1A2-BD42F868E647.dita"><apiname>KECamOverlayNoSpecificViewFinderHandle</apiname></xref> is provided by the implementation, then the overlay is supposed to be applied for every viewfinder handle of type as given by <xref href="GUID-8119DBE6-9344-3F9E-83A0-041B4CE74053.dita"><apiname>iCurrentModes</apiname></xref>. If <xref href="GUID-4170540A-7A57-3869-AE45-A0BC93D15110.dita"><apiname>KECamOverlayInvalidViewFinderHandle</apiname></xref> is provided, then <xref href="GUID-9A97AA55-4C2D-3CF3-A3E8-31774E26FC45.dita#GUID-9A97AA55-4C2D-3CF3-A3E8-31774E26FC45/GUID-5A318BA9-5DB2-363B-8CB7-4A8259F6C55F"><apiname>TOverlayParameters::iCurrentModes</apiname></xref> will not be omitted and overlay will be applied for every viewfinder along with other camera modes. </p> </li> </ul> </li> <li id="GUID-0F77DD3D-A2B9-5244-A16F-AF59C54062C1"><p>Set overlay image data using<xref href="GUID-5CF1EE7D-EAED-39F7-AF9D-73DD813B64F9.dita#GUID-5CF1EE7D-EAED-39F7-AF9D-73DD813B64F9/GUID-F2235006-F093-3DDD-AB80-E461F4A56CE0"><apiname>CCamera::CCameraOverlay::SetOverlayBitmapL()</apiname></xref> method, if it was not specified when the overlay was created using <xref href="GUID-7EB4D87A-5A4C-3A46-95BB-56BA4371C45C.dita"><apiname>CreateOverlayL()</apiname></xref> method. This changes the overlay image data for a specified overlay. </p> </li> <li id="GUID-58343E30-1DAC-54B7-95C5-6D28FE3255F6"><p>When this method is called, overlay size should not be changed for a given overlay. Hence, the client should not call <xref href="GUID-8C9476F2-D5BC-3A16-A3C4-8D9FD29AA86D.dita"><apiname>SetOverlayParametersL()</apiname></xref> after this method, since the new parameters might not be compatible with the overlay image set. </p> </li> <li id="GUID-F189DC8E-7ED5-5619-91BA-CCB5B88446B2"><p>Set the new parameters for the specific overlay using <xref href="GUID-5CF1EE7D-EAED-39F7-AF9D-73DD813B64F9.dita#GUID-5CF1EE7D-EAED-39F7-AF9D-73DD813B64F9/GUID-EC9D9EF2-72BB-32D7-8941-138EF68932F9"><apiname>CCamera::CCameraOverlay::SetOverlayParametersL()</apiname></xref> method. </p> <p>This might exit with an error if <xref href="GUID-24C99B98-57AE-347F-BDB8-E8E909CFE4FA.dita"><apiname>SetOverlayBitmapL()</apiname></xref> API is called before this method. </p> </li> <li id="GUID-43798A6D-41CE-5C69-8A24-2449E799FE7B"><p>Set the overlay image data using <xref href="GUID-5CF1EE7D-EAED-39F7-AF9D-73DD813B64F9.dita#GUID-5CF1EE7D-EAED-39F7-AF9D-73DD813B64F9/GUID-CF904B94-CCE4-3CC0-8147-3DAC352B20F0"><apiname>CCamera::CCameraOverlay::SetModifiableOverlayBitmapL()</apiname></xref> method, if it was not specified by<xref href="GUID-7EB4D87A-5A4C-3A46-95BB-56BA4371C45C.dita"><apiname>CreateOverlayL()</apiname></xref> during overlay creation. </p> <p>Ownership of the overlay image is passed to the ECam implementation. See also <b>step 5</b> above. </p> </li> <li id="GUID-FFD3E34A-9EA5-5769-8236-4E1DDA787CD6"><p>Use the overloaded <xref href="GUID-1CEA39E3-0011-3A6E-9EA0-514FC8B69D16.dita#GUID-1CEA39E3-0011-3A6E-9EA0-514FC8B69D16/GUID-51444180-74AC-3B78-BB7C-10F4F7A92EA4"><apiname>CCamera::CCameraOverlay::GetAllOverlaysInZOrderL
                (CCamera::CCameraOverlay::TOverlayCameraMode aOverlayCameraMode, TInt
                aViewFinderHandle, RArray&lt;TUint&gt;&amp; aOverlayHandles)</apiname></xref> method to get all mode-specific overlays in z-order from the ECam implementation server. </p> </li> <li id="GUID-41258620-81F5-51F0-9404-F78E1CD57257"><p>Implementation gives preference to the sequence in which the client has passed the overlay handles, if any mis-match occurs with the z-order of each such overlay. Implementation can improve the z-order of the overlays if required, to remove any ambiguity. </p> </li> <li id="GUID-2D28F459-3D76-5CD1-BB51-4D024D096874"><p>Use the overloaded <xref href="GUID-1D393214-187B-32F9-A36E-B98464F8395C.dita#GUID-1D393214-187B-32F9-A36E-B98464F8395C/GUID-B6DACCE3-212B-3967-82C0-26FE2930873E"><apiname>CCamera::CCameraOverlay::SetAllOverlaysInZOrderL(CCamera::CCameraOverlay::TOverlayCameraMode
                aOverlayCameraMode, TInt aViewFinderHandle, const RArray&lt;TUint&gt;&amp;
                aOverlayHandles)</apiname></xref> method to set all mode-specific overlays in z-order from the ECam implementation server. See <b>step 9</b> above. </p> </li> <li id="GUID-05B2747B-A467-5238-9F44-FE8A75F9247A"><p>Release the specific overlay from the ECam implementation server using <xref href="GUID-5CF1EE7D-EAED-39F7-AF9D-73DD813B64F9.dita#GUID-5CF1EE7D-EAED-39F7-AF9D-73DD813B64F9/GUID-CEA872C2-9ED7-378A-8112-1D0B9AE88B90"><apiname>CCamera::CCameraOverlay::ReleaseOverlay()</apiname></xref> method. </p> </li> </ol> <p>The following example code snippets illustrates the overlay implementation: </p> <codeblock id="GUID-E82A1C92-0CCC-509E-9679-5E87E713DDD0" xml:space="preserve">CFbsBitmap* bitmap = new (ELeave) CFbsBitmap;
CCamera::CCameraOverlay::TOverlayParameters parameters;
TUint ovrhandle =0; 
ovrhandle = ovrlay-&gt;CreateOverlayL(parameters, bitmap));
CFbsBitmap* getBitmap = new (ELeave) CFbsBitmap;
ovrlay-&gt;GetOverlayBitmapL(ovrhandle, getBitmap);

ovrlay-&gt;GetOverlayParametersL(ovrhandle, parameters);

//client changes the bitmap as desired.
ovrlay-&gt;SetOverlayBitmapL(ovrhandle, bitmap);


CFbsBitmap* modifiedBitmap = new (ELeave) CFbsBitmap; 
ovrlay-&gt;SetModifiableOverlayBitmapL(ovrhandle,modifiedBitmap);   

ovrlay-&gt;ReleaseOverlay(ovrhandle);

RArray&lt;TUint&gt; overlayHandles;
ovrlay-&gt;GetAllOverlaysInZOrderL(CCamera::CCameraOverlay::EModeStillImage,1,overlayHandles);
ovrlay-&gt;SetAllOverlaysInZOrderL(overlayHandles);</codeblock> </section> <section><title>Miscellaneous</title> <p><b>Overlay camera modes</b> </p> <p>You can specify the possible camera modes in which the overlay could be used using enum <xref href="GUID-4B373317-D44C-3831-B173-F566E2EEDDE1.dita"><apiname>TOverlayCameraMode</apiname></xref> in the following way: </p> <table id="GUID-FA244DD9-977E-5882-95EF-928BECD602CB"><tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/><tbody><row><entry><p> <b>Enum</b>  </p> </entry> <entry><p> <b> Enum Value</b>  </p> </entry> <entry><p> <b> Description</b>  </p> </entry> </row> <row><entry><p>EModeStillImageSingleShot </p> </entry> <entry><p>0x0001 </p> </entry> <entry><p>The image is to be overlaid when single shot Still Image driving mode is active. </p> </entry> </row> <row><entry><p>EModeStillImageContinuous </p> </entry> <entry><p>0x0020 </p> </entry> <entry><p>The image is to be overlaid when Continuous Still Image driving mode is active. </p> </entry> </row> <row><entry><p>EModeStillImageBracket </p> </entry> <entry><p>0x0040 </p> </entry> <entry><p>The image is to be overlaid when Still Image Bracketing driving mode is active. </p> </entry> </row> <row><entry><p>EModeStillImageBracketMerge </p> </entry> <entry><p>0x0080 </p> </entry> <entry><p>The image is to be overlaid when Still Image Bracketing with Merge option driving mode is active. </p> </entry> </row> <row><entry><p>EModeStillImageTimed </p> </entry> <entry><p>0x0100 </p> </entry> <entry><p>The image is to be overlaid when Timed Still Image driving mode is active. </p> </entry> </row> <row><entry><p>EModeStillImageTimeLapse </p> </entry> <entry><p>0x0200 </p> </entry> <entry><p>The image is to be overlaid when Timed Still Image with Lapse option driving mode is active. </p> </entry> </row> <row><entry><p>EModeStillImageBurst </p> </entry> <entry><p>0x0400 </p> </entry> <entry><p>The image is to be overlaid when Still Image Burst driving mode is active. </p> </entry> </row> </tbody> </tgroup> </table> </section> <section><title>See also</title> <p><xref href="GUID-AB5BD17E-F482-54A1-AE6F-4AEC178B2E0E.dita">Overview</xref> of the overlay functionality </p> <p>The <xref href="GUID-10E19876-85CA-5D45-854B-1F2C5A45A333.dita">Overlay</xref> tutorial </p> </section> </conbody></concept>