SAMPLE: DIBs and Their Uses

USING THE DIB API

GetDIBits() and SetDIBits()

These two functions are used to convert device-independent bitmaps into device-dependent bitmaps and vice versa. SetDIBits() converts a DIB to a device-dependent bitmap, and GetDIBits() generates a DIB from a device- dependent bitmap.

The device driver referenced by the hDC passed into both calls performs the actual translation. Some device drivers may not have this functionality (for example, a Windows version 2.0 driver or a primitive Windows version 3.0 driver). In this case, GDI simulates the translation, but only in monochrome -- color information is converted to black and white. For the most part, however, this is not a concern. All self-respecting display drivers support this functionality, and only a few printer drivers do not provide the translation, usually monochrome drivers for which the GDI simulations suffice.

GetDeviceCaps(hDC, RASTERCAPS) returns a WORD value with flags set indicating which DIB functions the driver supports. RC_DI_BITMAP indicates support of GetDIBits() and SetDIBits(), RC_DIBTODEV indicates support of SetDIBitsToDevice(), and RC_STRETCHDIB indicates support of StretchDIBits(). Any function not supported can be simulated, although the simulations are often not as useful as the real thing (mainly because color information is lost). A device may be unable to support the full functionality even if a bit is set. For example, a device could support StretchDIBits but only for integral stretches. Unfortunately, an application has no way to determine the completeness of the implementation. In these cases, GDI simulates the function.

The parameters are the same for both GetDIBits() and SetDIBits():

GetDIBits(hDC, hBitmap, nStartScan, nNumScans, lpBits, lpBitmapInfo, wUsage)

SetDIBits(hDC, hBitmap, nStartScan, nNumScans, lpBits, lpBitmapInfo, wUsage)

hDC            The device context (DC) responsible for the translation
               operation. hDC must be compatible with the hBitmap
               parameter.

hBitmap        The device-dependent bitmap from which (Get) or to
               which (Set) the DIB will be translated. Because of how
               the simulation code operates, this bitmap should not be
               currently selected into any DC.

nNumScans      Define the contents of lpBits. For example, a StartScan
               of 5 indicates that lpBits points to the fifth scan of
               the DIB. A NumScans of 14 indicates that lpBits points
               to 14 scans of the DIB. Normally, nStartScan is set to
               0 and nNumScans is set to biHeight to denote that the
               whole DIB is pointed to by lpBits.

lpBits         The actual bitmap of the DIB. The pixel information is
               pointed to by this parameter.

lpBitmapInfo   The header (with color table) defining the DIB. The
               height and width in this header must match the height
               and width of the hBitmap parameter (the translation is
               always 1-to-1). The color resolution of the DIB need
               not match that of hBitmap.

wUsage         For the purposes of this article, assume this to be
               DIB_RGB_COLORS, indicating RGB colors in the color
               table.

NOTE: For many printers that can do halftones, this method is not preferred; StretchDIBits (discussed below) is far more useful.

The following is a simple display of a DIB to a DC (with no error handling):

   HBITMAP hBitmap;
   HDC hMemDC;

   hBitmap = CreateCompatibleBitmap(hDC, (WORD)lpInfo->biWidth,
          lpInfo->(WORD)biHeight);
   hMemDC = CreateCompatibleDC(hDC);
   SetDIBits(hDC, hBitmap, 0, (WORD)lpInfo->biHeight, lpBits,
          lpBitmapInfo, DIB_RGB_COLORS);
   hBitmap = SelectObject(hMemDC, hBitmap);
   BitBlt(hDC, 0, 0, (WORD)lpInfo->biWidth, (WORD)lpInfo->biHeight,
          hMemDC, 0, 0, SRCCOPY);
   DeleteObject(SelectObject(hMemDC, hBitmap));
   DeleteDC(hMemDC);

For GetDIBits() to work properly, the application needs to set the following fields in the header:

   biSize = sizeof(BITMAPINFOHEADER)
   biWidth = (width of the bitmap)
   biHeight = (height of the bitmap)
   biPlanes = 1
   biBitCount = [desired color resolution (1, 4, 8, or 24)]
   biCompression = BI_RGB (For RLE information, see below.)

   if (biBitCount != 24)
     nSizeTable = (1 << biBitCount) * sizeof(RGBQUAD)
   else
     nSizeTable = 0;

• biSizeImage = size in bytes of the DIB data
• Color table (for non-24-bit case) is filled with appropriate colors
• lpBits is filled with the DIB data

