Programming Windows with MFC, Second Edition

The bitmapped image, or simply bitmap, is a staple of modern computer graphics because it allows computers to store complex images in the form of 1s and 0s. In Windows, bitmaps are GDI objects that are handled at a fairly high level just like fonts, brushes, pens, and other GDI objects. You can create bitmaps with a paint program, embed them as resources in an application's EXE file, and load them with a simple function call; or you can create bitmaps on the fly by using GDI functions to draw to virtual display surfaces in memory. Once created, a bitmap can be displayed on the screen or reproduced on the printer with a few simple function calls.

Two types of bitmaps are supported in 32-bit Windows: device-dependent bitmaps (DDBs) and device-independent bitmaps (DIBs). Also supported in 32-bit Windows is a variation on the device-independent bitmap that was first introduced in Windows NT—something programmers refer to as a DIB section. DDBs are the simplest of the lot as well as the most limiting. They also happen to be the only type of bitmap that MFC thoroughly encapsulates. We'll get the fundamentals out of the way first by covering CBitmaps and DDBs, and later we'll move on to the more powerful DIBs and DIB sections. As you read, be aware that I'll often use the term bitmap interchangeably with the more specific terms DDB, DIB, and DIB section. Which type of bitmap I'm referring to (or whether I'm using the term generically) should be clear from the context of the discussion.

DDBs and the CBitmap Class

It goes without saying that before you can do anything with a bitmap, you must first create it. One way to create a bitmap is to construct a CBitmap object and call CBitmap::CreateCompatibleBitmap:

In this example, dc represents a screen device context and nWidth and nHeight are the bitmap's dimensions in pixels. The reason CreateCompatibleBitmap requires a device context pointer is that the format of the resulting DDB is closely tied to the architecture of the output device. Providing a pointer to a device context enables Windows to structure the DDB so that it's compatible with the device on which you intend to display it. The alternative is to call CBitmap::CreateBitmap or CBitmap::CreateBitmapIndirect and specify the number of color planes and number of bits per pixel per color plane, both of which are device-dependent values. These days, about the only practical use for CreateBitmap and CreateBitmapIndirect is for creating monochrome bitmaps. Monochrome bitmaps are sometimes useful even in color environments, as one of this chapter's sample programs will demonstrate.

A DDB created with CreateCompatibleBitmap initially contains random data. If you want to do something with the DDB—say, display it in a window—you'll probably want to draw something into the bitmap first. You can use GDI functions to draw into a bitmap by first creating a special type of device context known as a memory device context (DC) and then selecting the bitmap into the memory DC. In essence, a bitmap selected into a memory DC becomes the device context's display surface, just as the display surface that corresponds to a screen DC is the screen itself. The following code creates an uninitialized DDB that measures 100 pixels square. It then creates a memory DC, selects the bitmap into it, and initializes all the pixels in the bitmap to blue:

CDC::CreateCompatibleDC creates a memory DC that's compatible with the specified device context. The device context whose address you pass in is usually a screen DC, but it could just as easily be a printer DC if the image you're preparing is destined for a printer rather than the screen. Once a bitmap is selected into a memory DC, you can draw to the memory DC (and hence into the bitmap) using the same CDC member functions you use to draw to a screen or printer DC.

The big difference between drawing to a memory DC and drawing to a screen DC is that pixels drawn to a memory DC aren't displayed. To display them, you have to copy them from the memory DC to a screen DC. Drawing to a memory DC first and then transferring pixels to a screen DC can be useful for replicating the same image on the screen several times. Rather than draw the image anew each time, you can draw it once in a memory DC and then transfer the image to a screen DC as many times as you want. (Be aware, however, that many display adapters will perform better if you copy the image from the memory DC to the screen DC one time and then replicate the image already present in the screen DC as needed.) Bitmaps play an important role in the process because when a memory DC is first created it contains just one pixel you can draw to, and that pixel is a monochrome pixel. Selecting a bitmap into a memory DC gives you a larger display surface to draw on and also more colors to work with as long as the bitmap isn't monochrome.

Blitting Bitmaps to Screens and Other Devices

How do you draw a bitmap on the screen? Bitmaps can't be selected into nonmemory DCs; if you try, SelectObject will return NULL. But you can use CDC::BitBlt or CDC::StretchBlt to "blit" pixels from a memory DC to a screen DC. BitBlt transfers a block of pixels from one DC to another and preserves the block's dimensions; StretchBlt transfers a block of pixels between DCs and scales the block to the dimensions you specify. If dcMem is a memory DC that contains a 100-pixel by 100-pixel bitmap image and dcScreen is a screen DC, the statement

copies the image to the screen DC and consequently displays it on the screen. The first two parameters passed to BitBlt specify the coordinates of the image's upper left corner in the destination (screen) DC, the next two specify the width and height of the block to be transferred, the fifth is a pointer to the source (memory) DC, the sixth and seventh specify the coordinates of the upper left corner of the block of pixels in the source DC, and the eighth and final parameter specifies the type of raster operation to be used in the transfer. SRCCOPY copies the pixels unchanged from the memory DC to the screen DC.

You can shrink or expand a bitmap as it's blitted by using StretchBlt instead of BitBlt. StretchBlt's argument list looks a lot like BitBlt's, but it includes an additional pair of parameters specifying the width and height of the resized image. The following statement blits a 100-by-100 image from a memory DC to a screen DC and stretches the image to fit a 50-by-200 rectangle:

By default, rows and columns of pixels are simply removed from the resultant image when the width or height in the destination DC is less than the width or height in the source DC. You can call CDC::SetStretchBltMode before calling StretchBlt to specify other stretching modes that use various methods to preserve discarded color information. Refer to the documentation on SetStretchBltMode for further details, but be advised that the most potentially useful alternative stretching mode—HALFTONE, which uses dithering to simulate colors that can't be displayed directly—works in Windows NT and Windows 2000 but not in Windows 95 and Windows 98.

You can get information about a bitmap by passing a pointer to a BITMAP structure to CBitmap::GetBitmap. BITMAP is defined as follows:

The bmType field always contains 0. bmWidth and bmHeight specify the bitmap's dimensions in pixels. bmWidthBytes specifies the length (in bytes) of each line in the bitmap and is always a multiple of 2 because rows of bits are padded to 16-bit boundaries. bmPlanes and bmBitsPixel specify the number of color planes and the number of pixels per bit in each color plane. If bm is an initialized BITMAP, you can determine the maximum number of colors the bitmap can contain by using the following statement:

Finally, bmBits contains a NULL pointer following a call to GetBitmap if the bitmap is a DDB. If bitmap represents a CBitmap object, the statements

initialize bm with information about the bitmap.

The bitmap dimensions returned by GetBitmap are expressed in device units (pixels), but both BitBlt and StretchBlt use logical units. If you want to write a generic DrawBitmap function that blits a bitmap to a DC, you must anticipate the possibility that the DC might be set to a mapping mode other than MM_TEXT. The following DrawBitmap function, which is designed to be a member function of a class derived from CBitmap, works in all mapping modes. pDC points to the device context the bitmap is being blitted to; x and y specify the location of the image's upper left corner at the destination:

Because of some inadvertent skullduggery that MFC's CDC::DPtoLP function performs on CSize objects, the size variable that holds the bitmap's dimensions is a CPoint object, not a CSize object. When you pass CDC::DPtoLP the address of a CPoint object, the call goes straight through to the ::DPtoLP API function and the conversion is performed properly, even if one or more of the coordinates comes back negative. But when you pass CDC::DPtoLP the address of a CSize object, MFC performs the conversion itself and converts any negatives to positives. It might make intuitive sense that sizes shouldn't be negative, but that's exactly what BitBlt expects in mapping modes in which the y axis points upward.

Bitmap Resources

If all you want to do is display a predefined bitmap image—one created with the Visual C++ resource editor or any paint program or image editor that generates BMP files—you can add a bitmap resource to your application's RC file like this:

Then you can load it like this:

In this example, IDB_MYLOGO is the bitmap's integer resource ID and Logo.bmp is the name of the file that contains the bitmap image. You can also assign a bitmap resource a string ID and load it this way:

LoadBitmap accepts resource IDs of either type. After loading a bitmap resource, you display it the way you display any other bitmap—by selecting it into a memory DC and blitting it to a screen DC. Splash screens like the one you see when Visual C++ starts up are typically stored as bitmap resources and loaded with LoadBitmap (or its API equivalent, ::LoadBitmap) just before they're displayed.

CBitmap includes a related member function named LoadMappedBitmap that loads a bitmap resource and transforms one or more colors in the bitmap to the colors you specify. LoadMappedBitmap is a wrapper around ::CreateMappedBitmap, which was added to the API so that colors in bitmaps used to paint owner-draw buttons, toolbar buttons, and other controls could be transformed into system colors upon loading. The statement

loads a bitmap resource and automatically transforms black pixels to the system color COLOR_BTNTEXT, dark gray (R=128, G=128, B=128) pixels to COLOR_BTNSHADOW, light gray (R=192, G=192, B=192) pixels to COLOR _BTNFACE, white pixels to COLOR_BTNHIGHLIGHT, dark blue (R=0, G=0, B=128) pixels to COLOR_HIGHLIGHT, and magenta (R=255, G=0, B=255) pixels to COLOR_WINDOW. The idea behind mapping magenta to COLOR_WINDOW is that you can add "transparent" pixels to a bitmap by coloring them magenta. If LoadMappedBitmap transforms magenta pixels into COLOR_WINDOW pixels and the bitmap is displayed against a COLOR_WINDOW background, the remapped pixels will be invisible against the window background.

You can perform custom color conversions by passing LoadMappedBitmap a pointer to an array of COLORMAP structures specifying the colors you want changed and the colors you want to change them to. One use for custom color mapping is for simulating transparent pixels by transforming an arbitrary background color to the background color of your choice. Later in this chapter, we'll examine a technique for drawing bitmaps with transparent pixels that works with any kind of background (even those that aren't solid) and requires no color mapping.

