Symbian
Symbian OS Library

SYMBIAN OS V9.3

[Index] [Spacer] [Previous] [Next]



Location: ImageConversion.h
Link against: imageconversion.lib

Class CImageEncoder

class CImageEncoder : public CBase;

Description

Provides access to the ICL (image conversion library) encoders.

This class provides functions that convert image data held in CFbsBitmap objects into well know formats and store the results in either files of descriptors.

Derivation

Members

Defined in CImageEncoder:
CImageEncoder(), Cancel(), Convert(), CustomAsync(), CustomSyncL(), DataNewL(), DataNewL(), EOptionAlwaysThread, EOptionGenerateAdaptivePalette, EOptionNone, FileNewL(), FileNewL(), FileNewL(), FileNewL(), GetFileTypesL(), GetImageSubTypesL(), GetImageTypesL(), ImplementationUid(), Plugin(), SetEncoderThreadPriority(), SetThumbnail(), TOptions, ~CImageEncoder()

Inherited from CBase:
Delete(), Extension_(), operator new()


Construction and destruction


~CImageEncoder()

virtual IMPORT_C ~CImageEncoder();

Description

Destructor for this class.

Closes the file. If using a local file session, it closes it. Calls ECom to tell it the encoder instance is no longer required.

Frees all other resources owned by the object prior to its destruction.


CImageEncoder()

protected: IMPORT_C CImageEncoder();

Description

Constructor for this class.

[Top]


Member functions


GetImageTypesL()

static IMPORT_C void GetImageTypesL(RImageTypeDescriptionArray &aImageTypeArray);

Description

Returns a list of the basic image types that can be encoded, based on the currently available encoder plugins.

The returned array contains entries for the supported image types. Each entry consists of the "display string" as well as the UID for that image type. Since this function only returns basic image type UID's, the second UID which represents the sub-type will always be zero.

Ownership of the array is passed to the caller so, before the array goes out of scope in the client, the caller must call the array's ResetAndDestroy() method to free any entries.

Parameters

RImageTypeDescriptionArray &aImageTypeArray

An empty array, into which this function will put a list of supported image types.


GetImageSubTypesL()

static IMPORT_C void GetImageSubTypesL(const TUid aImageType, RImageTypeDescriptionArray &aSubTypeArray);

Description

For a given basic image type, returns a list of the image sub-types that can be encoded, based on the currently available encoder plugins.

Each entry in the returned array consists of the "display string" for the plugin as well as the UID for the sub-type. The first UID represents the basic type and is always set to aImageType.

Ownership of the array is passed to the caller, so before the array goes out of scope in the client, the caller must call the array's ResetAndDestroy() method to free any entries.

Parameters

const TUid aImageType

The basic image type for which a list of sub-types should be returned.

RImageTypeDescriptionArray &aSubTypeArray

An empty array, into which this function will put a list of of supported image sub-types.


GetFileTypesL()

static IMPORT_C void GetFileTypesL(RFileExtensionMIMETypeArray &aFileExtensionArray);

Description

Get a list of the file extensions that can be encoded and their corresponding MIME types, based on the currently available encoder plugins.

Ownership of the array is passed to the caller, so before the array goes out of scope in the client, the caller must call the array's ResetAndDestroy() method to free any entries.

Parameters

RFileExtensionMIMETypeArray &aFileExtensionArray

An empty array, into which this function will put a list of entries. Each entry will consist of a file extension string for which an encoder plugin has been found, accompanied by the primary MIME type and then any secondary MIME types (if present).


FileNewL()

static IMPORT_C CImageEncoder *FileNewL(RFs &aFs, const TDesC &aDestinationFilename, const TDesC8 &aMIMEType, const TOptions aOptions=EOptionNone);

Description

Creates an encoder based on a specified MIME type and write output to a named file.

The client supplies a MIME type which will be used to try and select an appropriate plugin encoder. If an appropriate encoder is found, it is created.

If any file related errors are encountered opening the specified file, this function leaves with an appropriate file related leave code.

Parameters

RFs &aFs

A reference to a file server session for the encoder to use.

const TDesC &aDestinationFilename

The name of the file into which to put the encoded image.

const TDesC8 &aMIMEType

The MIME type to use for the encoding.

const TOptions aOptions

The encoder options to use.

Return value

CImageEncoder *

Returns a pointer to the newly created encoder.

See also:


FileNewL()

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

Description

Creates an encoder based on a supplied parameters and writes output to a named file.

The client must supply a basic image type (and a sub-type, if applicable) or a specific encoder implementation UID, which will be used to try and select an appropriate plugin encoder. If an appropriate encoder is found, it is created.

Note: Every image format has two IDs, known as the type and the sub-type (although generally the sub-type is KNullUid). To retrieve a list of supported types and sub-types that can be encoded, use the static functions GetImageTypesL() and GetImageSubTypesL().

If no plugin encoder can be found that matches the details provided in aImageType, aImageSubType and possibly aEncoderUid this function leaves with KErrNotFound or KEComErrNoInterfaceIdentified.

