When you issue a complex drawing request (for example, drawing a filled area), GDI cooperates with the device driver to carry out your request. If the device driver supports the drawing request directly, GDI passes it unchanged to the driver. The driver itself may have highly optimized code to perform the drawing request or, as graphics processors become more common on video display adapters, the video hardware itself may actually execute the request. When GDI determines that the device driver cannot support the drawing request as issued, GDI itself breaks the operation into a series of simpler requests that the device driver can process.

You take maximum advantage of Windows graphical device hardware when you allow it to worry about the complexities of actually performing the drawing. That said, let's look at the drawing functions provided by Windows from the simplest to the most complex. This chapter covers the following topics:

• Drawing a single pixel
• Drawing lines with stock pens
• Creating custom pens for line drawing
• Changing the drawing mode for a line
• Drawing ellipses and polygons and filling their interiors with a stock brush
• Creating custom brushes for painting areas, including the interiors of ellipses and -polygons
• Creating and using bitmaps. We describe how to use a bitmap as a pattern for a brush and how a bitmap can be used as a drawing surface.
• Using miscellaneous GDI drawing functions that don't fit in one of the previously listed categories
• Using regions to describe areas to paint or clip
• Using general paths to describe areas to outline, paint, or clip with
• Using transformation matrices There are two graphics modes that we will discuss later in this chapter: GM_COMPATIBLE and GM_ADVANCED. The GM_COMPATIBLE mode is the only mode available on Windows 95 and Win32s. It is required (and is the default mode) on Windows NT so that Windows graphical operations are compatible with the old Windows 3.x style of graphics. The GM_ADVANCED mode enables the transformation matrix capabilities of the DC. We will discuss this more starting on Page 371. A comparison of the details of GM_COMPATIBLE and GM_ADVANCED modes is given in Table 6.21 on page 377.

  We'll start with two functions almost never used in a Windows application - getting and setting the color of a single pixel.

COLORREF rgbColor ;

HDC hdc ;

int X, Y ;

.

.

rgbColor = GetPixel (hdc, X, Y) ;

You can retrieve the color value of a pixel only when the logical coordinates identify a point within the current clipping region. The GetPixel function returns -1 when the point is outside the current clipping region.

You can set the color of a particular pixel by calling the SetPixel function:

COLORREF SetPixel(HDC hdc, int x, int y, COLORREF color);

This function sets the pixel at the point identified by the logical coordinates X and Y to the nearest approximation to the specified color. The color that is actually used to paint the pixel is returned by the SetPixel function as an RGB color value. When the specified point is outside the current clipping region, the function call is ignored and the function returns -1. Even though the multiple pixels can have the same logical coordinate (depending on the mapping mode), the SetPixel function changes only one pixel.

COLORREF rgbActualColor, rgbDesiredColor ;

HDC hdc ;

int X, Y ;

.

.

rgbActualColor = SetPixel (hdc, X, Y, rgbDesiredColor) ;

For faster pixel setting, you can use the SetPixelV function. This takes the same arguments as the SetPixel function but has a different result type:

BOOL SetPixelV(HDC hdc, int x, int y, COLORREF color);

This function returns a Boolean value describing whether it succeeded or failed; if it failed, you can get more information by calling GetLastError. Generally it will fail because the pixel is outside the clipping region. Because it does not need to return the actual color value used, it is generally faster.

Lines, Pens, and Drawing Modes

To draw a line, you must specify two sets of information about the line: its location and its appearance. You specify the location of a line as the parameters to one of the line-drawing functions. There are 11 functions that draw a line:

• LineTo, which draws a straight line
• Polyline and PolyLineTo, which draw a series of connected line segments
• PolyPolyLine, which draws one or more disjoint sets of connected line segments
• AngleArc, Arc, and ArcTo, which draw an elliptical line
• PolyBezier and PolyBezierTo, which draw cubic Bézier splines
• PolyDraw, which draws a sequence of lines and Bézier curves
• StrokePath, which draws a line along an arbitrary path The appearance of a line is determined by four attributes of the device context: the selected pen, the background mode (for broken lines), the background color (when the background mode is OPAQUE), and the drawing mode. The selected pen determines the style of the line (solid or broken), the width of the line, and the color of the line. You have the ability to specify, with a pen, the way in which lines join, what the end caps look like, and either one of a selected set of broken lines or your own pattern of dots and dashes. GDI fills in the gaps of a broken line with the background color when the background mode is OPAQUE or leaves the underlying color in the gaps when the background mode is TRANSPARENT. The drawing mode specifies how to combine the color of the pen with the color(s) being overwritten by the line. We look first at how to specify the location of a line, and then we explain how to change its appearance.

Drawing Lines

Not all of these are available in all versions of Win32. We indicate their availability in the table. Note that Win32s has only the basic Win16-equivalent drawing functions. Therefore you must be prepared to deal with the fact that not all versions of Win32 have the full suite of functions available. If you expect your program to run on all versions of Win32, you can use only the common subset of line drawing functions. You can also, with careful programming, take advantage of as many features as are available; for example, by falling back to simpler functions if you find yourself running on Win32s, but using full functionality if you find yourself running on Windows NT.

Table 6.1: Line drawing and pen creation functions
Win32s	Win32 API 3	Win32 API 4	Batch		Pen Position
				Function Name	Used	Modified	Description
		3	Y	AngleArc	3	3	Draws a line segment and an arc, starting at the current pen position.
3	3	3	Y	Arc			Draws a segment of an ellipse.
		3	Y	ArcTo	3	3	Draws a segment of an ellipse.
3	3	3		CreatePen			Creates a pen for line drawing, given the pen parameters. Implies round end caps and round joins.
3	3	3		CreatePenIndirect			Creates a pen for line drawing, given a reference to the pen parameters. Implies round end caps and round joins.
	3	3		ExtCreatePen			Creates a pen for line drawing. Allows specification of end caps and joins.
	3	3		GetArcDirection			Obtains the last value set by DC creation or the SetArcDirection call.
3	3	3		GetCurrentPositionEx	3		Returns the current pen position.
3	3	3	Y	LineTo	3	3	Draws a line from the current pen position to the specified coordinate.
3	3	3	Y	MoveToEx	3	3	Moves the pen to a specified coordinate; optionally returns the previous pen position.
	3	3	Y	PolyBezier	3		Draws one or more Bézier curves; leaves the pen at the starting point.
	3	3	Y	PolyBezierTo	3	3	Draws one or more Bézier curves; moves the pen to the endpoint of the last curve drawn.
		3	Y	PolyDraw	3	3	Draws a set of line segments and Bézier curves.
3	3	3	Y	Polyline			Draws a series of line segments.
	3	3	Y	PolylineTo	3	3	Draws a series of line segments starting at the current pen position; moves the current pen position to the endpoint of the last segment drawn.
	3	3	Y	PolyPolyLine			Draws multiple series of connected lines.
	3	3	N	SetArcDirection			Sets the drawing direction for arc and rectangle functions.
							AD_COUNTERCLOCKWISE
								Figure drawn counter-clockwise.
							AD_CLOCKWISE
								Figure drawn clock-wise.
3	3	3	N	SetBkColor			Sets the background color used to fill in the gaps in dashed or dotted lines. See SetBkMode.
3	3	3	N	SetBkMode			Sets the background mode. This determines what happens to the color in the gaps of dashed or dotted lines.
							OPAQUE	The color set via SetBkColor is used to fill in the gaps.
							TRANSPARENT	The existing color that is drawn over -remains in the gaps.
	3	3	Y	StrokePath			Draws a line along an arbitrary path.
Although PolyDraw is not available as a Windows 95 API call, a function PolyDraw95 that simulates PolyDraw is described, with its complete source code, in the Microsoft Knowledge Base article Q135059.

The simplest line-drawing function is the LineTo function. This function draws a line from the logical coordinate specified by the current pen position attribute of the specified device context up to, but not including, the logical coordinate specified by the parameters of the LineTo function. A typical call looks like the -following:

BOOL Status ;

Status = LineTo (hdc, xEnd, yEnd) ;

The initial default setting for the current pen position attribute of a device context is the logical coordinate (0, 0). The preceding statement, issued on a device context with default values for its attributes, draws a line using the currently selected pen from the logical coordinate (0, 0) up to, but not including, the point (xEnd, yEnd). When all default settings for a device context (mapping mode, window, and viewport origin) are used, the line begins in the upper-left corner of the display surface (client area, window, screen, or device, depending on the type of device context). The LineTo function returns a nonzero value when the line is drawn and zero otherwise. After the line is drawn, the current pen position attribute of the device context is changed to the position (xEnd, yEnd).

Often you will want to start a line not at (0, 0) but at general coordinates such as (xBegin, yBegin). The function changes the current pen position attribute of a device context without drawing anything. The MoveToEx function returns the previous pen position in the specified POINT structure, if you provide one (if you don't need the previous value, just provide NULL as the parameter). The MoveToEx function returns a BOOL value that indicates the success or failure of the function call.

Therefore, to draw a line from the logical coordinates (xBegin, yBegin) up to, but not including, the logical coordinates (xEnd, yEnd), do the following:

POINT pt ;

MoveToEx (hdc, xBegin, yBegin, &pt) ;

LineTo (hdc, xEnd, yEnd) ;

The MoveToEx function returns a BOOL value that indicates the success or failure of the function call.

The AngleArc, ArcTo, LineTo, PolyBezier, PolyBezierTo, PolyDraw, and PolyLineTo functions are the only line drawing functions that use the current pen position attribute, as indicated in Table 6.1 (MoveToEx "uses" the pen position to return the previous value). The AngleArc, ArcTo, LineTo, MoveToEx, PolyBezierTo, PolyDraw, and PolyLineTo functions are the only line drawing functions that change the current pen position attribute of a device context. You can retrieve the current pen position without changing it by calling the GetCurrentPositionEx function:

POINT pt ;

GetCurrentPositionEx (hdc, &pt) ;

The GetCurrentPositionEx function returns the previous pen position in the specified POINT structure.

The separate functions for specifying the beginning and ending coordinates for a line are convenient when you are drawing a series of connected line segments. You call the MoveToEx function once to establish the beginning of the series of line segments, and then you call the LineTo function to draw each connected segment. This method is best when you don't know the coordinates of all the points ahead of time. As you determine the next point, all you need to do is use the LineTo function to draw to it. However, when you know all the points, there is an alternative way to draw a series of connected line segments.

The Polyline function draws a series of connected line segments. You pass it the address of an array of POINT structures and the number of points in the array (as well as the obligatory device context). It draws a line from the first point in the array through subsequent points in the array up to, but not including, the last point in the array. The Polyline function produces exactly the same output that would be produced by using the MoveToEx and LineTo functions to move to each point in the array and then drawing a line to the next point in the array when you use an ordinary (called "cosmetic") pen. The Polyline function, however, does not use or update the current pen position attribute of the device context. Since you know what the last pen position will be, namely, the last pair of coordinates, you can explicitly MoveToEx to that point if you need to. Alternatively, you can use the PolyLineTo function, which does update the current pen position. But unlike the Polyline function, in which the first point of the array is the first point of the polyline, PolylineTo specifies in the array the second point of the polyline; the first point is the current pen position.

If you are using a "geometric pen", however, the behavior of PolyLine and PolyLineTo are somewhat different. In Windows NT, the end cap and line join characteristics of the geometric pen come into play, and you will get lines with the selected style. In Windows 95, geometric pens are supported only when stroking a path, a topic we discuss starting on page 384. If you want geometric pen support on both platforms, you need to use PolyLine or PolyLineTo to establish a path and then stroke that path.

PolyDraw allows you to draw a complex figure composed of MoveToEx, LineTo, PolyBezierTo and CloseFigure operations, all in one function call. We will discuss it in detail in the section on paths, because we need to see how it relates to a path.

PolyLine, Polygon, PolyPolygon, and PolyDraw have one major advantage over drawing the individual lines to form the shape: If you draw the individual lines with LineTo, each line ends with a shape called an end cap, for example, a rounded end, which is the default. But if you are drawing thick lines, you may want the shapes to be smoothly joined. You will see how to control this when we talk about the Win32 pens in detail, in particular the ExtCreatePen function. But for now, be aware that these composite drawing functions really do have a potentially different effect than using the individual line drawing functions on the same set of point coordinates.

The following code draws a 10 ¥ 10 logical unit square centered around the origin. Of course, unless the origin is moved, only a quarter of the square is visible. Not all the braces are absolutely required. We put them in to make the association of the coordinates more apparent:

POINT apt [] = { {-5, -5},

{ 5, -5},

{ 5, 5},

{-5, 5},

{-5, -5} } ;

Polyline (hdc, apt, DIM(apt)) ;

You should note that both the LineTo, PolylineTo, Polyline, and the PolyDraw functions draw up to, but not including, the terminal point. Because they do draw the starting point, you can connect line segments without writing any point on the line more than once. This becomes quite important when using some drawing modes in which the result of drawing a line depends partially on the contents of the display before drawing the line. Drawing modes are discussed in depth beginning on page 293.

The next line-drawing function is the Arc function, one of the several functions that draw curved lines. The Arc function draws a line from a portion of the perimeter of an ellipse. The general form of a call to the function looks like this:

Arc (hdc, xUL, yUL, xLR, yLR, xBegin, yBegin, xEnd, yEnd) ;

The two points (xUL, yUL) and (xLR, yLR) specify the upper-left and lower-right corners of a bounding rectangle. GDI draws the arc within the bounding rectangle. It uses the convention that a bounding rectangle specifies an area that includes the upper and left coordinates of the rectangle but excludes the lower and right coordinates of the rectangle. It is important to keep this in mind to avoid being off by one unit.

One and only one ellipse can be inscribed in a given rectangle, so specifying a bounding rectangle uniquely determines an ellipse. When the rectangle is a square, the ellipse is a circle. After you've specified the location and size of the ellipse, all that remains is to specify where on the perimeter of the ellipse the line segment should begin and end.

Windows, however, does not require you to calculate the exact coordinates of the beginning and ending points on the perimeter of the ellipse. The logical coordinates (xBegin, yBegin) are used as one end of an imaginary line to the point at the logical coordinates ((xUL+xLR)/2, (yUL+yLR)/2), which is the center of the rectangle and, therefore, the center of the ellipse. Windows uses the point of intersection of this imaginary line and the perimeter of the ellipse as the actual starting point for the line segment. Another imaginary line from the logical coordinate (xEnd, yEnd) to the center of the ellipse is similarly used to determine the actual ending point for the line segment.

The net effect is that the beginning and ending points passed to the Arc function need only be near where you want the line segment to begin and end. They do not need to be exactly on the perimeter of the ellipse. Windows draws the arc from the beginning point to the ending point in a counterclockwise direction around the perimeter of the ellipse. Figure 6.1 shows a line drawn with the Arc function. We've drawn the bounding rectangle, the ellipse the arc is based on, and the imaginary lines using a dotted pen. We drew the arc itself using a wider, solid pen.

Another arc-drawing function, ArcTo, is available in Windows NT but not in Windows 95 or Win32s. This works just like the Arc function, except that it also uses the current pen position. It draws a straight line segment between the current position and the specified starting point of the arc and updates the current pen position to be the endpoint of the elliptical segment. This effect can be seen also in -Figure 6.2.

The AngleArc function draws both a line segment and an arc. It draws the line segment from the current pen position to the beginning of the arc. The arc itself is drawn along the perimeter of a circle (unlike the Arc and ArcTo functions, which can draw along an ellipse). The center of the circle and its radius are specified as input parameters to the function. Two angles are specified: the angle at which the arc starts and the sweep angle, the number of degrees counterclockwise that the arc traverses. Note that these latter two values, unlike most angle functions found in the C math library, are specified in degrees, not radians. The following call will draw an arc 50 logical units in radius, starting at the current point and rotating for 30 degrees clockwise starting at the horizontal positive axis:

POINT pt;

GetCurrentPointEx(hdc, &pt);

AngleArc(hdc, pt.x - 50, pt.y, 50, 0.0, -30.0);

The results are shown in Figure 6.3.

Win32 can draw compound curves using the PolyBezier and PolyBezierTo functions. These are not available in Win32s. They allow you to draw a complex curve by using a method known as a cubic Bézier splines. A Bézier spline, named after the person who first described and studied them,¹ is a curve that is specified by four control points, which we can call p1, p2, p3, and p4. The curve starts at the x,y position defined by p1 and ends at the x,y position defined by p4. The PolyBezier and PolyBezierTo take the first control point, p1, as the current position of the pen. Therefore, for a simple spline, you need to define only three control points: the points p2, p3, and p4. The "Poly" part of the name comes from the property that allows you to specify more than one group of three control points. For example, given that p1 is already specified, you can specify p2, p3, and p4 to get a single Bézier curve. But if you specify three additional points, p5, p6, and p7, then the function will draw a second spline, starting at p4 and using the additional points to define the endpoint (p7) and control points (p5, p6). You can specify as many triples of points as you wish. The PolyBezier function draws the curve(s) based on the specified points but leaves the current pen position unchanged. The PolyBezierTo function draws the curves exactly as PolyBezier but moves the pen to the endpoint of the last Bézier curve drawn.

A Bézier cubic spline is controlled by the two internal points. The curve starts from the first point specified, p1, and is drawn tangent to a line drawn between p1 and p2. The curve ends at the point p4 and is tangent to a line drawn between p3 and p4. Some examples are shown in Figure 6.4. The WM_PAINT handler that drew them is shown in Listing 6.1.

Listing 6.1: The WM_PAINT handler for the Bézier example

int caption; // string id of caption

BYTE style[4]; // coordinate style

POINT pt[4];

} bezier;

bezier b1 = { IDS_BEZIER_DOUBLE_CURVE,

{ DT_RIGHT | DT_TOP,

DT_CENTER | DT_BOTTOM,

DT_CENTER | DT_TOP,

DT_CENTER | DT_BOTTOM},

{ 30, 40,

50, 20,

70, 100,

80, 40}

};

bezier b2 = { IDS_BEZIER_CROSSOVER,

{DT_RIGHT | DT_TOP,

DT_LEFT | DT_VCENTER,

DT_RIGHT | DT_VCENTER,

DT_CENTER | DT_TOP},

{120, 80,

200, 50,

110, 40,

170, 80}

};

bezier b3 = { IDS_BEZIER_SIMPLE_CURVE,

{DT_CENTER | DT_TOP,

DT_CENTER | DT_BOTTOM,

DT_CENTER | DT_BOTTOM,

DT_CENTER | DT_TOP},

{220, 60,

240, 40,

260, 40,

280, 60}

};

bezier b4 = { IDS_BEZIER_COMPLEX_CURVE,

{DT_CENTER | DT_TOP,

DT_RIGHT | DT_BOTTOM,

DT_LEFT | DT_BOTTOM,

DT_CENTER | DT_TOP},

{300, 40,

330, 10,

370, 5,

360, 40}

};

