<?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-6DC34798-86CE-537D-B3B8-9A94FF77B283"><title>Image Encoding</title><prolog><metadata><keywords/></metadata></prolog><conbody><p>This document gives you more information about the Image Encoding functionality. </p> <section><title>Purpose</title> <p>The image encoding class CImageEncoder provides functions to save the following to files or descriptors: </p> <ul><li id="GUID-E0BCDD5B-933C-5B02-A2E3-775F95226E98"><p>Images originating from the screen. </p> </li> <li id="GUID-61C02273-687B-5BF7-BF34-7BB90273DD0D"><p>Applications such as browsers and paint programs </p> </li> <li id="GUID-2499D229-BAE4-50DA-A2B3-9E6DDED375F5"><p>Photos from cameras or viewer applications </p> </li> </ul> <p><b>Required Background</b> </p> <p>Image Encoding features are provided through Imaging Frameworks and Imaging plugins. The standard formats supported by the encoder plugins are shown in the table in <xref href="GUID-88091838-03FC-550F-9A3D-DA70907EF955.dita">Imaging Frameworks Overview</xref>. </p> <p><b>Introduction</b> </p> <p>The encoding process has been broken down into two stage process: </p> <ul><li id="GUID-74A226F0-F67C-56D3-BF10-9B9BA4729B58"><p>Creation </p> </li> <li id="GUID-E80A69E3-D077-5C6D-82CA-303F82718A01"><p>Conversion </p> </li> </ul> <p><b>Setup and Configuration Requirements</b> </p> <p>The <xref href="GUID-737DA130-9A66-39E2-9E68-2E65F37E02C8.dita"><apiname>CImageEncoder</apiname></xref> classes use synchronous methods to open an image and asynchronous methods to perform conversions or transformations. The asynchronous operations use the standard system of taking a pointer to a <xref href="GUID-E0B34F3E-D4C4-3232-B8B1-7DB35B454646.dita"><apiname>TRequestStatus</apiname></xref> object that is signalled on completion of the requested action. The assumption is that the client application or the calling DLL holds the <codeph>TRequestStatus</codeph> values within active objects. The structure of the active objects is dependent on the code that uses Imaging Frameworks and its own requirements, particularly its internal architecture and how many images are opened simultaneously. </p> <p>In addition to the use of active objects in the interfacing, many of Imaging Frameworks internal functions make extensive use of them to provide asynchronous behaviour. As with any use of an active object it is necessary to have an active scheduler in the same thread as the application making use of the object. The encoder can also be created, so the plugin and framework runs in a separate thread. This is achieved by setting the <codeph>EOptionAlwaysThread</codeph> option when constructing the encoder objects. By running the object in its own thread, the application is shielded from any latency that can occur during image conversion, or possibly due to a badly written plugin. </p> <p> <b> Note:</b> The encoder plugin formats do not support multiframe images or bitmap masks (transparent images). </p> </section> <section><title>Using Image Encoding </title> <p>The Following tasks are covered in this tutorial: </p> <ul><li id="GUID-D520A78B-63C6-57CD-BB28-40E7D88EE837"><p><xref href="GUID-6DC34798-86CE-537D-B3B8-9A94FF77B283.dita#GUID-6DC34798-86CE-537D-B3B8-9A94FF77B283/GUID-DFE3CD4C-2787-5DEC-A0AC-871CEBD22B11">How to create the object during encoding</xref> </p> </li> <li id="GUID-FE370FAC-ECB1-529F-B951-8FAAFCD60938"><p><xref href="GUID-6DC34798-86CE-537D-B3B8-9A94FF77B283.dita#GUID-6DC34798-86CE-537D-B3B8-9A94FF77B283/GUID-3CA67D41-A9F2-5D83-A0BC-61E1FDA4AA30">How to convert decoded data to encoded data</xref>  </p> </li> </ul> <p id="GUID-DFE3CD4C-2787-5DEC-A0AC-871CEBD22B11"><b>Basic Procedure For Creation</b> </p> <p>The high level steps to create the object during encoding are as follows: </p> <ol id="GUID-8FA73392-60BE-5D71-AB1B-B8C30EE95B1E"><li id="GUID-8B0FFDEE-614D-5BE8-BCD0-D208AB330FC2"><p>The creation of the encoder object is a synchronous operation performed using one of the following factory constructors: </p> <codeblock id="GUID-8E19493C-A0A1-511A-AD02-96796F464120" xml:space="preserve">static CImageEncoder* FileNewL(RFs&amp; aFs, const TDesC&amp; aDestinationFilename, const TDesC8&amp; aMIMEType, const TOptions aOptions = EOptionNone);

static CImageEncoder* FileNewL(RFs& aFs, const TDesC& aDestinationFilename, const TOptions aOptions = EOptionNone, const TUid aImageType = KNullUid, const TUid aImageSubType = KNullUid, const TUid aEncoderUid = KNullUid);

