// Copyright (c) 1997-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 __BITDRAW_H__
#define __BITDRAW_H__

#include <gdi.h>
#include <e32event_private.h>

/**
@publishedPartner
@released
*/
enum TScreenDriverPanic
	{
	EScreenDriverPanicNoDevicePresent=1,
	EScreenDriverPanicInvalidParameter,
	EScreenDriverPanicInvalidDisplayMode,
	EScreenDriverPanicInvalidWindowHandle,
	EScreenDriverPanicOutOfBounds,
	EScreenDriverPanicZeroLength,
	EScreenDriverPanicNullPointer,
	EScreenDriverPanicInvalidPointer,
	EScreenDriverPanicAlphaBlendInvariant,
	EScreenDriverPanicIvalidMethodCall,
	EScreenDriverPanicInvalidSize,
	EScreenDriverPanicInvalidHalValue,
	EScreenDriverPanicInvalidScreenNo,
	EScreenDriverPanicIncompatiblePreviousDevice		//<The previous device in SetDisplayMode was not compatible
	};

/**
@publishedPartner
@released
*/
GLREF_C void Panic(TScreenDriverPanic aPanicCode);


/**
@publishedPartner
@released
*/
class CFbsDrawDevice : public CBase
	{
public:
	/**
	Defines possible Shadowmode values
	*/
	enum TShadowMode
		{
		/** No Shadow mode is supported.
		*/
		ENoShadow	= 0x0,
		/** Shadow mode is supported. 
		*/
		EShadow		= 0x1,
		/** Faded mode is supported.
		*/
		EFade		= 0x2,
		/** Shadow and faded mode is supported. 
		*/
		EShadowFade	= 0x3
		};
	/**
	Defines possible rotation values
	*/
	enum TOrientation
		{
		/** Normal orientation is supported. 
		*/
		EOrientationNormal,
		/** A 90 degree rotation is supported. 
		*/
		EOrientationRotated90,
		/** A 180 degree rotation is supported. 
		*/
		EOrientationRotated180,
		/** A 270 degree rotation is supported. 
		*/
		EOrientationRotated270
		};
public:
   	/** 
   	DEPRECATED: Use NewScreenDeviceL(TInt aScreenNo, TDisplayMode aDispMode)
   	
	@deprecated
	*/
	IMPORT_C static CFbsDrawDevice* NewScreenDeviceL(TScreenInfoV01 aInfo,TDisplayMode aDispMode);
	
	/**
	Creates a new screen device instance, which implements CFbsDrawDevice interface.
	The method has to be implemented for each type of supported video hardware.
	@param aScreenNo    Screen number
	@param aDispMode    Requested display mode
	@return A pointer to just created screen device, which implements CFbsDrawDevice interface
	@leave 	KErrNoMemory Not enough memory
	KErrNotSupported The requested screen device type is not supported
	*/
	IMPORT_C static CFbsDrawDevice* NewScreenDeviceL(TInt aScreenNo, TDisplayMode aDispMode);
	
	/** 
	DEPRECATED: Use NewBitmapDeviceL(const TSize& aSize, TDisplayMode aDispMode, TInt aDataStride)
	
	@deprecated 
	*/
	IMPORT_C static CFbsDrawDevice* NewBitmapDeviceL(TScreenInfoV01 aInfo, TDisplayMode aDispMode, TInt aDataStride);
	
	/**	
	Creates a new bitmap device instance, which implements CFbsDrawDevice interface.
	
	@param  aSize       Bitmap device size
	@param  aDispMode   Bitmap display mode
	@param  aDataStride Bitmap data stride 
	@return A pointer to just created bitmap device, which implements CFbsDrawDevice interface
	@leave	KErrNoMemory Not enough memory
	KErrArgument Invalid aSize value
	*/
	IMPORT_C static CFbsDrawDevice* NewBitmapDeviceL(const TSize& aSize, TDisplayMode aDispMode, TInt aDataStride);
	
	/**	
	Depending on current graphics hardware the method will return one of 
	two possible 16M video modes: 
	EColor16M or EColor16MU. If the hardware doesn't support EColor16M 
	or EColor16MU mode, the return value will be ENone.
	
	@return	EColor16M, EColor16MU or ENone.	
	ENone - it means that current hardware doesn't support 16M color mode.
	*/
	IMPORT_C static TDisplayMode DisplayMode16M();

	/**
	Return the display mode of the device.
	@return Display mode
	*/
	virtual TDisplayMode DisplayMode() const = 0;

	/**
	Scanline width in pixels. 
	The return value can be greater or equal than iSize.iWidth, because
	the scan line memory is allocated in 32-bit words and can be rounded up, if
	the display mode allows more than 1 pixel to be stored in a single byte.
	@return The (adjusted) width in pixels.
	*/
	virtual TInt LongWidth() const = 0;
	
	/**
	Alter the colours within a defined rectangle according to the supplied mapping.
	The colour map is supplied as pairs of TRgb objects. One member of the pair defines a colour value
	to match, the other defines a colour to replace that value by.
	Note that, for comparison purposes, smaller gamuts (e.g. 64K colour) are mapped to TRgb form before
	comparison, so a colour that is not representable in the current display mode will not be matched.
	Pixels in the original that do not match an entry in the colour map are unchanged.
	@param aRect 			Area of the device/bitmap to be mapped in logical coordinates
	@param aColors 			Colour map. This should be provided as a set of TRgb pairs, one to be matched
							and the other to provide a replacement. 
	@param aNumPairs 		Number of pairs of colours in aColors.
	@param aMapForwards 	If ETrue, match the first colour of a pair and replace by the second, otherwise
	                    	match the second and replace by the first.
	@panic EScreenDriverPanicOutOfBounds 	if aRect transforms back to illegal physical coordinates.
	@panic EScreenDriverPanicNullPointer 	if aColors == NULL
	@panic EScreenDriverPanicZeroLength 	if aNumPairs == 0
	*/
	virtual void MapColors(const TRect& aRect,const TRgb* aColors,TInt aNumPairs,TBool aMapForwards) = 0;
	
	/**
	Reads a line of aLength pixels starting at [aX, aY] (in logical coordinates). The direction of reading
	is affected by the current orientation, and the "stride" taken in sampling pixels is affected by
	any scaling currently in force. Pixels are converted (if necessary) to the form specified by
	aDispMode before being written to the buffer. The entire line to be read must be within the
	physical bounds of the bitmap or device
	@param aX			X coordinate of the pixel to start reading from (logical coordinates)
	@param aY			Y coordinate of the pixel to start reading from(logical coordinates)
	@param aLength		Number of pixels to read
	@param aBuffer		Buffer to receive the pixel data (must be large enough)
	@param aDispMode	Format to use for writing pixels into the buffer.
	@panic EScreenDriverPanicOutOfBounds 	if either end of the line is out of bounds
	@panic EScreenDriverPanicNullPointer 	if aBuffer == NULL
	@panic EScreenDriverPanicZeroLength 	if aLength == 0
	*/
	virtual void ReadLine(TInt aX,TInt aY,TInt aLength,TAny* aBuffer,TDisplayMode aDispMode) const = 0;
	
	/**
	Get the colour of the pixel at the logical position [aX,aY]
	@param aX	X-coordinate of pixel to read (logical coordinates)
	@param aY	Y-coordinate of pixel to read (logical coordinates)
	@return The colour pf the pixel at [aX,aY]
	@panic EScreenDriverPanicOutOfBounds 	if [aX,aY] transforms back to illegal physical coordinates.
	*/
	virtual TRgb ReadPixel(TInt aX,TInt aY) const = 0;

	/**
	Returns a pointer to a buffer large enough to read a line of pixels of maximum length. Ownership of
	the buffer is retained by the bitmap or device object. Repeated calls to this function will return
	the same buffer.
	@return A pointer to a scan line buffer
	*/
	virtual TUint32* ScanLineBuffer() const = 0;
	
	/**
	Scanline width in bytes. The return value may be greater than the actual number of bytes needed
	to store the pixels, since scan line memory is allocated in 32-bit words and can be rounded up.
	@return The (adjusted) width in bytes.
	*/
	virtual TInt ScanLineBytes() const = 0;
	
	/**
	Return the display mode to be used when passing pixel data to the device using the scanline buffer.
	@return Display mode
	@see CFbsDrawDevice::DisplayMode
	*/
	virtual TDisplayMode ScanLineDisplayMode() const = 0;
	
	/**
	Returns the screen size in pixels, taking the orientation into account.
	Always prefer GetDrawRect() to SizeInPixels() call. 
	GetDrawRect() will take into account possible non-[0,0] top-left corner of the drawing
	rectangle if the device is scaled.
	@return TSize Screen size in pixels
	*/
	virtual TSize SizeInPixels() const = 0;

	/**
	Allows the caller to calculate the physical size of a bitmap on the current hardware
	by calculating how many twips a 1000-pixel wide bitmap would be. Only applicable to
	screen-based devices; bitmap devices return 0.
	@return Twips per 1000 pixels
	*/
	virtual TInt HorzTwipsPerThousandPixels() const = 0;
	
	/**
	Allows the caller to calculate the physical size of a bitmap on the current hardware
	by calculating how many twips a 1000-pixel high bitmap would be. Only applicable to
	screen-based devices; bitmap devices return 0.
	@return Twips per 1000 pixels
	*/
	virtual TInt VertTwipsPerThousandPixels() const = 0;
	
	/**
	Reports on which orientations are available on the device/bitmap.
	@param aOrientation	Array to receive the capability (use CFbsDrawDevice::TOrientation as an index)
	*/
	virtual void OrientationsAvailable(TBool aOrientation[4]) = 0;
	
	/**
	Set the orientation of the device
	@param aOrientation	Orientation to set
	@return ETrue if the new orientation was set successfully, EFalse otherwise
	*/
	virtual TBool SetOrientation(TOrientation aOrientation) = 0;

	/**
	Combines the current content of the device/bitmap with a supplied colour, based on a bitmask and
	a draw mode. The bitmask is supplied as an array of TUint32s, one for each line (so there should
	be aHeight entries in the array). Since one word is used per line, aLength must be <= 32. Each bit
	of the mask controls one pixel - if the bit is 1, the pixel is combined with aColor, if the bit
	is 0, the pixel is left unchanged. Note that bits in the bitmask are examined in low-high order,
	so bit0 affects the pixel at aX, bit1 affects the pixel at aX+1 and so forth.
	If the shadowing/fading flag is set, the resulting pixels will be shadowed/faded.
	@param aX			Left edge of the rectangle (logical coordinates)
	@param aY			Top edge of the rectangle (logical coordinates)
	@param aBuffer		Array of bitmasks - one per line
	@param aLength		Width of the rectangle (must be >0 and <= 32)
	@param aHeight		Height of the rectangle (== number of entries in aBuffer)
	@param aColor		Colour to combine with the existing pixel data
	@param aDrawMode	Combination function for source and destination pixels.			
	@panic EScreenDriverPanicOutOfBounds	If any part of the rectangle maps to an illegal physical coordinate
											or if aLength > 32.
	@panic EScreenDriverPanicNullPointer	If aBuffer == NULL
	@panic EScreenDriverPanicZeroLength		If aLength <= 0
	*/
	virtual void WriteBinary(TInt aX,TInt aY,TUint32* aBuffer,TInt aLength,TInt aHeight,TRgb aColor,CGraphicsContext::TDrawMode aDrawMode) = 0;
	
	/**
	Combines the current content of the device/bitmap with a supplied colour, based on a bitmask and
	a draw mode. This function differs from WriteBinary, in that aLength can be greater than 32, and
	the height is implicitly 1. aBuffer must contain sufficient elements to hold aLength bits
	If the shadowing/fading flag is set, the resulting pixels will be shadowed/faded.
	@param aX			Starting X coordinate (logical coordinates)
	@param aY			Starting Y coordinate (logical coordinates)
	@param aBuffer		Array of bitmasks
	@param aLength		Number of pixels
	@param aColor		Colour to combine with existing pixels
	@param aDrawMode	Combination function for source and destination pixels.			
	@panic EScreenDriverPanicOutOfBounds	If any part of the line maps to an illegal physical coordinate
	@panic EScreenDriverPanicNullPointer	If aBuffer == NULL
	@panic EScreenDriverPanicZeroLength		If aLength <= 0
	@see WriteBinary
	*/
	virtual void WriteBinaryLine(TInt aX,TInt aY,TUint32* aBuffer,TInt aLength,TRgb aColor,CGraphicsContext::TDrawMode aDrawMode) = 0;

	/**
	Similar to WriteBinaryLine, but writes a vertical, rather than a horizontal line. LIne is drawn upward
	(decreasing Y) if aUp == ETrue.
	@see WriteBinaryLine 
	*/	
	virtual void WriteBinaryLineVertical(TInt aX,TInt aY,TUint32* aBuffer,TInt aHeight,TRgb aColor,CGraphicsContext::TDrawMode aDrawMode,TBool aUp) = 0;

	/**
	Write the given colour to the location [aX,aY], combining it with the existing pixel
	using aDrawMode
	If the shadowing/fading flag is set, the resulting pixels will be shadowed/faded.
	@param aX			X coordinate (logical coordinates)
	@param aY			Y coordinate (logical coordinates)
	@param aColor		Colour to write
	@param aDrawMode	Combination function for source and destination pixels.			
	@panic EScreenDriverPanicOutOfBounds	If [aX,aY] maps to an illegal physical address
	*/
	virtual void WriteRgb(TInt aX,TInt aY,TRgb aColor,CGraphicsContext::TDrawMode aDrawMode) = 0;

	/**
	Write the given colour to the rectangle [aX,aY] - [aX+aLength,aY+aHeight], combining it
	with the exiasting pixels using aDrawMode
	If the shadowing/fading flag is set, the resulting pixels will be shadowed/faded.
	@param aX			X coordinate (logical coordinates)
	@param aY			Y coordinate (logical coordinates)
	@param aLength		Width of the rectangle (logical coordinates)
	@param aHeight		Height of the rectangle (logical coordinates)
	@param aColor		Colour to write
	@param aDrawMode	Combination function for source and destination pixels.			
	@panic EScreenDriverPanicOutOfBounds	If any part of the rectangle maps to an illegal physical address
	*/
	virtual void WriteRgbMulti(TInt aX,TInt aY,TInt aLength,TInt aHeight,TRgb aColor,CGraphicsContext::TDrawMode aDrawMode) = 0;
	
	/**
	The method performs an alpha blending of the source data - aRgbBuffer and screen pixels, using
	the data from aMaskBuffer buffer as an alpha blending factor.
	The formula used for that, is:
		(C1 * A + C2 * (255 - A)) / 255, where:
			- C1 - a pixel from aRgbBuffer;
			- C2 - a pixel from the sceen;
			- A  - a pixel from aMaskBuffer;
	The content of source and mask buffers is preserved.
	The calculated alpha blended pixel is written to the destination - the screen or a bitmap.
	If the shadowing/fading flag is set, a shadow/fade copy of the source bitmap will be used.
	@param aX 			Logical X coordinate of the start of the line.
	@param aY 			Logical Y coordinate of the line.
	@param aLength 		Source data - length in pixels.
	@param aRgbBuffer 	A pointer to a line of the source bitmap data.
	                    Must be in ERgb format.
	@param aMaskBuffer 	Buffer containing the data which should be used as an 
	                   	alpha blending factor. Must be in EGray256 format.
	@param aDrawMode	Combination function for source and destination pixels.
	@panic EScreenDriverPanicOutOfBounds	If any part of the line maps to an illegal physical address
	*/
	virtual void WriteRgbAlphaLine(TInt aX,TInt aY,TInt aLength,TUint8* aRgbBuffer,TUint8* aMaskBuffer, CGraphicsContext::TDrawMode aDrawMode) = 0;

	/**
	Combine the data in aBuffer with existing pixels along the line [aX,aY]-[aX+aLength,aY],
	using aDrawMode as the combining function.
	If the shadowing/fading flag is set, the resulting pixels will be shadowed/faded.
	@param aX 			Logical X coordinate of the start of the line.
	@param aY 			Logical Y coordinate of the line.
	@param aLength 		Source data - length in pixels.
	@param aBuffer		Source data. Must be in the format returned by ScanLineDisplayMode().
	@param aDrawMode	Combination function for source and destination pixels.			
	@panic EScreenDriverPanicOutOfBounds	If any part of the line maps to an illegal physical address
	*/
	virtual void WriteLine(TInt aX,TInt aY,TInt aLength,TUint32* aBuffer,CGraphicsContext::TDrawMode aDrawMode) = 0;
public:

	/**
	Do any necessary initialisation on screen devices (default applies to bitmaps)
	@return Success/failure code
	*/
	virtual TInt InitScreen() {return(KErrNone);}
	
	/** Sets or unsets auto-update for the screen.

	@param aValue ETrue, if the screen is set to auto-update; EFalse, otherwise. 
	*/
	virtual void SetAutoUpdate(TBool aValue) {(void) aValue;}	// To avoid compiler warning for unused parameter
	
	/**
	Set the internal data buffer to point to the supplied buffer. No checks are made that the buffer
	is appropriate for the purpose. Ownership is not taken.
	@param aBits	A buffer of sufficient size.
	*/
	virtual void SetBits(TAny*) {}
	
	/**
	Set up a custom palette for those bit formats that support palettised colour
	@param aPalette		Palette to use
	@return Success/failure code
	*/
	virtual TInt SetCustomPalette(const CPalette*) { return KErrNotSupported; }

	/**
	Retrieve a custom palette, if the bit format supports it.
	@param aPalette	Pointer to a CPalette. The palette will be created by this function.
	@return Success/failure code
	*/
	virtual TInt GetCustomPalette(CPalette*&) { return KErrNotSupported; }

	/**
	Copies all settings (scaling, orientation, etc.) from the supplied device
	and reinitialised the current device.
	@param aDrawDevice	Device to get settings from
	*/
	virtual void SetDisplayMode(CFbsDrawDevice*) {}

	/**
	Set the origin point of the dither matrix (if appropriate)
	@param aPoint	Dither origin (logical coordiantes)
	*/
	virtual void SetDitherOrigin(const TPoint&) {}

	/**
	Sets the user display mode - used for certain colour mapping functions
	*/
	virtual void SetUserDisplayMode(TDisplayMode) {}
	
	/**
	Sets the current shadowing mode
	@see TShadowMode
	*/
	virtual void SetShadowMode(TShadowMode) {}

	/**
	Set the current fading parameters
	@param aBlackMap	Black point
	@param aWhiteMap	White point
	*/
	virtual void SetFadingParameters(TUint8 /*aBlackMap*/,TUint8 /*aWhiteMap*/) {}

	/**
	Apply shadow processing to all the pixels in the supplied rectangle
	@param aRect	Area to apply shadow processing to (logical coordinates)
	@panic EScreenDriverPanicOutOfBounds	If any part of the rectangle maps to an illegal physical address
	*/
	virtual void ShadowArea(const TRect&) {} // Obeys shadow mode

	/**
	Applies shadow processing to the supplied buffer
	@param aLength		Length of buffer in pixels
	@param aBuffer		Buffer to process in the format returned by ScanLineDisplayMode()
	@panic EScreenDriverPanicZeroLength If aLength <= 0
	@panic EScreenDriverPanicNullPointer If aBuffer == NULL
	*/
	virtual void ShadowBuffer(TInt,TUint32*) {} // Obeys shadow mode

	/**
	Update the screen with the update region.
	*/
	virtual void Update() {}

	/**
	Update the screen with the union of the update and specified regions.
	@param aRegion		Region to update (logical coordinates)
	*/
	virtual void Update(const TRegion&) {}

	/**
	Update the update region.
	@param aRegion		Region to update (logical coordinates)
	*/
	virtual void UpdateRegion(const TRect&) {}
public:

	/**
	Blend aColor with the pixels along the line [aX,aY]-[aX+aLength,aY], using aMaskBuffer
	as alpha data
	If the shadowing/fading flag is set, a shadow/fade copy of the source bitmap will be used.
	@param aX			Logical X coordinate of the start of the line
	@param aY			Logical Y coordinate of the line.
	@param aLength		Length of line to modify
	@param aColor		Colour to blend with existing pixels
	@param aMaskBuffer	Buffer containing the data which should be used as an 
	                   	alpha blending factor.
	@panic EScreenDriverPanicOutOfBounds	If any part of the line maps to an illegal physical address
	*/
	virtual void WriteRgbAlphaMulti(TInt aX,TInt aY,TInt aLength,TRgb aColor,const TUint8* aMaskBuffer) = 0;

	/**
	The method performs an alpha blending of the source data - aRgbBuffer1 and aBuffer2, using
	the data from aMaskBuffer buffer as an alpha blending factor.
	If the shadowing/fading flag is set, the resulting pixels will be shadowed/faded.
	The formula used for that, is:
		(C1 * A + C2 * (255 - A)) / 255, where:
			- C1 - a pixel from aRgbBuffer1;
			- C2 - a pixel from aBuffer2;
			- A  - a pixel from aMaskBuffer;
	The content of source and mask buffers is preserved.
	The calculated alpha blended pixel is written to the destination - the screen or a bitmap.
	If the shadowing/fading flag is set, the resulting pixels will be shadowed/faded.
	@param aX Logical X coordinate of the position in the target the result should be drawn to.
	@param aY Logical Y coordinate of the position in the target the result should be drawn to.
	@param aLength Source data - length in pixels.
	@param aRgbBuffer1 A pointer to a line of the source bitmap data 1.
	                   Must be in ERgb format.
	@param aBuffer2 A pointer to a line of the source bitmap data 2.
	                Must be in the format returned by ScanLineDisplayMode().
	@param aMaskBuffer Buffer containing the data which should be used as an 
	                   alpha blending factor. Must be in EGray256 format.
	@param aDrawMode Drawing mode
	*/
	virtual void WriteRgbAlphaLine(TInt aX,TInt aY,TInt aLength,
								   const TUint8* aRgbBuffer1,
								   const TUint8* aBuffer2,
								   const TUint8* aMaskBuffer,
								   CGraphicsContext::TDrawMode aDrawMode) = 0;
	/**
	Retrieves a pointer to the specified CFbsDrawDevice interface extension.
	@param aInterfaceId Interface identifier of the interface to be retrieved.
	@param aInterface Address of pointer variable that retrieves the specified interface.
	@return KErrNone If the interface is supported, KErrNotSupported otherwise.
	@see BitDrawInterfaceId.h file for the IDs of supported interfaces
	*/
	virtual TInt GetInterface(TInt aInterfaceId, TAny*& aInterface) = 0;
	
	/**
	Gets logical coordinates of the drawing rectangle.
	If the device is not scaled and with zero origin, logocal coordinates of 
	the drawing rectangle are the same as its physical coordinates.
	If the device is rotated, drawing rectangle width and height are swapped.
	Always prefer GetDrawRect() to SizeInPixels() call. SizeInPixels() will return
	drawing rectangle width and height. But if the device is scaled or with nonzero origin,
	GetDrawRect() will take into account and the top-left corner of the drawing rectangle too,
	which may not be [0, 0].
	@param aDrawRect Upon return aRect contains drawing rectangle logical coordinates.
	*/
	virtual void GetDrawRect(TRect& aDrawRect) const = 0;
	
	/**
	The method swaps bitmap device's width and height.
	For example: if the size is (40, 20), the swapped size will be (20, 40).
	The device's content is not preserved.
	The method leaves CDrawBitmap object in a consistent state - 
	scaling settings will be set with their default values (the scaling is switched off),
	iDitherOrigin will be set to (0,0), iOrigin to (0,0).
	Note: This method is used internally by BITGDI component. Do not call it!
	*/
	virtual void SwapWidthAndHeight() = 0;
	};

#endif