--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/graphicsresourceservices/graphicsresource/inc/sgresourceadapter.h Tue Feb 02 01:47:50 2010 +0200
@@ -0,0 +1,586 @@
+// 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