# GetImageBits

int GetImageBits (int panelHandle, int controlID, int imageID, int *bytesPerRow, int *pixelDepth, int *width, int *height, int colorTable[], unsigned char bits[], unsigned char mask[]);

## Purpose

| Note This function is obsolete. National Instruments recommends that you use GetCtrlBitmap and GetBitmapData instead.

Obtains the bit values that define an image. You can modify the bit values and then apply them back to the image using SetImageBits.

Before calling GetImageBits, you must perform the following actions:

- Call GetImageInfo to get the size of the buffers, and then allocate the buffers.
- Call AllocImageBits.

You can use this function on images you create using functions such as DisplayImageFile, InsertListItem, ReplaceListItem, PlotBitmap, SetImageBits, or SetCtrlAttribute with the ATTR_IMAGE_FILE attribute.

## Parameters

Input
Name | Type | Description
panelHandle | integer | Specifier for a particular panel that is currently in memory. You obtain this handle from LoadPanel, NewPanel, or DuplicatePanel.
controlID | integer | The defined constant, located in the .uir header file, that you assigned to the control in the User Interface Editor, or the ID returned by NewCtrl or DuplicateCtrl.
imageID | integer | For picture rings, the zero-based index of an image in the ring. For graphs, the plot handle you obtain from PlotBitmap. For picture controls, picture buttons, and canvas controls, this parameter is ignored.
Output
Name | Type | Description
bytesPerRow | integer | Number of bytes on each scan line of the image. You can pass NULL for this parameter.
pixelDepth | integer | Number of bits per pixel. The valid values for the pixelDepth parameter are 1, 4, 8, 24, or 32. You can pass NULL for this parameter.
width | integer | Width of the image, in pixels. If no image exists, this parameter is set to –1. For images originally rendered from a Windows metafile (.wmf or .emf), you can determine the size of the bitmap obtained by this function as follows: If the image is in a graph control or if the fit mode is VAL_SIZE_TO_PICTURE, the size of the bitmap is the size of the image as it appears in the control. If the image is in a picture, picture ring, or picture button, and the fit mode is a value other than VAL_SIZE_TO_PICTURE, the size of the bitmap is the size stored in the original Windows metafile. You can pass NULL for this parameter.
height | integer | Height of the image, in pixels. If no image exists, this parameter is set to –1. For images originally rendered from a Windows metafile (.wmf or .emf), you can determine the size of the bitmap obtained by this function as follows: If the image is in a graph control or if the fit mode is VAL_SIZE_TO_PICTURE, the size of the bitmap is the size of the image as it appears in the control. If the image is in a picture, picture ring, or picture button, and the fit mode is a value other than VAL_SIZE_TO_PICTURE, the size of the bitmap is the size stored in the original Windows metafile. You can pass NULL for this parameter.
colorTable | integer array | 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. If GetBitmapInfo sets the colorSize parameter to 0, this array is not filled in. You can pass NULL for this parameter.
bits | unsigned char array | Array of bits that determines the colors to display on each pixel in the image. The number of bits per pixel is equal to the pixelDepth value. 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. 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. You can pass NULL for this parameter.
mask | unsigned char array | Array that determines which pixels in the image to 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 GetBitmapInfo sets the maskSize parameter to 0, this array is not filled in. You can pass NULL for this parameter.

## Return Value

Name | Type | Description
status | integer | Return value indicating whether the function was successful. A negative number indicates that an error occurred.
Code | Error Message String
xx | Success