ScriptGetFontAlternateGlyphs (Compact 2013)

3/28/2014

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

Syntax

HRESULT ScriptGetFontAlternateGlyphs(
  HDC hdc,
  SCRIPT_CACHE* psc,
  SCRIPT_ANALYSIS* psa,
  OPENTYPE_TAG tagScript,
  OPENTYPE_TAG tagLangSys,
  OPENTYPE_TAG tagFeature,
  WORD wGlyph,
  int cMaxAlternates,
  WORD* pAlternateGlyphs, 
  int* pcAlternates
) ;

Parameters

• hdc
  [in] Optional. Handle to the device context.

• psc
  [in/out] Pointer to a SCRIPT_CACHE structure defining the script cache.

• psa
  [in] 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 supply a null pointer to receive unfiltered results.

• tagScript
  [in] An OPENTYPE_TAG structure defining the script tag associated with alternate glyphs.

• tagLangSys
  [in] An OPENTYPE_TAG structure defining the language tag associated with alternate glyphs.

• tagFeature
  [in] An OPENTYPE_TAG structure defining the feature tag associated with alternate glyphs.

• wGlyph
  [in] The original glyph mapped from the character-map table.

• cMaxAlternates
  [in] Length of the array specified by pAlternateGlyphs.

• pAlternateGlyphs
  [out] 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.

• pcAlternates
  [out] Pointer to the number of elements in the array specified by pAlternateGlyphs.

Return Values

If the function is successful, it returns 0. If it does not succeed, it returns a nonzero HRESULT value. 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 call the function again with larger buffers.

Remarks

When using alternate glyphs, the application first reshapes the original glyph without applying any feature tag, and 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 the ScriptSubstituteSingleGlyph function. The application should try parameters one by one while glyphs are substituted.

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

Requirements

See Also

Reference

Uniscribe Functions
SCRIPT_CACHE
SCRIPT_ANALYSIS
ScriptItemizeOpenType
ScriptSubstituteSingleGlyph
ScriptShapeOpenType
ScriptShape