The application's goals for the DIB determine what color resolution to choose. The usual approach is to generate a DIB that preserves the color information of the source device-dependent bitmap. Choosing a lesser resolution results in a loss of color information, which is usually undesirable. Always using 24-bit resolution is unnecessary, however, because doing so adds no more color resolution if the source has 8-bit or less resolution.

   BITMAP bm;

   // get information on bitmap
   GetObject(hBitmap, sizeof(BITMAP), (LPVOID)&bm);

   BitmapRes = bm.bmPlanes * bm.bmBitsPixel;
   if (BitmapRes == 1)
     biBitCount = 1;
   else if (BitmapRes <= 4)
     biBitCount = 4;
   else if (BitmapRes <= 8)
     biBitCount = 8;
   else
     biBitCount = 24;

The nStartScan and nNumScans parameters (a residue of Presentation Manager compatibility) are designed to be used for banding. If not enough memory is available to load the entire DIB into memory in one piece, lpBits can be made to point to only a portion of the bits. Consider the following example:

   #define MAXREAD 5
   WORD ReadXScans(LPSTR, WORD);   // Read up to X scans; return
                                   // NumRead.
   LPSTR lpBits;                   // Points to a block of memory for
                                   // MAXREAD scans.
   LPBITMAPINFOHEADER lpInfo;
   WORD nStart, nNumRead;

   for (nStart = 0; nStart >= (WORD)lpInfo->biHeight; )
   {
     nNumRead = ReadXScans(lpBits, MAXREAD);
     SetDIBits(hDC, hBitmap, nStart, nNumRead,
          lpBits, lpInfo, DIB_RGB_COLORS);
     nStart += nNumRead;
   }

CreateDIBitmap()

The following code demonstrates calling CreateDIBitmap() with the usual case:

   hBitmap = CreateDIBitmap(hDC, lpInfo, CBM_INIT, lpBits, lpInfo,
                            wUsage);

   hBitmap = CreateCompatibleBitmap(hDC, (WORD)lpInfo->biWidth,
             (WORD)lpInfo->biHeight);
   SetDIBits(hDC, hBitmap, 0, (WORD)lpInfo->biHeight, lpBits, lpInfo,
             wUsage);

SetDIBitsToDevice()

SetDIBitsToDevice() allows an application to set a DIB directly to a device surface. Because this function is a holdout from early development, its interface is not as polished as it could be. StretchDIBits() is a far more powerful function than SetDIBitsToDevice(). StretchDIBits() does all that SetDIBitsToDevice() does and has a nicer interface. SetDIBitsToDevice() is limited in the way it handles metafiles because it does not scale, and banding with the nStartScan and nNumScans parameters is nontrivial at best. StretchDIBits() does not allow the banding.

The following code performs the SetDIBitsToDevice() functionality on the full bitmap (no banding) using StretchDIBits:

   StretchDIBits(hDC, x, y, (WORD)lpInfo->biWidth,
          (WORD)lpInfo->biHeight, 0, 0, (WORD)lpInfo->biWidth,
          (WORD)lpInfo->biHeight, lpBits, lpInfo, DIB_RGB_COLORS,
          SRCCOPY)

Dealing with the upside-down DIB is tricky when doing a partial setting. For example, if an application wants to get the bottom third of a DIB that is w by h pixels to the device at (x, y), the call would resemble the following:

   SetDIBitsToDevice(hDC, x, y, w, h/3, 0, h/3, 0,
          (WORD)lpInfo->biHeight, lpBits, lpInfo, DIB_RGB_COLORS);

StretchDIBits()

This function is the do-all darling for displaying a DIB on the surface of a device. It is especially nice for metafiling and for printing, for which the ability to stretch is important.

The one critical hole in the current implementation of StretchDIBits() is that StretchDIBits() is supported by printer drivers and not by many display drivers. Therefore, using this function repeatedly to stretch a DIB to the screen is significantly slower than using SetDIBits (to get a device-dependent bitmap) followed by repeated StretchBlt() calls.

The implementation of this function in GDI is very straightforward. If the device driver can handle the call itself, it does. If not, and the call is 1-to-1 and the device supports SetDIBitsToDevice(), the call is converted to a SetDIBitsToDevice() call to the driver. (This works only with SRCCOPY as the ROP.) If neither of these methods is possible, CreateDIBitmap() is used to make a device-dependent version of the bitmap, and StretchBlt is called to do the actual work.

The parameters for StretchDIBits() are basically the same as for StretchBlt() (with the source hDC replaced by lpBits and lpInfo). This function does not have the nStartScan and the nNumScans parameters of the other DIB functions, so lpBits always points to the first scan of the DIB.

When using this function for anything other than full bitmap stretches, remember that all of the source coordinates (the ones relating to the DIB) are in an upside-down system. The function will appropriately flip the image, but the source rectangle is defined with Y=0 at the bottom and extents going up. Fortunately, the x-coordinates use the same conventions as Windows.

Printer drivers that do support this functionality (for example, PSCRIPT and HPPCL) usually use a halftone algorithm to output good color images. Therefore, maintaining DIBs at the highest meaningful color resolution possible (usually 8 bit) is desirable even if the output device is monochrome, because the color information is still useful for good output. Unfortunately, most printer drivers do not support any ROP other than SRCCOPY.

