Platform Package reference: Function EwLockBitmap()

Description of the function EwLockBitmap() available in all Platform Packages for C compatible target systems. This function is intended to be used when integrating the Embedded Wizard created GUI application with the underlying graphics subsystem, graphics hardware or other external GUI applications coexisting on the same system.

Declaration

XBitmapLock* EwLockBitmap

(

  XBitmap*   aBitmap,

  XInt32     aFrameNo,

  XRect      aArea,

  XBool      aRead,

  XBool      aWrite

)

Parameters

aBitmap

Bitmap to obtain the direct memory access.

aFrameNo

Frame number within the destination bitmap affected by the access operation.

aArea

Area within the frame affected by the access operation (relative to the top-left corner of the bitmap frame). This is the area, the caller intends to read/write the pixel data.

aRead

Is != 0 (not zero), if the caller intends to read the pixel information from the bitmap memory. If == 0, the memory content may remain undefined depending on the underlying graphics sub-system and its video-memory management.

aWrite

Is != 0 (not zero), if the caller intends to overwrite the pixel information within the bitmap memory. If == 0, any modifications within the memory may remain ignored depending on the underlying graphics sub-system and its video-memory management.

Discussion

The function EwLockBitmap() provides a direct access to the pixel memory of the given bitmap. The function returns a lock object XBitmapLock containing pointers to memory, the caller can use to read/write the bitmap pixel values. When finished, the function EwUnlockBitmap() should be used in order to release the lock, update the affected bitmap, flush CPU caches, etc.

The memory returned by the function is not guaranteed to be the real video memory associated to the bitmap. If necessary, the function will handle the access by using a shadow memory area. Therefore to limit the effort of memory copy operations, the desired bitmap area and the access mode should be specified explicitly. Note the three parameters aArea, aRead and aWrite. Depending on the graphics sub-system these three parameters may affect significantly the performance.

If there was not possible to lock the bitmap, or the desired access mode is not supported by the underlying graphics sub-system, the function fails and returns NULL (e.g. OpenGL based sub-systems usually allow the write access to bitmaps (textures) only. Read access may fail in this case).

IMPORTANT

If your GUI application is running on a device with rotated LCD (attribute ScreenOrientation is not Normal) the bitmaps store the pixel in the corresponding orientation. For example, with ScreenOrientation set to Rotated_270 the real origin of a bitmap is found at its top-right corner while the logical bitmap origin lies at its top-left corner. The function EwLockBitmap() takes care of the conversion between the logical coordinates passed in aArea and the real dimension of the locked bitmap. You should however be aware of the changed layout of how pixel are stored in rows and columns when accessing the bitmap memory returned in XBitmapLock structure. See also Extern Bitmap loader.