Using Bitmap Objects
A bitmap is a two-dimensional grid of pixels that represents an image. Use bitmap objects to display images on user interface controls such as canvas controls, picture controls, graph controls, and tree controls. You also can use bitmap objects to capture screenshot images of user interface controls and panels.
LabWindows/CVI provides functions such as PlotBitmap and DisplayImageFile that display the contents of an image file directly on a control. LabWindows/CVI also provides functions that create a bitmap, extract a bitmap from an existing file, store the bitmap in memory, and return a bitmap ID. You then can pass the bitmap ID to functions such as CanvasDrawBitmap and SetCtrlBitmap to display the image in a control. You also can pass a bitmap ID to SetBitmapDataEx to modify the image contents.
Creating, Extracting, and Discarding Bitmap Objects
Use the following functions to create, extract, or discard bitmap objects.
- NewBitmap creates a bitmap object. To create a bitmap object that contains alpha-channel transparency data, call NewBitmapEx.
- GetBitmapFromFile and GetBitmapFromFileEx create a bitmap object using image data from a file. LabWindows/CVI supports the following image file formats: .tif, .pcx, .bmp, .dib, .rle, .ico, .jpg, .png, .wfm, and .emf.
- GetCtrlBitmap creates a bitmap object from an image contained in a control, such as a picture or graph control.
- GetTableCellVal or GetTableCellRangeVals creates one or more bitmap objects from an image contained in a table cell or cells if the cell type is set to VAL_CELL_PICTURE.
- GetCtrlDisplayBitmap creates a bitmap object that contains a screenshot image of the current appearance of a control. Call GetScaledCtrlDisplayBitmap to create a control image that is scaled to the specified rectangular area. LabWindows/CVI shrinks or stretches the image accordingly.
- GetPanelDisplayBitmap creates a bitmap object that contains a screenshot image of the current appearance of a panel. Specify the part of the panel to copy to the bitmap. Call GetScaledPanelDisplayBitmap to create a panel image that is scaled to the specified rectangular area. LabWindows/CVI shrinks or stretches the image accordingly.
- ClipboardGetBitmap creates a bitmap object from an image on the system clipboard, if an image is available on the clipboard.
- DuplicateBitmap creates a bitmap object that is an exact copy of a specified bitmap.
- DiscardBitmap removes a bitmap from memory.
- SetBitmapData changes the contents of an existing bitmap. This approach is faster than discarding a bitmap and creating a new one. To change the contents of a bitmap object that contains alpha-channel transparency data, call SetBitmapDataEx.
Displaying and Copying Bitmap Objects
Use the following functions to display a bitmap object in a control or copy an image from a bitmap object to a control.
- CanvasDrawBitmap displays a bitmap in a canvas control.
- SetCtrlBitmap sets an image in a control, such as a picture or graph control, from a bitmap object. You can use this function to add an image to a control, replace an existing image in a control, or delete an image from a control.
- SetTableCellVal, SetTableCellRangeVals, or FillTableCellRange displays a bitmap or bitmaps in a table cell or cells, if the cell type is set to VAL_CELL_PICTURE.
- ClipboardPutBitmap copies image data from a bitmap object to the system clipboard.
Retrieving Image Data from Bitmap Objects
Use the following functions to retrieve image data from bitmap objects.
- GetBitmapInfo obtains size information about the image associated with a bitmap. Use this information to allocate the buffers you pass to GetBitmapData. To obtain size information for a bitmap object that contains alpha-channel transparency data, call GetBitmapInfoEx.
- AllocBitmapData allocates the buffers that GetBitmapData requires. Call AllocBitmapData instead of calling GetBitmapInfo and allocating the buffers yourself. To allocate buffers for a bitmap object that contains alpha-channel transparency data, call AllocBitmapDataEx.
- GetBitmapData obtains the bit values that define the image associated with a bitmap. To obtain this data for a bitmap object that contains alpha-channel transparency data, call GetBitmapDataEx.
Saving Bitmap Objects
You can save a bitmap image to a .bmp, .jpg, .png, or .tif file. The .png file format is the only format in which you can save binary or alpha-channel transparency data. Call SaveBitmapToBMPFile, SaveBitmapToJPEGFile, SaveBitmapToPNGFile, or SaveBitmapToTIFFile to save a bitmap object to file.
Referencing Bitmap IDs
Use the bitmap ID returned by the following functions to reference the bitmap from functions that use bitmaps as an input.
NewBitmapEx (use with functions that support alpha-channel transparency)
GetBitmapFromFileEx (use with functions that support alpha-channel transparency)
NewBitmap (use with functions that do not support alpha-channel transparency)
GetBitmapFromFile (use with functions that do not support alpha-channel transparency)
OGLGetScaledCtrlBitmapOGLGetScaledCtrlBitmap
Pixel Transparency
To display images that are not rectangular or have holes in them, use binary transparency. With binary transparency, you specify which pixels in an image to draw and which pixels to make transparent. Use the mask parameter in the NewBitmap, NewBitmapEx, SetBitmapData, and SetBitmapDataEx functions to specify binary transparency data. To create images that have partially transparent pixels, use alpha-channel transparency. With alpha-channel transparency, you specify a transparency level, ranging from fully transparent to fully opaque, for each pixel. Use the alpha parameter in the NewBitmapEx and SetBitmapEx functions to specify alpha-channel data.
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 0 (pixel is not drawn), LabWindows/CVI sets the corresponding alpha array byte to 0 (pixel is fully transparent). For each mask array byte you set to 1 (pixel is drawn), the corresponding alpha array byte is retained.
Windows Metafiles
A Windows metafile (.wmf or .emf) contains a description of an image that is scalable without distortion. The description consists of a set of drawing commands rather than a bitmap. Use GetBitmapFromFile to load a Windows metafile.
 |
Note You cannot use SetBitmapData to change the image contents of a bitmap that originated as a Windows metafile. |