// Copyright (c) 2001-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 __GRAPHICSACCELERATOR_H__

#define __GRAPHICSACCELERATOR_H__

#include <e32std.h>

#include <gdi.h>

//

// Bitmaps

//

// Forward references

class CFbsBitmap;

class TAcceleratedBitmapSpec;

/**

A data structure that holds the information needed to directly access a bitmap.

The bitmap can be a hardware bitmap (RHardwareBitmap), or an ordinary bitmap 

(CFbsBitmap). An object of this class is filled by calling TAcceleratedBitmapSpec::GetInfo().

@see RHardwareBitmap

@see CFbsBitmap

@see TAcceleratedBitmapSpec::GetInfo() 

@publishedAll

@released

*/

class TAcceleratedBitmapInfo

	{

public:

	/** The display mode of the bitmap. */

	TDisplayMode	iDisplayMode;

	/** The address of the start of the bitmap. */

	TUint8*			iAddress;

	/** The width and height of the bitmap in pixels. */

	TSize			iSize;

	/** The address offset (in bytes) between successive lines in a bitmap.

	If the bitmap is compressed the line pitch has no meaning so this data

	member is set to the negation of the compression type. In the case of

	an extended bitmap it is -EProprietaryCompression. */

	TInt			iLinePitch;

	/** The shift required to obtain the number of bits needed to represent one pixel

	in the bitmap. The number of bits per pixel is calculated as 1 << iPixelShift.

	In the case of an extended bitmap this data member is set to the bitmap type UID. */

	TInt			iPixelShift;

	union

		{

		/** The physical address of the start of the bitmap. This is the address which a

		hardware graphics accelerator will use and is zero if the bitmap is not accessible

		to hardware graphics accelerators. Invalid in the case of an extended bitmap. */

		TUint8*		iPhysicalAddress;

		/** In the case of an extended bitmap, the size of the raw bitmap data. */

		TInt		iDataSize;

		};

	};

/**

The interface to a hardware bitmap.

This is a bitmap that can be drawn to by graphics acceleration hardware. It 

is stored in a contiguous area of physical memory.

After creating the hardware bitmap, it can be passed to CHardwareGraphicsAccelerator::NewL().

@see CHardwareGraphicsAccelerator::NewL() 

@publishedAll

@released

*/

class RHardwareBitmap

	{

	friend class CBitwiseBitmap;

	friend class CFbsScreenDevice;

public:

    /** Default constructor. */

	inline RHardwareBitmap();

    /** Constructor taking the handle of an existing RHardwareBitmap to duplicate it. */

	inline RHardwareBitmap(TInt aHandle);

	/** 

	Gets the information needed for accessing a bitmap directly into TAcceleratedBitmapInfo structure.

	@param aInfo On return, holds the information needed to directly access the	bitmap.

	@return KErrNone if sucessful, otherwise one of the system error codes, including 

	KErrUnknown if the object's type is ENoBitmap. 

	*/

	IMPORT_C TInt GetInfo(TAcceleratedBitmapInfo& aInfo) const;

private:

	IMPORT_C TInt SetAsScreenReference(TInt aScreen=-1);

	IMPORT_C TInt Create(TDisplayMode aDisplayMode, TSize aSize, TUid aCreatorUid);

	IMPORT_C void Destroy();

public:

	/** The bitmap's handle; assigned during construction. This is used to identify 

	the bitmap. */

	TInt iHandle;	// Must be only member data

	};

	/** Default constructor. Initialises the handle to zero. */

inline RHardwareBitmap::RHardwareBitmap()

	: iHandle(0)

	{}

	/** Constructor taking the handle of an existing RHardwareBitmap to duplicate.

	@param aHandle The RHardwareBitmap handle to duplicate. */

inline RHardwareBitmap::RHardwareBitmap(TInt aHandle)

	: iHandle(aHandle)

	{}

