ScriptPositionSingleGlyph function (usp10.h)

Positions a single glyph with a single adjustment using a specified feature provided in the font for OpenType processing. Most often, applications use this function to align a glyph optically at the beginning or end of a line.

Syntax

HRESULT ScriptPositionSingleGlyph(
  [in, optional] HDC             hdc,
  [in, out]      SCRIPT_CACHE    *psc,
  [in, optional] SCRIPT_ANALYSIS *psa,
  [in]           OPENTYPE_TAG    tagScript,
  [in]           OPENTYPE_TAG    tagLangSys,
  [in]           OPENTYPE_TAG    tagFeature,
  [in]           LONG            lParameter,
  [in]           WORD            wGlyphId,
  [in]           int             iAdvance,
  [in]           GOFFSET         GOffset,
  [out]          int             *piOutAdvance,
  [out]          GOFFSET         *pOutGoffset
);

Parameters

[in, optional] hdc

Handle to the device context. For more information, see Caching.

[in, out] psc

Pointer to a SCRIPT_CACHE structure identifying the script cache.

[in, optional] psa

Pointer to a SCRIPT_ANALYSIS structure obtained from a previous call to ScriptItemizeOpenType. This structure identifies the shaping engine, so that the advance widths can be retrieved.

Alternatively, the application can set this parameter to NULL to retrieve unfiltered results.

[in] tagScript

An OPENTYPE_TAG structure defining the script tag for shaping.

[in] tagLangSys

An OPENTYPE_TAG structure defining the language tag for shaping.

[in] tagFeature

An OPENTYPE_TAG structure defining the feature tag to use for shaping the alternate glyph.

[in] lParameter

A flag specifying if single substitution should be applied to the identifier specified in wGlyphId. The application sets this parameter to 1 to apply the single substitution feature to the identifier. The application sets the parameter to 0 if the function should not apply the feature.

[in] wGlyphId

The identifier of the original glyph being shaped.

[in] iAdvance

The original glyph advance width.

[in] GOffset

The original glyph offset. Typically, this value is an output of ScriptPlaceOpenType or ScriptPlace.

[out] piOutAdvance

Pointer to the location in which this function retrieves the new advance width adjusted for the alternate glyph.

[out] pOutGoffset

Pointer to the location in which this function retrieves the new glyph offset adjusted for the alternate glyph.

Return value

Returns 0 if successful. The function returns a nonzero HRESULT value if it does not succeed. The application can test the return value with the SUCCEEDED and FAILED macros.

Remarks

This function positions an individual glyph by adjusting the advance width and/or the offset of the given glyph. The function assumes that the font requires only one adjustment.

A typical use of this function is the slight adjustment of the margin to account for the visual impression made by certain characters. In Latin script, for example, at the beginning of a line it is common to make a slight adjustment to the left for an initial capital (such as "T" or "O") that does not have a vertical line on the left part of the glyph. Although doing this breaks the strict linear margin, the eye perceives the margin as more even.

The following examples demonstrate this effect. The first example shows strict alignment; the next two examples show an adjustment of the initial "T" to the left. The adjustments are by one pixel and two pixels, respectively. The magnified images to the right show how the "T" pushes slightly farther into the left margin in each successive case.

Requirements

See also

Caching

OPENTYPE_TAG

SCRIPT_ANALYSIS

SCRIPT_CACHE

ScriptItemizeOpenType

Uniscribe

Uniscribe Functions