Platform Package reference: Type XBitmapLock

Description of the type definition XBitmapLock available in all Platform Packages for ANSI C compatible target systems. This type definition 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

typedef struct

{

  void*   Pixel1;

  int     Pitch1X;

  int     Pitch1Y;

  void*   Pixel2;

  int     Pitch2X;

  int     Pitch2Y;

} XBitmapLock;

Elements

Pixel1

First color memory plane pointer. The pointer refers to the first pixel of the locked bitmap area.

Pitch1X

Distance between two pixel columns of the first color plane expressed in bytes.

Pitch1Y

Distance between two pixel rows of the first color plane expressed in bytes.

Pixel2

Pointer to the second (optional) color plane or NULL. If not NULL, the pointer also refers to the first pixel of the locked bitmap area.

Pitch2X

Distance between two pixel columns of the second color plane expressed in bytes or 0 (zero) if the bitmap doesn't store the second plane.

Pitch2Y

Distance between two pixel rows of the second color plane expressed in bytes or 0 (zero) if the bitmap doesn't store the second plane.

Discussion

The XBitmapLock structure provides information to access the color planes (the memory) of a previously locked bitmap. In order to lock a bitmap, you use the function EwLockBitmap(). Please note, when you access the bitmap memory by using the information provided in a XBitmapLock data structure, you should always take in account the color format of the affected bitmap. From the color format results the layout of how pixel data is stored within the bitmap memory area.

You should understand, that in Embedded Wizard we distinguish between three main and one optional bitmap formats. The table below gives you a short overview of them. The layout of how pixel are stored in the memory of a bitmap depends usually on how the bitmaps are treated natively in your target system. More details regarding the pixel layout of the diverse supported formats is found in the sections following this table:

Format

Description

EW_PIXEL_FORMAT_NATIVE

Represents the main pixel format valid within the particular graphics subsystem without any assumptions about the respective color space, color components, etc. This is the pixel format, the target system is working with internally. In this manner the Graphics Engine remains platform and color independent. Please note, bitmaps with this color format can serve as destination and source in all drawing operations.

EW_PIXEL_FORMAT_ALPHA8

Universal 8-bit per pixel alpha only format. Useful as storage for glyphs, masks, etc. Please note, bitmaps with this color format can serve as source only in all drawing operations.

EW_PIXEL_FORMAT_INDEX8

Universal 8-bit per pixel palette format. This format expects an additional color palette for translation between an 8-bit index and the native color value. The colors within the palette are determined by using the function EwModifyBitmapPalette(). Please note, bitmaps with this color format can serve as source only in all drawing operations.

EW_PIXEL_FORMAT_RGB565

16-bit per pixel RGB color format without opacity information. This format is optional depending on your target system. Please note, bitmaps with this color format can serve as source only in all drawing operations.

Bitmap color format EW_PIXEL_FORMAT_NATIVE variant RGBA8888

Bitmaps in the variant RGBA8888 of the EW_PIXEL_FORMAT_NATIVE color format store their pixel packed as a sequence of 32-bit values. Every pixel consists of four 8-bit color components red, green, blue and alpha (opacity). These components are also known as color channels:

Depending on the target system and its particular graphics hardware, the order in which the color components are stored within a pixel can differ. Moreover, the color components red, green and blue can be stored as values premultiplied by the corresponding alpha component. In order to query the exact layout of how the color components are understood, following ANSI C macros are available and can be evaluated in your implementation when you read or modify the pixel information of a RGBA8888 bitmap:

Macro

Description

EW_COLOR_CHANNEL_BIT_OFFSET_RED

Evaluating this macro results in a bit offset within the 32-bit value at which the red color component is stored. This value can be either 0, 8, 16 or 24.

EW_COLOR_CHANNEL_BIT_OFFSET_GREEN

Evaluating this macro results in a bit offset within the 32-bit value at which the green color component is stored. This value can be either 0, 8, 16 or 24.

EW_COLOR_CHANNEL_BIT_OFFSET_BLUE

Evaluating this macro results in a bit offset within the 32-bit value at which the blue color component is stored. This value can be either 0, 8, 16 or 24.

