williamr@2: // Copyright (c) 2007-2009 Nokia Corporation and/or its subsidiary(-ies).
williamr@2: // All rights reserved.
williamr@2: // This component and the accompanying materials are made available
williamr@2: // under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
williamr@2: // which accompanies this distribution, and is available
williamr@2: // at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
williamr@2: //
williamr@2: // Initial Contributors:
williamr@2: // Nokia Corporation - initial contribution.
williamr@2: //
williamr@2: // Contributors:
williamr@2: //
williamr@2: // Description:
williamr@2: //
williamr@2: 
williamr@2: #ifndef IMAGECONVERSIONEXTENSIONINTF_H
williamr@2: #define IMAGECONVERSIONEXTENSIONINTF_H
williamr@2: 
williamr@2: #include <icl/imageconversionextension.h>
williamr@2: 
williamr@2: class CImageFrame;
williamr@2: class CFrameImageData;
williamr@2: 
williamr@2: /**
williamr@2: @file
williamr@2: @publishedAll
williamr@2: @released
williamr@2: */
williamr@2: 
williamr@2: /**
williamr@2:  Image Conversion Library extensions. When applied together there is an implicit order for operations:
williamr@2:  	1. Crop or clip.
williamr@2:  	2. Scale
williamr@2:  	3. Rotate / flip.
williamr@2: 
williamr@2: In order to support an extension the codec plugin must implement the interface and return this interface 
williamr@2: through a call to CImageDecoderPlugin::GetExtensionL.
williamr@2: */
williamr@2:  
williamr@2: /**
williamr@2: Extension base class
williamr@2: */
williamr@2: class MImageConvExtension
williamr@2: 	{
williamr@2: public:
williamr@2: 	/** 
williamr@2: 	Uid of extension interface.
williamr@2: 	*/
williamr@2: 	virtual TUid Uid() const = 0; 
williamr@2: 
williamr@2: 	/**
williamr@2: 	Increment the reference count.
williamr@2: 	*/
williamr@2: 	virtual void IncrementRef() = 0;
williamr@2: 	
williamr@2: 	/**
williamr@2: 	Called when the client has finished with this interface allowing the codec to clean up.
williamr@2: 	*/
williamr@2: 	virtual void Release() = 0; 
williamr@2: 	};
williamr@2: 
williamr@2: /**
williamr@2: Operation extension for Image Conversion Library. Allows rotation and mirror/flip. 
williamr@2: */
williamr@2: class MImageConvOperation : public MImageConvExtension
williamr@2: 	{
williamr@2: public:	
williamr@2: 	/**
williamr@2: 	 Capabilities of the code plugin.
williamr@2: 	 
williamr@2: 	 @return Bitmask combination of TOperation. Bit is set if decoder plugin supports the operation.
williamr@2: 	 */
williamr@2: 	virtual TUint Capabilities() const = 0;
williamr@2: 	
williamr@2: 	/**
williamr@2: 	 Set up an operation be applied to the source. May be called more than once 
williamr@2: 	 to set up a stack of operations, but it is not possible to add more than one
williamr@2: 	 operation in a single call.
williamr@2: 	 
williamr@2: 	 @param aOperation An operation to be added to the current operation stack.
williamr@2: 	 
williamr@2: 	 @leave if more than one TOperation enum is passed for each individual call
williamr@2: 	 */
williamr@2: 	virtual void AddOperationL(TImageConvOperation::TOperation aOperation) = 0;
williamr@2: 	
williamr@2: 	/**
williamr@2: 	 Remove all operations previously set. 
williamr@2: 	*/
williamr@2: 	virtual void ClearOperationStack() = 0;
williamr@2: 	};
williamr@2: 
williamr@2: /**
williamr@2: Scaling extension for Image Conversion Library
williamr@2: */
williamr@2: class MImageConvScaler : public MImageConvExtension
williamr@2: 	{
williamr@2: public:
williamr@2: 	/**
williamr@2: 	 Gets the scaling capabilities.
williamr@2: 	 
williamr@2: 	 @param aCaps Returns scaling capabilities of the codec plugin.
williamr@2: 	 */
williamr@2: 	virtual void GetCapabilities(TScalerCaps& aCaps) const = 0;
williamr@2: 
williamr@2:     /** 
williamr@2:      Request scaling to the desired size using the quality specified and specifying if the aspect ratio is to
williamr@2:      be preserved.
williamr@2: 	 @param aDesiredSize  Proposed size of the scaled image.
williamr@2: 	 @param aQuality Desired quality of the image. Allows codec to lower quality targets to
williamr@2:      improve performance.
williamr@2: 	 @param aLockAspectRatio Set to ETrue if the aspect ratio of the original image is to be preserved.
williamr@2: 	 @leave KErrNotSupported if an invalid size is passed.
williamr@2: 	 @leave KErrNotSupported if aLockAspectRatio is EFalse and codec only supports preservation of aspect ratio.
williamr@2: 	 */ 
williamr@2: 	virtual void SetScalingL(const TSize& aDesiredSize, TImageConvScaler::TScalerQuality aQuality, TBool aLockAspectRatio) = 0;
williamr@2: 
williamr@2: 	/**
williamr@2: 	 Define the scaling to be applied to the image according to the given coefficient at the requested quality.
williamr@2: 	 
williamr@2: 	 @param aScalingCoeff Scale to apply to the source. 2 means twice the original size, -2 half the size. 
williamr@2: 	                      Do not confuse this with ReductionFactor where 2 indicates 1/2 size.
williamr@2:      @param aScalingQuality Desired quality of the image. Allows codec to lower quality targets to
williamr@2:      improve performance.
williamr@2: 	 @leave KErrNotSupported if codec cannot perform the requested scale.
williamr@2: 	 */
williamr@2: 	virtual void SetScalingL(TInt aScalingCoeff, TImageConvScaler::TScalerQuality aScalingQuality) = 0;
williamr@2: 	};
williamr@2: 
williamr@2: /**
williamr@2: Block Streaming extension for decoder plugins.
williamr@2: */
williamr@2: class MImageConvStreamedDecode : public MImageConvExtension
williamr@2: 	{	
williamr@2: public:
williamr@2:     /**
williamr@2:      Returns a list of supported formats and the optimal format to be used. @see imageframeconst.h
williamr@2:      for a list of format uids.
williamr@2:      @param aFormats Returns an array of format uids 
williamr@2:      @param aOptimalFormat The 'best' uid to use. 
williamr@2:      */
williamr@2: 	virtual void GetSupportedFormatsL(RArray<TUid>& aFormats, TUid& aOptimalFormat) const = 0;
williamr@2: 
williamr@2: 	/**
williamr@2: 	 Returns the capabilities of the codec plugin for a specific format.
williamr@2: 	 @param aFormat The format.
williamr@2: 	 @param aFrameNumber frame to stream
williamr@2: 	 @param aCaps The capabilities for the format given.
williamr@2: 	 */     
williamr@2: 	virtual void GetCapabilities(TUid aFormat, TInt aFrameNumber, TDecodeStreamCaps& aCaps) const = 0;
williamr@2: 	
williamr@2: 	/**
williamr@2: 	 Get the size of the memory buffer to hold the returned data.
williamr@2: 	 
williamr@2: 	 @param aFormat the required format
williamr@2: 	 @param aBlockSizeInPixels size of a single block to be returned
williamr@2: 	 @param aNumBlocks the number of blocks of size TDecodeStreamCaps::MinBlockSizeInPixels() to be returned by one request
williamr@2: 	 @return The memory buffer size in bytes to hold the requested blocks.
williamr@2: 	 */
williamr@2: 	virtual TInt GetBufferSize(TUid aFormat, TSize& aBlockSizeInPixels, TInt aNumBlocks) const = 0;
williamr@2: 
williamr@2: 	/**
williamr@2: 	 Initialise the stream.
williamr@2: 	 @param aFormat the format to use
williamr@2: 	 @param aFrameNumber frame to stream
williamr@2: 	 @param aNavigation indication to stream of the way that the stream will be navigated. Allows 
williamr@2: 	 codec to optimise it's behaviour.
williamr@2: 	 
williamr@2: 	 @note TO DO Do we need to specify where the source is held e.g. in memory, on flash card etc?
williamr@2: 	 
williamr@2: 	 @note must call InitFrameL before GetBlocks or GetNextBlocks. Failure to do so completes request with
williamr@2: 	 KErrNotReady
williamr@2: 	 */
williamr@2: 	virtual void InitFrameL(TUid aFormat, TInt aFrameNumber, TDecodeStreamCaps::TNavigation aNavigation) = 0;
williamr@2: 
williamr@2: 	/**
williamr@2: 	 Start asynchronous call to return random blocks from the stream
williamr@2: 	 
williamr@2: 	 @param aStatus request status
williamr@2: 	 @param aFrame An image frame wrapper a memory buffer to hold the returned block(s) of 
williamr@2: 	 pixel data. This can be 'uninitialised' or given specific format which must match that
williamr@2: 	 specified in the InitFrameL call.
williamr@2: 	 @param aSeqPosition block number starting at 0 ...
williamr@2: 	 @param aNumBlocksToGet number of blocks requested
williamr@2: 	 @param aNumBlocksRead number of blocks which will be returned when the request completes
williamr@2: 	 
williamr@2:      @note use CImageDecoder::Cancel() to cancel this request.
williamr@2: 	 */
williamr@2: 	virtual void GetBlocks(TRequestStatus* aStatus, CImageFrame* aFrame, TInt aSeqPosition, TInt aNumBlocksToGet, TInt* aNumBlocksRead) = 0;
williamr@2: 
williamr@2: 	/**
williamr@2: 	 Start asynchronous call to return blocks sequentially from the stream. Blocks are returned 
williamr@2: 	 from the first block until the last in the stream.
williamr@2: 	 
williamr@2: 	 @param aStatus request status
williamr@2: 	 @param aFrame An image frame wrapper a memory buffer to hold the returned block(s) of 
williamr@2: 	 pixel data. This can be 'uninitialised' or given specific format which must match that
williamr@2: 	 specified in the InitFrameL call.
williamr@2: 	 @param aNumBlocksToGet number of blocks requested
williamr@2: 	 @param aNumBlocksRead number of blocks which will be returned when the request completes
williamr@2: 	 
williamr@2:      @note use CImageDecoder::Cancel() to cancel this request.
williamr@2: 	 */
williamr@2: 	virtual void GetNextBlocks(TRequestStatus* aStatus, CImageFrame* aFrame, TInt aNumBlocksToGet, TInt* aNumBlocksRead, TBool* aHaveMoreBlocks) = 0;
williamr@2: 	};
williamr@2: 
williamr@2: /**
williamr@2: Block Streaming extension for encoder plugins.
williamr@2: */
williamr@2: class MImageConvStreamedEncode : public MImageConvExtension
williamr@2: 	{
williamr@2: public:
williamr@2:     /**
williamr@2:      Returns a list of supported formats and the optimal format to be used. @see imageframeconst.h
williamr@2:      for a list of format uids.
williamr@2:      @param aFormats Returns an array of format uids 
williamr@2:      @param aOptimalFormat The 'best' uid to use. 
williamr@2:      */
williamr@2: 	virtual void GetSupportedFormatsL(RArray<TUid>& aFormats, TUid& aOptimalFormat) const = 0;
williamr@2: 
williamr@2: 	/**
williamr@2: 	 Returns the capabilities of the codec plugin for a specific format.
williamr@2: 	 @param aFormat The format.
williamr@2: 	 @param aCaps The capabilities for the format given.
williamr@2: 	 */     
williamr@2: 	virtual void GetCapabilities(TUid aFormat, TEncodeStreamCaps& aCaps) const = 0;
williamr@2: 
williamr@2: 	/**
williamr@2: 	 Initialise the stream.
williamr@2: 	 @param aFormat the format to use
williamr@2: 	 @param aFrameNumber frame to stream
williamr@2: 	 @param aFrameSizeInPixels Size of this frame in pixels
williamr@2: 	 @param aBlockSizeInPixels Size of block to be added / appended. ??? do we want to support multiple blocks being added
williamr@2: 	 in which case InitFrameL needs an extra parameter
williamr@2: 	 @param aNavigation indication to stream of the way that the stream will be navigated. Allows 
williamr@2: 	 codec to optimise it's behaviour.
williamr@2: 	 @param aFrameImageData The frame image data. Optional.
williamr@2: 	 There exists format-specific image data variants that are used by 
williamr@2: 	 encoders to obtain image specific data. This behaviour is invoked by specifying 
williamr@2: 	 aFrameImageData. Otherwise, if set to NULL, encoder specific defaults are invoked. @see TJpegImageData
williamr@2: 	 
williamr@2: 	 @note TO DO Do we need to specify where the destination is held e.g. in memory, on flash card etc?
williamr@2: 	 
williamr@2: 	 @note must call InitFrameL before AppendBlocks or AddBlocks. Failure to do so completes request with
williamr@2: 	 KErrNotReady
williamr@2: 
williamr@2: 	 @note can either specify format through aFormat or aImageFrameData. Conflicts should leave with KErrArgument. 
williamr@2: 	 */
williamr@2: 	virtual void InitFrameL(TUid aFormat, TInt aFrameNumber, const TSize& aFrameSizeInPixels, const TSize& aBlockSizeInPixels, TEncodeStreamCaps::TNavigation aNavigation, const CFrameImageData* aFrameImageData) = 0;
williamr@2: 	
williamr@2: 	/** Append blocks to the stream.
williamr@2: 	 @param aStatus request status	
williamr@2: 	 @param aBlocks wraps a memory buffer containing the pixel data to be added to the stream
williamr@2: 	 @param aNumBlocksToAdd number of blocks of size TEncodeStreamCaps::MinBlockSizeInPixels to add to the stream
williamr@2: 	 */
williamr@2: 	virtual void AppendBlocks(TRequestStatus* aStatus, const CImageFrame& aBlocks, TInt aNumBlocksToAdd) = 0 ;
williamr@2: 	
williamr@2: 	/** Add blocks to the stream at a random position.
williamr@2: 	 @param aStatus request status	
williamr@2: 	 @param aBlocks wraps a memory buffer containing the pixel data to be added to the stream
williamr@2: 	 @param aSeqPosition position of block in stream starting at 0
williamr@2: 	 */
williamr@2: 	virtual void AddBlocks(TRequestStatus* aStatus, const CImageFrame& aBlocks, const TInt& aSeqPosition) = 0;
williamr@2: 	
williamr@2: 	/** Signal completion of writing the stream
williamr@2: 	 @param aStatus request status	
williamr@2: 	*/
williamr@2: 	virtual void Complete(TRequestStatus* aStatus) = 0; 
williamr@2: private:
williamr@2: 	TInt iReserved; // future proof
williamr@2: 	};
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: Extension for Prepare (analyse image in advance of conversion)
williamr@2: */
williamr@2: class MImageConvPrepare : public MImageConvExtension
williamr@2: 	{
williamr@2: public:
williamr@2: 	/**
williamr@2: 	Call to allow analysis of image prior to calling Convert.
williamr@2: 
williamr@2: 	@param	aStatus
williamr@2: 			Request status. On completion this contains an error code. This is KErrNone if the frame
williamr@2: 			was analyzed successfully, KErrNotSupported if the codec does not support analysis, or a 
williamr@2: 			system-wide error code.
williamr@2: 	*/
williamr@2: 	virtual void Prepare(TRequestStatus* aStatus) = 0;
williamr@2: 
williamr@2: private:
williamr@2: 	TInt iReserved; // future proof
williamr@2: 	};
williamr@2: 	
williamr@2: 
williamr@2: 
williamr@2: #endif // IMAGECONVERSIONEXTENSIONINF_H