// Copyright (c) 2008-2009 Nokia Corporation and/or its subsidiary(-ies).
// All rights reserved.
// This component and the accompanying materials are made available
// under the terms of the License "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:
// User side class definitions for GCE mode support.
// This file contains declarations for the generic
// screen display channel and APIs.
// 
//

/**
 @file dispchannel.h
 @publishedPartner
 @released
*/

#ifndef __DISPLAY_CHANNEL_H__
#define __DISPLAY_CHANNEL_H__ 

#include <e32cmn.h>
#include <e32ver.h>
#ifndef __KERNEL_MODE__
#include <e32std.h>
#endif

_LIT(KDisplayDriverName,"displaychannel");

// the defined versions to be used for macros, condititional complilation, etc. 

// The major version number. MUST be a number in the range 0 to 127
#define K_DISPLAY_CH_MAJOR_VERSION_NUMBER 1
// The minor version number. MUST be a number in the range 0 to 99
#define K_DISPLAY_CH_MINOR_VERSION_NUMBER 2
// The build number. MUST be a number in the range 0 to 32,767
#define K_DISPLAY_CH_BUILD_VERSION_NUMBER 1

// legacy set of version constants
const TInt KDisplayChMajorVersionNumber = K_DISPLAY_CH_MAJOR_VERSION_NUMBER;
const TInt KDisplayChMinorVersionNumber = K_DISPLAY_CH_MINOR_VERSION_NUMBER;
const TInt KDisplayChBuildVersionNumber = K_DISPLAY_CH_BUILD_VERSION_NUMBER;

// the base version supported across all implementation
const TInt KDisplayChMajorVersionNumberAlwaysSupported = 1;
const TInt KDisplayChMinorVersionNumberAlwaysSupported = 0;
const TInt KDisplayChBuildVersionNumberAlwaysSupported = 1;