EW_COLOR_CHANNEL_BIT_OFFSET_ALPHA

Evaluating this macro results in a bit offset within the 32-bit value at which the alpha color component is stored. This value can be either 0, 8, 16 or 24.

EW_PREMULTIPLY_COLOR_CHANNELS

If this macro is defined, the pixel store their color components red, green and blue as values premultiplied by the corresponding alpha component. If this macro is not defined, the color components are stored without being premultiplied. The last case is also known as linear or straight alpha.

The code example below demonstrates how you use the XBitmapLock structure and the above described macros to obtain access and modify the pixel information stored within a bitmap in RGBA8888 variant of the color format EW_PIXEL_FORMAT_NATIVE:

/* Include necessary header files */
#include "ewrte.h"
#include "ewgfxdriver.h"
#include "ewextgfx.h"
#include "ewgfxdefs.h"

/* Include one of the following header files depending on the version
  of your Graphics Engine */
#include "ewextpxl_RGB565.h"
#include "ewextpxl_RGB888.h"
#include "ewextpxl_RGBA8888.h"

[...]

/* We intend to modify the given 'area' of the bitmap.
   Lock the bitmap for write operation. */
XBitmap*      bitmap = ...
XRect         area   = ...
int           width  = area.Point2.X - area.Point1.X;
int           height = area.Point2.Y - area.Point1.Y;
XBitmapLock*  lock   = EwLockBitmap( bitmap, 0, area, 0, 1 );

/* Now get the pointer to the first pixel within the locked
   area. In the RGBA8888 format every pixel is a 32-bit value
   (unsigned int). Additionally calculate the offset in pixel
   between the end of one row and the begin of the next row. */
unsigned int* dest   = (unsigned int*)lock->Pixel1;
int           ofs    = ( lock->Pitch1Y / 4 ) - width;
int           x, y;

/* Iterate through the pixel within the locked area. Do this
   row-by-row and column-by-column. After one row is finished
   adjust the 'dest' pointer to refer to the next row. After
   one column is finished increment the 'dest' pointer only. */
for ( y = 0; y < height; y++, dest += ofs )
  for ( x = 0; x < width; x++, dest++ )
  {
    /* The color value you want to store in the pixel. Every variable
       is valid in range 0 .. 255. */
    unsigned int red   = ...
    unsigned int green = ...
    unsigned int blue  = ...
    unsigned int alpha = ...

    /* Should the color components be premultiplied by the alpha value?
       Please note, to optimize the implementation we divide the result
       of the multiplication by 256 (shift right 8) instead of by 255.
       Thus to reduce the calculation errors we increase the alpha value. */
    #ifdef EW_PREMULTIPLY_COLOR_CHANNELS
      red   = (( red   * ( alpha + 1 )) >> 8 );
      green = (( green * ( alpha + 1 )) >> 8 );
      blue  = (( blue  * ( alpha + 1 )) >> 8 );
    #endif

    /* Arrange the color components to appear at the corresponding
       bit-offset position within a 32-bit value. */
    red   <<= EW_COLOR_CHANNEL_BIT_OFFSET_RED;
    green <<= EW_COLOR_CHANNEL_BIT_OFFSET_GREEN;
    blue  <<= EW_COLOR_CHANNEL_BIT_OFFSET_BLUE;
    alpha <<= EW_COLOR_CHANNEL_BIT_OFFSET_ALPHA;
     
    /* Now compose the color components to a single 32-bit value and store
       the result in the bitmap memory ... */
    *dest = red | green | blue | alpha;
  }

/* Don't forget to unlock the bitmap when you are done! */
EwUnlockBitmap( lock );

Bitmap color format EW_PIXEL_FORMAT_NATIVE variant RGBA4444

Bitmaps in the variant RGBA4444 of the EW_PIXEL_FORMAT_NATIVE color format store their pixel packed as a sequence of 16-bit values. Every pixel consists of four 4-bit color components red, green, blue and alpha (opacity). These components are also known as color channels:

Depending on the target system and its particular graphics hardware, the order in which the color components are stored within a pixel can differ. Moreover, the color components red, green and blue can be stored as values premultiplied by the corresponding alpha component. In order to query the exact layout of how the color components are understood, following ANSI C macros are available and can be evaluated in your implementation when you read or modify the pixel information of a RGBA4444 bitmap:

