GetGlyphOutline
The GetGlyphOutline
function retrieves the outline or bitmap for a character in the TrueType font
that is selected into the specified device context.
DWORD GetGlyphOutline(
|
HDC hdc, |
// handle of device
context |
|
UINT uChar, |
// character to
query |
|
UINT uFormat, |
// format of data
to return |
|
LPGLYPHMETRICS lpgm, |
// address of
structure for metrics |
|
DWORD cbBuffer, |
// size of buffer
for data |
|
LPVOID lpvBuffer, |
// address of
buffer for data |
|
CONST MAT2 *lpmat2 |
// address of
transformation matrix structure |
|
); |
|
Parameters
hdc
Identifies
the device context.
uChar
Specifies the
character for which data is to be returned.
uFormat
Specifies the
format of the data that the function retrieves. Use one of the following
values:
|
Value |
Meaning |
|
GGO_BITMAP |
The
function retrieves the glyph bitmap. For information about memory allocation,
see the following Remarks section. |
|
GGO_NATIVE |
The
function retrieves the curve data points in the rasterizer s native format
and uses the font s design units. When this value is specified, any
transformation specified in the lpMatrix parameter is ignored. |
|
GGO_METRICS |
The function
only retrieves the GLYPHMETRICS structure specified by lpgm. The
other buffers are ignored. This value affects the meaning of the function s
return value upon failure; see the following Return Value section. |
|
GGO_GRAY2_BITMAP |
The
function retrieves a glyph bitmap that contains 5 levels of gray. |
|
GGO_GRAY4_BITMAP |
The
function retrieves a glyph bitmap that contains 17 levels of gray. |
|
GGO_GRAY8_BITMAP |
The
function retrieves a glyph bitmap that contains 65 levels of gray. |
Note that,
for the GGO_GRAYn_BITMAP values, the function retrieves a glyph bitmap that
contains n^2+1 (n squared plus one) levels of gray.
lpgm
Points to the
GLYPHMETRICS
structure describing the placement of the glyph in the character cell.
cbBuffer
Specifies the
size of the buffer where the function is to copy information about the outline
character. If this value is zero, the function returns the required size of the
buffer.
lpvBuffer
Points to the
buffer where the function is to copy information about the outline character.
If this value is NULL, the function returns the required size of the buffer.
lpmat2
Points to a MAT2 structure specifying a
transformation matrix for the character.
Return Values
If
GGO_BITMAP, GGO_GRAY2_BITMAP, GGO_GRAY4_BITMAP, GGO_GRAY8_BITMAP, or GGO_NATIVE
is specified and the function succeeds, the return value is greater than zero;
otherwise, the return value is GDI_ERROR. If one of these flags is specified
and the buffer size or address is zero, the return value specifies the required
buffer size, in bytes.
If
GGO_METRICS is specified and the function fails, the return value is GDI_ERROR.
Remarks
The glyph
outline returned by the GetGlyphOutline function is for a grid-fitted
glyph. (A grid-fitted glyph is a glyph that has been modified so that its
bitmapped image conforms as closely as possible to the original design of the
glyph.) If an application needs an unmodified glyph outline, it can request the
glyph outline for a character in a font whose size is equal to the font s em unit.
The value for a font s em unit is stored in the otmEMSquare member of
the OUTLINETEXTMETRIC structure.
The glyph
bitmap returned by GetGlyphOutline when GGO_BITMAP is specified is a
doubleword-aligned, row-oriented, monochrome bitmap. When GGO_GRAY2_BITMAP is
specified, the bitmap returned is a doubleword-aligned, row-oriented array of
bytes whose values range from 0 to 4. When GGO_GRAY4_BITMAP is specified, the
bitmap returned is a doubleword-aligned, row-oriented array of bytes whose
values range from 0 to 16. When GGO_GRAY8_BITMAP is specified, the bitmap
returned is a doubleword-aligned, row-oriented array of bytes whose values
range from 0 to 255.
An
application can rotate characters retrieved in bitmap format by specifying a
2-by-2 transformation matrix in the lpMatrix parameter.
See Also