/**

Maintains a count of the number of locks made on a bitmap through a TAcceleratedBitmapSpec 

object.

Passed as a parameter to TAcceleratedBitmapSpec::Lock() and TAcceleratedBitmapSpec::Unlock().

@see TAcceleratedBitmapSpec 

@publishedAll

@released

*/

class TBitmapLockCount

	{

	friend class TAcceleratedBitmapSpec;

public:

	/** Default constructor. Initialises the lock count to zero. */

	inline TBitmapLockCount() : iCount(0) {}

private:

	inline TInt Inc() { return iCount++; }

	inline TInt Dec() { return --iCount; }

private:

	TInt iCount;

	};

/**

A utility class that provides access to the contents of a bitmap.

The bitmap can be a hardware bitmap (RHardwareBitmap), or an ordinary bitmap 

(CFbsBitmap). An object of this class is used as a parameter by several accelerated 

graphics operations, e.g. TGopBitBlt, to specify the source bitmap for the 

operation. 

@publishedAll

@released

*/

class TAcceleratedBitmapSpec

	{

public:

	// Constructors

	inline TAcceleratedBitmapSpec();

	IMPORT_C TAcceleratedBitmapSpec(CFbsBitmap* aBitmap);

	IMPORT_C TAcceleratedBitmapSpec(RHardwareBitmap aBitmap);

	// Bitmap access (use with caution, see documentation)

	IMPORT_C TInt GetInfo(TAcceleratedBitmapInfo& aInfo) const;

	inline void Lock(TBitmapLockCount& aCount);

	inline void Lock(TBitmapLockCount& aCount,TAcceleratedBitmapInfo& aInfo);

	inline void	Unlock(TBitmapLockCount& aCount);

	// enums

	/** Identifies the type of the bitmap.

	Type() returns this value.

	@see CFbsBitmap */

	enum TAcceleratedBitmapType

		{

	/** The object was created using the default constructor, and has no type. */

		ENoBitmap,

	/** The bitmap is of type CFbsBitmap.

	@see CFbsBitmap */

		EFbsBitmap,

	/** The bitmap is of type RHardwareBitmap.

	@see RHardwareBitmap */

		EHardwareBitmap,

		};

	enum TAcceleratedBitmapLock

		{

		EBitmapIsStatic,

		EBitmapNeedsLocking,

		};

	// Getters

	inline TAcceleratedBitmapType	Type() const;

	inline TInt						Handle() const;

private:

	IMPORT_C void DoLock(TBitmapLockCount& aCount);

	IMPORT_C void DoLock(TBitmapLockCount& aCount,TAcceleratedBitmapInfo& aInfo);

	IMPORT_C void DoUnlock(TBitmapLockCount& aCount);

private:

	TUint8	iType;			// TAcceleratedBitmapType

	TUint8	iLockStatus;	// TAcceleratedBitmapLock

	TUint8	iSpare1;

	TUint8	iSpare2;

	TInt	iHandle;

	};

	/** Default constructor. 

	Use one of the other constructor overloads instead. */

inline TAcceleratedBitmapSpec::TAcceleratedBitmapSpec()

	: iType(ENoBitmap), iLockStatus(EBitmapIsStatic)

	{}

	/** Prevents a bitmap from moving in memory. Lock() should be called before accessing 

	the bitmap and Unlock() immediately afterwards. Although it is not necessary 

	to lock and unlock some types of bitmap, it is a small overhead, and it is 

	recommended that you always do it.

	If a bitmap is already locked, all uses of the Lock() and Unlock() methods 

	within the same thread must use the same TBitmapLockCount object, even if 

	Lock() and Unlock() are called by different instances of TAcceleratedBitmapSpec.

	@param aCount Maintains a count of the number of locks made on the bitmap. */