/****************************************************************

* drawDot

* Inputs:

* HDC hdc: display context

* LPPOINT pt: Point at which to draw dot

* BYTE style: Style control

* LPSTR label: Optional label, or NULL

* Result: void

*

* Effect:

* Draws the dot and labels it according to the given text

****************************************************************/

static void drawDot(HDC hdc, LPPOINT pt, BYTE style, LPSTR label)

{

RECT r;

HFONT f;

SIZE size;

SIZE space;

TEXTMETRIC tm;

int height;

#define DOTSIZE 1

Ellipse(hdc, pt->x - DOTSIZE,

pt->y - DOTSIZE,

pt->x + DOTSIZE,

pt->y + DOTSIZE);

if(label != NULL)

{ /* has text */

// Create a nice small font

f = createCaptionFont(-5, _T("Arial"));

SelectFont(hdc, f);

// Determine where to place our text

GetTextExtentPoint32(hdc, _T(" "), 1, &space);

GetTextExtentPoint32(hdc, label, lstrlen(label), &size);

GetTextMetrics(hdc, &tm);

height = tm.tmHeight + tm.tmInternalLeading;

r.left = pt->x;

r.top = pt->y;

if(style & DT_LEFT)

r.left = pt->x + space.cx;

else

if(style & DT_CENTER)

r.left = pt->x - size.cx / 2 - space.cx;

else

if(style & DT_RIGHT)

r.left = pt->x - size.cx - 2 * space.cx;

if(style & DT_TOP)

r.top = pt->y + 16 * DOTSIZE;

else

if(style & DT_VCENTER)

r.top = pt->y - height;

else

if(style & DT_BOTTOM)

r.top = pt->y - 2 * height;

r.bottom = r.top + 2 * height;

r.right = r.left + size.cx + 2 * space.cx;

// FrameRect(hdc, &r, GetStockBrush(BLACK_BRUSH));

DrawText(hdc, label, -1, &r,

DT_CENTER | DT_VCENTER | DT_SINGLELINE);

DeleteFont(f);

} /* has text */

}

/****************************************************************

* drawBezierDot

* Inputs:

* HDC hdc: display context

* bezier * b: Bezier descriptor

* int i: Index of bezier point to describe

* Result: void

*

* Effect:

* Draws an illustrative dot using the currently selected

* pen and brush. Draws the pen coordinates using the style

* parameters

****************************************************************/

static void drawBezierDot(HDC hdc, bezier * b, int i)

{

TCHAR coords[30];

wsprintf(coords,_T("%d,%d"), b->pt[i].x, b->pt[i].y);

drawDot(hdc, &b->pt[i], b->style[i], coords);

}

/****************************************************************

* drawBezier

* Inputs:

* HDC hdc: DC to draw in

* bezier * b: Bezier point description

* Result: void

*

* Effect:

* Draws a bezier curve, showing all the control points

****************************************************************/

static void drawBezier(HDC hdc, HWND hwnd, bezier * b)

{

HPEN showpen = CreatePen(PS_SOLID, 1, RGB(192,192,192)); example

HPEN curvepen = CreatePen(PS_SOLID, 2, RGB(0,0,0));

SelectPen(hdc, showpen);SelectPen

Polyline(hdc, &b->pt[0], 4);

SelectPen(hdc, curvepen);

if(!PolyBezier(hdc, &b->pt[0], 4))

{ /* no beziers */

PostMessage(hwnd, UWM_ERROR, IDS_BEZIER_FAILED,

IDS_NOT_SUPPORTED);

} /* no beziers */

else

{ /* finish drawing */

SelectPen(hdc, GetStockPen(BLACK_PEN));

SelectBrush(hdc, GetStockBrush(BLACK_BRUSH));

drawBezierDot(hdc, b, 0);

drawBezierDot(hdc, b, 1);

drawBezierDot(hdc, b, 2);

drawBezierDot(hdc, b, 3);

} /* finish drawing */

DeletePen(showpen);

DeletePen(curvepen);

}

/****************************************************************

* scaleToWindow

* Inputs:

* HDC hdc: Display context

* HWND hwnd: Window handle

* int width: Width to scale

* int height: Height to scale

* Result: void

*

* Effect:

* Scales the window. Maintains isotropic scaling so the

* entire image, whose dimensions are given as input

* parameters, will fit in the resulting window.

* min(hwnd.width()/width, hwnd.height/height)

****************************************************************/

void scaleToWindow(HDC hdc, HWND hwnd, int width, int height)

{

RECT r;

GetClientRect(hwnd, &r);

float dx = (float)r.right / (float)width;

float dy = (float)r.bottom / (float) height;

float scale = min(dx, dy);

SetMapMode(hdc, MM_ISOTROPIC);

SetWindowExtEx(hdc, 1000, 1000, NULL);

SetViewportExtEx(hdc, (int)(1000.0f * scale),

(int)(1000.0f * scale),

NULL);

}

/****************************************************************

* bezier_OnPaint

****************************************************************/

static void bezier_OnPaint(HWND hwnd)

{

PAINTSTRUCT ps;

HDC hdc = BeginPaint(hwnd, &ps);

int restore = SaveDC(hdc);

SetGraphicsMode(hdc, GM_ADVANCED);Set

translate(hdc, 0.0f, 20.0f);

scaleToWindow(hdc, hwnd, 400, 120);

drawBezier(hdc, hwnd, &b1);

drawBezier(hdc, hwnd, &b2);

drawBezier(hdc, hwnd, &b3);

drawBezier(hdc, hwnd, &b4);

RestoreDC(hdc, restore);

EndPaint(hwnd, &ps);

}

Creating Pens

You call the GetStockPen macro API function (defined in windowsx.h as a call to the GetStockObject function) to get a handle to one of the stock pens. After you have the handle to the pen, you can select it into a device context by calling the SelectPen macro API function (defined in windowsx.h as a call to the SelectObject function). For example, to use a white stock pen rather than the default black stock pen, you can do the following:

HPEN hpen ;

hpen = GetStockPen (WHITE_PEN) ;

SelectPen (hdc, hpen) ;

All lines drawn after selecting the white pen into the device context will be drawn in white. As long as you need only a 1-pixel-wide pen that can write in black, white, or invisible ink, you can stick with Windows's stock pens. Generally, though, you will want a little more variety in pens. To get it, you must abandon the stock pens and create your own.

Creating, using, and deleting your own pen is a five-step process:

1. Create a logical pen using the CreatePen, the CreatePenIndirect, or the ExtCreate-Pen function.

2. Select the logical pen into a device context by calling the SelectPen function.

3. Draw the lines using this pen by calling any of the line drawing functions, such as LineTo, Polyline, or Arc.

4. Select either the original pen or a stock pen into the device context by calling the SelectPen function or by using RestoreDC specifying a context that was saved before you did the SelectPen operation. This replaces your created pen.

5. Delete the logical pen by calling the DeletePen macro API function (defined in windowsx.h as a call to the DeleteObject function). You must not delete a pen while it is selected into a device context.

The easiest way to create a custom pen is to call the -CreatePen function or the CreatePenIndirect function. You pass the style, width, and color of the pen as parameters, and it returns a handle of type HPEN to a logical pen. The call looks like the following:

HPEN hpen ;

hpen = CreatePen (PenStyle, Width, Color) ;

The PenStyle parameter specifies whether a line drawn with the created pen will be solid, broken, or invisible. The windows.h header file defines seven symbolic names for pen styles: two for solid lines, four for broken lines, and one for invisible lines. Figure 6.5 shows each symbolic name and the pattern produced by each style. The line samples in Figure 6.5 are all 1 pixel wide. The PS_SOLID and PS_INSIDEFRAME styles are also shown with a rectangle drawn with the pen selected and then overlaid with the same rectangle drawn with the stock black pen to show how the two pens relate to a rectangle. You can study all these effects using the DC Explorer application of Chapter 5.

The Width parameter normally specifies the width of the pen in logical units. When this parameter is 0, GDI draws a line that is one device-unit wide (1-pixel wide). When this parameter is 1 or greater, GDI draws a line that is Width-logical-unit-wide with half the width on each side of the line. The actual width of the line in device units depends on the mapping mode that's in effect. GDI converts the width of a pen from logical units to device units using the x-axis scaling factor as determined by the mapping mode.

The Width parameter also can affect the style of the drawn line. GDI cannot draw dotted or dashed lines with a pen created from CreatePen or CreatePenIndirect unless the pen is 1 pixel wide. When the Width parameter specifies a logical width that translates to physical width greater than 1, GDI draws with a solid pen of that width even when you request a dotted or dashed pen style. You always get a null pen when you request one, regardless of the physical width of the pen. You cannot create a pen to draw dashed or dotted lines wider than 1 pixel using CreatePen; you must use ExtCreatePen to get these.

GDI also handles the width slightly differently in some situations when the pen style is PS_INSIDEFRAME. The PS_INSIDEFRAME style specifies that the mark left by a wide pen should be positioned differently than usual when drawing an arc, a chord, an ellipse, a rectangle, or a rounded rectangle. All these are figures that are drawn relative to a specified bounding rectangle. PS_INSIDEFRAME will not apply to path stroking or region outlining, topics we have not yet discussed (we do so starting on page 384).

Normally, wide pens distribute the mark equally on each side of the line. This causes part of the line to extend outside the bounding rectangle. When you use the PS_INSIDEFRAME style, GDI does not center the width around the line but offsets the pen and draws the line entirely inside the bounding rectangle. This is shown in Figure 6.5. The rectangles are drawn in a thick gray pen, and then another rectangle with identical coordinates is drawn with a 1-pixel pen. Note that for PS_SOLID, the thick pen surrounds the rectangle border, but for PS_INSIDEFRAME the thick pen is entirely within the rectangle border. A PS_INSIDEFRAME pen will also draw using dithered colors if necessary; all other pens will be rendered to the nearest pure color that is found in the current palette. If you need dithered colors, use ExtCreatePen.

The third parameter is a COLORREF value specifying the desired color of the logical pen; GDI can use a different actual color. When you select a logical pen into a device context and the pen style is not PS_INSIDEFRAME, GDI uses the nearest pure color that the device can represent for the pen. GDI will use a dithered color only for PS_INSIDEFRAME-style pens that have a physical width greater than 1.

The CreatePenIndirect function can also be used to create a logical pen. This function requires the same style, width, and color information as the CreatePen function; however, the information is passed to Windows a little differently. Instead of passing each item as a separate parameter, you fill in a LOGPEN structure and pass the address of the structure as the only parameter to the CreatePenIndirect function. The LOGPEN structure looks like the following:

typedef struct tagLOGPEN {

UINT lopnStyle ;

POINT lopnWidth ;

COLORREF lopnColor ;

} LOGPEN ;

The lopnStyle field holds the pen styles, which can be any one of the values listed in Figure 6.5. The lopnWidth field is a POINT structure. You must store the width of the pen in the x-coordinate field of the point. The y-coordinate value in the POINT structure is not used. The lopnColor field holds the desired color for the pen.

For example, a call to the CreatePenIndirect function to create a palette-relative, red, dashed, logical pen looks like the following:

HPEN hpen ;

LOGPEN logpen ;

logpen.lopnStyle = PS_DASH;

logpen.lopnWidth.x = 0 ;

logpen.lopnColor = PALETTERGB (255, 0, 0) ;

hpen = CreatePenIndirect (&logpen) ;

You also can ask Windows to copy information about an existing pen into a LOGPEN structure. The GetObject function can return information about an existing pen, brush, font, bitmap, or palette. The following code retrieves information about a pen given the handle to the pen:

LOGPEN logpen ;

GetObject ((HGDIOBJ) hpen, sizeof (logpen), (LPVOID) &logpen) ;

You may have noticed that we've been careful to call these pens logical pens. Like logical coordinates and logical units, a logical pen is a distinct entity from the physical pen used to draw into a device context. When you select a logical pen into a device context, only then are the physical width, style, and color actually determined. The same logical pen can produce differing results when used in two different device contexts.

It's worth repeating that pens (as well as brushes, bitmaps, regions, fonts, and palettes) are GDI objects. GDI objects are actually owned by GDI, and their space is managed by the GDI. A Windows program should explicitly delete all GDI objects it creates before terminating. It should also release each GDI object as soon as it is done with it. Failure to do so can cause a "resource leak". In Windows NT, this space is private to each running application and will only result in your application's becoming bulkier and bulkier as more GDI resources are unreclaimed. In Windows 95, the resources will be also be reclaimed when your program terminates, but while it is running, these resources consume shared GDI space. Although this space is very large, it is not unlimited. You can eventually fill it up, thereby causing Windows 95 to exhibit strange behavior. And in Win32s, you can lock up all of Windows when the very limited (64K) GDI space becomes glutted with objects.

Another good reason for having a good GDI-resource-deletion strategy deals with a number of third-party development tools that track resource allocation and deallocation. These tools will give you a post-mortem analysis of which resources you have allocated and failed to release. A not-uncommon scenario is that you allocate, say, 20 GDI objects at initialization and don't bother to delete them because you know they will be deleted anyway when the program term-inates. When you examine the post-mortem resource analysis, you see a large number of pens not deleted, so you ignore this part, knowing they were the initial pens. It turns out you have a re-source leak, which "leaks" one pen every time a certain operation is done. In your testing, you do that operation once. The difference between 20 and 21 unreleased pens is not easy to see and therefore might be missed. However, under actual operating conditions, this operation might be done hundreds of times, thus leaving hundreds of pens glutting up the GDI space. If you ar-range that all of your pens should be deleted, then any undeleted pen tells you immediately that you have a resource leak, which you can find and fix before the program goes into general use.

But you can't simply delete every pen you use. You must not delete a custom pen that is currently selected into a device context. You must take care to assure that each created pen is destroyed only after you're done using it. It is not sufficient to assume that because you have released a DC that the DC no longer exists and therefore the objects can be deleted. This is because you might have class-based or window-based DCs that continue to exist, as specified by the CS_CLASSDC or CS_OWNDC flags we discussed in Chapter 5.

You can create a pen of any style, width, and color you desire. Of course, the pen you're given by GDI occasionally will look a bit different than the one you expected. We already men-tioned most of the caveats. Being aware of those caveats will enable you to actually create a pen that draws exactly the way you expect-with three additions in the case of CreatePen.

You cannot specify the style of the end caps for a line written with a "fat pen" (a pen of width greater than 0) created by CreatePen or CreatePenIndirect. The end caps are always circles with a diameter equal to the pen width. Use ExtCreatePen if you need to control the end caps. The only way to get a flat side on the end of a fat line in Win32s is to adjust the clip-ping region so that the end of the line is clipped.

The color of the gaps in the line drawn by a dashed or a dotted pen isn't specified by the pen but by two other attributes of the device context in which the pen is selected: the background mode and the background color. When the background mode established by SetBkMode is TRANSPARENT, the gaps in a line are not filled in. The original background is left untouched. When the background mode is OPAQUE, the gaps in a line are filled with the color indicated by the background color attribute of the device context as established by the SetBkColor function.

Now that you have completely specified what the mark left by a pen looks like, there comes the process of transferring the "ink" to the drawing surface. Windows supports the obvious need to draw on a display, overwriting anything already there, but there are 15 other ways of copying the "ink" to the drawing surface. These are called the drawing modes.

Drawing Modes

The SetROP2 function changes the drawing mode of a device context:

int SetROP2 (HDC hdc, int DrawMode) ;

You can retrieve the current drawing mode by calling the GetROP2 function, as follows:

int DrawMode ;

DrawMode = GetROP2 (hdc) ;

The "ROP" stands for Raster OPeration, the term used to describe a bitwise Boolean operation on the pixels of a raster display device. The "2" in "ROP2" derives from the two operands: the pixels written by the pen and the pixels on the display surface. These are binary raster operations because two operands are used. Later you'll see ternary raster operations in which a third operand is involved and quaternary raster operation that involves four operands.

There are 16 ROP2 codes. This number is derived from the 16 possible outcomes of combining a pen and a monochrome display surface. The pen can be either black or white. Likewise, the display surface pixel can be either black or white. There are four possible combinations of the pen and the display surface: a white pen on a white surface, a white pen on a black surface, a black pen on a white surface, and a black pen on a black surface. You must describe to GDI what the dest-ination pixel's value should be for each of the four combinations of pen and destination. There are 16 such descriptions. One possible description would be as follows:

When the pen and the destination have the same color (that is, white and white or black and black), set the destination pixel to black. But when the pen is white and the destination is black, or vice versa, set the destination pixel to white. This is called the R2_XORPEN drawing mode. The symbolic names defined in windows.h for the raster operation codes are not assigned ar-bi-trary values. Instead, each symbolic name is assigned the decimal result value listed in Table 6.2, plus 1. This result value is produced by performing the Boolean operation listed in the right-most column on all four possible combinations of pen color and destination color. These symbolic names and their associated Boolean operations are listed in Table 6.2.

All possible combinations are represented in this table, but some are less useful than others. For example, R2_NOP derives its name from the fact that no matter what color of pen you use, the destination remains unchanged. The drawing operation performs no operation. The R2_BLACK and R2_WHITE raster operations always write black pixels and white pixels, respectively, to the destination no matter what the pen color or original color of the destination. One useful drawing mode is R2_NOT. This mode inverts the color of the destination pixels written by the pen. The pen color isn't used by the operation. Because the line is written in the inverse color of the destination, it is generally visible no matter what the destination color.

The default drawing mode for a device context is the R2_COPYPEN mode. As you can see in Table 6.2, the result of the Boolean operation on the pen and destination pixel is always the color of the pen, no matter what the destination color is. This copies the pen color to the destination surface. Basically, the pen overwrites anything already present. In the table, black is repre-sented by a 0, and white by a 1.

Table 6.2: Binary raster operation codes
Drawing Mode	Pen(P)	1	1	0	0	Decimal Result	Boolean Operation
	Dest(D)	1	0	1	0
R2_BLACK		0	0	0	0	0	0
R2_NOTMERGEPEN		0	0	0	1	1	~(P | D)
R2_MASKNOTPEN		0	0	1	0	2	~P & D
R2_NOTCOPYPEN		0	0	1	1	3	~P
R2_MASKPENNOT		0	1	0	0	4	P & ~D
R2_NOT		0	1	0	1	5	~D
R2_XORPEN		0	1	1	0	6	P ^ D
R2_NOTMASKPEN		0	1	1	1	7	~(P & D)
R2_MASKPEN		1	0	0	0	8	P & D
R2_NOTXORPEN		1	0	0	1	9	~(P ^ D)
R2_NOPR2_NOP		1	0	1	0	10	D
R2_MERGENOTPEN		1	0	1	1	11	~P | D
R2_COPYPEN		1	1	0	0	12	P (default)
R2_MERGEPENNOT		1	1	0	1	13	P | ~D
R2_MERGEPEN		1	1	1	0	14	P | D
R2_WHITE		1	1	1	1	15	1

