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