Platform Package reference: Type XBitmapLock
Description of the type definition XBitmapLock available in all Platform Packages for 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 bitmap main formats, which are described in the table below. Furthermore, the exact layout of how pixel are stored in the memory of a bitmap created with the main format EW_PIXEL_FORMAT_NATIVE depends on the particular target system - it corresponds to the format supported natively by your target system. Usually this is the color format of how the frame-buffer stores its pixel information. 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 subsystem 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. |
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 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 "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 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 RGB565A8
Bitmaps in the variant RGB565A8 of the EW_PIXEL_FORMAT_NATIVE color format store their pixel in two separate memory planes. The first plane (addressed by Pixel1 in the XBitmapLock structure) contains the pure RGB information packed as a sequence of 16-bit values. in this plane every pixel consists of three components red, green and blue stored respectively with 5, 6 and 5 bits. The second plane (addressed by Pixel2) contains the pure opacity information (the component alpha of the color) as a sequence of 8-bit values. All four 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 C macros are available and can be evaluated in your implementation when you read or modify the pixel information of a RGB565A8 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 or 11. Please note, the position of the green color component is fixed. |
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 or 11. Please note, the position of the green color component is fixed. |
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 RGB565A8 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_RGB565A8.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 RGB565A8 format the pixel are stored in two separate planes. Plane 1 contains RGB information as 16-bit values (unsigned short). Plane 2 contains opacity (alpha) information as 8-bit (unsigned char) values. Additionally calculate the offsets in pixel between the end of one row and the begin of the next row for the both planes. */ unsigned short* dest1 = (unsigned short*)lock->Pixel1; unsigned char* dest2 = (unsigned char*) lock->Pixel2; int ofs1 = ( lock->Pitch1Y / 2 ) - width; int ofs2 = lock->Pitch2Y - 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 'dest1' and 'dest2' pointers to refer to the next row. After one column is finished increment the both pointers only. */ for ( y = 0; y < height; y++, dest1 += ofs1, dest2 += ofs2 ) for ( x = 0; x < width; x++, dest1++, dest2++ ) { /* 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 */ unsigned char alpha = ... /* 8-bit value in range 0 .. 255 */ /* 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 = (unsigned short)(( red * ( alpha + 1 )) >> 8 ); green = (unsigned short)(( green * ( alpha + 1 )) >> 8 ); blue = (unsigned short)(( blue * ( alpha + 1 )) >> 8 ); #endif /* For the plane 1: arrange the RGB color components to appear at the corresponding bit-offset position within a 16-bit value. Note: position of 'green' is always fixed */ red <<= EW_COLOR_CHANNEL_BIT_OFFSET_RED; green <<= 5; blue <<= EW_COLOR_CHANNEL_BIT_OFFSET_BLUE; /* Now compose the color components to a single 16-bit value and store the result in the bitmap memory of plane 1 and plane 2 ... */ *dest1 = red | green | blue; *dest2 = alpha; } /* Don't forget to unlock the bitmap when you are done! */ EwUnlockBitmap( lock );
Bitmap color format EW_PIXEL_FORMAT_NATIVE variant RGB555A8
Bitmaps in the variant RGB555A8 of the EW_PIXEL_FORMAT_NATIVE color format store their pixel in two separate memory planes. The first plane (addressed by Pixel1 in the XBitmapLock structure) contains the pure RGB information packed as a sequence of 16-bit values. in this plane every pixel consists of three 5-bit color components red, green and blue. The second plane (addressed by Pixel2) contains the pure opacity information (the component alpha of the color) as a sequence of 8-bit values. All four 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. Also the function of the remaining bit 15 within every pixel of the plane 1 can be configured. In order to query the exact layout of how the color components are understood and what function the bit 15 has, following C macros are available and can be evaluated in your implementation when you read or modify the pixel information of a RGB555A8 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, 5 or 10. |
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, 5 or 10. |
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, 5 or 10. |
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. |
EW_COLOR_CHANNEL_BIT15_CONST_0 |
If this macro is defined, the bit 15 of every pixel in plane 1 is set to constant 0 (zero). |
EW_COLOR_CHANNEL_BIT15_CONST_1 |
If this macro is defined, the bit 15 of every pixel in plane 1 is set to constant 1 (one). |
EW_COLOR_CHANNEL_BIT15_ALPHA_8 |
If this macro is defined, the bit 15 of every pixel in plane 1 is set to the value of the top-most bit of the corresponding alpha component. |
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 RGB555A8 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_RGB555A8.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 RGB555A8 format the pixel are stored in two separate planes. Plane 1 contains RGB information as 16-bit values (unsigned short). Plane 2 contains opacity (alpha) information as 8-bit (unsigned char) values. Additionally calculate the offsets in pixel between the end of one row and the begin of the next row for the both planes. */ unsigned short* dest1 = (unsigned short*)lock->Pixel1; unsigned char* dest2 = (unsigned char*) lock->Pixel2; int ofs1 = ( lock->Pitch1Y / 2 ) - width; int ofs2 = lock->Pitch2Y - 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 'dest1' and 'dest2' pointers to refer to the next row. After one column is finished increment the both pointers only. */ for ( y = 0; y < height; y++, dest1 += ofs1, dest2 += ofs2 ) for ( x = 0; x < width; x++, dest1++, dest2++ ) { /* The color value you want to store in the pixel. */ unsigned short red = ... /* 5-bit value in range 0 .. 31 */ unsigned short green = ... /* 5-bit value in range 0 .. 31 */ unsigned short blue = ... /* 5-bit value in range 0 .. 31 */ unsigned char alpha = ... /* 8-bit value in range 0 .. 255 */ /* 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 = (unsigned short)(( red * ( alpha + 1 )) >> 8 ); green = (unsigned short)(( green * ( alpha + 1 )) >> 8 ); blue = (unsigned short)(( blue * ( alpha + 1 )) >> 8 ); #endif /* For the plane 1: arrange the RGB 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; /* Then compose the color components to a single 16-bit value and store the result in the bitmap memory of plane 1. Please note, the function of the additional bit 15 depends on the defined macros. */ #if defined EW_COLOR_CHANNEL_BIT15_CONST_1 *dest1 = red | green | blue | ( 1 << 15 ); #elif defined EW_COLOR_CHANNEL_BIT15_ALPHA_8 *dest1 = red | green | blue | (( alpha & 0x80 ) << 8 ); #else *dest1 = red | green | blue; #endif /* Also store the alpha component in the plane 2 */ *dest2 = 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 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.