CBrush::CreateDIBPatternBrush

BOOL CreateDIBPatternBrush( HGLOBAL hPackedDIB, UINT nUsage );

BOOL CreateDIBPatternBrush( const void* lpPackedDIB, UINT nUsage );

Return Value

Nonzero if successful; otherwise 0.

Parameters

hPackedDIB

Identifies a global-memory object containing a packed device-independent bitmap (DIB).

nUsage

Specifies whether the bmiColors[] fields of the BITMAPINFO data structure (a part of the “packed DIB”) contain explicit RGB values or indices into the currently realized logical palette. The parameter must be one of the following values:

DIB_PAL_COLORS The color table consists of an array of 16-bit indexes.
DIB_RGB_COLORS The color table contains literal RGB values.
The following value is available only in the second version of this member function:
DIB_PAL_INDICES No color table is provided. The bitmap itself contains indices into the logical palette of the device context into which the brush is to be selected.

lpPackedDIB

Points to a packed DIB consisting of a BITMAPINFO structure immediately followed by an array of bytes defining the pixels of the bitmap.

Remarks

Initializes a brush with the pattern specified by a device-independent bitmap (DIB). The brush can subsequently be selected for any device context that supports raster operations.

The two versions differ in the way you handle the DIB:

In the first version, to obtain a handle to the DIB you call the Windows ::GlobalAlloc function to allocate a block of global memory and then fill the memory with the packed DIB.
In the second version, it is not necessary to call ::GlobalAlloc to allocate memory for the packed DIB.

A packed DIB consists of a BITMAPINFO data structure immediately followed by the array of bytes that defines the pixels of the bitmap. Bitmaps used as fill patterns should be 8 pixels by 8 pixels. If the bitmap is larger, Windows creates a fill pattern using only the bits corresponding to the first 8 rows and 8 columns of pixels in the upper-left corner of the bitmap.

When an application selects a two-color DIB pattern brush into a monochrome device context, Windows ignores the colors specified in the DIB and instead displays the pattern brush using the current text and background colors of the device context. Pixels mapped to the first color (at offset 0 in the DIB color table) of the DIB are displayed using the text color. Pixels mapped to the second color (at offset 1 in the color table) are displayed using the background color.

For information about using the following Windows functions, see the Win32 SDK Programmer’s Reference:

::CreateDIBPatternBrush (This function is provided only for compatibility with applications written for versions of Windows earlier than 3.0; use the ::CreateDIBPatternBrushPt function.)
::CreateDIBPatternBrushPt (This function should be used for Win32-based applications.)
::GlobalAlloc

Example

// Resource handle to bitmap.
HRSRC hRes;    
// Global handles to bitmap resource.
HGLOBAL hData, hLockedData;   
CBrush brush;

// Find the resource handle.
hRes = ::FindResource(AfxGetResourceHandle(),
    MAKEINTRESOURCE(IDB_BRUSH), RT_BITMAP);
if (hRes != NULL)
{
   // Lock and Load (or Load and Lock).
   if (((hData = ::LoadResource(AfxGetResourceHandle(),
       hRes)) != NULL) && 
      ((hLockedData = (HGLOBAL)::LockResource(hData)) != NULL))
   {
      // Initialize the brush.
      brush.CreateDIBPatternBrush(hLockedData,
          DIB_RGB_COLORS);

      // Select the brush into the device context.
      CBrush* pOldBrush = pDC->SelectObject(&brush);

      // Draw.
      pDC->Rectangle(50, 50, 200, 200);

      // Restore the original device context.
      pDC->SelectObject(pOldBrush);

      // Free the resource.
      ::FreeResource(hLockedData);
   }
}

CBrush Overview | Class Members | Hierarchy Chart