1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/graphics/graphicsresourceservices/graphicsresourceinterface/inc/sgresource.h Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,503 @@
1.4 +// Copyright (c) 2007-2009 Nokia Corporation and/or its subsidiary(-ies).
1.5 +// All rights reserved.
1.6 +// This component and the accompanying materials are made available
1.7 +// under the terms of "Eclipse Public License v1.0"
1.8 +// which accompanies this distribution, and is available
1.9 +// at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.10 +//
1.11 +// Initial Contributors:
1.12 +// Nokia Corporation - initial contribution.
1.13 +//
1.14 +// Contributors:
1.15 +//
1.16 +// Description:
1.17 +// Graphics Resource - general functionality
1.18 +//
1.19 +
1.20 +#ifndef SGRESOURCE_H
1.21 +#define SGRESOURCE_H
1.22 +
1.23 +#include <e32std.h>
1.24 +#include <sgresource/sgconst.h>
1.25 +
1.26 +/**
1.27 +Panic codes defined for use by the Graphics Resource API.
1.28 +*/
1.29 +enum TSgResourcePanicReason
1.30 + {
1.31 + ESgPanicNoDriver = 1,
1.32 + ESgPanicUnclosedResources = 2,
1.33 + ESgPanicBadDrawableHandle = 3,
1.34 + ESgPanicBadAttributeArrayIndex = 4
1.35 + };
1.36 +
1.37 +/**
1.38 +Panics the calling thread with category “SGRES” and the given panic code.
1.39 +@param aReason The panic code.
1.40 +*/
1.41 +inline void Panic(TSgResourcePanicReason aReason);
1.42 +
1.43 +/**
1.44 +A handle to the implementation of the Graphics Resource API
1.45 +initialised in the context of a process. It groups miscellaneous functions that
1.46 +do not apply to individual drawable resources.
1.47 +
1.48 +At least one thread in the process must call RSgDriver::Open() before the
1.49 +Graphics Resource API can be used in the context of the process.
1.50 +When the Graphics Resource API is no longer needed RSgDriver::Close() should be
1.51 +called to release unused resources. Note that it is possible to call RSgDriver::Open()
1.52 +and RSgDriver::Close() from different threads.
1.53 +*/
1.54 +NONSHARABLE_CLASS(RSgDriver)
1.55 + {
1.56 +public:
1.57 + /**
1.58 + Default constructor.
1.59 + @post The instance of RSgDriver is a null handle.
1.60 + */
1.61 + inline RSgDriver();
1.62 +
1.63 + /**
1.64 + Initialises the implementation of the Graphics Resource API in the context
1.65 + of a process if it is not initialised already, updates the implementation
1.66 + opening count in the process and returns KErrNone if successful.
1.67 + Each successful call to RSgDriver::Open() in a process should be balanced
1.68 + by a corresponding call to RSgDriver::Close() in the same process, but not
1.69 + necessarily from the same thread.
1.70 +
1.71 + Note that an RSgDriver handle should never be bitwise-copied into another
1.72 + but this function should be used instead in all cases, since it is the only
1.73 + way to ensure that the implementation opening count is kept up to date.
1.74 + Failure to keep the implementation opening count up to date may result in
1.75 + the implementation of the Graphics Resource API becoming unexpectedly
1.76 + unavailable and, as a consequence, in an abnormal termination of the process.
1.77 +
1.78 + @pre The instance of RSgDriver is a null handle.
1.79 + @post The instance of RSgDriver references the implementation of the Graphics
1.80 + Resource API initialised in the context of the process.
1.81 + @return KErrNone if successful;
1.82 + KErrInUse if the instance of RSgDriver is not a null handle;
1.83 + KErrNoMemory if there is not enough system memory to initialise the
1.84 + implementation of the Graphics Resource API;
1.85 + KErrNoGraphicsMemory if there is not enough specialised graphics memory
1.86 + to initialise the implementation of the Graphics Resource API.
1.87 + */
1.88 + IMPORT_C TInt Open();
1.89 +
1.90 + /**
1.91 + Decrements the implementation opening count in the process.
1.92 + When the count reaches zero, checks whether there are still open handles to
1.93 + drawable resources in the process and carries out termination tasks to
1.94 + release the internal resources used by the implementation of the Graphics
1.95 + Resource API.
1.96 +
1.97 + An attempt to carry out these termination tasks will panic with category
1.98 + “SGRES” and code 2 in debug builds if there still are any open handles to
1.99 + drawable resources in the process. In release builds all the open handles
1.100 + to drawable resources in the process are silently closed at this point.
1.101 + Calling this function on a null handle has no effect.
1.102 +
1.103 + @post The instance of RSgDriver is a null handle.
1.104 + @panic SGRES 2 Debug builds only. There are open handles to drawable resources
1.105 + in the process during termination.
1.106 + */
1.107 + IMPORT_C void Close();
1.108 +
1.109 + /**
1.110 + Makes the extension interface specified by the type of the parameter
1.111 + aInterfacePtr available in the context of the process.
1.112 + This function stores a pointer to the extension interface in the variable
1.113 + referenced by the parameter aInterfacePtr and returns KErrNone if successful.
1.114 +
1.115 + @pre An RSgDriver has been opened in the context of the process.
1.116 + @param[out] aInterfacePtr Reference to a pointer to the interface class that on return points
1.117 + to the extension interface or, in case of error, is set to NULL.
1.118 + @return KErrNone if successful;
1.119 + KErrBadHandle if the instance of RSgDriver is a null handle;
1.120 + KErrExtensionNotSupported if the requested extension interface is not supported.
1.121 + */
1.122 + template<class M> inline TInt GetInterface(M*& aInterfacePtr) const;
1.123 +
1.124 + /**
1.125 + Returns the version of the implementation of the Graphics Resource API.
1.126 + The version comprises 3 numbers: major version number, minor version number
1.127 + and build number.
1.128 +
1.129 + Major revisions mean incompatible changes in the API.
1.130 + Minor revisions mean forward-compatible changes in the API.
1.131 + Build numbers are unrelated to API changes.
1.132 +
1.133 + @return The version of the implementation of the Graphics Resource API.
1.134 + */
1.135 + IMPORT_C static TVersion Version();
1.136 +private:
1.137 + /**
1.138 + Copy constructor.
1.139 + Implementation not provided. Declared private to prevent bit-wise copying
1.140 + of handles.
1.141 + */
1.142 + RSgDriver(const RSgDriver&);
1.143 +
1.144 + /**
1.145 + Assignment operator.
1.146 + Implementation not provided. Declared private to prevent bit-wise copying
1.147 + of handles.
1.148 + */
1.149 + const RSgDriver& operator =(const RSgDriver&);
1.150 +
1.151 + /**
1.152 + Makes the extension interface with the given UID available in the context
1.153 + of the process.
1.154 + This function stores a pointer to the extension interface in the variable
1.155 + referenced by the parameter aInterfacePtr and returns KErrNone if successful.
1.156 +
1.157 + @pre An RSgDriver has been opened in the context of the process.
1.158 + @param[in] aInterfaceUid The UID of the extension interface.
1.159 + @param[out] aInterfacePtr Reference to an untyped pointer that on return points
1.160 + to the extension interface or, in case of error, is set to NULL.
1.161 + @return KErrNone if successful;
1.162 + KErrBadHandle if the instance of RSgDriver is a null handle;
1.163 + KErrArgument if aInterfaceUid is the null UID;
1.164 + KErrExtensionNotSupported if the requested extension interface is not supported.
1.165 + */
1.166 + IMPORT_C TInt GetInterface(TUid aInterfaceUid, TAny*& aInterfacePtr) const;
1.167 +private:
1.168 + /** A pointer to an implementation-defined object initially set to NULL by the constructor.*/
1.169 + TAny* iImpl;
1.170 + };
1.171 +
1.172 +/**
1.173 +An extension attribute.
1.174 +*/
1.175 +NONSHARABLE_CLASS(TSgAttribute)
1.176 + {
1.177 +public:
1.178 + /**
1.179 + Default constructor.
1.180 + Data members remain uninitialised.
1.181 + */
1.182 + inline TSgAttribute();
1.183 +
1.184 + /**
1.185 + Constructor which initialises data members to the given values.
1.186 + */
1.187 + inline TSgAttribute(TUid aUid, TInt aValue);
1.188 +public:
1.189 + /** A UID that identifies the type of extension attribute.*/
1.190 + TUid iUid;
1.191 + /** The value of the extension attribute.*/
1.192 + TInt iValue;
1.193 + };
1.194 +
1.195 +/**
1.196 +Base class of all attribute array classes.
1.197 +It defines functions for bounds-checked access to extension attributes.
1.198 +*/
1.199 +NONSHARABLE_CLASS(TSgAttributeArrayBase)
1.200 + {
1.201 +public:
1.202 + /**
1.203 + Returns the number of extension attributes in the array.
1.204 + @return The number of extension attributes in the array.
1.205 + */
1.206 + inline TInt Count() const;
1.207 +
1.208 + /**
1.209 + Returns a reference to the extension attribute located in the array at the
1.210 + given position.
1.211 +
1.212 + @pre aIndex is equal to or greater than zero and less than the number of
1.213 + extension attributes in the array.
1.214 + @param aIndex The position of the extension attribute in the array.
1.215 + @return A reference to the extension attribute located in the array at the
1.216 + given position.
1.217 + @panic SGRES 4 Debug builds only. aIndex is out of bounds.
1.218 + */
1.219 + inline TSgAttribute& operator [](TInt aIndex);
1.220 +
1.221 + /**
1.222 + Returns a const-qualified reference to the extension attribute located in
1.223 + the array at the given position.
1.224 +
1.225 + @pre aIndex is equal to or greater than zero and less than the number of
1.226 + extension attributes in the array.
1.227 + @param aIndex The position of the extension attribute in the array.
1.228 + @return A reference to the extension attribute located in the array at the
1.229 + given position.
1.230 + @panic SGRES 4 Debug builds only. aIndex is out of bounds.
1.231 + */
1.232 + inline const TSgAttribute& operator [](TInt aIndex) const;
1.233 +protected:
1.234 + /**
1.235 + Constructor used by constructors of derived classes to initialise the
1.236 + attribute count.
1.237 + @param aCount The number of extension attributes.
1.238 + */
1.239 + inline TSgAttributeArrayBase(TInt aCount);
1.240 +
1.241 + /**
1.242 + Assignment operator.
1.243 + No operation is performed. Allows the compiler to generate assignment
1.244 + operators for derived classes automatically.
1.245 + */
1.246 + inline void operator =(const TSgAttributeArrayBase&);
1.247 +private:
1.248 + const TInt iCount;
1.249 + };
1.250 +
1.251 +/**
1.252 +A fixed-size array of extension attributes.
1.253 +It is a thin wrapper with bounds checking for arrays of TSgAttribute.
1.254 +*/
1.255 +template<TInt S>
1.256 +NONSHARABLE_CLASS(TSgAttributeArray): public TSgAttributeArrayBase
1.257 + {
1.258 +public:
1.259 + /**
1.260 + Default constructor.
1.261 + Data members remain uninitialised.
1.262 + */
1.263 + inline TSgAttributeArray();
1.264 +private:
1.265 + TSgAttribute iAttributes[S];
1.266 + };
1.267 +
1.268 +/**
1.269 +A system-wide unique 64-bit identifier that can be used to share a drawable
1.270 +resource between processes.
1.271 +
1.272 +The actual value of a drawable resource identifier has no meaning to the user
1.273 +of the Graphics Resource API, except that 64 zero bits represent the null
1.274 +drawable resource identifier, which explicitly identifies no drawable resource.
1.275 +As a convenience, the constant KSgNullDrawableId is defined as the null drawable
1.276 +resource identifier.
1.277 +*/
1.278 +NONSHARABLE_CLASS(TSgDrawableId)
1.279 + {
1.280 +public:
1.281 + /**
1.282 + Equality operator.
1.283 + Tests whether the given drawable resource identifier is the same as this.
1.284 +
1.285 + @param aId The drawable resource identifier to compare with this.
1.286 + @return ETrue if the 64-bit identifiers are the same, EFalse if not.
1.287 + */
1.288 + inline TBool operator ==(TSgDrawableId aId) const;
1.289 +
1.290 + /**
1.291 + Inequality operator.
1.292 + Tests whether the given drawable resource identifier is different from this.
1.293 +
1.294 + @param aId The drawable resource identifier to compare with this.
1.295 + @return ETrue if the 64-bit identifiers are different, EFalse if they are the same.
1.296 + */
1.297 + inline TBool operator !=(TSgDrawableId aId) const;
1.298 +public:
1.299 + /** The 64-bit identifier.*/
1.300 + TUint64 iId;
1.301 + };
1.302 +
1.303 +/**
1.304 +The null drawable resource identifier.
1.305 +*/
1.306 +const TSgDrawableId KSgNullDrawableId = {0};
1.307 +
1.308 +/**
1.309 +The UID identifying a RSgDrawable handle.
1.310 +This must never be changed.
1.311 +*/
1.312 +const TUid KSgDrawableTypeUid = {0x102858EB};
1.313 +
1.314 +/**
1.315 +A drawable resource handle.
1.316 +A null handle is a handle that explicitly does not reference any drawable resource.
1.317 +An open handle is a handle that references an existing drawable resource.
1.318 +An invalid handle is a handle that is not null but does not reference any
1.319 +existing drawable resource.
1.320 +Drawable resources are reference-counted so that a drawable resource is not
1.321 +destroyed while there still are open handles to it in any process in the system.
1.322 +
1.323 +RSgDrawable is not an abstract class, that is, it can be instantiated,
1.324 +but it can also be derived from to define subclasses representing types of
1.325 +handles that refer only to concrete types of drawable resources, for example,
1.326 +image handles. RSgImage is the only subclass of RSgDrawable defined in version
1.327 +1.1 of the Graphics Resource API.
1.328 +Instances of RSgDrawable are useful when drawable resources created in a
1.329 +component have to be passed to another component through a third component that
1.330 +cannot depend on the concrete type of the drawable resources being passed.
1.331 +@see RSgImage
1.332 +*/
1.333 +NONSHARABLE_CLASS(RSgDrawable)
1.334 + {
1.335 +public:
1.336 + /**
1.337 + Default constructor.
1.338 + @post The instance of RSgDrawable is a null handle.
1.339 + */
1.340 + inline RSgDrawable();
1.341 +
1.342 + /**
1.343 + Opens a new handle to the drawable resource with the given drawable resource
1.344 + identifier.
1.345 + The drawable resource may have been created in the same process or in a
1.346 + different one. This function does not allocate any specialised graphics memory.
1.347 +
1.348 + Note that an RSgDrawable handle should never be bitwise-copied into another
1.349 + but this function should be used instead in all cases, since it is the only
1.350 + way to ensure that the reference count of the drawable resource is kept up
1.351 + to date. Failure to keep the reference count of the resource up to date may
1.352 + result in invalid handles.
1.353 +
1.354 + @pre An RSgDriver handle has been opened in the context of the process.
1.355 + @pre The instance of RSgDrawable is a null handle.
1.356 + @post The specified drawable resource has its reference count incremented by one.
1.357 + @param aId The identifier of the drawable resource.
1.358 + @param aAttributes A pointer to an array of extension attributes,
1.359 + if allowed by any extension of the Graphics Resource API, or NULL otherwise.
1.360 + @return KErrNone if successful;
1.361 + KErrInUse if the instance of RSgDrawable is an open handle;
1.362 + KErrArgument if the parameter aId is the null drawable resource identifier;
1.363 + KErrNotSupported if the parameter aAttributes is not NULL and one or more
1.364 + of the extension attributes in the array is not defined by any extension
1.365 + of the Graphics Resource API;
1.366 + KErrNotFound if the parameter aId cannot be found to refer to an existing
1.367 + drawable resource;
1.368 + KErrNoMemory if it fails due to lack of system memory.
1.369 + @panic SGRES 1 No RSgDriver handle has been opened in the context of the process.
1.370 + */
1.371 + IMPORT_C TInt Open(TSgDrawableId aId, const TSgAttributeArrayBase* aAttributes = NULL);
1.372 +
1.373 + /**
1.374 + Closes a handle to a drawable resource.
1.375 + It decrements the reference count of the drawable resource and, if it reaches
1.376 + zero, destroys the drawable resource.
1.377 + Calling this function on a null handle has no effect.
1.378 +
1.379 + @pre If the instance of RSgDrawable is not a null handle then an RSgDriver
1.380 + handle has been opened in the context of the process.
1.381 + @post The instance of RSgDrawable is a null handle.
1.382 + @panic SGRES 1 The instance of RSgDrawable is not a null handle and no
1.383 + RSgDriver handle has been opened in the context of the process.
1.384 + @panic SGRES 3 The instance of RSgDrawable is an invalid handle.
1.385 + */
1.386 + IMPORT_C void Close();
1.387 +
1.388 + /**
1.389 + Returns the identifier of the drawable resource.
1.390 + This identifier can be used to open another handle to the drawable resource
1.391 + in the same process or in a different process.
1.392 + Calling this function on a null handle returns the null drawable resource
1.393 + identifier.
1.394 +
1.395 + @pre If the instance of RSgDrawable is not a null handle then an RSgDriver
1.396 + handle has been opened in the context of the process.
1.397 + @return The identifier of the drawable resource.
1.398 + @panic SGRES 1 The instance of RSgDrawable is not a null handle and no
1.399 + RSgDriver handle has been opened in the context of the process.
1.400 + @panic SGRES 3 The instance of RSgDrawable is an invalid handle.
1.401 + */
1.402 + IMPORT_C TSgDrawableId Id() const;
1.403 +
1.404 + /**
1.405 + Tests whether a handle is null.
1.406 + @return ETrue if the instance of RSgDrawable is a null handle; EFalse otherwise.
1.407 + */
1.408 + inline TBool IsNull() const;
1.409 +
1.410 + /**
1.411 + Returns the UID corresponding to the concrete type of the drawable resource
1.412 + referenced by a handle at run-time.
1.413 + Calling this function on a null handle returns the null UID.
1.414 + In version 1.1 of the Graphics Resource API every drawable resource is an image,
1.415 + so this function always returns KSgImageTypeUid when called on an open handle.
1.416 +
1.417 + @pre If the instance of RSgDrawable is not a null handle then an RSgDriver
1.418 + handle has been opened in the context of the process.
1.419 + @return The UID corresponding to the concrete type of the drawable resource.
1.420 + @panic SGRES 1 The instance of RSgDrawable is not a null handle and no
1.421 + RSgDriver handle has been opened in the context of the process.
1.422 + @panic SGRES 3 The instance of RSgDrawable is an invalid handle.
1.423 + */
1.424 + IMPORT_C TUid DrawableType() const;
1.425 +
1.426 + /**
1.427 + Makes the extension interface specified by the type of the parameter
1.428 + aInterfacePtr available on a drawable resource.
1.429 + This function stores a pointer to the extension interface in the variable
1.430 + referenced by the parameter aInterfacePtr and returns KErrNone if successful.
1.431 + The returned extension interface is tied to the drawable resource, that is,
1.432 + calls to functions in the returned extension interface operate on the
1.433 + drawable resource.
1.434 +
1.435 + @pre An RSgDriver handle has been opened in the context of the process.
1.436 + @pre The instance of RSgDrawable is an open handle.
1.437 + @param[out] aInterfacePtr Reference to a pointer to the interface class. that on return points
1.438 + to the extension interface or, in case of error, is set to NULL.
1.439 + @return KErrNone if successful;
1.440 + KErrBadHandle if the instance of RSgDrawable is a null handle;
1.441 + KErrExtensionNotSupported if the requested extension interface is not supported.
1.442 + @panic SGRES 1 No RSgDriver handle has been opened in the context of the process.
1.443 + @panic SGRES 3 The instance of RSgDrawable is an invalid handle.
1.444 + */
1.445 + template<class M> inline TInt GetInterface(M*& aInterfacePtr) const;
1.446 +protected:
1.447 + /**
1.448 + Handle base constructor.
1.449 + Used by constructors of derived classes to initialise the handle type.
1.450 + @post The instance of RSgDrawable is a null handle.
1.451 + @param aHandleType The UID identifying the handle type.
1.452 + */
1.453 + inline RSgDrawable(TUid aHandleType);
1.454 +private:
1.455 + /**
1.456 + Copy constructor.
1.457 + Implementation not provided. Declared private to prevent bit-wise copying
1.458 + of handles.
1.459 + */
1.460 + RSgDrawable(const RSgDrawable&);
1.461 +
1.462 + /**
1.463 + Assignment operator.
1.464 + Implementation not provided. Declared private to prevent bit-wise copying
1.465 + of handles.
1.466 + */
1.467 + const RSgDrawable& operator =(const RSgDrawable&);
1.468 +
1.469 + /**
1.470 + Makes the extension interface with the given UID available on a drawable
1.471 + resource.
1.472 + This function stores a pointer to the extension interface in the variable
1.473 + referenced by the parameter aInterfacePtr and returns KErrNone if successful.
1.474 + The returned extension interface is tied to the drawable resource, that is,
1.475 + calls to functions in the returned extension interface operate on the
1.476 + drawable resource.
1.477 +
1.478 + @pre An RSgDriver handle has been opened in the context of the process.
1.479 + @pre The instance of RSgDrawable is an open handle.
1.480 + @param[in] aInterfaceUid The UID of the extension interface.
1.481 + @param[out] aInterfacePtr Reference to an untyped pointer that on return points
1.482 + to the extension interface or, in case of error, is set to NULL.
1.483 + @return KErrNone if successful;
1.484 + KErrBadHandle if the instance of RSgDrawable is a null handle;
1.485 + KErrArgument if aInterfaceUid is the null UID;
1.486 + KErrExtensionNotSupported if the requested extension interface is not supported.
1.487 + @panic SGRES 1 No RSgDriver handle has been opened in the context of the process.
1.488 + @panic SGRES 3 The instance of RSgDrawable is an invalid handle.
1.489 + */
1.490 + IMPORT_C TInt GetInterface(TUid aInterfaceUid, TAny*& aInterfacePtr) const;
1.491 +protected:
1.492 + /**
1.493 + A UID permanently set by the constructor to the constant
1.494 + KSgDrawableTypeUid, except for subclasses of RSgDrawable, in which case it
1.495 + is permanently set by the constructor to the UID corresponding to the
1.496 + concrete type of drawable resource referenced by instances of the subclass.
1.497 + */
1.498 + const TUid iHandleType;
1.499 +
1.500 + /** A pointer to an implementation-defined object initially set to NULL by the constructor.*/
1.501 + TAny* iImpl;
1.502 + };
1.503 +
1.504 +#include <sgresource/sgresource.inl>
1.505 +
1.506 +#endif // SGRESOURCE_H