1 // Copyright (c) 2007-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 // Graphics Resource - general functionality

    15 //

    16 

    17 #ifndef SGRESOURCE_H

    18 #define SGRESOURCE_H

    19 

    20 #include <e32std.h>

    21 #include <sgresource/sgconst.h>

    22 

    23 /**

    24 Panic codes defined for use by the Graphics Resource API.

    25 */

    26 enum TSgResourcePanicReason

    27 	{

    28 	ESgPanicNoDriver = 1,

    29 	ESgPanicUnclosedResources = 2,

    30 	ESgPanicBadDrawableHandle = 3,

    31 	ESgPanicBadAttributeArrayIndex = 4

    32 	};

    33 

    34 /**

    35 Panics the calling thread with category “SGRES” and the given panic code.

    36 @param aReason The panic code.

    37 */

    38 inline void Panic(TSgResourcePanicReason aReason);

    39 

    40 /**

    41 A handle to the implementation of the Graphics Resource API 

    42 initialised in the context of a process. It groups miscellaneous functions that 

    43 do not apply to individual drawable resources.

    44 

    45 At least one thread in the process must call RSgDriver::Open() before the 

    46 Graphics Resource API can be used in the context of the process. 

    47 When the Graphics Resource API is no longer needed RSgDriver::Close() should be 

    48 called to release unused resources.  Note that it is possible to call RSgDriver::Open() 

    49 and RSgDriver::Close() from different threads.

    50 */

    51 NONSHARABLE_CLASS(RSgDriver)

    52 	{

    53 public:

    54 	/**

    55 	Default constructor.

    56 	@post The instance of RSgDriver is a null handle.

    57 	*/

    58 	inline RSgDriver();

    59 

    60 	/**

    61 	Initialises the implementation of the Graphics Resource API in the context 

    62 	of a process if it is not initialised already, updates the implementation 

    63 	opening count in the process and returns KErrNone if successful.

    64 	Each successful call to RSgDriver::Open() in a process should be balanced 

    65 	by a corresponding call to RSgDriver::Close() in the same process, but not 

    66 	necessarily from the same thread.

    67 

    68 	Note that an RSgDriver handle should never be bitwise-copied into another 

    69 	but this function should be used instead in all cases, since it is the only 

    70 	way to ensure that the implementation opening count is kept up to date.

    71 	Failure to keep the implementation opening count up to date may result in 

    72 	the implementation of the Graphics Resource API becoming unexpectedly 

    73 	unavailable and, as a consequence, in an abnormal termination of the process.

    74 

    75 	@pre The instance of RSgDriver is a null handle.

    76 	@post The instance of RSgDriver references the implementation of the Graphics 

    77 		Resource API initialised in the context of the process.

    78 	@return KErrNone if successful;

    79 		KErrInUse if the instance of RSgDriver is not a null handle;

    80 		KErrNoMemory if there is not enough system memory to initialise the 

    81 			implementation of the Graphics Resource API;

    82 		KErrNoGraphicsMemory if there is not enough specialised graphics memory

    83 			to initialise the implementation of the Graphics Resource API.

    84 	*/

    85 	IMPORT_C TInt Open();

    86 

    87 	/**

    88 	Decrements the implementation opening count in the process.

    89 	When the count reaches zero, checks whether there are still open handles to

    90 	drawable resources in the process and carries out termination tasks to

    91 	release the internal resources used by the implementation of the Graphics

    92 	Resource API.

    93 

    94 	An attempt to carry out these termination tasks will panic with category

    95 	“SGRES” and code 2 in debug builds if there still are any open handles to 

    96 	drawable resources in the process. In release builds all the open handles 

    97 	to drawable resources in the process are silently closed at this point.

    98 	Calling this function on a null handle has no effect.

    99 

   100 	@post The instance of RSgDriver is a null handle.

   101 	@panic SGRES 2 Debug builds only.  There are open handles to drawable resources 

   102 		in the process during termination.

   103 	*/

   104 	IMPORT_C void Close();

   105 

   106 	/**

   107 	Makes the extension interface specified by the type of the parameter 

   108 	aInterfacePtr available in the context of the process.

   109 	This function stores a pointer to the extension interface in the variable 

   110 	referenced by the parameter aInterfacePtr and returns KErrNone if successful.

   111 

   112 	@pre An RSgDriver has been opened in the context of the process.

   113 	@param[out] aInterfacePtr Reference to a pointer to the interface class that on return points 

   114 		to the extension interface or, in case of error, is set to NULL.

   115 	@return KErrNone if successful;

   116 		KErrBadHandle if the instance of RSgDriver is a null handle;

   117 		KErrExtensionNotSupported if the requested extension interface is not supported.

   118 	*/

   119 	template<class M> inline TInt GetInterface(M*& aInterfacePtr) const;

   120 

   121 	/**

   122 	Returns the version of the implementation of the Graphics Resource API.

   123 	The version comprises 3 numbers: major version number, minor version number 

   124 	and build number.

   125 

   126 	Major revisions mean incompatible changes in the API. 

   127 	Minor revisions mean forward-compatible changes in the API. 

   128 	Build numbers are unrelated to API changes.

   129 

   130 	@return The version of the implementation of the Graphics Resource API.

   131 	*/

   132 	IMPORT_C static TVersion Version();

   133 private:

   134 	/**

   135 	Copy constructor.

   136 	Implementation not provided. Declared private to prevent bit-wise copying 

   137 	of handles.

   138 	*/

   139 	RSgDriver(const RSgDriver&);

   140 

   141 	/**

   142 	Assignment operator.

   143 	Implementation not provided. Declared private to prevent bit-wise copying 

   144 	of handles.

   145 	*/

   146 	const RSgDriver& operator =(const RSgDriver&);

   147 

   148 	/**

   149 	Makes the extension interface with the given UID available in the context 

   150 	of the process.

   151 	This function stores a pointer to the extension interface in the variable 

   152 	referenced by the parameter aInterfacePtr and returns KErrNone if successful.

   153 

   154 	@pre An RSgDriver has been opened in the context of the process.

   155 	@param[in] aInterfaceUid The UID of the extension interface.

   156 	@param[out] aInterfacePtr Reference to an untyped pointer that on return points 

   157 		to the extension interface or, in case of error, is set to NULL.

   158 	@return KErrNone if successful;

   159 		KErrBadHandle if the instance of RSgDriver is a null handle;

   160 		KErrArgument if aInterfaceUid is the null UID;

   161 		KErrExtensionNotSupported if the requested extension interface is not supported.

   162 	*/

   163 	IMPORT_C TInt GetInterface(TUid aInterfaceUid, TAny*& aInterfacePtr) const;

   164 private:

   165 	/** A pointer to an implementation-defined object initially set to NULL by the constructor.*/

   166 	TAny* iImpl;

   167 	};

   168 

   169 /**

   170 An extension attribute.

   171 */

   172 NONSHARABLE_CLASS(TSgAttribute)

   173 	{

   174 public:

   175 	/**

   176 	Default constructor.

   177 	Data members remain uninitialised.

   178 	*/

   179 	inline TSgAttribute();

   180 

   181 	/**

   182 	Constructor which initialises data members to the given values.

   183 	*/

   184 	inline TSgAttribute(TUid aUid, TInt aValue);

   185 public:

   186 	/** A UID that identifies the type of extension attribute.*/

   187 	TUid iUid;

   188 	/** The value of the extension attribute.*/

   189 	TInt iValue;

   190 	};

   191 

   192 /**

   193 Base class of all attribute array classes.

   194 It defines functions for bounds-checked access to extension attributes.

   195 */

   196 NONSHARABLE_CLASS(TSgAttributeArrayBase)

   197 	{

   198 public:

   199 	/**

   200 	Returns the number of extension attributes in the array.

   201 	@return The number of extension attributes in the array.

   202 	*/

   203 	inline TInt Count() const;

   204 

   205 	/**

   206 	Returns a reference to the extension attribute located in the array at the 

   207 	given position.

   208 

   209 	@pre aIndex is equal to or greater than zero and less than the number of 

   210 		extension attributes in the array.

   211 	@param aIndex The position of the extension attribute in the array.

   212 	@return A reference to the extension attribute located in the array at the 

   213 		given position.

   214 	@panic SGRES 4 Debug builds only. aIndex is out of bounds.

   215 	*/

   216 	inline TSgAttribute& operator [](TInt aIndex);

   217 

   218 	/**

   219 	Returns a const-qualified reference to the extension attribute located in 

   220 	the array at the given position.

   221 

   222 	@pre aIndex is equal to or greater than zero and less than the number of 

   223 		extension attributes in the array.

   224 	@param aIndex The position of the extension attribute in the array.

   225 	@return A reference to the extension attribute located in the array at the 

   226 		given position.

   227 	@panic SGRES 4 Debug builds only. aIndex is out of bounds.

   228 	*/

   229 	inline const TSgAttribute& operator [](TInt aIndex) const;

   230 protected:

   231 	/**

   232 	Constructor used by constructors of derived classes to initialise the 

   233 	attribute count.

   234 	@param aCount The number of extension attributes.

   235 	*/

   236 	inline TSgAttributeArrayBase(TInt aCount);

   237 

   238 	/**

   239 	Assignment operator.

   240 	No operation is performed. Allows the compiler to generate assignment 

   241 	operators for derived classes automatically.

   242 	*/

   243 	inline void operator =(const TSgAttributeArrayBase&);

   244 private:

   245 	const TInt iCount;

   246 	};

   247 

   248 /**

   249 A fixed-size array of extension attributes.

   250 It is a thin wrapper with bounds checking for arrays of TSgAttribute.

   251 */

   252 template<TInt S>

   253 NONSHARABLE_CLASS(TSgAttributeArray): public TSgAttributeArrayBase

   254 	{

   255 public:

   256 	/**

   257 	Default constructor.

   258 	Data members remain uninitialised.

   259 	*/

   260 	inline TSgAttributeArray();

   261 private:

   262 	TSgAttribute iAttributes[S];

   263 	};

   264 

   265 /**

   266 A system-wide unique 64-bit identifier that can be used to share a drawable 

   267 resource between processes.

   268 

   269 The actual value of a drawable resource identifier has no meaning to the user 

   270 of the Graphics Resource API, except that 64 zero bits represent the null 

   271 drawable resource identifier, which explicitly identifies no drawable resource.

   272 As a convenience, the constant KSgNullDrawableId is defined as the null drawable 

   273 resource identifier.

   274 */

   275 NONSHARABLE_CLASS(TSgDrawableId)

   276 	{

   277 public:

   278 	/**

   279 	Equality operator.

   280 	Tests whether the given drawable resource identifier is the same as this.

   281 	

   282 	@param aId The drawable resource identifier to compare with this.

   283 	@return ETrue if the 64-bit identifiers are the same, EFalse if not.

   284 	*/

   285 	inline TBool operator ==(TSgDrawableId aId) const;

   286 

   287 	/**

   288 	Inequality operator.

   289 	Tests whether the given drawable resource identifier is different from this.

   290 	

   291 	@param aId The drawable resource identifier to compare with this.

   292 	@return ETrue if the 64-bit identifiers are different, EFalse if they are the same.

   293 	*/

   294 	inline TBool operator !=(TSgDrawableId aId) const;

   295 public:

   296 	/** The 64-bit identifier.*/

   297 	TUint64 iId;

   298 	};

   299 

   300 /**

   301 The null drawable resource identifier.

   302 */

   303 const TSgDrawableId KSgNullDrawableId = {0};

   304 

   305 /**

   306 The UID identifying a RSgDrawable handle.

   307 This must never be changed.

   308 */

   309 const TUid KSgDrawableTypeUid = {0x102858EB};

   310 

   311 /**

   312 A drawable resource handle. 

   313 A null handle is a handle that explicitly does not reference any drawable resource. 

   314 An open handle is a handle that references an existing drawable resource. 

   315 An invalid handle is a handle that is not null but does not reference any 

   316 existing drawable resource. 

   317 Drawable resources are reference-counted so that a drawable resource is not 

   318 destroyed while there still are open handles to it in any process in the system.

   319 

   320 RSgDrawable is not an abstract class, that is, it can be instantiated, 

   321 but it can also be derived from to define subclasses representing types of 

   322 handles that refer only to concrete types of drawable resources, for example, 

   323 image handles. RSgImage is the only subclass of RSgDrawable defined in version 

   324 1.1 of the Graphics Resource API. 

   325 Instances of RSgDrawable are useful when drawable resources created in a 

   326 component have to be passed to another component through a third component that 

   327 cannot depend on the concrete type of the drawable resources being passed.

   328 @see RSgImage

   329 */

   330 NONSHARABLE_CLASS(RSgDrawable)

   331 	{

   332 public:

   333 	/**

   334 	Default constructor.

   335 	@post The instance of RSgDrawable is a null handle.

   336 	*/

   337 	inline RSgDrawable();

   338 

   339 	/**

   340 	Opens a new handle to the drawable resource with the given drawable resource 

   341 	identifier.

   342 	The drawable resource may have been created in the same process or in a 

   343 	different one. This function does not allocate any specialised graphics memory.

   344 

   345 	Note that an RSgDrawable handle should never be bitwise-copied into another 

   346 	but this function should be used instead in all cases, since it is the only 

   347 	way to ensure that the reference count of the drawable resource is kept up 

   348 	to date. Failure to keep the reference count of the resource up to date may 

   349 	result in invalid handles.

   350 

   351 	@pre An RSgDriver handle has been opened in the context of the process.

   352 	@pre The instance of RSgDrawable is a null handle.

   353 	@post The specified drawable resource has its reference count incremented by one.

   354 	@param aId The identifier of the drawable resource.

   355 	@param aAttributes A pointer to an array of extension attributes, 

   356 		if allowed by any extension of the Graphics Resource API, or NULL otherwise.

   357 	@return KErrNone if successful;

   358 		KErrInUse if the instance of RSgDrawable is an open handle;

   359 		KErrArgument if the parameter aId is the null drawable resource identifier;

   360 		KErrNotSupported if the parameter aAttributes is not NULL and one or more 

   361 			of the extension attributes in the array is not defined by any extension 

   362 			of the Graphics Resource API;

   363 		KErrNotFound if the parameter aId cannot be found to refer to an existing 

   364 			drawable resource;

   365 		KErrNoMemory if it fails due to lack of system memory.

   366 	@panic SGRES 1 No RSgDriver handle has been opened in the context of the process.

   367 	*/

   368 	IMPORT_C TInt Open(TSgDrawableId aId, const TSgAttributeArrayBase* aAttributes = NULL);

   369 

   370 	/**

   371 	Closes a handle to a drawable resource. 

   372 	It decrements the reference count of the drawable resource and, if it reaches

   373 	zero, destroys the drawable resource. 

   374 	Calling this function on a null handle has no effect.

   375 

   376 	@pre If the instance of RSgDrawable is not a null handle then an RSgDriver 

   377 		handle has been opened in the context of the process.

   378 	@post The instance of RSgDrawable is a null handle.

   379 	@panic SGRES 1 The instance of RSgDrawable is not a null handle and no 

   380 		RSgDriver handle has been opened in the context of the process.

   381 	@panic SGRES 3 The instance of RSgDrawable is an invalid handle.

   382 	*/

   383 	IMPORT_C void Close();

   384 

   385 	/**

   386 	Returns the identifier of the drawable resource.

   387 	This identifier can be used to open another handle to the drawable resource 

   388 	in the same process or in a different process. 

   389 	Calling this function on a null handle returns the null drawable resource 

   390 	identifier.

   391 

   392 	@pre If the instance of RSgDrawable is not a null handle then an RSgDriver 

   393 		handle has been opened in the context of the process.

   394 	@return The identifier of the drawable resource.

   395 	@panic SGRES 1 The instance of RSgDrawable is not a null handle and no 

   396 		RSgDriver handle has been opened in the context of the process.

   397 	@panic SGRES 3 The instance of RSgDrawable is an invalid handle.

   398 	*/

   399 	IMPORT_C TSgDrawableId Id() const;

   400 

   401 	/**

   402 	Tests whether a handle is null.

   403 	@return ETrue if the instance of RSgDrawable is a null handle; EFalse otherwise.

   404 	*/

   405 	inline TBool IsNull() const;

   406 

   407 	/**

   408 	Returns the UID corresponding to the concrete type of the drawable resource 

   409 	referenced by a handle at run-time. 

   410 	Calling this function on a null handle returns the null UID. 

   411 	In version 1.1 of the Graphics Resource API every drawable resource is an image, 

   412 	so this function always returns KSgImageTypeUid when called on an open handle.

   413 

   414 	@pre If the instance of RSgDrawable is not a null handle then an RSgDriver 

   415 		handle has been opened in the context of the process.

   416 	@return The UID corresponding to the concrete type of the drawable resource.

   417 	@panic SGRES 1 The instance of RSgDrawable is not a null handle and no 

   418 		RSgDriver handle has been opened in the context of the process.

   419 	@panic SGRES 3 The instance of RSgDrawable is an invalid handle.

   420 	*/

   421 	IMPORT_C TUid DrawableType() const;

   422 

   423 	/**

   424 	Makes the extension interface specified by the type of the parameter 

   425 	aInterfacePtr available on a drawable resource.

   426 	This function stores a pointer to the extension interface in the variable 

   427 	referenced by the parameter aInterfacePtr and returns KErrNone if successful.

   428 	The returned extension interface is tied to the drawable resource, that is, 

   429 	calls to functions in the returned extension interface operate on the 

   430 	drawable resource.

   431 

   432 	@pre An RSgDriver handle has been opened in the context of the process.

   433 	@pre The instance of RSgDrawable is an open handle.

   434 	@param[out] aInterfacePtr Reference to a pointer to the interface class. that on return points 

   435 		to the extension interface or, in case of error, is set to NULL.

   436 	@return KErrNone if successful;

   437 		KErrBadHandle if the instance of RSgDrawable is a null handle;

   438 		KErrExtensionNotSupported if the requested extension interface is not supported.

   439 	@panic SGRES 1 No RSgDriver handle has been opened in the context of the process.

   440 	@panic SGRES 3 The instance of RSgDrawable is an invalid handle.

   441 	*/

   442 	template<class M> inline TInt GetInterface(M*& aInterfacePtr) const;

   443 protected:

   444 	/**

   445 	Handle base constructor.

   446 	Used by constructors of derived classes to initialise the handle type.

   447 	@post The instance of RSgDrawable is a null handle.

   448 	@param aHandleType The UID identifying the handle type.

   449 	*/

   450 	inline RSgDrawable(TUid aHandleType);

   451 private:

   452 	/**

   453 	Copy constructor.

   454 	Implementation not provided. Declared private to prevent bit-wise copying 

   455 	of handles.

   456 	*/

   457 	RSgDrawable(const RSgDrawable&);

   458 

   459 	/**

   460 	Assignment operator.

   461 	Implementation not provided. Declared private to prevent bit-wise copying 

   462 	of handles.

   463 	*/

   464 	const RSgDrawable& operator =(const RSgDrawable&);

   465 

   466 	/**

   467 	Makes the extension interface with the given UID available on a drawable 

   468 	resource.

   469 	This function stores a pointer to the extension interface in the variable 

   470 	referenced by the parameter aInterfacePtr and returns KErrNone if successful.

   471 	The returned extension interface is tied to the drawable resource, that is, 

   472 	calls to functions in the returned extension interface operate on the 

   473 	drawable resource.

   474 

   475 	@pre An RSgDriver handle has been opened in the context of the process.

   476 	@pre The instance of RSgDrawable is an open handle.

   477 	@param[in] aInterfaceUid The UID of the extension interface.

   478 	@param[out] aInterfacePtr Reference to an untyped pointer that on return points 

   479 		to the extension interface or, in case of error, is set to NULL.

   480 	@return KErrNone if successful;

   481 		KErrBadHandle if the instance of RSgDrawable is a null handle;

   482 		KErrArgument if aInterfaceUid is the null UID;

   483 		KErrExtensionNotSupported if the requested extension interface is not supported.

   484 	@panic SGRES 1 No RSgDriver handle has been opened in the context of the process.

   485 	@panic SGRES 3 The instance of RSgDrawable is an invalid handle.

   486 	*/

   487 	IMPORT_C TInt GetInterface(TUid aInterfaceUid, TAny*& aInterfacePtr) const;

   488 protected:

   489 	/**

   490 	A UID permanently set by the constructor to the constant 

   491 	KSgDrawableTypeUid, except for subclasses of RSgDrawable, in which case it 

   492 	is permanently set by the constructor to the UID corresponding to the 

   493 	concrete type of drawable resource referenced by instances of the subclass.

   494 	*/

   495 	const TUid iHandleType;

   496 

   497 	/** A pointer to an implementation-defined object initially set to NULL by the constructor.*/

   498 	TAny* iImpl;

   499 	};

   500 

   501 #include <sgresource/sgresource.inl>

   502 

   503 #endif // SGRESOURCE_H