Macro

Description

EW_COLOR_CHANNEL_BIT_OFFSET_RED

Evaluating this macro results in a bit offset within the 16-bit value at which the red color component is stored. This value can be either 0, 4, 8 or 12.

EW_COLOR_CHANNEL_BIT_OFFSET_GREEN

Evaluating this macro results in a bit offset within the 16-bit value at which the green color component is stored. This value can be either 0, 4, 8 or 12.

EW_COLOR_CHANNEL_BIT_OFFSET_BLUE

Evaluating this macro results in a bit offset within the 16-bit value at which the blue color component is stored. This value can be either 0, 4, 8 or 12.

EW_COLOR_CHANNEL_BIT_OFFSET_ALPHA

Evaluating this macro results in a bit offset within the 16-bit value at which the alpha color component is stored. This value can be either 0, 4, 8 or 12.

EW_PREMULTIPLY_COLOR_CHANNELS

If this macro is defined, the pixel store their color components red, green and blue as values premultiplied by the corresponding alpha component. If this macro is not defined, the color components are stored without being premultiplied. The last case is also known as linear or straight alpha.

The code example below demonstrates how you use the XBitmapLock structure and the above described macros to obtain access and modify the pixel information stored within a bitmap in RGBA4444 variant of the color format EW_PIXEL_FORMAT_NATIVE:

/* Include necessary header files */
#include "ewrte.h"
#include "ewgfxdriver.h"
#include "ewextgfx.h"
#include "ewgfxdefs.h"
#include "ewextpxl_RGBA4444.h"

[...]

/* We intend to modify the given 'area' of the bitmap.
   Lock the bitmap for write operation. */
XBitmap*      bitmap = ...
XRect         area   = ...
int           width  = area.Point2.X - area.Point1.X;
int           height = area.Point2.Y - area.Point1.Y;
XBitmapLock*  lock   = EwLockBitmap( bitmap, 0, area, 0, 1 );

/* Now get the pointer to the first pixel within the locked
   area. In the RGBA4444 format every pixel is a 16-bit value
   (unsigned short). Additionally calculate the offset in pixel
   between the end of one row and the begin of the next row. */
unsigned short* dest   = (unsigned short*)lock->Pixel1;
int             ofs    = ( lock->Pitch1Y / 2 ) - width;
int             x, y;

/* Iterate through the pixel within the locked area. Do this
   row-by-row and column-by-column. After one row is finished
   adjust the 'dest' pointer to refer to the next row. After
   one column is finished increment the 'dest' pointer only. */
for ( y = 0; y < height; y++, dest += ofs )
  for ( x = 0; x < width; x++, dest++ )
  {
    /* The color value you want to store in the pixel. Every variable
       is valid in range 0 .. 15. */
    unsigned short red   = ...
    unsigned short green = ...
    unsigned short blue  = ...
    unsigned short alpha = ...

    /* Should the color components be premultiplied by the alpha value?
       Please note, to optimize the implementation we divide the result
       of the multiplication by 16 (shift right 4) instead of by 15.
       Thus to reduce the calculation errors we increase the alpha value. */
    #ifdef EW_PREMULTIPLY_COLOR_CHANNELS
      red   = (unsigned short)(( red   * ( alpha + 1 )) >> 4 );
      green = (unsigned short)(( green * ( alpha + 1 )) >> 4 );
      blue  = (unsigned short)(( blue  * ( alpha + 1 )) >> 4 );
    #endif

    /* Arrange the color components to appear at the corresponding
       bit-offset position within a 16-bit value. */
    red   <<= EW_COLOR_CHANNEL_BIT_OFFSET_RED;
    green <<= EW_COLOR_CHANNEL_BIT_OFFSET_GREEN;
    blue  <<= EW_COLOR_CHANNEL_BIT_OFFSET_BLUE;
    alpha <<= EW_COLOR_CHANNEL_BIT_OFFSET_ALPHA;
     
    /* Now compose the color components to a single 16-bit value and store
       the result in the bitmap memory ... */
    *dest = red | green | blue | alpha;
  }

