// 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