static CImageEncoder* DataNewL(HBufC8*& aDestinationData, const TDesC8& aMIMEType, const TOptions aOptions = EOptionNone);

static CImageEncoder* DataNewL(HBufC8*& aDestinationData, const TOptions aOptions = EOptionNone, const TUid aImageType = KNullUid, const TUid aImageSubType = KNullUid, const TUid aEncoderUid = KNullUid);

</codeblock> </li> <li id="GUID-10936CCA-61DE-5983-9C4C-1E4143F8F74F"><p>The <codeph>FileNewL()</codeph> constructors are used to convert image data saved to a file. The two variants of the function enable you to set the imaging plugin to use either by specifying a MIME type, or by specifying an image type and sub-type and optional encoder UID. </p> </li> <li id="GUID-36BF55A5-A2CB-5C5D-BC3D-4269A019FCA7"><p>The <codeph>DataNewL()</codeph> constructors are used to convert image data saved to a buffer. Rather than specifying the destination buffer itself, the <codeph>DataNewL</codeph> functions require a <codeph>HBufC8*</codeph> value that must be set to zero. On successful completion of the conversion the <codeph>HBufC8*</codeph> contains a pointer to an internally generated buffer that contains the converted image data. </p> </li> <li id="GUID-E1B15CF8-1342-5FCA-B74B-A78850BDDDA5"><p>The two variants of the <codeph>DataNewL()</codeph> constructors enable you to specify the imaging plugin to use either by specifying a MIME type, an image type and sub-type, or by specifying the plugin ID itself. </p> </li> </ol> <p id="GUID-3CA67D41-A9F2-5D83-A0BC-61E1FDA4AA30"><b>Basic Procedure For Conversion</b> </p> <p>The high level steps to convert decoded data to Encoded data are as follows: </p> <ol id="GUID-62B573C4-6279-5A32-9017-F038F0B940CD"><li id="GUID-A3DD37B7-04D8-5FED-ACC0-5DB963102D02"><p>Before converting the image data, the destination image format specific data can be set by using <xref href="GUID-27B63129-ABD9-3B6C-882B-6F4501AF8E15.dita"><apiname>CFrameImageData</apiname></xref>. However, the type of data that can be supplied is dependant on the Imaging plugin that is being used. </p> </li> <li id="GUID-4CA47591-EA85-5A6F-95C0-8C46CB727DB3"><p>The format specific data are <xref href="GUID-9F5FFC62-2A6C-307A-8E34-1D9DE874A133.dita"><apiname>TImageDataBlock</apiname></xref> and <xref href="GUID-7E326426-8AE4-3792-8B80-19D2A4B839F3.dita"><apiname>TFrameDataBlock</apiname></xref> derivatives provided by the Imaging plugin. These can be appended to <xref href="GUID-27B63129-ABD9-3B6C-882B-6F4501AF8E15.dita"><apiname>CFrameImageData</apiname></xref> using <xref href="GUID-4CF303A2-1622-3511-8F69-B9F80E298E54.dita"><apiname>AppendImageData()</apiname></xref> and <xref href="GUID-6C6FE0CC-88C5-3C5D-AD4C-1722845AA6DD.dita"><apiname>AppendFrameData()</apiname></xref> at which point <codeph>CFrameImageData</codeph> takes ownership of the data. </p> </li> </ol> <p><b>Example </b> </p> <codeblock id="GUID-3C1D41A3-BDE1-5F8D-81AA-35B56E19BBF4" xml:space="preserve">TJpegImageData imageData = new (ELeave) TJpegImageData;

// Set some format specific data

imageData->iSampleScheme = TJpegImageData::EColor444;

imageData->iQualityFactor = 95;

iFrameImageData = CFrameImageData::NewL();

// frameData - ownership passed to iFrameImageData after AppendImageData

User::LeaveIfError(iFrameImageData->AppendImageData(imageData));

// Do the convert

iEncoder->Convert(iRequesStatus,iFrameBitmap,iFrameImageData);

</codeblock> </section> </conbody><related-links><link href="GUID-88091838-03FC-550F-9A3D-DA70907EF955.dita"><linktext>Imaging Frameworks overview</linktext> </link> <link href="GUID-3D9C4B45-EEA0-581C-A9E5-8B2535014930.dita"><linktext>Image Conversion Overview</linktext> </link> <link href="GUID-B10B048F-37FF-53E7-92B9-83F8C197566A.dita"><linktext>Image Decoding Tutorial</linktext> </link> <link href="GUID-A825B62E-B5F6-5FDD-B267-E47103D57FD8.dita"><linktext> Guide to Symbian supplied Codecs </linktext> </link> </related-links></concept>