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 //

    15 

    16 /**

    17  @file

    18  @publishedPartner

    19  @prototype

    20 */

    21 

    22 #ifndef SGRESOURCEADAPTER_H

    23 #define SGRESOURCEADAPTER_H

    24 

    25 #include <graphics/sgresource.h>

    26 #include <pixelformats.h>

    27 

    28 

    29 /**

    30 @publishedPartner

    31 @prototype

    32 @deprecated

    33 

    34 The file name of the Graphics Resource Adapter DLL.

    35 */

    36 _LIT(KSgResourceAdapterLibraryName, "graphicsresourceadapter");

    37 

    38 

    39 /**

    40 @publishedPartner

    41 @prototype

    42 @deprecated

    43 

    44 The UID3 value in the compound identifier of the Graphics Resource Adapter DLL.

    45 */

    46 const TUid KSgResourceAdapterLibraryUid = {0x10285A71};

    47 

    48 

    49 /**

    50 @publishedPartner

    51 @prototype

    52 @deprecated

    53 

    54 The category name of the panics raised by the Graphics Resource API.

    55 */

    56 _LIT(KSgResourcePanicCategory, "SGRES");

    57 

    58 

    59 /**

    60 @publishedPartner

    61 @prototype

    62 @deprecated

    63 

    64 The reason numbers of the panics raised by the Graphics Resource API.

    65 */

    66 enum TSgResourcePanicReason

    67 	{

    68 	/**

    69 	SGRES 1 In debug builds, there still are open handles to graphics resources in

    70 	a process when the process termination tasks are carried out.

    71 	*/

    72 	ESgPanicUnclosedResources = 1,

    73 	/**

    74 	SGRES 2 In debug builds, an RSgDrawable handle is invalid.

    75 	*/

    76 	ESgPanicBadDrawableHandle = 2,

    77 	/**

    78 	SGRES 3 In debug builds, an RSgImage handle is invalid.

    79 	*/

    80 	ESgPanicBadImageHandle = 3,

    81 	/**

    82 	SGRES 4 In debug builds, an RSgImageCollection handle is invalid.

    83 	*/

    84 	ESgPanicBadImageCollectionHandle = 4,

    85 	/**

    86 	SGRES 5 In debug builds, the Graphics Resource driver is not initialised for

    87 	use in the context of the calling process.

    88 	*/

    89 	ESgPanicNoDriver = 5

    90 	};

    91 

    92 

    93 /**

    94 @publishedPartner

    95 @prototype

    96 @deprecated

    97 

    98 Panics the current thread specifying a panic reason from the Graphics Resource API.

    99 */

   100 inline void Panic(TSgResourcePanicReason aReason);

   101 

   102 

   103 /**

   104 @publishedPartner

   105 @prototype

   106 @deprecated

   107 

   108 This constant consists of all the flags specifying usage of a graphics resource

   109 as a source of any rendering pipeline.

   110 */

   111 const TUint32 KSgUsageAllSources = ESgUsageDirectGdiSource | ESgUsageCompositionSource

   112 	| ESgUsageScreenSource | ESgUsageOpenGlesTexture2D | ESgUsageOpenVgImage

   113 	| ESgUsageOpenGles2Texture2D | ESgUsageWindowGcSource;

   114 

   115 

   116 /**

   117 @publishedPartner

   118 @prototype

   119 @deprecated

   120 

   121 This constant consists of all the flags specifying usage of a graphics resource

   122 as a target of any rendering pipeline.

   123 */

   124 const TUint32 KSgUsageAllTargets = ESgUsageDirectGdiTarget | ESgUsageCompositionTarget

   125 	| ESgUsageOpenGlesTarget | ESgUsageOpenVgTarget | ESgUsageEglCopyBuffersTarget

   126 	| ESgUsageOpenGles2Target;

   127 

   128 

   129 /**

   130 @publishedPartner

   131 @prototype

   132 @deprecated

   133 

   134 The default open mode for drawable resources.

   135 */

   136 const TUint32 KSgDefaultOpenMode = 0;

   137 

   138 

   139 /**

   140 @publishedPartner

   141 @prototype

   142 @deprecated

   143 

   144 This interface must be implemented by all the user-side objects in the adaptation

   145 layer of the Graphics subsystem which are referenced by instances of any handle

   146 class in the Graphics Resource API. The interface between the user-side and the

   147 kernel-side parts of the adaptation layer is outside the scope of the specification

   148 of the Graphics Resource API.

   149 

   150 Each resource referenced by a handle opened in the context of a process must be

   151 represented by an adapter object inside the process. Both the adapter object and

   152 the resource itself have reference counts. The reference count for the adapter object

   153 equals the number of handles to the resource open in the process, while the adapter

   154 object counts as a single reference to the resource.

   155 

   156 Adapter objects can be shared between all the threads in a process. This has two

   157 consequences:

   158 	- Adapter objects must be allocated in a multi-threaded heap owned by the Graphics

   159 	  Resource Adapter singleton.

   160 	- Access to adapter objects must be synchronised by means of a mutual exclusion

   161 	  mechanism.

   162 */

   163 class MSgResourceAdapter

   164 	{

   165 public:

   166 	/**

   167 	@publishedPartner

   168 	@prototype

   169 	@deprecated

   170 

   171 	Closes this adapter object by decrementing its reference count by one and, if the

   172 	count becomes zero, destroying the adapter object. If the adapter object is

   173 	destroyed then the reference count for the represented resource is decremented

   174 	by one.

   175 

   176 	@see RSgDrawable::Close()

   177 	@see RSgImageCollection::Close()

   178 	*/

   179 	virtual void Close() = 0;

   180 	};

   181 

   182 

   183 /**

   184 @publishedPartner

   185 @prototype

   186 @deprecated

   187 

   188 This interface must be implemented by all the user-side objects in the adaptation

   189 layer of the Graphics subsystem which are referenced by instances of RSgDrawable.

   190 The interface between the user-side and the kernel-side parts of the adaptation

   191 layer is outside the scope of the specification of the Graphics Resource API.

   192 

   193 @see RSgDrawable

   194 */

   195 class MSgDrawableAdapter: public MSgResourceAdapter

   196 	{

   197 public:

   198 	/**

   199 	@publishedPartner

   200 	@prototype

   201 	@deprecated

   202 

   203 	Retrieves the unique identifier of the drawable resource represented by this

   204 	adapter object.

   205 

   206 	@return The unique identifier of the drawable resource.

   207 	@see RSgDrawable::Id()

   208 	*/

   209 	virtual const TSgDrawableId& Id() const = 0;

   210 	/**

   211 	@publishedPartner

   212 	@prototype

   213 	@deprecated

   214 

   215 	Retrieves the actual type of the drawable resource represented by this adapter

   216 	object as a globally unique identifier.

   217 

   218 	@return The actual type of the drawable resource as a globally unique identifier.

   219 	@see RSgDrawable::DrawableType()

   220 	*/

   221 	virtual TUid DrawableType() const = 0;

   222 	/**

   223 	@publishedPartner

   224 	@prototype

   225 	@deprecated

   226 

   227 	Makes an extension interface available on the drawable resource represented by

   228 	this adapter object.

   229 

   230 	@param aInterfaceUid Globally unique identifier of the interface to be made

   231 	       available.

   232 	@param aInterfacePtr On return, a pointer to the specified interface.

   233 	@pre The specified interface is supported on the drawable resource.

   234 	@post The specified interface is available until this adapter object is destroyed.

   235 	@return KErrNone if successful.

   236 	@return KErrExtensionNotSupported if the specified interface is not supported

   237 	        on the drawable resource.

   238 	@return KErrNoMemory if there is not enough system memory.

   239 	@see RSgDrawable::GetInterface()

   240 	*/

   241 	virtual TInt GetInterface(TUid aInterfaceUid, TAny*& aInterfacePtr) = 0;

   242 	};

   243 

   244 

   245 class TSgImageInfo;

   246 class RSgImage;

   247 class MSgImageAdapter;

   248 class MSgImageCollectionAdapter;

   249 

   250 /**

   251 @publishedPartner

   252 @prototype

   253 @deprecated

   254 

   255 This interface must be implemented by the Graphics Resource Adapter singleton.

   256 There must be a single instance of the adaptation layer class that implements

   257 this interface in each process using the Graphics Resource API.

   258 */

   259 class MSgDriverAdapter

   260 	{

   261 public:

   262 	/**

   263 	@publishedPartner

   264 	@prototype

   265 	@deprecated

   266 

   267 	Creates a new instance of the singleton class and carries out the initialisation

   268 	tasks needed to use the Graphics Resource API in the context of the calling

   269 	process. This is the only function that must be exported by the Graphics Resource

   270 	Adapter DLL, at ordinal 1.

   271 

   272 	@param aPtr On return, a pointer to the new instance of the singleton class.

   273 	@return KErrNone if successful.

   274 	@return KErrNoMemory if there is not enough system memory.

   275 	@see SgDriver::Open()

   276 	*/

   277 	IMPORT_C static TInt New(MSgDriverAdapter*& aPtr);

   278 	/**

   279 	@publishedPartner

   280 	@prototype

   281 	@deprecated

   282 

   283 	Deletes an instance of the singleton class and carries out the termination tasks

   284 	needed to release the internal resources allocated for the calling process.

   285 

   286 	@see SgDriver::Close()

   287 	*/

   288 	virtual void Delete() = 0;

   289 	/**

   290 	@publishedPartner

   291 	@prototype

   292 	@deprecated

   293 

   294 	Retrieves the list of image pixel formats supported on this device for a

   295 	specified usage.

   296 

   297 	@param aInfo The image attributes. aInfo.iPixelFormat is ignored.

   298 	@param aPixelFormats A pointer to an array that on return will contain the

   299 	       supported pixel formats. If this parameter is null, then this function

   300 	       will just return the number of supported pixel formats in aCount.

   301 	@param aCount On input, the number of elements in the array pointed to by

   302 	       aPixelFormats if not null, ignored otherwise. On return, the actual number

   303 	       of supported pixel formats. If this number is greater than the number of

   304 	       elements in the array, then the array will be filled with as many pixel

   305 	       formats as it can hold and the function will return KErrOverflow.

   306 	@pre aInfo is valid.

   307 	@pre If aPixelFormats is not null then aCount is greater than zero.

   308 	@return KErrNone if successful.

   309 	@return KErrArgument if aInfo is invalid or if aPixelFormats is not null and

   310 	        aCount is negative.

   311 	@return KErrOverflow if the actual number of supported pixel formats is greater

   312 	        than the number of elements in the array pointed to by aPixelFormats.

   313 	@return KErrNoMemory if there is not enough system memory.

   314 	@see RSgImage::GetPixelFormats()

   315 	*/

   316 	virtual TInt GetPixelFormats(const TSgImageInfo& aInfo, TUidPixelFormat* aPixelFormats, TInt& aCount) = 0;

   317 	/**

   318 	@publishedPartner

   319 	@prototype

   320 	@deprecated

   321 

   322 	Creates an image with the specified attributes and, optionally, the specified

   323 	initial contents.

   324 

   325 	@param aInfo The attributes of the image to be created.

   326 	@param aDataAddress The base address of the pixel data used to populate the

   327 	       new image. If this value is null, the initial contents of the image are

   328 	       undefined. If aInfo specifies that the new image is constant, this value

   329 	       must not be null.

   330 	@param aDataStride The number of bytes between rows of the pixel data used to

   331 	       populate the new image.

   332 	@param aResult On return, a pointer to the adapter object that represents the

   333 	       new image.

   334 	@pre aInfo is supported.

   335 	@pre aResult is null.

   336 	@post aResult points to an adapter object that represents a newly created image

   337 	      with the specified attributes and initial contents. The initial reference

   338 	      count for the image is one.

   339 	@return KErrNone if successful.

   340 	@return KErrInUse if aResult was not null.

   341 	@return KErrArgument if aInfo is invalid.

   342 	@return KErrNoInitializationData if aInfo requests a constant image and aDataAddress

   343 	        is null.

   344 	@return KErrTooBig if the size specified in aInfo is too large.

   345 	@return KErrNotSupported if aInfo is not supported.

   346 	@return KErrNoMemory if there is not enough system memory.

   347 	@return KErrNoSpecializedMemory if there is not enough specialised graphics memory.

   348 	@see RSgImage::Create()

   349 	*/

   350 	virtual TInt CreateImage(const TSgImageInfo& aInfo, const TAny* aDataAddress, TInt aDataStride, MSgDrawableAdapter*& aResult) = 0;

   351 	/**

   352 	@publishedPartner

   353 	@prototype

   354 	@deprecated

   355 

   356 	Creates an image with the specified attributes and initial contents copied

   357 	from an existing image.

   358 

   359 	@param aInfo The attributes of the image to be created.

   360 	@param aImage A pointer to the adapter object that represents the existing

   361 	       image to be copied.

   362 	@param aResult On return, a pointer to the adapter object that represents the

   363 	       new image.

   364 	@pre aInfo is supported.

   365 	@pre aImage is not null.

   366 	@pre The size and the pixel format specified in aInfo must be the same as the

   367 	     size and the pixel format of the image represented by aImage.

   368 	@pre aResult is null.

   369 	@post aResult points to an adapter object that represents a newly created image

   370 	      with the specified attributes and initial contents. The initial reference

   371 	      count for the image is one.

   372 	@return KErrNone if successful.

   373 	@return KErrInUse if aResult was not null.

   374 	@return KErrArgument if aInfo is invalid or if aImage is null.

   375 	@return KErrNotSupported if aInfo is not supported or if the size and the pixel

   376 	        format specified in aInfo are not the same as the size and the pixel

   377 	        format of the image represented by aImage.

   378 	@return KErrNoMemory if there is not enough system memory.

   379 	@return KErrNoSpecializedMemory if there is not enough specialised graphics memory.

   380 	@see RSgImage::Create()

   381 	*/

   382 	virtual TInt CreateImage(const TSgImageInfo& aInfo, MSgImageAdapter* aImage, MSgDrawableAdapter*& aResult) = 0;

   383 	/**

   384 	@publishedPartner

   385 	@prototype

   386 	@deprecated

   387 

   388 	Creates an image collection with the specified attributes.

   389 

   390 	@param aInfo The image attributes of the collection to be created.

   391 	@param aImageCount The number of images in the collection to be created.

   392 	@param aResult On return, a pointer to the adapter object that represents the

   393 	       new image collection.

   394 	@pre aInfo is supported and specifies mutable images.

   395 	@pre aImageCount is greater than zero.

   396 	@pre aResult is null.

   397 	@post aResult points to an adapter object that represents a newly created image

   398 	      collection with the specified attributes. The initial reference count

   399 	      for the image collection is one.

   400 	@return KErrNone if successful.

   401 	@return KErrInUse if aResult was not null.

   402 	@return KErrArgument if aInfo is invalid or if aImageCount is negative or zero.

   403 	@return KErrTooBig if the size specified in aInfo is too large.

   404 	@return KErrNotSupported if aInfo is not supported or does not specify mutable

   405 	        images.

   406 	@return KErrNoMemory if there is not enough system memory.

   407 	@return KErrNoSpecializedMemory if there is not enough specialised graphics memory.

   408 	@see RSgImageCollection::Create()

   409 	*/

   410 	virtual TInt CreateImageCollection(const TSgImageInfo& aInfo, TInt aImageCount, MSgImageCollectionAdapter*& aResult) = 0;

   411 	/**

   412 	@publishedPartner

   413 	@prototype

   414 	@deprecated

   415 

   416 	Creates a set of image collections that share a single memory chunk.

   417 

   418 	@param aInfos An array of aCollectionCount elements with the image attributes

   419 	       of each of the collections to be created.

   420 	@param aImageCount The number of images in each of the collections to be created.

   421 	@param aCollections On return, an array of pointers to the adapter objects that

   422 	       represent the new image collections.

   423 	@param aCollectionCount The number of image collections to be created.

   424 	@pre All the elements of aInfos are supported and specify mutable images.

   425 	@pre aImageCount is greater than zero.

   426 	@pre All the pointers in aCollections are null.

   427 	@pre aCollectionCount is greater than zero.

   428 	@post The elements of aCollections point to aCollectionCount adapter objects that

   429 	      represent newly created image collections with the specified attributes.

   430 	      The initial reference count for each of the image collections is one.

   431 	@return KErrNone if successful.

   432 	@return KErrInUse if any of the pointers in aCollections was not null.

   433 	@return KErrArgument if any element of aInfos is invalid, if aImageCount is

   434 	        negative or zero, or if aCollectionCount is negative or zero.

   435 	@return KErrTooBig if any of the sizes specified in aInfos is too large.

   436 	@return KErrNotSupported if any element of aInfos is not supported or does not

   437 	        specify mutable images.

   438 	@return KErrNoMemory if there is not enough system memory.

   439 	@return KErrNoSpecializedMemory if there is not enough specialised graphics memory.

   440 	@see RSgImageCollection::Create()

   441 	*/

   442 	virtual TInt CreateImageCollections(const TSgImageInfo aInfos[], TInt aImageCount,

   443 	                                    MSgImageCollectionAdapter* aCollections[], TInt aCollectionCount) = 0;

   444 	/**

   445 	@publishedPartner

   446 	@prototype

   447 	@deprecated

   448 

   449 	Opens a new handle to a drawable resource. If there are no handles to the drawable

   450 	resource open in the calling process then this function creates a new adapter

   451 	object that represents the drawable resource in the context of the calling process.

   452 	Otherwise this function just increments the reference count of the existing adapter

   453 	object that represents the drawable resource in the context of the calling process.

   454 

   455 	@param aId The unique identifier of the drawable resource.

   456 	@param aMode Flags controlling how the drawable resource is opened. The only value

   457 	       of this parameter which it is mandatory to support is KSgDefaultOpenMode.

   458 	       Extra opening options may be defined by an implementation of the Graphics

   459 	       Resource API and made available through additional functions.

   460 	@param aHandleType The type of the handle which is to store the reference to

   461 	       the specified drawable resource as a globally unique identifier.

   462 	@param aResult On return, a pointer to the adapter object that represents the

   463 	       specified drawable resource.

   464 	@pre aId identifies an existing drawable resource.

   465 	@pre All of the requested opening options in aMode are supported.

   466 	@pre aHandleType specifies an instance of RSgDrawable or any other handle type

   467 	     that is compatible with the actual type of the specified drawable resource.

   468 	@pre aResult is null.

   469 	@post aResult points to either a newly created or an existing adapter object

   470 	      that represents the drawable resource specified by its unique identifier.

   471 	      If a new adapter object is created then its initial reference count is

   472 	      one and the reference count for the drawable resource itself is incremented

   473 	      by one. Otherwise only the reference count for the adapter object is

   474 	      incremented by one.

   475 	@return KErrNone if successful.

   476 	@return KErrInUse if aResult was not null.

   477 	@return KErrArgument if aId is the null drawable resource identifier.

   478 	@return KErrNotFound if aId cannot be found to refer to an existing drawable

   479 	        resource.

   480 	@return KErrPermissionDenied if this process is not permitted to access the

   481 	        drawable resource specified by aId.

   482 	@return KErrNotSupported if any of the requested opening options in aMode is

   483 	        not supported or if aHandleType is not compatible with the actual type

   484 	        of the drawable resource specified by aId.

   485 	@return KErrNoMemory if there is not enough system memory.

   486 	@see RSgDrawable::Open()

   487 	*/

   488 	virtual TInt OpenDrawable(const TSgDrawableId& aId, TUint32 aMode, TUid aHandleType, MSgDrawableAdapter*& aResult) = 0;

   489 	/**

   490 	@publishedPartner

   491 	@prototype

   492 	@deprecated

   493 

   494 	Tests whether aDrawable references an existing adapter object representing a

   495 	drawable resource. This function is called in debug builds to detect invalid

   496 	RSgDrawable handles.

   497 

   498 	@return ETrue if aDrawable is a valid reference to an adapter object representing

   499 	        a drawable resource, EFalse otherwise.

   500 	*/

   501 	virtual TBool CheckDrawable(const MSgResourceAdapter& aDrawable) const = 0;

   502 	/**

   503 	@publishedPartner

   504 	@prototype

   505 	@deprecated

   506 

   507 	Tests whether aImage references an existing adapter object representing an image.

   508 	This function is called in debug builds to detect invalid RSgImage handles.

   509 

   510 	@return ETrue if aImage is a valid reference to an adapter object representing

   511 	        an image, EFalse otherwise.

   512 	*/

   513 	virtual TBool CheckImage(const MSgResourceAdapter& aImage) const = 0;

   514 	/**

   515 	@publishedPartner

   516 	@prototype

   517 	@deprecated

   518 

   519 	Tests whether aImageCollection references an existing adapter object representing

   520 	an image collection. This function is called in debug builds to detect invalid

   521 	RSgImageCollection handles.

   522 

   523 	@return ETrue if aImageCollection is a valid reference to an adapter object

   524 	        representing an image collection, EFalse otherwise.

   525 	*/

   526 	virtual TBool CheckImageCollection(const MSgResourceAdapter& aImageCollection) const = 0;

   527 	/**

   528 	@publishedPartner

   529 	@deprecated

   530 	@test

   531 

   532 	Retrieves the number of handles to graphics resources open in the calling process.

   533 

   534 	@return The number of handles to graphics resources open in the calling process.

   535 	*/

   536 	virtual TInt ResourceCount() const = 0;

   537 	/**

   538 	@publishedPartner

   539 	@deprecated

   540 	@test

   541 

   542 	Marks the start of cell checking on the heap for adapter objects. Calls to this

   543 	function can be nested but each call must be matched by a corresponding call to

   544 	AllocMarkEnd().

   545 

   546 	@see RAllocator::__DbgMarkStart()

   547 	*/

   548 	virtual void AllocMarkStart() = 0;

   549 	/**

   550 	@publishedPartner

   551 	@deprecated

   552 	@test

   553 

   554 	Marks the end of cell checking at the current nesting level on the heap for

   555 	adapter objects. Each call to this function must match an earlier call to

   556 	AllocMarkStart().

   557 

   558 	This function checks that the number of cells allocated in the heap for adapter

   559 	objects, at the current nesting level, is aCount. If the check fails then an

   560 	SGALLOC:nnnnnnnn panic is raised, where nnnnnnnn is the hexadecimal address

   561 	of the first orphaned cell.

   562 

   563 	@param aCount The number of allocated heap cells expected.

   564 	@see RAllocator::__DbgMarkEnd()

   565 	*/

   566 	virtual void AllocMarkEnd(TInt aCount) = 0;

   567 	/**

   568 	@publishedPartner

   569 	@deprecated

   570 	@test

   571 

   572 	Sets the type and rate of simulated allocation failure on the heap for adapter

   573 	objects.

   574 

   575 	@param aType The type of allocation failure requested.

   576 	@param aRate The rate of allocation failure requested.

   577 	@see RAllocator::__DbgSetAllocFail()

   578 	*/

   579 	virtual void SetAllocFail(RAllocator::TAllocFail aType, TInt aRate) = 0;

   580 	};

   581 

   582 

   583 #include <graphics/sgresourceadapter.inl>

   584 

   585 

   586 #endif // SGRESOURCEADAPTER_H