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".
8 // Initial Contributors:
9 // Nokia Corporation - initial contribution.
17 #include "sgimageadapter.h"
28 @post All the data members of this instance of TSgImageInfo are zero, false or null.
30 EXPORT_C TSgImageInfo::TSgImageInfo()
32 Mem::FillZ(this, sizeof(TSgImageInfo));
44 @post This RSgImage handle is null.
46 EXPORT_C RSgImage::RSgImage()
48 iHandleType = KSgImageTypeUid;
57 Creates an image with the specified attributes and, optionally, the specified
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
66 @pre The Graphics Resource driver is initialised for use in the context of the
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
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
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.
85 EXPORT_C TInt RSgImage::Create(const TSgImageInfo& aInfo, const TAny* aDataAddress, TInt aDataStride)
89 __ASSERT_DEBUG(gPls.iDriver, Panic(ESgPanicNoDriver));
91 TInt err = gPls.iDriver->CreateImage(aInfo, aDataAddress, aDataStride, iImpl);
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.
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
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
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.
131 EXPORT_C TInt RSgImage::Create(const TSgImageInfo& aInfo, const RSgImage& aImage)
135 __ASSERT_DEBUG(gPls.iDriver, Panic(ESgPanicNoDriver));
137 TInt err = gPls.iDriver->CreateImage(aInfo, static_cast<MSgImageAdapter*>(aImage.iImpl), iImpl);
139 gPls.iMutex.Signal();
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.
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
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.
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.
173 EXPORT_C TInt RSgImage::GetInfo(TSgImageInfo& aInfo) const
177 return KErrBadHandle;
181 __ASSERT_DEBUG(gPls.iDriver, Panic(ESgPanicNoDriver));
182 __ASSERT_DEBUG(gPls.iDriver->CheckImage(*iImpl), Panic(ESgPanicBadImageHandle));
184 TInt err = static_cast<MSgImageAdapter*>(iImpl)->GetInfo(aInfo);
186 gPls.iMutex.Signal();
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.
200 When finished with the pixel data, the caller must end the mapping by calling Unmap()
201 on this RSgImage handle.
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.
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
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
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.
237 EXPORT_C TInt RSgImage::MapReadOnly(const TAny*& aDataAddress, TInt& aDataStride) const
241 return KErrBadHandle;
245 __ASSERT_DEBUG(gPls.iDriver, Panic(ESgPanicNoDriver));
246 __ASSERT_DEBUG(gPls.iDriver->CheckImage(*iImpl), Panic(ESgPanicBadImageHandle));
248 TInt err = static_cast<MSgImageAdapter*>(iImpl)->MapReadOnly(aDataAddress, aDataStride);
250 gPls.iMutex.Signal();
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.
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
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.
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
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
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.
303 EXPORT_C TInt RSgImage::MapWriteOnly(TAny*& aDataAddress, TInt& aDataStride)
307 return KErrBadHandle;
311 __ASSERT_DEBUG(gPls.iDriver, Panic(ESgPanicNoDriver));
312 __ASSERT_DEBUG(gPls.iDriver->CheckImage(*iImpl), Panic(ESgPanicBadImageHandle));
314 TInt err = static_cast<MSgImageAdapter*>(iImpl)->MapWriteOnly(aDataAddress, aDataStride);
316 gPls.iMutex.Signal();
327 Temporarily makes the pixel data of an image accessible for reading and writing
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
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.
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
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
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.
368 EXPORT_C TInt RSgImage::MapReadWrite(TAny*& aDataAddress, TInt& aDataStride)
372 return KErrBadHandle;
376 __ASSERT_DEBUG(gPls.iDriver, Panic(ESgPanicNoDriver));
377 __ASSERT_DEBUG(gPls.iDriver->CheckImage(*iImpl), Panic(ESgPanicBadImageHandle));
379 TInt err = static_cast<MSgImageAdapter*>(iImpl)->MapReadWrite(aDataAddress, aDataStride);
381 gPls.iMutex.Signal();
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.
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.
399 @pre The Graphics Resource driver is initialised for use in the context of the
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.
415 EXPORT_C TInt RSgImage::Unmap() const
419 return KErrBadHandle;
423 __ASSERT_DEBUG(gPls.iDriver, Panic(ESgPanicNoDriver));
424 __ASSERT_DEBUG(gPls.iDriver->CheckImage(*iImpl), Panic(ESgPanicBadImageHandle));
426 TInt err = static_cast<MSgImageAdapter*>(iImpl)->Unmap();
428 gPls.iMutex.Signal();
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.
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
454 @pre If aPixelFormats is not null then aCount is greater than zero.
456 @return KErrNone if successful.
457 @return KErrArgument if aInfo is invalid or if aPixelFormats is not null and aCount
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.
465 EXPORT_C TInt RSgImage::GetPixelFormats(const TSgImageInfo& aInfo, TUidPixelFormat* aPixelFormats, TInt& aCount)
469 __ASSERT_DEBUG(gPls.iDriver, Panic(ESgPanicNoDriver));
471 TInt err = gPls.iDriver->GetPixelFormats(aInfo, aPixelFormats, aCount);
473 gPls.iMutex.Signal();