ScriptShape (Windows Embedded CE 6.0)

  • Article

1/6/2010

This function takes a Unicode run and generates glyphs and visual attributes.

Syntax

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.
  • 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.
  • pwOutGlyphs
    [out] Pointer to an array that receives the glyphs.
  • pwLogClust
    [out] Pointer to an array that receives the logical cluster information. Each element in *pwLogClust corresponds to a character in *pwcChars. 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. For an example, see Remarks. Note that when *psa.fRTL is TRUE, the elements in *pwLogClust decrease when reading the array.
  • psva
    [out] Pointer to an array of SCRIPT_VISATTR structures that receives visual attributes information. There is one visual attribute per glyph, so *psva has cMaxGlyphs elements.
  • pcGlyphs
    [out] Pointer to an integer that receives a count of the number of glyphs written to pwOutGlyphs.

Return Value

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 all output parameters are undefined.

If any other unrecoverable error is encountered, it is returned as an HRESULT.

Remarks

If ScriptShape returns E_OUTOFMEMORY, pcGlyphs is undefined; you may need to call ScriptShape repeatedly until a large enough buffer is found. 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.

To determine if a font supports the characters in a given string, call ScriptShape. If it returns S_OK, check the output for missing glyphs.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.

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

1st cluster: one character represented by one glyph

2nd cluster: one character represented by three glyphs

3rd cluster: three characters represented by one glyph

4th cluster: two characters represented by three glyphs

Character array (where c<n>u<m> means cluster n, Unicode codepoint 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 (the offset, in glyphs, to the cluster containing the character):

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

Requirements

Header usp10.h
Library Uspce.lib
Windows Embedded CE Windows CE 5.0 and later

See Also

Reference

ScriptItemize
ScriptTextOut
SCRIPT_ANALYSIS
SCRIPT_CACHE
SCRIPT_VISATTR

Other Resources

Uniscribe Functions