If any file related errors are encountered opening the specified file, this function leaves with an appropriate file related leave code.

Parameters

RFs &aFs

A reference to a file server session for the encoder to use.

const TDesC &aDestinationFilename

The name of the file into which to put the encoded image.

const TOptions aOptions

Options to use.

const TUid aImageType

The image type to use for the encoding (mandatory).

const TUid aImageSubType

The image sub-type to use for the encoding (only if applicable, defaults to KNullUid).

const TUid aEncoderUid

The implementation UID for a specific codec or a decoder/encoder class UID (optional, defaults to KNullUid). If this option is selected for a specific codec the image type and image sub type for the displayer must be supplied. When loading plugins by class UID the image type and image subtype are not mandatory and the first valid plugin from the list of available plugins with the specified class UID will be loaded.

Return value

CImageEncoder *

A pointer to the newly created encoder.

Leave codes

KErrNotFound

No appropriate plugin encoder for this image has been found.

KEComErrNoInterfaceIdentified

ECom could not find the specified interface.

Panic codes

EIllegalImageType

No base type given for encoder implementation.

EIllegalImageSubType

No base type given for sub-type.

See also:


FileNewL()

static IMPORT_C CImageEncoder *FileNewL(RFile &aFile, const TDesC8 &aMIMEType, const TOptions aOptions=EOptionNone);

Description

Creates an encoder based on a specified MIME type and write output to a named file.

The client supplies a MIME type which will be used to try and select an appropriate plugin encoder. If an appropriate encoder is found, it is created.

If any file related errors are encountered opening the specified file, this function leaves with an appropriate file related leave code.

Parameters

RFile &aFile

The handle of an open file to write the encoded image to

const TDesC8 &aMIMEType

The MIME type to use for the encoding.

const TOptions aOptions

The encoder options to use.

Return value

CImageEncoder *

Returns a pointer to the newly created encoder.

Leave codes

KEComErrNoInterfaceIdentified

ECom could not find the specified interface.

KErrNotFound

No appropriate plugin encoder for this image has been found.

See also:


FileNewL()

static IMPORT_C CImageEncoder *FileNewL(RFile &aFile, const TOptions aOptions=EOptionNone, const TUid aImageType=TUid::Null(), const TUid aImageSubType=TUid::Null(), const TUid aEncoderUid=TUid::Null());

Description

Creates an encoder based on a supplied parameters and writes output to a named file.

The client must supply a basic image type (and a sub-type, if applicable) or a specific encoder/class implementation UID, which will be used to try and select an appropriate plugin encoder. If an appropriate encoder is found, it is created.

Note: Every image format has two IDs, known as the type and the sub-type (although generally the sub-type is KNullUid). To retrieve a list of supported types and sub-types that can be encoded, use the static functions GetImageTypesL() and GetImageSubTypesL().

If no plugin encoder can be found that matches the details provided in aImageType, aImageSubType and possibly aEncoderUid this function leaves with KErrNotFound or KEComErrNoInterfaceIdentified.

If any file related errors are encountered opening the specified file, this function leaves with an appropriate file related leave code.

Parameters

RFile &aFile

The handle of an open file to write the encoded image to

const TOptions aOptions

Options to use.

const TUid aImageType

The image type to use for the encoding (mandatory).

const TUid aImageSubType

The image sub-type to use for the encoding (only if applicable, defaults to KNullUid).

const TUid aEncoderUid

The implementation UID for a specific codec or a decoder/encoder class UID (optional, defaults to KNullUid). If this option is selected for a specific codec the image type and image sub type for the displayer must be supplied. When loading plugins by class UID the image type and image subtype are not mandatory and the first valid plugin from the list of available plugins with the specified class UID will be loaded.

Return value

CImageEncoder *

A pointer to the newly created encoder.

Leave codes

KErrNotFound

No appropriate plugin encoder for this image has been found.

KEComErrNoInterfaceIdentified

ECom could not find the specified interface.

Panic codes

EIllegalImageType

No base type given for encoder implementation.

EIllegalImageSubType

No base type given for sub-type.

See also:


DataNewL()

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

Description

Creates a plugin encoder for a specified MIME type and writes output to a descriptor.

The client supplies a MIME type which will be used to try and select an appropriate plugin encoder. If an appropriate encoder is found, it creates it.

Parameters

HBufC8 *&aDestinationData

The buffer pointer into which to put the encoded image. This must be a NULL pointer. Memory will be allocated internally and ownership of the data passed to the caller.

const TDesC8 &aMIMEType

The MIME type to use for the encoding.

const TOptions aOptions

Encoder options to use.

Return value

CImageEncoder *

A pointer to the newly created encoder.

See also:


DataNewL()

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

Description

Creates a plugin encoder based on optional parameters and writes output to a descriptor.

The client must supply a basic image type (and a sub-type, if applicable) or specific encoder/class, implementation UID which will be used to try and select an appropriate plugin encoder. If an appropriate encoder is found, it is created.

