Image Encoding

Purpose

The image encoding class CImageEncoder provides functions to save the following to files or descriptors:

• Images originating from the screen.

• Applications such as browsers and paint programs

• Photos from cameras or viewer applications

Required Background

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 Imaging Frameworks Overview.

Introduction

The encoding process has been broken down into two stage process:

• Creation

• Conversion

Setup and Configuration Requirements

The CImageEncoder 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 TRequestStatus object that is signalled on completion of the requested action. The assumption is that the client application or the calling DLL holds the TRequestStatus 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.

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 EOptionAlwaysThread 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.

Note: The encoder plugin formats do not support multiframe images or bitmap masks (transparent images).

Using Image Encoding

The Following tasks are covered in this tutorial:

• How to create the object during encoding

• How to convert decoded data to encoded data

Basic Procedure For Creation

The high level steps to create the object during encoding are as follows:

1. The creation of the encoder object is a synchronous operation performed using one of the following factory constructors:

   static CImageEncoder* FileNewL(RFs& aFs, const TDesC& aDestinationFilename, const TDesC8& 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);
   

2. The FileNewL() 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.

3. The DataNewL() constructors are used to convert image data saved to a buffer. Rather than specifying the destination buffer itself, the DataNewL functions require a HBufC8* value that must be set to zero. On successful completion of the conversion the HBufC8* contains a pointer to an internally generated buffer that contains the converted image data.

4. The two variants of the DataNewL() 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.

Basic Procedure For Conversion

The high level steps to convert decoded data to Encoded data are as follows:

1. Before converting the image data, the destination image format specific data can be set by using CFrameImageData. However, the type of data that can be supplied is dependant on the Imaging plugin that is being used.

2. The format specific data are TImageDataBlock and TFrameDataBlock derivatives provided by the Imaging plugin. These can be appended to CFrameImageData using AppendImageData() and AppendFrameData() at which point CFrameImageData takes ownership of the data.

Example

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);