A similar procedure handles color pens writing on a color surface. Rather than use ones and zeros as you do for a monochrome system, GDI uses RGB values to represent the colors of the pen and the destination. An RGB color value is a long integer containing red, green, and blue color fields, each 1 byte wide, representing the intensity from 0 to 255. The bitwise Boolean operation is per-form-ed on the two RGB color values. Here's an example in which a red pen is writing on a white destination surface using the R2_NOTMASKPEN operation. This operation sets the dest-ina-tion to the result of negating the logical AND of the pen color and the original destination color. The pen is red (0xFF0000), the destination is originally white (0xFFFFFF), and the result is (0x00FFFF), or full-intensity green and blue (cyan).

Some color devices, especially those with color palettes, don't assign the same meaning to the bits of a pixel's color value. You can calculate what the result of a raster operation will be, but the col-or corresponding to that bit pattern may not be defined.

GDI uses the raster operation code when a color value is a palette index (see Chapter 5) just like it does with a RGB color value; however, the result is less meaningful. Assume you per-form- the R2_NOTMASKPEN operation and have a pen using the color with palette-index 1 (a PALETTEINDEX (1) COLORREF value). This has the value 0x01000001. The destination is white, which is typically palette-index 255 (a PALETTEINDEX (255) COLORREF value). This has the value 0x010000FF. Logically ANDing the palette-indices 0x01 and 0xFF produces 0x01, and complementing that produces 0xFE. The color in palette-index 254 is the resulting color-whatever that color may be.

We wrote a set of Windows functions that draw the figure pictured in Figure 6.1. In that figure, we used the MM_ISOTROPIC mapping mode to draw dotted and solid lines using the MoveToEx, LineTo, and Arc line drawing functions and labeled the graph using the TextOut function. The graph automatically scales to the size of the window when the window is resized. All in all, it uses quite a number of the GDI functions that we have discussed so far in this chapter and in Chapter 5. You will find code very similar to this in the GDI Explorer. However, this code is somewhat simplified, since we use the same function in the Explorer to draw several of the other figures.

#define MARKGAP 10

static TCHAR xULLabel [] = _T("xUL") ;

static TCHAR yULLabel [] = _T("yUL") ;

static TCHAR xLRLabel [] = _T("xLR") ;

static TCHAR yLRLabel [] = _T("yLR") ;

static TCHAR xBeginLabel [] = _T("xBegin") ;

static TCHAR yBeginLabel [] = _T("yBegin") ;

static TCHAR xEndLabel [] = _T("xEnd") ;

static TCHAR yEndLabel [] = _T("yEnd") ;

static void

lines_OnPaint(HWND hwnd)

{

HDC hdc ;

HPEN hpenDot;

HPEN hpenThin;

HPEN hpenThick;

HPEN hpenOrig ;

int cxClient;

int cyClient ;

int xUL;

int yUL;

int xLR;

int yLR;

int xBegin;

int yBegin ;

int xEnd;

int yEnd ;

PAINTSTRUCT ps ;

RECT rect ;

SIZE size ;

/* Set the coordinates of the points */

/* used by the Arc function. */

xUL = -300 ; yUL = 200 ;

xLR = 300 ; yLR = -200 ;

xBegin = -150 ; yBegin = -250 ;

xEnd = 0 ; yEnd = 250 ;

/* Get the present size of the client area. */

GetClientRect (hwnd, &rect) ;

cxClient = rect.right ;

cyClient = rect.bottom ;

/* Get the device context and */

/* establish the coordinate mapping. */

hdc = BeginPaint (hwnd, &ps) ;

SetMapMode (hdc, MM_ISOTROPIC) ;Mapping mode:

SetViewportOrgEx (hdc, cxClient / 2, cyClient / 2, NULL) ;

SetWindowExtEx (hdc, 1000, 1000, NULL) ;

SetViewportExtEx (hdc, cxClient, -cyClient, NULL) ;

/* Create the drawing tools. */

hpenDot = CreatePen (PS_DOT, 0, RGB (0,0,0)) ;

hpenThin = CreatePen (PS_SOLID, 0, RGB (0,0,0)) ;

hpenThick = CreatePen (PS_SOLID, 5, RGB (0,0,0)) ;

/* Use a dotted pen to ... */

hpenOrig = SelectPen (hdc, hpenDot) ;

/* ...draw the rectangle and inscribed ellipse. */

Rectangle (hdc, xUL, yUL, xLR, yLR) ;

Ellipse (hdc, xUL, yUL, xLR, yLR) ;

/* Draw the imaginary lines from the begin and */

/* end points to the center of the rectangle. */

LineTo (hdc, xBegin, yBegin) ;

MoveToEx (hdc, 0, 0, NULL) ;

LineTo (hdc, xEnd, yEnd) ;

/* Use a solid thin pen to ... */

SelectPen (hdc, hpenThin) ;

/* Draw the point markers. */

MoveToEx (hdc, xUL - MARKGAP, yUL, NULL) ;

LineTo (hdc, xUL - MARKLENG, yUL) ;

MoveToEx (hdc, xUL, yUL + MARKGAP, NULL) ;

LineTo (hdc, xUL, yUL + MARKLENG) ;

MoveToEx (hdc, xLR + MARKGAP, yLR, NULL) ;

LineTo (hdc, xLR + MARKLENG, yLR) ;

MoveToEx (hdc, xLR, yLR - MARKGAP, NULL) ;

LineTo (hdc, xLR, yLR - MARKLENG) ;

MoveToEx (hdc, xBegin - MARKGAP, yBegin, NULL) ;

LineTo (hdc, xBegin - MARKLENG, yBegin) ;

MoveToEx (hdc, xBegin, yBegin - MARKGAP, NULL) ;

LineTo (hdc, xBegin, yBegin - MARKLENG) ;

MoveToEx (hdc, xEnd + MARKGAP, yEnd, NULL) ;

LineTo (hdc, xEnd + MARKLENG, yEnd) ;

MoveToEx (hdc, xEnd, yEnd + MARKGAP, NULL) ;

LineTo (hdc, xEnd, yEnd + MARKLENG) ;

/* Place labels by the markers. */

/* Draw the xUL label. */

GetTextExtentPoint32 (hdc, yULLabel,

lstrlen (yULLabel), &size) ;

TextOut (hdc,

xUL - 2 * MARKGAP - MARKLENG - size.cx,

yUL + size.cy / 2,

yULLabel, lstrlen (yULLabel)) ;

/* Draw the xUL label. */

GetTextExtentPoint32 (hdc, xULLabel,

lstrlen (xULLabel), &size) ;

TextOut (hdc,

xUL - size.cx / 2,

yUL + MARKGAP + MARKLENG + size.cy,

xULLabel, lstrlen (xULLabel)) ;

/* Draw the yLR label. */

GetTextExtentPoint32 (hdc, yLRLabel,

lstrlen (yLRLabel), &size) ;

TextOut (hdc,

xLR + 2 * MARKGAP + MARKLENG,

yLR + size.cy / 2,

yLRLabel, lstrlen (yxLRLabel)) ;

/* Draw the xLR label. */

GetTextExtentPoint32 (hdc, xLRLabel,

lstrlen (xLRLabel), &size) ;

TextOut (hdc,

xLR - size.cx / 2,

yLR - MARKGAP - MARKLENG,

xLRLabel, lstrlen (xLRLabel)) ;

/* Draw the yBegin label. */

GetTextExtentPoint32 (hdc, yBeginLabel,

lstrlen (yBeginLabel), &size) ;

TextOut (hdc,

xBegin - 2 * MARKGAP - MARKLENG - size.cx,

yBegin + size.cy / 2,

yBeginLabel, lstrlen (yBeginLabel)) ;

/* Draw the xBegin label. */

GetTextExtentPoint32 (hdc, xBeginLabel,

lstrlen (xBeginLabel), &size) ;

TextOut (hdc,

xBegin - size.cx / 2,

yBegin - MARKGAP - MARKLENG,

xBeginLabel, lstrlen (xBeginLabel)) ;

/* Draw the yEnd label. */

GetTextExtentPoint32 (hdc, yEndLabel,

lstrlen (yEndLabel), &size) ;

TextOut (hdc,

xEnd + 2 * MARKGAP + MARKLENG,

yEnd + size.cy / 2,

yEndLabel, lstrlen (yEndLabel)) ;

/* Draw the xEnd label. */

GetTextExtentPoint32 (hdc, xEndLabel,

lstrlen (xEndLabel), &size) ;

TextOut (hdc,

xEnd - size.cx / 2,

yEnd + MARKGAP + MARKLENG + size.cy,

xEndLabel, lstrlen (xEndLabel)) ;

/* Use a solid thick pen to ... */

SelectPen (hdc, hpenThick) ;

Arc (hdc, xUL, yUL, xLR, yLR,

xBegin, yBegin, xEnd, yEnd) ;

SelectPen (hdc, hpenOrig) ;

DeletePen (hpenDot) ;

DeletePen (hpenThin) ;

DeletePen (hpenThick) ;

EndPaint (hwnd, &ps) ;

}

More-complex Lines

Width = GetSystemMetrics(SM_CXBORDER);

The value returned is the value Windows uses for drawing "window borders" and is adjusted by the display driver to be a value that produces a "satisfactory" line for a horizontal border. There is also a value SM_CYBORDER, which is the recommended width for a vertical border. If you want to be strictly precise, you should use the border width based on the desired orientation of your line. However, in the modern world the aspect ratio of most displays is 1:1 ("square" pixels), so the two are usually interchangeable. Since this line is often for visual marking, then even if the values are different either one would probably suffice. However, in a given mapping mode the actual size of a logical pen that displays this "standard line" will vary. Once having obtained the "best" size for a thin pen in device units, you must also use DPtoLP on the current DC to determine the number of logical pixels you must use for your pen. Remember that if you are using the anisotropic mapping mode, the "logical units" may no longer be "square", so you may even have to compute pen widths for different angles if you want lines of equal visual thickness!

If you change mapping modes, you will have to create a new pen:

HPEN getThinPen(HDC hdc)

