--- /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 <e32base.h>
+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<TUid>& 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<TUid>& 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