/* Don't forget to unlock the bitmap when you are done! */
EwUnlockBitmap( lock );

Bitmap color format EW_PIXEL_FORMAT_NATIVE variant LumA44

Bitmaps in the variant LumA44 of the EW_PIXEL_FORMAT_NATIVE color format store their pixel packed as a sequence of 8-bit values. Every pixel consists of two 4-bit color components lum (luminance) and alpha (opacity). These components are also known as color channels. This color format is optimized for monochrome application cases:

Depending on the target system and its particular graphics hardware, the order in which the color components are stored within a pixel can differ. Moreover, the color component lum can be stored as value premultiplied by the corresponding alpha component. In order to query the exact layout of how the color components are understood, following ANSI C macros are available and can be evaluated in your implementation when you read or modify the pixel information of a LumA44 bitmap:

Macro

Description

EW_COLOR_CHANNEL_BIT_OFFSET_LUM

Evaluating this macro results in a bit offset within the 8-bit value at which the lum color component is stored. This value can be either 0 or 4.

EW_COLOR_CHANNEL_BIT_OFFSET_ALPHA

Evaluating this macro results in a bit offset within the 8-bit value at which the alpha color component is stored. This value can be either 0 or 4.

EW_PREMULTIPLY_COLOR_CHANNELS

If this macro is defined, the pixel store their color components lum as values premultiplied by the corresponding alpha component. If this macro is not defined, the color components are stored without being premultiplied. The last case is also known as linear or straight alpha.

The code example below demonstrates how you use the XBitmapLock structure and the above described macros to obtain access and modify the pixel information stored within a bitmap in LumA44 variant of the color format EW_PIXEL_FORMAT_NATIVE:

/* Include necessary header files */
#include "ewrte.h"
#include "ewgfxdriver.h"
#include "ewextgfx.h"
#include "ewgfxdefs.h"
#include "ewextpxl_LumA44.h"

[...]

/* We intend to modify the given 'area' of the bitmap.
   Lock the bitmap for write operation. */
XBitmap*      bitmap = ...
XRect         area   = ...
int           width  = area.Point2.X - area.Point1.X;
int           height = area.Point2.Y - area.Point1.Y;
XBitmapLock*  lock   = EwLockBitmap( bitmap, 0, area, 0, 1 );

/* Now get the pointer to the first pixel within the locked
   area. In the LumA44 format every pixel is a 8-bit value
   (unsigned char). Additionally calculate the offset in pixel
   between the end of one row and the begin of the next row. */
unsigned char* dest   = (unsigned char*)lock->Pixel1;
int            ofs    = lock->Pitch1Y - width;
int            x, y;

/* Iterate through the pixel within the locked area. Do this
   row-by-row and column-by-column. After one row is finished
   adjust the 'dest' pointer to refer to the next row. After
   one column is finished increment the 'dest' pointer only. */
for ( y = 0; y < height; y++, dest += ofs )
  for ( x = 0; x < width; x++, dest++ )
  {
    /* The color value you want to store in the pixel. Every variable
       is valid in range 0 .. 15. */
    unsigned char lum   = ...
    unsigned char alpha = ...

    /* Should the color components be premultiplied by the alpha value?
       Please note, to optimize the implementation we divide the result
       of the multiplication by 16 (shift right 4) instead of by 15.
       Thus to reduce the calculation errors we increase the alpha value. */
    #ifdef EW_PREMULTIPLY_COLOR_CHANNELS
      lum = (unsigned char)(( lum * ( alpha + 1 )) >> 4 );
    #endif

    /* Arrange the color components to appear at the corresponding
       bit-offset position within a 8-bit value. */
    lum   <<= EW_COLOR_CHANNEL_BIT_OFFSET_LUM;
    alpha <<= EW_COLOR_CHANNEL_BIT_OFFSET_ALPHA;
     
    /* Now compose the color components to a single 8-bit value and store
       the result in the bitmap memory ... */
    *dest = lum | alpha;
  }

/* Don't forget to unlock the bitmap when you are done! */
EwUnlockBitmap( lock );

Bitmap Color format EW_PIXEL_FORMAT_NATIVE variant Index8