{

POINT Width;

Width.x = GetSystemMetrics(SM_CXBORDER);

Width.y = 0; // unused, set to 0

DPtoLP(hdc, &Width, 1);

HPEN thinpen = CreatePen(PS_SOLID, Width.x, RGB(0,0,0);

return thinpen;

}

But this leads to a new and different problem: Such attributes as dotted and dashed lines are specified to work only for 1-pixel lines! This is one of the many limitations of normal Windows pens. Furthermore, additional line capabilities were needed, such as being able to control the shape of the end caps of lines, to get joined lines in a PolyLine to match nicely, and to specify application-specific dotted or dashed lines (the default dots and dashes were often insufficient for many applications, thus leading to "hand-drawn" dashed lines drawn as a series of individual LineTo operations, which are very inefficient to draw). And, while in the days of the 8-bit 8088 and the CGA the cost of computing all of these fancy features was prohibitive, today a graphics accelerator card often has all of these facilities "in the hardware". This removes the burden of doing it entirely from Windows.² Finally, there is the limitation in a pen created by CreatePen and CreatePenIndirect that such a pen is rendered to the nearest "pure" color except for PS_INSIDEFRAME. Again, the increase in computational power and graphics displays makes this limitation seem irrelevant. Many people run cards supporting full 24-bit graphics whose video memory is larger than the entire main memory of a 286 running Windows 3.0! Thus the early engineering trade-offs made in the Windows design seem inappropriate for a modern Win32 platform.

All of this leads up to the much more sophisticated graphics interface supported by Win32. We cover many of the features in this chapter. The first we cover is the ExtCreatePen interface, which allows us to create very fancy pens that give us control over the patterns, joins, and end caps. These newer pens are distinguished from the older Win16-compatible pens by calling them geometric pens and calling the older pens cosmetic pens. A cosmetic pen is currently always 1 pixel wide and can be created by calling CreatePen or CreatePenIndirect specifying a width of 0 or by specifying PS_COSMETIC to ExtCreatePen and specifying a width of 1. The stock pens, obtained from GetStockObject, are all cosmetic pens. Note that cosmetic pens created by ExtCreatePen and which are not solid do not support OPAQUE background mode.

Cosmetic pens are more efficient for the GDI to draw than are geometric pens. They also are independent of any scaling factors that may apply. Hence, as the image is scaled the cosmetic pens always draw as 1-pixel-wide pens. This is not always right, and you have to decide what makes sense for your application. For example, as we pointed out, a 1-pixel-wide pen on a very high resolution display may be virtually impossible to see.

The ExtCreatePen call takes a pen style that is made up of four components. Each of these is specified by choosing an element from the appropriate category and using the bitwise OR operation to combine them into a single 32-bit style value. The values available are given in Table 6.3.

Table 6.3: ExtCreatePen style parameters
Style Code	Meaning
Group 1: Pen Type
PS_GEOMETRIC	A geometric pen.
PS_COSMETIC	A cosmetic pen (the same as CreatePen/CreatePenIndirect with a width of 0. For ExtCreatePen, you must specify a width of 1 for a cosmetic pen).
Group 2: Pen Style
PS_ALTERNATE	Pen sets every other pixel (PS_COSMETIC pens only).
PS_SOLID	Pen is solid.
PS_DASH	Pen is dashed. Not supported in Windows 95 for PS_GEOMETRIC pens.
PS_DOT	Pen is dotted. Not supported in Windows 95 for PS_GEOMETRIC pens.
PS_DASHDOT	Pen has alternating dashes and dots. Not supported in Windows 95 for PS_GEOMETRIC pens.
PS_DASHDOTDOT	Pen has alternating dashes and double dots. Not supported in Windows 95 for PS_GEOMETRIC pens.
PS_NULL	Pen is invisible.
PS_USERSTYLE	Pen uses a styling array supplied by the user. Not supported in Windows 95.
PS_INSIDEFRAME	Pen is solid. When this pen is used for any object that uses a bounding box, such as a rectangle or ellipse, the dimensions are adjusted so that the pen fits entirely within the bounding box. This style is only for geometric pens.
Group 3: End Cap Style (PS_GEOMETRIC only) Not supported in Windows 95 except when stroking paths.
PS_ENDCAP_ROUND	End caps are round.
PS_ENDCAP_SQUARE	End caps are square.
PS_ENDCAP_FLAT	End caps are flat.
Group 4: Line Join Styles (PS_GEOMETRIC only) Not supported in Windows 95 except when stroking paths.
PS_JOIN_BEVEL	Line joins are beveled.
PS_JOIN_MITER	Line joins are mitered. See also SetMiterLimit.
PS_JOIN_ROUND	Line joins are rounded.

The end cap style determines the relationship of the end of the ink to the end of the logical line. This is shown in Figure 6.6. The white line in each drawing represents the actual coordinates used to draw the line. This line is drawn on top of the thick lines using a 1-pixel-wide pen. The thick black or gray line shows the line drawn by the pen, given a LineTo operation that uses the same coordinates as the thin white pen but draws with the thicker pen. In each example, the two lines are drawn independently using LineTo. Note that the square endcaps and the flat endcaps, although superficially the same, bear different relationships to the coordinates to which the line is drawn.

The WM_PAINT handler for Figure 6.6 is shown in Listing 6.3.

Listing 6.3: WM_PAINT handler for end caps example

static void

drawPenExample(HWND hwnd, HDC hdc,

LPRECT r, HPEN horz,

HPEN vert, int caption,

BOOL angle)

{

HPEN whitepen =

GetStockPen(WHITE_PEN);

TEXTMETRIC tm;

RECT trect;

TCHAR text[50];

LoadString(GetWindowInstance(hwnd),

caption,

text, DIM(text));

BeginPath(hdc); // in case Windows 95

// Draw the top line in the horizontal pen

SelectPen(hdc, horz);

MoveToEx(hdc, r->left, r->top, NULL);

LineTo(hdc, r->right, r->top);

// Draw the downward line either vertical or at an

// angle depending on the `angle' option

SelectPen(hdc, vert);

LineTo(hdc, (angle ? r->left : r->right), r->bottom);

// Draw the thin white pen to show the actual LineTo

// coordinates

SelectPen(hdc, whitepen);

MoveToEx(hdc, r->left, r->top, NULL);

LineTo(hdc, r->right, r->top);

LineTo(hdc, (angle ? r->left : r->right), r->bottom);

EndPath(hdc);

StrokePath(hdc);

// define a rectangle for the text

trect.left = r->left;

trect.right = r->right;

trect.top = r->bottom + 2 * WIDTH;

GetTextMetrics(hdc, &tm);

trect.bottom = trect.top +

2 * (tm.tmHeight + tm.tmExternalLeading);

DrawText(hdc, text, -1, &trect, DT_CENTER | DT_VCENTER);

}

static void

endcaps_OnPaint(HWND hwnd)

{

// Define some parameters for the line drawing

#define X1 (1 * WIDTH)

#define Y1 (2 * WIDTH)

#define Y2 (6 * WIDTH)

#define R (3 * WIDTH)

#define Dx (5 * WIDTH)

#define Dy (8 * WIDTH)

// Define the bounding rectangles for the six

// illustrations

RECT r1 = {X1, Y1, X1 + R, Y1 + R};

RECT r2 = {X1 + Dx, Y1, X1 + R + Dx, Y1 + R};

RECT r3 = {X1 + 2 * Dx, Y1, X1 + R + 2 * Dx, Y1 + R};

RECT r4 = {X1, Y1 + Dy, X1 + R, Y1 + Dy + R};

RECT r5 = {X1 + Dx, Y1 + Dy, X1 + R + Dx, Y1 + Dy + R};

RECT r6 = {X1 + 2 * Dx, Y1 + Dy, X1 + R + 2 * Dx, Y1 + Dy + R};

// Define the brushes used by ExtCreatePen used for the

// filling

LOGBRUSH blackbrush = {BS_SOLID, RGB(0,0,0), 0 };

LOGBRUSH graybrush = {BS_SOLID, RGB(128,128,128), 0 };

// The pens we are going to use

HPEN roundblack =

ExtCreatePen(PS_GEOMETRIC | PS_ENDCAP_ROUND,

WIDTH, &blackbrush, 0, NULL);

HPEN squareblack =

ExtCreatePen(PS_GEOMETRIC | PS_ENDCAP_SQUARE,

WIDTH, &blackbrush, 0, NULL);

HPEN flatblack =

ExtCreatePen(PS_GEOMETRIC | PS_ENDCAP_FLAT,

WIDTH, &blackbrush, 0, NULL);

HPEN roundgray =

ExtCreatePen(PS_GEOMETRIC | PS_ENDCAP_ROUND,

WIDTH, &graybrush, 0, NULL);

HPEN squaregray =

ExtCreatePen(PS_GEOMETRIC | PS_ENDCAP_SQUARE,

WIDTH, &graybrush, 0, NULL);

HPEN flatgray =

ExtCreatePen(PS_GEOMETRIC | PS_ENDCAP_FLAT,

WIDTH, &graybrush, 0, NULL);

// Define a font to be used for the captions

HFONT font = createCaptionFont(-20, TimesFont) ;

PAINTSTRUCT ps;

HDC hdc;

int restore;

hdc = BeginPaint(hwnd, &ps);

if(roundblack == NULL)

{ /* no ExtCreatePen */

// We are probably running under Windows 95

PostMessage(hwnd, UWM_ERROR, IDS_EXTCREATEPEN_FAILED,

IDS_NOT_SUPPORTED);

EndPaint(hwnd, &ps);

DeleteFont(font);

return;

} /* no ExtCreatePen */

restore = SaveDC(hdc);

SelectFont(hdc, font);

drawPenExample(hwnd, hdc, &r1, roundblack, roundgray,

IDS_ROUND, FALSE);

drawPenExample(hwnd, hdc, &r2, squareblack, squaregray,

IDS_SQUARE, FALSE);

drawPenExample(hwnd, hdc, &r3, flatblack, flatgray,

IDS_FLAT, FALSE);

drawPenExample(hwnd, hdc, &r4, roundblack, roundgray,

IDS_ROUND, TRUE);

drawPenExample(hwnd, hdc, &r5, squareblack, squaregray,

IDS_SQUARE, TRUE);

drawPenExample(hwnd, hdc, &r6, flatblack, flatgray,

IDS_FLAT, TRUE);

RestoreDC(hdc, restore);

EndPaint(hwnd, &ps);

// Now that we know all our objects are deselected,

// we can safely delete them

DeletePen(roundblack);

DeletePen(squareblack);

DeletePen(flatblack);

DeletePen(roundgray);

DeletePen(squaregray);

DeletePen(flatgray);

DeleteFont(font);

}

In this example, three pens are created in each color, representing each of the kinds of end caps possible. With each pen, two drawings are made: one with the lines at right angles and one with the lines at a 45° angle. The six drawings are specified by providing the function drawPenExample with a pair of pens (one for the horizontal line, one for the downward line), a rectangle whose corners are used to determine the endpoints of the lines, a caption to be placed, and an option indicating whether the second line is to be drawn vertically or at an angle.

Note that because we have selected a font and a pen, rather than saving individual objects returned by SelectObject and then restoring them individually at the end of the function, we used the SaveDC and RestoreDC functions to reset the entire DC to its initial state. We use RestoreDC rather than depending on ReleaseDC to implicitly deselect our objects because in the presence of a class DC or private DC, the -ReleaseDC would have no effect, and we want our code to work reliably independent of such considerations.

You may ignore the BeginPath, EndPath, and StrokePath functions for the moment. On Windows NT, these are actually unnecessary. But on Windows 95, geometric pens have no effect except when these operations are used. We discuss paths more fully starting on page 384. We had to include them so that this code will work correctly on Windows 95.³

You may notice in Figure 6.6 that lines that meet with other than round end caps do not create a particularly good-looking result. This is why the default for lines from CreatePen (which was the only way to create a pen in Windows 3.1 and earlier versions) is round end caps. However, you may want to have a line that ends with square or flat end caps, but which in fact has several internal segments. This is why there are functions like PolyLine, PolyLineTo, PolyDraw, and the like. You can therefore specify a pen property of how two lines drawn with a single line drawing function are joined. In Windows 3.1, this made no difference: All lines ended with round end caps, and a multiline drawing was identical to a sequence of LineTo function calls. But round line joins are not the only possible style. Two others can be specified with a pen: miter and bevel.

A bevel join, shown in Figure 6.7, clips off the corners of the lines that would protrude and flattens the end. Compare the bevel join to the effect of simply drawing two lines with flat or square end caps at an angle, as shown in Figure 6.7. Note that the join style is independent of the end cap style. You can have round end caps and a bevel join. The bevel join works well at any angle.

The round join is no different in appearance from the result of drawing two independent lines with round end caps. But since the join style is independent of the end cap style, with an ExtCreatePen pen you can have a line with square end caps and a round join, which is not possible with ordinary pens created with CreatePen. With an ordinary pen, although drawing two lines would look as if they had a round join, it would also draw lines with round end caps, because that is the only end cap style -CreatePen supports. (These all presuppose that the drawing mode is something like R2_COPYPEN. It gets even more difficult to explain, or even accomplish, in other drawing modes.)

The miter join, also shown in Figure 6.7, has some very special properties. Note that it produces the effect of projecting the outer edges of the lines forming the angle until they meet. This produces a nice, sharp edge but doesn't work well for very small angles (and if you should happen to draw a pair of lines that started and ended at the same coordinate, that is, that overlapped, the projection would be parallel and could be extended to infinity!). So notice in Figure 6.7 that as we decrease the angle, the endpoint projects farther and farther out from the point where the two lines intersect. But if you follow the drawing horizontally, you see that the last example of the miter join looks remarkably like the bevel join. That is because the distance the miter would project exceeds the miter limit. The miter length is defined as the distance from the intersection of the "inner wall" of the line to the intersection of the "outer wall" of the line. The miter limit is the maximum allowed ratio of the miter length to the line width. These are illustrated in Figure 6.8. If your line exceeds the miter limit, the join style is changed to a bevel join. You can change the miter limit using the SetMiterLimit function. The previous setting of the miter limit can be obtained either by the GetMiterLimit function or by providing a non-NULL third parameter to the SetMiterLimit function:

FLOAT oldlimit;

SetMiterLimit(hdc, 8.0, &oldlimit);

is the same as

FLOAT oldlimit;

GetMiterLimit(hdc, &oldlimit);

SetMiterLimit(hdc, 8.0, NULL);

Like most Win32 GDI functions, both of these return a BOOL result: TRUE if they succeeded and FALSE if they failed. If you know the Windows 3.1 GDI, you will also note that this function takes a FLOAT value. We show other functions that take FLOAT values later in this chapter. Windows was originally designed for the 8088, which was a slow machine. A modern processor can perform a 32-bit floating point multiply in less time than an 8088 required for a 16-bit integer add, so Win32 is less reticent about using floating point -values.

The program that created the line join illustration of Figure 6.7 is shown in Listing 6.4.

Listing 6.4: WM_PAINT handler for showing line joins

#define JOIN_PEN_WIDTH 15

#define JOIN_SAMPLE_SIZE 100

#define JOIN_WIDTH (JOIN_SAMPLE_SIZE + 2 * JOIN_SAMPLE_SIZE/3)

#define JOIN_HEIGHT (JOIN_SAMPLE_SIZE + JOIN_SAMPLE_SIZE/4)

static void polyLineInRect(HDC hdc, LPRECT r, int adjust)

{

POINT pts[3];

pts[0].x = r->left;

pts[0].y = r->bottom;

pts[1].x = r->right;

pts[1].y = r->bottom;

pts[2].x = r->right;

pts[2].y = r->top - adjust;

Polyline(hdc, pts, DIM(pts));

}

static void

drawJoin(HWND hwnd, HDC hdc, int y, DWORD style, int caption)

{

LOGBRUSH blackbrush = {BS_SOLID, RGB(0,0,0), 0 };

HPEN pen = ExtCreatePen(PS_GEOMETRIC | PS_ENDCAP_FLAT |

style, JOIN_PEN_WIDTH, &blackbrush,

0, NULL);

int restore;

RECT r;

HFONT font = createCaptionFont(-20, TimesFont);

TCHAR text[50];

LoadString(GetWindowInstance(hwnd), caption,

text, DIM(text));

restore = SaveDC(hdc);

BeginPath(hdc);

SelectFont(hdc, font);

r.top = y;

r.bottom = r.top + JOIN_SAMPLE_SIZE;

r.left = 0;

r.right = r.left + JOIN_WIDTH;

DrawText(hdc, text, -1, &r,

DT_LEFT | DT_VCENTER | DT_SINGLELINE);

SelectPen(hdc, pen);

r.right = r.left + JOIN_SAMPLE_SIZE;

OffsetRect(&r, JOIN_WIDTH, 0);

polyLineInRect(hdc, &r, 0);

OffsetRect(&r, JOIN_WIDTH, 0);

polyLineInRect(hdc, &r, 0);

OffsetRect(&r, JOIN_WIDTH, 0);

polyLineInRect(hdc, &r, JOIN_SAMPLE_SIZE / 4 );

OffsetRect(&r, JOIN_WIDTH, 0);

polyLineInRect(hdc, &r, JOIN_SAMPLE_SIZE / 6 );

EndPath(hdc);

StrokePath(hdc);

RestoreDC(hdc, restore);

DeletePen(pen);

DeleteFont(font);

}

static void

join_OnPaint(HWND hwnd)

{

#define START 20

HDC hdc;

PAINTSTRUCT ps;

hdc = BeginPaint(hwnd, &ps);

drawJoin(hwnd, hdc, START + 0, PS_JOIN_BEVEL,

IDS_BEVEL_JOIN);

drawJoin(hwnd, hdc, START + JOIN_HEIGHT, PS_JOIN_MITER,

IDS_MITER_JOIN);

drawJoin(hwnd, hdc, START + 2 * JOIN_HEIGHT, PS_JOIN_ROUND,

IDS_ROUND_JOIN);

EndPaint(hwnd, &ps);

}

As with Listing 6.3, you can for the moment ignore the use of the BeginPath, EndPath, and StrokePath functions, which are necessary to make this work in Window 95. Or you can jump ahead to page 384.

Geometric pens support additional capability beyond ordinary CreatePen/CreatePenIndirect style pens. For example, you can specify that a bitmap be used for the pen. This is because the "color" of the pen is actually specified by giving a LOGBRUSH structure, which can take a bitmap to define the brush. You can create a pen that is halftoned or plaid or that even contains an image. Those of you who programmed Windows 3.x may remember that patterned brushes were limited to bitmaps of 8 ¥ 8 pixels. This limitation is removed in Windows NT. Unfortunately, it is still in Windows 95.

Drawing Filled Areas

• Ellipses
• Polygons having an arbitrary number of sides
• The area bounded by the intersection of an ellipse and a line segment. (Windows incorrectly calls this area a chord. The chord is actually the line segment connecting the two points on the ellipse.)
• The pie-shaped wedge formed by drawing lines from the endpoints of an elliptical arc to the center of the arc
• Areas bounded by complex lines, including Bézier curves, polygons, and text outlines Windows draws the perimeter of a filled area with the pen currently selected into the device context and fills the interior of the area by painting it with the brush currently selected into the device context. The functions that draw filled areas are listed in Table 6.4. When we discuss paths, you will see that any collection of line segments can form a path and any path can be filled using either the FillPath or StrokeAndFillPath functions.

  Table 6.4: Filled-area drawing functions
  Function	Description
  Chord	Draws an arc on the perimeter of an ellipse and connects the endpoints of the arc with a chord (line segment).
  DrawFocusRect	Draws a rectangle in the style that indicates the object has the focus.
  Ellipse	Draws an ellipse.
  FillPath	Fills a path with the currently selected brush.
  FillRect	Fills the interior of a rectangle with a brush.
  FillRgn	Fills a region with the indicated brush.
  FrameRect	Draws a frame around a rectangle.
  InvertRect	Inverts the contents of a rectangle.
  Pie	Draws an arc on the perimeter of an ellipse and connects the endpoints of the arc to the center of the arc. This draws a pie-shaped wedge.
  Polygon	Draws a closed polygon.
  PolyPolygon	Draws a series of possibly open polygons.
  Rectangle	Draws a rectangle.
  RoundRect	Draws a rectangle with rounded corners.
  StrokeAndFillPath	Fills the area marked off by a path with the current brush and draws its outline with the currently selected pen.
  Note: With rectangles, the sides of the rectangle are always parallel to the axes. Rotational and shearing transformations (which we have not discussed yet) in effect change the angles of the axes. All of the above functions have BOOL results (and are batched in Windows NT 3.x).

  GDI draws the perimeter of a filled area with the pen that is selected into the device context. Everything that applies to drawing lines works the same when you are drawing the border of a filled area. This enables you to control the width of the perimeter of a filled area, its color, and its line style. In fact, you can draw the filled area without a border. Just select the NULL_PEN into the device context before drawing the filled area. You might be tempted to use the R2_NOP style, but this affects the brush as well as the pen. (For paths, you can selectively decide to draw the outline by using StrokePath, fill the interior by using FillPath, or do both by using StrokeAndFillPath. We discuss this in detail when we cover paths starting on page 384.)

  GDI paints the interior of the filled area with the brush that is selected into the device context. A brush determines the color of the filled area the way a pen determines the color of a line. However, unlike most pens (except those created with PS_INSIDEFRAME or using ExtCreatePen), Windows isn't limited to using pure colors for brushes. When you request a brush color that isn't available on a raster device, GDI attempts to approximate the desired color by producing a dithered color. Dithering is the equivalent of "halftoning". In halftone printing, the size of the black dots is changed to fool the eye into perceiving shades of gray when, in fact, there are only two colors, black and white. Dithering is an effect wherein two colors are "mixed" to fool the viewer into thinking that another color is present. Often this is done by mixing either black pixels or white pixels with a pure color. The brain, when it sees a red area with a heavy sprinkling of black pixels, interprets this as "dark red", and with a heavy sprinkling of white pixels, interprets this as "light red". But in fact only two pure colors are present: red and black or red and white. If you do not have a color in the display's color palette that gives you a "solid" color, the GDI will use dithering to approximate it visually.

  Brushes also can apply patterns when they're used. First, we show you how to draw a figure and then how to create different brushes to color it.

BOOL Rectangle (HDC hdc, int xUL, int yUL, int xLR, int yLR) ;

The logical coordinates (xUL, yUL) and (xLR, yLR) specify the upper-left and lower-right corners, respectively, of the bounding rectangle that surrounds the desired rectangle. Because they are logical coordinates, the value of xUL isn't necessarily less than xLR. Similarly, yUL is not necessarily less than yLR. Do not rely on assumptions that are true when using the MM_TEXT mapping mode but may not be true when using other mapping modes. In addition, remember that the point (xLR, yLR) isn't on the perimeter of the drawn rectangle. In the default graphics mode (GM_COMPATIBLE), GDI draws up to, but not including, the right and bottom sides of the bounding rectangle. Figure 6.9 shows a rectangle drawn with the Rectangle function. The exterior is drawn with the selected pen (the default BLACK_PEN, in this case) and the interior is filled with the selected brush (a stock LTGRAY_BRUSH). In the extended graphics mode (GM_ADVANCED), GDI draws up to and including the right and bottom sides of the bounding rectangle. GM_ADVANCED mode is not available on Windows 95.

Exactly the same parameters are required by the Ellipse function to draw an ellipse. Figure 6.10 shows an ellipse drawn within the same bounding rectangle that was used for drawing the rectangle in Figure 6.9.

The Chord and Pie functions take exactly the same parameters as the Arc function:

Arc (HDC hdc,

int xUL, int yUL,

int xLR, int yLR,

int xBegin, int yBegin,

int xEnd, int yEnd) ;

Chord (HDC hdc,

int xUL, int yUL,

int xLR, int yLR,

int xBegin, int yBegin,

int xEnd, int yEnd) ;

Pie (HDC hdc, int xUL, int yUL, int xLR, int yLR,

int xBegin, int yBegin, int xEnd, int yEnd) ;

All three functions draw the same arc. The Arc function draws the specified arc and leaves the endpoints of the arc unconnected. The Arc function draws a curved line, not a filled area. The Chord function draws the specified arc and the chord connecting the two endpoints of the arc. It then paints the interior of the area with a brush. The Pie function draws the specified arc and a line from each of the endpoints of the arc to the center of the ellipse. It then paints the interior of the pie-shaped wedge with a brush.

We drew the chord in Figure 6.11 and the pie in Figure 6.12 by changing the Arc function call in Listing 6.2 to Chord and Pie. The pie wedge in Figure 6.12 looks a bit strange because the pie isn't circular. There are no additional Windows functions for drawing circles and squares because they are special cases of ellipses and rectangles. To draw a circle or a square, the physical distance between the horizontal coordinates of the bounding rectangle must be equal to the physical distance between the vertical coordinates.

All physical measurement mapping modes and the MM_ISOTROPIC mapping modes ensure that a logical unit maps to the same physical distance on each axis. When using one of these mapping modes, you need to ensure only that equals . When using the MM_TEXT and MM_ANISOTROPIC mapping modes, you must adjust the logical coordinates to account for the aspect ratio of the device pixels. (The obsolete EGA did not have "square" pixels. In fact, it had a 4:3 ratio on pixel dimensions. This meant that if you drew a "square", that is, a figure n units wide and n units high, it would be distorted. While most modern display units have square pixels, not all printers do. Some common inkjet printers offer 600 ¥ 300 resolution, for example). When using the MM_ANISOTROPIC mapping mode, you also must compensate for the scaling of the window to the viewport.

If you use a display or printer with nonsquare pixels, you must take extra care when drawing circles and squares to do it correctly. Pixels on a VGA have an aspect ratio of 1:1; that is, they are square. The following statement, drawing into a default common display context, draws what looks like a square on a VGA but might be a rectangle on other output devices:

Rectangle (hdc, 50, 50, 100, 100) ;

This is because of the implicit use of the MM_TEXT mapping mode in which logical units are equal to device units (or pixels). On a VGA with square pixels, everything looks correct, but on a display with rectangular pixels, a rectangle is drawn.

You can draw a rectangle with rounded corners with the RoundRect function. In many ways, this function is a cross between the Rectangle function and the Ellipse function. Like these, it draws a rectangle within a bounding rectangle. However, it rounds the corners of the rectangle to match one of the four quadrants of an ellipse that you also specify. The RoundRect function is defined as

BOOL RoundRect (HDC hdc, int xUL, int yUL, int xLR, int yLR,

int Width, int Height) ;

The Width and Height parameters specify the width and height in logical units of the ellipse used to draw the rounded corners. By varying the width and height parameters, you can generate a rectangle with no rounding at the corners (width and height equal to 0) or, at the other extreme, produce a rectangle with so much rounding at the corners that it actually becomes an ellipse (width equal to and height equal to). Figure 6.13 shows a rounded rectangle with the corner ellipse dimensions equal to one third of the corresponding rectangle sides.

Finally, four rectangle drawing functions require a pointer to a RECT structure. The first is the DrawFocusRect function. This function draws a rectangle in the style used to indicate that an object has the focus. This rather strange function doesn't work the way the others do. A call to the function is defined as

BOOL DrawFocusRect(HDC hdc, CONST RECT * rect);

and can be called as

RECT rect = { xUL, yUL, xLR, yLR };

DrawFocusRect (hdc, &rect) ;

The first difference is that the upper-left and lower-right corners of the bounding rectangle aren't specified by separate parameters to the DrawFocusRect function. Instead, you must pass a pointer to a RECT structure containing the coordinates. This actually is a better way to pass the parameters. The other functions should have been designed to accept a RECT structure. But because they weren't, changing in midstream leaves this call as the oddball.

The second difference is that neither the currently selected pen nor the currently selected brush are used to draw the focus rectangle. The DrawFocusRect function draws the border of the rectangle using a dotted pen and doesn't fill the interior of the rectangle.

The third difference is that the DrawFocusRect function assumes that the mapping mode is MM_TEXT and fails to work properly when other mapping modes are in effect. The Windows documentation, unfortunately, fails to mention this assumption. To use this function when you use other mapping modes, you must convert the logical coordinates of the bounding rectangle to device coordinates. You also must change the mapping mode back to MM_TEXT, reset, if necessary, the window and viewport origin back to (0, 0), and call the DrawFocusRect function. We used a slight modification of the code in Listing 6.2 to draw Figure 6.14. The following lines of code generated the focus rectangle in Figure 6.14:

int saved = SaveDC(hdc);

SetRect (&rect, xUL, yUL, xLR, yLR) ;

LPtoDP (hdc, (LPPOINT) &rect, 2) ;

SetMapMode (hdc, MM_TEXT) ;

SetViewportOrgEx (hdc, 0, 0, NULL) ;

DrawFocusRect (hdc, &rect) ;

RestoreDC(hdc, saved);

Another big difference is that DrawFocusRect draws using the R2_XORPEN raster operation. Calling this function a second time with the same bounding rectangle erases the rectangle from the display without disturbing the underlying image. The functions we've seen previously can do almost the same thing, but you would need to select a dotted pen, select a null brush, change the drawing mode to R2_XORPEN, draw the rectangle, and finally, remember to delete the dotted pen. Even then, this only approximates the appearance of a focus rectangle. A dotted pen draws dots that are spaced farther apart than the dots in a focus rectangle. You can use ExtCreatePen to create a PS_ALTERNATE-style geometric pen to get this effect.

You cannot scroll an area of the display that contains a rectangle drawn by this function. When you want to scroll the area containing a rectangle drawn by the DrawFocusRect function, you must draw the focus rectangle a second time (which removes it from the display), scroll the area, and then draw the focus rectangle once more at the new location.

The three other rectangle drawing functions are as follows:

BOOL FillRect (HDC hdc, LPRECT rect, HBRUSH brush) ;

BOOL FrameRect (HDC hdc, LPRECT rect, HBRUSH brush) ;

BOOL InvertRect (HDC hdc, LPRECT rect) ;

The FillRect function uses the specified brush, rather than the brush currently selected in the device context, to fill the rectangle specified by the logical coordinates in the RECT structure. It fills the top and left borders of the rectangle and up to, but not including, the right and bottom borders. It also assumes that the axes in the logical coordinate system have the default orientation. That is, it requires that the bottom field of the RECT structure be greater than top and that right be greater than left. When you invert an axis, such as switching to a Cartesian-style vertical axis, these assumptions are no longer true, and the FillRect function won't draw the rectangle.

BOOL fillCartesianRect(HDC hdc, LPRECT rect, HBRUSH brush)

{

RECT r = *rect; // make copy

int saved = SaveDC(hdc);

BOOL result;

LPtoDP(hdc, (LPPOINT)&r, 2);

SetMapMode(hdc, MM_TEXT);

SetViewportOrgEx (hdc, 0, 0, NULL) ;

result = FillRect(hdc, &r, brush);

RestoreDC(hdc, saved);

return result;

}

The FrameRect function uses the specified brush to draw a border around the rectangle specified by the logical coordinates in the RECT structure. The border is one logical unit wide and high. All the functions described previously use the current pen to draw the border. Because a brush is used, the border does not have to be a pure color. When a logical unit is greater than a device unit, the border is drawn using dithered colors. The FrameRect function will not draw the border when the axes do not have the default orientation.

The InvertRect function inverts the contents of the specified rectangle. This changes all black pixels to white and all white pixels to black. Other colored pixels are changed to their respective inverse colors. A given color may have different inverse colors on different displays. Inverting the rectangle a second time restores the pixels to their original values. The InvertRect makes the same assumptions about the orientation of the axes as do the FillRect and FrameRect functions.

We discuss the FillRgn, FillPath, and StrokeAndFillPath functions when we discuss regions and paths. They are included in this list for completeness.

Many of the functions listed here work properly only if the axes have the default orientation. That is, y-values increase downward and x-values increase rightward. Be careful if you are using one of the mapping modes that allows you to change axis orientation.

A number of functions ease the effort of working with rectangles. Unfortunately, some of them also assume that horizontal axis values increase to the right and that vertical axis values increase downward. They don't work correctly when you use logical coordinates in the physical measurement mapping modes. The functions may or may not work using logical coordinates in the MM_ISOTROPIC or MM_ANISOTROPIC mapping modes. It depends on the orientation of the axes.

BOOL CopyRect (LPRECT rectDest, CONST RECT * rectSrc) ;

The CopyRect function makes one rectangle equal to another rectangle. You can do this just as easily with a structure assignment statement. This does the same thing with inline code rather than a function call to -Windows:

rectDest = rectSrc ;

The InflateRect function adds the xDelta value to the right and the yDelta value to the bottom of a rectangle and subtracts the xDelta value from the left and the yDelta value from the top. Positive values increase the size of the rectangle, and negative values shrink the rectangle. Note that this approach assumes that positive horizontal coordinates increase to the right and positive vertical coordinates increase downward. Here is a typical call to the InflateRect function:

BOOL InflateRect (LPRECT rect, int xDelta, int yDelta) ;

The IntersectRect function sets the Dest structure to the largest rectangle contained in both Src1 and Src2. It doesn't work properly unless the axes have the default orientation:

BOOL IntersectRect (LPRECT Dest, CONST RECT * Src1,

CONST RECT * Src2) ;.

The OffsetRect function shifts the rectangle xOffset units horizontally and yOffset units vertically. The xOffset and yOffset parameters can be positive or negative, thus enabling you to shift the rectangle in any direction:

BOOL OffsetRect (LPRECT rect, int xOffset, int yOffset) ;

The SetRect function initializes the four fields of a RECT structure to the provided values:

BOOL SetRect (LPRECT rect, int xUL, int yUL, int xLR, int yLR) ;

The above statement is equivalent to the following:

rect.left = xUL ;

rect.top = yUL ;

rect.right = xLR ;

rect.bottom = yLR ;

The SetRectEmpty function sets all fields in a RECT structure to 0:

BOOL SetRectEmpty (LPRECT rect) ;

The UnionRect function creates the union of the Src1 and Src2 rectangles. It sets the Dest rectangle to the smallest rectangle that can enclose the two source rectangles, that is, the bounding box that encloses the two source rectangles. It requires that the default coordinate orientation be used:

BOOL UnionRect (LPRECT Dest, CONST RECT * Src1,

CONST RECT * Src2) ;

The IsRectEmpty function returns a nonzero value when the rect parameter is an empty rectangle. An empty rectangle is a rectangle with either top equal to bottom (zero height) or left equal to right (zero width), or both:

BOOL IsRectEmpty (LPRECT rect) ;

The PtInRect function returns a nonzero value when the point specified by the pt parameter is in the rectangle. A point is in a rectangle when it is within the four sides or on the left or top side. A point is not in a rectangle when it lies on the right or bottom side of the rectangle:

BOOL PtInRect (LPRECT rect, LPPOINT pt) ;

Drawing Polygons

BOOL Polygon (HDC hdc, LPPOINT Points, int Count) ;

Unlike the Polyline function (which draws up to, but not including, the last point in the array), the Polygon function closes the polygon, if necessary, by drawing a line from the last vertex to the first. This is called "closing the figure", and you will see a generalization of it when we discuss paths (page 384). GDI draws the perimeter of the polygon with the selected pen and fills the interior of the polygon using the selected brush.

Unlike the simple rectangle and ellipse, a polygon can be a complex, overlapping figure. When a polygon is complex, the polygon-filling mode controls how GDI determines which points are interior points and therefore get filled. You get the polygon-filling mode with the GetPolyFillMode function and set it with the SetPolyFillMode function:

int PolyFillMode = GetPolyFillMode (hdc) ;

int PrevFillMode = SetPolyFillMode (hdc, PolyFillMode) ;

There are two polygon-filling modes: ALTERNATE (the default) and WINDING. When the polygon-filling mode is ALTERNATE, GDI fills every other enclosed area that is within the boundaries of the polygon. When the polygon-filling mode is WINDING, GDI computes a perimeter that encloses the polygon but does not overlap. This is the perimeter of the polygon drawn. The polygon itself can completely surround areas that aren't within the boundaries of the polygon. Those surrounded areas are not filled in either polygon-filling mode. In Figure 6.15, the left polygon was drawn with the WINDING polygon-filling mode. The right polygon was drawn with the ALTERNATE polygon-filling mode.

Listing 6.5 shows the WM_PAINT logic we used to draw the polygons in Figure 6.15. Notice that the same polygon is drawn twice. We inverted the orientation of both axes and changed from the default polygon--filling mode (ALTERNATE) to the WINDING polygon-filling mode before drawing the polygon the second time.

Listing 6.5: WM_PAINT logic for drawing Figure 6.15

{ 200, 400 },

{ 200, 0 },

{ 500, 0 },

{ 500, 300 },

{ 100, 300 },

{ 100, 200 },

{ 400, 200 },

{ 400, 100 },

{ 300, 100 },

{ 300, 400 }

} ;

