Using DisplayDib to Display 256-color Images

The DisplayDib function provides a convenient way to display 256-color
bitmaps on a standard VGA display. This function reduces the display re-solution to 320-by-200 or 320-by-240 to add the 256-color palette to the display. Bitmaps displayed with DisplayDib can use the BI_RGB or BI_RLE8 format.

To use DisplayDib in your application, you must use the following header files and libraries in addition to the standard Windows and Multimedia extensions header files and libraries.

File Description

DISPDIB.H Header file containing function and data declarations.
DISPDIB.LIB Import library used to resolve function-call references.

When you call DisplayDib, your application must be the active application. All inactive applications are suspended while DisplayDib temporarily reconfigures the display. (GDI screen updates are also suspended while the display is reconfigured.) The DisplayDib function has the following syntax:

WORD DisplayDib(lpbi, lpBits, wFlags)

The lpbi parameter is a pointer to BITMAPINFO data structure that describes the DIB bitmap.

The lpBits parameter is a pointer to the start of the bitmap. If lpBits is NULL, DisplayDib assumes that the bitmap starts immediately after the BITMAPINFO data structure.

The wFlags parameter contains the flags that specifies the operation of DisplayDib. The following flags are defined for wFlags:

Flag Description

DISPLAYDIB_MODE_DEFAULT Sets display resolution to 320-by-240.
DISPLAYDIB_MODE_320x200x8 Sets display resolution to 320-by-200.
DISPLAYDIB_MODE_320x240x8 Sets display resolution to 320-by-240.
DISPLAYDIB_NOCENTER Displays the image in the lower-left corner of the display.
DISPLAYDIB_NOPALETTE Ignores the bitmap palette.
DISPLAYDIB_NOWAIT Returns from the call without waiting for a key press or mouse click.
DISPLAYDIB_BEGIN Start of multiple calls to DisplayDib.
DISPLAYDIB_END End of multiple calls to DisplayDib.

Without any flags, DisplayDib defaults to the 320-by-240 resolution and provides a 1-to-1 aspect ratio. When the function displays the bitmap, it realizes the bitmap palette and centers the image on the display. (The bitmap is clipped as required for the display.) The function does not return to the application until the user presses a key or clicks a mouse button.

Use the DISPLAYDIB_MODE_320x200x8 flag to change the display resolution to 320-by-200. This display resolution matches that of the MCGA256.DRV display driver. You can change the resolution back to the 340-by-240 resolution by Using DISPLAYDIB_MODE_320x240x8 or DISPLAYDIB_MODE_DEFAULT.

Use the DISPLAYDIB_NOCENTER flag if you don't want your images centered on the display. With this flag, DisplayDib aligns the lower-left corner of the image with the lower-left corner of the display.

The default conditions of waiting for a key press or mouse button click,
and automatically realizing the bitmap palette, are both overridden with the DISPLAYDIB_NOWAIT and DISPLAYDIB_NOPALETTE flags. These
flags are most effectively used with the DISPLAYDIB_BEGIN and DISPLAYDIB_END flags. The DISPLAYDIB_BEGIN flag marks the start
of a series of calls to DisplayDib. This flag keeps DisplayDib from switching
the low-resolution display back to the standard VGA display. This avoids display flicker if your application is displaying a series of images.

The DISPLAYDIB_NOWAIT flag returns control to your application. During a DISPLAYDIB_BEGIN sequence, this flag lets your application perform any processes it needs while the image is displayed. This can include monitoring Windows keyboard and mouse messages for a particular response, or it might include preparing to display another image in the display sequence.

Use the DISPLAYDIB_NOPALLETTE flag if your image sequence has a common palette to avoid realizing the palette for each new image. Use the DISPLAYDIB_END flag to end a sequence image. If your application must perform processes during the display of the last image, display the last image without the DISPLAYDIB_END flag. When your application competes its processes, you can send this flag with lpbi and lpBits set to NULL to end the display sequence and restore the display to normal.

When DisplayDib switches to a low-resolution display, it disables the current display driver. As a result, your application cannot use GDI to update the display. However, your application can use GDI with the DIB driver to update a bitmap for display with DisplayDib. When DisplayDib switches back to the normal VGA display, it invalidates all windows to repaint the display.

When it encounters a problem with the DIB format, DisplayDib returns DISPLAYDIB_INVALIDDIB or DISPLAYDIB_INVALIDFORMAT. If you encounter one of these error returns, check that your bitmaps are 8-bit bitmaps with the BI_RGB or BI_RLE8 format. Also check the bitmap headers for the Windows 3.0 DIB BITMAPINFOHEADER data structure; DisplayDib does not support the OS/2 BITMAPCOREHEADER data structure.

This function returns DISPLAYDIB_INVALIDTASK when it is called by a inactive application. When DisplayDib is invoked, it prevents any inactive applications from running. To avoid this error return, make sure your application is the active application before calling DisplayDib.