Loading Bitmaps on the Back Buffer

The sample discussed in this tutorial (DDEX2) expands on the DDEX1 sample that was discussed in Tutorial 1. DDEX2 includes functionality to load a bitmap file on the back buffer. This new functionality is demonstrated in the following steps:

• Step 1: Creating the Palette

• Step 2: Setting the Palette

• Step 3: Loading a Bitmap on the Back Buffer

• Step 4: Flipping the Surfaces

As in DDEX1, doInit is the initialization function for the DDEX2 application. Although the code for the DirectDraw initialization does not look quite the same in DDEX2 as it did in DDEX1, it is essentially the same, except for the following section:

lpDDPal = DDLoadPalette(lpDD, szBackground);

if (lpDDPal == NULL)

goto error;

ddrval = lpDDSPrimary->SetPalette(lpDDPal);

if(ddrval != DD_OK)

goto error;

// Load a bitmap into the back buffer.

ddrval = DDReLoadBitmap(lpDDSBack, szBackground);

if(ddrval != DD_OK)

goto error;

Step 1: Creating the Palette. The ddex2 sample first loads the palette into a structure by using the following code:

lpDDPal = DDLoadPalette(lpDD, szBackground);

if (lpDDPal == NULL) goto error;

DDLoadPalette is part of the common DirectDraw functions found in the Ddutil.cpp file located in the \Dxsdk\Sdk\Samples\Misc directory. Most of the DirectDraw sample files in this SDK use this file. Essentially, it contains the functions for loading bitmaps and palettes from either files or resources. To avoid having to repeat code in the example files, these functions were placed in a file that could be reused. Make sure you include Ddutil.cpp in the list of files to be compiled with the rest of the DDEX samples.

For DDEX2, the DDLoadPalette function creates a DirectDrawPalette object from the Back.bmp file. The DDLoadPalette function determines if a file or resource for creating a palette exists. If one does not, it creates a default palette. For DDEX2, it extracts the palette information from the bitmap file and stores it in a structure pointed to by ape.

DDEX2 then creates the DirectDrawPalette object, as shown in the following example:

pdd->CreatePalette(DDPCAPS_8BIT, ape, &ddpal, NULL);

return ddpal;

When the IDirectDraw::CreatePalette method returns, the ddpal parameter points to the DirectDrawPalette object, which is then returned from the DDLoadPalette call.

The ape parameter is a pointer to a structure that can contain either 2, 4, 16, or 256 entries, organized linearly. The number of entries depends on the dwFlags parameter in the IDirectDraw::CreatePalette method. In this case, the dwFlags parameter is set to DDPCAPS_8BIT, which indicates that there are 256 entries in this structure. Each entry contains 4 bytes (a red channel, a green channel, a blue channel, and a flags byte).

Step 2: Setting the Palette. After you create the palette, you pass the pointer to the DirectDrawPalette object (ddpal) to the primary surface by calling the IDirectDrawSurface::SetPalette method, as shown in the following example:

ddrval = lpDDSPrimary->SetPalette(lpDDPal);

if(ddrval != DD_OK)

// SetPalette failed.

After you have called IDirectDrawSurface::SetPalette, the DirectDrawPalette object is associated with the DirectDrawSurface object. Any time you need to change the palette, you simply create a new palette and set the palette again. (Although this is how this is done in this example, there are other ways of changing the palette, as will be shown in later examples.)

Step 3: Loading a Bitmap on the Back Buffer. After the DirectDrawPalette object is associated with the DirectDrawSurface object, DDEX2 loads the Back.bmp bitmap on the back buffer by using the following code:

// Load a bitmap into the back buffer.

ddrval = DDReLoadBitmap(lpDDSBack, szBackground);

if(ddrval != DD_OK)

// Load failed.

DDReLoadBitmap is another function found in Ddutil.cpp. It loads a bitmap from a file or resource into an already existing DirectDraw surface. (You could also use DDLoadBitmap to create a surface and load the bitmap into that surface). For DDEX2, it loads the Back.bmp file pointed to by szBackground onto the back buffer pointed to by lpDDSBack. The DDReLoadBitmap function calls the DDCopyBitmap function to copy the file onto the back buffer and stretch it to the proper size.

The DDCopyBitmap function copies the bitmap into memory, and it uses the GetObject function to retrieve the size of the bitmap. It then uses the following code to retrieve the size of the back buffer onto which it will place the bitmap:

// Get the size of the surface.

ddsd.dwSize = sizeof(ddsd);

ddsd.dwFlags = DDSD_HEIGHT | DDSD_WIDTH;

pdds->GetSurfaceDesc(&ddsd);

The ddsd value is a pointer to the DDSURFACEDESC structure. This structure stores the current description of the DirectDraw surface. In this case, the DDSURFACEDESC members describe the height and width of the surface, which are indicated by DDSD_HEIGHT and DDSD_WIDTH. The call to the IDirectDrawSurface::GetSurfaceDesc method then loads the structure with the proper values. For DDEX2, the values will be 480 for the height and 640 for the width.

The DDCopyBitmap function locks the surface and copies the bitmap to the back buffer, stretching or compressing it as applicable by using the StretchBlt function, as shown below:

if ((hr = pdds->GetDC(&hdc)) == DD_OK)

{

StretchBlt(hdc, 0, 0, ddsd.dwWidth, ddsd.dwHeight, hdcImage, x, y,

dx, dy, SRCCOPY);

pdds->ReleaseDC(hdc);

}