diff -r 000000000000 -r bde4ae8d615e os/graphics/graphicsresourceservices/graphicsresource/inc/sgresourceadapter.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/os/graphics/graphicsresourceservices/graphicsresource/inc/sgresourceadapter.h Fri Jun 15 03:10:57 2012 +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 +#include + + +/** +@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 + + +#endif // SGRESOURCEADAPTER_H