StrBlt

The StrBlt function writes text strings by converting characters in a specified string into raster, vector, or outline glyphs and copying the glyphs to the specified device or bitmap. Depending on the value of its parameters, StrBlt also computes the x and y extents of the bounding rectangle of the displayed string and clips the text to fit a given clipping rectangle. GDI may call StrBlt if an application calls the TextOut function (GDI.33), the ExtTextOut function (GDI.351), or the GetTextExtent function (GDI.91).

The StrBlt function has been superseded by the ExtTextOut function. A graphics device driver must export the StrBlt function only if the RC_GDI20_OUTPUT value is not set in the dpRaster member of the driver's GDIINFO structure or only if the driver is intended to be installed under Windows version 1.x.

Parameters

lpDestDev

Points to a PDEVICE or PBITMAP structure specifying the device or bitmap to receive the text output.

wDestXOrg

Specifies the x-coordinate (in device units) of the starting point for the string.

wDestYOrg

Specifies the y-coordinate (in device units) of the starting point for the string.

lpClipRect

Points to a RECT structure specifying the clipping rectangle.

lpString

Points to a null-terminated character string specifying the characters to display.

wCount

Specifies what action the function is to take as well as the number of characters in the string. If the wCount parameter is positive, the function draws the characters in the string using the current font, text justification, escapement, rotation,

applying the clipping rectangle, and other factors. If the function modifies the BreakErr member specified by the lpDrawMode parameter, it must restore the member to its original value.

If wCount is negative, the function computes the x and y extents of the smallest rectangle that completely encloses the displayed string, but does not generate output. In this case, the absolute value of wCount specifies the number of characters in the string. The function uses the current font, text justification, and other factors to compute the bounding rectangle, but does not apply the clipping rectangle. The function updates the BreakErr member specified by lpDrawMode.

lpFontInfo

Points to a FONTINFO structure specifying the physical font to use.

lpDrawMode

Points to a DRAWMODE structure specifying the current text color, background mode, background color, text justification, and character spacing.

lpTextXForm

Points to a TEXTXFORM structure specifying additional information about the appearance of the characters when drawn.

Return Value

The return values are the x and y extents of the string's bounding rectangle; the x extent is in the low-order 16 bits and the y extent in the high-order 16 bits. If the x extent exceeds the maximum value for an extent (0x7FFF), the function returns 0x7FFF in the low-order 16 bits and the value of the wDestXorg parameter in the high-order 16 bits. The function returns 0x80000000 if error occurred or no output was generated.

Comments

The export ordinal for this function is 11.

To ensure backward compatibility, many graphics device drivers provide both StrBlt and ExtTextOut functions. In such cases, the StrBlt function does nothing more than call ExtTextOut as in the following example:

DWORD StrBlt(lpDestDev, wDestXOrg, wDestYOrg, lpClipRect,

lpString, wCount, lpFontInfo, lpDrawMode, lpTextXForm)

LPPDEVICE lpDestDev;

WORD wDestXOrg;

WORD wDestYOrg;

LPRECT lpClipRect;

LPSZ lpString;

int wCount;

LPFONTINFO lpFontInfo;

LPDRAWMODE lpDrawMode;

LPTEXTXFORM lpTextXForm;

{

return ExtTextOut(lpDestDev, wDestXOrg, wDestYOrg, lpClipRect,

lpString, wCount, lpFontInfo, lpDrawMode,

lpTextXForm, (LPSHORT)NULL, (LPRECT)NULL, 0);

}

See Also

ExtTextOut