diff -r 000000000000 -r 5752a19fdefe imaging/imagingfws/inc_pub/icl/imageconversionextension.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/imaging/imagingfws/inc_pub/icl/imageconversionextension.h Wed Aug 25 12:29:52 2010 +0300 @@ -0,0 +1,641 @@ +// Copyright (c) 2007-2009 Nokia Corporation and/or its subsidiary(-ies). +// All rights reserved. +// This component and the accompanying materials are made available +// under the terms of "Eclipse Public License v1.0" +// which accompanies this distribution, and is available +// at the URL "http://www.eclipse.org/legal/epl-v10.html". +// +// Initial Contributors: +// Nokia Corporation - initial contribution. +// +// Contributors: +// +// Description: +// + +#ifndef IMAGECONVERSIONEXTENSION_H +#define IMAGECONVERSIONEXTENSION_H + +#include +class MImageConvExtension; +class MImageConvOperation; +class MImageConvScaler; +class MImageConvStreamedDecode; +class MImageConvStreamedEncode; +class TFrameLayout; +class CImageFrame; +class CFrameImageData; + +/** +@file +@publishedAll +@released +*/ + +/** + Image Conversion Library extensions. When applied together there is an implicit order for operations: + 1. Crop or clip. + 2. Scale + 3. Rotate / mirror over axis. + */ + +/** +Operation extension for Image Conversion Library. Allows rotation and mirror over axis. +*/ +class TImageConvOperation + { +friend class CImageDecoder; +friend class CImageEncoder; + +public: + + + /** + Operations or transforms on an image. + */ + enum TOperation + { + /** Rotate source 90 degrees clockwise. + */ + ERotation90DegreesClockwise = 0x01, + /** Rotate source 180 degrees clockwise. + */ + ERotation180DegreesClockwise = 0x02, + /** Rotate source 270 degrees clockwise. + */ + ERotation270DegreesClockwise = 0x04, + /** Mirror source about the horizontal axis. + */ + EMirrorHorizontalAxis = 0x08, + /** Mirror source about the vertical axis. + */ + EMirrorVerticalAxis = 0x10 + }; + + /** + Get the codec plugin's capabilities. + + @return Bitmask combination of TOperation. Bit is set if decoder plugin supports the operation. + */ + IMPORT_C TUint Capabilities() const; + + /** + Set up an operation be applied to the source. May be called more than once + to set up a stack of operations, but it is not possible to add more than one + operation in a single call. + The operations are applied to the image in the same order as they are added. + + @param aOperation The operation to add to the current stack of operations. + + @leave if more than one TOperation enum is passed for each individual call + */ + IMPORT_C void AddOperationL(TOperation aOperation); + + /** + Remove all operations previously set. + */ + IMPORT_C void ClearOperationStack(); + +private: + + IMPORT_C TImageConvOperation(); + void SetExtension(MImageConvExtension* aExtension); + +private: + MImageConvOperation* iExtension; + TInt iReserved; // future proof + }; + + +/** +Represents scaling capabilities of the code plugin. +*/ +class TScalerCaps + { +public: + /** + Constructor + */ + IMPORT_C TScalerCaps(); + + /** + Constructor + + @param aMaxUpscaleLimit Maximum upscaling possible. + @param aMaxDownscaleLimit Maximum downscaling possible. + @param aPreserveAspectRatioIsNeeded ETrue if only support preservation of aspect ratio. + */ + IMPORT_C TScalerCaps(TInt aMaxUpscaleLimit,TInt aMaxDownscaleLimit,TBool aPreserveAspectRatioIsNeeded); + + /** + Maximum upscaling possible. + @return value >= 1 : 1 means cannot upscale, 2 means twice original size + */ + IMPORT_C TInt MaxUpscaleLimit() const; + + /** + Maximum downscaling possible. + @return value <= -1 : -1 means cannot downscale, -2 means half original size + */ + IMPORT_C TInt MaxDownscaleLimit() const; + + /** + Type of scaling which is supported. + + @return ETrue if can only do 1/2, 1/4, 1/8 etc downscale (limit depends on iMaxDownscaleLimit) + 2, 4, 8 etc upscale (limit depends on iMaxUpscaleLimit) + EFalse if can do arbitrary scaling between iMaxDownscaleLimit and iMaxUpscaleLimit + */ + IMPORT_C TBool PowerOfTwoScalingOnly() const; + + /** + Returns ETrue if the codec must preserve aspect ratio during scaling. + + @return ETrue if scaling is only possible if preservation of aspect ratio is requested. + EFalse if scaling without preserving aspect ratio is possible. + */ + IMPORT_C TBool MustPreserveAspectRatio() const; + + /** + Compatibility - internal use only + @internalComponent + */ + IMPORT_C TUint Size() const; + + /** + Compatibility - internal use only + @internalComponent + */ + IMPORT_C TUint Version() const; + +private: + TInt iMaxUpscaleLimit; // >= 1 : 2 means twice original size + TBool iMustPreserveAspectRatio; // If ETrue then can only do scaling whilst preserving aspect ratio + TInt iMaxDownscaleLimit; // <= -1 : -2 means 1/2 original size + TBool iPowerOfTwoScalingOnly; + TUint iSizeVersion; // bits 31 to 8 size, 7 to 0 contain version + TInt iReserved; // future proof + }; + + +/** +Scaling extension for Image Conversion Library. Supports both arbitrary or 'power of two' 1/2, 1/4, 1/8 scaling +*/ +class TImageConvScaler + { +friend class CImageDecoder; + +public: + + /** + Quality used during scaling. + */ + enum TScalerQuality + { + EMinimumQuality, // = 0 + EMediumQuality, + EMaximumQuality + }; + + /** + Get the codec plugin's capabilities. + + @param aCaps Returns scaling capabilities of the codec plugin. + */ + IMPORT_C void GetCapabilities(TScalerCaps& aCaps) const; + + /** + Request scaling to the desired size using the quality specified and specifying if the aspect ratio is to + be preserved. + Ensure that CImageDecoder::GetDestinationSize is used to obtain the size of destination bitmap passed + to CImageDecoder::Convert if scaling is set up by calling this method. + + @param aDesiredSize Proposed size of the scaled image. Note that this may not necessarily be the size + returned by a subsequent call to CImageDecoder::GetDestinationSize and is dependant upon the operations + (such as scaling, cropping and rotation) requested and also the capabilities of the plugin (which can be + queried using TImageConvScaler::GetCapabilities). + + Example: If a plugin is only capable of power of two scaling, with an original image size of 600x400, + then calling this SetScalingL function with a desired size of 500x300 will result in a subsequent call to + CImageDecoder::GetDestinationSize returning a size of 300x200 (that is, a scaling coefficient of -2). + + @param aQuality Desired quality of the image. Allows codec to lower quality targets to + improve performance. + + @param aLockAspectRatio Set to ETrue if the aspect ratio of the original image is to be preserved. + + @leave KErrNotSupported if an invalid size is passed. + @leave KErrNotSupported if aLockAspectRatio is EFalse and codec only supports preservation of aspect ratio. + + @see CImageDecoder::Convert + @see CImageDecoder::GetDestinationSize + @see TImageConvScaler::GetCapabilities + */ + IMPORT_C void SetScalingL(const TSize& aDesiredSize, TImageConvScaler::TScalerQuality aQuality, TBool aLockAspectRatio); + + /** + Define the scaling to be applied to the image according to the given coefficient at the requested quality. + Ensure that CImageDecoder::GetDestinationSize is used to obtain the size of destination bitmap to be passed + to CImageDecoder::Convert. + + @param aScalingCoeff Scale to apply to the source. 2 means twice the original size, -2 half the size. + Do not confuse this with ReductionFactor where 2 indicates 1/2 size. + + @param aScalingQuality Desired quality of the image. Allows codec to lower quality targets to + improve performance. + + @leave KErrNotSupported if codec cannot perform the requested scale. + + @see CImageDecoder::Convert + */ + IMPORT_C void SetScalingL(TInt aScalingCoeff, TImageConvScaler::TScalerQuality aScalingQuality); + +private: + IMPORT_C TImageConvScaler(); + void SetExtension(MImageConvExtension* aExtension); + +private: + MImageConvScaler* iExtension; + TInt iReserved; // future proof + }; + +/** +'Block' streaming extension capabilities. +*/ +class TDecodeStreamCaps + { +public: + /** Navigation possibilities within stream. + */ + enum TNavigation + { + /** Blocks are returned from first to last */ + ENavigationSequentialForward = 0x01, + + /** Blocks are returned in a random order but moving only from first to last e.g. 1, 5, 18...*/ + ENavigationRandomForward = 0x02, + + /** Blocks are returned in a random order but moving only from last to first e.g. 18, 5, 1...*/ + ENavigationRandomBackwards = 0x04, + + /** Blocks are returned randomly e.g. 18, 5, 20, ...*/ + ENavigationRandom = 0x08, + + /** Blocks are returned from last to first */ + ENavigationSequentialBackwards = 0x10 + }; + + /** + Constructor. + */ + IMPORT_C TDecodeStreamCaps(); + + /** + Constructor. + + @param aMaxBlocksPerRequest Maximum number of blocks that can be returned from the stream to client in a + single request. + @param aMinBlockSizeInPixels Minimum size in pixels of a block returned from the stream to the client in + a single request. + @param aOptimalBlocksPerRequest Optimum number of blocks returned from the stream to the client in + a single request to get maximum performance benefit. + @param aStreamSizeInBlocks Number of blocks of size MinBlockSizeInPixels() in the stream. + @param aNavigation Navigation capabilities. + */ + IMPORT_C TDecodeStreamCaps(TInt aMaxBlocksPerRequest, const TSize& aMinBlockSizeInPixels, + TInt aOptimalBlocksPerRequest, TInt aStreamSizeInBlocks, + TDecodeStreamCaps::TNavigation aNavigation); + + /** + The maximum number of blocks that can be returned from the stream to client in a + single request. + + @return Maximum number of blocks that can be returned from the stream to client in a + single request. + */ + IMPORT_C TInt MaxBlocksPerRequest() const; + + /** + The Minimum size in pixels of a block returned from the stream to the client in + a single request. + + @return Minimum size in pixels of a block returned from the stream to the client in + a single request. Sequence numbers and StreamSizeInBlocks() refer to this size of block. + */ + IMPORT_C const TSize& MinBlockSizeInPixels() const; + + /** + Optimum number of blocks returned from the stream to the client in + a single request to get maximum performance benefit. + + @return Optimum number of blocks returned from the stream to the client in + a single request to get maximum performance benefit. + This can be used to determine the optimum value of the number of blocks of min block size per request. + */ + IMPORT_C TInt OptimalBlocksPerRequest() const; + + /** + Number of blocks of size MinBlockSizeInPixels() in the stream. + + @return Number of blocks of size MinBlockSizeInPixels() in the stream. + */ + IMPORT_C TInt StreamSizeInBlocks() const; + + /** + Navigation capabilities. + + @return Navigation capabilities. + + Full random access to the stream if Navigation() returns + ENavigationSequentialForward | ENavigationRandomForward | ENavigationRandomBackwards + */ + IMPORT_C TDecodeStreamCaps::TNavigation Navigation() const; + + /** + Compatibility - internal use only + @internalComponent + */ + IMPORT_C TUint Size() const; + + /** + Compatibility - internal use only + @internalComponent + */ + IMPORT_C TUint Version() const; + +private: + TInt iMaxBlocksPerRequest; + TSize iMinBlockSizeInPixels; + TInt iOptimalBlocksPerRequest; + TInt iStreamSizeInBlocks; + TNavigation iNavigation; + TUint iSizeVersion; // bits 31 to 8 size, 7 to 0 contain version + TInt iReserved; // future proof + }; + +/** + 'Block' streaming extension for Image Conversion Library decoder. + */ +class TImageConvStreamedDecode + { +friend class CImageDecoder; + +public: + /** + Returns a list of supported formats and the optimal format to be used. @see imageframeconst.h + for a list of format uids. + @param aFormats Returns an array of format uids + @param aOptimalFormat The 'best' uid to use. + */ + IMPORT_C void GetSupportedFormatsL(RArray& aFormats, TUid& aOptimalFormat) const; + + /** + Returns the capabilities of the codec plugin for a specific format and for a specific frame. + @param aFormat The format. + @param aFrameNumber frame to stream + @param aCaps The capabilities for the format given. + */ + IMPORT_C void GetCapabilities(TUid aFormat, TInt aFrameNumber, TDecodeStreamCaps& aCaps) const; + + /** + Get the size of the memory buffer to hold the returned data. + + @param aFormat the required format + @param aBlockSizeInPixels returns the size in pixels of the block returned from the stream when aNumBlocks of minimum block size are requested. + @param aNumBlocks the number of blocks of size TDecodeStreamCaps::MinBlockSizeInPixels() to be returned by one request + + @return The memory buffer size in bytes to hold the requested blocks. System wide error if for example + the format is not supported. + */ + IMPORT_C TInt GetBufferSize(TUid aFormat, TSize& aBlockSizeInPixels, TInt aNumBlocks) const; + + + /** + Initialise the stream. + + @param aFormat the format to use + @param aFrameNumber frame to stream + @param aNavigation indication to stream of the way that the stream will be navigated. Allows + codec to optimise it's behaviour. + @leave System wide error if for example the format is not supported. + + @note must call InitFrameL before GetBlocks or GetNextBlocks. Failure to do so completes request with + KErrNotReady + */ + IMPORT_C void InitFrameL(TUid aFormat, TInt aFrameNumber, TDecodeStreamCaps::TNavigation aNavigation); + + /** + Start asynchronous call to return random blocks from the stream + + @param aStatus request status + @param aFrame An image frame wrapper a memory buffer to hold the returned block(s) of + pixel data. This can be 'uninitialised' or given specific format which must match that + specified in the InitFrameL call. + @param aSeqPosition block number starting at top left 0 ... TDecodeStreamCaps::StreamSizeInBlocks() + @param aNumBlocksToGet number of blocks requested + @param aNumBlocksRead number of blocks which will be returned when the request completes + + @note use CImageDecoder::Cancel() to cancel this request. + */ + IMPORT_C void GetBlocks(TRequestStatus& aStatus, CImageFrame& aFrame, TInt aSeqPosition, TInt aNumBlocksToGet, TInt& aNumBlocksRead); + + /** + Start asynchronous call to return blocks sequentially from the stream. Blocks are returned + from the first block until the last in the stream. + + @param aStatus request status + @param aFrame An image frame wrapper a memory buffer to hold the returned block(s) of + pixel data. This can be 'uninitialised' or given specific format which must match that + specified in the InitFrameL call. + @param aNumBlocksToGet number of blocks requested + @param aNumBlocksRead number of blocks which will be returned when the request completes + + @note use CImageDecoder::Cancel() to cancel this request. + */ + IMPORT_C void GetNextBlocks(TRequestStatus& aStatus, CImageFrame& aFrame, TInt aNumBlocksToGet, TInt& aNumBlocksRead, TBool& aHaveMoreBlocks); + +private: + IMPORT_C TImageConvStreamedDecode(); + void SetExtension(MImageConvExtension* aExtension); + +private: + MImageConvStreamedDecode* iExtension; + TInt iReserved; // future proof + }; + +/** + 'Block' streaming extension for Image Conversion Library encoder. + */ +/** + 'Block' streaming extension for Image Conversion Library encoder. + */ +class TEncodeStreamCaps + { +public: + /** Navigation possibilities within the stream. + */ + enum TNavigation + { + /** Blocks can be returned from first to last */ + ENavigationSequentialForward = 0x01, + + /** Blocks can be returned in a random order but moving only from first to last e.g. 1, 5, 18...*/ + ENavigationRandomForward = 0x02, + + /** Blocks can be returned in a random order but moving only from last to first e.g. 1, 5, 18...*/ + ENavigationRandomBackwards = 0x04 + }; + + /** + Constructor. + */ + IMPORT_C TEncodeStreamCaps(); + + /** + Constructor. + + @param aMaxBlocksPerRequest Maximum number of blocks that can be sent from the stream to client in a + single request. + @param aMinBlockSizeInPixels Minimum size in pixels of a block sent to the stream from the client in + a single request. + @param aOptimalBlocksPerRequest Optimum number of blocks sent to the stream from the client in + a single request to get maximum performance benefit. + @param aNavigation Navigation capabilities. + */ + IMPORT_C TEncodeStreamCaps(TInt aMaxBlocksPerRequest, const TSize& aMinBlockSizeInPixels, + TInt aOptimalBlocksPerRequest, + TEncodeStreamCaps::TNavigation aNavigation); + /** + Maximum number of blocks that can be sent from the stream to client in a + single request. + + @return Maximum number of blocks that can be sent from the stream to client in a + single request. + */ + IMPORT_C TInt MaxBlocksPerRequest() const; + + /** + Minimum size in pixels of a block sent to the stream from the client in + a single request. + + @return Minimum size in pixels of a block sent to the stream from the client in + a single request. + */ + IMPORT_C const TSize& MinBlockSizeInPixels() const; + + /** + Optimum number of blocks sent to the stream from the client in + a single request to get maximum performance benefit. + + @return Optimum number of blocks sent to the stream from the client in + a single request to get maximum performance benefit. + */ + IMPORT_C TInt OptimalBlocksPerRequest() const; + + + /** + Navigation capabilities. + + @return navigation capabilities. + + Full random access to the stream if Navigation() returns + ENavigationSequentialForward | ENavigationRandomForward |ENavigationRandomBackwards + */ + IMPORT_C TEncodeStreamCaps::TNavigation Navigation() const; + + /** + Compatibility - internal use only + @internalComponent + */ + IMPORT_C TUint Size() const; + + /** + Compatibility - internal use only + @internalComponent + */ + IMPORT_C TUint Version() const; + +private: + TInt iMaxBlocksPerRequest; + TSize iMinBlockSizeInPixels; + TInt iOptimalBlocksPerRequest; + TNavigation iNavigation; + TUint iSizeVersion; // bits 31 to 8 size, 7 to 0 contain version + TInt iReserved; // future proof + }; + +class TImageConvStreamedEncode + { +friend class CImageEncoder; + +public: + /** + Returns a list of supported formats and the optimal format to be used. @see imageframeconst.h + for a list of format uids. + @param aFormats Returns an array of format uids + @param aOptimalFormat The 'best' uid to use. + */ + IMPORT_C void GetSupportedFormatsL(RArray& aFormats, TUid& aOptimalFormat) const; + + /** + Returns the capabilities of the codec plugin for a specific format. + @param aFormat The format. + @param aCaps The capabilities for the format given. + */ + IMPORT_C void GetCapabilities(TUid aFormat, TEncodeStreamCaps& aCaps) const; + + /** + Initialise the stream. + + @param aFormat the format to use + @param aFrameNumber frame to stream + @param aFrameSizeInPixels Size of this frame in pixels + @param aBlockSizeInPixels Size of block to be added / appended. + @param aNavigation indication to stream of the way that the stream will be navigated. Allows + codec to optimise it's behaviour. + @param aFrameImageData The frame image data (optional pass NULL if not required). + There are format-specific image data variants that are used by encoders to obtain image specific + data. This behaviour is invoked by specifying aFrameImageData. Otherwise, encoder specific defaults + are invoked. @see TJpegImageData + + @leave System wide error if for example the format is not supported. + + @note must call InitFrameL before AppendBlocks or AddBlocks. Failure to do so completes request with + KErrNotReady + + @note can either specify format through aFormat or aImageFrameData. Conflicts cause a leave with KErrArgument. + */ + IMPORT_C void InitFrameL(TUid aFormat, TInt aFrameNumber, const TSize& aFrameSizeInPixels, const TSize& aBlockSizeInPixels, TEncodeStreamCaps::TNavigation aNavigation, const CFrameImageData* aFrameImageData); + + /** + Append blocks to the stream. + @param aStatus request status + @param aBlocks wraps a memory buffer containing the pixel data to be added to the stream + @param aNumBlocksToAdd number of blocks of size TEncodeStreamCaps::MinBlockSizeInPixels to add to the stream + */ + IMPORT_C void AppendBlocks(TRequestStatus& aStatus, const CImageFrame& aBlocks, TInt aNumBlocksToAdd); + + /** + Add blocks to the stream at a random position. + @param aStatus request status + @param aBlocks wraps a memory buffer containing the pixel data to be added to the stream + @param aSeqPosition position of block in stream starting at 0 + */ + IMPORT_C void AddBlocks(TRequestStatus& aStatus, const CImageFrame& aBlocks, const TInt& aSeqPosition); + + /** + Signal completion of writing the stream + @param aStatus request status + */ + IMPORT_C void Complete(TRequestStatus& aStatus); + +private: + + IMPORT_C TImageConvStreamedEncode(); + void SetExtension(MImageConvExtension* aExtension); + + MImageConvStreamedEncode* iExtension; + TInt iReserved; // future proof + }; + +#endif // IMAGECONVERSIONEXTENSION_H