Bitmaps in the variant Index8 of the EW_PIXEL_FORMAT_NATIVE color format store their pixel packed as a sequence of 8-bit values. Every pixel is understood as an index into a global hardware CLUT (color look-up table). At the runtime the CLUT is used to convert the index values into the real colors. This limits this color format to be able to use maximum 256 colors:

The code example below demonstrates how you use the XBitmapLock structure to obtain access and modify the pixel information stored within a bitmap in Index8 variant of the color format EW_PIXEL_FORMAT_NATIVE:

/* Include necessary header files */
#include "ewrte.h"
#include "ewgfxdriver.h"
#include "ewextgfx.h"
#include "ewgfxdefs.h"

[...]

/* We intend to modify the given 'area' of the bitmap.
   Lock the bitmap for write operation. */
XBitmap*      bitmap = ...
XRect         area   = ...
int           width  = area.Point2.X - area.Point1.X;
int           height = area.Point2.Y - area.Point1.Y;
XBitmapLock*  lock   = EwLockBitmap( bitmap, 0, area, 0, 1 );

/* Now get the pointer to the first pixel within the locked
   area. In the Index8 format every pixel is a 8-bit value
   (unsigned char). Additionally calculate the offset in pixel
   between the end of one row and the begin of the next row. */
unsigned char* dest   = (unsigned char*)lock->Pixel1;
int            ofs    = lock->Pitch1Y - width;
int            x, y;

/* Iterate through the pixel within the locked area. Do this
   row-by-row and column-by-column. After one row is finished
   adjust the 'dest' pointer to refer to the next row. After
   one column is finished increment the 'dest' pointer only. */
for ( y = 0; y < height; y++, dest += ofs )
  for ( x = 0; x < width; x++, dest++ )
  {
    /* The CLUT index to assign to the affected pixel */
    unsigned char index = ...

    /* Store the index in the bitmap memory ... */
    *dest = index;
  }

/* Don't forget to unlock the bitmap when you are done! */
EwUnlockBitmap( lock );

When you intend to evaluate or modify the bitmap created in the Index8 format you should remember, that the values stored in the bitmap are just indices into the CLUT. The CLUT, in turn, is part of the graphics hardware, which is eventually restricted to be directly accessed. Therefore in order to allow you to evaluate the color values from the CLUT the Graphics Engine manages a copy of all CLUT colors in an array. In this array every entry is a 32-bit RGBA8888 color value with the color components red, green, blue and alpha arranged at the fixed bit offsets 0, 8, 16 and 24. The color components are not premultiplied by alpha. Knowing this you should be able to convert the indices obtained from the bitmap in the corresponding RGBA color value:

/* Declaration of the array containing the CLUT colors */
extern unsigned int EwGlobalClut[ 256 ];

[...]

/* Some CLUT index read from the bitmap */
unsigned char index = ...

/* The corresponding RGBA value */
unsigned int color = EwGlobalClut[ index ];
unsigned int red   =   color & 0xFF;
unsigned int green = ( color >>  8 ) & 0xFF;
unsigned int blue  = ( color >> 16 ) & 0xFF;
unsigned int alpha = ( color >> 24 ) & 0xFF;

Similarly, using the EwGlobalClut array you can search the CLUT for a given RGBA value and use the found CLUT index to initialize the pixel within an Index8 bitmap. This, however, expects that you implement an algorithm to search in the EwGlobalClut array for the desired or similar color. More convenient and faster is to use the array EwColorIndexTable. This array maps between RGBA values and the corresponding CLUT indices. To use this array you calculate from the RGBA value a hash number. Knowing this hash you access the array and obtain so the corresponding CLUT index:

/* Declaration of the array containing the CLUT indices */
extern const unsigned char EwColorIndexTable[ 0x4000 ];

[...]

/* Some RGBA8888 value you want to convert in the CLUT index. The
   values are valid in range 0 .. 255 */
unsigned int red   = ...
unsigned int green = ...
unsigned int blue  = ...
unsigned int alpha = ...

