CImageEncoder Class Reference

#include <imageconversion.h>

Link against: imageconversion.lib

class CImageEncoder : public CBase

Inherits from

CImageEncoder
- CBase

Public Member Enumerations
enum	TOptions { EOptionNone, EOptionAlwaysThread, EOptionGenerateAdaptivePalette, EPreferFastEncode, ..., EOptionExtReserved3 }

Public Member Functions
virtual	~CImageEncoder()
IMPORT_C TImageConvStreamedEncode *	BlockStreamerL()
IMPORT_C void	Cancel()
IMPORT_C void	Convert(TRequestStatus , const CFbsBitmap &, const CFrameImageData )
IMPORT_C CImageEncoder *	DataNewL(HBufC8 *&, const TDesC8 &, const TOptions)
IMPORT_C CImageEncoder *	DataNewL(HBufC8 *&, const TOptions, const TUid, const TUid, const TUid)
IMPORT_C CImageEncoder *	FileNewL(RFs &, const TDesC &, const TDesC8 &, const TOptions)
IMPORT_C CImageEncoder *	FileNewL(RFs &, const TDesC &, const TOptions, const TUid, const TUid, const TUid)
IMPORT_C CImageEncoder *	FileNewL(RFile &, const TDesC8 &, const TOptions)
IMPORT_C CImageEncoder *	FileNewL(RFile &, const TOptions, const TUid, const TUid, const TUid)
IMPORT_C void	GetFileTypesL(RFileExtensionMIMETypeArray &)
IMPORT_C void	GetImageSubTypesL(const TUid, RImageTypeDescriptionArray &)
IMPORT_C void	GetImageTypesL(RImageTypeDescriptionArray &)
IMPORT_C void	GetInterfaceImplementationsL(const RUidDataArray &, RUidDataArray &)
IMPORT_C void	GetInterfaceImplementationsL(const TUid *, const TInt, RUidDataArray &)
IMPORT_C void	GetPluginPropertiesL(const TUid, RUidDataArray &)
IMPORT_C TUid	ImplementationUid()
IMPORT_C TImageConvOperation *	OperationL()
IMPORT_C void	Prepare(TRequestStatus *)
IMPORT_C TInt	SetEncoderThreadPriority(TThreadPriority)
IMPORT_C void	SetThumbnail(TBool)

Protected Member Functions
	CImageEncoder()
IMPORT_C void	CustomAsync(TRequestStatus *, TInt)
IMPORT_C void	CustomSyncL(TInt)
IMPORT_C CImageEncoderPlugin *	Plugin()

Inherited Functions
	CBase::CBase()
	CBase::Delete(CBase *)
	CBase::Extension_(TUint,TAny &,TAny )
	CBase::operator new(TUint)
	CBase::operator new(TUint,TAny *)
	CBase::operator new(TUint,TLeave)
	CBase::operator new(TUint,TLeave,TUint)
	CBase::operator new(TUint,TUint)
	CBase::~CBase()

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

Member Enumeration Documentation

Enum TOptions

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

Enumerator	Value	Description
EOptionNone	0x00	No flag set
EOptionAlwaysThread	0x01	Perform the encoding in a separate thread
EOptionGenerateAdaptivePalette	0x02	If the codec supports it, generate a palette based on the colors present in the image data, rather than using the default palette
EPreferFastEncode	0x04	Use the highest possible image encoding speed; this may result in lower image quality. This flag is more applicable to formats which use "lossy" compression algorithms, such as JPEG. Decoders that do not support fast encoding will ignore it.
EOptionExtStream	0x0100	Codec must support block streaming extension.
EOptionExtRotation	0x0200	Codec must support rotation through the operation extension.
EOptionExtMirrorHorizontalAxis	0x0400	Codec must support horizontal mirror through the operation extension.
EOptionExtMirrorVerticalAxis	0x0800	Codec must support vertical mirror through the operation extension.
EOptionExtUseWithSetThumbnail	0x1000	Codec must support setting thumbnail when using the other extensions (e.g. thumbnail rotation)
EOptionExtReserved1	0x2000	Reserved.
EOptionExtReserved2	0x4000	Reserved.
EOptionExtReserved3	0x8000	Reserved.

Constructor & Destructor Documentation

CImageEncoder ( )

IMPORT_C

CImageEncoder

(

)

[protected]

Constructor for this class.

~CImageEncoder ( )

IMPORT_C

~CImageEncoder

(

)

[virtual]

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.

Member Function Documentation

BlockStreamerL ( )

IMPORT_C TImageConvStreamedEncode *

