SetBitmapDataEx
int SetBitmapDataEx (int bitmapID, int bytesPerRow, int pixelDepth, int colorTable[], unsigned char bits[], unsigned char mask[], unsigned char alpha[]);
Purpose
Changes the image contents of an existing bitmap. The width and height of the bitmap do not change. When you call SetBitmapDataEx, you can achieve better performance than when you call DiscardBitmap and NewBitmapEx. SetBitmapDataEx is similar to SetBitmapData, except that SetBitmapDataEx supports alpha-channel transparency.
You can obtain the ID of the bitmap object from functions such as NewBitmapEx and GetCtrlBitmap. You cannot use SetBitmapDataEx if the bitmap originated from a Windows metafile (.wmf or .emf).
Refer to the parameter help for information about changing specific components of the image.
Parameters
| Input | ||
| Name | Type | Description |
| bitmapID | int | ID of the bitmap object that contains the image. You can obtain the ID from functions such as NewBitmapEx and GetCtrlBitmap. |
| bytesPerRow | int | Number of bytes on each scan line of the image. If bytesPerRow is a positive number, then the bits for each scan line must start on a byte boundary. Depending on pixelDepth and the width of the bitmap, the number of bits per line in the bits array might not be an even multiple of eight. In this case, you must pad the bits array to get to the next byte boundary. If bytesPerRow is -1, no padding occurs. The bits for each scan line immediately follow the bits for the previous scan line. |
| pixelDepth | int | Number of bits per pixel. The valid values for pixelDepth are 1, 4, 8, 24, and 32. This depth determines how LabWindows/CVI interprets the data you pass in the bits parameter. Regardless of the color depth that you specify, the new bitmap matches the color depth of the display screen unless the image has an alpha channel, in which case the depth is 24. |
| colorTable | int [] | Array of RGB color values, or NULL if pixelDepth is greater than 8. If pixelDepth is 8 or less, the bits array contains indices into the colorTable array. The number of entries in the colorTable array must equal 2n, where n is the value of the pixelDepth parameter. If pixelDepth is greater than 8, the colorTable parameter is not used. The bits array contains actual RGB color values rather than indices into the colorTable array. |
| bits | unsigned char [] | Array of bits that determines the colors to display on each pixel in the image. The first pixel in the bits array is at the upper-left corner of the image. The pixels in the array are stored in row-major order. The number of bits per pixel is equal to the pixelDepth value. If pixelDepth is 8 or less, the bits array contains indices into the colorTable array. If pixelDepth is greater than 8, the colorTable array is not used, and the bits array contains the actual RGB values. If pixelDepth is 24, each pixel is represented by a 24-bit RGB value of the form RRGGBB, where RR, GG, and BB represent the red, green, and blue components of the color value. The RR byte is at the lowest memory address of the three bytes. If pixelDepth is 32, each pixel is represented by a 32-bit RGB value of the form 0x00RRGGBB, where RR, GG, and BB represent the red, green, and blue components of the color value. The 32-bit value is treated as a native 32-bit integer value. The BB byte is in the least significant byte and, therefore, is at the lowest memory address of the four bytes. The most significant byte of this integer is ignored. Notice that this byte ordering scheme differs from the byte ordering scheme when pixelDepth is 24. When pixelDepth is 24 or 32, valid RR, GG, and BB values range from 0 to 255. |
| mask | unsigned char [] | Array that determines which pixels in the image to actually draw. Use the mask array to achieve binary transparency. The mask array contains one bit for each pixel in the image. A mask array bit value of 1 indicates that the pixel is drawn; a mask array bit value of 0 indicates that the pixel is not drawn. When pixelDepth is 1, the pixels that have a bits array value of 1 are always drawn, regardless of the mask array value. In this case, the mask array affects only the pixels that have a bits array value of 0. You must pad each row of the mask array to the nearest even-byte boundary. For example, if the width of the image is 21 pixels, then each row of the mask array must have 32 bits (four bytes) of data. If the bitmap already has a mask, you can pass NULL to keep the same mask array, supply a new mask array, or pass REMOVE_TRANSPARENCY_MASK to remove the mask. When you use REMOVE_TRANSPARENCY_MASK, the color of the pixels that were transparent under the previous mask is unpredictable. Use the bits parameter to set the color value of these pixels. If the bitmap does not already have a mask, you can pass NULL, or you can add a mask by supplying a mask array. If you pass a mask array and an alpha array, LabWindows/CVI incorporates the mask values into the alpha array and then sets the mask value to NULL. For each mask array bit that you set to 1, LabWindows/CVI sets the corresponding alpha array byte to 255. |
| alpha | unsigned char [] | Array that specifies the alpha channel for each pixel in an image. The alpha array contains one byte per pixel in the image. Bytes are stored in row-major order starting with the upper-left corner pixel. Each byte specifies the transparency of the corresponding pixel. Valid byte values range from 0 to 255. A value of 0 indicates that the pixel is fully transparent; a value of 255 indicates that the pixel is fully opaque. LabWindows/CVI coerces the red, green, and blue color channel values you specify for a pixel to one of alpha + 1 discrete values, which are evenly distributed from 0 to 255. If you reduce the alpha value of a pixel, the color value for that pixel is adjusted to the nearest available discrete value. If you then increase the alpha value of the same pixel, the color value for that pixel is not restored to the original value. However, you can programmatically reset the color value to the original value. If the bitmap already has an alpha channel, you can pass NULL to keep the same alpha array, supply a new alpha array, or pass REMOVE_ALPHA_CHANNEL to remove the alpha channel. If the bitmap does not already have an alpha channel, you can pass NULL, or you can add an alpha channel by supplying an alpha array. If you pass a mask array and an alpha array, LabWindows/CVI incorporates the mask values into the alpha array and then sets the mask value to NULL. For each mask array bit that you set to 1, LabWindows/CVI sets the corresponding alpha array byte to 255. |
Return Value
| Name | Type | Description |
| status | int | Return value indicating whether the function was successful. A negative number indicates that an error occurred. |
Additional Information
Library: User Interface Library
Include file: userint.h
LabWindows/CVI compatibility: LabWindows/CVI 8.0 and later