CImageDecoder Class Reference

#include <imageconversion.h>

class CImageDecoder : public CBase

Inherits from

  • CImageDecoder
    Public Member Enumerations
    enumTImageType { EImageTypeThumbnail, EImageTypeMain }
    enumTOptions { EOptionNone, EOptionNoDither, EOptionAlwaysThread, EOptionAllowZeroFrameOpen, ..., EOptionAutoRotate }
    Public Member Functions
    virtual ~CImageDecoder()
    IMPORT_C TImageConvStreamedDecode *BlockStreamerL()
    IMPORT_C voidCancel()
    virtual IMPORT_C voidContinueConvert(TRequestStatus *)
    IMPORT_C voidContinueProcessingHeaderL()
    virtual IMPORT_C voidConvert(TRequestStatus *, CFbsBitmap &, TInt)
    virtual IMPORT_C voidConvert(TRequestStatus *, CFbsBitmap &, CFbsBitmap &, TInt)
    IMPORT_C CImageDecoder *DataNewL(RFs &, const TDesC8 &, const TDesC8 &, const TOptions)
    IMPORT_C CImageDecoder *DataNewL(RFs &, const TDesC8 &, const TOptions, const TUid, const TUid, const TUid)
    IMPORT_C CImageDecoder *FileNewL(RFs &, const TDesC &, const TDesC8 &, const TOptions)
    IMPORT_C CImageDecoder *FileNewL(RFs &, const TDesC &, const TOptions, const TUid, const TUid, const TUid)
    IMPORT_C CImageDecoder *FileNewL(RFs &, const TDesC &, const TDesC8 &, ContentAccess::TIntent, const TOptions)
    IMPORT_C CImageDecoder *FileNewL(RFs &, const TDesC &, ContentAccess::TIntent, const TOptions, const TUid, const TUid, const TUid)
    IMPORT_C CImageDecoder *FileNewL(RFile &, const TDesC8 &, ContentAccess::TIntent, const TOptions)
    IMPORT_C CImageDecoder *FileNewL(RFile &, ContentAccess::TIntent, const TOptions, const TUid, const TUid, const TUid)
    IMPORT_C CImageDecoder *FileNewL(RFs &, const TMMSource &, const TDesC8 &, const TOptions)
    IMPORT_C CImageDecoder *FileNewL(RFs &, const TMMSource &, const TOptions, const TUid, const TUid, const TUid)
    IMPORT_C HBufC *FrameCommentL(TInt, TInt)
    IMPORT_C TIntFrameCount()
    IMPORT_C const CFrameImageData &FrameData(TInt)
    IMPORT_C const TFrameInfo &FrameInfo(TInt)
    IMPORT_C CFrameInfoStrings *FrameInfoStringsL(TInt)
    IMPORT_C CFrameInfoStrings *FrameInfoStringsLC(TInt)
    IMPORT_C TIntGetDestinationSize(TSize &, TInt)
    IMPORT_C voidGetFileTypesL(RFileExtensionMIMETypeArray &)
    IMPORT_C voidGetImageSubTypesL(const TUid, RImageTypeDescriptionArray &)
    IMPORT_C voidGetImageTypesL(RImageTypeDescriptionArray &)
    IMPORT_C CImplementationInformationType *GetImplementationInformationL(TUid)
    IMPORT_C voidGetInterfaceImplementationsL(const RUidDataArray &, RUidDataArray &)
    IMPORT_C voidGetInterfaceImplementationsL(const TUid *, const TInt, RUidDataArray &)
    IMPORT_C voidGetMimeTypeDataL(const TDesC8 &, TDes8 &)
    IMPORT_C voidGetMimeTypeFileL(RFs &, const TDesC &, TDes8 &)
    IMPORT_C voidGetPluginPropertiesL(const TUid, RUidDataArray &)
    IMPORT_C HBufC *ImageCommentL(TInt)
    IMPORT_C voidImageType(TInt, TUid &, TUid &)
    IMPORT_C TUidImplementationUid()
    IMPORT_C TBoolIsImageHeaderProcessingComplete()
    IMPORT_C TIntNumberOfFrameComments(TInt)
    IMPORT_C TIntNumberOfImageComments()
    IMPORT_C TImageConvOperation *OperationL()
    IMPORT_C voidPrepare(TRequestStatus *)
    IMPORT_C TIntReducedSize(const TSize &, TInt, TSize &)
    IMPORT_C TIntReductionFactor(const TSize &, const TSize &)
    IMPORT_C TImageConvScaler *ScalerL()
    IMPORT_C TIntSetAgentProperty(ContentAccess::TAgentProperty, TInt)
    IMPORT_C voidSetClippingRectL(const TRect *)
    IMPORT_C TIntSetDecoderThreadPriority(TThreadPriority)
    IMPORT_C voidSetImageTypeL(TInt)
    Protected Member Functions
    CImageDecoder()
    IMPORT_C voidCustomAsync(TRequestStatus *, TInt)
    IMPORT_C voidCustomSyncL(TInt)
    IMPORT_C CImageDecoderPlugin *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 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 FileNewL() 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.

    Member Enumeration Documentation

    Enum TImageType

    Flags to control which image is decoded. This can be used when the source file or descriptor contains multiple distinct image sources.

    EnumeratorValueDescription
    EImageTypeThumbnail0x01

    Use the thumbnail as source image

    EImageTypeMain0x02

    Use the main image

    Enum TOptions

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

    EnumeratorValueDescription
    EOptionNone0x00

    No flag set

    EOptionNoDither0x01

    Do not dither the decoded image

    EOptionAlwaysThread0x02

    Perform the decoding in a separate thread

    EOptionAllowZeroFrameOpen0x04

    Allow Opens to complete with no error if there is less than one frame available. This should be set for streaming.

    EAllowGeneratedMask0x08

    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.

    EPreferFastDecode0x10

    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.

    EOptionMngSubframesNoLoops0x20

    Prevent MNG ImageDecoder from unwinding all the loops

    EOptionUseFrameSizeInPixels0x40

    Setting this flag requests that the plugin use the frame size rather than the overall size when calculating its reduction factor

    EOptionIgnoreExifMetaData0x80

    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.

    EOptionExtCrop0x0100

    Codec must support crop.

    EOptionExtStream0x0200

    Codec must support block streaming extension.

    EOptionExtRotation0x0400

    Codec must support rotation through the operation extension.

    EOptionExtMirrorHorizontalAxis0x0800

    Codec must support horizontal mirror through the operation extension.

    EOptionExtMirrorVerticalAxis0x1000

    Codec must support vertical mirror through the operation extension.

    EOptionExtScaling0x2000

    Codec must support the scaling extension.

    EOptionExtReserved70x4000

    Reserved.

    EOptionExtReserved80x8000

    Reserved.

    EOptionPngMissingiENDFail0x010000

    Requests that decode always fails for Png images without an iEND chunk.

    EOptionWmfIgnoreViewportMetaData0x020000

    Allows WMF codec to ignore any SETVIEWPORTORG, SETVIEWPORTEXT, SCALEVIEWPORTEXT or OFFSETVIEWPORTORG commands in the metafile and allows scaling to destination bitmap.

    EOptionAutoRotate0x040000

    Requests that codec applies the auto rotation when decoding according to the orientation tag in the image Exif header.

    Constructor & Destructor Documentation

    CImageDecoder ( )

    IMPORT_CCImageDecoder()[protected]

    Constructor for this class.

    ~CImageDecoder ( )

    IMPORT_C~CImageDecoder()[virtual]

    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.

    Member Function Documentation

    BlockStreamerL ( )

    IMPORT_C TImageConvStreamedDecode *BlockStreamerL()

    Get the extension interface for block streaming on the image.

    See also: TImageConvStreamedDecode

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

    Returns: Interface to image conversion block streamer.

    Cancel ( )

    IMPORT_C voidCancel()

    Cancels any conversions currently in progress (Cancel is synchronous).

    ContinueConvert ( TRequestStatus * )

    IMPORT_C voidContinueConvert(TRequestStatus *aRequestStatus)[virtual]

    Continue decoding a frame and/or mask after new image data was added to the source file or descriptor and a previous call to Convert() or ContinueConvert() returned KErrUnderflow.

    ParameterDescription
    aRequestStatusRequest 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.

    ContinueProcessingHeaderL ( )

    IMPORT_C voidContinueProcessingHeaderL()

    Continue processing image headers after new image data was added to the source file or descriptor.

    See also: IsImageHeaderProcessingComplete()

    Convert ( TRequestStatus *, CFbsBitmap &, TInt )

    IMPORT_C voidConvert(TRequestStatus *aRequestStatus,
    CFbsBitmap &aDestination,
    TIntaFrameNumber = 0
    )[virtual]

    Start decoding an image frame asynchronously.

    Pre-condition
    The destination bitmap aDestination, must be created before the call to Convert() is made. aDestination must be large enough to contain the frame and be set to the required display mode. FrameInfo() can be used to obtain the size and display mode of the frame.
    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, ContinueConvert() should be called repeatedly until the descriptor has accumulated enough information for ContinueConvert() 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 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. 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(.. functions then it is required that the destination size is obtained through CImageDecoder::GetDestinationSize and that a destination bitmap of that size is passed to CImageDecoder::Convert. 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.

    ParameterDescription
    aRequestStatusRequest 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.
    aDestinationA bitmap that will contain the decoded frame.
    aFrameNumberThe frame in a multi-frame image to decode (optional, defaults to zero).

    Convert ( TRequestStatus *, CFbsBitmap &, CFbsBitmap &, TInt )

    IMPORT_C voidConvert(TRequestStatus *aRequestStatus,
    CFbsBitmap &aDestination,
    CFbsBitmap &aDestinationMask,
    TIntaFrameNumber = 0
    )[virtual]

    Start decoding an image frame and mask asynchronously.

    Pre-condition
    The destination bitmap aDestination, must be created before the call to Convert() is made. aDestination must be large enough to contain the frame and be set to the required display mode. FrameInfo() can be used to obtain the size and display mode of the frame. The destination mask aDestinationMask must be created before the call to Convert() 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 FrameInfo() call.
    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, ContinueConvert() should be called repeatedly until the descriptor has accumulated enough information for ContinueConvert() 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.

    See also: TFrameInfo

    ParameterDescription
    aRequestStatusRequest 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.
    aDestinationA bitmap that will contain the decoded frame.
    aDestinationMaskA bitmap that will contain the decoded frame mask.
    aFrameNumberThe frame in multi-frame image to decode (optional, defaults to zero).

    CustomAsync ( TRequestStatus *, TInt )

    IMPORT_C voidCustomAsync(TRequestStatus *aRequestStatus,
    TIntaParam
    )[protected]

    Sets up background convert cycle, bypassing Convert(). 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 Convert(), and therefore cannot be used concurrently. Cancel() etc work as expected.

    Note: This function is intended for use by plugin writers only.

    ParameterDescription
    aRequestStatusRequest status. On completion contains an error code. KErrNone if the bitmap was successfully decoded, otherwise another of the system-wide error codes.
    aParamInterpretation dependent on plugin.

    CustomSyncL ( TInt )

    IMPORT_C voidCustomSyncL(TIntaParam)[protected]

    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.

    See also: CImageDecoderPlugin::HandleCustomSyncL()

    ParameterDescription
    aParamInterpretation dependent on plugin.

    DataNewL ( RFs &, const TDesC8 &, const TDesC8 &, const TOptions )

    IMPORT_C CImageDecoder *DataNewL(RFs &aFs,
    const TDesC8 &aSourceData,
    const TDesC8 &aMIMEType,
    const TOptionsaOptions = EOptionNone
    )[static]

    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.

    leave
    KEComErrNoInterfaceIdentified ECom could not find the specified interface.
    leave
    KErrNotFound No appropriate plugin decoder for this image has been found.

    See also: TOptions

    ParameterDescription
    aFsA reference to a file server session for the decoder to use.
    aSourceDataThe 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.
    aMIMETypeThe MIME type of the image in the file(used to determine the plugin to create).
    aOptionsThe 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.

    Returns: Returns a pointer to the newly created decoder.

    DataNewL ( RFs &, const TDesC8 &, const TOptions, const TUid, const TUid, const TUid )

    IMPORT_C CImageDecoder *DataNewL(RFs &aFs,
    const TDesC8 &aSourceData,
    const TOptionsaOptions = EOptionNone,
    const TUidaImageType = KNullUid,
    const TUidaImageSubType = KNullUid,
    const TUidaDecoderUid = KNullUid
    )[static]

    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.

    See also: KUidICLJpegEXIFInterface KUidICLJpegImageFrameInterface

    leave
    KErrUnderflow Not enough data in descriptor to identify which plugin decoder to use.
    leave
    KErrNotFound No appropriate plugin decoder for this image has been found.
    leave
    KEComErrNoInterfaceIdentified ECom could not find the specified interface.
    panic
    ImageConversion 19 No base type given for sub-type.

    See also: TOptions

    ParameterDescription
    aFsA reference to a file server session for the decoder to use.
    aSourceDataThe 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.
    aOptionsDecoder options to use.
    aImageTypeThe image type of the image in the file (optional, defaults to KNullUid).
    aImageSubTypeThe image sub-type of the image in the file (optional, defaults to KNullUid).
    aDecoderUidThe 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.

    Returns: Returns a pointer to the newly created decoder.

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

    IMPORT_C CImageDecoder *FileNewL(RFs &aFs,
    const TDesC &aSourceFilename,
    const TDesC8 &aMIMEType,
    const TOptionsaOptions = EOptionNone
    )[static]

    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.

    leave
    KEComErrNoInterfaceIdentified ECom could not find the specified interface.
    leave
    KErrNotFound Either the specific plugin decoder for this file hasn't been found, or the file itself is missing.

    See also: TOptions

    ParameterDescription
    aFsA reference to a file server session for the decoder to use.
    aSourceFilenameThe name of the file to be decoded.
    aMIMETypeThe MIME type of the image in the file.
    aOptionsDecoder options to use.

    Returns: Returns a pointer to the newly created decoder.

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

    IMPORT_C CImageDecoder *FileNewL(RFs &aFs,
    const TDesC &aSourceFilename,
    const TOptionsaOptions = EOptionNone,
    const TUidaImageType = KNullUid,
    const TUidaImageSubType = KNullUid,
    const TUidaDecoderUid = KNullUid
    )[static]

    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 GetImageTypesL() and GetImageSubTypesL().

    See also: KUidICLJpegEXIFInterface KUidICLJpegImageFrameInterface

    leave
    KErrUnderflow Not enough data in file to identify which plugin decoder to use.
    leave
    KErrNotFound Either the appropriate plugin decoder for this file hasn't been found, or the file itself is missing.
    leave
    KEComErrNoInterfaceIdentified ECom could not find the specified interface.
    panic
    ImageConversion 19 No base type given for sub-type.

    See also: TOptions

    ParameterDescription
    aFsA reference to a file server session for the decoder to use.
    aSourceFilenameThe name of the file to be decoded.
    aOptionsDecoder options to use.
    aImageTypeThe image type of the image in the file (optional, defaults to KNullUid).
    aImageSubTypeThe image sub-type of the image in the file (optional, defaults to KNullUid).
    aDecoderUidThe 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.

    Returns: Returns a pointer to the newly created decoder.

    FileNewL ( RFs &, const TDesC &, const TDesC8 &, ContentAccess::TIntent, const TOptions )

    IMPORT_C CImageDecoder *FileNewL(RFs &aFs,
    const TDesC &aSourceFilename,
    const TDesC8 &aMIMEType,
    ContentAccess::TIntentaIntent,
    const TOptionsaOptions = EOptionNone
    )[static]

    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.

    leave
    KEComErrNoInterfaceIdentified ECom could not find the specified interface.
    leave
    KErrNotFound Either the specific plugin decoder for this file hasn't been found, or the file itself is missing.
    ParameterDescription
    aFsA reference to a file server session for the decoder to use.
    aSourceFilenameThe name of the file to be decoded.
    aMIMETypeThe MIME type of the image in the file.
    aIntentThe DRM Intent for image conversion.
    aOptionsThe decoder options to use.

    Returns: A pointer to the newly created decoder.

    FileNewL ( RFs &, const TDesC &, ContentAccess::TIntent, const TOptions, const TUid, const TUid, const TUid )

    IMPORT_C CImageDecoder *FileNewL(RFs &aFs,
    const TDesC &aSourceFilename,
    ContentAccess::TIntentaIntent,
    const TOptionsaOptions = EOptionNone,
    const TUidaImageType = KNullUid,
    const TUidaImageSubType = KNullUid,
    const TUidaDecoderUid = KNullUid
    )[static]

    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.

    See also: KUidICLJpegEXIFInterface KUidICLJpegImageFrameInterface

    leave
    KErrUnderflow Not enough data in file to identify which plugin decoder to use.
    leave
    KErrNotFound Either the appropriate plugin decoder for this file hasn't been found, or the file itself is missing.
    leave
    KEComErrNoInterfaceIdentified ECom could not find the specified interface.
    panic
    ImageConversion 19 No base type given for sub-type.

    See also: TOptions

    ParameterDescription
    aFsA reference to a file server session for the decoder to use.
    aSourceFilenameThe name of the file to be decoded.
    aIntentThe DRM Intent for image conversion.
    aOptionsThe decoder options to use. See TOptions.
    aImageTypeThe image type of the image in the file (optional, defaults to KNullUid).
    aImageSubTypeThe image sub-type of the image in the file (optional, defaults to KNullUid).
    aDecoderUidThe 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.

    Returns: A pointer to the newly created decoder.

    FileNewL ( RFile &, const TDesC8 &, ContentAccess::TIntent, const TOptions )

    IMPORT_C CImageDecoder *FileNewL(RFile &aFile,
    const TDesC8 &aMIMEType,
    ContentAccess::TIntentaIntent,
    const TOptionsaOptions = EOptionNone
    )[static]

    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.

    leave
    KEComErrNoInterfaceIdentified ECom could not find the specified interface.
    leave
    KErrNotFound Either the appropriate plugin decoder for this file hasn't been found, or the file itself is missing.

    See also: TOptions

    ParameterDescription
    aFileThe handle of the file to decode
    aMIMETypeThe MIME type of the image in the file.
    aIntentThe DRM Intent to open the file with
    aOptionsDecoder options to use.

    Returns: Returns a pointer to the newly created decoder.

    FileNewL ( RFile &, ContentAccess::TIntent, const TOptions, const TUid, const TUid, const TUid )

    IMPORT_C CImageDecoder *FileNewL(RFile &aFile,
    ContentAccess::TIntentaIntent,
    const TOptionsaOptions = EOptionNone,
    const TUidaImageType = KNullUid,
    const TUidaImageSubType = KNullUid,
    const TUidaDecoderUid = KNullUid
    )[static]

    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.

    See also: KUidICLJpegEXIFInterface KUidICLJpegImageFrameInterface

    leave
    KErrUnderflow Not enough data in file to identify which plugin decoder to use.
    leave
    KErrNotFound Either the appropriate plugin decoder for this file hasn't been found, or the file itself is missing.
    leave
    KEComErrNoInterfaceIdentified ECom could not find the specified interface.
    panic
    ImageConversion 19 No base type given for sub-type.

    See also: TOptions

    ParameterDescription
    aFileThe handle of the file to decode
    aIntentThe DRM Intent for image conversion.
    aOptionsThe decoder options to use. See TOptions.
    aImageTypeThe image type of the image in the file (optional, defaults to KNullUid).
    aImageSubTypeThe image sub-type of the image in the file (optional, defaults to KNullUid).
    aDecoderUidThe 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.

    Returns: A pointer to the newly created decoder.

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

    IMPORT_C CImageDecoder *FileNewL(RFs &aFs,
    const TMMSource &aFileSource,
    const TDesC8 &aMIMEType,
    const TOptionsaOptions = EOptionNone
    )[static]

    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.

    leave
    KErrNotSupported A matching decoder could not be found for the MIME type.
    leave
    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.
    ParameterDescription
    aFsA reference to a file server session for the decoder to use.
    aFileSourceAn interface between filename based and file handle.
    aMIMETypeThe MIME type of the image in the file.
    aOptionsThe 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.

    Returns: A pointer to the newly created decoder.

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

    IMPORT_C CImageDecoder *FileNewL(RFs &aFs,
    const TMMSource &aFileSource,
    const TOptionsaOptions = EOptionNone,
    const TUidaImageType = KNullUid,
    const TUidaImageSubType = KNullUid,
    const TUidaDecoderUid = KNullUid
    )[static]

    Create a decoder for the image in the named source.

    See also: KUidICLJpegEXIFInterface KUidICLJpegImageFrameInterface

    leave
    KErrNotSupported A matching decoder could not be found for the MIME type.
    leave
    KErrNotFound Either the specific plugin decoder for this source image hasn't been found, or the source image itself is missing.
    leave
    KEComErrNoInterfaceIdentified ECom could not find the specified interface.
    panic
    ImageConversion 19 No base type given for sub-type.
    ParameterDescription
    aFsA reference to a file server session for the decoder to use.
    aFileSourceAn interface between filename based and file handle.
    aOptionsThe 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.
    aImageTypeThe image type of the image in the file.
    aImageSubTypeThe image sub-type of the image in the file.
    aDecoderUidThe implementation UID for a specific codec or a decoder/encoder class UID.

    Returns: A pointer to the newly created decoder.

    FrameCommentL ( TInt, TInt )

    IMPORT_C HBufC *FrameCommentL(TIntaFrameNumber,
    TIntaCommentNumber
    )const

    Return a particular comment attached to a given frame of the image.

    The desired order of calling methods should be FrameCount(),NumberOfFrameComments() and then FrameCommentL().

    Use FrameCount() to retrieve the number of frames in the image to ensure that a valid aFrameNumber is used.

    Use NumberOfFrameComments() 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.

    For further informantion on panic categories, please see the note in CImageDecoder::IsImageHeaderProcessingComplete().

    panic
    ImageConversion 10 aFrameNumber is not valid. See CImageDecoder::FrameCount().
    panic
    ImageConversion 13 Header processing has not completed. See CImageDecoder::IsImageHeaderProcessingComplete().
    panic
    ImageConversion 14 aCommentNumber is not valid. See CImageDecoder::NumberOfFrameComments().

    See also: IsImageHeaderProcessingComplete() FrameCount() NumberOfFrameComments()

    ParameterDescription
    aFrameNumberThe frame number within the image from which to retrieve the specified comment.
    aCommentNumberThe comment number to retrieve from the specified frame.

    Returns: A buffer containing the specified comment.

    FrameCount ( )

    IMPORT_C TIntFrameCount()const

    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 IsImageHeaderProcessingComplete() & ContinueProcessingHeaders() to ensure all all data is available.

    Returns: The number of frames in the source image.

    FrameData ( TInt )

    IMPORT_C const CFrameImageData &FrameData(TIntaFrameNumber = 0)const

    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 FrameCount() to determine how many frames are contained in the image before using this function.

    panic
    ImageConversion 10 Frame number outside the range 0 to FrameCount()-1. See CImageDecoder::FrameCount().

    See also: CImageDecoder::FrameCount()

    ParameterDescription
    aFrameNumberThe frame number.

    Returns: The data for the specified frame.

    FrameInfo ( TInt )

    IMPORT_C const TFrameInfo &FrameInfo(TIntaFrameNumber = 0)const

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

    Use FrameCount() to determine how many frames are contained in the image before using this function.

    panic
    ImageConversion 10 Frame number outside the range 0 to FrameCount()-1. See CImageDecoder::FrameCount().

    See also: CImageDecoder::FrameCount()

    ParameterDescription
    aFrameNumberThe frame number.

    Returns: The returned information for the specified frame.

    FrameInfoStringsL ( TInt )

    IMPORT_C CFrameInfoStrings *FrameInfoStringsL(TIntaFrameNumber = 0)

    Return the formatted frame information strings for a specific frame. Ownership is transferred to the caller.

    ParameterDescription
    aFrameNumberThe frame number from which to retrieve the formatted information string.

    Returns: The formatted frame information strings.

    FrameInfoStringsLC ( TInt )

    IMPORT_C CFrameInfoStrings *FrameInfoStringsLC(TIntaFrameNumber = 0)

    Return the formatted frame information strings for a specific frame and leave it on the cleanup stack.

    Ownership is transferred to the caller.

    ParameterDescription
    aFrameNumberThe frame number from which to retrieve the formatted information string.

    Returns: The formatted frame information strings.

    GetDestinationSize ( TSize &, TInt )

    IMPORT_C TIntGetDestinationSize(TSize &aSize,
    TIntaFrameNumber = 0
    )

    Get the size of the decoded image for the given frame. The calculation will account for any clipping rectangle set, scaling applied through the TImageConvScaler extension and any operation applied through TImageConvOperation. If TImageConvScaler::SetScalingL(.. has been called then the size of the bitmap passed to CImageDecoder::Convert must match the size returned from this function.

    ParameterDescription
    aSizeReturns the size of the decoded image.
    aFrameNumberThe frame number.

    Returns: KErrArgument if an error in calculation is detected e.g. if clipping rectangle is outside of the overall frame boundary. Other system wide errors.

    GetFileTypesL ( RFileExtensionMIMETypeArray & )

    IMPORT_C voidGetFileTypesL(RFileExtensionMIMETypeArray &aFileExtensionArray)[static]

    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.

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

    GetImageSubTypesL ( const TUid, RImageTypeDescriptionArray & )

    IMPORT_C voidGetImageSubTypesL(const TUidaImageType,
    RImageTypeDescriptionArray &aSubTypeArray
    )[static]

    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.

    ParameterDescription
    aImageTypeThe basic image type for which you want a list of sub-types.
    aSubTypeArrayAn 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.

    GetImageTypesL ( RImageTypeDescriptionArray & )

    IMPORT_C voidGetImageTypesL(RImageTypeDescriptionArray &aImageTypeArray)[static]

    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.

    ParameterDescription
    aImageTypeArrayAn 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.

    GetImplementationInformationL ( TUid )

    IMPORT_C CImplementationInformationType *GetImplementationInformationL(TUidaImplementationUid)[static]

    Gets the implementation information for a specific decoder plugin

    Ownership of the implementation information is passed to the caller.

    ParameterDescription
    aImplementationUidThe decoder implementation UID for which to retrieve implementation information

    Returns: A pointer to the implementation information.

    GetInterfaceImplementationsL ( const RUidDataArray &, RUidDataArray & )

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

    Gets a list of decoder implementations UIDs which have a set of specific capabilities defined by UIDs.

    ParameterDescription
    aRequiredUidsThe array containing the required UIDs (properties, image type, image sub-type or class UIDs).
    aImplArrayThe array containing the implementation UIDs of the available decoder plugins with the required UIDs. The caller has the ownership of the array.

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

    IMPORT_C voidGetInterfaceImplementationsL(const TUid *aRequiredUids,
    const TIntaLength,
    RUidDataArray &aImplArray
    )[static]

    Gets a list of decoder implementations UIDs which have a set of specific capabilities defined by UIDs.

    ParameterDescription
    aRequiredUidsThe array containing the required UIDs (properties, image type, image sub-type or class UIDs).
    aLengthThe length of aRequiredUids (number of required UIDs).
    aImplArrayThe array containing the implementation UIDs of the available decoder plugins with the required UIDs. The caller has the ownership of the array.

    GetMimeTypeDataL ( const TDesC8 &, TDes8 & )

    IMPORT_C voidGetMimeTypeDataL(const TDesC8 &aImageData,
    TDes8 &aMimeType
    )[static]

    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

    ParameterDescription
    aImageDataA descriptor containing the image data for which a MIME type has to be determined.
    aMimeTypeAn empty descriptor in which the MIME type assosiated with the file will be returned. Ownership is passed to the caller.

    GetMimeTypeFileL ( RFs &, const TDesC &, TDes8 & )

    IMPORT_C voidGetMimeTypeFileL(RFs &aFs,
    const TDesC &aFileName,
    TDes8 &aMimeType
    )[static]

    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.

    ParameterDescription
    aFsA reference to a file server session to use.
    aFileNameThe name of the file for which a MIME type has to be determined
    aMimeTypeAn empty descriptor in which the MIME type assosiated with the file will be returned. Ownership is passed to the caller.

    GetPluginPropertiesL ( const TUid, RUidDataArray & )

    IMPORT_C voidGetPluginPropertiesL(const TUidaImplementationUid,
    RUidDataArray &aPropertiesArray
    )[static]

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

    ParameterDescription
    aImplementationUidThe decoder implementation UID for which the plugin properties need to be retrieved.
    aPropertiesArrayThe array of plugin properties owned by the specified decoder. The caller has the ownership of the array.

    ImageCommentL ( TInt )

    IMPORT_C HBufC *ImageCommentL(TIntaCommentNumber)const

    Return a particular comment attached to the image.

    Ownership of the returned buffer is transferred to the caller. Use NumberOfImageComments() to determine how many (if any) comments are contained within the image.

    For further informantion on panic categories, please see the note in CImageDecoder::IsImageHeaderProcessingComplete().

    panic
    ImageConversion 12 Comments are not supported. See CImageDecoder::NumberOfImageComments().
    panic
    ImageConversion 13 Header processing has not completed. See CImageDecoder::IsImageHeaderProcessingComplete().
    panic
    ImageConversion 14 aCommentNumber is not valid. See CImageDecoder::NumberOfImageComments().

    See also: IsImageHeaderProcessingComplete() NumberOfImageComments()

    ParameterDescription
    aCommentNumberThe comment number.

    Returns: A buffer containing the comment.

    ImageType ( TInt, TUid &, TUid & )

    IMPORT_C voidImageType(TIntaFrameNumber,
    TUid &aImageType,
    TUid &aImageSubType
    )const

    Retrieves the image type and sub-type for a given frame of the image that has just been decoded.

    For further informantion on panic categories, please see the note in CImageDecoder::IsImageHeaderProcessingComplete().

    panic
    ImageConversion 10 aFrameNumber is not valid. See CImageDecoder::FrameCount().

    See also: IsImageHeaderProcessingComplete() FrameCount()

    ParameterDescription
    aFrameNumberThe frame number for which type information should be retreived.
    aImageTypeOn return contains the image type UID for the specified frame.
    aImageSubTypeOn return contains the image sub-type UID if there is one (or KNullUid if there is not).

    ImplementationUid ( )

    IMPORT_C TUidImplementationUid()const

    Return the implementation UID of the decoder being used to decode the image.

    Returns: The implementation UID of the decoder.

    IsImageHeaderProcessingComplete ( )

    IMPORT_C TBoolIsImageHeaderProcessingComplete()const

    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.

    Panic categories: Many CImageDecoder functions are dependent upon this function returning ETrue before they can successfully be called. If the client calls one of these dependent functions, then that function call may panic with either the 'ImageConversion' panic category or a decoder plugin specific panic category, for example: 'BMPConvertPlugin', 'GIFConvertPlugin', 'ICOConvertPlugin', 'JPEGConvertPlugin', 'MBMConvertPlugin', 'OTAConvertPlugin', 'PNGConvertPlugin', 'TIFFConvertPlugin', 'WBMPConvertPlugin', 'WMFConvertPlugin'.

    Returns: Image status.

    NumberOfFrameComments ( TInt )

    IMPORT_C TIntNumberOfFrameComments(TIntaFrameNumber)const

    Return the number of comments attached to a given frame of the image (as opposed to the whole image).

    Use FrameCount() to retrieve the number of frames in the image to ensure that a valid aFrameNumber is used.

    For further informantion on panic categories, please see the note in CImageDecoder::IsImageHeaderProcessingComplete().

    panic
    ImageConversion 10 aFrameNumber is not valid. See CImageDecoder::FrameCount().
    panic
    ImageConversion 13 Header processing has not completed. See CImageDecoder::IsImageHeaderProcessingComplete().

    See also: IsImageHeaderProcessingComplete() FrameCount()

    ParameterDescription
    aFrameNumberThe frame number.

    Returns: The number of comments attached to a given frame of the image.

    NumberOfImageComments ( )

    IMPORT_C TIntNumberOfImageComments()const

    Return the number of comments attached to the image (as opposed to a particular frame).

    For further informantion on panic categories, please see the note in CImageDecoder::IsImageHeaderProcessingComplete().

    panic
    ImageConversion 13 Header processing has not completed. See CImageDecoder::IsImageHeaderProcessingComplete().

    See also: IsImageHeaderProcessingComplete()

    Returns: The number of comments attached to the image.

    OperationL ( )

    IMPORT_C TImageConvOperation *OperationL()
    Get the extension interface for operations on the image.
    leave
    KErrNotSupported if loaded codec plugin does not support this optional extension.
    leave
    Other system wide errors
    Note:

    The order of post processing operations when applied for decoding is

    • 1. Clip the image

    • 2. Scale the image

    • 3. Operate on the image

    See also: CImageDecoder::SetClippingRectL() TImageConvScaler TImageConvOperation

    Returns: Interface to image conversion operations.

    Plugin ( )

    IMPORT_C CImageDecoderPlugin *Plugin()const [protected]

    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.

    Returns: A pointer to the related CImageDecoderPlugin instance.

    Prepare ( TRequestStatus * )

    IMPORT_C voidPrepare(TRequestStatus *aRequestStatus)

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

    Should be called once decode is fully set up e.g. clipping rectangle set.

    See also: CImageDecoder::Convert

    ParameterDescription
    aRequestStatusRequest status. On completion this contains an error code. This is KErrNone if the frame was analyzed successfully, KErrNotSupported if the codec does not support analysis, or a system-wide error code.

    ReducedSize ( const TSize &, TInt, TSize & )

    IMPORT_C TIntReducedSize(const TSize &aOriginalSize,
    TIntaReductionFactor,
    TSize &aReducedSize
    )const

    Calculates reduced size of the decoded bitmap based on the input parameters and updates aReducedSize with this value.

    ParameterDescription
    aOriginalSizeA reference to the original size of an image.
    aReductionFactorThe Reduction Factor to be applied
    aReducedSizeA reference to the new size of the image.

    Returns: An error code indicating if the function call was successful. KErrNone on success, otherwise KErrArgument.

    ReductionFactor ( const TSize &, const TSize & )

    IMPORT_C TIntReductionFactor(const TSize &aOriginalSize,
    const TSize &aReducedSize
    )const

    Function to calculate the reduction factor based on the input parameters.

    ParameterDescription
    aOriginalSizeA reference to the original size of an image.
    aReducedSizeA reference to the new size of an image.

    Returns: The reduction factor.

    ScalerL ( )

    IMPORT_C TImageConvScaler *ScalerL()

    Get the extension interface for scaling the image.

    See also: TImageConvScaler

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

    See also: note under CImageDecoder::OperationL.

    Returns: Interface to image conversion scaler.

    SetAgentProperty ( ContentAccess::TAgentProperty, TInt )

    IMPORT_C TIntSetAgentProperty(ContentAccess::TAgentPropertyaProperty,
    TIntaValue
    )

    Sets the properties for the Image decoder.

    ParameterDescription
    aPropertyThe property to set.
    aValueThe value of the property.

    Returns: KErrNone if successful, otherwise one of the system-wide errors.

    SetClippingRectL ( const TRect * )

    IMPORT_C voidSetClippingRectL(const TRect *aClipRect)

    Sets the area of interest of the image to be decoded. This function can leave with any of the system-wide error codes.

    leave
    KErrNotSupported This function is not supported.
    leave
    KErrArgument Returned if the clipping rectangle: a) is empty (i.e. IsEmpty() returns ETrue) b) is not normalised (i.e. IsNormalized() returns EFalse) c) has coordinates that are not located within, or on, the coodinates of at least one frame of the original image. d) has a width or a height of 0

    See also: TRect::IsEmpty() TRect::IsNormalized() TRect::Normalize()note under CImageDecoder::OperationL

    ParameterDescription
    aClipRectA pointer to a TRect that specifies the location and size of the region to be decoded. This rectangle must have positive width and height values as per TRect::IsNormalized() and TRect::Normalize(). Passing in a NULL value will clear the clipping rectangle. Note that a clipping rectangle may not be valid for all frames of an image.

    SetDecoderThreadPriority ( TThreadPriority )

    IMPORT_C TIntSetDecoderThreadPriority(TThreadPriorityaPriority)

    Set the decoder worker thread priority

    See also: TThreadPriority

    ParameterDescription
    aPrioritya new value for worker thread priority

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

    SetImageTypeL ( TInt )

    IMPORT_C voidSetImageTypeL(TIntaImageType)

    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.

    leave
    KErrNotFound If the image for the type specified is not found.
    leave
    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.
    ParameterDescription
    aImageTypeAn image type from TImageType to denote source image that the decoder should use.