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 "sgimageadapter.h"

    18 

    19 

    20 /**

    21 @publishedPartner

    22 @prototype

    23 @deprecated

    24 

    25 Default constructor.

    26 

    27 @pre None.

    28 @post All the data members of this instance of TSgImageInfo are zero, false or null.

    29 */

    30 EXPORT_C TSgImageInfo::TSgImageInfo()

    31 	{

    32 	Mem::FillZ(this, sizeof(TSgImageInfo));

    33 	}

    34 

    35 

    36 /**

    37 @publishedPartner

    38 @prototype

    39 @deprecated

    40 

    41 Default constructor.

    42 

    43 @pre None.

    44 @post This RSgImage handle is null.

    45 */

    46 EXPORT_C RSgImage::RSgImage()

    47 	{

    48 	iHandleType = KSgImageTypeUid;

    49 	}

    50 

    51 

    52 /**

    53 @publishedPartner

    54 @prototype

    55 @deprecated

    56 

    57 Creates an image with the specified attributes and, optionally, the specified

    58 initial contents.

    59 

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

    61 @param aDataAddress The base address of the pixel data used to populate the new image.

    62        If this value is null, the initial contents of the image are undefined.

    63        If aInfo specifies that the new image is constant, this value must not be null.

    64 @param aDataStride The number of bytes between rows of the pixel data used to populate

    65        the new image.

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

    67      calling process.

    68 @pre This RSgImage handle is null.

    69 @pre aInfo is supported.

    70 @post This RSgImage handle references a newly created image with the specified

    71       attributes and initial contents. The initial reference count for the image

    72       is one.

    73 @return KErrNone if successful.

    74 @return KErrInUse if this RSgImage handle was not null.

    75 @return KErrArgument if aInfo is invalid.

    76 @return KErrNoInitializationData if aInfo requests a constant image and aDataAddress

    77         is null.

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

    79 @return KErrNotSupported if aInfo is not supported.

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

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

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

    83        for use in the context of the calling process.

    84 */

    85 EXPORT_C TInt RSgImage::Create(const TSgImageInfo& aInfo, const TAny* aDataAddress, TInt aDataStride)

    86 	{

    87 #ifdef _DEBUG

    88 	gPls.iMutex.Wait();

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

    90 #endif

    91 	TInt err = gPls.iDriver->CreateImage(aInfo, aDataAddress, aDataStride, iImpl);

    92 #ifdef _DEBUG

    93 	gPls.iMutex.Signal();

    94 #endif

    95 	return err;

    96 	}

    97 

    98 

    99 /**

   100 @publishedPartner

   101 @prototype

   102 @deprecated

   103 

   104 Creates an image with the specified attributes and initial contents copied from an

   105 existing image. The size and the pixel format of the image to be created must be the

   106 same as the size and the pixel format of the existing image.

   107 

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

   109 @param aImage A handle to the existing image to be copied.

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

   111      calling process.

   112 @pre This RSgImage handle is null.

   113 @pre aInfo is supported.

   114 @pre aImage is a valid and not null handle.

   115 @pre The size and the pixel format specified in aInfo must be the same as the size

   116      and the pixel format of aImage.

   117 @post This RSgImage handle references a newly created image with the specified

   118       attributes and initial contents. The initial reference count for the image

   119       is one.

   120 @return KErrNone if successful.

   121 @return KErrInUse if this RSgImage handle was not null.

   122 @return KErrArgument if aInfo is invalid or if aImage is a null handle.

   123 @return KErrNotSupported if aInfo is not supported or if the size and the pixel format

   124         specified in aInfo are not the same as the size and the pixel format of aImage.

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

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

   127 @panic SGRES 3 in debug builds if aImage is an invalid handle.

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

   129        for use in the context of the calling process.

   130 */

   131 EXPORT_C TInt RSgImage::Create(const TSgImageInfo& aInfo, const RSgImage& aImage)

   132 	{

   133 #ifdef _DEBUG

   134 	gPls.iMutex.Wait();

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

   136 #endif

   137 	TInt err = gPls.iDriver->CreateImage(aInfo, static_cast<MSgImageAdapter*>(aImage.iImpl), iImpl);

   138 #ifdef _DEBUG

   139 	gPls.iMutex.Signal();

   140 #endif

   141 	return err;

   142 	}

   143 

   144 

   145 /**

   146 @publishedPartner

   147 @prototype

   148 @deprecated

   149 

   150 Retrieves the values of the attributes of an image. This function can also retrieve

   151 the values of selected user-defined attributes attached to an image by passing in

   152 the globally unique identifiers of the user-defined attributes to be retrieved.

   153 

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

   155        to be retrieved from the image, if any. On return, the values of the attributes

   156        of the image and the values of the selected user-defined attributes.

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

   158      calling process.

   159 @pre This RSgImage handle is valid and not null.

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

   161      aInfo.iUserAttributeCount elements with globally unique identifiers

   162      corresponding to user-defined attributes attached to the image.

   163 @post None.

   164 @return KErrNone if successful.

   165 @return KErrBadHandle if this RSgImage handle is null.

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

   167         image cannot be found.

   168 @panic SGRES 3 in debug builds if this RSgImage handle is invalid.

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

   170        for use in the context of the calling process.

   171 @see TSgImageInfo

   172 */

   173 EXPORT_C TInt RSgImage::GetInfo(TSgImageInfo& aInfo) const

   174 	{

   175 	if (!iImpl)

   176 		{

   177 		return KErrBadHandle;

   178 		}

   179 #ifdef _DEBUG

   180 	gPls.iMutex.Wait();

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

   182 	__ASSERT_DEBUG(gPls.iDriver->CheckImage(*iImpl), Panic(ESgPanicBadImageHandle));

   183 #endif

   184 	TInt err = static_cast<MSgImageAdapter*>(iImpl)->GetInfo(aInfo);

   185 #ifdef _DEBUG

   186 	gPls.iMutex.Signal();

   187 #endif

   188 	return err;

   189 	}

   190 

   191 

   192 /**

   193 @publishedPartner

   194 @prototype

   195 @deprecated

   196 

   197 Temporarily makes the pixel data of an image accessible for reading by the CPU.

   198 Undefined behaviour occurs if the CPU tries to modify the pixel data.

   199 

   200 When finished with the pixel data, the caller must end the mapping by calling Unmap()

   201 on this RSgImage handle.

   202 

   203 If an image is shared across processes, only the creator process is allowed to map

   204 the image for access to its pixel data.

   205 

   206 Depending upon the hardware architecture, whilst an image is mapped the GPU may be

   207 denied access to the pixel data, so this function may cause GPU operations that use

   208 this image to fail if proper synchronisation is not provided by means of the

   209 mechanisms available from the different rendering pipelines or from specialised

   210 synchronisation objects. Likewise, if the GPU is using the image at the time this

   211 function is called, the mapping may fail with KErrInUse. Note that even if operations

   212 do not fail, the results are not guaranteed to be correct unless proper synchronisation

   213 is provided.

   214 

   215 @param aDataAddress On return, the base address of the pixel data in the address

   216        space of the calling process.

   217 @param aDataStride On return, the number of bytes between rows of the pixel data.

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

   219      calling process.

   220 @pre This RSgImage handle is valid and not null.

   221 @pre The image is not mapped yet.

   222 @pre The image was created with CPU access ESgCpuAccessReadOnly or ESgCpuAccessReadWrite.

   223 @pre The image was created by the calling process.

   224 @post The pixel data of the image is directly accessible in the address space of the

   225       calling process for reading only, until Unmap() is called.

   226 @return KErrNone if successful.

   227 @return KErrBadHandle if this RSgImage handle is null.

   228 @return KErrInUse if the image is already mapped or in exclusive use by the GPU.

   229 @return KErrAccessDenied if the image was not created with CPU access ESgCpuAccessReadOnly

   230         or ESgCpuAccessReadWrite.

   231 @return KErrPermissionDenied if the image was created by another process.

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

   233 @panic SGRES 3 in debug builds if this RSgImage handle is invalid.

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

   235        for use in the context of the calling process.

   236 */

   237 EXPORT_C TInt RSgImage::MapReadOnly(const TAny*& aDataAddress, TInt& aDataStride) const

   238 	{

   239 	if (!iImpl)

   240 		{

   241 		return KErrBadHandle;

   242 		}

   243 #ifdef _DEBUG

   244 	gPls.iMutex.Wait();

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

   246 	__ASSERT_DEBUG(gPls.iDriver->CheckImage(*iImpl), Panic(ESgPanicBadImageHandle));

   247 #endif

   248 	TInt err = static_cast<MSgImageAdapter*>(iImpl)->MapReadOnly(aDataAddress, aDataStride);

   249 #ifdef _DEBUG

   250 	gPls.iMutex.Signal();

   251 #endif

   252 	return err;

   253 	}

   254 

   255 

   256 /**

   257 @publishedPartner

   258 @prototype

   259 @deprecated

   260 

   261 Temporarily makes the pixel data of an image accessible for writing by the CPU.

   262 Any pre-existing content is discarded, meaning that the mapped memory initially

   263 contains undefined pixel data.

   264 

   265 When finished with the pixel data, the caller must end the mapping by calling Unmap()

   266 on this RSgImage handle. The caller is required to write to every pixel of the image

   267 before unmapping.

   268 

   269 If an image is shared across processes, only the creator process is allowed to map

   270 the image for access to its pixel data.

   271 

   272 Depending upon the hardware architecture, whilst an image is mapped the GPU may be

   273 denied access to the pixel data, so this function may cause GPU operations that use

   274 this image to fail if proper synchronisation is not provided by means of the

   275 mechanisms available from the different rendering pipelines or from specialised

   276 synchronisation objects. Likewise, if the GPU is using the image at the time this

   277 function is called, the mapping may fail with KErrInUse. Note that even if operations

   278 do not fail, the results are not guaranteed to be correct unless proper synchronisation

   279 is provided.

   280 

   281 @param aDataAddress On return, the base address of the pixel data in the address

   282        space of the calling process.

   283 @param aDataStride On return, the number of bytes between rows of the pixel data.

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

   285      calling process.

   286 @pre This RSgImage handle is valid and not null.

   287 @pre The image is not mapped yet.

   288 @pre The image was created with CPU access ESgCpuAccessWriteOnly or ESgCpuAccessReadWrite.

   289 @pre The image was created by the calling process.

   290 @post The pixel data of the image is directly accessible in the address space of the

   291       calling process for writing only, until Unmap() is called.

   292 @return KErrNone if successful.

   293 @return KErrBadHandle if this RSgImage handle is null.

   294 @return KErrInUse if the image is already mapped or in exclusive use by the GPU.

   295 @return KErrAccessDenied if the image was not created with CPU access ESgCpuAccessWriteOnly

   296         or ESgCpuAccessReadWrite.

   297 @return KErrPermissionDenied if the image was created by another process.

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

   299 @panic SGRES 3 in debug builds if this RSgImage handle is invalid.

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

   301        for use in the context of the calling process.

   302 */

   303 EXPORT_C TInt RSgImage::MapWriteOnly(TAny*& aDataAddress, TInt& aDataStride)

   304 	{

   305 	if (!iImpl)

   306 		{

   307 		return KErrBadHandle;

   308 		}

   309 #ifdef _DEBUG

   310 	gPls.iMutex.Wait();

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

   312 	__ASSERT_DEBUG(gPls.iDriver->CheckImage(*iImpl), Panic(ESgPanicBadImageHandle));

   313 #endif

   314 	TInt err = static_cast<MSgImageAdapter*>(iImpl)->MapWriteOnly(aDataAddress, aDataStride);

   315 #ifdef _DEBUG

   316 	gPls.iMutex.Signal();

   317 #endif

   318 	return err;

   319 	}

   320 

   321 

   322 /**

   323 @publishedPartner

   324 @prototype

   325 @deprecated

   326 

   327 Temporarily makes the pixel data of an image accessible for reading and writing

   328 by the CPU.

   329 

   330 When finished with the pixel data, the caller must end the mapping by calling Unmap()

   331 on this RSgImage handle. Any modification performed by the CPU will be retained upon

   332 unmapping.

   333 

   334 If an image is shared across processes, only the creator process is allowed to map

   335 the image for access to its pixel data.

   336 

   337 Depending upon the hardware architecture, whilst an image is mapped the GPU may be

   338 denied access to the pixel data, so this function may cause GPU operations that use

   339 this image to fail if proper synchronisation is not provided by means of the

   340 mechanisms available from the different rendering pipelines or from specialised

   341 synchronisation objects. Likewise, if the GPU is using the image at the time this

   342 function is called, the mapping may fail with KErrInUse. Note that even if operations

   343 do not fail, the results are not guaranteed to be correct unless proper synchronisation

   344 is provided.

   345 

   346 @param aDataAddress On return, the base address of the pixel data in the address

   347        space of the calling process.

   348 @param aDataStride On return, the number of bytes between rows of the pixel data.

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

   350      calling process.

   351 @pre This RSgImage handle is valid and not null.

   352 @pre The image is not mapped yet.

   353 @pre The image was created with CPU access ESgCpuAccessReadWrite.

   354 @pre The image was created by the calling process.

   355 @post The pixel data of the image is directly accessible in the address space of the

   356       calling process for reading and writing, until Unmap() is called.

   357 @return KErrNone if successful.

   358 @return KErrBadHandle if this RSgImage handle is null.

   359 @return KErrInUse if the image is already mapped or in exclusive use by the GPU.

   360 @return KErrAccessDenied if the image was not created with CPU access

   361         ESgCpuAccessReadWrite.

   362 @return KErrPermissionDenied if the image was created by another process.

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

   364 @panic SGRES 3 in debug builds if this RSgImage handle is invalid.

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

   366        for use in the context of the calling process.

   367 */

   368 EXPORT_C TInt RSgImage::MapReadWrite(TAny*& aDataAddress, TInt& aDataStride)

   369 	{

   370 	if (!iImpl)

   371 		{

   372 		return KErrBadHandle;

   373 		}

   374 #ifdef _DEBUG

   375 	gPls.iMutex.Wait();

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

   377 	__ASSERT_DEBUG(gPls.iDriver->CheckImage(*iImpl), Panic(ESgPanicBadImageHandle));

   378 #endif

   379 	TInt err = static_cast<MSgImageAdapter*>(iImpl)->MapReadWrite(aDataAddress, aDataStride);

   380 #ifdef _DEBUG

   381 	gPls.iMutex.Signal();

   382 #endif

   383 	return err;

   384 	}

   385 

   386 

   387 /**

   388 @publishedPartner

   389 @prototype

   390 @deprecated

   391 

   392 Makes the pixel data of an image no longer accessible by the CPU. If the image was

   393 mapped for writing by the CPU, any written data is retained and any subsequent usage

   394 of the image by the GPU will reflect its new state.

   395 

   396 If the last handle to an image in a process is closed while the image is still mapped

   397 by the process then the image will be automatically unmapped.

   398 

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

   400      calling process.

   401 @pre This RSgImage handle is valid and not null.

   402 @pre The image is mapped for CPU access by a previous call to MapReadOnly(),

   403      MapWriteOnly() or MapReadWrite().

   404 @post The GPU is guaranteed to be able to get access to the image.

   405 @post The address range in the calling process used for the mapping is no longer

   406       valid. Attempts by the calling process to access any address in this range

   407       will result in undefined behaviour.

   408 @return KErrNone if successful.

   409 @return KErrBadHandle if this RSgImage handle is null.

   410 @return KErrGeneral if the image was not mapped for CPU access.

   411 @panic SGRES 3 in debug builds if this RSgImage handle is invalid.

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

   413        for use in the context of the calling process.

   414 */

   415 EXPORT_C TInt RSgImage::Unmap() const

   416 	{

   417 	if (!iImpl)

   418 		{

   419 		return KErrBadHandle;

   420 		}

   421 #ifdef _DEBUG

   422 	gPls.iMutex.Wait();

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

   424 	__ASSERT_DEBUG(gPls.iDriver->CheckImage(*iImpl), Panic(ESgPanicBadImageHandle));

   425 #endif

   426 	TInt err = static_cast<MSgImageAdapter*>(iImpl)->Unmap();

   427 #ifdef _DEBUG

   428 	gPls.iMutex.Signal();

   429 #endif

   430 	return err;

   431 	}

   432 

   433 

   434 /**

   435 @publishedPartner

   436 @prototype

   437 @deprecated

   438 

   439 Retrieves the list of image pixel formats supported on this device for a specified

   440 usage. This function is often called before creating images.

   441 

   442 @param aInfo The image attributes. aInfo.iPixelFormat is ignored.

   443 @param aPixelFormats A pointer to an array that on return will contain the supported

   444        pixel formats. If this parameter is null, then this function will just

   445        return the number of supported pixel formats in aCount.

   446 @param aCount On input, the number of elements in the array pointed to by aPixelFormats

   447        if not null, ignored otherwise. On return, the actual number of supported pixel

   448        formats. If this number is greater than the number of elements in the array,

   449        then the array will be filled with as many pixel formats as it can hold and the

   450        function will return KErrOverflow.

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

   452      calling process.

   453 @pre aInfo is valid.

   454 @pre If aPixelFormats is not null then aCount is greater than zero.

   455 @post None.

   456 @return KErrNone if successful.

   457 @return KErrArgument if aInfo is invalid or if aPixelFormats is not null and aCount

   458         is negative.

   459 @return KErrOverflow if the actual number of supported pixel formats is greater than

   460         the number of elements in the array pointed to by aPixelFormats.

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

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

   463        for use in the context of the calling process.

   464 */

   465 EXPORT_C TInt RSgImage::GetPixelFormats(const TSgImageInfo& aInfo, TUidPixelFormat* aPixelFormats, TInt& aCount)

   466 	{

   467 #ifdef _DEBUG

   468 	gPls.iMutex.Wait();

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

   470 #endif

   471 	TInt err = gPls.iDriver->GetPixelFormats(aInfo, aPixelFormats, aCount);

   472 #ifdef _DEBUG

   473 	gPls.iMutex.Signal();

   474 #endif

   475 	return err;

   476 	}