#include <icl/imageplugin.h>
class CImageDecoderPlugin : public CBase |
Public Member Functions | |
---|---|
~CImageDecoderPlugin() | |
virtual IMPORT_C HBufC * | FrameCommentL(TInt, TInt) |
virtual IMPORT_C TInt | GetDestinationSize(TSize &, TInt) |
virtual IMPORT_C void | GetExtensionL(TUid, MImageConvExtension *&) |
virtual IMPORT_C HBufC * | ImageCommentL(TInt) |
pure virtual void | ImageType(TInt, TUid &, TUid &) |
virtual IMPORT_C TInt | NumberOfFrameComments(TInt) |
virtual IMPORT_C TInt | NumberOfImageComments() |
virtual IMPORT_C void | SetClippingRectL(const TRect *) |
The PluginAPI for Image Converter Library decoder plugins.
Intended for use by plugin writers only.
IMPORT_C TBool | AmInThread | ( | ) | const [protected] |
Indicates if this decoder is running in a separate thread.
IMPORT_C TInt | AppendImageData | ( | const TImageDataBlock * | aEntry | ) | [protected] |
Appends a new image data data block to the end of the internally held array.
Parameters | |
---|---|
aEntry | The image data block to be appended. |
Appends a new image data buffer to the end of the internally held array
Parameters | |
---|---|
aImageBuffer | The data buffer to append. |
IMPORT_C void | Cleanup | ( | ) | [protected, virtual] |
Called when the plugin is destroyed or a decode is cancelled. This may be overriden in derived classes.
Note: Derived classes must call this version after performing any plugin specific cleanup.
IMPORT_C TInt | DataLength | ( | ) | const [protected] |
Returns the maximum number of bytes of data that can be decoded.
IMPORT_C CImageDecoder::TOptions | DecoderOptions | ( | ) | const [protected] |
Returns the decoding options specified by the client when it created the CImageDecoder object.
IMPORT_C const CFbsBitmap & | Destination | ( | ) | const [protected] |
Returns the destination bitmap.
IMPORT_C const CFbsBitmap & | DestinationMask | ( | ) | const [protected] |
Returns the destination bitmap mask.
IMPORT_C void | DoConvert | ( | ) | [protected, virtual] |
Performs a decode step. This effectively forms the RunL() call of the decoder.
This call may be overriden in derived classes. However, if this the case, then if the custom decode is not performed and the derived class should either ensure that this base class's version is called or should completely replace the base class's version calling PrepareForProcessFrameL(), ProcessFrameL() and HandleProcessFrameResult() as appropriate. Unlike the standard version, an override instance may choose to spread these calls over several RunL() instances.
Returns the block size used in the specified frame. Always returns 4096 regardless of the frame number specified. Should be overriden by codecs that use larger blocks.
Parameters | |
---|---|
aFrameNumber | The frame to which the block size information applies. |
Returns a particular comment attatched to a given frame of the image.
Ownership of the returned buffer is transferred to the caller.
Parameters | |
---|---|
aFrameNumber | The index of the frame containing the comments. |
aCommentNumber | The index of the comment to retrieve from the specified frame. |
IMPORT_C const CFrameImageData & | FrameData | ( | TInt | aFrameNumber = 0 | ) | const [protected] |
Returns the frame data for a specified frame of the image.
Parameters | |
---|---|
aFrameNumber | The frame number from which to retreive the frame data (Optional, defaults to 0). |
Returns the block size used in the specified frame's header. Always returns 4096 regardless of the frame number specified. Should be overriden by codecs that use larger blocks.
Parameters | |
---|---|
aFrameNumber | The frame to which the header block size information applies. |
IMPORT_C const TFrameInfo & | FrameInfo | ( | TInt | aFrameNumber = 0 | ) | const [protected] |
Returns 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 decoding it.
Parameters | |
---|---|
aFrameNumber | The frame number for which information is requested (Optional, defaults to 0). |
IMPORT_C CFrameInfoStrings * | FrameInfoStringsL | ( | RFs & | aFs, |
TInt | aFrameNumber = 0 | |||
) | [protected, pure virtual] |
Returns the codec specific frame information stored in resource files.
This is a virtual function that each individual plugin must implement.
Parameters | |
---|---|
aFs | A handle to a file server session. |
aFrameNumber | The frame number to which the codec specific frame information applies (optional, defaults to zero). |
Called by framework on plugin to get the size of decoded image.
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.
Gets the size of the destination CFbsBitmap needed prior to a call to Convert(). Essential when using the ICL Framework Extensions such as SetClippingRectL() or codec extensions obtained through the OperationL(), ScalerL() and BlockStreamerL() calls.
See also: CImageDecoder::OperationL() CImageDecoder::ScalerL() CImageDecoder::BlockStreamerL() CImageDecoder::SetClippingRectL() CImageDecoder::Convert()
Parameters | |
---|---|
aSize | A reference to a TSize that specifies the size of the region that is to be decoded by a call to Convert(). |
aFrameNumber | The number of the frame that is to be decoded. |
IMPORT_C void | GetExtensionL | ( | TUid | aExtUid, |
MImageConvExtension *& | aExtPtr | |||
) | [virtual] |
Called by the framework to obtain a pointer to a codec implemented extension.
See also: icl_uids.hrh .
Parameters | |
---|---|
aExtUid | Extension UID normally prefixed KUidImageConv. |
aExtPtr | Returns a ptr to the extension implemented by the codec plugin. |
IMPORT_C void | HandleCustomSyncL | ( | TInt | aParam | ) | [protected, virtual] |
Called as a result of an associated CImageDecoder::CustomSyncL() function being called. Plugins may override this to provide extended commands in CImageDecoder. Default version leaves with KErrNotSupported.
Parameters | |
---|---|
aParam | Interpretation dependent on plugin. |
IMPORT_C void | HandleProcessFrameResult | ( | TInt | aErrCode, |
TFrameState | aCodecState | |||
) | [protected] |
Deals with result from ProcessFrameL(). This function processes the results of the standard ProcessFrameL() call, feeding in the resultant error code from its TRAP and the status result. It will call RequestComplete() or SelfComplete() as appropriate.
Note that if no data was consumed by ProcessFrameL(), HandleProcessFrameResult() assumes that it requires more data and calls RequestComplete(KErrUnderflow). If this is not appropriate, an overloaded DoConvert() should be made to handle it.
Parameters | |
---|---|
aErrCode | The error result of TRAP arround ProcessFrameL(). |
aCodecState | The result of ProcessFrameL() itself. |
IMPORT_C const TImageDataBlock * | ImageData | ( | TInt | aIndex | ) | const [protected] |
Returns the image data block for the specified index.
Parameters | |
---|---|
aIndex | The index of the image data block to return. |
IMPORT_C TInt | ImageDataCount | ( | ) | const [protected] |
Returns the number of image data blocks present in the image data.
IMPORT_C const TFrameInfo & | ImageInfo | ( | ) | const [protected] |
Returns image information such as colour depth, scaling support etc.
IMPORT_C CImageReadCodec * | ImageReadCodec | ( | ) | const [protected] |
Returns the plugin's read codec.
Returns the image type and sub-type for a given frame of the image that has just been opened.
This is a virtual function that each individual plugin must implement.
Parameters | |
---|---|
aFrameNumber | The frame index for type and sub-type information should be returned. |
aImageType | On return contains the image type UID for the specified frame. |
aImageSubType | On return contains the image sub-type UID for the specified frame. If the sub-type does not exist KNullUid is returned. |
IMPORT_C void | InitConvertL | ( | ) | [protected, virtual] |
Initialises data structures prior to decoding a frame.
This function may be overriden in derived classes. Any override should also call this version after performing any plugin initialistion.
IMPORT_C void | InitCustomAsyncL | ( | TInt | aParam | ) | [protected, virtual] |
Called as a result of the associated CImageDecoder::CustomAsync() function being called.
If this function finishes normally, then a convert cycle is started - so that DoConvert() will be subsequently started in the background - otherwise, if this function leaves then the error result is immediately signalled back to the caller of CustomAsync().
Plugins may override this to provide extended commands in CImageDecoder.Users of CImageEncoder can then use the extended encoder functions by calling CustomAsync, rather than CImageEncoder::Convert().
By default this function leaves with KErrNotSupported unless overriden.
Parameters | |
---|---|
aParam | Interpretation dependent on plugin. |
IMPORT_C TInt | InsertImageData | ( | const TImageDataBlock * | aEntry, |
TInt | aPos | |||
) | [protected] |
Inserts an image data block into the internally held array at the specified position.
Parameters | |
---|---|
aEntry | Pointer to the image data block to be inserted. |
aPos | The position within the arrary to insert the data block. |
IMPORT_C TBool | IsImageHeaderProcessingComplete | ( | ) | const [protected] |
Returns the status of header processing. If the processing is incomplete or not terminated correctly EFalse will be returned
IMPORT_C void | NotifyComplete | ( | ) | [protected, virtual] |
Plugin defined actions resulting from a call by RequestComplete().
This function is called when a RequestComplete() is issued indicating that an asynchronous command has finished. Plugins can extend this function to, clear any custom command flags.
Returns the number of comments attatched to a given frame of the image.
Use NumberOfImageComments() for the image equivalent.
Parameters | |
---|---|
aFrameNumber | The frame number. |
IMPORT_C TInt | NumberOfFrames | ( | ) | const [protected] |
Returns the number of frames to be decoded.
IMPORT_C TInt | NumberOfImageComments | ( | ) | const [virtual] |
Returns the number of comments attatched to the image.
Some image formats allow comments to be attached to the entire image, others allow comments to be attached to individual frames within the image. Use this function to retrieve the number of comments in the image. Use NumberOfFrameComments() for the frame equivalent.
IMPORT_C void | OpenExtraResourceFileLC | ( | RFs & | aFs, |
const TUid | aUid, | |||
RResourceFile & | aResourceFile | |||
) | const [protected] |
Locates the extra resource file for the decoder aUid_extra.rsc, opens the resource file and pushes it on the cleanup stack.
If the resource file is not found the method leaves with KErrNotFound. If more than one resource file is found, only the first one is opened.
Parameters | |
---|---|
aFs | A reference to the file server. |
aUid | The decoder's UID. |
aResourceFile | A reference to the opened resource file. |
IMPORT_C TInt | Position | ( | ) | const [protected] |
Returns the current position within the data.
IMPORT_C void | PrepareForProcessFrameL | ( | ) | [protected] |
Initialises system for ProcessFrameL(). This reads in a new buffer for ProcessFrameL().
Reads a block of data into an internal buffer.
A block of data of size aLength is read from the position specified by aPosition to an internal data buffer. After a successful read, aReadBuffer is set to point to the internal buffer.
If an attempt is made to read past the end of data, all available data is read and the descriptors length will indicate the actual number of bytes read.
Parameters | |
---|---|
aPosition | The start position from where data will be read. |
aReadBuffer | Upon completion of a successful call, points to the internal buffer containing the data read from the source. |
aLength | The size in bytes of the block of data to be read. |
IMPORT_C void | ReadFrameHeadersL | ( | ) | [protected, virtual] |
Invokes the ReadFrameHeadersL method of the supplied plugin which should process the frame headers contained within the image.
IMPORT_C void | RemoveImageData | ( | TInt | aPos | ) | [protected] |
Removes a specified image data block from the internally held array.
Parameters | |
---|---|
aPos | The index of the image data block to be removed. |
IMPORT_C void | RequestComplete | ( | TInt | aReason | ) | [protected] |
Must be called on completion of decoding the image data.
Parameters | |
---|---|
aReason | KErrNone should be returned if the decoding completes successfully. If the request fails an appropriate error code should be returned. |
IMPORT_C void | RequestInitL | ( | TInt | aFrameNumber | ) | [protected] |
Forces initialization of data structures prior to decoding a frame.
Parameters | |
---|---|
aFrameNumber | The frame in a multi-frame image to decode. |
void | ScanDataL | ( | ) | [protected, pure virtual] |
Invokes the ReadFrameHeadersL() method of the supplied plugin.
The plugin's version of ReadFrameHeadersL() should read the image header information, create the required codec and read the frame headers.
This is a virtual function that each individual plugin must implement.
IMPORT_C void | SelfComplete | ( | TInt | aReason | ) | [protected] |
Must be called at the end of a slice of decoding.
If successful specify KErrNone that results in a repeat call to DoConvert().
See also: CImageDecoderPlugin::RequestComplete(TInt aReason)
Parameters | |
---|---|
aReason | The error code giving the reason for completion, or KErrNone if no error occurred. |
IMPORT_C void | SetClippingRectL | ( | const TRect * | aClipRect | ) | [virtual] |
Called by the framework on the plugin to apply a clipping rectangle to the image.
Sets the area of interest of the image to be decoded.
See also: TRect::IsEmpty() TRect::IsNormalized() TRect::Normalize()
Parameters | |
---|---|
aClipRect | A 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. |
Leave Codes | |
---|---|
KErrNotSupported | if clipping is not supported by the codec plugin. |
Other | system-wide error codes. |
KErrNotSupported | This function is not supported. |
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 |
IMPORT_C void | SetDataLength | ( | TInt | aDataLength | ) | [protected] |
Sets the maximum number of bytes of data that can be decoded.
Parameters | |
---|---|
aDataLength | The maximum number of bytes of data. |
IMPORT_C void | SetImageInfo | ( | const TFrameInfo & | aImageInfo | ) | [protected] |
Sets the image information.
Parameters | |
---|---|
aImageInfo | The image information. |
IMPORT_C void | SetImageReadCodec | ( | CImageReadCodec * | aImageReadCodec | ) | [protected] |
Sets the plugin's read codec. Ownership of the codec is transferred to the plugin.
Parameters | |
---|---|
aImageReadCodec | Pointer to the codec. |
IMPORT_C void | SetPosition | ( | const TInt | aPosition | ) | [protected] |
Sets the current position in the data.
Parameters | |
---|---|
aPosition | The current position in the data. |
IMPORT_C void | SetSelfPending | ( | ) | [protected] |
May be called at the start of a slice of decoding if the decoding is expected to complete asynchronously. This sets the AO in CImageDecoderPriv to active, but does not complete the request.
When decoding of the slice is complete, there must be a call to SelfComplete().
IMPORT_C void | SetStartPosition | ( | TInt | aDataLength | ) | [protected] |
Sets the starting position of the frame to be decoded.
Parameters | |
---|---|
aDataLength | The starting position in the data. |
IMPORT_C void | SetThumbnailData | ( | HBufC8 * | aThumbnailData | ) | [protected] |
Passes a pointer to a descriptor containing the thumbnail from the plugin to the framework. The framework then owns this descriptor.
Parameters | |
---|---|
aThumbnailData | A pointer to a HBufC8 containing the thumbnail data |
IMPORT_C TBool | ShouldAbort | ( | ) | const [protected] |
Indicates if the decoder should abort early ie. following a call to Cancel().
Note: This function always returns false unless the decoder is running in its own thread.
IMPORT_C TBufPtr8 & | SourceData | ( | ) | [protected] |
Value to be fed to CImageReadCodec::ProcessFrameL().
This value is setup by PrepareForProcessFrameL() - it returns the value that will be fed to CImageReadCodec::ProcessFrameL(), and will be used by codecs that fully override DoConvert().
IMPORT_C TInt | SourceLength | ( | ) | const [protected] |
Returns the length of the source data in bytes.
IMPORT_C TInt | StartPosition | ( | ) | const [protected] |
Returns the starting position of the frame to be decoded.
IMPORT_C TBool | ValidDestination | ( | ) | const [protected] |
Returns the validity of the destination bitmap.
IMPORT_C TBool | ValidDestinationMask | ( | ) | const [protected] |
Indicates if the destination bitmap mask is valid.