static void

poly_OnPaint(HWND hwnd)

{

RECT rect;

int cxClient:

int cyClient;

HDC hdc;

PAINTSTRUCT ps;

HBRUSH hbr;

/* Get the present size of the client area. */

GetClientRect (hwnd, &rect) ;

cxClient = rect.right ;

cyClient = rect.bottom ;

/* Get the device context and */

/* establish the coordinate mapping. */

hdc = BeginPaint (hwnd, &ps) ;

SetMapMode (hdc, MM_ISOTROPIC) ;

SetViewportOrgEx (hdc, cxClient / 2, cyClient / 2, NULL) ;

SetWindowExtEx (hdc, 1000, 1000, NULL) ;

SetViewportExtEx (hdc, cxClient, -cyClient, NULL) ;

hbr = GetStockBrush (LTGRAY_BRUSH) ;

SelectBrush (hdc, hbr) ;

/* Draw the right polygon. */

Polygon (hdc, Points, DIM(Points)) ;

/* Invert the coordinate system axes. */

SetViewportExtEx (hdc, -cxClient, cyClient, NULL) ;

/* Change the polygon-filling mode. */

SetPolyFillMode (hdc, WINDING) ;

/* Draw the left polygon. */

Polygon (hdc, Points, DIM(Points)) ;

EndPaint (hwnd, &ps) ;

}

The PolyPolygon function draws a series of polygons. Unlike the Polygon function, polygons drawn by the PolyPolygon function are not automatically closed. That is, the PolyPolygon function does not draw a line from the last vertex to the first. GDI draws the perimeter of the polygon with the selected pen and fills the interior of the polygon using the selected brush. The interior of the polygon is filled in accordance with the polygon-filling mode, as is done for the Polygon function. Figure 6.16 shows the drawn polygons. In this case, we use the same points that would have drawn the two polygons shown in Figure 6.15, but we divide the points differently. You can use the GDI Explorer application to see all the variants of this. Select the PolyPolygon display and then use the right mouse button to change the properties of the drawing by selecting a different set of vertices. Selecting the 0th, 4th, and 13th vertices will generate the image shown in Figure 6.16. When the polygons are disjoint, they are drawn as if each is filled separately.

Listing 6.6 gives the WM_PAINT logic for drawing the polygons shown in Figure 6.16. Note that the same coordinates are used as for Figure 6.15, but the splits between the two points are different.

Listing 6.6: Code to draw the bizarre polygons of Figure 6.16

{ 200, 400 }, /* Right polygon */

{ 200, 0 },

{ 500, 0 },

{ 500, 300 },

{ 100, 300 },

{ 100, 200 },

{ 400, 200 },

{ 400, 100 },

{ 300, 100 },

{ 300, 400 },

{ -200, -400 }, /* Left polygon */

{ -200, 0 },

{ -500, 0 },

{ -500, -300 },

{ -100, -300 },

{ -100, -200 },

{ -400, -200 },

{ -400, -100 },

{ -300, -100 },

{ -300, -400 }

} ;

int PolyCounts [] = { 4, 9, 8 } ;

static void

polypoly_OnPaint(HWND hwnd)

