ScriptGetFontAlternateGlyphs function (usp10.h)
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.
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 |