ScriptGetFontAlternateGlyphs function (usp10.h)

Article
10/13/2021

Retrieves a list of alternate glyphs for a specified character that can be accessed through a specified OpenType feature.

Syntax

HRESULT ScriptGetFontAlternateGlyphs(
  [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]           WORD            wGlyphId,
  [in]           int             cMaxAlternates,
  [out]          WORD            *pAlternateGlyphs,
  [out]          int             *pcAlternates
);

Parameters

[in, optional] hdc

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

[in, out] psc

Pointer to a SCRIPT_CACHE structure defining the script cache.

[in, optional] psa

Pointer to a SCRIPT_ANALYSIS structure obtained from a previous call to ScriptItemizeOpenType. This parameter identifies the shaping engine, so that the array of alternate glyphs can be created with the correct scope.

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

[in] tagScript

An OPENTYPE_TAG structure defining the script tag associated with alternate glyphs.

[in] tagLangSys

An OPENTYPE_TAG structure defining the language tag associated with alternate glyphs.

[in] tagFeature

An OPENTYPE_TAG structure defining the feature tag associated with alternate glyphs.

[in] wGlyphId

The identifier of the original glyph mapped from the character map table.

[in] cMaxAlternates

Length of the array specified by pAlternateGlyphs.

[out] pAlternateGlyphs

Pointer to buffer in which this function retrieves an array of glyph identifiers. The array includes the original glyph, followed by alternate glyphs. The first element is always the original glyph. Alternate forms are identified by an index into the array. The index is a value greater than one and less than the value of pcAlternates.

When the user chooses an alternate form from the user interface, the alternate glyph is applied to the corresponding character and the rendering is reformatted.

[out] pcAlternates

Pointer to the number of elements in the array specified by pAlternateGlyphs.

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.

If the number of alternate glyphs exceeds the value of cMaxAlternates, the function fails with E_OUTOFMEMORY. The application can try calling again with larger buffers.

Remarks

When using alternate glyphs, the application first reshapes the original glyph without applying any feature tag, then selects an alternate. The original glyph is established as the base glyph. If another alternate is required, the original glyph provides information to match with the corresponding alternates list.

If an alternate glyph is used as the base glyph, no matching output list is found. The user interface uses the selected final form without providing the capability to choose another alternate.

The operations of ScriptGetFontAlternateGlyphs can be emulated by ScriptSubstituteSingleGlyph. The application should try parameters one by one while glyphs are substituted.

For shaping fonts with Uniscribe, ScriptShapeOpenType is preferred over the older ScriptShape function.

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

Requirement	Value
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