/* The estimated CLUT index for the given color value */
unsigned char index = EwColorIndexTable[(( red   & 0xF0 ) << 4 ) |
                                        (( green & 0xF0 ) >> 4 ) |
                                        (( blue  & 0xF0 ) >> 0 ) |
                                        (( alpha & 0xC0 ) << 6 )];

Bitmap Color format EW_PIXEL_FORMAT_ALPHA8

Bitmaps in the EW_PIXEL_FORMAT_ALPHA8 color format store their pixel packed as a sequence of 8-bit values. Every pixel is understood as an opacity value. This format doesn't story any color information:

The code example below demonstrates how you use the XBitmapLock structure and the above described macros to obtain access and modify the pixel information stored within a EW_PIXEL_FORMAT_ALPHA8 bitmap:

/* Include necessary header files */
#include "ewrte.h"
#include "ewgfxdriver.h"
#include "ewextgfx.h"
#include "ewgfxdefs.h"

[...]

/* We intend to modify the given 'area' of the bitmap.
   Lock the bitmap for write operation. */
XBitmap*      bitmap = ...
XRect         area   = ...
int           width  = area.Point2.X - area.Point1.X;
int           height = area.Point2.Y - area.Point1.Y;
XBitmapLock*  lock   = EwLockBitmap( bitmap, 0, area, 0, 1 );

/* Now get the pointer to the first pixel within the locked
   area. In the ALPHA8 format every pixel is a 8-bit value
   (unsigned char). Additionally calculate the offset in pixel
   between the end of one row and the begin of the next row. */
unsigned char* dest   = (unsigned char*)lock->Pixel1;
int            ofs    = lock->Pitch1Y - width;
int            x, y;

/* Iterate through the pixel within the locked area. Do this
   row-by-row and column-by-column. After one row is finished
   adjust the 'dest' pointer to refer to the next row. After
   one column is finished increment the 'dest' pointer only. */
for ( y = 0; y < height; y++, dest += ofs )
  for ( x = 0; x < width; x++, dest++ )
  {
    /* The Opacity value you want to store in the pixel. The values lies
       in the range 0 .. 255. */
    unsigned char alpha = ...

    /* Store the alpha value in the bitmap memory ... */
    *dest = alpha;
  }

/* Don't forget to unlock the bitmap when you are done! */
EwUnlockBitmap( lock );

Bitmap Color format EW_PIXEL_FORMAT_INDEX8

Bitmaps in the EW_PIXEL_FORMAT_INDEX8 color format store their pixel packed as a sequence of 8-bit values. Every pixel is understood as an index into a bitmap associated (private) color palette. At the runtime the color palette is used to convert the index values into the real colors. This limits the bitmap to use maximum 256 colors:

The code example below demonstrates how you use the XBitmapLock structure and the above described macros to obtain access and modify the pixel information stored within a EW_PIXEL_FORMAT_INDEX8 bitmap:

/* Include necessary header files */
#include "ewrte.h"
#include "ewgfxdriver.h"
#include "ewextgfx.h"
#include "ewgfxdefs.h"

[...]

/* We intend to modify the given 'area' of the bitmap.
  Lock the bitmap for write operation. */
XBitmap*      bitmap = ...
XRect         area   = ...
int           width  = area.Point2.X - area.Point1.X;
int           height = area.Point2.Y - area.Point1.Y;
XBitmapLock*  lock   = EwLockBitmap( bitmap, 0, area, 0, 1 );

/* Now get the pointer to the first pixel within the locked
  area. In the INDEX8 format every pixel is a 8-bit value
  (unsigned char). Additionally calculate the offset in pixel
  between the end of one row and the begin of the next row. */
unsigned char* dest   = (unsigned char*)lock->Pixel1;
int            ofs    = lock->Pitch1Y - width;
int            x, y;

/* Iterate through the pixel within the locked area. Do this
  row-by-row and column-by-column. After one row is finished
  adjust the 'dest' pointer to refer to the next row. After
  one column is finished increment the 'dest' pointer only. */
for ( y = 0; y < height; y++, dest += ofs )
  for ( x = 0; x < width; x++, dest++ )
  {
    /* The color palette index to assign to the affected pixel */
    unsigned char index = ...

    /* Store the index in the bitmap memory ... */
    *dest = index;
  }