inline void TAcceleratedBitmapSpec::Lock(TBitmapLockCount& aCount)

	{ if(iLockStatus==EBitmapNeedsLocking) DoLock(aCount); }

	/** Prevents a bitmap from moving in memory. Lock() should be called before accessing 

	the bitmap and Unlock() immediately afterwards. Although it is not necessary 

	to lock and unlock some types of bitmap, it is a small overhead, and it is 

	recommended that you always do it. Also updates a TAcceleratedBitmapInfo structure 

	with any information that may have changed, (typically the bitmap's memory 

	address).

	If a bitmap is already locked, all uses of the Lock() and Unlock() methods 

	within the same thread must use the same TBitmapLockCount object, even if 

	Lock() and Unlock() are called by different instances of TAcceleratedBitmapSpec.

	@param aCount Maintains a count of the number of locks made on the bitmap.

	@param aInfo On return, contains the new address of the start of the bitmap. */

inline void TAcceleratedBitmapSpec::Lock(TBitmapLockCount& aCount,TAcceleratedBitmapInfo& aInfo)

	{ if(iLockStatus==EBitmapNeedsLocking) DoLock(aCount,aInfo); }

	/** Frees a bitmap after a call to Lock().  A call to Unlock() must be made for each corresponding

	call to Lock(). This function should be called as soon as any bitmap access has finished. If, after

	the Unlock() operation, no more calls to Lock() are outstanding on the bitmap, the bitmap is free to

	be moved in memory again.

	If a bitmap is already locked, all uses of the Lock() and Unlock() methods 

	within the same thread must use the same TBitmapLockCount object, even if 

	Lock() and Unlock() are called by different instances of TAcceleratedBitmapSpec.

	@param aCount Maintains a count of the number of locks made on the bitmap. */

inline void	TAcceleratedBitmapSpec::Unlock(TBitmapLockCount& aCount)

	{ if(iLockStatus==EBitmapNeedsLocking) DoUnlock(aCount); }

	/** Returns the type of the bitmap. The type is assigned during construction.

	@return The type of bitmap. */

inline TAcceleratedBitmapSpec::TAcceleratedBitmapType TAcceleratedBitmapSpec::Type() const

	{ return (TAcceleratedBitmapSpec::TAcceleratedBitmapType)iType; }

	/** Returns the handle to the bitmap.

	@return The handle to the bitmap. */

inline TInt TAcceleratedBitmapSpec::Handle() const

	{ return iHandle; }

//

// Accelerator capabilities

//

/**

Enumerates the four transparency types.

ETransparentPixel and ETransparentColor are used with a pixel value or a TRgb 

respectively.

@see TGopTransparency

@see TGraphicsAcceleratorCaps::iTransparency 

@publishedAll

@released

*/

enum TTransparencyType

	{

	/** Any pixel that has all bits equal to zero is treated as transparent. */

	ETransparentPixelZero,

	/** Any pixel that is equal to the pixel value passed to the TGopTransparency constructor 

	is treated as transparent. */

	ETransparentPixel,

	/** Any pixel that is equal to the TRgb value passed to the TGopTransparency constructor 

	is treated as transparent. */

	ETransparentColor,

	/** In 16 bits per pixel display mode, which uses 5 bits each for red, green and 

	blue, the most significant bit is an Alpha value. Alpha=0 means the pixel 

	is transparent, Alpha=1 means the pixel is fully opaque. */

	ETransparent1555,

	};

/** 

Stores the capabilities of a graphics accelerator.

All of the member enums except TMaskBitmapCaps define flags that are stored 

as public data of type TUint. Only TMaskBitmapCaps takes sequential values, 

so its values are mutually exclusive.

An object of this class is returned by CGraphicsAccelerator::Capabilities() 

or by GenericCapabilities(), which is implemented by CSoftwareGraphicsAccelerator 

and CHardwareGraphicsAccelerator.

@see CGraphicsAccelerator::Capabilities() 

@publishedAll

@released

*/

