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: // Graphics Resource - general functionality sl@0: // sl@0: sl@0: #ifndef SGRESOURCE_H sl@0: #define SGRESOURCE_H sl@0: sl@0: #include sl@0: #include sl@0: sl@0: /** sl@0: Panic codes defined for use by the Graphics Resource API. sl@0: */ sl@0: enum TSgResourcePanicReason sl@0: { sl@0: ESgPanicNoDriver = 1, sl@0: ESgPanicUnclosedResources = 2, sl@0: ESgPanicBadDrawableHandle = 3, sl@0: ESgPanicBadAttributeArrayIndex = 4 sl@0: }; sl@0: sl@0: /** sl@0: Panics the calling thread with category “SGRES” and the given panic code. sl@0: @param aReason The panic code. sl@0: */ sl@0: inline void Panic(TSgResourcePanicReason aReason); sl@0: sl@0: /** sl@0: A handle to the implementation of the Graphics Resource API sl@0: initialised in the context of a process. It groups miscellaneous functions that sl@0: do not apply to individual drawable resources. sl@0: sl@0: At least one thread in the process must call RSgDriver::Open() before the sl@0: Graphics Resource API can be used in the context of the process. sl@0: When the Graphics Resource API is no longer needed RSgDriver::Close() should be sl@0: called to release unused resources. Note that it is possible to call RSgDriver::Open() sl@0: and RSgDriver::Close() from different threads. sl@0: */ sl@0: NONSHARABLE_CLASS(RSgDriver) sl@0: { sl@0: public: sl@0: /** sl@0: Default constructor. sl@0: @post The instance of RSgDriver is a null handle. sl@0: */ sl@0: inline RSgDriver(); sl@0: sl@0: /** sl@0: Initialises the implementation of the Graphics Resource API in the context sl@0: of a process if it is not initialised already, updates the implementation sl@0: opening count in the process and returns KErrNone if successful. sl@0: Each successful call to RSgDriver::Open() in a process should be balanced sl@0: by a corresponding call to RSgDriver::Close() in the same process, but not sl@0: necessarily from the same thread. sl@0: sl@0: Note that an RSgDriver handle should never be bitwise-copied into another sl@0: but this function should be used instead in all cases, since it is the only sl@0: way to ensure that the implementation opening count is kept up to date. sl@0: Failure to keep the implementation opening count up to date may result in sl@0: the implementation of the Graphics Resource API becoming unexpectedly sl@0: unavailable and, as a consequence, in an abnormal termination of the process. sl@0: sl@0: @pre The instance of RSgDriver is a null handle. sl@0: @post The instance of RSgDriver references the implementation of the Graphics sl@0: Resource API initialised in the context of the process. sl@0: @return KErrNone if successful; sl@0: KErrInUse if the instance of RSgDriver is not a null handle; sl@0: KErrNoMemory if there is not enough system memory to initialise the sl@0: implementation of the Graphics Resource API; sl@0: KErrNoGraphicsMemory if there is not enough specialised graphics memory sl@0: to initialise the implementation of the Graphics Resource API. sl@0: */ sl@0: IMPORT_C TInt Open(); sl@0: sl@0: /** sl@0: Decrements the implementation opening count in the process. sl@0: When the count reaches zero, checks whether there are still open handles to sl@0: drawable resources in the process and carries out termination tasks to sl@0: release the internal resources used by the implementation of the Graphics sl@0: Resource API. sl@0: sl@0: An attempt to carry out these termination tasks will panic with category sl@0: “SGRES” and code 2 in debug builds if there still are any open handles to sl@0: drawable resources in the process. In release builds all the open handles sl@0: to drawable resources in the process are silently closed at this point. sl@0: Calling this function on a null handle has no effect. sl@0: sl@0: @post The instance of RSgDriver is a null handle. sl@0: @panic SGRES 2 Debug builds only. There are open handles to drawable resources sl@0: in the process during termination. sl@0: */ sl@0: IMPORT_C void Close(); sl@0: sl@0: /** sl@0: Makes the extension interface specified by the type of the parameter sl@0: aInterfacePtr available in the context of the process. sl@0: This function stores a pointer to the extension interface in the variable sl@0: referenced by the parameter aInterfacePtr and returns KErrNone if successful. sl@0: sl@0: @pre An RSgDriver has been opened in the context of the process. sl@0: @param[out] aInterfacePtr Reference to a pointer to the interface class that on return points sl@0: to the extension interface or, in case of error, is set to NULL. sl@0: @return KErrNone if successful; sl@0: KErrBadHandle if the instance of RSgDriver is a null handle; sl@0: KErrExtensionNotSupported if the requested extension interface is not supported. sl@0: */ sl@0: template inline TInt GetInterface(M*& aInterfacePtr) const; sl@0: sl@0: /** sl@0: Returns the version of the implementation of the Graphics Resource API. sl@0: The version comprises 3 numbers: major version number, minor version number sl@0: and build number. sl@0: sl@0: Major revisions mean incompatible changes in the API. sl@0: Minor revisions mean forward-compatible changes in the API. sl@0: Build numbers are unrelated to API changes. sl@0: sl@0: @return The version of the implementation of the Graphics Resource API. sl@0: */ sl@0: IMPORT_C static TVersion Version(); sl@0: private: sl@0: /** sl@0: Copy constructor. sl@0: Implementation not provided. Declared private to prevent bit-wise copying sl@0: of handles. sl@0: */ sl@0: RSgDriver(const RSgDriver&); sl@0: sl@0: /** sl@0: Assignment operator. sl@0: Implementation not provided. Declared private to prevent bit-wise copying sl@0: of handles. sl@0: */ sl@0: const RSgDriver& operator =(const RSgDriver&); sl@0: sl@0: /** sl@0: Makes the extension interface with the given UID available in the context sl@0: of the process. sl@0: This function stores a pointer to the extension interface in the variable sl@0: referenced by the parameter aInterfacePtr and returns KErrNone if successful. sl@0: sl@0: @pre An RSgDriver has been opened in the context of the process. sl@0: @param[in] aInterfaceUid The UID of the extension interface. sl@0: @param[out] aInterfacePtr Reference to an untyped pointer that on return points sl@0: to the extension interface or, in case of error, is set to NULL. sl@0: @return KErrNone if successful; sl@0: KErrBadHandle if the instance of RSgDriver is a null handle; sl@0: KErrArgument if aInterfaceUid is the null UID; sl@0: KErrExtensionNotSupported if the requested extension interface is not supported. sl@0: */ sl@0: IMPORT_C TInt GetInterface(TUid aInterfaceUid, TAny*& aInterfacePtr) const; sl@0: private: sl@0: /** A pointer to an implementation-defined object initially set to NULL by the constructor.*/ sl@0: TAny* iImpl; sl@0: }; sl@0: sl@0: /** sl@0: An extension attribute. sl@0: */ sl@0: NONSHARABLE_CLASS(TSgAttribute) sl@0: { sl@0: public: sl@0: /** sl@0: Default constructor. sl@0: Data members remain uninitialised. sl@0: */ sl@0: inline TSgAttribute(); sl@0: sl@0: /** sl@0: Constructor which initialises data members to the given values. sl@0: */ sl@0: inline TSgAttribute(TUid aUid, TInt aValue); sl@0: public: sl@0: /** A UID that identifies the type of extension attribute.*/ sl@0: TUid iUid; sl@0: /** The value of the extension attribute.*/ sl@0: TInt iValue; sl@0: }; sl@0: sl@0: /** sl@0: Base class of all attribute array classes. sl@0: It defines functions for bounds-checked access to extension attributes. sl@0: */ sl@0: NONSHARABLE_CLASS(TSgAttributeArrayBase) sl@0: { sl@0: public: sl@0: /** sl@0: Returns the number of extension attributes in the array. sl@0: @return The number of extension attributes in the array. sl@0: */ sl@0: inline TInt Count() const; sl@0: sl@0: /** sl@0: Returns a reference to the extension attribute located in the array at the sl@0: given position. sl@0: sl@0: @pre aIndex is equal to or greater than zero and less than the number of sl@0: extension attributes in the array. sl@0: @param aIndex The position of the extension attribute in the array. sl@0: @return A reference to the extension attribute located in the array at the sl@0: given position. sl@0: @panic SGRES 4 Debug builds only. aIndex is out of bounds. sl@0: */ sl@0: inline TSgAttribute& operator [](TInt aIndex); sl@0: sl@0: /** sl@0: Returns a const-qualified reference to the extension attribute located in sl@0: the array at the given position. sl@0: sl@0: @pre aIndex is equal to or greater than zero and less than the number of sl@0: extension attributes in the array. sl@0: @param aIndex The position of the extension attribute in the array. sl@0: @return A reference to the extension attribute located in the array at the sl@0: given position. sl@0: @panic SGRES 4 Debug builds only. aIndex is out of bounds. sl@0: */ sl@0: inline const TSgAttribute& operator [](TInt aIndex) const; sl@0: protected: sl@0: /** sl@0: Constructor used by constructors of derived classes to initialise the sl@0: attribute count. sl@0: @param aCount The number of extension attributes. sl@0: */ sl@0: inline TSgAttributeArrayBase(TInt aCount); sl@0: sl@0: /** sl@0: Assignment operator. sl@0: No operation is performed. Allows the compiler to generate assignment sl@0: operators for derived classes automatically. sl@0: */ sl@0: inline void operator =(const TSgAttributeArrayBase&); sl@0: private: sl@0: const TInt iCount; sl@0: }; sl@0: sl@0: /** sl@0: A fixed-size array of extension attributes. sl@0: It is a thin wrapper with bounds checking for arrays of TSgAttribute. sl@0: */ sl@0: template sl@0: NONSHARABLE_CLASS(TSgAttributeArray): public TSgAttributeArrayBase sl@0: { sl@0: public: sl@0: /** sl@0: Default constructor. sl@0: Data members remain uninitialised. sl@0: */ sl@0: inline TSgAttributeArray(); sl@0: private: sl@0: TSgAttribute iAttributes[S]; sl@0: }; sl@0: sl@0: /** sl@0: A system-wide unique 64-bit identifier that can be used to share a drawable sl@0: resource between processes. sl@0: sl@0: The actual value of a drawable resource identifier has no meaning to the user sl@0: of the Graphics Resource API, except that 64 zero bits represent the null sl@0: drawable resource identifier, which explicitly identifies no drawable resource. sl@0: As a convenience, the constant KSgNullDrawableId is defined as the null drawable sl@0: resource identifier. sl@0: */ sl@0: NONSHARABLE_CLASS(TSgDrawableId) sl@0: { sl@0: public: sl@0: /** sl@0: Equality operator. sl@0: Tests whether the given drawable resource identifier is the same as this. sl@0: sl@0: @param aId The drawable resource identifier to compare with this. sl@0: @return ETrue if the 64-bit identifiers are the same, EFalse if not. sl@0: */ sl@0: inline TBool operator ==(TSgDrawableId aId) const; sl@0: sl@0: /** sl@0: Inequality operator. sl@0: Tests whether the given drawable resource identifier is different from this. sl@0: sl@0: @param aId The drawable resource identifier to compare with this. sl@0: @return ETrue if the 64-bit identifiers are different, EFalse if they are the same. sl@0: */ sl@0: inline TBool operator !=(TSgDrawableId aId) const; sl@0: public: sl@0: /** The 64-bit identifier.*/ sl@0: TUint64 iId; sl@0: }; sl@0: sl@0: /** sl@0: The null drawable resource identifier. sl@0: */ sl@0: const TSgDrawableId KSgNullDrawableId = {0}; sl@0: sl@0: /** sl@0: The UID identifying a RSgDrawable handle. sl@0: This must never be changed. sl@0: */ sl@0: const TUid KSgDrawableTypeUid = {0x102858EB}; sl@0: sl@0: /** sl@0: A drawable resource handle. sl@0: A null handle is a handle that explicitly does not reference any drawable resource. sl@0: An open handle is a handle that references an existing drawable resource. sl@0: An invalid handle is a handle that is not null but does not reference any sl@0: existing drawable resource. sl@0: Drawable resources are reference-counted so that a drawable resource is not sl@0: destroyed while there still are open handles to it in any process in the system. sl@0: sl@0: RSgDrawable is not an abstract class, that is, it can be instantiated, sl@0: but it can also be derived from to define subclasses representing types of sl@0: handles that refer only to concrete types of drawable resources, for example, sl@0: image handles. RSgImage is the only subclass of RSgDrawable defined in version sl@0: 1.1 of the Graphics Resource API. sl@0: Instances of RSgDrawable are useful when drawable resources created in a sl@0: component have to be passed to another component through a third component that sl@0: cannot depend on the concrete type of the drawable resources being passed. sl@0: @see RSgImage sl@0: */ sl@0: NONSHARABLE_CLASS(RSgDrawable) sl@0: { sl@0: public: sl@0: /** sl@0: Default constructor. sl@0: @post The instance of RSgDrawable is a null handle. sl@0: */ sl@0: inline RSgDrawable(); sl@0: sl@0: /** sl@0: Opens a new handle to the drawable resource with the given drawable resource sl@0: identifier. sl@0: The drawable resource may have been created in the same process or in a sl@0: different one. This function does not allocate any specialised graphics memory. sl@0: sl@0: Note that an RSgDrawable handle should never be bitwise-copied into another sl@0: but this function should be used instead in all cases, since it is the only sl@0: way to ensure that the reference count of the drawable resource is kept up sl@0: to date. Failure to keep the reference count of the resource up to date may sl@0: result in invalid handles. sl@0: sl@0: @pre An RSgDriver handle has been opened in the context of the process. sl@0: @pre The instance of RSgDrawable is a null handle. sl@0: @post The specified drawable resource has its reference count incremented by one. sl@0: @param aId The identifier of the drawable resource. sl@0: @param aAttributes A pointer to an array of extension attributes, sl@0: if allowed by any extension of the Graphics Resource API, or NULL otherwise. sl@0: @return KErrNone if successful; sl@0: KErrInUse if the instance of RSgDrawable is an open handle; sl@0: KErrArgument if the parameter aId is the null drawable resource identifier; sl@0: KErrNotSupported if the parameter aAttributes is not NULL and one or more sl@0: of the extension attributes in the array is not defined by any extension sl@0: of the Graphics Resource API; sl@0: KErrNotFound if the parameter aId cannot be found to refer to an existing sl@0: drawable resource; sl@0: KErrNoMemory if it fails due to lack of system memory. sl@0: @panic SGRES 1 No RSgDriver handle has been opened in the context of the process. sl@0: */ sl@0: IMPORT_C TInt Open(TSgDrawableId aId, const TSgAttributeArrayBase* aAttributes = NULL); sl@0: sl@0: /** sl@0: Closes a handle to a drawable resource. sl@0: It decrements the reference count of the drawable resource and, if it reaches sl@0: zero, destroys the drawable resource. sl@0: Calling this function on a null handle has no effect. sl@0: sl@0: @pre If the instance of RSgDrawable is not a null handle then an RSgDriver sl@0: handle has been opened in the context of the process. sl@0: @post The instance of RSgDrawable is a null handle. sl@0: @panic SGRES 1 The instance of RSgDrawable is not a null handle and no sl@0: RSgDriver handle has been opened in the context of the process. sl@0: @panic SGRES 3 The instance of RSgDrawable is an invalid handle. sl@0: */ sl@0: IMPORT_C void Close(); sl@0: sl@0: /** sl@0: Returns the identifier of the drawable resource. sl@0: This identifier can be used to open another handle to the drawable resource sl@0: in the same process or in a different process. sl@0: Calling this function on a null handle returns the null drawable resource sl@0: identifier. sl@0: sl@0: @pre If the instance of RSgDrawable is not a null handle then an RSgDriver sl@0: handle has been opened in the context of the process. sl@0: @return The identifier of the drawable resource. sl@0: @panic SGRES 1 The instance of RSgDrawable is not a null handle and no sl@0: RSgDriver handle has been opened in the context of the process. sl@0: @panic SGRES 3 The instance of RSgDrawable is an invalid handle. sl@0: */ sl@0: IMPORT_C TSgDrawableId Id() const; sl@0: sl@0: /** sl@0: Tests whether a handle is null. sl@0: @return ETrue if the instance of RSgDrawable is a null handle; EFalse otherwise. sl@0: */ sl@0: inline TBool IsNull() const; sl@0: sl@0: /** sl@0: Returns the UID corresponding to the concrete type of the drawable resource sl@0: referenced by a handle at run-time. sl@0: Calling this function on a null handle returns the null UID. sl@0: In version 1.1 of the Graphics Resource API every drawable resource is an image, sl@0: so this function always returns KSgImageTypeUid when called on an open handle. sl@0: sl@0: @pre If the instance of RSgDrawable is not a null handle then an RSgDriver sl@0: handle has been opened in the context of the process. sl@0: @return The UID corresponding to the concrete type of the drawable resource. sl@0: @panic SGRES 1 The instance of RSgDrawable is not a null handle and no sl@0: RSgDriver handle has been opened in the context of the process. sl@0: @panic SGRES 3 The instance of RSgDrawable is an invalid handle. sl@0: */ sl@0: IMPORT_C TUid DrawableType() const; sl@0: sl@0: /** sl@0: Makes the extension interface specified by the type of the parameter sl@0: aInterfacePtr available on a drawable resource. sl@0: This function stores a pointer to the extension interface in the variable sl@0: referenced by the parameter aInterfacePtr and returns KErrNone if successful. sl@0: The returned extension interface is tied to the drawable resource, that is, sl@0: calls to functions in the returned extension interface operate on the sl@0: drawable resource. sl@0: sl@0: @pre An RSgDriver handle has been opened in the context of the process. sl@0: @pre The instance of RSgDrawable is an open handle. sl@0: @param[out] aInterfacePtr Reference to a pointer to the interface class. that on return points sl@0: to the extension interface or, in case of error, is set to NULL. sl@0: @return KErrNone if successful; sl@0: KErrBadHandle if the instance of RSgDrawable is a null handle; sl@0: KErrExtensionNotSupported if the requested extension interface is not supported. sl@0: @panic SGRES 1 No RSgDriver handle has been opened in the context of the process. sl@0: @panic SGRES 3 The instance of RSgDrawable is an invalid handle. sl@0: */ sl@0: template inline TInt GetInterface(M*& aInterfacePtr) const; sl@0: protected: sl@0: /** sl@0: Handle base constructor. sl@0: Used by constructors of derived classes to initialise the handle type. sl@0: @post The instance of RSgDrawable is a null handle. sl@0: @param aHandleType The UID identifying the handle type. sl@0: */ sl@0: inline RSgDrawable(TUid aHandleType); sl@0: private: sl@0: /** sl@0: Copy constructor. sl@0: Implementation not provided. Declared private to prevent bit-wise copying sl@0: of handles. sl@0: */ sl@0: RSgDrawable(const RSgDrawable&); sl@0: sl@0: /** sl@0: Assignment operator. sl@0: Implementation not provided. Declared private to prevent bit-wise copying sl@0: of handles. sl@0: */ sl@0: const RSgDrawable& operator =(const RSgDrawable&); sl@0: sl@0: /** sl@0: Makes the extension interface with the given UID available on a drawable sl@0: resource. sl@0: This function stores a pointer to the extension interface in the variable sl@0: referenced by the parameter aInterfacePtr and returns KErrNone if successful. sl@0: The returned extension interface is tied to the drawable resource, that is, sl@0: calls to functions in the returned extension interface operate on the sl@0: drawable resource. sl@0: sl@0: @pre An RSgDriver handle has been opened in the context of the process. sl@0: @pre The instance of RSgDrawable is an open handle. sl@0: @param[in] aInterfaceUid The UID of the extension interface. sl@0: @param[out] aInterfacePtr Reference to an untyped pointer that on return points sl@0: to the extension interface or, in case of error, is set to NULL. sl@0: @return KErrNone if successful; sl@0: KErrBadHandle if the instance of RSgDrawable is a null handle; sl@0: KErrArgument if aInterfaceUid is the null UID; sl@0: KErrExtensionNotSupported if the requested extension interface is not supported. sl@0: @panic SGRES 1 No RSgDriver handle has been opened in the context of the process. sl@0: @panic SGRES 3 The instance of RSgDrawable is an invalid handle. sl@0: */ sl@0: IMPORT_C TInt GetInterface(TUid aInterfaceUid, TAny*& aInterfacePtr) const; sl@0: protected: sl@0: /** sl@0: A UID permanently set by the constructor to the constant sl@0: KSgDrawableTypeUid, except for subclasses of RSgDrawable, in which case it sl@0: is permanently set by the constructor to the UID corresponding to the sl@0: concrete type of drawable resource referenced by instances of the subclass. sl@0: */ sl@0: const TUid iHandleType; sl@0: sl@0: /** A pointer to an implementation-defined object initially set to NULL by the constructor.*/ sl@0: TAny* iImpl; sl@0: }; sl@0: sl@0: #include sl@0: sl@0: #endif // SGRESOURCE_H