DIBs and DIB Sections

The problem with device-dependent bitmaps is—well, that they're device-dependent. You can manipulate the bits in a DDB directly using CBitmap::GetBitmapBits and CBitmap::SetBitmapBits, but because pixel color data is stored in a device-dependent format, it's difficult to know what to do with the data returned by GetBitmapBits (or what to pass to SetBitmapBits) unless the bitmap is monochrome. Worse, the color information encoded in a DDB is meaningful only to the device driver that displays it. If you write a DDB to disk on one PC and read it back on another, there's a very good chance that the colors won't come out the same. DDBs are fine for loading and displaying bitmap resources (although you'll get poor results if a bitmap resource contains more colors than your hardware is capable of displaying) and for drawing images in memory DCs before rendering them on an output device. But their lack of portability makes them unsuitable for just about anything else.

That's why Windows 3.0 introduced the device-independent bitmap, or DIB. The term DIB describes a device-independent format for storing bitmap data, a format that's meaningful outside the context of a display driver and even outside the framework of Windows itself. When you call ::CreateBitmap (the API equivalent of CBitmap::CreateBitmap) to create a bitmap, you get back an HBITMAP handle. When you call ::CreateDIBitmap to create a bitmap, you also get back an HBITMAP. The difference is what's inside. Pixel data passed to ::CreateBitmap is stored in device driver format, but pixel data passed to ::CreateDIBitmap is stored in DIB format. Moreover, the DIB format includes color information that enables different device drivers to interpret colors consistently. The API includes a pair of functions named ::GetDIBits and ::SetDIBits for reading and writing DIB-formatted bits. It also includes functions for rendering raw DIB data stored in a buffer owned by the application to an output device. Windows BMP files store bitmaps in DIB format, so it's relatively easy to write a function that uses ::CreateDIBitmap to convert the contents of a BMP file into a GDI bitmap object.

DIB sections are similar to DIBs and were created to solve a performance problem involving the ::StretchDIBits function in Windows NT. Some graphics programs allocate a buffer to hold DIB bits and then render those bits directly to the screen with ::StretchDIBits. By not passing the bits to ::CreateDIBitmap and creating an HBITMAP, the programs enjoy direct access to the bitmap data but can still display the bitmap on the screen. Unfortunately, the client/server architecture of Windows NT and Windows 2000 dictates that bits blitted from a buffer on the client side be copied to a buffer on the server side before they're transferred to the frame buffer, and the extra overhead causes ::StretchDIBits to perform sluggishly.

Rather than compromise the system architecture, the Windows NT team came up with DIB sections. A DIB section is the Windows NT and Windows 2000 equivalent of having your cake and eating it, too: you can select a DIB section into a DC and blit it to the screen (thus avoiding the undesirable memory-to-memory moves), but you can also access the bitmap bits directly. Speed isn't as much of an issue with the ::StretchDIBits function in Windows 95 and Windows 98 because these operating systems are architected differently than Windows NT and Windows 2000, but Windows 95 and Windows 98 support DIB sections just as Windows NT and Windows 2000 do and also offer some handy API functions for dealing with them. Win32 programmers are encouraged to use DIB sections in lieu of ordinary DIBs and DDBs whenever possible to give the operating system the greatest amount of flexibility in handling bitmap data.

The bad news about DIBs and DIB sections is that current versions of MFC don't encapsulate them. To use DIBs and DIB sections in your MFC applications, you have to either resort to the API or write your own classes to encapsulate the relevant API functions. Writing a basic CDib class or extending CBitmap to include functions for DIBs and DIB sections isn't difficult, but I'm not going to do either here because it's very likely that some future version of MFC will include a comprehensive set of classes representing DIBs and DIB sections. What I'll do instead is show you how to get the most out of MFC's CBitmap class and how to combine CBitmap with API functions to get some very DIB-like behavior out of ordinary CBitmaps.

Blits, Raster Operations, and Color Mapping

The most common use for CDC::BitBlt is to blit bitmap images to the screen. But BitBlt does more than just transfer raw bits. In reality, it's a complex function that computes the color of each pixel it outputs by using Boolean operations to combine pixels from the source DC, the destination DC, and the brush currently selected in the destination DC. The SRCCOPY raster-op code is simple; it merely copies pixels from the source to the destination. Other raster-op codes aren't so simple. MERGEPAINT, for example, inverts the colors of the source pixels with a Boolean NOT operation and ORs the result with the pixel colors at the destination. BitBlt supports 256 raster-op codes in all. The 15 shown in the following table are given names with #define statements in Wingdi.h.

BitBlt Raster-Op Codes

You can derive custom raster-op codes by applying the logical operations you want to the bit values in the following list and using the result to look up a DWORD-sized raster-op code in the "Ternary Raster Operations" section of Microsoft's Platform SDK.

Pat (for "pattern") represents the color of the brush selected into the destination DC; Src represents the pixel color in the source DC; and Dest represents the pixel color in the destination DC. Let's say you want to find a raster-op code that inverts a source bitmap, ANDs it with the pixels at the destination, and ORs the result with the brush color. First apply these same operations to each column of bits in the list. The result is shown here:

Look up 0xF2 in the ternary raster operations table, and you'll find that the full raster-op code is 0xF20B05. Consequently, you can pass BitBlt the hex value 0xF20B05 instead of SRCCOPY or some other raster-op code and it will perform the raster operation described above.

So what can you do with all those raster-op codes? The truth is that in color environments you probably won't use many of them. After SRCCOPY, the next most useful raster operations are SRCAND, SRCINVERT, and SRCPAINT. But as the sample program in the next section demonstrates, using an unnamed raster-op code can sometimes reduce the number of steps required to achieve a desired result.

BitBlt is part of a larger family of CDC blitting functions that includes StretchBlt (which we've already discussed), PatBlt, MaskBlt, and PlgBlt. PatBlt combines pixels in a rectangle in the destination DC with the brush selected into the device context, basically duplicating the subset of BitBlt raster operations that don't use a source DC. MaskBlt combines pixels in source and destination DCs and uses a monochrome bitmap as a mask. One raster operation (the "foreground" raster operation) is performed on pixels that correspond to 1s in the mask, and another raster operation (the "background" raster operation) is performed on pixels that correspond to 0s in the mask. PlgBlt blits a rectangular block of pixels in a source DC to a parallelogram in the destination DC and optionally uses a monochrome bitmap as a mask during the transfer. Pixels that correspond to 1s in the mask are blitted to the parallelogram; pixels that correspond to 0s in the mask are not. Unfortunately, MaskBlt and PlgBlt are supported in Windows NT 3.1 and higher and in Windows 2000 but not in Windows 95 and Windows 98. If you call either of them in Windows 95 or Windows 98, you'll get a 0 return, indicating that the function failed.

Some output devices (notably plotters) don't support BitBlt and other blitting functions. To determine whether BitBlts are supported on a given device, get a device context and call GetDeviceCaps with a RASTERCAPS parameter. If the RC_BITBLT bit is set in the return value, the device supports BitBlts; if the RC_STRETCHBLT bit is set, the device also supports StretchBlts. There are no specific RASTERCAPS bits for other blit functions, but if you're writing for Windows NT and BitBlt isn't supported, you should assume that PatBlt, MaskBlt, and PlgBlt aren't supported, either. Generally, plotters and other vector-type devices that don't support blits will set the RC_NONE bit in the value returned by GetDeviceCaps to indicate that they don't support raster operations of any type.

BitBlt and other blitting functions produce the best results (and also perform the best) when the color characteristics of the source and destination DCs match. If you blit a 256-color bitmap to a 16-color destination DC, Windows must map the colors in the source DC to the colors in the destination DC. On some occasions, however, you can use color mapping to your advantage. When BitBlt blits a monochrome bitmap to a color DC, it converts 0 bits to the destination DC's current foreground color (CDC::SetTextColor) and 1 bits to the destination DC's current background color (CDC::SetBkColor). Conversely, when it blits a color bitmap to a monochrome DC, BitBlt converts pixels that match the destination DC's background color to 1 and all other pixels to 0. You can use the latter form of color mapping to create a monochrome mask from a color bitmap and use that mask in a routine that blits all pixels except those of a certain color from a bitmap to a screen DC, in effect creating transparent pixels in the bitmap.

Sound interesting? Icons implement transparent pixels by storing two bitmaps for every icon image: a monochrome AND mask and a color XOR mask. You can draw bitmaps with transparent pixels by writing an output routine that uses BitBlts and raster operations to build the AND and XOR masks on the fly. The BitmapDemo sample program in the next section shows how.

The BitmapDemo Application

BitmapDemo is a non-document/view application created with AppWizard that demonstrates how to load a bitmap resource and BitBlt it to the screen. It also shows how to make clever use of BitBlts and raster-op codes to blit irregularly shaped images by designating one color in the bitmap as the transparency color. The program's output consists of a rectangular array of bitmap images drawn against a background that fades from blue to black. When Draw Opaque is checked in the Options menu, bitmaps are blitted to the screen unchanged, producing the result shown in Figure 15-5. If Draw Transparent is checked instead, red pixels are removed from the bitmaps when they're blitted to the screen. The result is pictured in Figure 15-6.

Figure 15-5. The BitmapDemo window with transparency disabled.

Figure 15-6. The BitmapDemo window with transparency enabled.

BitmapDemo uses a CBitmap-derived class named CMaskedBitmap to represent bitmaps. CMaskedBitmap contains two member functions that CBitmap doesn't: a Draw function for blitting a bitmap to a DC and a DrawTransparent function for blitting a bitmap to a DC and simultaneously filtering out all pixels of a specified color. With CMaskedBitmap to lend a hand, the statements

are all you need to create a bitmap object, load a bitmap resource into it, and draw that bitmap on the device represented by pDC. The x and y parameters specify the placement of the bitmap's upper left corner. The statements

do the same but don't blit any pixels in the bitmap whose color is bright magenta—RGB (255, 0, 255). With CMaskedBitmap to help out, drawing bitmaps with "holes" or nonrectangular profiles is easy: just assign all the transparent pixels in the bitmap a common color and pass that color to DrawTransparent. DrawTransparent will see to it that the transparent pixels don't get blitted along with the others.

The source code for CMaskedBitmap::Draw should look familiar to you: it's identical to the DrawBitmap function discussed earlier. CMaskedBitmap::DrawTransparent is a little more complicated. The comments in the source code should help you understand what's going on. If the comments don't make things clear enough, here's a summary of the steps involved in blitting a bitmap to the screen but omitting pixels of a certain color:

1. Create a memory DC, and select the bitmap into it.
2. Create a second memory DC, and select in a monochrome bitmap whose size is identical to that of the original bitmap. Create an AND mask by setting the background color of the memory DC created in step 1 to the transparency color and blitting the bitmap to the DC. The resultant AND mask has 1s everywhere the original bitmap has pixels whose color equals the transparency color and 0s everywhere else.
3. Create a third memory DC, and select in a bitmap whose size and color characteristics match those of the original bitmap. Create an XOR mask in this DC by first blitting the image from the memory DC created in step 1 to this DC with a SRCCOPY raster-op code and then blitting the AND mask to this DC with the raster-op code 0x220326.
4. Create a fourth memory DC, and select in a bitmap whose size and color characteristics match those of the original bitmap. Blit the pixels from the rectangle in which the bitmap will go in the output DC to the newly created memory DC.
5. Create the final image in the memory DC created in step 4 by first blitting in the AND mask with a SRCAND raster-op code and then blitting in the XOR mask with a SRCINVERT raster-op code.
6. Copy the image from the memory DC to the output DC.

Notice how BitBlt is used to generate the AND mask in step 2. Because the destination DC is monochrome, the GDI translates pixels whose color equals the background color to 1s and all other pixels to 0s at the destination. It's important to set the source DC's background color equal to the bitmap's transparency color first so that the transformation will be performed properly. If you look at the code in CMaskedBitmap::DrawTransparent that corresponds to step 2, you'll see that the destination DC's size and color characteristics are set by using CBitmap::CreateBitmap to create a monochrome bitmap whose dimensions equal the dimensions of the original bitmap and then selecting the monochrome bitmap into the DC. You control the size of a memory DC's display surface and the number of colors that it supports by selecting a bitmap into it. That's why you see so many calls to CreateBitmap and CreateCompatibleBitmap in DrawTransparent.

One other point of interest in DrawTransparent is the raster-op code 0x220326 used in step 3, which performs the following raster operation involving pixels at the source and destination.

You can accomplish the same thing using "standard" raster-op codes by calling BitBlt twice: once with the raster-op code NOTSRCCOPY to invert the image in the source DC and again with SRCAND to AND the inverted image with the pixels in the destination DC. One BitBlt is obviously more efficient than two, but don't be surprised if the 0x220326 code doesn't perform any faster than the NOTSRCCOPY/SRCAND combination on some PCs. Most display drivers are optimized to perform certain raster operations faster than others, and it's always possible that a NOTSRCCOPY or a SRCAND will execute very quickly but a 0x220326 won't.

As you experiment with BitmapDemo (whose source code appears in Figure 15-7), notice that the window takes longer to repaint when BitmapDemo draws transparent pixels. That's because DrawTransparent has to do a lot more work than Draw to get a single image to the screen. The worst performance hit occurs when DrawTransparent generates the same AND and XOR masks over and over again. If you want the functionality of DrawTransparent in an application in which output performance is critical (for example, if you use transparent bitmaps to create spritelike objects that move about the screen), you should modify the CMaskedBitmap class so that the masks are generated just once and then reused as needed. Performance can also be improved by applying the AND and XOR masks directly to the destination DC rather than to a memory DC containing a copy of the pixels at the destination, but the small amount of flickering produced by the short delay between the application of the masks might be too much if you're using the bitmap for animation.

Figure 15-7. The BitmapDemo application.

Both Windows 98 and Windows 2000 support a new API function named ::TransparentBlt that performs the equivalent of a StretchBlt and also accepts a transparency color. Like BitmapDemo's DrawTransparent function, ::TransparentBlt skips pixels whose color equals the transparency color. I didn't use ::TransparentBlt because I wanted BitmapDemo to work as well on down-level systems as it works on Windows 98 and Windows 2000 systems. Which of these transparency functions you should use depends on the platforms you're targeting.

Writing a BMP File Viewer

The disk-and-drive image drawn by BitmapDemo looks pretty good because it's a simple 16-color bitmap whose colors match the static colors in the system palette. As long as you draw the bitmaps yourself and stick to the colors in the default palette, bitmaps will display just fine without custom CPalettes. But if you write an application that reads arbitrary BMP files created by other programs and you rely on the default palette for color mapping, bitmaps containing 256 or more colors will be posterized—some rather severely. You can dramatically improve the quality of the output by creating a CPalette whose colors match the colors in the bitmap. The sample program in this section demonstrates how. It also shows one way that MFC programmers can combine CBitmaps with DIB sections to create more functional bitmaps.

The sample program, which I'll call Vista, is shown in Figure 15-8. Vista is a document/view BMP file viewer that will read virtually any BMP file containing any number of colors and draw a reasonable representation of it on a screen that's capable of displaying 256 or more colors. (Vista works with 16-color screens, too, but don't expect a lot from the output if the bitmap contains more than 16 colors.) The source code, selected portions of which appear in Figure 15-9, is surprisingly simple. Other than the code that creates a logical palette after a BMP file is read from disk, the application includes very little other than the standard stuff that forms the core of every document/view application.

Figure 15-8. The Vista window with a bitmap displayed.

The view's OnDraw function displays bitmaps on the screen by selecting the logical palette associated with the bitmap into the device context (provided such a palette exists) and BitBlting the bitmap to a CScrollView. OnDraw retrieves the logical palette by calling the document's GetPalette function, and it retrieves the bitmap by calling the document's GetBitmap function. GetPalette returns a CPalette pointer to the palette that the document object creates when the bitmap is loaded. A NULL return means that no palette is associated with the bitmap, which in turn means that Vista is running on a nonpalettized video adapter. GetBitmap returns a pointer to the bitmap that constitutes the document itself. Vista's document class CVistaDoc stores the bitmap in a CBitmap data member named m_bitmap and the palette (if any) that goes with the bitmap in a CPalette member named m_palette. The bitmap and palette objects are initialized when the document's OnOpenDocument function is called (when the user selects Open from the File menu) and destroyed when the document's DeleteContents function is called.

One simple statement in OnOpenDocument reads the BMP file named in the function's parameter list:

The value returned by ::LoadImage is a valid HBITMAP if the DIB section was successfully created and NULL if it wasn't. If ::LoadImage fails, it's highly likely that the file doesn't contain a DIB. OnOpenDocument indicates as much in the error message it displays when ::LoadImage returns NULL. If the HBITMAP isn't NULL, OnOpenDocument attaches it to m_bitmap. The document (bitmap) is now loaded and ready to be displayed—almost.

If Vista is running on a palettized display device, the bitmap probably won't look very good unless there's a logical palette to go with it. After ::LoadImage returns, OnOpenDocument grabs a device context and calls GetDeviceCaps to determine whether palettes are supported. If the return value doesn't contain an RC_PALETTE flag, OnOpenDocument returns immediately and leaves m_palette uninitialized. Otherwise, OnOpenDocument initializes m_palette with a logical palette.

To determine how best to create the palette, OnOpenDocument first finds out how many colors the bitmap contains by calling GetObject with a pointer to a DIBSECTION structure. One of the members of a DIBSECTION structure is a BITMAPINFOHEADER structure, and the BITMAPINFOHEADER structure's biClrUsed and biBitCount fields reveal the number of colors in the bitmap. If biClrUsed is nonzero, it specifies the color count. If biClrUsed is 0, the number of colors equals

The following code in OnOpenDocument sets nColors equal to the number of colors in the bitmap:

What OnOpenDocument does next depends on the value of nColors. If nColors is greater than 256, indicating that the bitmap has a color depth of 16, 24, or 32 bits (images stored in BMP files always use 1-bit, 4-bit, 8-bit, 16-bit, 24-bit, or 32-bit color), OnOpenDocument creates a halftone palette by calling CPalette::CreateHalftonePalette with a pointer to the screen DC it obtained earlier:

In return, the system creates a generic palette with a rainbow of colors that's suited to the device context. In most cases, a logical palette created by CreateHalftonePalette will contain 256 colors. That's not enough to allow a bitmap containing thousands or perhaps millions of colors to be displayed with 100 percent accuracy, but it will produce much better results than you'd get if you used the device context's default palette.

If nColors is less than or equal to 256, OnOpenDocument initializes m_palette with a logical palette whose colors match the colors in the bitmap. The key to matching the bitmap's colors is the API function ::GetDIBColorTable, which copies the color table associated with a 1-bit, 4-bit, or 8-bit DIB section to an array of RGBQUAD structures. That array, in turn, is used to initialize an array of PALETTEENTRY structures and create a logical palette:

::GetDIBColorTable works only if the DIB section is selected into a device context, so OnOpenDocument creates a memory DC and selects m_bitmap into it before making the call. The rest is just detail: allocating memory for a LOGPALETTE structure, transferring the RGBQUAD values from the color table to the corresponding PALETTEENTRY entries, and calling CreatePalette. Once it has a palette to work with, Vista will display most 256-color bitmaps with stunning accuracy on 256-color screens.

For a nice touch, Vista includes a readout in its status bar that identifies the bitmap's dimensions and color depth (bits per pixel). The status bar is updated when OnOpenDocument sends Vista's main window a WM_USER_UPDATE_STATS message containing a pointer to the string that it wants to appear in the status bar pane. A message handler in the frame window class fields the message and updates the status bar accordingly.

Figure 15-9. The Vista application.

More on the ::LoadImage Function

One reason Vista can do so much with so little code is that the ::LoadImage function allows a DIB section to be built from a BMP file with just one statement. Here's that statement again:

::LoadImage is to DIB sections what ::LoadBitmap and CDC::LoadBitmap are to DDBs. But it's also much more. I won't rehash all the input values it accepts because you can get that from the documentation, but here's a short summary of some of the things you can do with ::LoadImage:

• Load bitmap resources, and create DDBs and DIB sections from them.
• Load bitmaps stored in BMP files, and create DDBs and DIB sections from them.
• Automatically convert three shades of gray (RGB (128, 128, 128), RGB (192, 192, 192), and RGB (223, 223, 223)) to the system colors COLOR_3DSHADOW, COLOR_3DFACE, and COLOR_3DLIGHT as an image is loaded.
• Automatically convert the color of the pixel in the upper left corner of the bitmap to the system color COLOR_WINDOW or COLOR_3DFACE so that the pixel and others like it will be invisible against a COLOR_WINDOW or COLOR_3DFACE background.
• Convert a color image to monochrome.

Keep in mind that ::LoadImage's color-mapping capabilities work only with images that contain 256 or fewer colors. DIBs with 256 or fewer colors contain built-in color tables that make color mapping fast and efficient. Rather than examine every pixel in the image to perform a color conversion, ::LoadImage simply modifies the color table.

Vista demonstrates how ::LoadImage can be used to create a DIB section from a BMP file and attach it to a CBitmap object. One advantage of loading a bitmap as a DIB section instead of as an ordinary DDB is that you can call functions such as ::GetDIBColorTable on it. Had the LR_CREATEDIBSECTION flag been omitted from the call to ::LoadImage, we would have been unable to access the bitmap's color table and create a logical palette from it. In general, your applications will port more easily to future versions of Windows (and probably perform better, too) if you now start using DIB sections instead of DDBs whenever possible.