12 <concept xml:lang="en" id="GUID-B10B048F-37FF-53E7-92B9-83F8C197566A"><title>Image Decoding</title><prolog><metadata><keywords/></metadata></prolog><conbody><p>This document gives you more information about the Image Decoding functionality. </p> <section><title>Purpose</title> <p>The image decoding class <xref href="GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4.dita"><apiname>CImageDecoder</apiname></xref> provides functions to decode images held in descriptors or files from standard formats for use with devices such as screens, browsers and viewer applications. </p> <p><b>Required Background</b> </p> <p>Image decoding features are provided through Imaging Frameworks and Imaging plugins. The standard formats supported by the decode 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 decoding process comprises the following sections: </p> <ul><li id="GUID-BE3B993F-3793-55B4-9ADB-9456FE73CA19"><p> <b>Creation</b> - The creation of the <xref href="GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4.dita"><apiname>CImageDecoder</apiname></xref> object and any requirements necessary. </p> </li> <li id="GUID-D5FE22F6-687F-560D-A336-4F01B5945273"><p> <b>Conversion</b> - Covers the basic form of image decoding. More advanced features such as progressive and buffered decoding are described separately. </p> </li> <li id="GUID-9A4AD0DE-AFCF-5F33-AAC7-007FD9F8A291"><p> <b>Enquiry features</b> - Additional features that enable you to retrieve information stored in certain types of images, for example frame information and comments. </p> </li> <li id="GUID-643CE012-6C73-5068-A7AD-FDA810FBBFD8"><p> <b>Streamed and progressive decoding</b> - Reading partial image files and displaying image data before the entire image is read. </p> </li> <li id="GUID-E3D6BB50-DBE9-5967-9FAC-B56BCBCCADAC"><p> <b>Buffered decoding</b> - The decoding of an image using a buffered input rather than a file or descriptor. </p> </li> </ul> <p><b>Setup and Configuration Requirements</b> </p> <p>The <xref href="GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4.dita"><apiname>CImageDecoder</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 the 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 the 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 Decoders 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 decoder 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> </section> <section><title>Using Image Decoding </title> <p>The Following tasks are covered in this tutorial: </p> <ul><li id="GUID-085EEC3C-C78B-5FDC-B630-C3A28DF0CA1F"><p><xref href="GUID-B10B048F-37FF-53E7-92B9-83F8C197566A.dita#GUID-B10B048F-37FF-53E7-92B9-83F8C197566A/GUID-1F8A0DCC-CB95-5245-9ED0-FE4A775152D0">How to create the object during decoding</xref> </p> </li> <li id="GUID-A5E71C36-E811-509B-A547-04F174B7000B"><p><xref href="GUID-B10B048F-37FF-53E7-92B9-83F8C197566A.dita#GUID-B10B048F-37FF-53E7-92B9-83F8C197566A/GUID-7A3F98C2-C86B-5DC4-9F0E-EAE030341325">How to convert encoded data to decoded data</xref>  </p> </li> <li id="GUID-D6EDE32F-F011-5191-AD15-AD8FAEFC5C75"><p><xref href="GUID-B10B048F-37FF-53E7-92B9-83F8C197566A.dita#GUID-B10B048F-37FF-53E7-92B9-83F8C197566A/GUID-FF418A2D-436B-515F-B9D1-E0A0C87E7394"> How to retrieve the information stored in certain types of images</xref>  </p> </li> <li id="GUID-05966714-BB75-5DB1-86E5-4FE075507C2D"><p><xref href="GUID-B10B048F-37FF-53E7-92B9-83F8C197566A.dita#GUID-B10B048F-37FF-53E7-92B9-83F8C197566A/GUID-AA950124-42DE-5A65-B371-7D85F43D71A6">How to perform the streaming and the progressive during decoding</xref>  </p> </li> <li id="GUID-3BBA8FBB-FB2E-5774-921E-8BBAC95DF55C"><p><xref href="GUID-B10B048F-37FF-53E7-92B9-83F8C197566A.dita#GUID-B10B048F-37FF-53E7-92B9-83F8C197566A/GUID-C7FEA8F9-B367-52B1-9D26-84F9E225D17C">How to perform the buffered decoding</xref>  </p> </li> </ul> <p id="GUID-1F8A0DCC-CB95-5245-9ED0-FE4A775152D0"><b>Basic Procedure For Creation</b> </p> <p>The high level steps to create the object during decoding are as follows: </p> <ol id="GUID-A8F73379-5277-5ACC-82A4-9199BE24142A"><li id="GUID-166216C0-5CAA-5FF4-8B40-BB562EEF3C61"><p> <xref href="GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4.dita"><apiname>CImageDecoder</apiname></xref> decodes images stored in files or in descriptors. The decoder object is owned by the client and must be deleted once decoding is finished. <codeph>CImageDecoder</codeph> objects cannot be reused to decode other images, each image requires its own instance of the decoder. </p> </li> <li id="GUID-BB617D39-8A46-5C7F-A28B-7C334F24594C"><p> <codeph>CImageDecoder</codeph> objects are created using the <xref href="GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4.dita#GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4/GUID-00FB83E8-3759-32BE-B6E8-6F04EC60A909"><apiname>CImageDecoder::DataNewL()</apiname></xref> and <xref href="GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4.dita#GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4/GUID-6DA07559-7DDC-32A9-9E09-D557348D46DE"><apiname>CImageDecoder::FileNewL()</apiname></xref> factory functions for images held in descriptors or files respectively. </p> </li> <li id="GUID-F1D28859-A28F-56EA-8755-25C8FF70BB50"><p>When you create a <xref href="GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4.dita"><apiname>CImageDecoder</apiname></xref> object, a suitable plugin must be associated with the image to be decoded. The Imaging plugin depends on the factory function you use to create the object and what parameters you specify. There are four alternatives: </p> <ul><li id="GUID-A40501AD-3679-5612-AA43-06DB6345C79D"><p> <b>MIME type</b> The plugin is determined by looking up a specified MIME type against a list of known MIME type/plugin implementations. Use the following "File" factory function (or its "Data" equivalent). </p> <codeblock id="GUID-FF20429E-3D1D-5D99-9548-9AA701AC1B32" xml:space="preserve">static CImageDecoder* FileNewL(RFs&amp; aFs, const TDesC&amp; aSourceFilename, const TDesC8&amp; aMIMEType, const TOptions aOptions = EOptionNone);

    12 <concept id="GUID-B10B048F-37FF-53E7-92B9-83F8C197566A" xml:lang="en"><title>Image

    13 </codeblock> </li> <li id="GUID-9D96F47A-F784-5252-AAC9-3DDEF2E96764"><p> <b>Image type and sub-type</b> The plugin is determined by looking up the specified image type and sub-types against a list of known type/sub-type plugin implementations. Use the following "File" factory function (or its "Data" equivalent). </p> <codeblock id="GUID-2D5A7779-CBE9-5B3E-B9E7-C5CD7631DB33" xml:space="preserve">static CImageDecoder* FileNewL(RFs&amp; aFs, const TDesC&amp; aSourceFilename, const TOptions aOptions = EOptionNone, const TUid aImageType = KNullUid, const TUid aImageSubType = KNullUid, const TUid aDecoderUid = KNullUid);

    13 Decoding</title><prolog><metadata><keywords/></metadata></prolog><conbody>

    14 </codeblock> <p> <b>Note:</b> For images types that do not have sub-types use <codeph>KNullUid</codeph>. </p> </li> <li id="GUID-D80A799E-E49E-547C-9286-1AB38F8EB819"><p> <b>Implementation UID</b> The plugin is determined by looking up its specific UID and the image type and sub-type. Use the same <codeph>FileNewL()</codeph> factory function shown in "Image type and sub-type", but in addition to the type and sub-type parameters, also specify the plugin UID using <codeph>aDecoderUid</codeph>. </p> <p> <b>Note:</b> Implementation UID is supported because it is possible to have more than one plugin for a particular image type. This method is recommended if the application or calling DLL needs to exploit features of a particular plugin. </p> </li> <li id="GUID-A08944FA-6BE6-574A-AE00-5F12F5A07F0B"><p> <b>Automatic detection</b> - no MIME type, format type/sub-type or UIDs are specified. The plugin analyses the header information of the specified image. Use the same <codeph>FileNewL()</codeph> factory function shown in "Image type and sub-type", but do not specify any values for <codeph>aImageType</codeph>  <codeph>aImageSubType</codeph> or <codeph>aDecoderUid</codeph>. </p> <p>If a suitable plugin cannot be found, the factory function leaves with <codeph>KErrNotFound</codeph>. If a suitable plugin is found, but that plugin cannot interpret the image data the factory function leaves with <codeph>KErrCorrupt</codeph>. </p> <p>Note: Some image formats cannot be automatically detected because they do not contain sufficient header information, for example, WBMP and OTA images. Under such circumstances, use one of the other three alternative for opening the image. </p> </li> </ul> </li> </ol> <p>It is possible for more than one valid plugin decoder to be available for a specific image format. If a plugin determined by MIME type or type/sub-type fails to open an image due to <codeph>KErrCorrupt</codeph>, it will continue to try with subsequent valid plugins if available. This mechanism is carried out in the system and is not visible to the application. If you require a specific function available within a specific plugin, specify that plugin using <codeph>aDecoderUid</codeph>. </p> <p id="GUID-7A3F98C2-C86B-5DC4-9F0E-EAE030341325"><b>Basic Procedure For Conversion </b> </p> <p>The high level steps to convert encoded data to decoded data are as follow: </p> <ol id="GUID-495365EB-B53D-5229-AD45-F9700A22F2AB"><li id="GUID-4B6AEB44-3426-5B83-A12E-755230627D23"><p>As part of the <codeph>CImageDecoder</codeph> creation basic information about the image is pre-read from the image headers. This information is used to support certain enquiry methods such as <xref href="GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4.dita#GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4/GUID-6506DA99-55E9-3524-BD64-528E145915F4"><apiname>CImageDecoder::FrameCount()</apiname></xref> and <xref href="GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4.dita#GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4/GUID-7CE85F05-6D58-30F1-87D3-324BFB6131FB"><apiname>CImageDecoder::FrameInfo()</apiname></xref> (For more information about the retrieve information stored in certain types of images is supplied in <xref href="GUID-B10B048F-37FF-53E7-92B9-83F8C197566A.dita#GUID-B10B048F-37FF-53E7-92B9-83F8C197566A/GUID-FF418A2D-436B-515F-B9D1-E0A0C87E7394">Retrieve Information features</xref>). </p> </li> <li id="GUID-18D5494C-BECC-52A5-9C51-60A9E560C816"><p>You can decode any subset of individual frames, in any order, and to repeat the decoding if necessary. To decode an image frame use the asynchronous conversion method <xref href="GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4.dita#GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4/GUID-8118AC37-471E-3CB6-9F71-4E93507DDE57"><apiname>CImageDecoder::Convert()</apiname></xref>, as follows. </p> </li> </ol> <codeblock id="GUID-557B2DE9-6AA7-593B-A1A7-0D1E4352E184" xml:space="preserve">

    14 <p>This document gives you more information about the Image Decoding functionality. </p>

    15 <section id="GUID-41872C2C-A6EB-446B-AA79-62BAA6B69437"><title>Purpose</title> <p>The image decoding class <xref href="GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4.dita"><apiname>CImageDecoder</apiname></xref> provides

    16 functions to decode images held in descriptors or files from standard formats

    17 for use with devices such as screens, browsers and viewer applications. </p> <p><b>Required Background</b> </p> <p>Image decoding features are provided through

    18 Imaging Frameworks and Imaging plugins. The standard formats supported by

    19 the decode plugins are shown in the table in <xref href="GUID-88091838-03FC-550F-9A3D-DA70907EF955.dita">Imaging

    20 Frameworks Overview</xref>. </p> <p><b>Introduction</b> </p> <p>The decoding process comprises the following sections: </p> <ul>

    21 <li id="GUID-BE3B993F-3793-55B4-9ADB-9456FE73CA19"><p> <b>Creation</b> - The

    22 creation of the <xref href="GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4.dita"><apiname>CImageDecoder</apiname></xref> object and any requirements

    23 necessary. </p> </li>

    24 <li id="GUID-D5FE22F6-687F-560D-A336-4F01B5945273"><p> <b>Conversion</b> -

    25 Covers the basic form of image decoding. More advanced features such as progressive

    26 and buffered decoding are described separately. </p> </li>

    27 <li id="GUID-9A4AD0DE-AFCF-5F33-AAC7-007FD9F8A291"><p> <b>Enquiry features</b> -

    28 Additional features that enable you to retrieve information stored in certain

    29 types of images, for example frame information and comments. </p> </li>

    30 <li id="GUID-643CE012-6C73-5068-A7AD-FDA810FBBFD8"><p> <b>Streamed and progressive

    31 decoding</b> - Reading partial image files and displaying image data before

    32 the entire image is read. </p> </li>

    33 <li id="GUID-E3D6BB50-DBE9-5967-9FAC-B56BCBCCADAC"><p> <b>Buffered decoding</b> -

    34 The decoding of an image using a buffered input rather than a file or descriptor. </p> </li>

    35 </ul> <p><b>Setup

    36 and Configuration Requirements</b> </p> <p>The <xref href="GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4.dita"><apiname>CImageDecoder</apiname></xref> classes

    37 use synchronous methods to open an image and asynchronous methods to perform

    38 conversions or transformations. The asynchronous operations use the standard

    39 system of taking a pointer to a <xref href="GUID-E0B34F3E-D4C4-3232-B8B1-7DB35B454646.dita"><apiname>TRequestStatus</apiname></xref> object that

    40 is signalled on completion of the requested action. The assumption is that

    41 the client application or the calling DLL holds the <codeph>TRequestStatus</codeph> values

    42 within active objects. The structure of the active objects is dependent on

    43 the code that uses the Imaging Frameworks and its own requirements, particularly

    44 its internal architecture and how many images are opened simultaneously. </p> <p>In

    45 addition to the use of active objects in the interfacing, many of the Imaging

    46 Frameworks internal functions make extensive use of them to provide asynchronous

    47 behaviour. As with any use of an active object it is necessary to have an

    48 active scheduler in the same thread as the application making use of the object.

    49 The Decoders can also be created so the plugin and framework runs in a separate

    50 thread. This is achieved by setting the <codeph>EOptionAlwaysThread</codeph> option

    51 when constructing the decoder objects. By running the object in its own thread,

    52 the application is shielded from any latency that can occur during image conversion,

    53 or possibly due to a badly written plugin. </p> </section>

    54 <section id="GUID-6741516A-A0A7-4021-9A5A-6855E4AE9E8B"><title>Using Image Decoding </title> <p>The Following tasks are covered

    55 in this tutorial: </p> <ul>

    56 <li id="GUID-085EEC3C-C78B-5FDC-B630-C3A28DF0CA1F"><p><xref href="GUID-B10B048F-37FF-53E7-92B9-83F8C197566A.dita#GUID-B10B048F-37FF-53E7-92B9-83F8C197566A/GUID-1F8A0DCC-CB95-5245-9ED0-FE4A775152D0">How to create the object during decoding</xref> </p> </li>

    57 <li id="GUID-A5E71C36-E811-509B-A547-04F174B7000B"><p><xref href="GUID-B10B048F-37FF-53E7-92B9-83F8C197566A.dita#GUID-B10B048F-37FF-53E7-92B9-83F8C197566A/GUID-7A3F98C2-C86B-5DC4-9F0E-EAE030341325">How to convert encoded data to decoded data</xref>  </p> </li>

    58 <li id="GUID-D6EDE32F-F011-5191-AD15-AD8FAEFC5C75"><p><xref href="GUID-B10B048F-37FF-53E7-92B9-83F8C197566A.dita#GUID-B10B048F-37FF-53E7-92B9-83F8C197566A/GUID-FF418A2D-436B-515F-B9D1-E0A0C87E7394"> How to retrieve the information stored in certain types of images</xref>  </p> </li>

    59 <li id="GUID-05966714-BB75-5DB1-86E5-4FE075507C2D"><p><xref href="GUID-B10B048F-37FF-53E7-92B9-83F8C197566A.dita#GUID-B10B048F-37FF-53E7-92B9-83F8C197566A/GUID-AA950124-42DE-5A65-B371-7D85F43D71A6">How to perform the streaming and the progressive during decoding</xref>  </p> </li>

    60 <li id="GUID-3BBA8FBB-FB2E-5774-921E-8BBAC95DF55C"><p><xref href="GUID-B10B048F-37FF-53E7-92B9-83F8C197566A.dita#GUID-B10B048F-37FF-53E7-92B9-83F8C197566A/GUID-C7FEA8F9-B367-52B1-9D26-84F9E225D17C">How to perform the buffered decoding</xref>  </p> </li>

    61 </ul> <p id="GUID-1F8A0DCC-CB95-5245-9ED0-FE4A775152D0"><b>Basic Procedure For Creation</b> </p> <p>The

    62 high level steps to create the object during decoding are as follows: </p> <ol id="GUID-A8F73379-5277-5ACC-82A4-9199BE24142A">

    63 <li id="GUID-166216C0-5CAA-5FF4-8B40-BB562EEF3C61"><p> <xref href="GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4.dita"><apiname>CImageDecoder</apiname></xref> decodes

    64 images stored in files or in descriptors. The decoder object is owned by the

    65 client and must be deleted once decoding is finished. <codeph>CImageDecoder</codeph> objects

    66 cannot be reused to decode other images, each image requires its own instance

    67 of the decoder. </p> </li>

    68 <li id="GUID-BB617D39-8A46-5C7F-A28B-7C334F24594C"><p> <codeph>CImageDecoder</codeph> objects

    69 are created using the <xref href="GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4.dita#GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4/GUID-00FB83E8-3759-32BE-B6E8-6F04EC60A909"><apiname>CImageDecoder::DataNewL()</apiname></xref> and <xref href="GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4.dita#GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4/GUID-6DA07559-7DDC-32A9-9E09-D557348D46DE"><apiname>CImageDecoder::FileNewL()</apiname></xref> factory

    70 functions for images held in descriptors or files respectively. </p> </li>

    71 <li id="GUID-F1D28859-A28F-56EA-8755-25C8FF70BB50"><p>When you create a <xref href="GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4.dita"><apiname>CImageDecoder</apiname></xref> object,

    72 a suitable plugin must be associated with the image to be decoded. The Imaging

    73 plugin depends on the factory function you use to create the object and what

    74 parameters you specify. There are four alternatives: </p> <ul>

    75 <li id="GUID-A40501AD-3679-5612-AA43-06DB6345C79D"><p> <b>MIME type</b> The

    76 plugin is determined by looking up a specified MIME type against a list of

    77 known MIME type/plugin implementations. Use the following "File" factory function

    78 (or its "Data" equivalent). </p> <codeblock id="GUID-FF20429E-3D1D-5D99-9548-9AA701AC1B32" xml:space="preserve">static CImageDecoder* FileNewL(RFs&amp; aFs, const TDesC&amp; aSourceFilename, const TDesC8&amp; aMIMEType, const TOptions aOptions = EOptionNone);

    79 </codeblock> </li>

    80 <li id="GUID-9D96F47A-F784-5252-AAC9-3DDEF2E96764"><p> <b>Image type and sub-type</b> The

    81 plugin is determined by looking up the specified image type and sub-types

    82 against a list of known type/sub-type plugin implementations. Use the following

    83 "File" factory function (or its "Data" equivalent). </p> <codeblock id="GUID-2D5A7779-CBE9-5B3E-B9E7-C5CD7631DB33" xml:space="preserve">static CImageDecoder* FileNewL(RFs&amp; aFs, const TDesC&amp; aSourceFilename, const TOptions aOptions = EOptionNone, const TUid aImageType = KNullUid, const TUid aImageSubType = KNullUid, const TUid aDecoderUid = KNullUid);

    84 </codeblock> <p> <b>Note:</b> For images types that do not have sub-types

    85 use <codeph>KNullUid</codeph>. </p> </li>

    86 <li id="GUID-D80A799E-E49E-547C-9286-1AB38F8EB819"><p> <b>Implementation UID</b> The

    87 plugin is determined by looking up its specific UID and the image type and

    88 sub-type. Use the same <codeph>FileNewL()</codeph> factory function shown

    89 in "Image type and sub-type", but in addition to the type and sub-type parameters,

    90 also specify the plugin UID using <codeph>aDecoderUid</codeph>. </p> <p> <b>Note:</b> Implementation

    91 UID is supported because it is possible to have more than one plugin for a

    92 particular image type. This method is recommended if the application or calling

    93 DLL needs to exploit features of a particular plugin. </p> </li>

    94 <li id="GUID-A08944FA-6BE6-574A-AE00-5F12F5A07F0B"><p> <b>Automatic detection</b> -

    95 no MIME type, format type/sub-type or UIDs are specified. The plugin analyses

    96 the header information of the specified image. Use the same <codeph>FileNewL()</codeph> factory

    97 function shown in "Image type and sub-type", but do not specify any values

    98 for <codeph>aImageType</codeph>  <codeph>aImageSubType</codeph> or <codeph>aDecoderUid</codeph>. </p> <p>If

    99 a suitable plugin cannot be found, the factory function leaves with <codeph>KErrNotFound</codeph>.

   100 If a suitable plugin is found, but that plugin cannot interpret the image

   101 data the factory function leaves with <codeph>KErrCorrupt</codeph>. </p> <p>Note:

   102 Some image formats cannot be automatically detected because they do not contain

   103 sufficient header information, for example, WBMP and OTA images. Under such

   104 circumstances, use one of the other three alternative for opening the image. </p> </li>

   105 </ul> </li>

   106 </ol> <p>It is possible for more than one valid plugin decoder to be available

   107 for a specific image format. If a plugin determined by MIME type or type/sub-type

   108 fails to open an image due to <codeph>KErrCorrupt</codeph>, it will continue

   109 to try with subsequent valid plugins if available. This mechanism is carried

   110 out in the system and is not visible to the application. If you require a

   111 specific function available within a specific plugin, specify that plugin

   112 using <codeph>aDecoderUid</codeph>. </p> <p id="GUID-7A3F98C2-C86B-5DC4-9F0E-EAE030341325"><b>Basic Procedure For Conversion </b> </p> <p>The

   113 high level steps to convert encoded data to decoded data are as follow: </p> <ol id="GUID-495365EB-B53D-5229-AD45-F9700A22F2AB">

   114 <li id="GUID-4B6AEB44-3426-5B83-A12E-755230627D23"><p>As part of the <codeph>CImageDecoder</codeph> creation

   115 basic information about the image is pre-read from the image headers. This

   116 information is used to support certain enquiry methods such as <xref href="GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4.dita#GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4/GUID-6506DA99-55E9-3524-BD64-528E145915F4"><apiname>CImageDecoder::FrameCount()</apiname></xref> and <xref href="GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4.dita#GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4/GUID-7CE85F05-6D58-30F1-87D3-324BFB6131FB"><apiname>CImageDecoder::FrameInfo()</apiname></xref> (For more information about the retrieve information stored in certain types

   117 of images is supplied in <xref href="GUID-B10B048F-37FF-53E7-92B9-83F8C197566A.dita#GUID-B10B048F-37FF-53E7-92B9-83F8C197566A/GUID-FF418A2D-436B-515F-B9D1-E0A0C87E7394">Retrieve

   118 Information features</xref>). </p> </li>

   119 <li id="GUID-18D5494C-BECC-52A5-9C51-60A9E560C816"><p>You can decode any subset

   120 of individual frames, in any order, and to repeat the decoding if necessary.

   121 To decode an image frame use the asynchronous conversion method <xref href="GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4.dita#GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4/GUID-8118AC37-471E-3CB6-9F71-4E93507DDE57"><apiname>CImageDecoder::Convert()</apiname></xref>,

   122 as follows. </p> </li>

   123 </ol> <codeblock id="GUID-557B2DE9-6AA7-593B-A1A7-0D1E4352E184" xml:space="preserve">

    17 void ContinueConvert(TRequestStatus* aRequestStatus);</codeblock> <p> <b> Note:</b> The use of <xref href="GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4.dita#GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4/GUID-F4F5A5F6-03E5-3801-93CC-A023363F35F8"><apiname>CImageDecoder::ContinueConvert()</apiname></xref> is described in <xref href="GUID-B10B048F-37FF-53E7-92B9-83F8C197566A.dita#GUID-B10B048F-37FF-53E7-92B9-83F8C197566A/GUID-AA950124-42DE-5A65-B371-7D85F43D71A6">Streamed and progressive decoding</xref>. </p> <p>There are different type of sub-procedures which have to be followed before decode conversion, they are: </p> <ul><li id="GUID-1F27341A-4A6A-5269-AA61-CBB0FB620258"><p><xref href="GUID-B10B048F-37FF-53E7-92B9-83F8C197566A.dita#GUID-B10B048F-37FF-53E7-92B9-83F8C197566A/GUID-52CAB4D2-BFA9-528C-ADB6-88515893F2B1">Bitmap Masks conversion</xref>  </p> </li> <li id="GUID-3537322C-B7E7-502D-A773-294DEC45A6DC"><p><xref href="GUID-B10B048F-37FF-53E7-92B9-83F8C197566A.dita#GUID-B10B048F-37FF-53E7-92B9-83F8C197566A/GUID-03A3E6BD-8702-5C0D-8265-F956EC03CD73">Scaling and display modes</xref>  </p> </li> <li id="GUID-D11765E3-CD93-5CF2-A530-B7725F742861"><p><xref href="GUID-B10B048F-37FF-53E7-92B9-83F8C197566A.dita#GUID-B10B048F-37FF-53E7-92B9-83F8C197566A/GUID-9C2E0BFC-61FE-5F83-A78A-C9248C5D6FA3">Animations</xref>  </p> </li> <li id="GUID-EA7899D9-F950-514D-9696-072C14116B44"><p><xref href="GUID-B10B048F-37FF-53E7-92B9-83F8C197566A.dita#GUID-B10B048F-37FF-53E7-92B9-83F8C197566A/GUID-9BD9C48A-B582-5730-B03F-CF6CB00DF6D1">Background colours </xref>  </p> </li> </ul> <p id="GUID-52CAB4D2-BFA9-528C-ADB6-88515893F2B1"><b>Basic Procedure For Bitmap Masks conversion</b> </p> <p>The high level steps to Bitmap Masks conversion are as follows: </p> <ol id="GUID-A330923C-DA1E-55CF-A01C-151CD203D37B"><li id="GUID-E493B5B2-D8A2-5428-846B-0BA902EAF641"><p>There is a second variant of the <codeph>Convert()</codeph> function intended for use when decoding images with bitmap masks. </p> <codeblock id="GUID-F6213C82-A604-57F0-B4C2-5667007CAD53" xml:space="preserve">

   126 void ContinueConvert(TRequestStatus* aRequestStatus);</codeblock> <p> <b> Note:</b> The

   127 use of <xref href="GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4.dita#GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4/GUID-F4F5A5F6-03E5-3801-93CC-A023363F35F8"><apiname>CImageDecoder::ContinueConvert()</apiname></xref> is described in <xref href="GUID-B10B048F-37FF-53E7-92B9-83F8C197566A.dita#GUID-B10B048F-37FF-53E7-92B9-83F8C197566A/GUID-AA950124-42DE-5A65-B371-7D85F43D71A6">Streamed

   128 and progressive decoding</xref>. </p> <p>There are different type of sub-procedures

   129 which have to be followed before decode conversion, they are: </p> <ul>

   130 <li id="GUID-1F27341A-4A6A-5269-AA61-CBB0FB620258"><p><xref href="GUID-B10B048F-37FF-53E7-92B9-83F8C197566A.dita#GUID-B10B048F-37FF-53E7-92B9-83F8C197566A/GUID-52CAB4D2-BFA9-528C-ADB6-88515893F2B1">Bitmap Masks conversion</xref>  </p> </li>

   131 <li id="GUID-3537322C-B7E7-502D-A773-294DEC45A6DC"><p><xref href="GUID-B10B048F-37FF-53E7-92B9-83F8C197566A.dita#GUID-B10B048F-37FF-53E7-92B9-83F8C197566A/GUID-03A3E6BD-8702-5C0D-8265-F956EC03CD73">Scaling and display modes</xref>  </p> </li>

   132 <li id="GUID-D11765E3-CD93-5CF2-A530-B7725F742861"><p><xref href="GUID-B10B048F-37FF-53E7-92B9-83F8C197566A.dita#GUID-B10B048F-37FF-53E7-92B9-83F8C197566A/GUID-9C2E0BFC-61FE-5F83-A78A-C9248C5D6FA3">Animations</xref>  </p> </li>

   133 <li id="GUID-EA7899D9-F950-514D-9696-072C14116B44"><p><xref href="GUID-B10B048F-37FF-53E7-92B9-83F8C197566A.dita#GUID-B10B048F-37FF-53E7-92B9-83F8C197566A/GUID-9BD9C48A-B582-5730-B03F-CF6CB00DF6D1">Background colours </xref>  </p> </li>

   134 </ul> <p id="GUID-52CAB4D2-BFA9-528C-ADB6-88515893F2B1"><b>Basic Procedure For Bitmap

   135 Masks conversion</b> </p> <p>The high level steps to Bitmap Masks conversion

   136 are as follows: </p> <ol id="GUID-A330923C-DA1E-55CF-A01C-151CD203D37B">

   137 <li id="GUID-E493B5B2-D8A2-5428-846B-0BA902EAF641"><p>There is a second variant

   138 of the <codeph>Convert()</codeph> function intended for use when decoding

   139 images with bitmap masks. </p> <codeblock id="GUID-F6213C82-A604-57F0-B4C2-5667007CAD53" xml:space="preserve">

    19 </codeblock> </li> <li id="GUID-1E7DC04E-A101-5C33-B6B5-BE5F83E95801"><p>Within the Symbian platform it is normal to store the bitmap mask separately from the main image data. Calls such as <xref href="GUID-2395FA67-5DCD-3CD7-BBB6-66625A3E2B6E.dita"><apiname>BitBltMasked()</apiname></xref> expect this data to be provided separately. This separation is true for both <xref href="GUID-683A1D42-2764-3EB7-BD19-9E12559199AB.dita"><apiname>CFbsBitmap</apiname></xref> objects and MBM files. </p> </li> <li id="GUID-B9CE26DF-AE1C-592F-8C0E-DD0AAD69BF60"><p>To determine whether an image contains a bitmap mask use <codeph>FrameInfo()</codeph>, the presence or absence of a mask will be indicated the <codeph>ETransparencyPossible</codeph> flag. </p> <p>The following two types of mask are available: </p> <ul><li id="GUID-1A03053A-C797-57EF-978E-C25A1D32163A"><p> <b>8-bit alpha blend</b> - indicated by the <codeph>EAlphaChannel</codeph> flag of <xref href="GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4.dita#GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4/GUID-7CE85F05-6D58-30F1-87D3-324BFB6131FB"><apiname>CImageDecoder::FrameInfo()</apiname></xref>  <codeph>iFlags</codeph>. The destination mask bitmap must be of type <codeph>EGray256</codeph>. </p> </li> <li id="GUID-9B51A424-66ED-584F-A3CD-55D575B38FEA"><p> <b>Simple on/off mask</b> - if no <codeph>EAlphaChannel</codeph> flag is set. The destination bitmap mask can be either <codeph>EGray2</codeph> or <codeph>EGray256</codeph>. </p> </li> </ul> </li> </ol> <p> <b>Note:</b> Images that contain bitmap masks do not have to have those masks decoded if they are not required. </p> <p id="GUID-03A3E6BD-8702-5C0D-8265-F956EC03CD73"><b>Basic Procedure For Scaling and display modes</b> </p> <p>The high level steps to Scale and display are shown here: </p> <ol id="GUID-DE0D4041-CBBF-5841-BE53-A8F6EA2CDE38"><li id="GUID-921CCDF6-7346-577E-AEC2-217C82329D44"><p>Before <codeph>Convert()</codeph> is used, the destination <xref href="GUID-683A1D42-2764-3EB7-BD19-9E12559199AB.dita"><apiname>CFbsBitmap</apiname></xref> objects for image data and bitmap masks are created. The simplest way to do this is to use a 1 to 1 approach, that is, create the <codeph>CFbsBitmap</codeph> object with the same properties as the source image. This is achieved by using something similar to: </p> <codeblock id="GUID-198859CC-C33A-5BE8-B75C-C32746D65DF7" xml:space="preserve">iFrameInfo = &amp;imageDecoder-&gt;FrameInfo(FrameNum);

   141 </codeblock> </li>

   142 <li id="GUID-1E7DC04E-A101-5C33-B6B5-BE5F83E95801"><p>Within the Symbian platform

   143 it is normal to store the bitmap mask separately from the main image data.

   144 Calls such as <xref href="GUID-2395FA67-5DCD-3CD7-BBB6-66625A3E2B6E.dita"><apiname>BitBltMasked()</apiname></xref> expect this data to be provided

   145 separately. This separation is true for both <xref href="GUID-683A1D42-2764-3EB7-BD19-9E12559199AB.dita"><apiname>CFbsBitmap</apiname></xref> objects

   146 and MBM files. </p> </li>

   147 <li id="GUID-B9CE26DF-AE1C-592F-8C0E-DD0AAD69BF60"><p>To determine whether

   148 an image contains a bitmap mask use <codeph>FrameInfo()</codeph>, the presence

   149 or absence of a mask will be indicated the <codeph>ETransparencyPossible</codeph> flag. </p> <p>The

   150 following two types of mask are available: </p> <ul>

   151 <li id="GUID-1A03053A-C797-57EF-978E-C25A1D32163A"><p> <b>8-bit alpha blend</b> -

   152 indicated by the <codeph>EAlphaChannel</codeph> flag of <xref href="GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4.dita#GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4/GUID-7CE85F05-6D58-30F1-87D3-324BFB6131FB"><apiname>CImageDecoder::FrameInfo()</apiname></xref>  <codeph>iFlags</codeph>.

   153 The destination mask bitmap must be of type <codeph>EGray256</codeph>. </p> </li>

   154 <li id="GUID-9B51A424-66ED-584F-A3CD-55D575B38FEA"><p> <b>Simple on/off mask</b> -

   155 if no <codeph>EAlphaChannel</codeph> flag is set. The destination bitmap mask

   156 can be either <codeph>EGray2</codeph> or <codeph>EGray256</codeph>. </p> </li>

   157 </ul> </li>

   158 </ol> <p> <b>Note:</b> Images that contain bitmap masks do not have to have

   159 those masks decoded if they are not required. </p> <p id="GUID-03A3E6BD-8702-5C0D-8265-F956EC03CD73"><b>Basic Procedure For Scaling

   160 and display modes</b> </p> <p>The high level steps to Scale and display are

   161 shown here: </p> <ol id="GUID-DE0D4041-CBBF-5841-BE53-A8F6EA2CDE38">

   162 <li id="GUID-921CCDF6-7346-577E-AEC2-217C82329D44"><p>Before <codeph>Convert()</codeph> is

   163 used, the destination <xref href="GUID-683A1D42-2764-3EB7-BD19-9E12559199AB.dita"><apiname>CFbsBitmap</apiname></xref> objects for image data

   164 and bitmap masks are created. The simplest way to do this is to use a 1 to

   165 1 approach, that is, create the <codeph>CFbsBitmap</codeph> object with the

   166 same properties as the source image. This is achieved by using something similar

   167 to: </p> <codeblock id="GUID-198859CC-C33A-5BE8-B75C-C32746D65DF7" xml:space="preserve">iFrameInfo = &amp;imageDecoder-&gt;FrameInfo(FrameNum);

    22 </codeblock> </li> <li id="GUID-B3559310-560A-5671-9560-509F14B729ED"><p>If the <codeph>ECanDither</codeph> flag of <xref href="GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4.dita#GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4/GUID-7CE85F05-6D58-30F1-87D3-324BFB6131FB"><apiname>CImageDecoder::FrameInfo()</apiname></xref>  <codeph>iFlags</codeph> is set then the destination display mode can be adjusted. It is recommended that the window display mode is used as it is more efficient. </p> <p> <b>Note:</b> The mask bitmap must have the same size in pixels as the main image, even though the display mode is generally different. </p> </li> <li id="GUID-B517656C-3294-5D3A-92E3-442CAE099FE1"><p>The size of the image bitmap is available via <codeph>FrameInfo()</codeph> (<codeph>iOverallSizeInPixels</codeph>). However, in addition to a direct mapping of the size of an image, <xref href="GUID-062B8E74-EDEF-3A98-9728-79C3E5A8C829.dita"><apiname>ReducedSize()</apiname></xref> function can be used to calculate the reduced size of the decoded bitmap based on the input parameters. </p> </li> <li id="GUID-52299AC9-377C-5DEB-B16A-BDA0538D91A7"><p>If the <codeph>EFullyScaleable</codeph> flag of <codeph>FrameInfo()</codeph>  <codeph>iFlags</codeph> is set, you can specify any size for the <xref href="GUID-683A1D42-2764-3EB7-BD19-9E12559199AB.dita"><apiname>CFbsBitmap</apiname></xref> and the image will be resized accordingly. </p> </li> </ol> <p id="GUID-9C2E0BFC-61FE-5F83-A78A-C9248C5D6FA3"><b>Basic Procedure For Animations</b> </p> <p>The high level steps to decode a GIF multi-frame image are as follow: </p> <ol id="GUID-C7E99D55-48C9-5329-B07B-28A65AB102D6"><li id="GUID-53364690-F9D3-5A80-9FAA-2046F8DB80AB"><p>Included in the <xref href="GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4.dita#GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4/GUID-7CE85F05-6D58-30F1-87D3-324BFB6131FB"><apiname>CImageDecoder::FrameInfo()</apiname></xref> result are flags that enable the support of GIF animation. These flags are <codeph>iDelay</codeph>, <codeph>ELeaveInPlace</codeph>, <codeph>ERestoreToBackground</codeph> and <codeph>ERestoreToPrevious</codeph>. ICL provides these flags to enable the application to implement the animation; ICL does not provide functions to display the animation directly. </p> </li> <li id="GUID-3BAC1045-E210-5B1A-93E9-BB15C9FC1871"><p>Processing the information from these flags will inevitably require a state machine, and additional timers, within the application. Requirements will vary depending on the architecture of the client application itself. </p> </li> </ol> <p id="GUID-9BD9C48A-B582-5730-B03F-CF6CB00DF6D1"><b>Basic Procedure For Background colours</b> </p> <ol id="GUID-2D46054E-1344-5B17-B353-8A68A0C97DB0"><li id="GUID-41959955-766E-5AAD-AA6D-65C4F99E5581"><p>Some image formats contain background colour information. This is information is presented through <xref href="GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4.dita#GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4/GUID-7CE85F05-6D58-30F1-87D3-324BFB6131FB"><apiname>CImageDecoder::FrameInfo()</apiname></xref>  <codeph>iBackgroundColor</codeph>. </p> </li> <li id="GUID-B3419EC0-109F-5A37-9A4F-CD0F7A96FCDC"><p>If a non-masked image with background colour is decoded, the colour is included in the image data. If the decoded image also contains a bitmap mask, then the background colour will be a component of the mask <xref href="GUID-683A1D42-2764-3EB7-BD19-9E12559199AB.dita"><apiname>CFbsBitmap</apiname></xref> object. Depending on your application, you may want to choose your own background colour rather than use the one provided by the source image. </p> </li> </ol> <p id="GUID-FF418A2D-436B-515F-B9D1-E0A0C87E7394"><b>Basic Procedure To Retrieve Information From An Image</b> </p> <p>The high level steps to retrieve the information stored in certain types of images are shown here: </p> <ol id="GUID-2D40722B-5BEA-52ED-B143-A4E85CE8EB22"><li id="GUID-B40D32A1-CC43-50B8-A873-A6E14C27D165"><p> <xref href="GUID-5F0CD3F3-8833-3D31-A9B9-B832BAAA588B.dita#GUID-5F0CD3F3-8833-3D31-A9B9-B832BAAA588B/GUID-7BB6FC3D-2721-3902-B6BD-C99697C35D6D"><apiname>CImageDecode::FrameData()</apiname></xref> Provides access to additional chunks of data within the images, for example, palette and similar lookup tables, copyright information and other strings. This information should be used with care, the returned data is merely a reference to the original data within the <xref href="GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4.dita"><apiname>CImageDecoder</apiname></xref> object, and is only valid for the lifetime of the object. </p> </li> <li id="GUID-875B1CFA-CE86-50D7-BD8A-4E7453EEF35F"><p> <xref href="GUID-5F0CD3F3-8833-3D31-A9B9-B832BAAA588B.dita#GUID-5F0CD3F3-8833-3D31-A9B9-B832BAAA588B/GUID-08674EE0-C31A-3E42-A121-4341983A6B0C"><apiname>CImageDecode::NumberOfImageComments()</apiname></xref> and <xref href="GUID-5F0CD3F3-8833-3D31-A9B9-B832BAAA588B.dita#GUID-5F0CD3F3-8833-3D31-A9B9-B832BAAA588B/GUID-26AFE814-96FB-333F-B545-1E18B835206B"><apiname>CImageDecode::ImageCommentL()</apiname></xref> Images can have comments embedded in them. These comments are usually either embedded as a single repository which can be retrieved on an image level, or multiple repositories attached to individual frames within the image. The two functions above return the number of comments attached to the entire image and provide a mechanism for retrieving any of those comments. </p> </li> <li id="GUID-6854DEC9-4348-56DD-B5E2-47DEE3DC43AE"><p> <xref href="GUID-5F0CD3F3-8833-3D31-A9B9-B832BAAA588B.dita#GUID-5F0CD3F3-8833-3D31-A9B9-B832BAAA588B/GUID-AB2B99F5-49E5-37DD-80F1-3776CB9A0D1A"><apiname>CImageDecode::NumberOfFrameComments()</apiname></xref> and <xref href="GUID-5F0CD3F3-8833-3D31-A9B9-B832BAAA588B.dita#GUID-5F0CD3F3-8833-3D31-A9B9-B832BAAA588B/GUID-A12EAD36-D2F0-3CAA-A6CE-033ABE8DE258"><apiname>CImageDecode::FrameCommentL()</apiname></xref> Similar functionality to above, but these functions return the number of comments attached to individually specified frames and provide a mechanism for retrieving any of those comments. </p> </li> <li id="GUID-F51D81A1-61A7-5C1C-B0FB-99B18C1203DC"><p> <xref href="GUID-5F0CD3F3-8833-3D31-A9B9-B832BAAA588B.dita#GUID-5F0CD3F3-8833-3D31-A9B9-B832BAAA588B/GUID-BD657401-E04F-331E-B72E-3729CB35C919"><apiname>CImageDecode::FrameInfoStringsLC</apiname></xref> and <xref href="GUID-5F0CD3F3-8833-3D31-A9B9-B832BAAA588B.dita#GUID-5F0CD3F3-8833-3D31-A9B9-B832BAAA588B/GUID-E9107BE1-58BF-3C1A-BBFF-B7027C35331B"><apiname>CImageDecode::FrameInfoStringsL()</apiname></xref> Provide a list of data for a specified frame, including data items such as format, plugin description, size and so on, in a readable format. Although the property strings can be accessed by name, it is recommended that they be generally treated as a list of strings. </p> </li> </ol> <p id="GUID-AA950124-42DE-5A65-B371-7D85F43D71A6"><b>Basic Procedure Streamed and Progressive Decoding</b> </p> <p> <xref href="GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4.dita"><apiname>CImageDecoder</apiname></xref> includes facilities to support the simultaneous decoding and display of images as they are being loaded. The decoder does not wait for the entire image to be loaded before processing it, rather it begins as soon as possible, stops when it runs out of data and then carries on when more data is available. </p> <p>The high level steps to perform the streaming and the progressive during decoding are shown here: </p> <ol id="GUID-0E29E833-4435-5E55-908F-938A13473B79"><li id="GUID-CE64D3C8-8923-5BAF-AF29-9BA6470008F8"><p>If there is insufficient data to work out the image format (plugin decoder to use) <xref href="GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4.dita#GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4/GUID-6DA07559-7DDC-32A9-9E09-D557348D46DE"><apiname>CImageDecoder::FileNewL()</apiname></xref> (or its "Data" equivalent) leaves with <codeph>KErrUnderflow</codeph>. This is only applicable to instances where automatic detection of the plugin decoder is used. For more information see, "Automatic detection" in <xref href="GUID-B10B048F-37FF-53E7-92B9-83F8C197566A.dita#GUID-B10B048F-37FF-53E7-92B9-83F8C197566A/GUID-1F8A0DCC-CB95-5245-9ED0-FE4A775152D0">Creation</xref>. </p> </li> <li id="GUID-23175979-940A-507D-B478-0C4ACB5F9071"><p>As soon as the correct plugin decoder has been determined it is opened and whatever addition image data available is scanned. The plugin decoder continues to decode image data as it arrives, updating <codeph>FrameCount()</codeph> whenever it becomes aware of a new frame within the data. The internal flag <xref href="GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4.dita#GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4/GUID-26084926-42C1-38FC-9F30-E1801AE5167D"><apiname>CImageDecoder::IsHeaderProcessingComplete()</apiname></xref> is maintained at <codeph>EFalse</codeph> until the entire image has been loaded. </p> </li> <li id="GUID-75959B88-7CE2-598E-9F83-EC0189BD2F6C"><p>Frames can be decoded before the entire image is loaded, but the frame to be decoded must be at least partially loaded. If <codeph>IsHeaderProcessingComplete()</codeph> is set to <codeph>EFalse</codeph> and <codeph>FrameCount()</codeph> is equal to or less than the frame to decode, the application must wait for the relevant frame to load. In such circumstances a call to <xref href="GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4.dita#GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4/GUID-A74CEA6D-ED47-3EA4-8917-FEE4B51B7639"><apiname>CImageDecoder::ContinueProcessingHeadersL()</apiname></xref> should be made that scans for any further headers. <codeph>FrameCount()</codeph> and <codeph>IsHeaderProcessingComplete()</codeph> should then be recalled to determine if the frame has arrived. </p> </li> <li id="GUID-C390495B-840E-541B-A0C5-061D3706AD8A"><p>Once <codeph>FrameCount()</codeph> is greater than the frame the application wants to decode, it is possible to start to decoding the frame using <xref href="GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4.dita#GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4/GUID-8118AC37-471E-3CB6-9F71-4E93507DDE57"><apiname>CImageDecoder::Convert()</apiname></xref>. Frame headers and their associated data do not always follow each other in some image formats. This has the implication that although <codeph>FrameCount()</codeph> has indicated that the frame is available, it may not yet be fully loaded. Under such circumstances as much decoding as possible is undertaken, and <codeph>Convert()</codeph> then completes with the error code <codeph>KErrUnderflow</codeph>. If the <codeph>EPartialDecodeInvalid</codeph> flag (from <codeph>FrameInfo()</codeph>) is not set, the partially decoded image can be displayed - for some image formats, a partially decoded image is not generally usable, but this facility is supported by most known formats. Obviously, if all of the image is present, <codeph>Convert()</codeph> completes with <codeph>KErrNone</codeph> as normal. </p> </li> <li id="GUID-44864401-5DB5-56A5-BE6D-5B8B4570CCBF"><p>Where only a partial conversion has been completed, <xref href="GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4.dita#GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4/GUID-F4F5A5F6-03E5-3801-93CC-A023363F35F8"><apiname>CImageDecoder::ContinueConvert()</apiname></xref> should be used to continue converting when new data arrives. <codeph>ContinueConvert()</codeph> continues to convert the frame data where the previous call left off. This function should continue to be called until it returns the error code <codeph>KErrNone</codeph> rather than <codeph>KErrUnderflow</codeph>. </p> <p>Note: The <xref href="GUID-683A1D42-2764-3EB7-BD19-9E12559199AB.dita"><apiname>CFbsBitmap</apiname></xref> must never be resized during a conversion session using <codeph>ContinueConvert()</codeph>, if resizing does occur, a panic will be raised by the function. If resizing or any other parameter changes need to be made to the <codeph>CFbsBitmap</codeph>, frame decoding should be restarted by using <codeph>Convert()</codeph> rather than trying to continue an existing conversion session. </p> </li> </ol> <p>There is no explicit decoder call to say "all of the data is now present". This could be done via inference, continuously checking <codeph>IsHeaderProcessingComplete()</codeph> until it returns <codeph>ETrue</codeph>. However, this is not advisable as it is possible that <codeph>IsHeaderProcessingComplete()</codeph> could continue to return <codeph>EFalse</codeph> even after the application has finished sending image data. Your state machine should be written so that it takes this possibility into account. </p> <p id="GUID-C7FEA8F9-B367-52B1-9D26-84F9E225D17C"><b>Basic Procedure For Buffered Decoding</b> </p> <p> <xref href="GUID-DD2EDAB6-784C-3FC9-A53D-84D133049378.dita"><apiname>CBufferedImageDecoder</apiname></xref> is a wrapper that encapsulates not only a <xref href="GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4.dita"><apiname>CImageDecoder</apiname></xref> but also the descriptor used to store the image, and in some circumstances can replace the use of <codeph>CImageDecoder</codeph> itself. <xref href="GUID-DD2EDAB6-784C-3FC9-A53D-84D133049378.dita"><apiname>CBufferedImageDecoder</apiname></xref> can always be created, even if there is no data available at the time of creation. Another key feature of <codeph>CBufferedImageDecoder</codeph> is that it can be reused to decode multiple images. </p> <p>The high level steps to perform the buffered decoding are shown here: </p> <ol id="GUID-0EEA3303-59C3-5326-8E10-3C54BE69B336"><li id="GUID-8749D5E2-2E9D-578B-A02C-C4C1309E2AC5"><p>The decoder is created using the <xref href="GUID-DD2EDAB6-784C-3FC9-A53D-84D133049378.dita#GUID-DD2EDAB6-784C-3FC9-A53D-84D133049378/GUID-D255B2EF-1DA0-336E-A173-0FD03210B349"><apiname>CBufferedImageDecoder::NewL()</apiname></xref> factory function, and the decoding process is started with one of the two <xref href="GUID-DD2EDAB6-784C-3FC9-A53D-84D133049378.dita#GUID-DD2EDAB6-784C-3FC9-A53D-84D133049378/GUID-A8D36C2B-C057-3F6A-A1AF-F7421D204B11"><apiname>CBufferedImageDecoder::OpenL()</apiname></xref> calls, specifying either MIME-type or image type/sub-type and UID, which are similar to <xref href="GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4.dita#GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4/GUID-00FB83E8-3759-32BE-B6E8-6F04EC60A909"><apiname>CImageDecoder::DataNewL()</apiname></xref>. If not enough data is available to create an internal decoder a call to <xref href="GUID-DD2EDAB6-784C-3FC9-A53D-84D133049378.dita#GUID-DD2EDAB6-784C-3FC9-A53D-84D133049378/GUID-0C7E0E24-8352-353E-9E55-D216300D1CFA"><apiname>CBufferedImageDecoder::ValidDecoder()</apiname></xref> returns <codeph>EFalse</codeph>. The decoder keeps an internal copy of the data provided so the client can discard its own copy. </p> <p> <b>Warning:</b> The decoding and enquiry functions must not be used until an internal decoder has been created, otherwise calls will panic with <codeph>EDecoderNotCreated</codeph>. </p> </li> <li id="GUID-A1DD251D-D1B2-57EE-9A2D-94AE75DBA35B"><p>Additional data can be supplied to the decoder, when it becomes available, by using <xref href="GUID-DD2EDAB6-784C-3FC9-A53D-84D133049378.dita#GUID-DD2EDAB6-784C-3FC9-A53D-84D133049378/GUID-5CF4094C-A829-347A-835C-17ABF439445A"><apiname>CBufferedImageDecoder::AppendDataL()</apiname></xref> and <xref href="GUID-DD2EDAB6-784C-3FC9-A53D-84D133049378.dita#GUID-DD2EDAB6-784C-3FC9-A53D-84D133049378/GUID-B85FD15C-337A-393F-A9DA-65EC1EB546C5"><apiname>CBufferedImageDecoder::ContinueOpenL()</apiname></xref>, which will copy the data and try to find an appropriate plugin. This step should be repeated until enough data is available to create the internal decoder, indicated by <codeph>ValidDecoder()</codeph> returning <codeph>ETrue</codeph>. <codeph>OpenL()</codeph> and <codeph>ContinueOpenL()</codeph> will leave with <codeph>KErrCorrupt</codeph> if a suitable decoder is found, but that decoder was unable to interpret the supplied image data. </p> <p>Note: As with <codeph>OpenL()</codeph>, data provided by <codeph>AppendDataL()</codeph> is kept in an internal buffer by the decoder so the client can discard its own copy. </p> </li> <li id="GUID-E4E67E99-0D9A-5CA9-8FE3-6A32A36C3F42"><p>The process for decoding the image header and frames are the same as for <xref href="GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4.dita"><apiname>CImageDecoder</apiname></xref> with <codeph>IsHeaderProcessingComplete()</codeph>, <codeph>FrameCount()</codeph>, <codeph>Convert()</codeph> and <codeph>ContinueConvert()</codeph> calls except that the data is not appended to a descriptor, but supplied to the decoder with <codeph>AppendDataL()</codeph>. </p> </li> <li id="GUID-E40CF367-2601-5B9F-9E20-34CD8F2754EB"><p>The decoder can be reused by calling a <xref href="GUID-DD2EDAB6-784C-3FC9-A53D-84D133049378.dita#GUID-DD2EDAB6-784C-3FC9-A53D-84D133049378/GUID-44030283-5CB8-3317-8498-0B70C0C358A9"><apiname>CBufferedImageDecoder::Reset()</apiname></xref>, which destroys the internal data buffer and decoder. A new decoder plugin can then be started using <codeph>OpenL()</codeph>. </p> </li> </ol> </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-6DC34798-86CE-537D-B3B8-9A94FF77B283.dita"><linktext>Image Encoding Tutorial</linktext> </link> <link href="GUID-A825B62E-B5F6-5FDD-B267-E47103D57FD8.dita"><linktext>Guide to Symbian supplied Codecs </linktext> </link> </related-links></concept>

   170 </codeblock> </li>

   171 <li id="GUID-B3559310-560A-5671-9560-509F14B729ED"><p>If the <codeph>ECanDither</codeph> flag

   172 of <xref href="GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4.dita#GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4/GUID-7CE85F05-6D58-30F1-87D3-324BFB6131FB"><apiname>CImageDecoder::FrameInfo()</apiname></xref>  <codeph>iFlags</codeph> is

   173 set then the destination display mode can be adjusted. It is recommended that

   174 the window display mode is used as it is more efficient. </p> <p> <b>Note:</b> The

   175 mask bitmap must have the same size in pixels as the main image, even though

   176 the display mode is generally different. </p> </li>

   177 <li id="GUID-B517656C-3294-5D3A-92E3-442CAE099FE1"><p>The size of the image

   178 bitmap is available via <codeph>FrameInfo()</codeph> (<codeph>iOverallSizeInPixels</codeph>).

   179 However, in addition to a direct mapping of the size of an image, <xref href="GUID-062B8E74-EDEF-3A98-9728-79C3E5A8C829.dita"><apiname>ReducedSize()</apiname></xref> function

   180 can be used to calculate the reduced size of the decoded bitmap based on the

   181 input parameters. </p> </li>

   182 <li id="GUID-52299AC9-377C-5DEB-B16A-BDA0538D91A7"><p>If the <codeph>EFullyScaleable</codeph> flag

   183 of <codeph>FrameInfo()</codeph>  <codeph>iFlags</codeph> is set, you can specify

   184 any size for the <xref href="GUID-683A1D42-2764-3EB7-BD19-9E12559199AB.dita"><apiname>CFbsBitmap</apiname></xref> and the image will be resized

   185 accordingly. </p> </li>

   186 </ol> <p id="GUID-9C2E0BFC-61FE-5F83-A78A-C9248C5D6FA3"><b>Basic Procedure For Animations</b> </p> <p>The

   187 high level steps to decode a GIF multi-frame image are as follow: </p> <ol id="GUID-C7E99D55-48C9-5329-B07B-28A65AB102D6">

   188 <li id="GUID-53364690-F9D3-5A80-9FAA-2046F8DB80AB"><p>Included in the <xref href="GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4.dita#GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4/GUID-7CE85F05-6D58-30F1-87D3-324BFB6131FB"><apiname>CImageDecoder::FrameInfo()</apiname></xref> result

   189 are flags that enable the support of GIF animation. These flags are <codeph>iDelay</codeph>, <codeph>ELeaveInPlace</codeph>, <codeph>ERestoreToBackground</codeph> and <codeph>ERestoreToPrevious</codeph>. ICL provides these flags to enable

   190 the application to implement the animation; ICL does not provide functions

   191 to display the animation directly. </p> </li>

   192 <li id="GUID-3BAC1045-E210-5B1A-93E9-BB15C9FC1871"><p>Processing the information

   193 from these flags will inevitably require a state machine, and additional timers,

   194 within the application. Requirements will vary depending on the architecture

   195 of the client application itself. </p> </li>

   196 </ol> <p id="GUID-9BD9C48A-B582-5730-B03F-CF6CB00DF6D1"><b>Basic Procedure For Background

   197 colours</b> </p> <ol id="GUID-2D46054E-1344-5B17-B353-8A68A0C97DB0">

   198 <li id="GUID-41959955-766E-5AAD-AA6D-65C4F99E5581"><p>Some image formats contain

   199 background colour information. This is information is presented through <xref href="GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4.dita#GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4/GUID-7CE85F05-6D58-30F1-87D3-324BFB6131FB"><apiname>CImageDecoder::FrameInfo()</apiname></xref>  <codeph>iBackgroundColor</codeph>. </p> </li>

   200 <li id="GUID-B3419EC0-109F-5A37-9A4F-CD0F7A96FCDC"><p>If a non-masked image

   201 with background colour is decoded, the colour is included in the image data.

   202 If the decoded image also contains a bitmap mask, then the background colour

   203 will be a component of the mask <xref href="GUID-683A1D42-2764-3EB7-BD19-9E12559199AB.dita"><apiname>CFbsBitmap</apiname></xref> object. Depending

   204 on your application, you may want to choose your own background colour rather

   205 than use the one provided by the source image. </p> </li>

   206 </ol> <p id="GUID-FF418A2D-436B-515F-B9D1-E0A0C87E7394"><b>Basic Procedure To Retrieve

   207 Information From An Image</b> </p> <p>The high level steps to retrieve the

   208 information stored in certain types of images are shown here: </p> <ol id="GUID-2D40722B-5BEA-52ED-B143-A4E85CE8EB22">

   209 <li id="GUID-B40D32A1-CC43-50B8-A873-A6E14C27D165"><p> <xref href="GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4.dita#GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4/GUID-01F212DD-0A35-3702-948B-1CBFB6675456"><apiname>CImageDecoder::FrameData()</apiname></xref> Provides

   210 access to additional chunks of data within the images, for example, palette

   211 and similar lookup tables, copyright information and other strings. This information

   212 should be used with care, the returned data is merely a reference to the original

   213 data within the <xref href="GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4.dita"><apiname>CImageDecoder</apiname></xref> object, and is only valid

   214 for the lifetime of the object. </p> </li>

   215 <li id="GUID-875B1CFA-CE86-50D7-BD8A-4E7453EEF35F"><p> <xref href="GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4.dita#GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4/GUID-B237AB64-0A03-3356-AA51-FCFD59E1A513"><apiname>CImageDecoder::NumberOfImageComments()</apiname></xref> and <xref href="GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4.dita#GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4/GUID-F7CADA2E-4B76-3B23-B5CA-92CD652E9A97"><apiname>CImageDecoder::ImageCommentL()</apiname></xref> Images can have comments embedded in them. These comments are usually either

   216 embedded as a single repository which can be retrieved on an image level,

   217 or multiple repositories attached to individual frames within the image. The

   218 two functions above return the number of comments attached to the entire image

   219 and provide a mechanism for retrieving any of those comments. </p> </li>

   220 <li id="GUID-6854DEC9-4348-56DD-B5E2-47DEE3DC43AE"><p> <xref href="GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4.dita#GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4/GUID-3057B1A5-9F03-363B-9E84-9CFE2A2892EB"><apiname>CImageDecoder::NumberOfFrameComments()</apiname></xref> and <xref href="GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4.dita#GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4/GUID-28A8EF22-C0C8-32BB-B9F3-96588F63A321"><apiname>CImageDecoder::FrameCommentL()</apiname></xref> Similar functionality to above, but these functions return the number of

   221 comments attached to individually specified frames and provide a mechanism

   222 for retrieving any of those comments. </p> </li>

   223 <li id="GUID-F51D81A1-61A7-5C1C-B0FB-99B18C1203DC"><p> <xref href="GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4.dita#GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4/GUID-78BF07BC-5338-3A60-B8BF-47DAFE2CA82C"><apiname>CImageDecoder::FrameInfoStringsLC</apiname></xref> and <xref href="GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4.dita#GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4/GUID-7B3BDF3B-43BA-3206-AF62-174B7C3AF516"><apiname>CImageDecoder::FrameInfoStringsL()</apiname></xref> Provide a list of data for a specified frame, including data items such

   224 as format, plugin description, size and so on, in a readable format. Although

   225 the property strings can be accessed by name, it is recommended that they

   226 be generally treated as a list of strings. </p> </li>

   227 </ol> <p id="GUID-AA950124-42DE-5A65-B371-7D85F43D71A6"><b>Basic Procedure Streamed

   228 and Progressive Decoding</b> </p> <p> <xref href="GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4.dita"><apiname>CImageDecoder</apiname></xref> includes

   229 facilities to support the simultaneous decoding and display of images as they

   230 are being loaded. The decoder does not wait for the entire image to be loaded

   231 before processing it, rather it begins as soon as possible, stops when it

   232 runs out of data and then carries on when more data is available. </p> <p>The

   233 high level steps to perform the streaming and the progressive during decoding

   234 are shown here: </p> <ol id="GUID-0E29E833-4435-5E55-908F-938A13473B79">

   235 <li id="GUID-CE64D3C8-8923-5BAF-AF29-9BA6470008F8"><p>If there is insufficient

   236 data to work out the image format (plugin decoder to use) <xref href="GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4.dita#GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4/GUID-6DA07559-7DDC-32A9-9E09-D557348D46DE"><apiname>CImageDecoder::FileNewL()</apiname></xref> (or

   237 its "Data" equivalent) leaves with <codeph>KErrUnderflow</codeph>. This is

   238 only applicable to instances where automatic detection of the plugin decoder

   239 is used. For more information see, "Automatic detection" in <xref href="GUID-B10B048F-37FF-53E7-92B9-83F8C197566A.dita#GUID-B10B048F-37FF-53E7-92B9-83F8C197566A/GUID-1F8A0DCC-CB95-5245-9ED0-FE4A775152D0">Creation</xref>. </p> </li>

   240 <li id="GUID-23175979-940A-507D-B478-0C4ACB5F9071"><p>As soon as the correct

   241 plugin decoder has been determined it is opened and whatever addition image

   242 data available is scanned. The plugin decoder continues to decode image data

   243 as it arrives, updating <codeph>FrameCount()</codeph> whenever it becomes

   244 aware of a new frame within the data. The internal flag <xref href="GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4.dita#GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4/GUID-26084926-42C1-38FC-9F30-E1801AE5167D"><apiname>CImageDecoder::IsHeaderProcessingComplete()</apiname></xref> is

   245 maintained at <codeph>EFalse</codeph> until the entire image has been loaded. </p> </li>

   246 <li id="GUID-75959B88-7CE2-598E-9F83-EC0189BD2F6C"><p>Frames can be decoded

   247 before the entire image is loaded, but the frame to be decoded must be at

   248 least partially loaded. If <codeph>IsHeaderProcessingComplete()</codeph> is

   249 set to <codeph>EFalse</codeph> and <codeph>FrameCount()</codeph> is equal

   250 to or less than the frame to decode, the application must wait for the relevant

   251 frame to load. In such circumstances a call to <xref href="GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4.dita#GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4/GUID-A74CEA6D-ED47-3EA4-8917-FEE4B51B7639"><apiname>CImageDecoder::ContinueProcessingHeadersL()</apiname></xref> should

   252 be made that scans for any further headers. <codeph>FrameCount()</codeph> and <codeph>IsHeaderProcessingComplete()</codeph> should

   253 then be recalled to determine if the frame has arrived. </p> </li>

   254 <li id="GUID-C390495B-840E-541B-A0C5-061D3706AD8A"><p>Once <codeph>FrameCount()</codeph> is

   255 greater than the frame the application wants to decode, it is possible to

   256 start to decoding the frame using <xref href="GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4.dita#GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4/GUID-8118AC37-471E-3CB6-9F71-4E93507DDE57"><apiname>CImageDecoder::Convert()</apiname></xref>.

   257 Frame headers and their associated data do not always follow each other in

   258 some image formats. This has the implication that although <codeph>FrameCount()</codeph> has

   259 indicated that the frame is available, it may not yet be fully loaded. Under

   260 such circumstances as much decoding as possible is undertaken, and <codeph>Convert()</codeph> then

   261 completes with the error code <codeph>KErrUnderflow</codeph>. If the <codeph>EPartialDecodeInvalid</codeph> flag

   262 (from <codeph>FrameInfo()</codeph>) is not set, the partially decoded image

   263 can be displayed - for some image formats, a partially decoded image is not

   264 generally usable, but this facility is supported by most known formats. Obviously,

   265 if all of the image is present, <codeph>Convert()</codeph> completes with <codeph>KErrNone</codeph> as

   266 normal. </p> </li>

   267 <li id="GUID-44864401-5DB5-56A5-BE6D-5B8B4570CCBF"><p>Where only a partial

   268 conversion has been completed, <xref href="GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4.dita#GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4/GUID-F4F5A5F6-03E5-3801-93CC-A023363F35F8"><apiname>CImageDecoder::ContinueConvert()</apiname></xref> should

   269 be used to continue converting when new data arrives. <codeph>ContinueConvert()</codeph> continues

   270 to convert the frame data where the previous call left off. This function

   271 should continue to be called until it returns the error code <codeph>KErrNone</codeph> rather

   272 than <codeph>KErrUnderflow</codeph>. </p> <p>Note: The <xref href="GUID-683A1D42-2764-3EB7-BD19-9E12559199AB.dita"><apiname>CFbsBitmap</apiname></xref> must

   273 never be resized during a conversion session using <codeph>ContinueConvert()</codeph>,

   274 if resizing does occur, a panic will be raised by the function. If resizing

   275 or any other parameter changes need to be made to the <codeph>CFbsBitmap</codeph>,

   276 frame decoding should be restarted by using <codeph>Convert()</codeph> rather

   277 than trying to continue an existing conversion session. </p> </li>

   278 </ol> <p>There is no explicit decoder call to say "all of the data is now

   279 present". This could be done via inference, continuously checking <codeph>IsHeaderProcessingComplete()</codeph> until

   280 it returns <codeph>ETrue</codeph>. However, this is not advisable as it is

   281 possible that <codeph>IsHeaderProcessingComplete()</codeph> could continue

   282 to return <codeph>EFalse</codeph> even after the application has finished

   283 sending image data. Your state machine should be written so that it takes

   284 this possibility into account. </p> <p id="GUID-C7FEA8F9-B367-52B1-9D26-84F9E225D17C"><b>Basic Procedure For Buffered

   285 Decoding</b> </p> <p> <xref href="GUID-DD2EDAB6-784C-3FC9-A53D-84D133049378.dita"><apiname>CBufferedImageDecoder</apiname></xref> is a wrapper

   286 that encapsulates not only a <xref href="GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4.dita"><apiname>CImageDecoder</apiname></xref> but also the

   287 descriptor used to store the image, and in some circumstances can replace

   288 the use of <codeph>CImageDecoder</codeph> itself. <xref href="GUID-DD2EDAB6-784C-3FC9-A53D-84D133049378.dita"><apiname>CBufferedImageDecoder</apiname></xref> can

   289 always be created, even if there is no data available at the time of creation.

   290 Another key feature of <codeph>CBufferedImageDecoder</codeph> is that it can

   291 be reused to decode multiple images. </p> <p>The high level steps to perform

   292 the buffered decoding are shown here: </p> <ol id="GUID-0EEA3303-59C3-5326-8E10-3C54BE69B336">

   293 <li id="GUID-8749D5E2-2E9D-578B-A02C-C4C1309E2AC5"><p>The decoder is created

   294 using the <xref href="GUID-DD2EDAB6-784C-3FC9-A53D-84D133049378.dita#GUID-DD2EDAB6-784C-3FC9-A53D-84D133049378/GUID-D255B2EF-1DA0-336E-A173-0FD03210B349"><apiname>CBufferedImageDecoder::NewL()</apiname></xref> factory function,

   295 and the decoding process is started with one of the two <xref href="GUID-DD2EDAB6-784C-3FC9-A53D-84D133049378.dita#GUID-DD2EDAB6-784C-3FC9-A53D-84D133049378/GUID-A8D36C2B-C057-3F6A-A1AF-F7421D204B11"><apiname>CBufferedImageDecoder::OpenL()</apiname></xref> calls,

   296 specifying either MIME-type or image type/sub-type and UID, which are similar

   297 to <xref href="GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4.dita#GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4/GUID-00FB83E8-3759-32BE-B6E8-6F04EC60A909"><apiname>CImageDecoder::DataNewL()</apiname></xref>. If not enough data is available

   298 to create an internal decoder a call to <xref href="GUID-DD2EDAB6-784C-3FC9-A53D-84D133049378.dita#GUID-DD2EDAB6-784C-3FC9-A53D-84D133049378/GUID-0C7E0E24-8352-353E-9E55-D216300D1CFA"><apiname>CBufferedImageDecoder::ValidDecoder()</apiname></xref> returns <codeph>EFalse</codeph>.

   299 The decoder keeps an internal copy of the data provided so the client can

   300 discard its own copy. </p> <p> <b>Warning:</b> The decoding and enquiry functions

   301 must not be used until an internal decoder has been created, otherwise calls

   302 will panic with <codeph>EDecoderNotCreated</codeph>. </p> </li>

   303 <li id="GUID-A1DD251D-D1B2-57EE-9A2D-94AE75DBA35B"><p>Additional data can

   304 be supplied to the decoder, when it becomes available, by using <xref href="GUID-DD2EDAB6-784C-3FC9-A53D-84D133049378.dita#GUID-DD2EDAB6-784C-3FC9-A53D-84D133049378/GUID-5CF4094C-A829-347A-835C-17ABF439445A"><apiname>CBufferedImageDecoder::AppendDataL()</apiname></xref> and <xref href="GUID-DD2EDAB6-784C-3FC9-A53D-84D133049378.dita#GUID-DD2EDAB6-784C-3FC9-A53D-84D133049378/GUID-B85FD15C-337A-393F-A9DA-65EC1EB546C5"><apiname>CBufferedImageDecoder::ContinueOpenL()</apiname></xref>, which will copy the data and try to find an appropriate plugin. This step

   305 should be repeated until enough data is available to create the internal decoder,

   306 indicated by <codeph>ValidDecoder()</codeph> returning <codeph>ETrue</codeph>. <codeph>OpenL()</codeph> and <codeph>ContinueOpenL()</codeph> will

   307 leave with <codeph>KErrCorrupt</codeph> if a suitable decoder is found, but

   308 that decoder was unable to interpret the supplied image data. </p> <p>Note:

   309 As with <codeph>OpenL()</codeph>, data provided by <codeph>AppendDataL()</codeph> is

   310 kept in an internal buffer by the decoder so the client can discard its own

   311 copy. </p> </li>

   312 <li id="GUID-E4E67E99-0D9A-5CA9-8FE3-6A32A36C3F42"><p>The process for decoding

   313 the image header and frames are the same as for <xref href="GUID-8F2953B2-E64E-3D8B-B30B-B35B373368D4.dita"><apiname>CImageDecoder</apiname></xref> with <codeph>IsHeaderProcessingComplete()</codeph>, <codeph>FrameCount()</codeph>, <codeph>Convert()</codeph> and <codeph>ContinueConvert()</codeph> calls

   314 except that the data is not appended to a descriptor, but supplied to the

   315 decoder with <codeph>AppendDataL()</codeph>. </p> </li>

   316 <li id="GUID-E40CF367-2601-5B9F-9E20-34CD8F2754EB"><p>The decoder can be reused

   317 by calling a <xref href="GUID-DD2EDAB6-784C-3FC9-A53D-84D133049378.dita#GUID-DD2EDAB6-784C-3FC9-A53D-84D133049378/GUID-44030283-5CB8-3317-8498-0B70C0C358A9"><apiname>CBufferedImageDecoder::Reset()</apiname></xref>, which destroys

   318 the internal data buffer and decoder. A new decoder plugin can then be started

   319 using <codeph>OpenL()</codeph>. </p> </li>

   320 </ol> </section>

   321 </conbody><related-links>

   322 <link href="GUID-88091838-03FC-550F-9A3D-DA70907EF955.dita"><linktext>Imaging Frameworks

   323 overview</linktext></link>

   324 <link href="GUID-3D9C4B45-EEA0-581C-A9E5-8B2535014930.dita"><linktext>Image Conversion

   325 Overview</linktext></link>

   326 <link href="GUID-6DC34798-86CE-537D-B3B8-9A94FF77B283.dita"><linktext>Image Encoding

   327 Tutorial</linktext></link>

   328 <link href="GUID-A825B62E-B5F6-5FDD-B267-E47103D57FD8.dita"><linktext>Guide to

   329 Symbian supplied Codecs </linktext></link>

   330 </related-links></concept>