/* Don't forget to unlock the bitmap when you are done! */
EwUnlockBitmap( lock );

To modify the color palette associated with a EW_PIXEL_FORMAT_INDEX8 bitmap use the function EwModifyBitmapPalette(). Actually there is no possibility to read values stored within the palette so you will need to maintain a copy of the palette in an array if it is necessary to convert index in color values.

Bitmap color format EW_PIXEL_FORMAT_RGB565 (optional)

Bitmaps in the EW_PIXEL_FORMAT_RGB565 color format store their pixel packed as a sequence of 16-bit values. Every pixel consists of a 5-bit red, 6-bit green and 5-bit blue color components. These components are also known as color channels:

Depending on the target system and its particular graphics hardware, the order in which the color components are stored within a pixel can differ. In order to query the exact layout of how the color components are understood, following ANSI C macros are available and can be evaluated in your implementation when you read or modify the pixel information of an EW_PIXEL_FORMAT_RGB565 bitmap:

Macro

Description

EW_RGB565_COLOR_CHANNEL_BIT_OFFSET_RED

Evaluating this macro results in a bit offset within the 16-bit value at which the red color component is stored. This value can be either 0 or 11.

EW_RGB565_COLOR_CHANNEL_BIT_OFFSET_GREEN

Evaluating this macro results in a bit offset within the 16-bit value at which the green color component is stored. This value is always 5.

EW_RGB565_COLOR_CHANNEL_BIT_OFFSET_BLUE

Evaluating this macro results in a bit offset within the 16-bit value at which the blue color component is stored. This value can be either 0 or 11.

The code example below demonstrates how you use the XBitmapLock structure and the above described macros to obtain access and modify the pixel information stored within a bitmap in EW_PIXEL_FORMAT_RGB565 color format:

/* Include necessary header files */
#include "ewrte.h"
#include "ewgfxdriver.h"
#include "ewextgfx.h"
#include "ewgfxdefs.h"

/* Include one of the following header files depending on the version
   of your Graphics Engine */
#include "ewextpxl_RGB565.h"
#include "ewextpxl_RGB888.h"
#include "ewextpxl_RGBA8888.h"

[...]

/* We intend to modify the given 'area' of the bitmap.
   Lock the bitmap for write operation. */
XBitmap*      bitmap = ...
XRect         area   = ...
int           width  = area.Point2.X - area.Point1.X;
int           height = area.Point2.Y - area.Point1.Y;
XBitmapLock*  lock   = EwLockBitmap( bitmap, 0, area, 0, 1 );

/* Now get the pointer to the first pixel within the locked
   area. In the RGB565 format every pixel is a 16-bit value
   (unsigned short). Additionally calculate the offset in pixel
   between the end of one row and the begin of the next row. */
unsigned short* dest   = (unsigned short*)lock->Pixel1;
int             ofs    = ( lock->Pitch1Y / 2 ) - width;
int             x, y;

/* Iterate through the pixel within the locked area. Do this
   row-by-row and column-by-column. After one row is finished
   adjust the 'dest' pointer to refer to the next row. After
   one column is finished increment the 'dest' pointer only. */
for ( y = 0; y < height; y++, dest += ofs )
  for ( x = 0; x < width; x++, dest++ )
  {
    /* The color value you want to store in the pixel. */
      unsigned short red   = ... /* 5-bit value in range 0 ..  31 */
      unsigned short green = ... /* 6-bit value in range 0 ..  63 */
      unsigned short blue  = ... /* 5-bit value in range 0 ..  31 */
      
    /* Arrange the color components to appear at the corresponding
       bit-offset position within a 16-bit value. */
    red   <<= EW_RGB565_COLOR_CHANNEL_BIT_OFFSET_RED;
    green <<= EW_RGB565_COLOR_CHANNEL_BIT_OFFSET_GREEN;
    blue  <<= EW_RGB565_COLOR_CHANNEL_BIT_OFFSET_BLUE;
     
    /* Now compose the color components to a single 16-bit value and store
       the result in the bitmap memory ... */
    *dest = red | green | blue;
  }

/* Don't forget to unlock the bitmap when you are done! */
EwUnlockBitmap( lock );