DC_WRITE_DIB Function (Windows)

Writes image data from a variable to a Device Independent Bitmap (DIB) format file.

Usage

status = DC_WRITE_DIB(filename, imgarr)

Input Parameters

filename — A string containing the pathname and filename of the DIB file.

imgarr — The variable containing the image data to be saved as a DIB file.

Returned Value

status — Value returned by DC_WRITE_DIB; expected values are:

< 0 — Indicates an error, such as an invalid filename.
0 — Indicates a successful write.

Keywords

ColorClass — An integer specifying the DIB color class level. If not provided, ColorClass=2 is assumed. Valid values are 2, 16, and 256.

ColorsUsed — The number of colors that the bitmap image uses. If this keyword is not provided, it is set to the number of elements in SystemPalette or Palette if one of them is provided; otherwise, ColorsUsed defaults to 2.

Compression — A string that specifies the kind of image data compression to use as the data is written to the file. This keyword is valid only if ColorClass is specified as 16 or 256. If this keyword is not provided, no compression is performed. Valid values are:

'None' — None (no compression)
'RLE4' — Run-length encoded format for bitmaps with 4 bits per pixel
'RLE8' — Run-length encoded format for bitmaps with 8 bits per pixel

ImportantColors — The number of important colors that the bitmap image needs to display. If not provided, ImportantColors defaults to 0.

Palette — Specifies a color table to be saved with the DIB file. Palette must be a 3-by-n array of integers, where n is either 1, 16, or 256. n specifies the number of colors associated with the bitmap. If the ColorClass keyword is set to 2, then the Palette keyword is ignored and a monochrome color table is saved.

SystemPalette — If set to a nonzero value, this keyword causes the system color table to be saved with the DIB file. SystemPalette always takes precedence over the Palette keyword.

Discussion

Device Independent Bitmap (DIB) is a bitmap format that is useful for transporting graphics and color table information between different devices and applications in the Windows environment. DIB files can be produced by graphics applications such as Microsoft Image Editor, Microsoft Paintbrush, and PV‑WAVE.

Specify a color table to be saved with the DIB file, or an error is returned. The Palette and SystemPalette keywords let you specify a color table.

DC_WRITE_DIB exports DIB images from PV-WAVE. It handles: 1) opening the file, 2) assigning it a logical unit number (LUN), and 3) closing the file when you are done writing the data.

If imgarr is not a 2- or 3-dimensional byte array, DC_WRITE_DIB returns an error status and no data is written to the output file.

Example

If the variable maverick is a 512-by-512 byte array, the commands:

TV, DIST(512)
; Create a color map
cmap = TRANSPOSE([[INDGEN(256)], [INDGEN(256)], [INDGEN(256)]])
; Read the displayed image
maverick = TVRD(0, 0, 512, 512)
; Save the image in DIB format
status = DC_WRITE_DIB('mav.bmp', maverick, Compression='None', $
   ColorClass=256, Palette=cmap)

create the file mav.bmp containing the image data in the variable maverick. The created DIB file is not compressed and has a color class of 256.