// Copyright (c) 2007-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:

 //

 /**

  @file

  @publishedPartner

  @prototype

 */

 #ifndef SGRESOURCEADAPTER_H

 #define SGRESOURCEADAPTER_H

 #include <graphics/sgresource.h>

 #include <pixelformats.h>

 /**

 @publishedPartner

 @prototype

 @deprecated

 The file name of the Graphics Resource Adapter DLL.

 */

 _LIT(KSgResourceAdapterLibraryName, "graphicsresourceadapter");

 /**

 @publishedPartner

 @prototype

 @deprecated

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

 */

 const TUid KSgResourceAdapterLibraryUid = {0x10285A71};

 /**

 @publishedPartner

 @prototype

 @deprecated

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

 */

 _LIT(KSgResourcePanicCategory, "SGRES");

 /**

 @publishedPartner

 @prototype

 @deprecated

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

 */

 enum TSgResourcePanicReason

 	{

 	/**

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

 	a process when the process termination tasks are carried out.

 	*/

 	ESgPanicUnclosedResources = 1,

 	/**

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

 	*/

 	ESgPanicBadDrawableHandle = 2,

 	/**

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

 	*/

 	ESgPanicBadImageHandle = 3,

 	/**

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

 	*/

 	ESgPanicBadImageCollectionHandle = 4,

 	/**

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

 	use in the context of the calling process.

 	*/

 	ESgPanicNoDriver = 5

 	};

 /**

 @publishedPartner

 @prototype

 @deprecated

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

 */

 inline void Panic(TSgResourcePanicReason aReason);

 /**

 @publishedPartner

 @prototype

 @deprecated

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

 as a source of any rendering pipeline.

 */

 const TUint32 KSgUsageAllSources = ESgUsageDirectGdiSource | ESgUsageCompositionSource

 	| ESgUsageScreenSource | ESgUsageOpenGlesTexture2D | ESgUsageOpenVgImage

 	| ESgUsageOpenGles2Texture2D | ESgUsageWindowGcSource;

 /**

 @publishedPartner

 @prototype

 @deprecated

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

 as a target of any rendering pipeline.

 */

 const TUint32 KSgUsageAllTargets = ESgUsageDirectGdiTarget | ESgUsageCompositionTarget

 	| ESgUsageOpenGlesTarget | ESgUsageOpenVgTarget | ESgUsageEglCopyBuffersTarget

 	| ESgUsageOpenGles2Target;

 /**

 @publishedPartner

 @prototype

 @deprecated

 The default open mode for drawable resources.

 */

 const TUint32 KSgDefaultOpenMode = 0;

 /**

 @publishedPartner

 @prototype

 @deprecated

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

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

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

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

 of the Graphics Resource API.

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

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

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

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

 object counts as a single reference to the resource.

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

 consequences:

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

 	  Resource Adapter singleton.

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

 	  mechanism.

 */

 class MSgResourceAdapter

 	{

 public:

 	/**

 	@publishedPartner

 	@prototype

 	@deprecated

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

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

 	destroyed then the reference count for the represented resource is decremented

 	by one.

 	@see RSgDrawable::Close()

 	@see RSgImageCollection::Close()

 	*/

 	virtual void Close() = 0;

 	};

 /**

 @publishedPartner

 @prototype

 @deprecated

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

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

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

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

 @see RSgDrawable

 */

 class MSgDrawableAdapter: public MSgResourceAdapter

 	{

 public:

 	/**

 	@publishedPartner

 	@prototype

 	@deprecated

 	Retrieves the unique identifier of the drawable resource represented by this

 	adapter object.

 	@return The unique identifier of the drawable resource.

 	@see RSgDrawable::Id()

 	*/

 	virtual const TSgDrawableId& Id() const = 0;

 	/**

 	@publishedPartner

 	@prototype

 	@deprecated

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

 	object as a globally unique identifier.

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

 	@see RSgDrawable::DrawableType()

 	*/

 	virtual TUid DrawableType() const = 0;

 	/**

 	@publishedPartner

 	@prototype

 	@deprecated

 	Makes an extension interface available on the drawable resource represented by

 	this adapter object.

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

 	       available.

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

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

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

 	@return KErrNone if successful.

 	@return KErrExtensionNotSupported if the specified interface is not supported

 	        on the drawable resource.

 	@return KErrNoMemory if there is not enough system memory.

 	@see RSgDrawable::GetInterface()

 	*/

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

 	};

 class TSgImageInfo;

 class RSgImage;

 class MSgImageAdapter;

 class MSgImageCollectionAdapter;

 /**

 @publishedPartner

 @prototype

 @deprecated

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

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

 this interface in each process using the Graphics Resource API.

 */

 class MSgDriverAdapter

 	{

 public:

 	/**

 	@publishedPartner

 	@prototype

 	@deprecated

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

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

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

 	Adapter DLL, at ordinal 1.

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

 	@return KErrNone if successful.

 	@return KErrNoMemory if there is not enough system memory.

 	@see SgDriver::Open()

 	*/

 	IMPORT_C static TInt New(MSgDriverAdapter*& aPtr);

 	/**

 	@publishedPartner

 	@prototype

 	@deprecated

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

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

 	@see SgDriver::Close()

 	*/

 	virtual void Delete() = 0;

 	/**

 	@publishedPartner

 	@prototype

 	@deprecated

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

 	specified usage.

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

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

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

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

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

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

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

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

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

 	@pre aInfo is valid.

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

 	@return KErrNone if successful.

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

 	        aCount is negative.

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

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

 	@return KErrNoMemory if there is not enough system memory.

 	@see RSgImage::GetPixelFormats()

 	*/

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

 	/**

 	@publishedPartner

 	@prototype

 	@deprecated

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

 	initial contents.

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

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

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

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

 	       must not be null.

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

 	       populate the new image.

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

 	       new image.

 	@pre aInfo is supported.

 	@pre aResult is null.

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

 	      with the specified attributes and initial contents. The initial reference

 	      count for the image is one.

 	@return KErrNone if successful.

 	@return KErrInUse if aResult was not null.

 	@return KErrArgument if aInfo is invalid.

 	@return KErrNoInitializationData if aInfo requests a constant image and aDataAddress

 	        is null.

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

 	@return KErrNotSupported if aInfo is not supported.

 	@return KErrNoMemory if there is not enough system memory.

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

 	@see RSgImage::Create()

 	*/

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

 	/**

 	@publishedPartner

 	@prototype

 	@deprecated

 	Creates an image with the specified attributes and initial contents copied

 	from an existing image.

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

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

 	       image to be copied.

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

 	       new image.

 	@pre aInfo is supported.

 	@pre aImage is not null.

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

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

 	@pre aResult is null.

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

 	      with the specified attributes and initial contents. The initial reference

 	      count for the image is one.

 	@return KErrNone if successful.

 	@return KErrInUse if aResult was not null.

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

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

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

 	        format of the image represented by aImage.

 	@return KErrNoMemory if there is not enough system memory.

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

 	@see RSgImage::Create()

 	*/

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

 	/**

 	@publishedPartner

 	@prototype

 	@deprecated

 	Creates an image collection with the specified attributes.

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

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

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

 	       new image collection.

 	@pre aInfo is supported and specifies mutable images.

 	@pre aImageCount is greater than zero.

 	@pre aResult is null.

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

 	      collection with the specified attributes. The initial reference count

 	      for the image collection is one.

 	@return KErrNone if successful.

 	@return KErrInUse if aResult was not null.

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

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

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

 	        images.

 	@return KErrNoMemory if there is not enough system memory.

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

 	@see RSgImageCollection::Create()

 	*/

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

 	/**

 	@publishedPartner

 	@prototype

 	@deprecated

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

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

 	       of each of the collections to be created.

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

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

 	       represent the new image collections.

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

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

 	@pre aImageCount is greater than zero.

 	@pre All the pointers in aCollections are null.

 	@pre aCollectionCount is greater than zero.

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

 	      represent newly created image collections with the specified attributes.

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

 	@return KErrNone if successful.

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

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

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

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

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

 	        specify mutable images.

 	@return KErrNoMemory if there is not enough system memory.

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

 	@see RSgImageCollection::Create()

 	*/

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

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

 	/**

 	@publishedPartner

 	@prototype

 	@deprecated

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

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

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

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

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

 	@param aId The unique identifier of the drawable resource.

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

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

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

 	       Resource API and made available through additional functions.

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

 	       the specified drawable resource as a globally unique identifier.

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

 	       specified drawable resource.

 	@pre aId identifies an existing drawable resource.

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

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

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

 	@pre aResult is null.

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

 	      that represents the drawable resource specified by its unique identifier.

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

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

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

 	      incremented by one.

 	@return KErrNone if successful.

 	@return KErrInUse if aResult was not null.

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

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

 	        resource.

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

 	        drawable resource specified by aId.

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

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

 	        of the drawable resource specified by aId.

 	@return KErrNoMemory if there is not enough system memory.

 	@see RSgDrawable::Open()

 	*/

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

 	/**

 	@publishedPartner

 	@prototype

 	@deprecated

 	Tests whether aDrawable references an existing adapter object representing a

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

 	RSgDrawable handles.

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

 	        a drawable resource, EFalse otherwise.

 	*/

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

 	/**

 	@publishedPartner

 	@prototype

 	@deprecated

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

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

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

 	        an image, EFalse otherwise.

 	*/

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

 	/**

 	@publishedPartner

 	@prototype

 	@deprecated

 	Tests whether aImageCollection references an existing adapter object representing

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

 	RSgImageCollection handles.

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

 	        representing an image collection, EFalse otherwise.

 	*/

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

 	/**

 	@publishedPartner

 	@deprecated

 	@test

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

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

 	*/

 	virtual TInt ResourceCount() const = 0;

 	/**

 	@publishedPartner

 	@deprecated

 	@test

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

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

 	AllocMarkEnd().

 	@see RAllocator::__DbgMarkStart()

 	*/

 	virtual void AllocMarkStart() = 0;

 	/**

 	@publishedPartner

 	@deprecated

 	@test

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

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

 	AllocMarkStart().

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

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

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

 	of the first orphaned cell.

 	@param aCount The number of allocated heap cells expected.

 	@see RAllocator::__DbgMarkEnd()

 	*/

 	virtual void AllocMarkEnd(TInt aCount) = 0;

 	/**

 	@publishedPartner

 	@deprecated

 	@test

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

 	objects.

 	@param aType The type of allocation failure requested.

 	@param aRate The rate of allocation failure requested.

 	@see RAllocator::__DbgSetAllocFail()

 	*/

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

 	};

 #include <graphics/sgresourceadapter.inl>

 #endif // SGRESOURCEADAPTER_H