BlockStreamerL

(

)

Get the extension interface for block streaming on image.

Leave Codes
KErrNotSupported	if loaded codec plugin does not support this optional extension.
Other	system wide errors

Cancel ( )

IMPORT_C void

Cancel

(

)

Asynchronously cancels any conversions currently in progress.

Convert ( TRequestStatus , const CFbsBitmap &, const CFrameImageData )

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

Encodes a bitmap asynchronously.

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

CustomAsync ( TRequestStatus *, TInt )

IMPORT_C void	CustomAsync	(	TRequestStatus *	aRequestStatus,
			TInt	aParam
		)	[protected]

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
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.
aParam	Interpretation determined by plugin.

CustomSyncL ( TInt )

IMPORT_C void

CustomSyncL

(

TInt

aParam

)

[protected]

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
aParam	Interpretation determined by plugin.

DataNewL ( HBufC8 *&, const TDesC8 &, const TOptions )

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

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.

See also: TOptions

Parameters
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.
aMIMEType	The MIME type to use for the encoding.
aOptions	Encoder options to use.

Return Value: A pointer to the newly created encoder.

DataNewL ( HBufC8 *&, const TOptions, const TUid, const TUid, const TUid )

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()
		)	[static]

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.

See also: KUidICLJpegEXIFInterface KUidICLJpegImageFrameInterface

See also: TOptions

Parameters
aDestinationData	The buffer pointer into which to put the encoded image.
aOptions	The encoder options to use.
aImageType	The image type to use for the encoding (mandatory).
aImageSubType	The image sub-type to use for the encoding (only if applicable, defaults to KNullUid).
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: 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
ImageConversion	19 No base type given for sub-type.
ImageConversion	20 No base type given for encoder implementation.

FileNewL ( RFs &, const TDesC &, const TDesC8 &, const TOptions )

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

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.

See also: TOptions

Parameters
aFs	A reference to a file server session for the encoder to use.
aDestinationFilename	The name of the file into which to put the encoded image.
aMIMEType	The MIME type to use for the encoding.
aOptions	The encoder options to use.

Return Value: Returns a pointer to the newly created encoder.

FileNewL ( RFs &, const TDesC &, const TOptions, const TUid, const TUid, const TUid )

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()
		)	[static]

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.

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.

See also: KUidICLJpegEXIFInterface KUidICLJpegImageFrameInterface

See also: TOptions

Parameters
aFs	A reference to a file server session for the encoder to use.
aDestinationFilename	The name of the file into which to put the encoded image.
aOptions	Options to use.
aImageType	The image type to use for the encoding (mandatory).
aImageSubType	The image sub-type to use for the encoding (only if applicable, defaults to KNullUid).
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: 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
ImageConversion	19 No base type given for sub-type.
ImageConversion	20 No base type given for encoder implementation.

FileNewL ( RFile &, const TDesC8 &, const TOptions )

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

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.

See also: TOptions

Parameters
aFile	The handle of an open file to write the encoded image to
aMIMEType	The MIME type to use for the encoding.
aOptions	The encoder options to use.

Return Value: 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.

FileNewL ( RFile &, const TOptions, const TUid, const TUid, const TUid )

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()
		)	[static]

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.

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.

See also: KUidICLJpegEXIFInterface KUidICLJpegImageFrameInterface

See also: TOptions

Parameters
aFile	The handle of an open file to write the encoded image to
aOptions	Options to use.
aImageType	The image type to use for the encoding (mandatory).
aImageSubType	The image sub-type to use for the encoding (only if applicable, defaults to KNullUid).
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: 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
ImageConversion	19 No base type given for sub-type.
ImageConversion	20 No base type given for encoder implementation.

GetFileTypesL ( RFileExtensionMIMETypeArray & )

IMPORT_C void

GetFileTypesL

(

RFileExtensionMIMETypeArray &

aFileExtensionArray

)

[static]

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

GetImageSubTypesL ( const TUid, RImageTypeDescriptionArray & )

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

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
aImageType	The basic image type for which a list of sub-types should be returned.
aSubTypeArray	An empty array, into which this function will put a list of of supported image sub-types.

GetImageTypesL ( RImageTypeDescriptionArray & )

IMPORT_C void

GetImageTypesL

(

RImageTypeDescriptionArray &

aImageTypeArray

)

[static]

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
aImageTypeArray	An empty array, into which this function will put a list of supported image types.

GetInterfaceImplementationsL ( const RUidDataArray &, RUidDataArray & )