{

RECT rect;

HDC hdc;

PAINTSTRUCT ps;

HBRUSH hbr;

int cxClient;

int cyClient;

/* Get the present size of the client area. */

GetClientRect (hwnd, &rect) ;

cxClient = rect.right ;

cyClient = rect.bottom ;

/* Get the device context and */

/* establish the coordinate mapping. */

hdc = BeginPaint (hwnd, &ps) ;

SetMapMode (hdc, MM_ISOTROPIC) ;

SetViewportOrgEx (hdc, cxClient / 2, cyClient / 2, NULL) ;

SetWindowExtEx (hdc, 1000, 1000, NULL) ;

SetViewportExtEx (hdc, cxClient, -cyClient, NULL) ;

hbr = GetStockBrush (LTGRAY_BRUSH) ;

SelectBrush (hdc, hbr) ;

/* Change the polygon-filling mode. */

SetPolyFillMode (hdc, ALTERNATE) ;

/* Draw the polygon. */

PolyPolygon (hdc, Points, PolyCounts, DIM(PolyCounts)) ;

EndPaint (hwnd, &ps) ;

return 0 ;

All polygons drawn by the PolyPolygon function use the polygon-filling mode in effect at the time of the call. You can't draw multiple polygons using different polygon-filling modes with a single function call. Figure 6.16, drawn by the algorithm in Listing 6.6, is drawn using the ALTERNATE polygon-filling mode. You can use the GDI Explorer to change the polygon fill mode using the right mouse button in the PolyPolygon display.

Creating and Using Stock and Custom Brushes

You use a brush exactly the same as you do a pen. You select a brush into a device context by calling the SelectBrush macro API function. Windows defines the SelectBrush macro in windowsx.h as a call to the SelectObject function. It is defined as

#define SelectBrush(hdc, hbr)

((HBRUSH)SelectObject((hdc), (HGDIOBJ)(HBRUSH)(hbr)))

You should use the SelectBrush macro API rather than a call to the SelectObject function. The macro is more descriptive. You use it like this:

HBRUSH hbrush;

HBRUSH hbrPrevious ;

hbrPrevious = SelectBrush (hdc, hbrush) ;

The SelectBrush function returns the previously selected object. In the immediately preceding example, the SelectBrush function returns the previously selected brush. You must delete all the brushes you create. You need not be concerned about accidentally deleting stock objects; DeleteObject applied to a stock brush does nothing. A brush must not be selected into a device context when it is deleted, so you must select a different brush into the device context and then delete the created brush.

Windows provides the DeleteBrush macro to delete a brush. It is defined in windowsx.h as a call to the DeleteObject function. It looks like this:

#define DeleteBrush(hbr) DeleteObject((HGDIOBJ)(HBRUSH)(hbr))

Reselecting the previously selected brush always works, provided the previously selected brush was not also the current brush:

hbr = SelectBrush (hdc, hbrPrevious) ;

DeleteBrush (hbr) ;

Generally, you are selecting a previous brush that was replaced by a brush you have newly created. So you know that the previous brush cannot be the current brush, since the current brush is local to your procedure. But beware of this trap in the fully general case.

Stock Brushes

DeleteBrush (SelectBrush (hdc, GetStockBrush (BLACK_BRUSH))) ;

Windows provides six different monochrome stock brushes, as listed in Table 6.6. Note that there are, for historical reasons, seven names for the six stock brushes.

You retrieve the handle to a stock brush like you do all stock objects: call the GetStockBrush function and pass the symbolic name of the desired stock brush. The Windows SDK defines the GetStockBrush macro API in windows.h. It looks like this:

#define GetStockBrush(i) ((HBRUSH)GetStockObject(i))

You can use the macro by writing something like this:

HBRUSH hbrush ;

hbrush = GetStockBrush (LTGRAY_BRUSH) ;

Custom Brushes

Solid Brushes

HBRUSH CreateSolidBrush

(COLORREF Color) ;

The Color parameter is a COLORREF value that specifies the color of the brush. As such, it can be an RGB, a PALETTEINDEX, or a PALETTERGB color value. When you select a solid brush into a device context, GDI attempts to produce a color as close as possible to your specified logical color. When the device supports a pure color identical to your requested color, you get that color. However, when the device doesn't support your logical color exactly, GDI will approximate the color by creating an 8 ¥ 8 bitmap containing dithered pure colors. GDI then will use that bitmap for the brush. This is unlike ordinary ("cosmetic") pens in which GDI converts the specified color into the nearest pure color supported by the device.

Hatched Brushes

hbrush = CreateHatchBrush(HatchStyle, Color);

The HatchStyle parameter can be one of the symbolic values shown in Figure 6.17.The color specified in the call to the -CreateHatchBrush function is the color of the hatch lines. GDI converts the specified color to the nearest pure color supported by the device. This differs from a solid brush, where dithered colors can be used. The color of the areas between the hatch lines is determined by the background mode attribute of the device context.

When the background mode is TRANSPARENT, GDI draws the hatch lines without changing the areas in between the lines. When the background mode is OPAQUE, GDI uses the background color (after converting it to a pure color) to fill in the areas between the hatches.

Bitmap Brushes

hbrush = CreatePatternBrush (hbitmap) ;

When you create a brush based on a monochrome bitmap, the brush uses the current text and background colors. These are not necessarily black and white. Pixels represented in the bitmap by a 0 bit are drawn with the current text color, and pixels represented in the bitmap by a 1 bit are drawn with the current background color.

Because creating the bitmap can be a chore in itself, we will finish our examination of brush creation before we look at bitmaps.

Programmers who know the Win16 API may remember that the CreatePatternBrush API call created a brush that was only 8 ¥ 8, and in fact, used only the top-most, left-most 8 rows and columns no matter how large the bitmap was. A program that relied on this behavior in Win16 will probably create unexpected results in Win32. This is because there is no such restriction in Win32; the entire bitmap will be used.

An example of a pie chart created with a bitmap (in fact, our bitmap is the classic marble.bmp bitmap that comes with Windows) is shown in Figure 6.18. The accompanying code is in Listing 6.7, although the details of how a bitmap is created may not be apparent because we have not yet discussed that topic.

Listing 6.7: Code to fill using a bitmap

ids_GetTextExtentPoint32(HINSTANCE hinst, HDC hdc, int ids, LPSIZE size)

{

TCHAR text[256];

LoadString(hinst, ids, text, DIM(text));

return GetTextExtentPoint32 (hdc, text,

lstrlen(text), size);

}

static void

bmpbrush_OnPaint(HWND hwnd)

{

PAINTSTRUCT ps;

HDC hdc = BeginPaint(hwnd, &ps);

int xUL = -300;

int yUL = 200;

int xLR = 300;

int yLR = -200;

int xBegin = -250;

int yBegin = -100;

int xEnd = 0;

int yEnd = 250;

RECT rect;

RECT r;

#define BMP_CAPTION_OFFSET (-80)

HFONT font = createCaptionFont(-(abs(BMP_CAPTION_OFFSET)),

TimesFont);

HBRUSH brush;

HBITMAP bmp;

int save = SaveDC(hdc);

SIZE size;

// Get the device context

// and establish the coordinate mapping

GetClientRect(hwnd, &rect);

SetMapMode(hdc, MM_ISOTROPIC);

SetViewportOrgEx(hdc, rect.right / 2,

rect.bottom / 2, NULL);

SetWindowExtEx(hdc, 1000, 1000, NULL);

SetViewportExtEx(hdc, rect.right, - rect.bottom, NULL);

bmp = LoadBitmap(GetWindowInstance(hwnd),

MAKEINTRESOURCE(IDB_MARBLE));

brush = CreatePatternBrush(bmp);

// Do a drop-shadow 3-D effect here

#define BMP_SHADOW (-20)

SelectBrush(hdc, GetStockObject(BLACK_BRUSH));

Ellipse(hdc, xUL, yUL + BMP_SHADOW, xLR, yLR + BMP_SHADOW);

SelectBrush(hdc, GetStockObject(WHITE_BRUSH));

Ellipse(hdc, xUL, yUL, xLR, yLR);

SelectBrush(hdc, brush);

Pie(hdc, xUL, yUL, xLR, yLR, xBegin, yBegin, xEnd, yEnd);

r = rect;

DPtoLP(hdc, (LPPOINT)&r, 2);

r.top = yLR + BMP_CAPTION_OFFSET;

r.bottom = yLR + 2 * BMP_CAPTION_OFFSET;

SelectFont(hdc, font);

ids_GetTextExtentPoint32(GetWindowInstance(hwnd), hdc,

IDS_BMPBRUSH, &size);

r.bottom = r.top - size.cy;

ids_DrawText(GetWindowInstance(hwnd), hdc, IDS_BMPBRUSH, &r,

DT_CENTER);

RestoreDC(hdc, save);

DeleteObject(font);

DeleteObject(brush);

DeleteObject(bmp);

EndPaint(hwnd, &ps);

}

The helper function ids_GetTextExtentPoint32 simulates the effect of GetTextExtentPoint32, but it is passed an instance handle and a string ID instead of a string. The painting code first computes a scaled coordinate system with 0, 0 in the center of the client area. It loads a bitmap using LoadBitMap, which loads the "marble" bitmap we copied into our project and put into the resource file. The createCaptionFont helper function creates a font of a given size, which must be negative to indicate a desired point size. To ensure that the font value is always negative whether we place the caption above or below the pie chart, we pass in the negative of the absolute value of its separation. We use this value so that the font will always appear to be one "line" above or below the pie chart. After we draw a black ellipse slightly offset below a white ellipse (giving us a sort-of-3D effect), we draw our pie chart using the Pie function. To properly center the caption, we define a rectangle that is as wide as the window and use DPtoLP to convert the client coordinates we obtained from GetClientRect to logical co-ordinates in our new mapping. We then use the ids_GetTextExtentPoint32 function to compute the height so that we have a rectangle we can use for DrawText.

The CreateDIBPatternBrush and CreateDIBPatternBrushPt functions create a logical brush that has the pattern specified by a device-independent bitmap (DIB). Normally, color bitmaps are device-specific. They contain assumptions about the representation of a color on the device (for example, the number of color planes or adjacent pixels), as well as what pixel value represents which color. A device-independent bitmap specification is a device-independent recipe for describing the colors and image in a color bitmap.

A logical brush created by the CreateDIBPatternBrush or CreateDIBPatternBrushPt functions can be subsequently selected into a device context for any device that supports raster operations. The DIB specification is translated into the device-specific bitmap that is actually used on the device. You create a pattern brush with this function as follows:

hbrush = CreateDIBPatternBrush (hPackedDIB, Usage) ;

hbrush = CreateDIBPatternBrushPt (lpPackedDIB, Usage) ;

The hPackedDIB parameter to CreateDIBPatternBrush specifies a handle to a global memory block containing a packed DIB. Global memory is largely a vestige of the old Windows memory management methods. More modern usage will tend to use ordinary memory pointers, and you are more likely, in Win32, to use the CreateDIBPatternBrushPt function, which takes an ordinary memory pointer to a packed DIB. The Usage parameter specifies whether the bmiColors[] array of the BITMAPINFO structure of the bitmap contains explicit RGB values or indices into the currently realized logical palette. Device-independent bitmaps will be covered in greater depth in the following section, "Creating and Using Bitmaps".

The final function that can be used to create a brush is the CreateBrushIndirect function. It works very much like the CreatePenIndirect function. You pass a pointer to a structure, and the function creates the type of brush indicated by information in the structure. You can create any of the previously mentioned -custom brushes with the CreateBrushIndirect function. The only parameter to the function is a far pointer to a LOGBRUSH (logical brush) structure. A typical function call is as follows:

HBRUSH hbrush ;

LOGBRUSH logbrush ;

/* Fill in LOGBRUSH structure. */

hbrush = CreateBrushIndirect (&logbrush) ;

The LOGBRUSH structure has three fields and defines the style, color, and hatch style of the logical brush to create. It has three corresponding fields and is defined as follows:

typedef struct tagLOGBRUSH {

UINT lbStyle ;

COLORREF lbColor ;

int lbHatch ;

} LOGBRUSH ;

You set the lbStyle field to indicate the type of brush you want the CreateBrushIndirect function to create. The possible values are listed in Table 6.7.

Table 6.7: Logical brush types for the CreateBrushIndirect function
lbStyle	lbColor	lbHatch
BS_DIBPATTERN	LOWORD (lbColor) con-tains either DIB_PAL_COLORS or DIB_RGB_COLORS	Handle to global memory containing a packed device-independent bitmap (DIB). Cast to a HANDLE before using in a handle context; cast to an int to store it.
BS_DIBPATTERNPT	LOWORD (lbColor) con-tains either DIB_PAL_COLORS or DIB_RGB_COLORS	Pointer to memory containing a packed device-independent bitmap (DIB). Cast to a pointer before us-ing in a pointer context; cast to an int to store it.
BS_HATCHED	Color of hatches.	Hatch style as shown in Figure 6.17.
BS_HOLLOW	Ignored.	Ignored.
BS_PATTERN	Ignored.	Handle to a bitmap.
BS_SOLID	Color of brush.	Ignored.

The GetObject function works on brushes just as it does on pens. When you call the GetObject function and pass the handle to a logical brush as its parameter, it retrieves a LOGBRUSH structure that describes the brush. A typical call to GetObject for a logical brush is

LOGBRUSH logbrush ;

GetObject (hbrush, sizeof (logbrush), (LPSTR) &logbrush) ;

Note that how you interpret the lbHatch field depends on the value in the lbStyle field. You must ex-plicitly cast the int value to a handle (for BS_SOLID or BS_DIBPATTERN styles) or a pointer (for the BS_PATTERN style) to use it to access the bitmap.

Now that you've seen how to create and use a brush, we need to fill a gap: how to create the bitmap that describes a custom brush's color and pattern. Any bitmap can be used when creating a brush. So we don't restrict the following discussion to bitmaps used only to create a brush; we look at bit-maps in general.

Creating and Using Bitmaps

A DIB is also a pattern of bits stored in memory. However, the bits for a pix-el in a DIB are not necessarily organized in the same manner as bits for a pixel on the eventual output device. They could be organized in the same fashion, but they do not need to be. Instead, the bit-map is organized in a fashion that best describes the encoded image. Doing this takes into account the number of colors used in the bitmap, the actual colors used, and the data redundancy in the bit-map (used when selecting a compressed bitmap format).

The format of a device-specific bitmap is known (by implication) from the device on which it is used. The format of a DIB is specified by an accompanying DIB specification. A DIB spec-i-fi-ca-tion describes the -following:

• The width and height of the bitmap
• The number of color planes
• The number of pix-els
• The type of data compression used for a compressed bitmap
• The horizontal and vertical res-o-lu-tion of the target device for which the bitmap was designed
• The number of colors actually used by the bitmap
• The number of colors considered important for displaying the bitmap To use a DIB on a device, the DIB first must be converted into a device-specific bit-map. GDI uses the DIB specification and the device capabilities to properly map pixel values in the DIB to the proper values in the device-specific bitmap.

  Either type of bitmap can be used for either monochrome or color bitmaps for any device. There are trade-offs, however, that make one type or the other a better choice in differing situations. Mono-chrome bitmaps are, by their very nature, device-independent. Because they always have a known color format, it's easiest to use the device-specific bitmap functions when creating a mono-chrome bitmap. In that way, you don't have to create a DIB specification that describes the monochrome bitmap.

  Color bitmaps are harder to create. If you're creating a color bitmap for a known device (such as a stock VGA), you can determine the color format of the device and create the bitmap accordingly. However, the bitmap won't take advantage of additional colors available on other devices, such as those supporting 24-bit color. So alternatively, you could create a blank bitmap for a specific device and draw the desired figure in it. This lets GDI worry about the details of the organization of the colors and bits. Often, though, you may want to create a bitmap ahead of time, and you would like it to look as good as possible on whatever display device Windows supports. This is a time to use a DIB.

  DIBs are quite important if you want portability. While for a long time the "stock VGA" was the most popular display card, today there are a variety of display interfaces. These are operating at resolutions anywhere from the traditional VGA resolution of 640 ¥ 480 to higher resolutions such as 1600 ¥ 1200 and in any mode from "16-color" to 24-bit (RGB), to 30-bit (10 R, 10 G, 10 B), to 32-bit (CMYK) color. The device-specific layouts are numerous. You should think of working in DIBs as much as possible, saving the device-specific bitmaps only for when you can get Windows to handle the device-dependent details for you.

  Copying a bitmap between two disparate devices requires the use of a DIB. You can copy a device-specific bitmap to a DIB, which encodes the image in a device-independent manner as described by the DIB specification. After you have the image in a DIB, you can copy it back to a different device, one that doesn't necessarily use the same pixel format as the original device's. DIBs are more efficient in many cases because the bitmap can be stored in a compressed format. For example, it may take longer to read an uncompressed bitmap from the disk than it does to read a compressed bitmap and uncompress it, depending on the speed of your processor and disk.

  We first look at the functions that operate on bitmaps. Then we look at creating various dev-ice-specific bitmaps. Next, we discuss the functions that use DIBs. Finally, we cover a few functions that do not fit anywhere else.

For example, the LineTo and Polygon functions will draw a line and a polygon on a bitmap when you specify a memory device context. Other functions listed in Table 6.8 are often used to draw into a bitmap. The BitBlt function copies a rectangular area from one device context to another. When the device contexts are memory device contexts, this function copies part of one bitmap to another. You can also use it to copy part of a device's display surface, such as the pixels in a window, to a memory device context and thus to the pixels of a bitmap. The StretchBlt function works similarly to the BitBlt function but can also stretch or compress the copied bitmap. We look at some of the other "Blt" functions in more detail (See, for example, the description of the PatBlt function on page 340, the StretchBlt function on page 351, the PlgBlt function on page 353, and the MaskBlt function on 357 ). You also can use the "BLT Explorer" to see how these functions operate. This Explorer is a component of the GDI Explorer that is included on the CD-ROM that accompanies this book.

Table 6.8: Functions that operate on bitmaps
Function	Description
BitBlt	Copies a rectangular area from a source device context to a destination device context.
CreateBitmap	Creates a device-specific memory bitmap. This function is sim-ilar to CreateDIBitmap.
CreateBitmapIndirect	Creates a device-specific memory bitmap from a description in a data structure.
CreateCompatibleBitmap	Creates a device-specific memory bitmap that is compatible with a specified device and that may be selected into a mem-ory device context associated with the device.
CreateDIBitmap	Creates a device-specific memory bitmap from a device-in-de-pendent bitmap (DIB) specification. The pixels in the bitmap can be initialized when created, if desired. This function is sim-ilar to CreateBitmap.
CreateDIBSection	Creates a device-independent bitmap that applications can write to -directly.
CreateDiscardableBitmap	Creates a discardable device-specific memory bitmap that is compatible with a specified device and that may be selected into a memory device context associated with the device.
ExtFloodFill	Fills an area of a display surface with the current brush. It can fill to a specified color boundary or fill an area that is a specified color.
FloodFill	Fills an area of a display surface with the current brush. It fills only to a specified color boundary.
GetBitmapBits	Retrieves the pixels from a specified bitmap. This function is similar to GetDIBits. It is present in Win32 for com-pat-i-bility with older Win16 that is being ported, but it is considered obsolete. You shouldn't use it for any new code.
GetBitmapDimensionEx	Retrieves the height and width of a bitmap by updating a SIZE -structure.
GetDIBits	Retrieves the pixels from a specified bitmap. This function is similar to GetBitmapBits, which it replaces in Win32 ap-pli-cations. It can also be used to retrieve bitmap dimensions.
GetPixel	Gets the RGB color value for a pixel.
LoadBitmap	Loads a bitmap from a resource file.
PatBlt	Sets the pixels of a bitmap to a pattern.
MaskBlt	Combines the color data for the source and destination using a bitmap mask and a pair of raster operations.
PlgBlt	Transfers a block of bits, optionally masking color bits, to a region delimited by a parallelogram. The mask is specified by a monochrome bitmap.
SetBitmapBits	Sets the pixels of a memory bitmap. This function is similar to SetDIBits. It is present in Win32 for compatibility with older Win16 code that is being ported, but it is considered ob-so-lete.
SetBitmapDimensionEx	Sets the height and width of a bitmap and, optionally, updates a SIZE structure with the previous height and width.
SetDIBits	Sets the pixels of a memory bitmap directly from a DIB.
SetDIBitsToDevice	Draws on a device surface directly from a DIB.
SetPixel	Sets a pixel to the specified COLORREF color or to the nearest matching color. Returns the actual color.
SetPixelV	Sets a pixel to the specified COLORREF color or to the nearest matching color.
StretchBlt	Copies a rectangular area from a source device context to a destination device context. The source bitmap is stretched or compressed, if necessary.
StretchDIBits	Copies a rectangular area of a DIB to a different rectangular area on the device associated with the destination device con-text. The source bitmap is stretched or compressed, if nec-es-sary.

Creating a Bitmap

When you create a device-specific bitmap, GDI actually allocates space for the bitmap and, if the bitmap is initialized, copies the initial values for the pixels to the bitmap. You receive a handle to the bitmap of type HBITMAP. You do not have direct access to the memory containing the pixels of the bitmap. A device-specific bitmap is a GDI object. GDI objects are automatically released when an application terminates. But it is generally cleaner to delete all bitmaps you create. In particular, because bitmaps can be quite large, if you fail to release them early your application will gradually consume more and more memory and bog down the system. As always, you must not delete a bitmap while it is currently selected into a memory device context.

There are several ways to create a bitmap:

1. Use external bitmap files. These files are created by a program such the Paint application included with Microsoft Windows or by a tool such as the bitmap resource editor, which is part of most development environments (such as the Visual C++ Workbench).

• You can add these external bitmap files to your program's resources by including them in your resource script (.rc file) and the resource compiler will copy them into your resource segment. You can then use the LoadBitmap or LoadImage function to load the bitmap resource and obtain a handle to it.
• You can open the bitmap file directly, read its bits into memory, and copy them to a blank bitmap (see the next section). 2. Create a blank bitmap and draw the appropriate pattern on it using any GDI drawing functions such as TextOut, LineTo, and Polygon.

  3. Create a blank bitmap and initialize its pixels to the image given by an array of bits.

  4. Create a blank bitmap and initialize its pixels by copying the image from a DIB. A device-independent bitmap is a DIB specification with an accompanying array of pixel values specifying the bitmap image. This can be a collection of bits you read in from a file.

  Each of these ways to create a bitmap are discussed next.

You also can create your own bitmap file. A bitmap file is a file containing binary data that consists of three sec-tions. The file begins with a BITMAPFILEHEADER structure, which looks like the following:

typedef struct tagBITMAPFILEHEADER {

WORD bfType;

DWORD bfSize;

WORD bfReserved1;

WORD bfReserved2;

DWORD bfOffBits;

} BITMAPFILEHEADER;

The bfType field identifies the file as a DIB file. It must have the value "BM" (for BitMap, of course). Remember that multibyte integer values are stored in byte-swapped order on Intel processors. You must swap the bytes in an assignment so that they will be in the correct order in memory:

BITMAPFILEHEADER bmfh ;

bmfh.bfType = 0x4D42 ; /* "MB" is swapped to "BM" in memory. */

The bfSize field specifies the size of the file in DWORDs. Both the bfReserved1 and bfReserved2 fields are reserved and must be set to 0. The bfOffBits field specifies the offset (in bytes) from the BITMAPFILEHEADER to the actual bitmap in the file.

Either a BITMAPINFO structure or a BITMAPCOREINFO structure must immediately follow the BITMAPFILEHEADER structure in the DIB file.

A BITMAPCOREINFO structure defines the dimensions of the bitmap and the colors used in an OS/2 Presentation Manager version 1.x DIB. If you are running in an environment in which OS/2 is used or in which you might be importing OS/2 files, you need to be prepared to handle one of these. Win-dows can use either Windows DIBs or Presentation Manager DIBs. You can tell the difference between the two by the value of the first field in each structure. Because we're talking about Windows, we discuss only the Windows BITMAPINFO structure.

A BITMAPINFO structure defines the dimensions and color of a Windows DIB. It has the following definition:

typedef struct tagBITMAPINFO {

BITMAPINFOHEADER bmiHeader;

RGBQUAD bmiColors[1];

} BITMAPINFO;

The bmiHeader field specifies a BITMAPINFOHEADER structure that contains information about the dimensions and color format of a DIB. The bmiColors field specifies an array of RGBQUAD data structures that define the colors in the bitmap. A BITMAPINFOHEADER has the following fields:

typedef struct tagBITMAPINFOHEADER{

DWORD biSize;

LONG biWidth;

LONG biHeight;

WORD biPlanes;

WORD biBitCount

DWORD biCompression;

DWORD biSizeImage;

LONG biXPelsPerMeter;

LONG biYPelsPerMeter;

DWORD biClrUsed;

DWORD biClrImportant;

} BITMAPINFOHEADER;

The fields of a BITMAPINFOHEADER are described in Table 6.9.

Table 6.9: The fields of a BITMAPINFOHEADER structure
Field	Description
biSize	Size of a BITMAPINFOHEADER structure, in bytes.
biWidth	Width of the bitmap, in pixels.
biHeight	Height of the bitmap, in pixels.
biPlanes	Number of planes for the target device. Must be 1.
biBitCount	Number of bits per pixel. Must be 1, 4, 8, or 24.
biCompression	Type of compression for a compressed bitmap. It can be one of the fol-lowing values:
	BI_RGB	Bitmap is not compressed.
	BI_RLE8	Bitmap is run-length encoded and has 8 bits per pixel.
	BI_RLE4	Bitmap is run-length encoded and has 4 bits per pixel.
biSizeImage	Size of the image in bytes.
biXPelsPerMeter	Horizontal resolution in pixels per meter of the target device for the bit-map. This is a suggested figure. You can use this number to locate a bit-map that best matches the device on which it will be used.
biYPelsPerMeter	Vertical resolution in pixels per meter of the target device for the bit-map. This is a suggested figure. You can use this number to locate a bitmap that best matches the device on which it will be used.
biClrUsed	Number of color indices in the color table actually used by the bitmap. When 0, the bitmap uses all the possible 2biBitCount color indices.
biClrImportant	Number of color indices in the color table that hold colors important when displaying the bitmap. When 0, all colors are important.

The biSizeImage, biXPelsPerMeter, and biYPelsPerMeter are advisory. Many applications, for example, set all three fields to 0 and may even also set biClrUsed and biClrImportant to 0.

The bmiColors field, which is an array of RGBQUAD structures, immediately follows the BITMAPINFOHEADER structure. Each element of the bmiColors array defines the color of a pixel whose value equals the index of the element. That is, the element bmiColors[0] contains the color for pixel values of 0, bmiColors[1] contains the color for pixel values of 1, and so on. You should arrange colors in the array in descending order of importance. When a DIB is converted to a device-specific bitmap for a device that supports fewer colors than are used in the DIB, Windows uses the colors listed at the beginning of the array. Pixels using later, unsupported colors are displayed in the nearest matching color.

The bmiColors array is defined to have one entry in order to establish the location of the beginning of the array. You must, however, provide room for one entry for each possible color. When the biBitCount field of the BITMAPINFOHEADER structure is set to 1, the bitmap is a monochrome bitmap, so the bmiColors field must contain two entries. (Have you ever noticed that monochrome really should be called bichrome?) Each bit in the bitmap represents a pixel and may be clear (0) or set (1). When the bit is clear, the pixel has the color of the first entry in the bmiColors array; when the bit is set, the pixel has the color of the second entry in the array. Notice that a monochrome bitmap is not restricted to simply black and white but can have any two colors: the color in bmiColors[0] and the color in bmiColors[1].

When the biBitCount field of the BITMAPINFOHEADER structure is set to 4, the bitmap contains pixels, each of which can have one of 16 colors. Therefore the bmiColors field can contain up to 16 entries. You need to allocate room only for the number of entries used by pixel values in the bitmap. For example, when you use only 12 different pixel values, set the biClrUsed parameter to 12 and allocate only 12 entries in the bmiColors array.

When the biBitCount field of the BITMAPINFOHEADER structure is set to 8, the bitmap contains pixels, each of which can have one of 256 colors. Therefore the bmiColors field can contain up to 256 entries. As before, you need to allocate space only for the entries actually used.

When the biBitCount field of the BITMAPINFOHEADER structure is set to 24, the bitmap contains pixels, each of which can have one of 16,777,216 colors. In this case, the bmiColors field is not used. The 24 bits for each pixel directly encode the red, green, and blue intensities.

Normally, you specify the colors in the bmiColors array as red, green, and blue intensities, each ranging from 0 to 255. Each RGBQUAD array element looks like the following. The rgbReserved field must be set to 0.

typedef struct tagRGBQUAD {

BYTE rgbBlue;

BYTE rgbGreen;

BYTE rgbRed;

BYTE rgbReserved;

} RGBQUAD;

A DIB uses a different coordinate system than a device-specific bitmap. A DIB uses a Cartesian first-quadrant coordinate system. The origin of the bitmap is the lower-left corner of the bitmap. Horizontal pixel coordinates increase from left to right and vertical pixel coordinates increase from bottom to top. A device-specific bitmap uses device coordinates. So its origin is the upper-left corner of the bitmap. Horizontal coordinates increase the same direction as a DIB (left to right), but vertical coordinates increase in the -opposite direction (top to bottom rather than bottom to top).

However, you also can allocate the bmiColors array as an array of WORDs rather than RGBQUAD structures. Each WORD entry represents an index into the currently selected and realized logical palette. When you use this format to specify the colors for a DIB, you must call the DIB functions with the Usage parameter set to DIB_PAL_COLORS. Typically, you don't use this format for a DIB stored in a file because the color palette may not have the proper colors when the DIB is next used.

The actual bitmap follows the BITMAPINFO structure. It does not have to be immediately contiguous because the location of the bitmap is specified by the bfOffBits parameter of the BITMAPFILEHEADER structure. The bits for each pixel are packed together.

The bitmap begins with the bottom row of pixels and at the left side. Each row must be a multiple of 4 bytes in length. The first pixel in a row of a monochrome bitmap is encoded in the most-significant bit of the first byte in the row. The first pixel in a row of a 16-color bitmap is encoded in the most-significant 4 bits of the first byte in the row. The first pixel in a row of a 256-color bitmap is encoded in all 8 bits of the first 3 bytes in the row (each pixel occupies 1 byte in this case). Twenty-four bits-per-pixel bitmaps use groups of 3 bytes for each pixel. The 3 bytes contain the red, green, and blue intensity values for the pixel.

As soon as you have a file containing a bitmap, you can add a BITMAPBITMAP resource statement to your application's resource script (.rc) file. You usually do this via whatever environment tool you are using. For example, in Visual C++ the act of creating a bitmap in the resource editor will include a reference to it in the resource script. If the bitmap was created by some external program, you need to generate a reference to it. The BITMAP statement associates a character-string identifier or an integer with the bitmap contained in the file. The resource compiler copies the bitmap from the bitmap file (typically, such a file uses the .bmp extension) into the compiled resource (.res) file. As the program is linked, the linker inserts the compiled resources into the executable (.exe) program file.

For example, suppose you've drawn a custom brush pattern using a bitmap editor application and saved it in a file called mybrush.bmp. If you use the built-in bitmap editor of your environment, the BITMAP statement will usually be inserted for you. If you import the file into your resource set, your environment tool will also add the BITMAP statement so that in your application's resource script file, you will find a BITMAP statement of the following form:

resID BITMAP filename

The resID field specifies either an integer value or a unique character string that identifies the resource. You use this value in your program to reference the bitmap. In the example proposed, let's use the following statement:

RoughTexture BITMAP mybrush.bmp

Be aware, however, that in looking at this statement you can't tell how to access the resource. For example, most environment tools will also create a definition

#define RoughTexture 17

so the effect is as if you had the resource:

17 BITMAP MYBRUSH.BMP

This is particularly important to understand how your environment resource tool handles this when you are creating a bitmap resource from an externally-created bitmap. If it creates a #define, you will need to use MAKEINTRESOURCE when you want to name the resource; if it doesn't create a #define, you will use the string name of the resource.

When you want to create a brush based on this pattern, you use the LoadBitmap or LoadImage function to load the bitmap from the executable file. You pass the function the instance handle of the module containing the desired bitmap and a parameter identifying the desired bitmap within that module. The function returns a handle to the created device-specific memory bitmap. In this example, you can load the bitmap one of two ways, depending on how you identified the bitmap on the BITMAP statement in the resource script file. You can load it either by name:

hbitmap = LoadBitmap (hInstance, _T("RoughTexture")) ;

or by integer identifier:

hbitmap = LoadBitmap (hInstance, MAKEINTRESOURCE (RoughTexture)) ;

It is critical that you use the correct form; the two are not interchangeable. Note that since you can't tell by looking at your .rc file which is the correct form, you have to either rely on your environment tool or read the appropriate .h file to determine which form to use. For example, in Visual C++ if you get a list of bitmaps or are displaying the bitmap in question, it will display the name as "RoughTexture" (quotes included) if you must use the string form and as RoughTexture (no quotes) if you must use the MAKEINTRESOURCE form. We point this out because it is a frequent source of problems, particularly for people either learning Windows for the first time or those moving to an integrated development environment such as those supported by Borland or Microsoft. The Visual C++ environment, if you are creating the bitmap with its built-in bitmap editor, will actually assign a name and create the #define. (It usually suggests a name starting with IDB_, a convention you may wish to maintain.) So you will find the following declarations in your files:

#define IDB_RoughTexture 17 // this is in RESOURCE.H

IDB_RoughTexture BITMAP filename // this is in your resource file

The LoadBitmap function will not load bitmaps using 256-color palettes. This is because Windows treats bitmaps loaded via LoadBitmap as 16-color bitmaps. To load bitmaps with higher resolution, you need to use the more general LoadResource call and extract the color information.

Once you have successfully done a LoadBitMap, you then can use the handle to the bitmap to create a logical brush that has that pattern by calling the CreatePatternBrush function:

hbrush = CreatePatternBrush (hbitmap) ;

Then you use this brush the way you use the others we've discussed. You select it into a device context, draw the filled object(s), select the default brush (or a stock brush) back into device context, and, finally, delete the brush and the bitmap:

hbrush = CreatePatternBrush (hbitmap) ;

DeleteBitmap (hbitmap) ;

SelectBrush (hdc, hbrush) ;

Rectangle (hdc, xUL, yUL, xLR, yLR) ;

SelectBrush (hdc, GetStockBrush (WHITE_BRUSH)) ;

DeleteBrush (brush) ;

As shown in this example, the bitmap can be deleted any time after you've used it to create the brush. You don't have to wait until the brush is deleted to delete the bitmap on which it's based.

Bitmaps are used for more than just brush patterns. An entire bitmap can be copied to a device surface as a complex picture or a large pattern, although somewhat indirectly. You create a compatible memory device con-text for the destination device, select the bitmap into the memory device context, and then copy the bitmap from the memory device context to the destination device context:

BITMAP bm ;

GetObject (hbitmap, sizeof (bm), (LPSTR) &bm) ;

hMemoryDC = CreateCompatibleDC (hdc, bm.bmWidth, bm.bmHeight) ;

SelectBitmap (hMemoryDC, hbitmap) ;

BitBlt (hdc, 0, 0, bm.bmWidth, bm.bmHeight,

hMemoryDC, 0, 0, SRCCOPY) ;

Creating and Drawing into a Blank Bitmap

HBITMAP CreateBitmap (int Width, int Height,

UINT Planes, UINT BitCount,

CONST VOID * lpBits) ;

HBITMAP CreateBitmapIndirect (CONST BITMAP * Bitmap) ;

HBITMAP CreateCompatibleBitmap (HDC hdc, int Width, int Height) ;

HBITMAP CreateDIBitmap (HDC hdc, CONST BITMAPINFOHEADER * lpInfoHeader,

DWORD Usage,

CONST VOID * lpInitBits,

CONST BITMAPINFO * lpInitInfo,

UINT Usage) ;

Those who know the Win16 API may notice that CreateDiscardableBitmap is missing from this set. This is because the concept of "discardable" storage was part of the Win16 memory management. Although the API call is retained in Win32, it is obsolete there and turns into a CreateCompatibleBitmap call.

Because all these functions return a device-specific bitmap, they must be provided with the format used by the device to represent colors and pixels. You specify this information explicitly when calling the CreateBitmap function. For a monochrome bitmap, this task is easy: Set both the Planes and BitCount parameters to 1. Setting the lpBits parameter to NULL specifies that the bitmap should not be initialized. A monochrome 8 ¥ 8 uninitialized bitmap used for a brush pattern can be created by the following:

hbitmap = CreateBitmap (8, 8, 1, 1, NULL) ;

The same approach can be used when calling the CreateBitmapIndirect function, but the information is passed via the fields of the BITMAP structure that is passed as the function parameter.

It's a bit more difficult to create a color bitmap using these two functions and still ensure that the bitmap is compatible with the desired device. You must get the device capabilities using the GetDeviceCaps function and create the bitmap accordingly. However, you can let Windows do the work by using either the CreateCompatibleBitmap or CreateDIBitmap functions.

You provide the handle of a device context to all three functions. Windows uses the handle to create a bitmap that has the same number of color planes and bits per pixel as the specified device.

The CreateCompatibleBitmap function is the function used most often to create an uninitialized color bitmap. It doesn't accept a parameter that specifies initialization data for the bitmap, and it creates the bitmap compatible with the specified device so that you don't have to worry about color planes and bits per pixel.

The CreateDIBitmap function also can be used to create an uninitialized bitmap, although it's much more useful when creating an initialized color bitmap, as you'll see later in the chapter. The following statements use the CreateDIBitmap function to create an uninitialized bitmap:

BITMAPINFOHEADER bmih ;

/* Initialize the BITMAPINFOHEADER here. */

hbitmap = CreateDIBitmap (hdc, &bmih, 0, NULL, NULL, 0) ;

After you have the handle to a device-specific bitmap, you can select it into a compatible memory device context using the SelectBitmap macro API function. Similar to the others you've seen, Windows defines it in windowsx.h this way:

#define SelectBitmap(hdc, hbm) \

((HBITMAP)SelectObject((hdc), (HGDIOBJ)(HBITMAP)(hbm)))

You can use the SelectBitmap macro in place of the SelectObject function to make your code more understandable:

SelectBitmap (hMemoryDC, hbitmap) ;

You can retrieve the current bitmap by using the GetCurrentObject function:

HBITMAP bm = (HBITMAP)GetCurrentObject(hdc, OBJ_BITMAP);

All drawing functions issued on the memory device context now draw on the newly created bitmap. It's important to note that uninitialized bitmaps are just that-completely uninitialized. In particular, the pixels in the bitmap aren't cleared to any value: 0, 1, white, or black. You'll probably want to start by clearing the entire bitmap to a known color. This is easiest done by using the PatBlt function. "PatBlt" stands for "Pattern Block transfer". The function call looks like this:

PatBlt (hdc, X, Y, Width, Height, Rop) ;

The PatBlt function creates a pattern on the specified device that is based on the selected brush and the pixels already on the device. When the specified device context refers to a memory device context, the pattern is applied to the selected bitmap. This function does not use a bounding rectangle to specify the area. Instead, the X and Y parameters specify one corner (in logical coordinates) of the rectangle that is to receive the pattern. The Width and Height parameters specify the width and height of the rectangle in logical units. Therefore the corner of the rectangle opposite the point (X, Y) is the point (X + Width, Y + Height).

The coordinates of any corner of the desired rectangle can be given as the X and Y parameters. The Width and Height parameters can be positive or negative. These all are logical values, and the mapping mode specifies the orientation of the axes. Therefore the upper-left corner of the rectangle can be at the point (X, Y) or (X + Width, Y) or (X, Y + Height) or (X + Width, Y + Height).

GDI determines the upper-left corner of the rectangle and copies the pattern to it. Like the area functions previously described, the top and left sides of the rectangle are included in the modified area. The right and bottom sides of the rectangle are outside the modified area.

GDI combines the colors of the pixels in the selected brush with the colors already present on the device according to a raster operation code that is similar, but not identical, to the raster operation code used when drawing lines. In general, raster operation codes describe the operation that should be applied to a source operand, a brush, and a destination operand. However, the Rop parameter to the PatBlt function cannot be an operation code that refers to a source operand. The valid operation codes for the PatBlt function that have common names are listed in Table 6.10. Any raster operation code that doesn't refer to a source operand, but only to a pattern and destination operand, can be used as the raster operation code for the PatBlt function. You must specify the ones that are not listed in Table 6.10 numerically.⁴ The hexadecimal values for all 16 PatBlt raster operation codes are give in Table 6.11.

Table 6.10: Raster operation codes for the PatBlt function
ROP Code	Result
PATCOPY	Copies the brush to the destination bitmap.
PATINVERT	Combines the brush and the destination bitmap using the Boolean Exclusive OR (XOR) operation.
DSTINVERT	Ignores the brush and inverts the destination bitmap using the Boolean bitwise NOT -operation.
BLACKNESS	Ignores the brush and sets the destination bitmap to all bits 0. This sets the bitmap to all-black. (Technically, a pixel value of 0 doesn't necessarily mean black.)
WHITENESS	Ignores the brush and sets the destination bitmap to all bits 1. This sets the bitmap to all-white. (Technically, a pixel value with all bits set to 1 doesn't necessarily mean white.)

Table 6.11: The Boolean operations performed by the raster operation codes usable by the PatBlt function
	Pattern(P)	1	1	0	0	Decimal Result	Boolean Operation	ROP Code
	Dest(D)	1	0	1	0
Name
BLACKNESS		0	0	0	0	0	D = 0	0x000042
-		0	0	0	1	1	D = ~(P | D)	0x0500A9
-		0	0	1	0	2	D = ~P & D	0x0A0329
-		0	0	1	1	3	D = ~P	0x0F0001
-		0	1	0	0	4	D = P & ~D	0x500325
DSTINVERT		0	1	0	1	5	D = ~D	0x550009
PATINVERT		0	1	1	0	6	D = P ^ D	0x5A0049
-		0	1	1	1	7	D = ~(P & D)	0x5F00E9
-		1	0	0	0	8	D = P & D	0xA000C9
-		1	0	0	1	9	D = ~(P ^ D)	0xA50065
-		1	0	1	0	10	D = D	0xAA0029
-		1	0	1	1	11	D = ~P | D	0xAF0229
PATCOPY		1	1	0	0	12	D = P	0xF00021
-		1	1	0	1	13	D = P | ~D	0xF50225
-		1	1	1	0	14	D = P | D	0xFA0089
WHITENESS		1	1	1	1	15	D = 1	0xFF0062

Finally, to stress the point again, bitmaps are GDI objects. You should delete them as soon as they are no longer needed, ideally before your application terminates.

Next we look at an example. We create an uninitialized 16 ¥ 32-pixel bitmap compatible with the display device, clear it to all-black, and draw a green X from corner to corner. The following code assumes that a common display context is retrieved by the GetDC function-particularly, that the MM_TEXT mapping mode is in effect:

HDC hdc ;

HDC hMemoryDC ;

HBITMAP hbitmap ;

HBITMAP hbitmapOrig ;

HPEN hpen ;

HPEN hpenOrig ;

hdc = GetDC (hwnd) ;

hMemoryDC = CreateCompatibleDC (hdc) ;

hbitmap = CreateCompatibleBitmap (hdc, 16, 32) ;

ReleaseDC (hwnd, hdc) ;

hbitmapOrig = SelectBitmap (hMemoryDC, hbitmap) ;

PatBlt (hMemoryDC, 0, 0, 16, 32, BLACKNESS) ;

hpen = CreatePen (PS_SOLID, 0, RGB (0, 255, 0)) ;

hpenOrig = SelectPen (hMemoryDC, hpen) ;

LineTo (hMemoryDC, 16, 32) ;

MoveToEx (hMemoryDC, 16, 0, NULL) ;

LineTo (hMemoryDC, 0, 32) ;

SelectBitmap (hMemoryDC, hbitmapOrig) ;

SelectPen (hMemoryDC, hpenOrig) ;

DeletePen (hpen) ;

DeleteDC (hMemoryDC) ;

/* Now you have the desired bitmap. */

/* When you no longer need the bitmap, delete it. */

DeleteBitmap (hbitmap) ;

Creating an Initialized Bitmap

The CreateDIBitmap function enables you to specify the initial values of a color bitmap in a device-independent manner. A DIB specification is used to convert the DIB to a device-specific bitmap.

First we'll discuss creating initialized device-dependent bitmaps, and then we'll look at creating color bitmaps using DIB specifications. Let's create an initialized monochrome bitmap similar to the X described above. Because we lack green, we'll make it a white X on a black 32 ¥ 32-pixel background. The CreateBitmap function call will look like the following:

BYTE Bits [] = { 0x80, 0x00, 0x00, 0x01, 0x40, 0x00, 0x00, 0x02,

0x20, 0x00, 0x00, 0x04, 0x10, 0x00, 0x00, 0x08,

0x08, 0x00, 0x00, 0x10, 0x04, 0x00, 0x00, 0x20,

0x02, 0x00, 0x00, 0x40, 0x01, 0x00, 0x00, 0x80,

0x00, 0x80, 0x01, 0x00, 0x00, 0x40, 0x02, 0x00,

0x00, 0x20, 0x04, 0x00, 0x00, 0x10, 0x08, 0x00,

0x00, 0x08, 0x10, 0x00, 0x00, 0x04, 0x20, 0x00,

0x00, 0x02, 0x40, 0x00, 0x00, 0x01, 0x80, 0x00,

0x00, 0x01, 0x80, 0x00, 0x00, 0x02, 0x40, 0x00,

0x00, 0x04, 0x20, 0x00, 0x00, 0x08, 0x10, 0x00,

0x00, 0x10, 0x08, 0x00, 0x00, 0x20, 0x04, 0x00,

0x00, 0x40, 0x02, 0x00, 0x00, 0x80, 0x01, 0x00,

0x01, 0x00, 0x00, 0x80, 0x02, 0x00, 0x00, 0x40,

0x04, 0x00, 0x00, 0x20, 0x08, 0x00, 0x00, 0x10,

0x10, 0x00, 0x00, 0x08, 0x20, 0x00, 0x00, 0x04,

0x40, 0x00, 0x00, 0x02, 0x80, 0x00, 0x00, 0x01 } ;

hbitmap = CreateBitmap (32, 32, 1, 1, Bits) ;

A couple of points aren't apparent from this example. Each scan line in the bitmap must be an even number of bytes long. Notice that this is different from a DIB. Each scan line in a DIB must be a multiple of 4 bytes in length. GDI assumes that a bitmap passed to the CreateBitmap function is composed of an array of short integer values. Scan lines are organized in a device-specific bitmap with the top line (line 0) at the beginning of the array, line 1 immediately following it, proceeding sequentially up to line Height-1. This, too, differs from a DIB. In a DIB, the bottom scan line comes first in the array, followed by the next line up, and so on. One bits represent white and 0 bits represent black. The left-most bit of a scan line is in the most significant bit of the first byte of data for the row.

You can set the bits of an already-created bitmap with the SetBitmapBits function. In this example, hbitmap is the handle of the bitmap whose bits you want to set and Count is a DWORD containing the number of bytes in the array pointed to by the lpBits parameter:

SetBitmapBits (hbitmap, Count, lpBits) ;

To set the X in a bitmap, we could do

SetBitmapBits (hbitmap, sizeof Bits, Bits) ;

We mentioned that each scan line of a device-specific bitmap must be an even number of bytes in length. Redefining the Bits array as an array of WORDs to ensure this necessity produces its own problems. For example, this bitmap isn't the same as the preceding one:

WORD Bits [] = { 0x8000, 0x0001,

0x4000, 0x0002,

0x2000, 0x0004,

0x1000, 0x0008,

.

.

.

The reason is that WORDs are stored in byte-swapped order on Intel processors. That is, the WORD 0x8000 is stored in memory as 0x00 followed by 0x80 in the next-higher memory location. We could, of course, swap the bytes in the definition of the constants (0x8000 to 0x0080), but then the pattern of the bitmap would become less obvious to those maintaining the source code.

You can use the CreateBitmapIndirect function to create the same bitmap with the following code. Notice the distinction between a BITMAP structure and an HBITMAP handle:

BITMAP bm ;

HBITMAP hbitmap ;

bm.bmType = 0 ;

bm.bmWidth = 32 ;

bm.bmHeight = 32 ;

bm.bmWidthBytes = 4 ;

bm.bmPlanes = 1 ;

bm.bmBitsPixel = 1 ;

bm.bmBits = (LPVOID) Bits ;

hbitmap = CreateBitmapIndirect (&bm) ;

A BITMAP is essentially a memory-based structure that contains some state information and a reference to the bits of the bitmap. However, Windows itself does not actually process this structure. Instead, it requires a copy of the bitmap description and the contents which is under its own control, and this copy is referenced by a bitmap handle, whose type is HBITMAP. Until you have converted a bitmap to a GDI object, Windows cannot do anything with it. Much of this is due to the original design of Windows for the 8088, in which memory management of the "virtual" memory was so critical. So, while Win32, in principle, should be able to reference a bitmap directly through the BITMAP structure, it in fact retains the same API and requires a bitmap handle.

Creating an Initialized Bitmap from a DIB

struct tagMonoDIBSpec {

BITMAPINFOHEADER I;

RGBQUAD Colors [2];

} mdib ;

mdib.ih.biSize = sizeof (mdib.ih) ;

mdib.ih.biWidth = 32 ;

mdib.ih.biHeight = 32 ;

mdib.ih.biPlanes = 1 ;

mdib.ih.biBitCount = 1 ;

mdib.ih.biCompression = 0 ;

mdib.ih.biSizeImage = 0 ;

mdib.ih.biXPelsPerMeter = 0 ;

mdib.ih.biYPelsPerMeter = 0 ;

mdib.ih.biClrUsed = 0;

mdib.ih.biClrImportant = 0 ;

mdib.Colors [0].rgbRed = 0 ; // Black (0, 0, 0)

mdib.Colors [0].rgbGreen = 0 ;

mdib.Colors [0].rgbBlue = 0 ;

mdib.Colors [1].rgbRed = 0xFF ; // White (255, 255, 255)

mdib.Colors [1].rgbGreen = 0xFF ;

mdib.Colors [1].rgbBlue = 0xFF ;

hdc = GetDC (hwnd) ;

hbitmap = CreateDIBitmap (hdc,

(LPBITMAPINFOHEADER) &mdib.ih,

CBM_INIT,

(LPVOID) Bits,

(LPBITMAPINFO) &mdib,

DIB_RGB_COLORS) ;

ReleaseDC (hwnd, hdc) ;

This last example requires some explanation. The BITMAPINFO structure mdib.ih specifies how the array of bits Bits is interpreted. It defines the array as a 32 ¥ 32-pixel array with each pixel being represented by 1 bit. One-bit pixels require two colors, so there are only two RGBQUAD entries. Each RGBQUAD entry contains the red, green, and blue intensities for a given pixel value. One advantage of this method is that you can change the bitmap to a green cross on a black background (like the one we created by drawing it) by simply changing the element in mdib.Colors[1] to green.

The process works as follows. Windows retrieves a number of bits from the Bits array based on the described bit planes and bits-per-pixel. It uses this pixel value to index into the RGBQUAD array, retrieving the color of the pixel in term of red, green, and blue intensities. This RGB color value is then converted to the device-specific pixel value that produces the equivalent color on the specified device. This process is a lot of work for a monochrome bitmap, but it is invaluable when dealing with color bitmaps.

We also cheated a little in the preceding example. The origin of a device-specific bitmap is the upper-left corner of the bitmap. The origin of a device-independent bitmap is the lower-left corner. This means you need to define the array of bytes starting with the bottom row of pixels rather than the top row when creating a device-independent bitmap. We used a symmetrical figure so that we didn't have to account for that difference. You also can define the bitmap data for a device-independent bitmap in a run-length-encoded (RLE) form to save space.

You also can use the SetDIBits function to copy a device-independent bitmap into a bitmap of your choice. It looks like this:

int SetDIBits (HDC hdc, HBITMAP hbitmap, UINT StartScan, UINT NumScans,

CONST VOID * lpBits,

CONST BITMAPINFO * lpBitsInfo,

UINT ColorUsage) ;

The parameter StartScan specifies the scan line number of the first row of pixels in the device-independent bitmap pointed to by lpBits. The NumScans parameter specifies how many scan lines are in the lpBits buffer. All NumScans scan lines are copied from the device-independent bitmap, converted to device-specific pixel values as described before, and stored into the bitmap identified by hbitmap. The lpBitsInfo parameter points to a BITMAPINFO structure that defines the format of the bits in the device-independent bitmap. The ColorUsage parameter specifies whether the colors in the RGBQUAD array entries are literal RGB values (as we used before) or 16-bit indices into the current realized logical palette.

Similarly, you can retrieve the pixels from a device-specific bitmap, convert them to a specified device-independent representation, and store the device-independent bitmap into a specified buffer. This is the purpose of the GetDIBits function:

int GetDIBits (HDC hdc, HBITMAP hbitmap,

UINT StartScan, UINT NumScans,

LPVOID * lpBits,

LPBITMAPINFO lpBitsInfo,

UINT ColorUsage) ;

There is another use of GetDIBits, which is obtaining the parameters of a bitmap given its handle. This is particularly useful for obtaining the dimensions of a bitmap loaded with the LoadBitmap function. This is discussed on page 337.

You can skip a step and write a DIB directly to the surface of a device using the SetDIBitsToDevice function. There is no function to copy a device-specific bitmap directly to a device surface. A device-specific bitmap must be selected into a compatible memory device context, and then the BitBlt function can copy all or part of the memory device context surface to the device surface. The SetDIBitsToDevice function looks like this:

int SetDIBitsToDevice (HDC hdc, int xDest, int yDest,

DWORD Width, DWORD Height,

int xSrc, int ySrc,

UINT StartScan, UINT NumScans,

CONST VOID * lpBits,

CONST BITMAPINFO lpBitsInfo,

UINT ColorUsage) ;

The hdc parameter identifies the destination device. The xSrc, ySrc, Width, and Height parameters describe a rectangular area in the source DIB. The xSrc and ySrc parameters are in device coordinates; Width and Height are in device units. Windows translates the device-independent pixel values to the appropriate device-dependent pixel values and copies the source rectangle to the destination-device surface. The rectangle is placed on device surface at the logical coordinates (xDest, yDest).

DIBs can be very large. You can reduce the amount of memory they require by keeping only a portion of the bitmap in memory at any given time. The StartScan and NumScans parameters identify the portion of the DIB that presently is in memory. The StartScan parameter identifies the number of the scan line located at the beginning of the bitmap in memory, that is, the scan line number of the first row of pixels pointed to by the lpBits parameter. The NumScans parameter specifies how many scan lines are in memory. To write a large bitmap to a device surface a small section at a time, you can repeatedly load a portion of a DIB into memory and call the SetDIBitsToDevice function with the StartScan and NumScans parameters set appropriately.

In Win16, it was sometimes necessary to use these techniques because it was not always possible to fit in memory at once all of a DIB or several DIBs requiring simultaneous access. In Win32, this is a far less important issue because the underlying paging system can handle the swapping. However, for very large images you might find yourself straining even Win32's available paging space. Or you may have a program so large that it is "thrashing" its own memory, that is, causing page faults and a page swap operation so often that the paging time dominates the execution time. Also, the time required to initially read in a very large DIB might be significant, particularly if only a small portion can be viewed at any one time. For example, you might be able to read in a "window's worth" of an image in a few seconds, but reading in the entire image might take minutes. When such performance bottlenecks arise, you might find it advantageous to consider using partial-DIB management. You also can take advantage of multithreading to bring in pieces of a bitmap "in the background". In this way, the user can begin to work on or see the pieces already present. We discuss multithreading in Chapter 18.

The lpBitsInfo parameter points to a BITMAPINFO structure that defines the format of the DIB. The Usage parameter is either DIB_RGB_COLORS or DIB_PAL_COLORS. The first indicates that colors are specified by RGB color values. The second indicates that colors are specified by indices into the currently realized color palette.

Finally, there is the CreateDIBSection function. This creates a DIB that an application can write to directly. We document this function here because the documentation in the Win32 API reference (at least in the editions we have) is incomplete and, in fact, incorrect.

HBITMAP CreateDIBSection( HDC hdc, CONST BITMAPINFO * pbitmap,

UINT usage, VOID ** ppbits,

HANDLE hSection, DWORD offset);

The hdc is a handle to a device context. If the usage parameter is DIB_PAL_COLORS, the logical palette of this device context is used to initialize the DIB's colors. The pbitmap reference is a pointer to a BITMAPINFO structure that specifies the DIB, including its dimensions and colors. The ppbits parameter (which does not appear in some versions of the Win32 documentation) is a pointer to a variable that receives a pointer to the bitmap's bits. The hSection value is optional and can be NULL. If it is not NULL, it must be a handle to a "mapping object" obtained from the CreateFileMapping function. The bitmap's bits will be located at offset bytes into the mapping object. You will be able to retrieve this handle by calling GetObject on the bitmap handle:

DIBSECTION as;

HANDLE section;

GetObject(hbitmap, sizeof DIBSECTION, &ds);

section = ds.dshSection;

If the hSection parameter is NULL, the system will allocate memory for the DIB and the offset parameter will be ignored. You will not be able to retrieve this handle using the above code; the ds.dshSection member will be NULL. The DIBSECTION structure, which is not otherwise documented in the Win32 reference, is

typedef struct tagDIBSECTION {

BITMAP dsBM;

BITMAPINFOHEADER dsBmih;

DWORD dsBitFields[3];

HANDLE dshSection;

DWORD dsOffset;

} DIBSECTION;

If you specify the hSection value when you create the DIB section, the offset parameter must be a multiple of sizeof(DWORD), since the bits will be aligned on double-word boundaries. This offset value will appear as the dsOffset field in the DIBSECTION. If the hSection value is NULL on creation, the dshSection value of the DIBSECTION will be NULL and the dsOffset value will have no meaning. If this function succeeds, it returns a handle to the newly-created bitmap; if it fails, it returns NULL.

If hSection is NULL, the system will free up the allocated storage when you call DeleteObject on the bitmap. If hSection is not NULL, you must close the hSection memory handle after calling DeleteObject.

For Windows NT, you have to guarantee that the GDI subsystem has completed drawing to the bitmap. You must call GdiFlush before accessing the bits of the bitmap via the pointer that was returned via the ppbits parameter.

One of the major useful purposes of the DIBSECTION is that it allows you to perform bitmap operations very quickly, primarily to expedite animation effects.

The BitBlt, StretchBlt, and StretchDIBits Functions

Like the PatBlt function you saw earlier, these functions can do much more than simply copy bits from here to there. Technically, the BitBlt function provides a superset of the functionality of the PatBlt function. The StretchBlt function provides a superset of the functionality of the BitBlt function. The StretchDIBits function provides the same functionality as the StretchBlt function, but it does it on DIBs. In the next section, we discuss even more sophisticated Blt-class instructions: PlgBlt and MaskBlt.

The basic form of the BitBlt function call is

BOOL BitBlt (HDC hDestDC, int X, int Y, int Width, int Height,

HDC hSrcDC, int xSrc, int ySrc, DWORD Rop) ;

As you can see, this looks much like the PatBlt function discussed earlier in the chapter. The hDestDC parameter specifies the destination device context for the transfer. The X, Y, Width, and Height parameters are logical coordinates of one corner of a rectangle and the extent of the rectangle, horizontally and vertically. As with the PatBlt function, this information specifies two opposite corners of a rectangle. GDI uses this information and the mapping mode to determine the upper-left corner of the rectangle. It includes the top and left sides in the modified area. The bottom and right sides are not included in the default (GM_COMPATIBLE) mode but are included in the extended (GM_ADVANCED) mode.

The PatBlt function used two operands in the transfer: a brush (or pattern) and a rectangular area of pixels on the surface of a destination device context. The BitBlt function uses the same two parameters and adds a third: a rectangular area of pixels on the surface of a source device context. The hSrcDC parameter specifies the source device context. One of the source rectangle is at the (source device context) logical coordinate (xSrc, ySrc). The Width and Height parameters specify the logical width and height of the source rectangle, which has the same size as the destination rectangle.

The final parameter, Rop, specifies the raster operation code for the transfer. A raster operation code for the BitBlt and StretchBlt functions indicates the Boolean operation to use when combining a source bitmap, a pattern bitmap, and a destination bitmap. There are 256 raster operation codes.

A raster operation code (ROP) is a 32-bit value. The high-order 16-bits of the code identifies the Boolean operation and is a 0-extended, 8-bit value that ranges from 0 to 255. The low-order word is a bit-encoded operation code used by the device driver in executing the requested function. Only 15 of the 256 possible ternary raster operation codes have symbolic names defined in windows.h. We gave their symbolic names in Table 6.12, along with the Boolean operation they represent and the hexadecimal ROP code value. You can specify the other ROP values numerically. Or you can use the extrops.h header file-supplied with the GDI Explorer-which assigns names to all 256 ROP codes. You can also use the BLT Explorer component of the GDI Explorer to experiment with the entire set of ROP codes (although some are rather boring; for -example, ROP code 0x00AA0029, which copies the destination pixel to the destination, ignoring both the source and the brush pattern).

Table 6.12: The 15 ternary ROP codes with their symbolic names
		Pixel Values
	Pattern (P)	1	1	1	1	0	0	0	0
	Source (S)	1	1	0	0	1	1	0	0	Boolean Operation	ROP Code
	Dest(D)	1	0	1	0	1	0	1	0
Name
BLACKNESS		0	0	0	0	0	0	0	0	0	0x000042
NOTSRCERASE		0	0	0	1	0	0	0	1	~(S | D)	0x1100A6
NOTSRCCOPY		0	0	1	1	0	0	1	1	~S	0x330008
SRCERASE		0	1	0	0	0	1	0	0	S & ~D	0x440328
DSTINVERT		0	1	0	1	0	1	0	1	~D	0x550009
PATINVERT		0	1	0	1	1	0	1	0	P ^ D	0x5A0049
SRCINVERT		0	1	1	0	0	1	1	0	S ^ D	0x660046
SRCAND		1	0	0	0	1	0	0	0	S & D	0x8800C6
MERGEPAINT		1	0	1	1	1	0	1	1	~S | D	0xBB0226
MERGECOPY		1	1	0	0	0	0	0	0	P & S	0xC000CA
SRCCOPY		1	1	0	0	1	1	0	0	S	0xCC0020
SRCPAINT		1	1	1	0	1	1	1	0	S | D	0xEE0086
PATCOPY		1	1	1	1	0	0	0	0	P	0xF00021
PATPAINT		1	1	1	1	1	0	1	1	P | ~S | D	0xFB0A09
WHITENESS		1	1	1	1	1	1	1	1	1	0xFF0062