1 // Copyright (c) 2007-2009 Nokia Corporation and/or its subsidiary(-ies).

     2 // All rights reserved.

     3 // This component and the accompanying materials are made available

     4 // under the terms of "Eclipse Public License v1.0"

     5 // which accompanies this distribution, and is available

     6 // at the URL "http://www.eclipse.org/legal/epl-v10.html".

     7 //

     8 // Initial Contributors:

     9 // Nokia Corporation - initial contribution.

    10 //

    11 // Contributors:

    12 //

    13 // Description:

    14 //

    15 

    16 #include "sgdriver.h"

    17 #include "sgimagecollectionadapter.h"

    18 

    19 

    20 /**

    21 @internalComponent

    22 */

    23 const TSurfaceId KNullSurfaceId = {0, 0, 0, 0};

    24 

    25 

    26 /**

    27 @publishedPartner

    28 @prototype

    29 @deprecated

    30 

    31 Default constructor.

    32 

    33 @pre None.

    34 @post This RSgImageCollection handle is null.

    35 */

    36 EXPORT_C RSgImageCollection::RSgImageCollection()

    37 	: iImpl(NULL)

    38 	{}

    39 

    40 

    41 /**

    42 @publishedPartner

    43 @prototype

    44 @deprecated

    45 

    46 Creates an image collection with the specified attributes. The number of images in

    47 the collection cannot be changed after creation. The images in the collection have

    48 identical attributes. The initial contents of all the images are undefined.

    49 

    50 @param aInfo The image attributes of the collection to be created.

    51 @param aImageCount The number of images in the collection to be created.

    52 @pre The Graphics Resource driver is initialised for use in the context of the

    53      calling process.

    54 @pre This RSgImageCollection handle is null.

    55 @pre aInfo is supported and specifies mutable images.

    56 @pre aImageCount is greater than zero.

    57 @post This RSgImageCollection handle references a newly created image collection with

    58       the specified attributes. The initial reference count for the image collection

    59       is one.

    60 @return KErrNone if successful.

    61 @return KErrInUse if this RSgImageCollection handle was not null.

    62 @return KErrArgument if aInfo is invalid or if aImageCount is negative or zero.

    63 @return KErrTooBig if the size specified in aInfo is too large.

    64 @return KErrNotSupported if aInfo is not supported or does not specify mutable images.

    65 @return KErrNoMemory if there is not enough system memory.

    66 @return KErrNoSpecializedMemory if there is not enough specialised graphics memory.

    67 @panic SGRES 5 in debug builds if the Graphics Resource driver is not initialised

    68        for use in the context of the calling process.

    69 */

    70 EXPORT_C TInt RSgImageCollection::Create(const TSgImageInfo& aInfo, TInt aImageCount)

    71 	{

    72 #ifdef _DEBUG

    73 	gPls.iMutex.Wait();

    74 	__ASSERT_DEBUG(gPls.iDriver, Panic(ESgPanicNoDriver));

    75 #endif

    76 	TInt err = gPls.iDriver->CreateImageCollection(aInfo, aImageCount, iImpl);

    77 #ifdef _DEBUG

    78 	gPls.iMutex.Signal();

    79 #endif

    80 	return err;

    81 	}

    82 

    83 

    84 /**

    85 @publishedPartner

    86 @prototype

    87 @deprecated

    88 

    89 Creates a set of image collections that share a single memory chunk. The number of

    90 images in each collection is the same and cannot be changed after creation. The images

    91 in each collection have identical attributes. The initial contents of all the images

    92 are undefined.

    93 

    94 Care must be taken when using image collections created in this way. In particular,

    95 writing to the Nth image of one collection may invalidate the contents of the Nth image

    96 of all other collections, but will not affect any other images.

    97 

    98 @param aInfos An array of aCollectionCount elements with the image attributes of each

    99        of the collections to be created.

   100 @param aImageCount The number of images in each of the collections to be created.

   101 @param aCollections On return, an array of RSgImageCollection handles that reference

   102        newly created image collections with the specified attributes.

   103 @param aCollectionCount The number of image collections to be created.

   104 @pre The Graphics Resource driver is initialised for use in the context of the

   105      calling process.

   106 @pre All the elements of aInfos are supported and specify mutable images.

   107 @pre aImageCount is greater than zero.

   108 @pre All the RSgImageCollection handles in aCollections are null.

   109 @pre aCollectionCount is greater than zero.

   110 @post The initial reference count for each of the newly created image collections is one.

   111 @return KErrNone if successful.

   112 @return KErrInUse if any of the RSgImageCollection handles in aCollections was not null.

   113 @return KErrArgument if any element of aInfos is invalid, if aImageCount is negative

   114         or zero, or if aCollectionCount is negative or zero.

   115 @return KErrTooBig if any of the sizes specified in aInfos is too large.

   116 @return KErrNotSupported if any element of aInfos is not supported or does not specify

   117         mutable images.

   118 @return KErrNoMemory if there is not enough system memory.

   119 @return KErrNoSpecializedMemory if there is not enough specialised graphics memory.

   120 @panic SGRES 5 in debug builds if the Graphics Resource driver is not initialised

   121        for use in the context of the calling process.

   122 */

   123 EXPORT_C TInt RSgImageCollection::Create(const TSgImageInfo aInfos[], TInt aImageCount,

   124                                          RSgImageCollection aCollections[], TInt aCollectionCount)

   125 	{

   126 #ifdef _DEBUG

   127 	gPls.iMutex.Wait();

   128 	__ASSERT_DEBUG(gPls.iDriver, Panic(ESgPanicNoDriver));

   129 #endif

   130 	TInt err = gPls.iDriver->CreateImageCollections(aInfos, aImageCount,

   131 	                                                reinterpret_cast<MSgImageCollectionAdapter**>(aCollections), aCollectionCount);

   132 #ifdef _DEBUG

   133 	gPls.iMutex.Signal();

   134 #endif

   135 	return err;

   136 	}

   137 

   138 

   139 /**

   140 @publishedPartner

   141 @prototype

   142 @deprecated

   143 

   144 Closes a handle to an image collection. If there are no remaining handles to

   145 the image collection, then it can be destroyed by the Graphics Resource driver.

   146 Calling Close() on a null handle is allowed but has no effect.

   147 

   148 @pre If this RSgImageCollection handle is not null then the Graphics Resource

   149      driver is initialised for use in the context of the calling process.

   150 @pre This RSgImageCollection handle is valid.

   151 @post This RSgImageCollection handle is null. The reference count for the

   152       previously referenced image collection, if any, is decremented by one.

   153 @panic SGRES 4 in debug builds if this RSgImageCollection handle is invalid.

   154 @panic SGRES 5 in debug builds if this RSgImageCollection handle is not null

   155        and the Graphics Resource driver is not initialised for use in the

   156        context of the calling process.

   157 */

   158 EXPORT_C void RSgImageCollection::Close()

   159 	{

   160 	if (iImpl)

   161 		{

   162 #ifdef _DEBUG

   163 		gPls.iMutex.Wait();

   164 		__ASSERT_DEBUG(gPls.iDriver, Panic(ESgPanicNoDriver));

   165 		__ASSERT_DEBUG(gPls.iDriver->CheckImageCollection(*iImpl), Panic(ESgPanicBadImageCollectionHandle));

   166 #endif

   167 		iImpl->Close();

   168 		iImpl = NULL;

   169 #ifdef _DEBUG

   170 		gPls.iMutex.Signal();

   171 #endif

   172 		}

   173 	}

   174 

   175 

   176 /**

   177 @publishedPartner

   178 @prototype

   179 @deprecated

   180 

   181 Retrieves the surface identifier of an image collection.

   182 

   183 @pre The Graphics Resource driver is initialised for use in the context of the

   184      calling process.

   185 @pre This RSgImageCollection handle is valid.

   186 @post None.

   187 @return The surface identifier of the image collection or the null surface identifier

   188         if this RSgImageCollection handle is null.

   189 @panic SGRES 4 in debug builds if this RSgImageCollection handle is invalid.

   190 @panic SGRES 5 in debug builds if the Graphics Resource driver is not initialised

   191        for use in the context of the calling process.

   192 */

   193 EXPORT_C const TSurfaceId& RSgImageCollection::SurfaceId() const

   194 	{

   195 	if (!iImpl)

   196 		{

   197 		return KNullSurfaceId;

   198 		}

   199 #ifdef _DEBUG

   200 	gPls.iMutex.Wait();

   201 	__ASSERT_DEBUG(gPls.iDriver, Panic(ESgPanicNoDriver));

   202 	__ASSERT_DEBUG(gPls.iDriver->CheckImageCollection(*iImpl), Panic(ESgPanicBadImageCollectionHandle));

   203 #endif

   204 	const TSurfaceId& id = iImpl->SurfaceId();

   205 #ifdef _DEBUG

   206 	gPls.iMutex.Signal();

   207 #endif

   208 	return id;

   209 	}

   210 

   211 

   212 /**

   213 @publishedPartner

   214 @prototype

   215 @deprecated

   216 

   217 Tests whether this RSgImageCollection handle is null.

   218 

   219 @pre None.

   220 @post None.

   221 @return ETrue, if this RSgImageCollection handle is null, EFalse otherwise.

   222 */

   223 EXPORT_C TBool RSgImageCollection::IsNull() const

   224 	{

   225 	return iImpl == NULL;

   226 	}

   227 

   228 

   229 /**

   230 @publishedPartner

   231 @prototype

   232 @deprecated

   233 

   234 Retrieves the values of the attributes of the images in an image collection. This

   235 function can also retrieve the values of selected user-defined attributes attached

   236 to an image collection by passing in the globally unique identifiers of the

   237 user-defined attributes to be retrieved.

   238 

   239 @param aInfo On input, the globally unique identifiers of the user-defined attributes

   240        to be retrieved from the image collection, if any. On return, the values of

   241        the attributes of the images in the collection and the values of the selected

   242        user-defined attributes.

   243 @pre The Graphics Resource driver is initialised for use in the context of the

   244      calling process.

   245 @pre This RSgImageCollection handle is valid and not null.

   246 @pre If aInfo.iUserAttributes is not null then it points to an array of

   247      aInfo.iUserAttributeCount elements with globally unique identifiers

   248      corresponding to user-defined attributes attached to the image collection.

   249 @post None.

   250 @return KErrNone if successful.

   251 @return KErrBadHandle if this RSgImageCollection handle is null.

   252 @return KErrNotFound if any of the user-defined attributes to be retrieved from the

   253         image collection cannot be found.

   254 @panic SGRES 4 in debug builds if this RSgImageCollection handle is invalid.

   255 @panic SGRES 5 in debug builds if the Graphics Resource driver is not initialised

   256        for use in the context of the calling process.

   257 */

   258 EXPORT_C TInt RSgImageCollection::GetInfo(TSgImageInfo& aInfo) const

   259 	{

   260 	if (!iImpl)

   261 		{

   262 		return KErrBadHandle;

   263 		}

   264 #ifdef _DEBUG

   265 	gPls.iMutex.Wait();

   266 	__ASSERT_DEBUG(gPls.iDriver, Panic(ESgPanicNoDriver));

   267 	__ASSERT_DEBUG(gPls.iDriver->CheckImageCollection(*iImpl), Panic(ESgPanicBadImageCollectionHandle));

   268 #endif

   269 	TInt err = iImpl->GetInfo(aInfo);

   270 #ifdef _DEBUG

   271 	gPls.iMutex.Signal();

   272 #endif

   273 	return err;

   274 	}

   275 

   276 

   277 /**

   278 @publishedPartner

   279 @prototype

   280 @deprecated

   281 

   282 Retrieves the number of images in an image collection.

   283 

   284 @pre The Graphics Resource driver is initialised for use in the context of the

   285      calling process.

   286 @pre This RSgImageCollection handle is valid.

   287 @post None.

   288 @return The number of images in the image collection or zero if this RSgImageCollection

   289         handle is null.

   290 @panic SGRES 4 in debug builds if this RSgImageCollection handle is invalid.

   291 @panic SGRES 5 in debug builds if the Graphics Resource driver is not initialised

   292        for use in the context of the calling process.

   293 */

   294 EXPORT_C TInt RSgImageCollection::Count() const

   295 	{

   296 	if (!iImpl)

   297 		{

   298 		return 0;

   299 		}

   300 #ifdef _DEBUG

   301 	gPls.iMutex.Wait();

   302 	__ASSERT_DEBUG(gPls.iDriver, Panic(ESgPanicNoDriver));

   303 	__ASSERT_DEBUG(gPls.iDriver->CheckImageCollection(*iImpl), Panic(ESgPanicBadImageCollectionHandle));

   304 #endif

   305 	TInt count = iImpl->Count();

   306 #ifdef _DEBUG

   307 	gPls.iMutex.Signal();

   308 #endif

   309 	return count;

   310 	}

   311 

   312 

   313 /**

   314 @publishedPartner

   315 @prototype

   316 @deprecated

   317 

   318 Opens a new handle to one of the images in an image collection.

   319 

   320 @param aIndex The index of the image within the image collection.

   321 @param aResult On return, an RSgImage handle that references the specified image in

   322        the collection.

   323 @pre The Graphics Resource driver is initialised for use in the context of the

   324      calling process.

   325 @pre This RSgImageCollection handle is valid and not null.

   326 @pre aIndex is greater than or equal to zero and less than the number of images in

   327      the collection.

   328 @pre aResult is a null handle.

   329 @post The reference count for the image collection is incremented by one.

   330 @return KErrNone if successful.

   331 @return KErrBadHandle if this RSgImageCollection handle is null.

   332 @return KErrInUse if aResult was not a null handle.

   333 @return KErrArgument if aIndex is invalid.

   334 @return KErrNoMemory if there is not enough system memory.

   335 @panic SGRES 4 in debug builds if this RSgImageCollection handle is invalid.

   336 @panic SGRES 5 in debug builds if the Graphics Resource driver is not initialised

   337        for use in the context of the calling process.

   338 */

   339 EXPORT_C TInt RSgImageCollection::OpenImage(TInt aIndex, RSgImage& aResult)

   340 	{

   341 	if (!iImpl)

   342 		{

   343 		return KErrBadHandle;

   344 		}

   345 #ifdef _DEBUG

   346 	gPls.iMutex.Wait();

   347 	__ASSERT_DEBUG(gPls.iDriver, Panic(ESgPanicNoDriver));

   348 	__ASSERT_DEBUG(gPls.iDriver->CheckImageCollection(*iImpl), Panic(ESgPanicBadImageCollectionHandle));

   349 #endif

   350 	TInt err = iImpl->OpenImage(aIndex, aResult.iImpl);

   351 #ifdef _DEBUG

   352 	gPls.iMutex.Signal();

   353 #endif

   354 	return err;

   355 	}