/*
    Generic display driver interface
*/
class RDisplayChannel : public RBusLogicalChannel
	{
public:

	typedef TInt  TPixelFormat;
	typedef TUint TBufferId;
	typedef TUint TPostCount;

    enum TDisplayRotation
         /** Used to communicate available rotations as a bit field and used to set a 
             particular rotation as a single value. Rotations are specified relative 
             to the normal physical orientation of the device.
         */
        {
            ERotationNormal    = 1,
            ERotation90CW      = 2,
            ERotation180       = 4,
            ERotation270CW     = 8,
            // v 1.1
            ERotationAll       = 0xF
        };

    // control messages
	enum TControl
		{
		// v 1.0
		ECtrlGetCaps = 0,
		ECtrlIsSingleBuffered,
		ECtrlGetDisplayInfo,
		ECtrlOpen,
		ECtrlClose,
		ECtrlPostCompositionBuffer,
		ECtrlPostLegacyBuffer,
		ECtrlRegisterUserBuffer,
		ECtrlDeregisterUserBuffer,
		ECtrlPostCount,
		ECtrlSetRotation,
		ECtrlCurrentRotation,
		ECtrlGetCompositionBufferInfo,
		// intermediate version
		ECtrlVersion,
		// v 1.1
		ECtrlNumberOfResolutions,
		ECtrlGetResolutions,
		ECtrlSetResolution,
		ECtrlGetResolution,
		ECtrlGetTwips,
		ECtrlNumberOfPixelFormats,
		ECtrlGetPixelFormats,
		ECtrlSetBufferFormat,
		ECtrlGetBufferFormat,
		ECtrlNextPlaneOffset,
		ECtrlNextLineOffset,
		// v 1.2
		ECtrlNextPlaneOffsetExtended,
		ECtrlNextLineOffsetExtended,
		ECtrlCreateUserBuffer
		};

    // request messages
	enum TRequest
		{
		EReqGetCompositionBuffer = 0,
		EReqPostUserBuffer,
		EReqWaitForPost,
		// v 1.1
		EReqWaitForDisplayConnect
		};

    // corresponding cancel
    enum TCancel
    	{
           ECtrlCancelGetCompositionBuffer = 0,
	       ECtrlCancelPostUserBuffer,
	       ECtrlCancelWaitForPost,
			// v 1.1
	       ECtrlCancelWaitForDisplayConnect
	       
    	};

    enum TPanic
    	{
            EWrongRequest,      // wrong request number from the user side
    		EReqAlreadyPending, // user asynchronous reques is already pending
    		EDriverNotReady,    // wrong operation mode
			// v 1.1
    		EInvalidResolution,	// Negative resolution passed
    		ENullArgument,		// NULL argument passed
    	};

public:		//structures used
	
    // display channel configuration information per orientation
    class TOrientationSpecificInfo
    /** Used to communicate the display configuration for a particular orientation.
    */
        {
    public:
        TUint iWidth;               //the width of the display in pixels.
        TUint iHeight;              // the height of the display in pixels.
        TInt iOffsetBetweenLines;
        TUint32 reserved_0;        // reserved fields for future extension
        TUint32 reserved_1;
        TUint32 reserved_2;
        TUint32 reserved_3;
        TUint32 reserved_4;
        };

    // display channel info
    class TDisplayInfo
        {
    public:
		enum { KMaxUserBuffers = 8 };
		enum { KMaxRectangles = 4 };
        TUint iBitsPerPixel;
        TUint iRefreshRateHz;
        TUint iAvailableRotations;
        TPixelFormat iPixelFormat;
        TOrientationSpecificInfo iNormal;       // rotation of 0 or 180 degrees
        TOrientationSpecificInfo iFlipped;      // rotation of 90 or 270 degrees
        TUint iNumCompositionBuffers;
        TUint32 reserved_0;                     // reserved fields for future extension
        TUint32 reserved_1;
        TUint32 reserved_2;
        TUint32 reserved_3;
        TUint32 reserved_4;
        };
    
	/** Defines a resolution setting, a combination of a size in pixels and the
		rotations of that size that can be used. For consistency, the size is always
		given in terms of ERotationNormal, regardless of whether that rotation is
		supported or not.
	 */
	class TResolution
		{	//Kernel mode makes use of agregate constructors
	public:
#ifndef __KERNEL_MODE__
		inline TResolution(TSize aPixelSize,TSize aTwipsSize, TUint32 aFlags = ERotationNormal);
#endif

	public:
		/** The physical display size in pixels with no rotation (i.e. ERotationNormal).
		    See RDisplayChannel::SetResolution().
		*/
		TSize iPixelSize;
		/** The physical display size in twips with no rotation (i.e. ERotationNormal).
		    See RDisplayChannel::SetResolution().
		*/
		TSize iTwipsSize;
		/** A bitwise combination of RDisplayChannel::TDisplayRotation values.
		*/
		TUint32 iFlags;
#ifndef __KERNEL_MODE__
	private:
#endif
		/** Reserved for extension and alignment.
		*/
		TUint32 reserved_0;
		};

	/**
	  Defines the format of a buffer to be posted using PostCompositionBuffer(),
	  PostLegacyBuffer() or PostUserBuffer().
	 */
	class TBufferFormat
		{	//Kernel mode makes use of agregate constructors
	public:
#ifndef __KERNEL_MODE__
		inline TBufferFormat(TSize aSize, TPixelFormat aPixelFormat);
#endif
	public:
		/** The pixel dimensions of the buffer.
		*/
		TSize iSize;
		/** The pixel format of the buffer.
		*/
		TPixelFormat iPixelFormat;
#ifndef __KERNEL_MODE__
	private:
#endif
		/** Reserved for extension and alignment
		*/
		TUint32 reserved_0;
		};
	
	struct TBufferFormatContext
		{
#ifndef __KERNEL_MODE__
		inline TBufferFormatContext(TResolution aResolution, TDisplayRotation aRotation, TInt aPlane);
#endif
		/** The resolution to be used when the buffer format is processed
		*/
		TResolution iResolution;
		
		/** The rotation to be used when the buffer format is processed
		*/
		TDisplayRotation iRotation;
		
		/** The plane number, starting at zero
		*/
		TInt iPlane;
		};

	inline static const TDesC& Name();
	inline static TVersion VersionRequired(void);
#ifndef __KERNEL_MODE__
	// v1.0 methods
	inline TInt Open(TUint aScreen);
	inline void Close(void);
	inline TInt	GetDisplayInfo(TDes8& aInfo);
	inline TDisplayRotation CurrentRotation(void);
	inline TInt GetCompositionBufferInfo(TUint aBufferIndex, RChunk& aChunk, TInt& aOffset);
	inline void GetCompositionBuffer(TUint& aBufferIndex, TRequestStatus& aStatus);
	inline void CancelGetCompositionBuffer(void);
	inline TInt PostCompositionBuffer(const TRegionFix<TDisplayInfo::KMaxRectangles>* aRegion, TPostCount& aCount );
	inline TInt	PostLegacyBuffer(const TRegionFix<TDisplayInfo::KMaxRectangles>* aRegion, TPostCount& aCount);
	inline TInt RegisterUserBuffer(TBufferId& aBufferId, const RChunk& aChunk, TInt aOffset);
    inline void PostUserBuffer(TBufferId aBufferId, TRequestStatus& aStatus, const TRegionFix<TDisplayInfo::KMaxRectangles>* aRegion, TPostCount& aCount );
    inline void CancelPostUserBuffer(void);
    inline TInt DeregisterUserBuffer(TBufferId aBufferId);
    inline void WaitForPost(TPostCount aTPostCount, TRequestStatus& aStatus);
    inline void CancelWaitForPost(void);
    inline TInt SetRotation(TDisplayRotation aRotation, TBool& aDisplayConfigChanged);
    // added to v1.0
    inline TInt Version(TVersion& aVersion); 
    // v1.1 methods
	inline void NotifyOnDisplayChange(TRequestStatus& aStatus);
	inline void NotifyOnDisplayChangeCancel();
	inline TInt NumberOfResolutions();
	inline TInt GetResolutions(TDes8& aResolutions, TInt& aCount);
	inline TInt SetResolution(const TSize& aRes);
	inline TInt GetResolution(TSize& aSize);
	inline TInt GetTwips(TSize& aTwips);
	inline TInt NumberOfPixelFormats();
	inline TInt GetPixelFormats(TDes8& aFormatsBuf, TInt& aCount);
	inline TInt SetBufferFormat(const TBufferFormat& aBufferFormat);
	inline TInt GetBufferFormat(TBufferFormat& aBufferFormat);
	inline TInt NextPlaneOffset(const TBufferFormat& aBufferFormat, TInt aPlane);
	inline TInt NextLineOffset(const TBufferFormat& aBufferFormat, TInt aPlane);
    // v1.2 methods
	inline TInt NextPlaneOffset(const TBufferFormat& aBufferFormat, const TResolution& aResolution, TDisplayRotation aRotation, TInt aPlane);
	inline TInt NextLineOffset(const TBufferFormat& aBufferFormat, const TResolution& aResolution, TDisplayRotation aRotation, TInt aPlane);
#ifdef _DEBUG
	inline TInt CreateUserBuffer(TBufferFormat& aBufferFormat, RChunk& aChunk);
#endif // _DEBUG
#endif
	};

#include <dispchannel.inl>

#endif /* __DISPLAY_CHANNEL__ */

// EOF