CreateDIBPatternBrush()

This function allows an application to create a pattern brush by specifying a DIB instead of a device-dependent bitmap, as used in the CreatePatternBrush() function. A brush created using this function is used similar to any other brush. The DIB is turned into a device-dependent bitmap at SelectObject() time for use by the device. This brush resembles a standard pattern brush to the device.

DIBS IN THE CLIPBOARD

Two basic mechanisms for placing DIBs in the Clipboard are using the CF_DIB data format or placing the DIB into a metafile and using the CF_METAFILEPICT data format.

The CF_DIB format uses a packed DIB, in which the bits follow immediately after the header and the color table. When reading or creating a packed DIB, an application must properly calculate the size of the color table to ensure that the bits are in the proper place. Because all DIB functions expect the DIB as two pointers, one to the header and one to the bits, the bits pointer must be calculated before use. (For color table size computations, see the code sample in the color table description above.)

The simplest way to place a DIB into a metafile is to use StretchDIBits():

   hMetaDC = CreateMetaFile((LPSTR) NULL));
   StretchDIBits(hMetaDC, 0, 0, biWidth, biHeight, 0, 0, biWidth,
          biHeight, lpBits, lpInfo, DIB_RGB_COLORS, SRCCOPY);
   hMetafile = CloseMetaFile(hMF);

RLE FORMATS

When the biCompression field in a DIB's header is set to either BI_RLE4 (for biBitCount = 4) or BI_RLE8 (for biBitCount = 8), the image has been run-length encoded. A description of the encoding schemes can be found in the "Microsoft Windows Software Development Kit Reference Volume 2," in the "BITMAPINFOHEADER" section of the "Data types and Structures" chapter. The basic scheme involves compressing multiple, horizontally adjacent, identical pixels into a run encoding. For example, 10 pixels of color index 17 are encoded as a run of length 10 and of index 17. Codes for end-of-scan and for delta moves are also provided, in which an X and a Y offset are provided for the next pixel.

This type of encoding usually compresses the bitmap and is also useful for creating sprite-type animations, in which only a small part of an image changes in each frame. The animation capabilities are accomplished by using delta codes to limit the number of pixels actually being set. Pixels skipped by a delta move are left untouched.

The main limitations of RLE DIBs are that an application can neither easily determine the size of the bitmap in bytes nor point to a certain scanline without decoding the bitmap from the first scan. The biSizeImage field is useful in solving the first problem. Decoding, encoding, and generally manipulating the RLE format is slower and more complicated than the noncompressed (BI_RGB) format. Some applications -- for example, Paintbrush -- refuse to read RLE DIBs. Although all APIs accept them, RLE DIBs will probably not become a universally supported format. Also, because of the relative rarity of these formats, some device drivers might not have fully tested support for the encoding and decoding processes.

To generate an RLE DIB, GetDIBits() is called with biCompression set to the desired type of encoding. The amount of memory needed to store the bits is not easily computed. If GetDIBits() is called with lpBits set to NULL, the amount of memory needed for the bits is returned in biSizeImage. A subsequent call with lpBits pointing to a properly sized block of memory returns an encoded bitmap.

Translating an RLE DIB into a device-dependent form requires no special processing. Any of the Set functions can be used normally with a header containing the proper biSizeImage and biCompression values to match the bits.

SHORTCOMINGS OF DIBS

Probably the biggest limitation of DIBs is that they are slower than device- dependent bitmaps. Translating DIBs into a device-dependent form before they can actually be displayed requires extra processing, resulting in additional overhead. In an ideal world, a 1-to-1 StretchDIBits() would be as fast as a BitBlt(). This speed would allow an application to operate effectively in the realm of the logical bitmap, with full color and full access to each and every pixel, regardless of the physical device's limitations.

DIBs are based in a coordinate system that is upside down relative to Windows, making coding a bit frustrating and not intuitive. Always remembering this quirkiness should help limit the number of iterations needed to get bitmaps properly lined up.

You can get full color using 24-bit DIBs, but they are very slow to decode, read, and write. This is especially true on 8-bit palette devices, in which translation literally can take minutes. Also, the sheer size of 24-bit DIBs makes them a bit unwieldy for general use.

DIB-RELATED PROBLEMS IN WINDOWS VERSION 3.0

Metafile recording of StretchDIBits() calls that use BITMAPCOREHEADER causes a UAE. Convert all headers to the BITMAPINFO style to avoid this problem. This workaround is recommended for general DIB processing.

The SetDIBits() simulation code for greater than 64K monochrome DIBs causes crashes or erroneous printouts when using a SetDIBits(), a SetDIBitsToDevice(), or a StretchDIBits() to a driver that does not support SetDIBits().

Copyright 1992 by Microsoft Corporation. All rights reserved.