class TGraphicsAcceleratorCaps

	{

public:

    /** Clipping capabilities. Used by the iClipping member.

    @see CGraphicsAccelerator::Operation() */

	enum TClipCaps	// Bit flags

		{

		EClipToBitmap = 1,	// Will always clip all operations to the bitmap

	    /** The accelerator supports the Operation() methods which take clipping rectangles 

	    as parameters.

	    @see CGraphicsAccelerator::Operation() */

		EClipping = 2		// Is able to clip operations to a region

		};

/** Enumerates the capabilities relating to operations taking a bitmap mask parameter, 

for instance TGopBitBltMasked. These are mutually exclusive values used by 

the iMaskType member. */

	enum TMaskBitmapCaps	// Enum

		{

	/** No masked operations are supported. */

		EMaskBitmapNone = 0,

	/** The mask bitmap can be in any display mode at all. */

		EMaskBitmapAnyDisplayMode,

	/** The mask bitmap must be in the same display mode as the destination bitmap. */

		EMaskBitmapMatchingDisplayMode,

	/** The mask bitmap must be in EGray2 display mode. */

		EMaskBitmapGray2,

		};

/** Bit flags for the capabilities relating to operations that use an alpha channel 

(TGopBitBltAlphaChannel and TGopScaledBitBltAlphaChannel). These flags are 

used by the iAlphaChannel member. */

	enum TAlphaChannelCaps	//Bit flags

    	{

	/** The accelerator can draw bitmaps with 4 bits each for the alpha value and the 

	red, green and blue components. */

		EAlpha4444 = 1,	// Bitmaps with 4 bits for Alpha value and Red, Green, Blue components

	/** The accelerator can draw bitmaps with 8 bits each for the alpha value and the 

	red, green and blue components. */

		EAlpha8888 = 2, // Bitmaps with 8 bits for Alpha value and Red, Green, Blue components

	/** The accelerator can draw bitmaps with 1 bit for the alpha value and and 5 bits 

	for the red, green and blue components. */

		EAlpha1555 = 4, // Bitmaps with 1 bit for Alpha value and 5 bits for Red, Green, and Blue

		};

/** Bit flags for the capabilities relating to operations which take an alpha bitmap 

parameter, for instance TGopBitBltAlphaBitmap. These flags are used by the 

iAlphaBitmap member. */

	enum TAlphaBitmapCaps	//Bit flags

    	{

	/** For 256 greyscale bitmaps, the value of each pixel in the alpha bitmap (from 

	0 to 255) is used as the alpha value. */

		EAlphaBitmapGray256 = 1,

	/** An EColor16M bitmap may be used as the alpha bitmap. The red, green and blue 

	values for each pixel in this bitmap are used as the alpha values for the 

	red, green and blue components of the corresponding pixel in the source bitmap. */

		EAlphaBitmapColor16M = 2,

	/** The alpha bitmap must have the same display mode as the source bitmap. */

		EAlphaBitmapMatchingMode = 4,	// Alpha bitmap must be same mode as source

		};

/** Indicates whether there is a restriction on the sizes of bitmaps that can be 

used in bitmap patterns.

This is one of the possible values for the iPatternSizes member.

@see TGopFillPattern */

	enum TPatternSizeCaps	//Bit flags

		{

	/** There is no restriction on the dimensions of bitmap patterns. */

		EPatternSizeAny = 0xFFFFFFFF,

		};

/** Bit flags for the capabilities relating to operations that draw a fill pattern 

using a bitmap, for instance TGopFilledRectWithPatern. They are used in the 

iPattern member. */

	enum TPatternCaps	//Bit flags

		{

	/** The pattern bitmap can be in any display mode. */

		EPatternAnyDisplayMode = 1,			// Patterns can be in any supported display mode

	/** The pattern bitmap must be in the same display mode as the destination. */

		EPatternMatchingDisplayMode = 2,	// Pattern must be in same displ mode as target

	/** The pattern bitmap must be square (width==height). */

		EPatternMustBeSquare = 4,			// The pattern must be square (width==height)

		};

/** Bit flags for how self-crossing polygons are filled.

@see CGraphicsContext::TFillRule */

	enum TPolygonCaps	// Bit flags for fill rules (see CGraphicsContext::TFillRule)

		{

	/** Only areas with odd winding numbers are filled. */

		EPolygonFillAlternate = 1,

	/** All areas with a winding number greater than zero are filled.

	@see CGraphicsContext::TFillRule */

		EPolygonFillWinding = 2,

		};

/** Bit flags for the specifying the supported rendering orientations. 

@see  CFbsBitGc::TGraphicsOrientation */

 	enum TOrientationCaps

 		{

 		/** Normal orientation is supported. */

 		EOrientationCapNormal = 1,

 		/** A 90 degree rotation is supported. */

 		EOrientationCapRotated90 = 2,

 		/** A 180 degree rotation is supported. */

 		EOrientationCapRotated180 = 4,

 		/** A 270 degree rotation is supported. */

 		EOrientationCapRotated270 = 8,

 		/** All orientations are supported. */ 

 		EOrientationCapAll = EOrientationCapNormal|EOrientationCapRotated90|EOrientationCapRotated180|EOrientationCapRotated270

 		};

 	/** The size of this class in bytes. */

	TInt			iStructureSize;	// The size of this class

	/** The version number of the API. */

	TInt			iVersion;		// == 1 to specify current API

	/** Optional UID to identify the vendor of the graphics accelerator. This UID can 

	be used to recognise a particular accelerator, enabling code to use any custom 

	graphics operations and capabilities that it knows the accelerator provides. */

	TUid			iVendorUid;		// Optional ID

	/** A bit mask of the supported display modes for the bitmap passed to the graphics 

	accelerator's NewL(). Uses the least significant 11 bits as flags for each 

	TDisplayMode supported. For instance, to check whether the EColor256 display 

	mode is available, use the expression iDisplayModes & (1 << EColor256).

	@see TDisplayMode */

	TUint			iDisplayModes;	// One bit for each TDisplayMode enumeration

	/** Indicates whether the Operation() methods which take clipping rectangles as 

	parameters are supported.

	@see TClipCaps */

	TUint			iClipping;		// TClipCaps bit flags

	/** Specifies the display mode restrictions for bitmap masks. These are mutually 

	exclusive values.

	@see TMaskBitmapCaps */

	TMaskBitmapCaps	iMaskType;		// Mask type used

	/** Specifies the transparency types supported. Uses a bit flag for each TTransparencyType 

	supported.

	@see TTransparencyType */

	TUint			iTransparency;	// Bit flag for each TTransparencyType supported

	/** Specifies the capabilities relating to operations that use an alpha channel. Uses a bit flag for

	each TAlphaChannelCaps supported.

	@see TAlphaChannelCaps */

	TUint			iAlphaChannel;	// TAlphaChannelCaps bit flags

	/** Specifies the supported alpha bitmap types. Uses a bit flag for each TAlphaBitmapCaps 

	supported.

	@see TAlphaBitmapCaps */

	TUint			iAlphaBitmap;	// TAlphaBitmapCaps bit flags

	/** Specifies the sizes of bitmaps that can be used in bitmap patterns.

	This is a bitmask for each power of 2, or EPatternSizeAny. For example, if 

	bitmaps used in patterns can only have a width or height of 16 pixels then 

	this value should be set to 16. If patterns can have dimensions of 16, 32, 

	64, 128 or 256, then this value would equal the sum of these, (i.e. bits 4, 

	5, 6, 7 and 8 would be set).  If this value is equal to EPatternSizeAny, there

	are no restrictions on the size of patterns that can be used.

	@see TPatternSizeCaps */

	TUint			iPatternSizes;	// a mask bit for each power of 2, or EPatternSizeAny

	/** Specifies the supported bitmap types for fill patterns. Uses a bit flag for 

	each TPatternCaps supported.

	@see TPatternCaps */

	TUint			iPattern;		// TPatternCaps bit flags

	/** Specifies the supported fill rules for self crossing polygons. Uses a bit flag 

	for each TPolygonCaps supported.