GetGlyphOutline

3.1

  DWORD GetGlyphOutline(hdc, uChar, fuFormat, lpgm, cbBuffer, lpBuffer, lpmat2)    
  HDC hdc; /* handle of device context */
  UINT uChar; /* character to query, */  
  UINT fuFormat; /* format of data to return */
  LPGLYPHMETRICS lpgm; /* address of structure with glyph metrics */
  DWORD cbBuffer; /* size of buffer for data */
  void FAR* lpBuffer; /* address of buffer for outline data */
  LPMAT2 lpmat2; /* address of structure with transform matrix */

The GetGlyphOutline function retrieves the outline curve or bitmap for an outline character in the current font.

Parameters

hdc

Identifies the device context.

uChar

Specifies the character for which information is to be returned.

fuFormat

Specifies the format in which the function is to return information. It can be one of the following values:

Value Meaning

GGO_BITMAP Returns the glyph bitmap. When the function returns, the buffer pointed to by the lpBuffer parameter contains a 1-bit-per-pixel bitmap whose rows start on doubleword boundaries.
GGO_NATIVE Returns the curve data points in the rasterizer's native format, using device units. When this value is specified, any transformation specified in the lpmat2 parameter is ignored.

When the value of this parameter is zero, the function fills in a GLYPHMETRICS structure but does not return glyph-outline data.

lpgm

Points to a GLYPHMETRICS structure that describes the placement of the glyph in the character cell. The GLYPHMETRICS structure has the following form:

typedef struct tagGLYPHMETRICS {  /* gm */
    UINT  gmBlackBoxX;
    UINT  gmBlackBoxY;
    POINT gmptGlyphOrigin;
    int   gmCellIncX;
    int   gmCellIncY;
} GLYPHMETRICS;

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

cbBuffer

Specifies the size of the buffer into which the function copies information about the outline character. If this value is zero and the fuFormat parameter is either the GGO_BITMAP or GGO_NATIVE values, the function returns the required size of the buffer.

lpBuffer

Points to a buffer into which the function copies information about the outline character. If the fuFormat parameter specifies the GGO_NATIVE value, the information is copied in the form of TTPOLYGONHEADER and TTPOLYCURVE structures. If this value is NULL and the fuFormat parameter is either the GGO_BITMAP or GGO_NATIVE value, the function returns the required size of the buffer.

lpmat2

Points to a MAT2 structure that contains a transformation matrix for the character. This parameter cannot be NULL, even when the GGO_NATIVE value is specified for the fuFormat parameter. The MAT2 structure has the following form:

typedef struct tagMAT2 {  /* mat2 */
    FIXED eM11;
    FIXED eM12;
    FIXED eM21;
    FIXED eM22;
} MAT2;

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

Return Value

The return value is the size, in bytes, of the buffer required for the retrieved information if the cbBuffer parameter is zero or the lpBuffer parameter is NULL. Otherwise, it is a positive value if the function is successful, or –1 if there is an error.

Comments

An application can rotate characters retrieved in bitmap format by specifying a 2-by-2 transformation matrix in the structure pointed to by the lpmat2 parameter.

A glyph outline is returned as a series of contours. Each contour is defined by a TTPOLYGONHEADER structure followed by as many TTPOLYCURVE structures as are required to describe it. All points are returned as POINTFX structures and represent absolute positions, not relative moves. The starting point given by the pfxStart member of the TTPOLYGONHEADER structure is the point at which the outline for a contour begins. The TTPOLYCURVE structures that follow can be either polyline records or spline records. Polyline records are a series of points; lines drawn between the points describe the outline of the character. Spline records represent the quadratic curves used by TrueType (that is, quadratic b-splines).

For example, the GetGlyphOutline function retrieves the following information about the lowercase “i” in the Arial TrueType font:

dwrc = 88                     /* total size of native buffer     */

TTPOLYGONHEADER #1            /* contour for dot on i            */
  cb     = 44                 /* size for contour                */
  dwType = 24                 /* TT_POLYGON_TYPE                 */
  pfxStart = 1.000, 11.000

  TTPOLYCURVE #1
    wType  = TT_PRIM_LINE
    cpfx   = 3
    pfx[0] = 1.000, 12.000
    pfx[1] = 2.000, 12.000
    pfx[2] = 2.000, 11.000    /* automatically close to pfxStart */

TTPOLYGONHEADER #2            /* contour for body of i           */
  cb     = 44
  dwType = 24                 /* TT_POLYGON_TYPE                 */
  pfxStart = 1.000, 0.000

  TTPOLYCURVE #1
    wType  = TT_PRIM_LINE
    cpfx   = 3
    pfx[0] = 1.000, 9.000
    pfx[1] = 2.000, 9.000
    pfx[2] = 2.000, 0.000     /* automatically close to pfxStart */

See Also

GetOutlineTextMetrics