--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/imaging/imagingfws/inc_pub/icl/imageconversionextensionintf.h Wed Aug 25 12:29:52 2010 +0300
@@ -0,0 +1,295 @@
+// 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 IMAGECONVERSIONEXTENSIONINTF_H
+#define IMAGECONVERSIONEXTENSIONINTF_H
+
+#include <icl/imageconversionextension.h>
+
+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 / flip.
+
+In order to support an extension the codec plugin must implement the interface and return this interface
+through a call to CImageDecoderPlugin::GetExtensionL.
+*/
+
+/**
+Extension base class
+*/
+class MImageConvExtension
+ {
+public:
+ /**
+ Uid of extension interface.
+ */
+ virtual TUid Uid() const = 0;
+
+ /**
+ Increment the reference count.
+ */
+ virtual void IncrementRef() = 0;
+
+ /**
+ Called when the client has finished with this interface allowing the codec to clean up.
+ */
+ virtual void Release() = 0;
+ };
+
+/**
+Operation extension for Image Conversion Library. Allows rotation and mirror/flip.
+*/
+class MImageConvOperation : public MImageConvExtension
+ {
+public:
+ /**
+ Capabilities of the code plugin.
+
+ @return Bitmask combination of TOperation. Bit is set if decoder plugin supports the operation.
+ */
+ virtual TUint Capabilities() const = 0;
+
+ /**
+ 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.
+
+ @param aOperation An operation to be added to the current operation stack.
+
+ @leave if more than one TOperation enum is passed for each individual call
+ */
+ virtual void AddOperationL(TImageConvOperation::TOperation aOperation) = 0;
+
+ /**
+ Remove all operations previously set.
+ */
+ virtual void ClearOperationStack() = 0;
+ };
+
+/**
+Scaling extension for Image Conversion Library
+*/
+class MImageConvScaler : public MImageConvExtension
+ {
+public:
+ /**
+ Gets the scaling capabilities.
+
+ @param aCaps Returns scaling capabilities of the codec plugin.
+ */
+ virtual void GetCapabilities(TScalerCaps& aCaps) const = 0;
+
+ /**
+ Request scaling to the desired size using the quality specified and specifying if the aspect ratio is to
+ be preserved.
+ @param aDesiredSize Proposed size of the scaled image.
+ @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.
+ */
+ virtual void SetScalingL(const TSize& aDesiredSize, TImageConvScaler::TScalerQuality aQuality, TBool aLockAspectRatio) = 0;
+
+ /**
+ Define the scaling to be applied to the image according to the given coefficient at the requested quality.
+
+ @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.
+ */
+ virtual void SetScalingL(TInt aScalingCoeff, TImageConvScaler::TScalerQuality aScalingQuality) = 0;
+ };
+
+/**
+Block Streaming extension for decoder plugins.
+*/
+class MImageConvStreamedDecode : public MImageConvExtension
+ {
+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.
+ */
+ virtual void GetSupportedFormatsL(RArray<TUid>& aFormats, TUid& aOptimalFormat) const = 0;
+
+ /**
+ Returns the capabilities of the codec plugin for a specific format.
+ @param aFormat The format.
+ @param aFrameNumber frame to stream
+ @param aCaps The capabilities for the format given.
+ */
+ virtual void GetCapabilities(TUid aFormat, TInt aFrameNumber, TDecodeStreamCaps& aCaps) const = 0;
+
+ /**
+ Get the size of the memory buffer to hold the returned data.
+
+ @param aFormat the required format
+ @param aBlockSizeInPixels size of a single block to be returned
+ @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.
+ */
+ virtual TInt GetBufferSize(TUid aFormat, TSize& aBlockSizeInPixels, TInt aNumBlocks) const = 0;
+
+ /**
+ 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.
+
+ @note TO DO Do we need to specify where the source is held e.g. in memory, on flash card etc?
+
+ @note must call InitFrameL before GetBlocks or GetNextBlocks. Failure to do so completes request with
+ KErrNotReady
+ */
+ virtual void InitFrameL(TUid aFormat, TInt aFrameNumber, TDecodeStreamCaps::TNavigation aNavigation) = 0;
+
+ /**
+ 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 0 ...
+ @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.
+ */
+ virtual void GetBlocks(TRequestStatus* aStatus, CImageFrame* aFrame, TInt aSeqPosition, TInt aNumBlocksToGet, TInt* aNumBlocksRead) = 0;
+
+ /**
+ 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.
+ */
+ virtual void GetNextBlocks(TRequestStatus* aStatus, CImageFrame* aFrame, TInt aNumBlocksToGet, TInt* aNumBlocksRead, TBool* aHaveMoreBlocks) = 0;
+ };
+
+/**
+Block Streaming extension for encoder plugins.
+*/
+class MImageConvStreamedEncode : public MImageConvExtension
+ {
+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.
+ */
+ virtual void GetSupportedFormatsL(RArray<TUid>& aFormats, TUid& aOptimalFormat) const = 0;
+
+ /**
+ Returns the capabilities of the codec plugin for a specific format.
+ @param aFormat The format.
+ @param aCaps The capabilities for the format given.
+ */
+ virtual void GetCapabilities(TUid aFormat, TEncodeStreamCaps& aCaps) const = 0;
+
+ /**
+ 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. ??? do we want to support multiple blocks being added
+ in which case InitFrameL needs an extra parameter
+ @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.
+ There exists format-specific image data variants that are used by
+ encoders to obtain image specific data. This behaviour is invoked by specifying
+ aFrameImageData. Otherwise, if set to NULL, encoder specific defaults are invoked. @see TJpegImageData
+
+ @note TO DO Do we need to specify where the destination is held e.g. in memory, on flash card etc?
+
+ @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 should leave with KErrArgument.
+ */
+ virtual void InitFrameL(TUid aFormat, TInt aFrameNumber, const TSize& aFrameSizeInPixels, const TSize& aBlockSizeInPixels, TEncodeStreamCaps::TNavigation aNavigation, const CFrameImageData* aFrameImageData) = 0;
+
+ /** 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
+ */
+ virtual void AppendBlocks(TRequestStatus* aStatus, const CImageFrame& aBlocks, TInt aNumBlocksToAdd) = 0 ;
+
+ /** 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
+ */
+ virtual void AddBlocks(TRequestStatus* aStatus, const CImageFrame& aBlocks, const TInt& aSeqPosition) = 0;
+
+ /** Signal completion of writing the stream
+ @param aStatus request status
+ */
+ virtual void Complete(TRequestStatus* aStatus) = 0;
+private:
+ TInt iReserved; // future proof
+ };
+
+
+/**
+Extension for Prepare (analyse image in advance of conversion)
+*/
+class MImageConvPrepare : public MImageConvExtension
+ {
+public:
+ /**
+ Call to allow analysis of image prior to calling Convert.
+
+ @param aStatus
+ Request 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.
+ */
+ virtual void Prepare(TRequestStatus* aStatus) = 0;
+
+private:
+ TInt iReserved; // future proof
+ };
+
+
+
+#endif // IMAGECONVERSIONEXTENSIONINF_H