Creating CBitmap Objects

CBitmap objects are empty when they’re first instantiated. The bitmap that the class wraps must eventually be created for the object to be useful. There are several ways to create bitmaps within a CBitmap class. The first uses the CreateBitmap function and has the following syntax:

CBitmap::CreateBitmap( int nWidth, int nHeight,
  int nPlanes, int nBits, const *void lpBits );

The nWidth and nHeight parameters specify the size of the bitmap in pixels. The nPlanes argument specifies the number of bit planes that the bitmap will be — this will almost always be one. The nBits argument specifies the number of bits for each pixel. The last argument, lpBits, enables you to initialize the bitmap with a bit pattern. The bit pattern is copied into the bitmap memory, but it’s still the caller’s responsibility to maintain and dispose of the original bit pattern memory. Normally a bit pattern isn’t specified when creating a bitmap, and in this case, the lpBits parameter will be NULL. Without initializing the bitmap pattern, it will contain meaningless data and look like a jumbled up mess. The following example creates a bitmap with a width of 50, a height of 60, one bit plane, 24 bits per pixel, and no initial bit pattern:

CBitmap Bitmap;
Bitmap.CreateBitmap( 50, 60, 1, 24, NULL );

Many times, it’s important to find out the configuration of a bitmap that’s already been created. To do this, you must use the GetObject function to have a BITMAP structure filled in with information about the bitmap. When retrieving information about the CBitmap object, the bmBits member will be NULL because you can't get a direct pointer to bitmap memory. However, if you create use CBitmap's CreateBitmapIndirect function, bmBits will be used to initialize the bitmap data if the structure member is not NULL. The bmType member will always be zero. The BITMAP structure definition below is followed by an example of using to fill in a BITMAP structure:

typedef struct tagBITMAP
{
  int bmType;
  int bmWidth;
  int bmHeight;
  int bmWidthBytes;
  BYTE bmPlanes;
  BYTE bmBitsPixel;
  void *bmBits;
} BITMAP;

// Bitmap is a CBitmap object.
BITMAP bm;
Bitmap.GetObject( sizeof( BITMAP ), &bm );

Another way to create a bitmap is with the CreateBitmapIndirect function. To do this, a BITMAP structure must first be filled in with the values for the bitmap that’s to be created. A call to CreateBitmapIndirect then uses the members of the structure to create the bitmap. An example that uses the CreateBitmapIndirect function to create a bitmap with a width of 100, a height of 200, one bit plane, and 16 bits of color depth follows:

BITMAP bm;
bm.bmType = 0;
bm.bmWidth = 100;
bm.bmHeight = 200;
bm.bmWidthBytes = 200;
bm.bmPlanes = 1;
bm.bmBitsPixel = 16;
bm.bmBits = NULL;

CBitmap Bitmap;
Bitmap.CreateBitmapIndirect( &bm );

Many times you simply want to create a bitmap that’s compatible with the video system. You can do this without having to specify the bit planes or bits per pixel by using the CreateCompatibleBitmap function. This function takes a pointer to a device context, and uses the device context to figure out how many bit planes and how many bits per pixel the bitmap must be. Following is an example of using this from the OnDraw function:

void CBitmapView::OnDraw(CDC* pDC)
{
 CBitmapDoc* pDoc = GetDocument();
 ASSERT_VALID(pDoc);

 CBitmap Bitmap;
 Bitmap.CreateCompatibleBitmap( pDC );
}

Loading and Setting Bitmap Content

Before using a bitmap, you’ll want to set its contents with meaningful data. When bitmaps are first created, their memory contains unpredictable data. If you display a bitmap on the screen before setting the data, what you’ll see will resemble a television that’s not set to a station and is just producing random patterns. We’ll talk about two different ways to set the contents of a bitmap. The first uses the SetBitmapBits function, and the second uses the LoadBitmap function.

The SetBitmapBits function copies the contents of a memory buffer into the bitmap memory. The source memory must be created and subsequently managed and deleted by the calling code. There are two reasons you’d want to set bitmap contents from a memory buffer. The first is because you want to algorithmically create a pattern in memory and move it into the bitmap. The second is because you want to load bitmap data from disk and then move it into bitmap memory. The example below creates a 24-bit bitmap, creates a memory buffer that’ll produce a red rectangle when copied to memory, and then sets the contents of the bitmap to the red pattern.

// Instantiate CBitmap and create the bitmap
CBitmap Bitmap;
Bitmap.CreateBitmap( 50, 50, 1, 24, NULL );

// Get the bitmap dimensions and allocation a buffer
// large enough for its contents.
BITMAP bm;
Bitmap.GetObject( sizeof( BITMAP ), &bm );
unsigned char pData =
    new unsigned char [bm.bmHeight*bm.bmWidthBytes];
// Loop through and set the buffer values so
// that the pattern will be solid red.
for( int y=0; y<bm.bmHeight; y++ )
{
 for( int x=0; x<bm.bmWidth; x++ )
 {
  pData[x*3+y*bm.bmWidthBytes] = 0;
  pData[x*3+1+y*bm.bmWidthBytes] = 0;
  pData[x*3+2+y*bm.bmWidthBytes] = 255;
  }
 }

// Set the bitmap with the red data.
Bitmap.SetBitmapBits( bm.bmHeight * bm.bmWidthBytes,
 pData );

// Delete the data buffer.
delete [] pData;

There is another alternative. You can put the bitmap into your program as a resource, and then use the LoadBitmap function to transfer the data into a bitmap. A bonus of using LoadBitmap is that you don’t have to use CreateBitmap or any of the other bitmap creation functions, it’s done for you by LoadBitmap. Another nice thing is that LoadBitmap will create a bitmap that’s compatible with the current video system, regardless of the format of the resource bitmap. Following is an example of loading a bitmap with a resource id of IDB_BITMAP1 into a CBitmap object:

CBitmap Bitmap;
Bitmap.LoadBitmap( IDB_BITMAP1 );

One other function that you might find useful is LoadMappedBitmap. It takes the same argument that LoadBitmap takes, but converts various colors in the bitmap according to how the user's system colors are set. For instance, it converts black pixels to the color of button text, and converts dark gray to the color of button shadows.