1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/graphics/graphicsresourceservices/graphicsresource/src/sgimage.cpp Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,476 @@
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 +//
1.18 +
1.19 +#include "sgdriver.h"
1.20 +#include "sgimageadapter.h"
1.21 +
1.22 +
1.23 +/**
1.24 +@publishedPartner
1.25 +@prototype
1.26 +@deprecated
1.27 +
1.28 +Default constructor.
1.29 +
1.30 +@pre None.
1.31 +@post All the data members of this instance of TSgImageInfo are zero, false or null.
1.32 +*/
1.33 +EXPORT_C TSgImageInfo::TSgImageInfo()
1.34 + {
1.35 + Mem::FillZ(this, sizeof(TSgImageInfo));
1.36 + }
1.37 +
1.38 +
1.39 +/**
1.40 +@publishedPartner
1.41 +@prototype
1.42 +@deprecated
1.43 +
1.44 +Default constructor.
1.45 +
1.46 +@pre None.
1.47 +@post This RSgImage handle is null.
1.48 +*/
1.49 +EXPORT_C RSgImage::RSgImage()
1.50 + {
1.51 + iHandleType = KSgImageTypeUid;
1.52 + }
1.53 +
1.54 +
1.55 +/**
1.56 +@publishedPartner
1.57 +@prototype
1.58 +@deprecated
1.59 +
1.60 +Creates an image with the specified attributes and, optionally, the specified
1.61 +initial contents.
1.62 +
1.63 +@param aInfo The attributes of the image to be created.
1.64 +@param aDataAddress The base address of the pixel data used to populate the new image.
1.65 + If this value is null, the initial contents of the image are undefined.
1.66 + If aInfo specifies that the new image is constant, this value must not be null.
1.67 +@param aDataStride The number of bytes between rows of the pixel data used to populate
1.68 + the new image.
1.69 +@pre The Graphics Resource driver is initialised for use in the context of the
1.70 + calling process.
1.71 +@pre This RSgImage handle is null.
1.72 +@pre aInfo is supported.
1.73 +@post This RSgImage handle references a newly created image with the specified
1.74 + attributes and initial contents. The initial reference count for the image
1.75 + is one.
1.76 +@return KErrNone if successful.
1.77 +@return KErrInUse if this RSgImage handle was not null.
1.78 +@return KErrArgument if aInfo is invalid.
1.79 +@return KErrNoInitializationData if aInfo requests a constant image and aDataAddress
1.80 + is null.
1.81 +@return KErrTooBig if the size specified in aInfo is too large.
1.82 +@return KErrNotSupported if aInfo is not supported.
1.83 +@return KErrNoMemory if there is not enough system memory.
1.84 +@return KErrNoSpecializedMemory if there is not enough specialised graphics memory.
1.85 +@panic SGRES 5 in debug builds if the Graphics Resource driver is not initialised
1.86 + for use in the context of the calling process.
1.87 +*/
1.88 +EXPORT_C TInt RSgImage::Create(const TSgImageInfo& aInfo, const TAny* aDataAddress, TInt aDataStride)
1.89 + {
1.90 +#ifdef _DEBUG
1.91 + gPls.iMutex.Wait();
1.92 + __ASSERT_DEBUG(gPls.iDriver, Panic(ESgPanicNoDriver));
1.93 +#endif
1.94 + TInt err = gPls.iDriver->CreateImage(aInfo, aDataAddress, aDataStride, iImpl);
1.95 +#ifdef _DEBUG
1.96 + gPls.iMutex.Signal();
1.97 +#endif
1.98 + return err;
1.99 + }
1.100 +
1.101 +
1.102 +/**
1.103 +@publishedPartner
1.104 +@prototype
1.105 +@deprecated
1.106 +
1.107 +Creates an image with the specified attributes and initial contents copied from an
1.108 +existing image. The size and the pixel format of the image to be created must be the
1.109 +same as the size and the pixel format of the existing image.
1.110 +
1.111 +@param aInfo The attributes of the image to be created.
1.112 +@param aImage A handle to the existing image to be copied.
1.113 +@pre The Graphics Resource driver is initialised for use in the context of the
1.114 + calling process.
1.115 +@pre This RSgImage handle is null.
1.116 +@pre aInfo is supported.
1.117 +@pre aImage is a valid and not null handle.
1.118 +@pre The size and the pixel format specified in aInfo must be the same as the size
1.119 + and the pixel format of aImage.
1.120 +@post This RSgImage handle references a newly created image with the specified
1.121 + attributes and initial contents. The initial reference count for the image
1.122 + is one.
1.123 +@return KErrNone if successful.
1.124 +@return KErrInUse if this RSgImage handle was not null.
1.125 +@return KErrArgument if aInfo is invalid or if aImage is a null handle.
1.126 +@return KErrNotSupported if aInfo is not supported or if the size and the pixel format
1.127 + specified in aInfo are not the same as the size and the pixel format of aImage.
1.128 +@return KErrNoMemory if there is not enough system memory.
1.129 +@return KErrNoSpecializedMemory if there is not enough specialised graphics memory.
1.130 +@panic SGRES 3 in debug builds if aImage is an invalid handle.
1.131 +@panic SGRES 5 in debug builds if the Graphics Resource driver is not initialised
1.132 + for use in the context of the calling process.
1.133 +*/
1.134 +EXPORT_C TInt RSgImage::Create(const TSgImageInfo& aInfo, const RSgImage& aImage)
1.135 + {
1.136 +#ifdef _DEBUG
1.137 + gPls.iMutex.Wait();
1.138 + __ASSERT_DEBUG(gPls.iDriver, Panic(ESgPanicNoDriver));
1.139 +#endif
1.140 + TInt err = gPls.iDriver->CreateImage(aInfo, static_cast<MSgImageAdapter*>(aImage.iImpl), iImpl);
1.141 +#ifdef _DEBUG
1.142 + gPls.iMutex.Signal();
1.143 +#endif
1.144 + return err;
1.145 + }
1.146 +
1.147 +
1.148 +/**
1.149 +@publishedPartner
1.150 +@prototype
1.151 +@deprecated
1.152 +
1.153 +Retrieves the values of the attributes of an image. This function can also retrieve
1.154 +the values of selected user-defined attributes attached to an image by passing in
1.155 +the globally unique identifiers of the user-defined attributes to be retrieved.
1.156 +
1.157 +@param aInfo On input, the globally unique identifiers of the user-defined attributes
1.158 + to be retrieved from the image, if any. On return, the values of the attributes
1.159 + of the image and the values of the selected user-defined attributes.
1.160 +@pre The Graphics Resource driver is initialised for use in the context of the
1.161 + calling process.
1.162 +@pre This RSgImage handle is valid and not null.
1.163 +@pre If aInfo.iUserAttributes is not null then it points to an array of
1.164 + aInfo.iUserAttributeCount elements with globally unique identifiers
1.165 + corresponding to user-defined attributes attached to the image.
1.166 +@post None.
1.167 +@return KErrNone if successful.
1.168 +@return KErrBadHandle if this RSgImage handle is null.
1.169 +@return KErrNotFound if any of the user-defined attributes to be retrieved from the
1.170 + image cannot be found.
1.171 +@panic SGRES 3 in debug builds if this RSgImage handle is invalid.
1.172 +@panic SGRES 5 in debug builds if the Graphics Resource driver is not initialised
1.173 + for use in the context of the calling process.
1.174 +@see TSgImageInfo
1.175 +*/
1.176 +EXPORT_C TInt RSgImage::GetInfo(TSgImageInfo& aInfo) const
1.177 + {
1.178 + if (!iImpl)
1.179 + {
1.180 + return KErrBadHandle;
1.181 + }
1.182 +#ifdef _DEBUG
1.183 + gPls.iMutex.Wait();
1.184 + __ASSERT_DEBUG(gPls.iDriver, Panic(ESgPanicNoDriver));
1.185 + __ASSERT_DEBUG(gPls.iDriver->CheckImage(*iImpl), Panic(ESgPanicBadImageHandle));
1.186 +#endif
1.187 + TInt err = static_cast<MSgImageAdapter*>(iImpl)->GetInfo(aInfo);
1.188 +#ifdef _DEBUG
1.189 + gPls.iMutex.Signal();
1.190 +#endif
1.191 + return err;
1.192 + }
1.193 +
1.194 +
1.195 +/**
1.196 +@publishedPartner
1.197 +@prototype
1.198 +@deprecated
1.199 +
1.200 +Temporarily makes the pixel data of an image accessible for reading by the CPU.
1.201 +Undefined behaviour occurs if the CPU tries to modify the pixel data.
1.202 +
1.203 +When finished with the pixel data, the caller must end the mapping by calling Unmap()
1.204 +on this RSgImage handle.
1.205 +
1.206 +If an image is shared across processes, only the creator process is allowed to map
1.207 +the image for access to its pixel data.
1.208 +
1.209 +Depending upon the hardware architecture, whilst an image is mapped the GPU may be
1.210 +denied access to the pixel data, so this function may cause GPU operations that use
1.211 +this image to fail if proper synchronisation is not provided by means of the
1.212 +mechanisms available from the different rendering pipelines or from specialised
1.213 +synchronisation objects. Likewise, if the GPU is using the image at the time this
1.214 +function is called, the mapping may fail with KErrInUse. Note that even if operations
1.215 +do not fail, the results are not guaranteed to be correct unless proper synchronisation
1.216 +is provided.
1.217 +
1.218 +@param aDataAddress On return, the base address of the pixel data in the address
1.219 + space of the calling process.
1.220 +@param aDataStride On return, the number of bytes between rows of the pixel data.
1.221 +@pre The Graphics Resource driver is initialised for use in the context of the
1.222 + calling process.
1.223 +@pre This RSgImage handle is valid and not null.
1.224 +@pre The image is not mapped yet.
1.225 +@pre The image was created with CPU access ESgCpuAccessReadOnly or ESgCpuAccessReadWrite.
1.226 +@pre The image was created by the calling process.
1.227 +@post The pixel data of the image is directly accessible in the address space of the
1.228 + calling process for reading only, until Unmap() is called.
1.229 +@return KErrNone if successful.
1.230 +@return KErrBadHandle if this RSgImage handle is null.
1.231 +@return KErrInUse if the image is already mapped or in exclusive use by the GPU.
1.232 +@return KErrAccessDenied if the image was not created with CPU access ESgCpuAccessReadOnly
1.233 + or ESgCpuAccessReadWrite.
1.234 +@return KErrPermissionDenied if the image was created by another process.
1.235 +@return KErrNoMemory if there is not enough system memory.
1.236 +@panic SGRES 3 in debug builds if this RSgImage handle is invalid.
1.237 +@panic SGRES 5 in debug builds if the Graphics Resource driver is not initialised
1.238 + for use in the context of the calling process.
1.239 +*/
1.240 +EXPORT_C TInt RSgImage::MapReadOnly(const TAny*& aDataAddress, TInt& aDataStride) const
1.241 + {
1.242 + if (!iImpl)
1.243 + {
1.244 + return KErrBadHandle;
1.245 + }
1.246 +#ifdef _DEBUG
1.247 + gPls.iMutex.Wait();
1.248 + __ASSERT_DEBUG(gPls.iDriver, Panic(ESgPanicNoDriver));
1.249 + __ASSERT_DEBUG(gPls.iDriver->CheckImage(*iImpl), Panic(ESgPanicBadImageHandle));
1.250 +#endif
1.251 + TInt err = static_cast<MSgImageAdapter*>(iImpl)->MapReadOnly(aDataAddress, aDataStride);
1.252 +#ifdef _DEBUG
1.253 + gPls.iMutex.Signal();
1.254 +#endif
1.255 + return err;
1.256 + }
1.257 +
1.258 +
1.259 +/**
1.260 +@publishedPartner
1.261 +@prototype
1.262 +@deprecated
1.263 +
1.264 +Temporarily makes the pixel data of an image accessible for writing by the CPU.
1.265 +Any pre-existing content is discarded, meaning that the mapped memory initially
1.266 +contains undefined pixel data.
1.267 +
1.268 +When finished with the pixel data, the caller must end the mapping by calling Unmap()
1.269 +on this RSgImage handle. The caller is required to write to every pixel of the image
1.270 +before unmapping.
1.271 +
1.272 +If an image is shared across processes, only the creator process is allowed to map
1.273 +the image for access to its pixel data.
1.274 +
1.275 +Depending upon the hardware architecture, whilst an image is mapped the GPU may be
1.276 +denied access to the pixel data, so this function may cause GPU operations that use
1.277 +this image to fail if proper synchronisation is not provided by means of the
1.278 +mechanisms available from the different rendering pipelines or from specialised
1.279 +synchronisation objects. Likewise, if the GPU is using the image at the time this
1.280 +function is called, the mapping may fail with KErrInUse. Note that even if operations
1.281 +do not fail, the results are not guaranteed to be correct unless proper synchronisation
1.282 +is provided.
1.283 +
1.284 +@param aDataAddress On return, the base address of the pixel data in the address
1.285 + space of the calling process.
1.286 +@param aDataStride On return, the number of bytes between rows of the pixel data.
1.287 +@pre The Graphics Resource driver is initialised for use in the context of the
1.288 + calling process.
1.289 +@pre This RSgImage handle is valid and not null.
1.290 +@pre The image is not mapped yet.
1.291 +@pre The image was created with CPU access ESgCpuAccessWriteOnly or ESgCpuAccessReadWrite.
1.292 +@pre The image was created by the calling process.
1.293 +@post The pixel data of the image is directly accessible in the address space of the
1.294 + calling process for writing only, until Unmap() is called.
1.295 +@return KErrNone if successful.
1.296 +@return KErrBadHandle if this RSgImage handle is null.
1.297 +@return KErrInUse if the image is already mapped or in exclusive use by the GPU.
1.298 +@return KErrAccessDenied if the image was not created with CPU access ESgCpuAccessWriteOnly
1.299 + or ESgCpuAccessReadWrite.
1.300 +@return KErrPermissionDenied if the image was created by another process.
1.301 +@return KErrNoMemory if there is not enough system memory.
1.302 +@panic SGRES 3 in debug builds if this RSgImage handle is invalid.
1.303 +@panic SGRES 5 in debug builds if the Graphics Resource driver is not initialised
1.304 + for use in the context of the calling process.
1.305 +*/
1.306 +EXPORT_C TInt RSgImage::MapWriteOnly(TAny*& aDataAddress, TInt& aDataStride)
1.307 + {
1.308 + if (!iImpl)
1.309 + {
1.310 + return KErrBadHandle;
1.311 + }
1.312 +#ifdef _DEBUG
1.313 + gPls.iMutex.Wait();
1.314 + __ASSERT_DEBUG(gPls.iDriver, Panic(ESgPanicNoDriver));
1.315 + __ASSERT_DEBUG(gPls.iDriver->CheckImage(*iImpl), Panic(ESgPanicBadImageHandle));
1.316 +#endif
1.317 + TInt err = static_cast<MSgImageAdapter*>(iImpl)->MapWriteOnly(aDataAddress, aDataStride);
1.318 +#ifdef _DEBUG
1.319 + gPls.iMutex.Signal();
1.320 +#endif
1.321 + return err;
1.322 + }
1.323 +
1.324 +
1.325 +/**
1.326 +@publishedPartner
1.327 +@prototype
1.328 +@deprecated
1.329 +
1.330 +Temporarily makes the pixel data of an image accessible for reading and writing
1.331 +by the CPU.
1.332 +
1.333 +When finished with the pixel data, the caller must end the mapping by calling Unmap()
1.334 +on this RSgImage handle. Any modification performed by the CPU will be retained upon
1.335 +unmapping.
1.336 +
1.337 +If an image is shared across processes, only the creator process is allowed to map
1.338 +the image for access to its pixel data.
1.339 +
1.340 +Depending upon the hardware architecture, whilst an image is mapped the GPU may be
1.341 +denied access to the pixel data, so this function may cause GPU operations that use
1.342 +this image to fail if proper synchronisation is not provided by means of the
1.343 +mechanisms available from the different rendering pipelines or from specialised
1.344 +synchronisation objects. Likewise, if the GPU is using the image at the time this
1.345 +function is called, the mapping may fail with KErrInUse. Note that even if operations
1.346 +do not fail, the results are not guaranteed to be correct unless proper synchronisation
1.347 +is provided.
1.348 +
1.349 +@param aDataAddress On return, the base address of the pixel data in the address
1.350 + space of the calling process.
1.351 +@param aDataStride On return, the number of bytes between rows of the pixel data.
1.352 +@pre The Graphics Resource driver is initialised for use in the context of the
1.353 + calling process.
1.354 +@pre This RSgImage handle is valid and not null.
1.355 +@pre The image is not mapped yet.
1.356 +@pre The image was created with CPU access ESgCpuAccessReadWrite.
1.357 +@pre The image was created by the calling process.
1.358 +@post The pixel data of the image is directly accessible in the address space of the
1.359 + calling process for reading and writing, until Unmap() is called.
1.360 +@return KErrNone if successful.
1.361 +@return KErrBadHandle if this RSgImage handle is null.
1.362 +@return KErrInUse if the image is already mapped or in exclusive use by the GPU.
1.363 +@return KErrAccessDenied if the image was not created with CPU access
1.364 + ESgCpuAccessReadWrite.
1.365 +@return KErrPermissionDenied if the image was created by another process.
1.366 +@return KErrNoMemory if there is not enough system memory.
1.367 +@panic SGRES 3 in debug builds if this RSgImage handle is invalid.
1.368 +@panic SGRES 5 in debug builds if the Graphics Resource driver is not initialised
1.369 + for use in the context of the calling process.
1.370 +*/
1.371 +EXPORT_C TInt RSgImage::MapReadWrite(TAny*& aDataAddress, TInt& aDataStride)
1.372 + {
1.373 + if (!iImpl)
1.374 + {
1.375 + return KErrBadHandle;
1.376 + }
1.377 +#ifdef _DEBUG
1.378 + gPls.iMutex.Wait();
1.379 + __ASSERT_DEBUG(gPls.iDriver, Panic(ESgPanicNoDriver));
1.380 + __ASSERT_DEBUG(gPls.iDriver->CheckImage(*iImpl), Panic(ESgPanicBadImageHandle));
1.381 +#endif
1.382 + TInt err = static_cast<MSgImageAdapter*>(iImpl)->MapReadWrite(aDataAddress, aDataStride);
1.383 +#ifdef _DEBUG
1.384 + gPls.iMutex.Signal();
1.385 +#endif
1.386 + return err;
1.387 + }
1.388 +
1.389 +
1.390 +/**
1.391 +@publishedPartner
1.392 +@prototype
1.393 +@deprecated
1.394 +
1.395 +Makes the pixel data of an image no longer accessible by the CPU. If the image was
1.396 +mapped for writing by the CPU, any written data is retained and any subsequent usage
1.397 +of the image by the GPU will reflect its new state.
1.398 +
1.399 +If the last handle to an image in a process is closed while the image is still mapped
1.400 +by the process then the image will be automatically unmapped.
1.401 +
1.402 +@pre The Graphics Resource driver is initialised for use in the context of the
1.403 + calling process.
1.404 +@pre This RSgImage handle is valid and not null.
1.405 +@pre The image is mapped for CPU access by a previous call to MapReadOnly(),
1.406 + MapWriteOnly() or MapReadWrite().
1.407 +@post The GPU is guaranteed to be able to get access to the image.
1.408 +@post The address range in the calling process used for the mapping is no longer
1.409 + valid. Attempts by the calling process to access any address in this range
1.410 + will result in undefined behaviour.
1.411 +@return KErrNone if successful.
1.412 +@return KErrBadHandle if this RSgImage handle is null.
1.413 +@return KErrGeneral if the image was not mapped for CPU access.
1.414 +@panic SGRES 3 in debug builds if this RSgImage handle is invalid.
1.415 +@panic SGRES 5 in debug builds if the Graphics Resource driver is not initialised
1.416 + for use in the context of the calling process.
1.417 +*/
1.418 +EXPORT_C TInt RSgImage::Unmap() const
1.419 + {
1.420 + if (!iImpl)
1.421 + {
1.422 + return KErrBadHandle;
1.423 + }
1.424 +#ifdef _DEBUG
1.425 + gPls.iMutex.Wait();
1.426 + __ASSERT_DEBUG(gPls.iDriver, Panic(ESgPanicNoDriver));
1.427 + __ASSERT_DEBUG(gPls.iDriver->CheckImage(*iImpl), Panic(ESgPanicBadImageHandle));
1.428 +#endif
1.429 + TInt err = static_cast<MSgImageAdapter*>(iImpl)->Unmap();
1.430 +#ifdef _DEBUG
1.431 + gPls.iMutex.Signal();
1.432 +#endif
1.433 + return err;
1.434 + }
1.435 +
1.436 +
1.437 +/**
1.438 +@publishedPartner
1.439 +@prototype
1.440 +@deprecated
1.441 +
1.442 +Retrieves the list of image pixel formats supported on this device for a specified
1.443 +usage. This function is often called before creating images.
1.444 +
1.445 +@param aInfo The image attributes. aInfo.iPixelFormat is ignored.
1.446 +@param aPixelFormats A pointer to an array that on return will contain the supported
1.447 + pixel formats. If this parameter is null, then this function will just
1.448 + return the number of supported pixel formats in aCount.
1.449 +@param aCount On input, the number of elements in the array pointed to by aPixelFormats
1.450 + if not null, ignored otherwise. On return, the actual number of supported pixel
1.451 + formats. If this number is greater than the number of elements in the array,
1.452 + then the array will be filled with as many pixel formats as it can hold and the
1.453 + function will return KErrOverflow.
1.454 +@pre The Graphics Resource driver is initialised for use in the context of the
1.455 + calling process.
1.456 +@pre aInfo is valid.
1.457 +@pre If aPixelFormats is not null then aCount is greater than zero.
1.458 +@post None.
1.459 +@return KErrNone if successful.
1.460 +@return KErrArgument if aInfo is invalid or if aPixelFormats is not null and aCount
1.461 + is negative.
1.462 +@return KErrOverflow if the actual number of supported pixel formats is greater than
1.463 + the number of elements in the array pointed to by aPixelFormats.
1.464 +@return KErrNoMemory if there is not enough system memory.
1.465 +@panic SGRES 5 in debug builds if the Graphics Resource driver is not initialised
1.466 + for use in the context of the calling process.
1.467 +*/
1.468 +EXPORT_C TInt RSgImage::GetPixelFormats(const TSgImageInfo& aInfo, TUidPixelFormat* aPixelFormats, TInt& aCount)
1.469 + {
1.470 +#ifdef _DEBUG
1.471 + gPls.iMutex.Wait();
1.472 + __ASSERT_DEBUG(gPls.iDriver, Panic(ESgPanicNoDriver));
1.473 +#endif
1.474 + TInt err = gPls.iDriver->GetPixelFormats(aInfo, aPixelFormats, aCount);
1.475 +#ifdef _DEBUG
1.476 + gPls.iMutex.Signal();
1.477 +#endif
1.478 + return err;
1.479 + }