IMPORT_C void	GetInterfaceImplementationsL	(	const RUidDataArray &	aRequiredUids,
			RUidDataArray &	aImplArray
		)	[static]

Gets a list of encoder implementations UIDs that have some specific uids (properties, image type, image sub-type or class uids).

Parameters
aRequiredUids	The array containing the UIDs of the required uids (properties, image type, image sub-type or class uids).
aImplArray	The array containing the implementation UIDs of the available encoder plugins with the required UIDs. The caller has the ownership of the array.

GetInterfaceImplementationsL ( const TUid *, const TInt, RUidDataArray & )

IMPORT_C void	GetInterfaceImplementationsL	(	const TUid *	aRequiredUids,
			const TInt	aLength,
			RUidDataArray &	aImplArray
		)	[static]

Gets a list of encoder implementations UIDs that have some specific required uids (properties, image type, image sub-type or class uids).

Parameters
aRequiredUids	The array containing the UIDs of the required uids (properties, image type, image sub-type or class uids).
aLength	The length of aRequiredUids (number of required uids).
aImplArray	The array containing the implementation UIDs of the available encoder plugins with the required UIDs. The caller has the ownership of the array.

GetPluginPropertiesL ( const TUid, RUidDataArray & )

IMPORT_C void	GetPluginPropertiesL	(	const TUid	aImplementationUid,
			RUidDataArray &	aPropertiesArray
		)	[static]

Gets a list of the properties of a specific encoder plugin.

Parameters
aImplementationUid	The encoder implementation UID for which the plugin properties need to be retrieved.
aPropertiesArray	The array of plugin properties owned by the specified encoder. The caller has the ownership of the array.

ImplementationUid ( )

IMPORT_C TUid

ImplementationUid

(

)

const

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

Return Value: The implementation UID of the encoder.

OperationL ( )

IMPORT_C TImageConvOperation *

OperationL

(

)

Get the extension interface for operations on image.

Plugin ( )

IMPORT_C CImageEncoderPlugin *

Plugin

(

)

const [protected]

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.

Prepare ( TRequestStatus * )

IMPORT_C void

Prepare

(

TRequestStatus *

aRequestStatus

)

Optional call from client which may be made on the encoder to allow analysis of image prior to calling Convert.

Should be called once encode is fully set up e.g. any encode operations defined.

SetEncoderThreadPriority ( TThreadPriority )

IMPORT_C TInt

SetEncoderThreadPriority

(

TThreadPriority

aPriority

)

Set the encoder worker thread priority

SetThumbnail ( TBool )

IMPORT_C void

SetThumbnail

(

TBool

aDoGenerateThumbnail

)

Select to encode or not the thumbnail

Parameters
aDoGenerateThumbnail	EFalse if no generation of thumbnail

Parameters
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.
aSource	A bitmap to encode.
aFrameImageData	The frame image data (optional, defaults to NULL). 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.

CImageEncoder Class Reference

Inherits from

Detailed Description

Member Enumeration Documentation

Enum TOptions

Constructor & Destructor Documentation

CImageEncoder ( )

~CImageEncoder ( )

Member Function Documentation

BlockStreamerL ( )

Cancel ( )

Convert ( TRequestStatus *, const CFbsBitmap &, const CFrameImageData * )

CustomAsync ( TRequestStatus *, TInt )

CustomSyncL ( TInt )

DataNewL ( HBufC8 *&, const TDesC8 &, const TOptions )

DataNewL ( HBufC8 *&, const TOptions, const TUid, const TUid, const TUid )

FileNewL ( RFs &, const TDesC &, const TDesC8 &, const TOptions )

FileNewL ( RFs &, const TDesC &, const TOptions, const TUid, const TUid, const TUid )

FileNewL ( RFile &, const TDesC8 &, const TOptions )

FileNewL ( RFile &, const TOptions, const TUid, const TUid, const TUid )

GetFileTypesL ( RFileExtensionMIMETypeArray & )

GetImageSubTypesL ( const TUid, RImageTypeDescriptionArray & )

GetImageTypesL ( RImageTypeDescriptionArray & )

GetInterfaceImplementationsL ( const RUidDataArray &, RUidDataArray & )

GetInterfaceImplementationsL ( const TUid *, const TInt, RUidDataArray & )

GetPluginPropertiesL ( const TUid, RUidDataArray & )

ImplementationUid ( )

OperationL ( )

Plugin ( )

Prepare ( TRequestStatus * )

SetEncoderThreadPriority ( TThreadPriority )

SetThumbnail ( TBool )

Convert ( TRequestStatus , const CFbsBitmap &, const CFrameImageData )