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.

Illustration showing the same block of text three times, with enlargements of each showing slightly different alignment
Important  Starting with Windows 8: To maintain the ability to run on Windows 7, a module that uses Uniscribe must specify Usp10.lib before gdi32.lib in its library list.
 

Requirements

   
Minimum supported client Windows Vista [desktop apps only]
Minimum supported server Windows Server 2008 [desktop apps only]
Target Platform Windows
Header usp10.h
Library Usp10.lib
DLL Usp10.dll
Redistributable Usp10.dll version 1.600 or greater on Windows XP

See also

Caching

OPENTYPE_TAG

SCRIPT_ANALYSIS

SCRIPT_CACHE

ScriptItemizeOpenType

Uniscribe

Uniscribe Functions