sl@0: // Copyright (c) 2007-2009 Nokia Corporation and/or its subsidiary(-ies). sl@0: // All rights reserved. sl@0: // This component and the accompanying materials are made available sl@0: // under the terms of "Eclipse Public License v1.0" sl@0: // which accompanies this distribution, and is available sl@0: // at the URL "http://www.eclipse.org/legal/epl-v10.html". sl@0: // sl@0: // Initial Contributors: sl@0: // Nokia Corporation - initial contribution. sl@0: // sl@0: // Contributors: sl@0: // sl@0: // Description: sl@0: // sl@0: sl@0: /** sl@0: @file sl@0: @publishedPartner sl@0: @prototype sl@0: */ sl@0: sl@0: #ifndef SGRESOURCEADAPTER_H sl@0: #define SGRESOURCEADAPTER_H sl@0: sl@0: #include sl@0: #include sl@0: sl@0: sl@0: /** sl@0: @publishedPartner sl@0: @prototype sl@0: @deprecated sl@0: sl@0: The file name of the Graphics Resource Adapter DLL. sl@0: */ sl@0: _LIT(KSgResourceAdapterLibraryName, "graphicsresourceadapter"); sl@0: sl@0: sl@0: /** sl@0: @publishedPartner sl@0: @prototype sl@0: @deprecated sl@0: sl@0: The UID3 value in the compound identifier of the Graphics Resource Adapter DLL. sl@0: */ sl@0: const TUid KSgResourceAdapterLibraryUid = {0x10285A71}; sl@0: sl@0: sl@0: /** sl@0: @publishedPartner sl@0: @prototype sl@0: @deprecated sl@0: sl@0: The category name of the panics raised by the Graphics Resource API. sl@0: */ sl@0: _LIT(KSgResourcePanicCategory, "SGRES"); sl@0: sl@0: sl@0: /** sl@0: @publishedPartner sl@0: @prototype sl@0: @deprecated sl@0: sl@0: The reason numbers of the panics raised by the Graphics Resource API. sl@0: */ sl@0: enum TSgResourcePanicReason sl@0: { sl@0: /** sl@0: SGRES 1 In debug builds, there still are open handles to graphics resources in sl@0: a process when the process termination tasks are carried out. sl@0: */ sl@0: ESgPanicUnclosedResources = 1, sl@0: /** sl@0: SGRES 2 In debug builds, an RSgDrawable handle is invalid. sl@0: */ sl@0: ESgPanicBadDrawableHandle = 2, sl@0: /** sl@0: SGRES 3 In debug builds, an RSgImage handle is invalid. sl@0: */ sl@0: ESgPanicBadImageHandle = 3, sl@0: /** sl@0: SGRES 4 In debug builds, an RSgImageCollection handle is invalid. sl@0: */ sl@0: ESgPanicBadImageCollectionHandle = 4, sl@0: /** sl@0: SGRES 5 In debug builds, the Graphics Resource driver is not initialised for sl@0: use in the context of the calling process. sl@0: */ sl@0: ESgPanicNoDriver = 5 sl@0: }; sl@0: sl@0: sl@0: /** sl@0: @publishedPartner sl@0: @prototype sl@0: @deprecated sl@0: sl@0: Panics the current thread specifying a panic reason from the Graphics Resource API. sl@0: */ sl@0: inline void Panic(TSgResourcePanicReason aReason); sl@0: sl@0: sl@0: /** sl@0: @publishedPartner sl@0: @prototype sl@0: @deprecated sl@0: sl@0: This constant consists of all the flags specifying usage of a graphics resource sl@0: as a source of any rendering pipeline. sl@0: */ sl@0: const TUint32 KSgUsageAllSources = ESgUsageDirectGdiSource | ESgUsageCompositionSource sl@0: | ESgUsageScreenSource | ESgUsageOpenGlesTexture2D | ESgUsageOpenVgImage sl@0: | ESgUsageOpenGles2Texture2D | ESgUsageWindowGcSource; sl@0: sl@0: sl@0: /** sl@0: @publishedPartner sl@0: @prototype sl@0: @deprecated sl@0: sl@0: This constant consists of all the flags specifying usage of a graphics resource sl@0: as a target of any rendering pipeline. sl@0: */ sl@0: const TUint32 KSgUsageAllTargets = ESgUsageDirectGdiTarget | ESgUsageCompositionTarget sl@0: | ESgUsageOpenGlesTarget | ESgUsageOpenVgTarget | ESgUsageEglCopyBuffersTarget sl@0: | ESgUsageOpenGles2Target; sl@0: sl@0: sl@0: /** sl@0: @publishedPartner sl@0: @prototype sl@0: @deprecated sl@0: sl@0: The default open mode for drawable resources. sl@0: */ sl@0: const TUint32 KSgDefaultOpenMode = 0; sl@0: sl@0: sl@0: /** sl@0: @publishedPartner sl@0: @prototype sl@0: @deprecated sl@0: sl@0: This interface must be implemented by all the user-side objects in the adaptation sl@0: layer of the Graphics subsystem which are referenced by instances of any handle sl@0: class in the Graphics Resource API. The interface between the user-side and the sl@0: kernel-side parts of the adaptation layer is outside the scope of the specification sl@0: of the Graphics Resource API. sl@0: sl@0: Each resource referenced by a handle opened in the context of a process must be sl@0: represented by an adapter object inside the process. Both the adapter object and sl@0: the resource itself have reference counts. The reference count for the adapter object sl@0: equals the number of handles to the resource open in the process, while the adapter sl@0: object counts as a single reference to the resource. sl@0: sl@0: Adapter objects can be shared between all the threads in a process. This has two sl@0: consequences: sl@0: - Adapter objects must be allocated in a multi-threaded heap owned by the Graphics sl@0: Resource Adapter singleton. sl@0: - Access to adapter objects must be synchronised by means of a mutual exclusion sl@0: mechanism. sl@0: */ sl@0: class MSgResourceAdapter sl@0: { sl@0: public: sl@0: /** sl@0: @publishedPartner sl@0: @prototype sl@0: @deprecated sl@0: sl@0: Closes this adapter object by decrementing its reference count by one and, if the sl@0: count becomes zero, destroying the adapter object. If the adapter object is sl@0: destroyed then the reference count for the represented resource is decremented sl@0: by one. sl@0: sl@0: @see RSgDrawable::Close() sl@0: @see RSgImageCollection::Close() sl@0: */ sl@0: virtual void Close() = 0; sl@0: }; sl@0: sl@0: sl@0: /** sl@0: @publishedPartner sl@0: @prototype sl@0: @deprecated sl@0: sl@0: This interface must be implemented by all the user-side objects in the adaptation sl@0: layer of the Graphics subsystem which are referenced by instances of RSgDrawable. sl@0: The interface between the user-side and the kernel-side parts of the adaptation sl@0: layer is outside the scope of the specification of the Graphics Resource API. sl@0: sl@0: @see RSgDrawable sl@0: */ sl@0: class MSgDrawableAdapter: public MSgResourceAdapter sl@0: { sl@0: public: sl@0: /** sl@0: @publishedPartner sl@0: @prototype sl@0: @deprecated sl@0: sl@0: Retrieves the unique identifier of the drawable resource represented by this sl@0: adapter object. sl@0: sl@0: @return The unique identifier of the drawable resource. sl@0: @see RSgDrawable::Id() sl@0: */ sl@0: virtual const TSgDrawableId& Id() const = 0; sl@0: /** sl@0: @publishedPartner sl@0: @prototype sl@0: @deprecated sl@0: sl@0: Retrieves the actual type of the drawable resource represented by this adapter sl@0: object as a globally unique identifier. sl@0: sl@0: @return The actual type of the drawable resource as a globally unique identifier. sl@0: @see RSgDrawable::DrawableType() sl@0: */ sl@0: virtual TUid DrawableType() const = 0; sl@0: /** sl@0: @publishedPartner sl@0: @prototype sl@0: @deprecated sl@0: sl@0: Makes an extension interface available on the drawable resource represented by sl@0: this adapter object. sl@0: sl@0: @param aInterfaceUid Globally unique identifier of the interface to be made sl@0: available. sl@0: @param aInterfacePtr On return, a pointer to the specified interface. sl@0: @pre The specified interface is supported on the drawable resource. sl@0: @post The specified interface is available until this adapter object is destroyed. sl@0: @return KErrNone if successful. sl@0: @return KErrExtensionNotSupported if the specified interface is not supported sl@0: on the drawable resource. sl@0: @return KErrNoMemory if there is not enough system memory. sl@0: @see RSgDrawable::GetInterface() sl@0: */ sl@0: virtual TInt GetInterface(TUid aInterfaceUid, TAny*& aInterfacePtr) = 0; sl@0: }; sl@0: sl@0: sl@0: class TSgImageInfo; sl@0: class RSgImage; sl@0: class MSgImageAdapter; sl@0: class MSgImageCollectionAdapter; sl@0: sl@0: /** sl@0: @publishedPartner sl@0: @prototype sl@0: @deprecated sl@0: sl@0: This interface must be implemented by the Graphics Resource Adapter singleton. sl@0: There must be a single instance of the adaptation layer class that implements sl@0: this interface in each process using the Graphics Resource API. sl@0: */ sl@0: class MSgDriverAdapter sl@0: { sl@0: public: sl@0: /** sl@0: @publishedPartner sl@0: @prototype sl@0: @deprecated sl@0: sl@0: Creates a new instance of the singleton class and carries out the initialisation sl@0: tasks needed to use the Graphics Resource API in the context of the calling sl@0: process. This is the only function that must be exported by the Graphics Resource sl@0: Adapter DLL, at ordinal 1. sl@0: sl@0: @param aPtr On return, a pointer to the new instance of the singleton class. sl@0: @return KErrNone if successful. sl@0: @return KErrNoMemory if there is not enough system memory. sl@0: @see SgDriver::Open() sl@0: */ sl@0: IMPORT_C static TInt New(MSgDriverAdapter*& aPtr); sl@0: /** sl@0: @publishedPartner sl@0: @prototype sl@0: @deprecated sl@0: sl@0: Deletes an instance of the singleton class and carries out the termination tasks sl@0: needed to release the internal resources allocated for the calling process. sl@0: sl@0: @see SgDriver::Close() sl@0: */ sl@0: virtual void Delete() = 0; sl@0: /** sl@0: @publishedPartner sl@0: @prototype sl@0: @deprecated sl@0: sl@0: Retrieves the list of image pixel formats supported on this device for a sl@0: specified usage. sl@0: sl@0: @param aInfo The image attributes. aInfo.iPixelFormat is ignored. sl@0: @param aPixelFormats A pointer to an array that on return will contain the sl@0: supported pixel formats. If this parameter is null, then this function sl@0: will just return the number of supported pixel formats in aCount. sl@0: @param aCount On input, the number of elements in the array pointed to by sl@0: aPixelFormats if not null, ignored otherwise. On return, the actual number sl@0: of supported pixel formats. If this number is greater than the number of sl@0: elements in the array, then the array will be filled with as many pixel sl@0: formats as it can hold and the function will return KErrOverflow. sl@0: @pre aInfo is valid. sl@0: @pre If aPixelFormats is not null then aCount is greater than zero. sl@0: @return KErrNone if successful. sl@0: @return KErrArgument if aInfo is invalid or if aPixelFormats is not null and sl@0: aCount is negative. sl@0: @return KErrOverflow if the actual number of supported pixel formats is greater sl@0: than the number of elements in the array pointed to by aPixelFormats. sl@0: @return KErrNoMemory if there is not enough system memory. sl@0: @see RSgImage::GetPixelFormats() sl@0: */ sl@0: virtual TInt GetPixelFormats(const TSgImageInfo& aInfo, TUidPixelFormat* aPixelFormats, TInt& aCount) = 0; sl@0: /** sl@0: @publishedPartner sl@0: @prototype sl@0: @deprecated sl@0: sl@0: Creates an image with the specified attributes and, optionally, the specified sl@0: initial contents. sl@0: sl@0: @param aInfo The attributes of the image to be created. sl@0: @param aDataAddress The base address of the pixel data used to populate the sl@0: new image. If this value is null, the initial contents of the image are sl@0: undefined. If aInfo specifies that the new image is constant, this value sl@0: must not be null. sl@0: @param aDataStride The number of bytes between rows of the pixel data used to sl@0: populate the new image. sl@0: @param aResult On return, a pointer to the adapter object that represents the sl@0: new image. sl@0: @pre aInfo is supported. sl@0: @pre aResult is null. sl@0: @post aResult points to an adapter object that represents a newly created image sl@0: with the specified attributes and initial contents. The initial reference sl@0: count for the image is one. sl@0: @return KErrNone if successful. sl@0: @return KErrInUse if aResult was not null. sl@0: @return KErrArgument if aInfo is invalid. sl@0: @return KErrNoInitializationData if aInfo requests a constant image and aDataAddress sl@0: is null. sl@0: @return KErrTooBig if the size specified in aInfo is too large. sl@0: @return KErrNotSupported if aInfo is not supported. sl@0: @return KErrNoMemory if there is not enough system memory. sl@0: @return KErrNoSpecializedMemory if there is not enough specialised graphics memory. sl@0: @see RSgImage::Create() sl@0: */ sl@0: virtual TInt CreateImage(const TSgImageInfo& aInfo, const TAny* aDataAddress, TInt aDataStride, MSgDrawableAdapter*& aResult) = 0; sl@0: /** sl@0: @publishedPartner sl@0: @prototype sl@0: @deprecated sl@0: sl@0: Creates an image with the specified attributes and initial contents copied sl@0: from an existing image. sl@0: sl@0: @param aInfo The attributes of the image to be created. sl@0: @param aImage A pointer to the adapter object that represents the existing sl@0: image to be copied. sl@0: @param aResult On return, a pointer to the adapter object that represents the sl@0: new image. sl@0: @pre aInfo is supported. sl@0: @pre aImage is not null. sl@0: @pre The size and the pixel format specified in aInfo must be the same as the sl@0: size and the pixel format of the image represented by aImage. sl@0: @pre aResult is null. sl@0: @post aResult points to an adapter object that represents a newly created image sl@0: with the specified attributes and initial contents. The initial reference sl@0: count for the image is one. sl@0: @return KErrNone if successful. sl@0: @return KErrInUse if aResult was not null. sl@0: @return KErrArgument if aInfo is invalid or if aImage is null. sl@0: @return KErrNotSupported if aInfo is not supported or if the size and the pixel sl@0: format specified in aInfo are not the same as the size and the pixel sl@0: format of the image represented by aImage. sl@0: @return KErrNoMemory if there is not enough system memory. sl@0: @return KErrNoSpecializedMemory if there is not enough specialised graphics memory. sl@0: @see RSgImage::Create() sl@0: */ sl@0: virtual TInt CreateImage(const TSgImageInfo& aInfo, MSgImageAdapter* aImage, MSgDrawableAdapter*& aResult) = 0; sl@0: /** sl@0: @publishedPartner sl@0: @prototype sl@0: @deprecated sl@0: sl@0: Creates an image collection with the specified attributes. sl@0: sl@0: @param aInfo The image attributes of the collection to be created. sl@0: @param aImageCount The number of images in the collection to be created. sl@0: @param aResult On return, a pointer to the adapter object that represents the sl@0: new image collection. sl@0: @pre aInfo is supported and specifies mutable images. sl@0: @pre aImageCount is greater than zero. sl@0: @pre aResult is null. sl@0: @post aResult points to an adapter object that represents a newly created image sl@0: collection with the specified attributes. The initial reference count sl@0: for the image collection is one. sl@0: @return KErrNone if successful. sl@0: @return KErrInUse if aResult was not null. sl@0: @return KErrArgument if aInfo is invalid or if aImageCount is negative or zero. sl@0: @return KErrTooBig if the size specified in aInfo is too large. sl@0: @return KErrNotSupported if aInfo is not supported or does not specify mutable sl@0: images. sl@0: @return KErrNoMemory if there is not enough system memory. sl@0: @return KErrNoSpecializedMemory if there is not enough specialised graphics memory. sl@0: @see RSgImageCollection::Create() sl@0: */ sl@0: virtual TInt CreateImageCollection(const TSgImageInfo& aInfo, TInt aImageCount, MSgImageCollectionAdapter*& aResult) = 0; sl@0: /** sl@0: @publishedPartner sl@0: @prototype sl@0: @deprecated sl@0: sl@0: Creates a set of image collections that share a single memory chunk. sl@0: sl@0: @param aInfos An array of aCollectionCount elements with the image attributes sl@0: of each of the collections to be created. sl@0: @param aImageCount The number of images in each of the collections to be created. sl@0: @param aCollections On return, an array of pointers to the adapter objects that sl@0: represent the new image collections. sl@0: @param aCollectionCount The number of image collections to be created. sl@0: @pre All the elements of aInfos are supported and specify mutable images. sl@0: @pre aImageCount is greater than zero. sl@0: @pre All the pointers in aCollections are null. sl@0: @pre aCollectionCount is greater than zero. sl@0: @post The elements of aCollections point to aCollectionCount adapter objects that sl@0: represent newly created image collections with the specified attributes. sl@0: The initial reference count for each of the image collections is one. sl@0: @return KErrNone if successful. sl@0: @return KErrInUse if any of the pointers in aCollections was not null. sl@0: @return KErrArgument if any element of aInfos is invalid, if aImageCount is sl@0: negative or zero, or if aCollectionCount is negative or zero. sl@0: @return KErrTooBig if any of the sizes specified in aInfos is too large. sl@0: @return KErrNotSupported if any element of aInfos is not supported or does not sl@0: specify mutable images. sl@0: @return KErrNoMemory if there is not enough system memory. sl@0: @return KErrNoSpecializedMemory if there is not enough specialised graphics memory. sl@0: @see RSgImageCollection::Create() sl@0: */ sl@0: virtual TInt CreateImageCollections(const TSgImageInfo aInfos[], TInt aImageCount, sl@0: MSgImageCollectionAdapter* aCollections[], TInt aCollectionCount) = 0; sl@0: /** sl@0: @publishedPartner sl@0: @prototype sl@0: @deprecated sl@0: sl@0: Opens a new handle to a drawable resource. If there are no handles to the drawable sl@0: resource open in the calling process then this function creates a new adapter sl@0: object that represents the drawable resource in the context of the calling process. sl@0: Otherwise this function just increments the reference count of the existing adapter sl@0: object that represents the drawable resource in the context of the calling process. sl@0: sl@0: @param aId The unique identifier of the drawable resource. sl@0: @param aMode Flags controlling how the drawable resource is opened. The only value sl@0: of this parameter which it is mandatory to support is KSgDefaultOpenMode. sl@0: Extra opening options may be defined by an implementation of the Graphics sl@0: Resource API and made available through additional functions. sl@0: @param aHandleType The type of the handle which is to store the reference to sl@0: the specified drawable resource as a globally unique identifier. sl@0: @param aResult On return, a pointer to the adapter object that represents the sl@0: specified drawable resource. sl@0: @pre aId identifies an existing drawable resource. sl@0: @pre All of the requested opening options in aMode are supported. sl@0: @pre aHandleType specifies an instance of RSgDrawable or any other handle type sl@0: that is compatible with the actual type of the specified drawable resource. sl@0: @pre aResult is null. sl@0: @post aResult points to either a newly created or an existing adapter object sl@0: that represents the drawable resource specified by its unique identifier. sl@0: If a new adapter object is created then its initial reference count is sl@0: one and the reference count for the drawable resource itself is incremented sl@0: by one. Otherwise only the reference count for the adapter object is sl@0: incremented by one. sl@0: @return KErrNone if successful. sl@0: @return KErrInUse if aResult was not null. sl@0: @return KErrArgument if aId is the null drawable resource identifier. sl@0: @return KErrNotFound if aId cannot be found to refer to an existing drawable sl@0: resource. sl@0: @return KErrPermissionDenied if this process is not permitted to access the sl@0: drawable resource specified by aId. sl@0: @return KErrNotSupported if any of the requested opening options in aMode is sl@0: not supported or if aHandleType is not compatible with the actual type sl@0: of the drawable resource specified by aId. sl@0: @return KErrNoMemory if there is not enough system memory. sl@0: @see RSgDrawable::Open() sl@0: */ sl@0: virtual TInt OpenDrawable(const TSgDrawableId& aId, TUint32 aMode, TUid aHandleType, MSgDrawableAdapter*& aResult) = 0; sl@0: /** sl@0: @publishedPartner sl@0: @prototype sl@0: @deprecated sl@0: sl@0: Tests whether aDrawable references an existing adapter object representing a sl@0: drawable resource. This function is called in debug builds to detect invalid sl@0: RSgDrawable handles. sl@0: sl@0: @return ETrue if aDrawable is a valid reference to an adapter object representing sl@0: a drawable resource, EFalse otherwise. sl@0: */ sl@0: virtual TBool CheckDrawable(const MSgResourceAdapter& aDrawable) const = 0; sl@0: /** sl@0: @publishedPartner sl@0: @prototype sl@0: @deprecated sl@0: sl@0: Tests whether aImage references an existing adapter object representing an image. sl@0: This function is called in debug builds to detect invalid RSgImage handles. sl@0: sl@0: @return ETrue if aImage is a valid reference to an adapter object representing sl@0: an image, EFalse otherwise. sl@0: */ sl@0: virtual TBool CheckImage(const MSgResourceAdapter& aImage) const = 0; sl@0: /** sl@0: @publishedPartner sl@0: @prototype sl@0: @deprecated sl@0: sl@0: Tests whether aImageCollection references an existing adapter object representing sl@0: an image collection. This function is called in debug builds to detect invalid sl@0: RSgImageCollection handles. sl@0: sl@0: @return ETrue if aImageCollection is a valid reference to an adapter object sl@0: representing an image collection, EFalse otherwise. sl@0: */ sl@0: virtual TBool CheckImageCollection(const MSgResourceAdapter& aImageCollection) const = 0; sl@0: /** sl@0: @publishedPartner sl@0: @deprecated sl@0: @test sl@0: sl@0: Retrieves the number of handles to graphics resources open in the calling process. sl@0: sl@0: @return The number of handles to graphics resources open in the calling process. sl@0: */ sl@0: virtual TInt ResourceCount() const = 0; sl@0: /** sl@0: @publishedPartner sl@0: @deprecated sl@0: @test sl@0: sl@0: Marks the start of cell checking on the heap for adapter objects. Calls to this sl@0: function can be nested but each call must be matched by a corresponding call to sl@0: AllocMarkEnd(). sl@0: sl@0: @see RAllocator::__DbgMarkStart() sl@0: */ sl@0: virtual void AllocMarkStart() = 0; sl@0: /** sl@0: @publishedPartner sl@0: @deprecated sl@0: @test sl@0: sl@0: Marks the end of cell checking at the current nesting level on the heap for sl@0: adapter objects. Each call to this function must match an earlier call to sl@0: AllocMarkStart(). sl@0: sl@0: This function checks that the number of cells allocated in the heap for adapter sl@0: objects, at the current nesting level, is aCount. If the check fails then an sl@0: SGALLOC:nnnnnnnn panic is raised, where nnnnnnnn is the hexadecimal address sl@0: of the first orphaned cell. sl@0: sl@0: @param aCount The number of allocated heap cells expected. sl@0: @see RAllocator::__DbgMarkEnd() sl@0: */ sl@0: virtual void AllocMarkEnd(TInt aCount) = 0; sl@0: /** sl@0: @publishedPartner sl@0: @deprecated sl@0: @test sl@0: sl@0: Sets the type and rate of simulated allocation failure on the heap for adapter sl@0: objects. sl@0: sl@0: @param aType The type of allocation failure requested. sl@0: @param aRate The rate of allocation failure requested. sl@0: @see RAllocator::__DbgSetAllocFail() sl@0: */ sl@0: virtual void SetAllocFail(RAllocator::TAllocFail aType, TInt aRate) = 0; sl@0: }; sl@0: sl@0: sl@0: #include sl@0: sl@0: sl@0: #endif // SGRESOURCEADAPTER_H