ScriptShape function (usp10.h)

Article
10/13/2021

Generates glyphs and visual attributes for a Unicode run.

Syntax

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

Parameters

[in] hdc

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

[in, out] psc

Pointer to a SCRIPT_CACHE structure identifying the script cache.

[in] pwcChars

Pointer to an array of Unicode characters defining the run.

[in] cChars

Number of characters in the Unicode run.

[in] cMaxGlyphs

Maximum number of glyphs to generate, and the length of pwOutGlyphs. A reasonable value is (1.5 * cChars + 16), but this value might be insufficient in some circumstances. For more information, see the Remarks section.

[in, out] psa

Pointer to the SCRIPT_ANALYSIS structure for the run, containing the results from an earlier call to ScriptItemize.

[out] pwOutGlyphs

Pointer to a buffer in which this function retrieves an array of glyphs with size as indicated by cMaxGlyphs.

[out] pwLogClust

Pointer to a buffer in which this function retrieves an array of logical cluster information. Each array element corresponds to a character in the array of Unicode characters; therefore this array has the number of elements indicated by cChars. The value of each element is the offset from the first glyph in the run to the first glyph in the cluster containing the corresponding character. Note that, when the fRTL member is set to TRUE in the SCRIPT_ANALYSIS structure, the elements decrease as the array is read.

[out] psva

Pointer to a buffer in which this function retrieves an array of SCRIPT_VISATTR structures containing visual attribute information. Since each glyph has only one visual attribute, this array has the number of elements indicated by cMaxGlyphs.

[out] pcGlyphs

Pointer to the location in which this function retrieves the number of glyphs indicated in pwOutGlyphs.

Return value

Returns 0 if successful. The function returns a nonzero HRESULT value if it does not succeed. In all error cases, the content of all output parameters is undefined.

Error returns include:

E_OUTOFMEMORY. The output buffer length indicated by cMaxGlyphs is insufficient.
E_PENDING. The script cache specified by the psc parameter does not contain enough information to shape the string, and the device context has been passed as NULL so that the function is unable to complete the shaping process. The application should set up a correct device context for the run, and call this function again with the appropriate value in hdc and with all other parameters the same.
USP_E_SCRIPT_NOT_IN_FONT. The font corresponding to the device context does not support the script required by the run indicated by pwcChars. The application should choose another font, using either ScriptGetCMap or another function to select the font.

Remarks

See Displaying Text with Uniscribe for a discussion of the context in which this function is normally called.

If this function returns E_OUTOFMEMORY, the application might call ScriptShape repeatedly, with successively larger output buffers, until a large enough buffer is provided. 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 might 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, such as invalid character representations, in which extra glyphs are added to represent the invalid sequence. Therefore, a reasonable guess for the size of the buffer indicated by pwOutGlyphs is 1.5 times the length of the character buffer, plus an additional 16 glyphs for rare cases, for example, invalid sequence representation.

This function can set the fNoGlyphIndex member of the SCRIPT_ANALYSIS structure if the font or operating system cannot support glyph indexes.

The application can call ScriptShape to determine if a font supports the characters in a given string. If the function returns S_OK, the application should check the output for missing glyphs. If fLogicalOrder is set to TRUE in the SCRIPT_ANALYSIS structure, the function always generates glyphs in the same order as the original Unicode characters. If fLogicalOrder is set to FALSE, the function generates right-to-left items in reverse order so that ScriptTextOut does not have to reverse them before calling ExtTextOut.

If the eScript member of SCRIPT_ANALYSIS is set to SCRIPT_UNDEFINED, shaping is disabled. In this case, ScriptShape displays the glyph that is in the font cmap table. If no glyph is in the table, the function indicates that glyphs are missing.

ScriptShape sequences clusters uniformly within the run, and sequences glyphs uniformly within a cluster. It uses the value of the fRTL member of SCRIPT_ANALYSIS, from ScriptItemize, to identify sequencing as left-to-right or right-to-left.

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.

Examples

The following example shows how ScriptShape generates a logical cluster array (pwLogClust) from a character array (pwcChars) and a glyph array (pwOutGlyphs). The run has four clusters.

First cluster: one character represented by one glyph
Second cluster: one character represented by three glyphs
Third cluster: three characters represented by one glyph
Fourth cluster: two characters represented by three glyphs

Character array, where c<n>u<m> means cluster n, Unicode code point m:

| c1u1 | c2u1 | c3u1 c3u2 c3u3 | c4u1 c4u2 |

Glyph array, where c<n>g<m> means cluster n, glyph m:

| c1g1 | c2g1 c2g2 c2g3 | c3g1 | c4g1 c4g2 c4g3 |

Cluster array, that is, the offset (in glyphs) to the cluster containing the character:

| 0 | 1 | 4 4 4 | 5 5 |

Requirements

Requirement	Value
Minimum supported client	Windows 2000 Professional [desktop apps only]
Minimum supported server	Windows 2000 Server [desktop apps only]
Target Platform	Windows
Header	usp10.h
Library	Usp10.lib
DLL	Usp10.dll