#include <ImageConversion.h>
Link against:
imageconversion.lib
class CImageDecoder : public CBase;
Description
Provides access to the Image Conversion Library decoders.
This class provides functions to decode images held in files or descriptors. To decode buffered images use the buffered version
of this class CBufferedImageDecoder.
Regarding DRM: Note that intent is evaluated when a CImageDecoder instance is being constructed by one of the CImageDecoder::FileNewL(RFs &,const TDesC &,const TDesC8 &,const TOptions) methods. It is executed after at least one frame of the image has been successfully decoded. Subsequent converts using the
same CImageDecoder instance will not execute intent.
Derivation
CBase -
Base class for all classes to be instantiated on the heap.
CImageDecoder -
Provides access to the Image Conversion Library decoders.
Members
Defined in CImageDecoder:
Cancel()Cancels any conversions currently in progress (Cancel is synchronous). ContinueConvert(TRequestStatus *)Continue decoding a frame and/or mask after new image data was added to the sour...ContinueProcessingHeaderL()Continue processing image headers after new image data was added to the source f...Convert(TRequestStatus *,CFbsBitmap &,CFbsBitmap &,TInt)Start decoding an image frame and mask asynchronously.Convert(TRequestStatus *,CFbsBitmap &,TInt)Start decoding an image frame asynchronously.CustomAsync(TRequestStatus *,TInt)Sets up background convert cycle, bypassing CImageDecoder::Convert(TRequestStatu...CustomSyncL(TInt)Calls CImageDecoderPlugin::HandleCustomSyncL(aParam) that executes user defined ...DataNewL(RFs &,const TDesC8 &,const TDesC8 &,const TOptions)Create a decoder for the image in the source buffer. The client supplies a MIME ...DataNewL(RFs &,const TDesC8 &,const TOptions,const TUid,const TUid,const TUid)Creates a decoder for the image in the source buffer.EAllowGeneratedMaskSetting this flag requests that the plugin generate a mask during decoding.EImageTypeMainUse the main imageEImageTypeThumbnailUse the thumbnail as source imageEOptionAllowZeroFrameOpenAllow Opens to complete with no error if there is less than one frame available....EOptionAlwaysThreadPerform the decoding in a separate threadEOptionExtReserved7Reserved.EOptionExtReserved8Reserved.EOptionIgnoreExifMetaDataWhen specified, this flag indicates that the decoder must ignore the EXIF meta-d...EOptionNoDitherDo not dither the decoded imageEOptionNoneNo flag setEPreferFastDecodeUse the highest possible image decoding speed; this may result in lower image qu...FileNewL(RFs &,const TDesC &,const TDesC8 &,const TOptions)Create a decoder for the image in the named file. The client supplies a MIME typ...FileNewL(RFs &,const TDesC &,const TOptions,const TUid,const TUid,const TUid)Create a decoder for the image in the named file.FileNewL(RFs &,const TMMSource &,const TDesC8 &,const TOptions)Create a decoder for the image in the named file. The client supplies a MIME typ...FileNewL(RFs &,const TMMSource &,const TOptions,const TUid,const TUid,const TUid)Create a decoder for the image in the named source.FrameCommentL(TInt,TInt)constReturn a particular comment attached to a given frame of the image.FrameCount()constReturn the number of frames in the image being decoded.FrameData(TInt)constReturns additional plugin specific information on a specified frame.FrameInfo(TInt)constReturn the frame info for a specified frame of the image.FrameInfoStringsL(TInt)Return the formatted frame information strings for a specific frame. Ownership i...FrameInfoStringsLC(TInt)Return the formatted frame information strings for a specific frame and leave it...GetFileTypesL(RFileExtensionMIMETypeArray &)Get a list of the file extensions that can be decoded and their corresponding MI...GetImageSubTypesL(const TUid,RImageTypeDescriptionArray &)For a given basic image type, get a list of the sub image types that can be deco...GetImageTypesL(RImageTypeDescriptionArray &)Get a list of the basic image types that can be decoded, based on the currently ...GetImplementationInformationL(TUid)Gets the implementation information for a specific decoder pluginGetMimeTypeDataL(const TDesC8 &,TDes8 &)Get the primary MIME type of the decoder that will be used to decode a descripto...GetMimeTypeFileL(RFs &,const TDesC &,TDes8 &)Get the primary MIME type of the decoder that will be used to decode a file. Som...ImageCommentL(TInt)constReturn a particular comment attached to the image.ImageType(TInt,TUid &,TUid &)constRetrieves the image type and sub-type for a given frame of the image that has ju...ImplementationUid()constReturn the implementation UID of the decoder being used to decode the image.IsImageHeaderProcessingComplete()constReturn the status of the image.NumberOfFrameComments(TInt)constReturn the number of comments attached to a given frame of the image (as opposed...NumberOfImageComments()constReturn the number of comments attached to the image (as opposed to a particular ...Plugin()constReturns associated CImageDecoderPlugin.ReducedSize(const TSize &,TInt,TSize &)constCalculates reduced size of the decoded bitmap based on the input parameters and ...ReductionFactor(const TSize &,const TSize &)constFunction to calculate the reduction factor based on the input parameters.SetDecoderThreadPriority(TThreadPriority)Set the decoder worker thread prioritySetImageTypeL(TInt)Set the source image type, this can be any value from TImageType. It can leave w...TImageTypeFlags to control which image is decoded. This can be used when the source file o...TOptionsFlags to control how the image is decoded. These can be combined using an OR ope...~CImageDecoder()Destructor for this class.
Inherited from CBase:
Construction and destruction
IMPORT_C virtual ~CImageDecoder();
Description
Destructor for this class.
If using a local file session, it closes it. It also informs ECom that has finished with the decoder instance.
Frees all resources owned by the object prior to its destruction.
GetImageTypesL(RImageTypeDescriptionArray &)
IMPORT_C static void GetImageTypesL(RImageTypeDescriptionArray &aImageTypeArray);
Description
Get a list of the basic image types that can be decoded, based on the currently available decoder 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
ResetAndDestroy() on it to free the entries.
Parameters
RPointerArray &aImageTypeArray |
An empty array, into which this function will put a list of entries. Each entry will consist of the "display string" from
the registry entry for a plugin that has been found and that is a decoder for a basic image type, accompanied by the Uids
for that image type. Since we asked for basic types the second Uid, for the image sub-type, will always be zero.
|
|
GetImageSubTypesL(const TUid,RImageTypeDescriptionArray &)
IMPORT_C static void GetImageSubTypesL(const TUid aImageType, RImageTypeDescriptionArray &aSubTypeArray);
Description
For a given basic image type, get a list of the sub image types that can be decoded, based on the currently available decoder
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
ResetAndDestroy() on it to free the entries.
Parameters
const TUid aImageType |
The basic image type for which you want a list of sub-types.
|
RPointerArray &aSubTypeArray |
An empty array, into which this function will put a list of entries. Each entry will consist of the "display string" from
the registry entry for a plugin that has been found and that is a decoder for a sub-type of the given basic image type, accompanied
by the Uids for the sub type. The first Uid, for the basic type, will always correspond to aImageType.
|
|
GetFileTypesL(RFileExtensionMIMETypeArray &)
IMPORT_C static void GetFileTypesL(RFileExtensionMIMETypeArray &aFileExtensionArray);
Description
Get a list of the file extensions that can be decoded and their corresponding MIME types, based on the currently available
decoder 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
ResetAndDestroy() on it to free the entries.
Parameters
RPointerArray &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 a decoder plugin has been found, accompanied by the primary MIME type and then any secondary MIME types (if present).
|
|
GetMimeTypeFileL(RFs &,const TDesC &,TDes8 &)
IMPORT_C static void GetMimeTypeFileL(RFs &aFs, const TDesC &aFileName, TDes8 &aMimeType);
Description
Get the primary MIME type of the decoder that will be used to decode a file. Some file types (like OTA or WBPM), which do
not have unique pattern in their header may not be recognised, in case when the source file name doesn't have extension or,
extension is not common to that file type. Such files are not supported by this API.
Parameters
RFs &aFs |
A reference to a file server session to use.
|
const TDesC16 &aFileName |
The name of the file for which a MIME type has to be determined
|
TDes8 &aMimeType |
An empty descriptor in which the MIME type assosiated with the file will be returned. Ownership is passed to the caller.
|
|
GetMimeTypeDataL(const TDesC8 &,TDes8 &)
IMPORT_C static void GetMimeTypeDataL(const TDesC8 &aImageData, TDes8 &aMimeType);
Description
Get the primary MIME type of the decoder that will be used to decode a descriptor. Some file types (like OTA or WBPM), which
do not have unique pattern in their header may not be recognised. Such files are not supported by this API
Parameters
const TDesC8 &aImageData |
A descriptor containing the image data for which a MIME type has to be determined.
|
TDes8 &aMimeType |
An empty descriptor in which the MIME type assosiated with the file will be returned. Ownership is passed to the caller.
|
|
GetImplementationInformationL(TUid)
IMPORT_C static CImplementationInformationType* GetImplementationInformationL(TUid aImplementationUid);
Description
Gets the implementation information for a specific decoder plugin
Ownership of the implementation information is passed to the caller.
Parameters
TUid aImplementationUid |
The decoder implementation UID for which to retrieve implementation information
|
|
Return value
FileNewL(RFs &,const TDesC &,const TDesC8 &,const TOptions)
IMPORT_C static CImageDecoder* FileNewL(RFs &aFs, const TDesC &aSourceFilename, const TDesC8 &aMIMEType, const TOptions aOptions=EOptionNone);
Description
Create a decoder for the image in the named file. The client supplies a MIME type which will be used to try and select an
appropriate plugin decoder. If it finds a decoder it creates it and then goes on to use that decoder to scan the beginning
of the image file.
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 decoder to use.
|
const TDesC16 &aSourceFilename |
The name of the file to be decoded.
|
const TDesC8 &aMIMEType |
The MIME type of the image in the file.
|
const CImageDecoder::TOptions aOptions |
Decoder options to use.
|
|
Return value
Leave codes
KEComErrNoInterfaceIdentified |
ECom could not find the specified interface.
|
KErrNotFound |
Either the specific plugin decoder for this file hasn't been found, or the file itself is missing.
|
|
See also:
FileNewL(RFs &,const TDesC &,const TOptions,const TUid,const TUid,const TUid)
IMPORT_C static CImageDecoder* FileNewL(RFs &aFs, const TDesC &aSourceFilename, const TOptions aOptions=EOptionNone, const
TUid aImageType=TUid::Null(), const TUid aImageSubType=TUid::Null(), const TUid aDecoderUid=TUid::Null());
Description
Create a decoder for the image in the named file.
If the client supplies an image type (and sub-type, if applicable) or decoder UID, these will be used to try and select an
appropriate plugin decoder. If not, then the selection will be done by matching the image header in the file. If it finds
a decoder, it will be created and then used to scan the beginning of the image file.
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 decoded, use the static functions CImageDecoder::GetImageTypesL(RImageTypeDescriptionArray &) and CImageDecoder::GetImageSubTypesL(const TUid,RImageTypeDescriptionArray &).
Parameters
RFs &aFs |
A reference to a file server session for the decoder to use.
|
const TDesC16 &aSourceFilename |
The name of the file to be decoded.
|
const CImageDecoder::TOptions aOptions |
Decoder options to use.
|
const TUid aImageType |
The image type of the image in the file (optional, defaults to KNullUid).
|
const TUid aImageSubType |
The image sub-type of the image in the file (optional, defaults to KNullUid).
|
const TUid aDecoderUid |
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
Leave codes
KErrUnderflow |
Not enough data in file to identify which plugin decoder to use.
|
KErrNotFound |
Either the appropriate plugin decoder for this file hasn't been found, or the file itself is missing.
|
KEComErrNoInterfaceIdentified |
ECom could not find the specified interface.
|
|
Panic codes
EIllegalImageSubType |
No base type given for sub-type.
|
|
See also:
FileNewL(RFs &,const TDesC &,const TDesC8 &,ContentAccess::TIntent,const TOptions)
IMPORT_C static CImageDecoder* FileNewL(RFs &aFs, const TDesC &aSourceFilename, const TDesC8 &aMIMEType, ContentAccess::TIntent
aIntent, const TOptions aOptions=EOptionNone);
Description
Create a decoder for the image in the named file. The client supplies a MIME type which will be used to try and select an
appropriate plugin decoder. If it finds a decoder it creates it and then goes on to use that decoder to scan the beginning
of the image file.
Parameters
RFs &aFs |
A reference to a file server session for the decoder to use.
|
const TDesC16 &aSourceFilename |
The name of the file to be decoded.
|
const TDesC8 &aMIMEType |
The MIME type of the image in the file.
|
ContentAccess::TIntent aIntent |
The DRM Intent for image conversion.
|
const CImageDecoder::TOptions aOptions |
The decoder options to use.
|
|
Return value
Leave codes
KEComErrNoInterfaceIdentified |
ECom could not find the specified interface.
|
KErrNotFound |
Either the specific plugin decoder for this file hasn't been found, or the file itself is missing.
|
|
FileNewL(RFs &,const TDesC &,ContentAccess::TIntent,const TOptions,const TUid,const TUid,const TUid)
IMPORT_C static CImageDecoder* FileNewL(RFs &aFs, const TDesC &aSourceFilename, ContentAccess::TIntent aIntent, const TOptions
aOptions=EOptionNone, const TUid aImageType=TUid::Null(), const TUid aImageSubType=TUid::Null(), const TUid aDecoderUid=TUid::Null());
Description
Creates a decoder for the image in the named file. If the client supplies an image type (and sub-type, if applicable) or decoder
UID, these will be used to try and select an appropriate plugin decoder. If not, then the selection will be done by matching
the image header in the file. If it finds a decoder it creates it and then goes on to use that decoder to scan the beginning
of the image file.
Parameters
RFs &aFs |
A reference to a file server session for the decoder to use.
|
const TDesC16 &aSourceFilename |
The name of the file to be decoded.
|
ContentAccess::TIntent aIntent |
The DRM Intent for image conversion.
|
const CImageDecoder::TOptions aOptions |
The decoder options to use. See TOptions.
|
const TUid aImageType |
The image type of the image in the file (optional, defaults to KNullUid).
|
const TUid aImageSubType |
The image sub-type of the image in the file (optional, defaults to KNullUid).
|
const TUid aDecoderUid |
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
Leave codes
KErrUnderflow |
Not enough data in file to identify which plugin decoder to use.
|
KErrNotFound |
Either the appropriate plugin decoder for this file hasn't been found, or the file itself is missing.
|
KEComErrNoInterfaceIdentified |
ECom could not find the specified interface.
|
|
Panic codes
EIllegalImageSubType |
No base type given for sub-type.
|
|
See also:
FileNewL(RFile &,const TDesC8 &,ContentAccess::TIntent,const TOptions)
IMPORT_C static CImageDecoder* FileNewL(RFile &aFile, const TDesC8 &aMIMEType, ContentAccess::TIntent aIntent, const TOptions
aOptions=EOptionNone);
Description
Create a decoder for the image in the named file. The client supplies a MIME type which will be used to try and select an
appropriate plugin decoder. If it finds a decoder it creates it and then goes on to use that decoder to scan the beginning
of the image file.
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 the file to decode
|
const TDesC8 &aMIMEType |
The MIME type of the image in the file.
|
ContentAccess::TIntent aIntent |
The DRM Intent to open the file with
|
const CImageDecoder::TOptions aOptions |
Decoder options to use.
|
|
Return value
Leave codes
KEComErrNoInterfaceIdentified |
ECom could not find the specified interface.
|
KErrNotFound |
Either the appropriate plugin decoder for this file hasn't been found, or the file itself is missing.
|
|
See also:
FileNewL(RFile &,ContentAccess::TIntent,const TOptions,const TUid,const TUid,const TUid)
IMPORT_C static CImageDecoder* FileNewL(RFile &aFile, ContentAccess::TIntent aIntent, const TOptions aOptions=EOptionNone,
const TUid aImageType=TUid::Null(), const TUid aImageSubType=TUid::Null(), const TUid aDecoderUid=TUid::Null());
Description
Creates a decoder for the image in the named file. If the client supplies an image type (and sub-type, if applicable) or decoder
UID, these will be used to try and select an appropriate plugin decoder. If not, then the selection will be done by matching
the image header in the file. If it finds a decoder it creates it and then goes on to use that decoder to scan the beginning
of the image file.
Parameters
RFile &aFile |
The handle of the file to decode
|
ContentAccess::TIntent aIntent |
The DRM Intent for image conversion.
|
const CImageDecoder::TOptions aOptions |
The decoder options to use. See TOptions.
|
const TUid aImageType |
The image type of the image in the file (optional, defaults to KNullUid).
|
const TUid aImageSubType |
The image sub-type of the image in the file (optional, defaults to KNullUid).
|
const TUid aDecoderUid |
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
Leave codes
KErrUnderflow |
Not enough data in file to identify which plugin decoder to use.
|
KErrNotFound |
Either the appropriate plugin decoder for this file hasn't been found, or the file itself is missing.
|
KEComErrNoInterfaceIdentified |
ECom could not find the specified interface.
|
|
Panic codes
EIllegalImageSubType |
No base type given for sub-type.
|
|
See also:
FileNewL(RFs &,const TMMSource &,const TDesC8 &,const TOptions)
IMPORT_C static CImageDecoder* FileNewL(RFs &aFs, const TMMSource &aFileSource, const TDesC8 &aMIMEType, const TOptions aOptions=EOptionNone);
Description
Create a decoder for the image in the named file. The client supplies a MIME type which will be used to try and select an
appropriate plugin decoder. If it finds a decoder it creates it and then goes on to use that decoder to scan the beginning
of the image file.
Parameters
RFs &aFs |
A reference to a file server session for the decoder to use.
|
const TMMSource &aFileSource |
An interface between filename based and file handle.
|
const TDesC8 &aMIMEType |
The MIME type of the image in the file.
|
const CImageDecoder::TOptions aOptions |
The decoder options to use. Specifying one of more extension options (for example EOptionExtCrop) can be used to cause the
to cause a plugin to load which supports the image type and supports the requested extensions.
|
|
Return value
Leave codes
KErrNotSupported |
A matching decoder could not be found for the MIME type.
|
KErrNotFound |
Either the specific plugin decoder for this source image hasn't been found, or the source image itself is missing, or a plugin
with the requested extensions cannot be found.
|
|
FileNewL(RFs &,const TMMSource &,const TOptions,const TUid,const TUid,const TUid)
IMPORT_C static CImageDecoder* FileNewL(RFs &aFs, const TMMSource &aFileSource, const TOptions aOptions=EOptionNone, const
TUid aImageType=TUid::Null(), const TUid aImageSubType=TUid::Null(), const TUid aDecoderUid=TUid::Null());
Description
Create a decoder for the image in the named source.
Parameters
RFs &aFs |
A reference to a file server session for the decoder to use.
|
const TMMSource &aFileSource |
An interface between filename based and file handle.
|
const CImageDecoder::TOptions aOptions |
The decoder options to use. Specifying one of more extension options (for example EOptionExtCrop) can be used to cause the
to cause a plugin to load which supports the image type and supports the requested extensions.
|
const TUid aImageType |
The image type of the image in the file.
|
const TUid aImageSubType |
The image sub-type of the image in the file.
|
const TUid aDecoderUid |
The implementation UID for a specific codec or a decoder/encoder class UID.
|
|
Return value
Leave codes
KErrNotSupported |
A matching decoder could not be found for the MIME type.
|
KErrNotFound |
Either the specific plugin decoder for this source image hasn't been found, or the source image itself is missing.
|
KEComErrNoInterfaceIdentified |
ECom could not find the specified interface.
|
|
Panic codes
EIllegalImageSubType |
No base type given for sub-type.
|
|
DataNewL(RFs &,const TDesC8 &,const TDesC8 &,const TOptions)
IMPORT_C static CImageDecoder* DataNewL(RFs &aFs, const TDesC8 &aSourceData, const TDesC8 &aMIMEType, const TOptions aOptions=EOptionNone);
Description
Create a decoder for the image in the source buffer. The client supplies a MIME type which will be used to try and select
an appropriate plugin decoder. If a decoder is found it is created and then used to scan the beginning of the image file.
Parameters
RFs &aFs |
A reference to a file server session for the decoder to use.
|
const TDesC8 &aSourceData |
The buffer containing the image to be decoded. Note that the framework doesn't take a copy of the actual data, therefore both
the descriptor object and the data must persist during decoding.
|
const TDesC8 &aMIMEType |
The MIME type of the image in the file(used to determine the plugin to create).
|
const CImageDecoder::TOptions aOptions |
The decoder options to use. Specifying one of more extension options (for example EOptionExtCrop) can be used to cause the
to cause a plugin to load which supports the image type and supports the requested extensions.
|
|
Return value
Leave codes
KEComErrNoInterfaceIdentified |
ECom could not find the specified interface.
|
KErrNotFound |
No appropriate plugin decoder for this image has been found.
|
|
See also:
DataNewL(RFs &,const TDesC8 &,const TOptions,const TUid,const TUid,const TUid)
IMPORT_C static CImageDecoder* DataNewL(RFs &aFs, const TDesC8 &aSourceData, const TOptions aOptions=EOptionNone, const TUid
aImageType=TUid::Null(), const TUid aImageSubType=TUid::Null(), const TUid aDecoderUid=TUid::Null());
Description
Creates a decoder for the image in the source buffer.
If the client supplies an image type (and sub-type, if applicable) or decoder UID, these will be used to try and select an
appropriate plugin decoder. If not, then the selection will be done by matching the image header from the buffer. If it finds
a decoder, it is created and then used to scan the beginning of the image buffer.
Parameters
RFs &aFs |
A reference to a file server session for the decoder to use.
|
const TDesC8 &aSourceData |
The buffer containing the image to be decoded. Note that the framework doesn't take a copy of the actual data, therefore both
the descriptor object and the data must persist during decoding.
|
const CImageDecoder::TOptions aOptions |
Decoder options to use.
|
const TUid aImageType |
The image type of the image in the file (optional, defaults to KNullUid).
|
const TUid aImageSubType |
The image sub-type of the image in the file (optional, defaults to KNullUid).
|
const TUid aDecoderUid |
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
Leave codes
KErrUnderflow |
Not enough data in descriptor to identify which plugin decoder to use.
|
KErrNotFound |
No appropriate plugin decoder for this image has been found.
|
KEComErrNoInterfaceIdentified |
ECom could not find the specified interface.
|
|
Panic codes
EIllegalImageSubType |
No base type given for sub-type.
|
|
See also:
Convert(TRequestStatus *,CFbsBitmap &,TInt)
IMPORT_C virtual void Convert(TRequestStatus *aRequestStatus, CFbsBitmap &aDestination, TInt aFrameNumber=0);
Pre-Condition
The destination bitmap aDestination, must be created before the call to CImageDecoder::Convert(TRequestStatus *,CFbsBitmap &,TInt) is made. aDestination must be large enough to contain the frame and be set to the required display mode. CImageDecoder::FrameInfo(TInt)const can be used to obtain the size and display mode of the frame.
Description
Start decoding an image frame asynchronously.
When the conversion is complete, successfully or otherwise, the status is returned in aRequestStatus.
If the operations completes with KErrUnderflow, then there is insufficient information in the descriptor. In this situation,
CImageDecoder::ContinueConvert(TRequestStatus *) should be called repeatedly until the descriptor has accumulated enough information for CImageDecoder::ContinueConvert(TRequestStatus *) to complete with KErrNone.It is the responsibility of the caller to ensure that the original data source used to create this
decoder object gets enough information. If there is no data available then a caller can ignore this error code and use partially
decoded image.
Note: As most codec plugins support downscaling the image but not upscaling, the standard behaviour (i.e. no requested transformations)
for codecs begins with the size of the destination bitmap passed to CImageDecoder::Convert(TRequestStatus *,CFbsBitmap &,TInt) being inspected, and: 1. If the destination size matches the frame size of the image then the image is decoded full size
into the destination bitmap. 2. If the destination size is larger than the frame size of the image then the image is decoded
full size into the destination bitmap with no upscaling. The image origin is aligned with the top left corner of the bitmap
and any area in the bitmap to the bottom and right of image is left in its initialised state. 3. If the destination size is
smaller than the frame size of the image then a reduction factor is calculated and the image is scaled down (1/2, 1/4, 1/8
size) whilst maintaining the aspect ratio of the image. The size is the next smallest size that will fit in the destination
bitmap. The use case for this is when the client wants to pass in the screen size of device and have the image scaled to fill
as much of the screen as possible. However, if the extension interfaces (clipping, scale, operation) are used then the additional
behaviour below applies. 4. If the extension interfaces for clipping rectangle and/or operation are applied, but not scaling,
then the size of the destination bitmap for an unscaled image can be obtained via CImageDecoder::GetDestinationSize(TSize &,TInt). Lets call that SizeA. The same rules apply as given in 1, 2, 3 above resulting in a down-scaled destination if the destination
bitmap is smaller than SizeA. 5. If the extension interface for scaling is called via one of the two TImageConvScaler::SetScalingL(const TSize &,TImageConvScaler::TScalerQuality,TBool)(.. functions then it is required that the destination size is obtained through CImageDecoder::GetDestinationSize(TSize &,TInt) and that a destination bitmap of that size is passed to CImageDecoder::Convert(TRequestStatus *,CFbsBitmap &,TInt). Failure to do this will cause the decoder to fail with KErrArgument. This rule holds if clipping and/or operation is applied
as well as scaling.
Parameters
TRequestStatus *aRequestStatus |
Request status. On completion contains an error code. KErrNone if frame was decoded successfully, KErrUnderflow if the frame
was partially decoded otherwise another of the system-wide error codes.
|
CFbsBitmap &aDestination |
A bitmap that will contain the decoded frame.
|
TInt aFrameNumber |
The frame in a multi-frame image to decode (optional, defaults to zero).
|
|
Convert(TRequestStatus *,CFbsBitmap &,CFbsBitmap &,TInt)
IMPORT_C virtual void Convert(TRequestStatus *aRequestStatus, CFbsBitmap &aDestination, CFbsBitmap &aDestinationMask, TInt
aFrameNumber=0);
Pre-Condition
The destination bitmap aDestination, must be created before the call to CImageDecoder::Convert(TRequestStatus *,CFbsBitmap &,TInt) is made. aDestination must be large enough to contain the frame and be set to the required display mode. CImageDecoder::FrameInfo(TInt)const can be used to obtain the size and display mode of the frame. The destination mask aDestinationMask must be created before
the call to CImageDecoder::Convert(TRequestStatus *,CFbsBitmap &,TInt) is made and must be large enough for the mask. The display mode must be EGray2 or EGray256 and must be EGray256 if the image
contains alpha-blending information. This information can be obtained from the iFlags property of TFrameInfo obtained from a CImageDecoder::FrameInfo(TInt)const call.
Description
Start decoding an image frame and mask asynchronously.
When the conversion is complete, successfully or otherwise, the status is returned in aRequestStatus.
If the operations completes with KErrUnderflow, then there is insufficient information in the descriptor. In this situation,
CImageDecoder::ContinueConvert(TRequestStatus *) should be called repeatedly until the descriptor has accumulated enough information for CImageDecoder::ContinueConvert(TRequestStatus *) to complete with KErrNone.It is the responsibility of the caller to ensure that the original data source used to create this
decoder object gets enough information. If there is no data available then a caller can ignore this error code and use partially
decoded image.
Parameters
TRequestStatus *aRequestStatus |
Request status. On completion contains an error code. KErrNone if frame was decoded successfully, KErrUnderflow if the frame
was partially decoded otherwise another of the system-wide error codes.
|
CFbsBitmap &aDestination |
A bitmap that will contain the decoded frame.
|
CFbsBitmap &aDestinationMask |
A bitmap that will contain the decoded frame mask.
|
TInt aFrameNumber |
The frame in multi-frame image to decode (optional, defaults to zero).
|
|
ContinueConvert(TRequestStatus *)
IMPORT_C virtual void ContinueConvert(TRequestStatus *aRequestStatus);
Description
Continue decoding a frame and/or mask after new image data was added to the source file or descriptor and a previous call
to CImageDecoder::Convert(TRequestStatus *,CFbsBitmap &,TInt) or CImageDecoder::ContinueConvert(TRequestStatus *) returned KErrUnderflow.
Parameters
TRequestStatus *aRequestStatus |
Request status. On completion contains an error code. KErrNone if frame was decoded successfully, KErrUnderflow if the frame
was partially decoded otherwise another of the system-wide error codes.
|
|
IMPORT_C void Cancel();
Description
Cancels any conversions currently in progress (Cancel is synchronous).
IMPORT_C TInt FrameCount() const;
Description
Return the number of frames in the image being decoded.
This function can be called immediately after the call to create the decoder, thus enabling the caller to know how many frames
need to be converted. Client may have to call CImageDecoder::IsImageHeaderProcessingComplete()const & ContinueProcessingHeaders() to ensure all all data is available.
Return value
TInt
|
The number of frames in the source image.
|
|
IsImageHeaderProcessingComplete()const
IMPORT_C TBool IsImageHeaderProcessingComplete() const;
Description
Return the status of the image.
If the image is incomplete EFalse will be returned. The client should continue to supply more data and call ContinueProcessingHeaders()
until ETrue is returned.
Return value
ContinueProcessingHeaderL()
IMPORT_C void ContinueProcessingHeaderL();
Description
Continue processing image headers after new image data was added to the source file or descriptor.
See also:
IMPORT_C const TFrameInfo& FrameInfo(TInt aFrameNumber=0) const;
Description
Return the frame info for a specified frame of the image.
This function can be called immediately after the call to create the decoder, thus enabling the caller to know about each
frame in advance of converting it.
The returned information contains details of the size of the image, the dimensions of the frame, its colour depth and so on.
More advanced information may be available for the image using CImageDecoder::FrameData(TInt)const.
Use CImageDecoder::FrameCount()const to determine how many frames are contained in the image before using this function.
Parameters
TInt aFrameNumber |
The frame number.
|
|
Return value
const TFrameInfo & |
The returned information for the specified frame.
|
|
Panic codes
EFrameNumberOutOfRange |
Frame number outside the range 0 to FrameCount()-1.
|
|
IMPORT_C const CFrameImageData& FrameData(TInt aFrameNumber=0) const;
Description
Returns additional plugin specific information on a specified frame.
The plugin specific information usually covers advanced image features such as image quality, advanced colour settings and
so on.
Use CImageDecoder::FrameCount()const to determine how many frames are contained in the image before using this function.
Parameters
TInt aFrameNumber |
The frame number.
|
|
Return value
Panic codes
EFrameNumberOutOfRange |
Frame number outside the range 0 to FrameCount()-1.
|
|
NumberOfImageComments()const
IMPORT_C TInt NumberOfImageComments() const;
Description
Return the number of comments attached to the image (as opposed to a particular frame).
Return value
TInt
|
The number of comments attached to the image.
|
|
IMPORT_C HBufC* ImageCommentL(TInt aCommentNumber) const;
Description
Return a particular comment attached to the image.
Ownership of the returned buffer is transferred to the caller. Use CImageDecoder::NumberOfImageComments()const to determine how many (if any) comments are contained within the image.
Parameters
TInt aCommentNumber |
The comment number.
|
|
Return value
HBufC16 * |
A buffer containing the comment.
|
|
NumberOfFrameComments(TInt)const
IMPORT_C TInt NumberOfFrameComments(TInt aFrameNumber) const;
Description
Return the number of comments attached to a given frame of the image (as opposed to the whole image).
Use CImageDecoder::FrameCount()const to retrieve the number of frames in the image to ensure that a valid aFrameNumber is used.
Parameters
TInt aFrameNumber |
The frame number.
|
|
Return value
TInt
|
The number of comments attached to a given frame of the image.
|
|
FrameCommentL(TInt,TInt)const
IMPORT_C HBufC* FrameCommentL(TInt aFrameNumber, TInt aCommentNumber) const;
Description
Return a particular comment attached to a given frame of the image.
The desired order of calling methods should be CImageDecoder::FrameCount()const,CImageDecoder::NumberOfFrameComments(TInt)const and then CImageDecoder::FrameCommentL(TInt,TInt)const.
Use CImageDecoder::FrameCount()const to retrieve the number of frames in the image to ensure that a valid aFrameNumber is used.
Use CImageDecoder::NumberOfFrameComments(TInt)const to retrieve the number of comments attached to a given frame of the image (as opposed to the whole image),to ensure that
a valid aCommentNumber is used.
Ownership of the returned buffer is transferred to the caller.
Parameters
TInt aFrameNumber |
The frame number within the image from which to retrieve the specified comment.
|
TInt aCommentNumber |
The comment number to retrieve from the specified frame.
|
|
Return value
HBufC16 * |
A buffer containing the specified comment.
|
|
Panic codes
This |
function may panic with panic category 'ImageConversion' and panic code 13 when called before the header is processed.See
the CImageDecoder::IsImageHeaderProcessingComplete().
|
This |
function panics with panic category 'ImageConversion' and panic code 10 when aFrameNumber is not valid.
|
This |
function panics with panic category 'ImageConversion' and panic code 14 when aCommentNumber is not valid.
|
|
IMPORT_C CFrameInfoStrings* FrameInfoStringsLC(TInt aFrameNumber=0);
Description
Return the formatted frame information strings for a specific frame and leave it on the cleanup stack.
Ownership is transferred to the caller.
Parameters
TInt aFrameNumber |
The frame number from which to retrieve the formatted information string.
|
|
Return value
IMPORT_C CFrameInfoStrings* FrameInfoStringsL(TInt aFrameNumber=0);
Description
Return the formatted frame information strings for a specific frame. Ownership is transferred to the caller.
Parameters
TInt aFrameNumber |
The frame number from which to retrieve the formatted information string.
|
|
Return value
IMPORT_C TUid ImplementationUid() const;
Description
Return the implementation UID of the decoder being used to decode the image.
Return value
TUid
|
The implementation UID of the decoder.
|
|
ImageType(TInt,TUid &,TUid &)const
IMPORT_C void ImageType(TInt aFrameNumber, TUid &aImageType, TUid &aImageSubType) const;
Description
Retrieves the image type and sub-type for a given frame of the image that has just been decoded.
Parameters
TInt aFrameNumber |
The frame number for which type information should be retreived.
|
TUid &aImageType |
On return contains the image type UID for the specified frame.
|
TUid &aImageSubType |
On return contains the image sub-type UID if there is one (or KNullUid if there is not).
|
|
SetAgentProperty(ContentAccess::TAgentProperty,TInt)
IMPORT_C TInt SetAgentProperty(ContentAccess::TAgentProperty aProperty, TInt aValue);
Description
Sets the properties for the Image decoder.
Parameters
ContentAccess::TAgentProperty aProperty |
The property to set.
|
TInt aValue |
The value of the property.
|
|
Return value
TInt
|
KErrNone if successful, otherwise one of the system-wide errors.
|
|
IMPORT_C void SetImageTypeL(TInt aImageType);
Description
Set the source image type, this can be any value from TImageType. It can leave with a system wide error. Typical leaves are
documented below.
Parameters
TInt aImageType |
An image type from TImageType to denote source image that the decoder should use.
|
|
Leave codes
KErrNotFound |
If the image for the type specified is not found.
|
KErrCorrupt |
For a corrupt image. In the case of failing to change the source image from a valid EImageTypeMain image to a corrupt EImageTypeThumbnail,
the decoder resets the image type back to the valid EImageTypeMain.
|
|
ReductionFactor(const TSize &,const TSize &)const
IMPORT_C TInt ReductionFactor(const TSize &aOriginalSize, const TSize &aReducedSize) const;
Description
Function to calculate the reduction factor based on the input parameters.
Parameters
const TSize &aOriginalSize |
A reference to the original size of an image.
|
const TSize &aReducedSize |
A reference to the new size of an image.
|
|
Return value
TInt
|
The reduction factor.
|
|
ReducedSize(const TSize &,TInt,TSize &)const
IMPORT_C TInt ReducedSize(const TSize &aOriginalSize, TInt aReductionFactor, TSize &aReducedSize) const;
Description
Calculates reduced size of the decoded bitmap based on the input parameters and updates aReducedSize with this value.
Parameters
const TSize &aOriginalSize |
A reference to the original size of an image.
|
TInt aReductionFactor |
The Reduction Factor to be applied
|
TSize &aReducedSize |
A reference to the new size of the image.
|
|
Return value
TInt
|
An error code indicating if the function call was successful. KErrNone on success, otherwise KErrArgument.
|
|
SetDecoderThreadPriority(TThreadPriority)
IMPORT_C TInt SetDecoderThreadPriority(TThreadPriority aPriority);
Description
Set the decoder worker thread priority
Parameters
Return value
TInt
|
KErrNotSupported the decoder object doesn't use a worker thread. Other system-wide error codes.
|
|
protected: IMPORT_C void CustomSyncL(TInt aParam);
Description
Calls CImageDecoderPlugin::HandleCustomSyncL(aParam) that executes user defined plugin specific functions. Subsequent behaviour
depends on the CImageDecoderPlugin class.
This function is part of the support for extended codecs for use within classes derived from CImageDecoder.
Note: This function is intended for use by plugin writers only.
Parameters
TInt aParam |
Interpretation dependent on plugin.
|
|
See also:
CustomAsync(TRequestStatus *,TInt)
protected: IMPORT_C void CustomAsync(TRequestStatus *aRequestStatus, TInt aParam);
Description
Sets up background convert cycle, bypassing CImageDecoder::Convert(TRequestStatus *,CFbsBitmap &,TInt). A call to this will result in a call to the associated CImageDecoderPlugin::InitCustomAsyncL(aParam), which if successful
will start background processing. This function uses the same mechanism as CImageDecoder::Convert(TRequestStatus *,CFbsBitmap &,TInt), and therefore cannot be used concurrently. CImageDecoder::Cancel() etc work as expected.
Note: This function is intended for use by plugin writers only.
Parameters
TRequestStatus *aRequestStatus |
Request status. On completion contains an error code. KErrNone if the bitmap was successfully decoded, otherwise another of
the system-wide error codes.
|
TInt aParam |
Interpretation dependent on plugin.
|
|
protected: IMPORT_C CImageDecoderPlugin* Plugin() const;
Description
Returns associated CImageDecoderPlugin.
Allows the extended CImageDecoder object to talk to its CImageDecoderPlugin equivalent.
Note: This function is intendend for use by plugin writers only.
Return value
TOptions
Description
Flags to control how the image is decoded. These can be combined using an OR operation.
EOptionNone |
No flag set
|
EOptionNoDither |
Do not dither the decoded image
|
EOptionAlwaysThread |
Perform the decoding in a separate thread
|
EOptionAllowZeroFrameOpen |
Allow Opens to complete with no error if there is less than one frame available. This should be set for streaming.
|
EAllowGeneratedMask |
Setting this flag requests that the plugin generate a mask during decoding.
Note:
This option is only relevant to image formats that do not already contain mask information.
The client must check that TFrameInfo::ETransparencyPossible is set before attempting to obtain the mask, because not all plugins support mask generation.
|
EPreferFastDecode |
Use the highest possible image decoding 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 decoding will ignore it.
|
EOptionIgnoreExifMetaData |
When specified, this flag indicates that the decoder must ignore the EXIF meta-data, if present. In this case, the ExifMetaData()
should return NULL. This option value is also used to indicate the requirement to ignore the EXIF meta-data when doing the
image transformation.
|
EOptionExtReserved7 |
Reserved.
|
EOptionExtReserved8 |
Reserved.
|
|
TImageType
Description
Flags to control which image is decoded. This can be used when the source file or descriptor contains multiple distinct image
sources.
![[Index]](../../../../a_stock/images/btn_index.gif)
![[Previous]](../../../../a_stock/images/btn_prev_top.gif)
![[Next]](../../../../a_stock/images/btn_next_top.gif)
![[Top]](../../../../a_stock/images/arrow_up_2.gif){kind=icon}
![[Previous]](../../../../a_stock/images/btn_prev.gif)
![[Top]](../../../../a_stock/images/btn_top.gif)
![[Next]](../../../../a_stock/images/btn_next.gif)