ScriptShape

The ScriptShape function takes a Unicode run and generates glyphs and visual attributes.

HRESULT WINAPI ScriptShape(
  HDC hdc, 
  SCRIPT_CACHE *psc, 
  const WCHAR *pwcChars, 
  int cChars, 
  int cMaxGlyphs, 
  SCRIPT_ANALYSIS *psa, 
  WORD *pwOutGlyphs, 
  WORD *pwLogClust, 
  SCRIPT_VISATTR *psva, 
  int *pcGlyphs 
);

Parameters

hdc

[in] Handle to a device context.

psc

[in/out] Pointer to a SCRIPT_CACHE structure.

pwcChars

[in] Pointer to an array of Unicode characters containing the run.

cChars

[in] Number of characters in the Unicode run.

cMaxGlyphs

[in] Maximum number of glyphs to generate.

psa

[in/out] Pointer to an array of SCRIPT_ANALYSIS structures containing the results of an earlier call to ScriptItemize.

pwOutGlyphs

[out] Pointer to an array that receives the glyphs.

pwLogClust

[out] Pointer to an array that receives the logical clusters.

psva

[out] Pointer to an array of SCRIPT_VISATTR structures that receives visual attributes information.

pcGlyphs

[out] Pointer to an integer that receives a count of the number of glyphs processed.

Return Values

If the function succeeds, the return value is zero.

If the function fails, it returns a nonzero value. The function returns E_OUTOFMEMORY if the output buffer length, cMaxGlyphs, is insufficient. Note that in all error cases the content of the output array is undefined.

If any other unrecoverable error is encountered, it is also returned as HRESULT. For example, error returns from Win32 API functions are converted to HRESULT using the HRESULT_FROM_WIN32 macro and returned to the client in the HRESULT.

Remarks

The number of glyphs generated by a code point varies according to the script and the font. For a simple script, a Unicode code point may generate a single glyph. However, a complex script font might construct characters from components, and thus generate several times as many glyphs as characters. Also, there are special cases like invalid character representations, where extra glyphs are added to represent the invalid sequence. Therefore, a reasonable guess for the buffer pointed to by pwOutGlyphs might be 1.5 times the length of the character buffer, plus an additional 16 glyphs for rare cases like invalid sequence representation.

If ScriptShape returns E_OUTOFMEMORY it will be necessary to call ScriptShape again, and possibly more than once, until a large enough buffer is found.

Clusters are sequenced uniformly within the run, as are glyphs within the cluster. The fRTL item flag (from ScriptItemize) identifies whether sequencing is left-to-right, or right-to-left.

ScriptShape may set the fNoGlyphIndex flag in psa if the font or operating system cannot support glyph indices.

If fLogicalOrder is requested in psa, glyphs will be always be generated in the same order as the original Unicode characters. If fLogicalOrder is not set, RTL items are generated in reverse order, so ScriptTextOut does not need to reverse them before calling ExtTextOut.

If SCRIPT_ANALYSIS.eScript is set to SCRIPT_UNDEFINED, shaping is disabled and ScriptShape displays whatever glyph is in the font cmap table; if none, it displays the missing glyph.

Requirements

  Windows NT/2000: Requires Windows 2000.
  Header: Declared in Usp10.h.
  Library: Use Usp10.lib.

See Also

Uniscribe Overview, Uniscribe Functions, ExtTextOut, ScriptItemize, ScriptShape, ScriptTextOut, SCRIPT_ANALYSIS, SCRIPT_CACHE, SCRIPT_VISATTR