1 // Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies).

     2 // All rights reserved.

     3 // This component and the accompanying materials are made available

     4 // under the terms of "Eclipse Public License v1.0"

     5 // which accompanies this distribution, and is available

     6 // at the URL "http://www.eclipse.org/legal/epl-v10.html".

     7 //

     8 // Initial Contributors:

     9 // Nokia Corporation - initial contribution.

    10 //

    11 // Contributors:

    12 //

    13 // Description:

    14 // Surface Manager API

    15 // 

    16 //

    17 

    18 /**

    19  @file

    20  @publishedPartner

    21  @prototype

    22 */

    23 

    24 #ifndef __SURFACEMANAGER_H__

    25 #define __SURFACEMANAGER_H__

    26 

    27 #ifndef __KERNEL_MODE__

    28 #include <e32std.h>

    29 #endif

    30 

    31 #include <e32cmn.h>

    32 #include <e32ver.h>

    33 #include <pixelformats.h>

    34 #include <graphics/surface.h>

    35 

    36 class RSurfaceManagerDriver;

    37 

    38 /**

    39 RSurface Manager User API.

    40 */

    41 class RSurfaceManager

    42 	{

    43 public:

    44 

    45 	class THintPair

    46 		{

    47 	public:

    48 		/** UID key number */

    49 		TUid iKey;

    50 		/** Integer key value */

    51 		TInt iValue;

    52 		/** Is the value modifiable */

    53 		TBool iMutable;

    54 	public:

    55 		inline void Set(TUid aKey,TInt aValue,TBool aMutable);

    56 		};

    57 	

    58 	enum TCacheAttribute

    59 		{

    60 		/** CPU cached */

    61 		ECached = 0,

    62 		/** Non CPU cached */

    63 		ENotCached = 1

    64 		};

    65 

    66 	class TSurfaceCreationAttributes

    67 		{

    68 	public:

    69 		/** Width and height of the surface in pixels. */

    70 		TSize iSize;

    71 		/** Number of buffers in the surface. */

    72 		TInt iBuffers;

    73 		/** The pixel format. */

    74 		TUidPixelFormat iPixelFormat;

    75 		/** Minimum or required number of bytes between start of one line and

    76 		start of next. */

    77 		TInt iStride;

    78 		/** Minimum or required offset to the first buffer from the base of the

    79 		chunk. Typically this will be set to 0. The value specified for the

    80 		offset must comply with the alignment specified in iAlignment.

    81 		

    82 		If iAlignment is page aligned, this value will be rounded up to a

    83 		multiple of the page size when the surface is created, therefore the

    84 		surface info must be queried for the actual value used. */

    85 		TInt iOffsetToFirstBuffer;

    86 		/** Alignment applied to the base address of each buffer in the surface:

    87 		1, 2, 4, 8 ,16, 32, 64 bytes or EPageAligned. */

    88 		TInt iAlignment;

    89 		/** Require physically contiguous memory. This value will be ignored if

    90 		using a chunk which already exists. */

    91 		TBool iContiguous;

    92 		/** Caching attribute to create chunk memory. This value will be 

    93 		ignored if using a chunk which already exists. */

    94 		TCacheAttribute iCacheAttrib;

    95 		/** Minimum or required offset between the start of one buffer and the

    96 		start of the next one in bytes. When set to 0 the surface manager will

    97 	   	choose how buffers are laid out within the chunk. If it is too small

    98 		and doesn't fit with the alignment, CreateSurface() will return

    99 		KErrArgument. */

   100 		TInt iOffsetBetweenBuffers;

   101 		/** Array of hints which should be associated with the surface. This

   102 		array must not contain duplicate hint keys. */

   103 		THintPair* iSurfaceHints;

   104 		/** Number of hints in the array iSurfaceHints. The number should not

   105 		exceed the maximum number supported by the surface manager, see 

   106 		GetSurfaceManagerAttrib(EMaxNumberOfHints). */

   107 		TInt iHintCount;

   108 		/** Should the surface be mappable. If EFalse any call to MapSurface()

   109 		will fail with KErrNotSupported -- Note, some architectures may not

   110 		support mappable surfaces. */

   111 		TBool iMappable;

   112 	public:

   113 		inline TSurfaceCreationAttributes();

   114 		};

   115 

   116 	class TSurfaceInfoV01

   117 		{

   118 	public:

   119 		/** Width and height of the surface in pixels */

   120 		TSize iSize;

   121 		/** Number of buffers in the surface */

   122 		TInt iBuffers;

   123 		/** The pixel format */

   124 		TUidPixelFormat iPixelFormat;

   125 		/** Number of bytes between start of one line and start of next */

   126 		TInt iStride;

   127 		/** Has physically contiguous memory */

   128 		TBool iContiguous;

   129 		/** Specified if the underlying chunk is CPU cached or not */

   130 		TCacheAttribute iCacheAttrib;

   131 		/** ETrue if the surface can be mapped */

   132 		TBool iMappable;

   133 		};

   134 	

   135 	enum TSurfaceManagerAttrib

   136 		{

   137 		/** Maximum number of hints per surface */

   138 		EMaxNumberOfHints = 0x0 

   139 		};

   140 

   141 	/** Package buf used to pass information about a surface from the driver */

   142 	typedef TPckgBuf<TSurfaceInfoV01> TInfoBuf;

   143 	/** Package buf used to pass the surface creation attributes to the device driver */

   144 	typedef TPckgBuf<TSurfaceCreationAttributes> TSurfaceCreationAttributesBuf;

   145 

   146 	enum TSyncOperation

   147 		{

   148 		/** Synchronize before non CPU hardware reads from the memory, i.e. if the

   149 		buffer is cached and may have been written to by the CPU, this type of

   150 		synchronisation should be used before a peripheral is used to read from the

   151 		buffer's memory */

   152 		ESyncBeforeNonCPURead,

   153 		/** Synchronize before non CPU hardware writes to the memory, i.e. if the

   154 		buffer is cached and may have been written to by the CPU, this type of

   155 		synchronisation should be used before a peripheral is used to write to the

   156 		buffer's memory */

   157 		ESyncBeforeNonCPUWrite,

   158 		/** Synchronize after non CPU hardware writes to the memory, i.e. if the

   159 		buffer is cached, this type of synchronisation should be used after a

   160 		peripheral has been used to write to the buffer's memory */

   161 		ESyncAfterNonCPUWrite

   162 		};

   163 

   164 	enum TPageAlignment

   165 		{

   166 		/** Specifies iAlignment is a page alignment */

   167 		EPageAligned = -1

   168 		};

   169 	

   170 public:

   171 #ifndef __KERNEL_MODE__

   172 	IMPORT_C RSurfaceManager();

   173 	IMPORT_C TInt Open();

   174 	IMPORT_C void Close();

   175 	IMPORT_C TInt CreateSurface(const TSurfaceCreationAttributesBuf& aReqs, TSurfaceId& aSurfaceId);

   176 	IMPORT_C TInt CreateSurface(const TSurfaceCreationAttributesBuf& aReqs, TSurfaceId& aSurfaceId, const RChunk& aChunkHandle);

   177 	IMPORT_C TInt OpenSurface(const TSurfaceId& aSurfaceId);

   178 	IMPORT_C TInt CloseSurface(const TSurfaceId& aSurfaceId);

   179 	IMPORT_C TInt MapSurface(const TSurfaceId& aSurfaceId, RChunk& aHandle);

   180 	IMPORT_C TInt SurfaceInfo(const TSurfaceId& aSurfaceId, TInfoBuf& aInfo);

   181 	IMPORT_C TInt SynchronizeCache(const TSurfaceId& aSurfaceId, TInt aBuffer, TSyncOperation aOperation);

   182 	IMPORT_C TInt GetSurfaceManagerAttrib(TSurfaceManagerAttrib aAttrib, TInt& aValue);

   183 	IMPORT_C TInt GetSurfaceHint(const TSurfaceId& aSurfaceId, THintPair& aHint);

   184 	IMPORT_C TInt SetSurfaceHint(const TSurfaceId& aSurfaceId, const THintPair& aHint);

   185 	IMPORT_C TInt AddSurfaceHint(const TSurfaceId&aSurface, const THintPair& aHint);

   186 	IMPORT_C TInt GetBufferOffset(const TSurfaceId& aSurfaceId, TInt aBuffer, TInt& aOffset);

   187 #endif	//__KERNEL_MODE__	

   188 private:

   189 	inline RSurfaceManagerDriver& Driver();

   190 private:

   191 	TInt32 iDriverBuf[4];

   192 	};

   193 

   194 //

   195 // THintPair inline

   196 //

   197 

   198 /**

   199 Sets key, value and mutability of the hint.

   200 @param aKeyUid The UID of the key

   201 @param aValue The value of the hint

   202 @param aMutable ETrue if the hint value is mutable

   203 */

   204 inline void RSurfaceManager::THintPair::Set(TUid aKeyUid,TInt aValue,TBool aMutable)

   205 	{

   206 	iKey = aKeyUid;

   207 	iValue = aValue;

   208 	iMutable = aMutable;

   209 	}

   210 

   211 //

   212 // TSurfaceCreationAttributes inline

   213 //

   214 

   215 /**

   216 Default constructor, zero initializes all attributes.

   217 */

   218 inline RSurfaceManager::TSurfaceCreationAttributes::TSurfaceCreationAttributes()

   219 	{

   220 	memclr(this, sizeof(TSurfaceCreationAttributes));

   221 	}

   222 

   223 #endif //__SURFACEMANAGER_H__