CreateDIBPatternBrush

3.0

The CreateDIBPatternBrush function creates a brush that has the pattern specified by a device-independent bitmap (DIB). The brush can subsequently be selected for any device that supports raster operations.

Parameters

hglbDIBPacked

Identifies a global memory object containing a packed device-independent bitmap. A packed DIB consists of a BITMAPINFO structure immediately followed by the array of bytes that define the pixels of the bitmap. The BITMAPINFO structure has the following form:

typedef struct tagBITMAPINFO {  /* bmi */
    BITMAPINFOHEADER    bmiHeader;
    RGBQUAD             bmiColors[1];
} BITMAPINFO;

For a full description of this structure, see the Microsoft Windows Programmer's Reference, Volume 3.

fnColorSpec

Specifies whether the bmiColors member(s) of the BITMAPINFO structure contain explicit red, green, blue (RGB) values or indices into the currently realized logical palette. This parameter must be one of the following values:

Return Value

The return value is the handle of the brush if the function is successful. Otherwise, it is NULL.

Comments

To retrieve the handle identified by the hglbDIBPacked parameter, an application calls the GlobalAlloc function to allocate a global memory object and then fills the memory with the packed DIB.

Bitmaps used as fill patterns should be 8 pixels by 8 pixels. If such a 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, and pixels mapped to the second color (at offset 1 in the color table) are displayed using the background color.

When it has finished using a brush created by CreateDIBPatternBrush, an application should remove the brush by using the DeleteObject function.

Example

The following example retrieves a bitmap named DIBit from the application's resource file, uses the bitmap to create a pattern brush in a call to the CreateDIBPatternBrush function, selects the brush into a device context, and fills a rectangle by using the new brush:

HRSRC hrsrc;
HGLOBAL hglbl;
HBRUSH hbr, hbrOld;

hrsrc = FindResource(hinst, "DIBit", RT_BITMAP);
hglbl = LoadResource(hinst, hrsrc);
LockResource(hglbl);


hbr = CreateDIBPatternBrush(hglbl, DIB_RGB_COLORS);
hbrOld = SelectObject(hdc, hbr);
Rectangle(hdc, 10, 10, 100, 100);
UnlockResource(hglbl);

See Also

CreatePatternBrush, DeleteObject, FindResource, GetDeviceCaps, GlobalAlloc, LoadResource, LockResource, SelectObject, SetBkColor, SetTextColor, UnlockResource