Note: Every image format has two IDs, known as the type and the sub-type (although generally the sub-type is KNullUid). To retrieve a list of supported types and sub-types that can be encoded, use the static functions GetImageTypesL() and GetImageSubTypesL().

If no plugin encoder can be found that matches the details provided in aImageType, aImageSubType and possibly aEncoderUid this function leaves with KErrNotFound or KEComErrNoInterfaceIdentified.

Parameters

HBufC8 *&aDestinationData

The buffer pointer into which to put the encoded image.

const TOptions aOptions

The encoder options to use.

const TUid aImageType

The image type to use for the encoding (mandatory).

const TUid aImageSubType

The image sub-type to use for the encoding (only if applicable, defaults to KNullUid).

const TUid aEncoderUid

The implementation UID for a specific codec or a decoder/encoder class UID (optional, defaults to KNullUid). If this option is selected for a specific codec the image type and image sub type for the displayer must be supplied. When loading plugins by class UID the image type and image subtype are not mandatory and the first valid plugin from the list of available plugins with the specified class UID will be loaded.

Return value

CImageEncoder *

A pointer to the newly created encoder.

Leave codes

KErrNotFound

No appropriate plugin encoder for this image has been found.

KEComErrNoInterfaceIdentified

ECom could not find the specified interface.

Panic codes

EIllegalImageSubType

No base type given for sub-type.

EIllegalImageType

No base type given for encoder implementation.

See also:


Convert()

IMPORT_C void Convert(TRequestStatus *aRequestStatus, const CFbsBitmap &aSource, const CFrameImageData *aFrameImageData=0);

Description

Encodes a bitmap asynchronously.

When encoding is complete, successfully or otherwise, the status is returned in aRequestStatus.

There exists format-specific image data variants that are used by encoders to obtain image specific data. This behaviour is invoked by specifying aFrameImageData. Otherwise, encoder specific defaults are invoked.

Parameters

TRequestStatus *aRequestStatus

The request status. On completion contains an error code. KErrNone if the bitmap was successfully encoded, otherwise another of the system-wide error codes.

const CFbsBitmap &aSource

A bitmap to encode.

const CFrameImageData *aFrameImageData

The frame image data (optional, defaults to NULL).

See also:


Cancel()

IMPORT_C void Cancel();

Description

Asynchronously cancels any conversions currently in progress.


ImplementationUid()

IMPORT_C TUid ImplementationUid() const;

Description

Returns the implementation UID of the encoder being used to encode the bitmap.

Return value

TUid

The implementation UID of the encoder.


SetThumbnail()

IMPORT_C void SetThumbnail(TBool aDoGenerateThumbnail);

Description

Select to encode or not the thumbnail

Parameters

TBool aDoGenerateThumbnail

EFalse if no generation of thumbnail


SetEncoderThreadPriority()

IMPORT_C TInt SetEncoderThreadPriority(TThreadPriority aPriority);

Description

Set the encoder worker thread priority

Parameters

TThreadPriority aPriority

a new value for worker thread priority

Return value

TInt

KErrNotSupported the encoder object doesn't use a worker thread. Other system-wide error codes.

See also:


CustomSyncL()

protected: IMPORT_C void CustomSyncL(TInt aParam);

Description

Calls CImageEncoderPlugin::HandleCustomSyncL() that executes user defined plugin specific functions. Subsequent behaviour therefore depends on the CImageEncoderPlugin class.

Note: For use by plugin writers only.

Parameters

TInt aParam

Interpretation determined by plugin.


CustomAsync()

protected: IMPORT_C void CustomAsync(TRequestStatus *aRequestStatus, TInt aParam);

Description

Sets up background convert cycle, bypassing Convert().

Use this function to inititate CImageEncoderPlugin::InitCustomAsyncL(aParam), which if successful will start background processing. Convert() uses the same mechanism as CustomAsync(), and therefore cannot be used concurrently. Cancel() and other related functions still work as expected.

Note: For use by plugin writers only.

Parameters

TRequestStatus *aRequestStatus

The request status. On completion contains an error code. KErrNone if the bitmap was successfully encoded, otherwise another of the system-wide error codes.

TInt aParam

Interpretation determined by plugin.


Plugin()

protected: IMPORT_C CImageEncoderPlugin *Plugin() const;

Description

Returns the associated CImageEncoderPlugin.

This is part of support for extended codecs, for use within classes derived from CImageEncoder. Allows the extended CImageEncoder object to talk to its CImageEncoderPlugin equivalent.

Note: For use by plugin writers only.

Return value

CImageEncoderPlugin *

[Top]


Member enumerations


Enum TOptions

TOptions

Description

Flags to control how the image is encoded. These can be combined using an OR operation.

EOptionNone

No flag set

EOptionAlwaysThread

Perform the encoding in a separate thread

EOptionGenerateAdaptivePalette

If the codec supports it, generate a palette based on the colors present in the image data, rather than using the default palette