ScriptPlace function

Generates glyph advance width and two-dimensional offset information from the output of ScriptShape.


HRESULT ScriptPlace(
  _In_          HDC             hdc,
  _Inout_       SCRIPT_CACHE    *psc,
  _In_    const WORD            *pwGlyphs,
  _In_          int             cGlyphs,
  _In_    const SCRIPT_VISATTR  *psva,
  _Inout_       SCRIPT_ANALYSIS *psa,
  _Out_         int             *piAdvance,
  _Out_         GOFFSET         *pGoffset,
  _Out_         ABC             *pABC


hdc [in]

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

psc [in, out]

Pointer to a SCRIPT_CACHE structure identifying the script cache.

pwGlyphs [in]

Pointer to a glyph buffer obtained from an earlier call to the ScriptShape function.

cGlyphs [in]

Count of glyphs in the glyph buffer.

psva [in]

Pointer to an array of SCRIPT_VISATTR structures indicating visual attributes.

psa [in, out]

Pointer to a SCRIPT_ANALYSIS structure. On input, this structure is obtained from a previous call to ScriptItemize. On output, this structure contains values retrieved by ScriptPlace.

piAdvance [out]

Pointer to an array in which this function retrieves advance width information.

pGoffset [out]

Optional. Pointer to an array of GOFFSET structures in which this function retrieves the x and y offsets of combining glyphs. This array must be of length indicated by cGlyphs.

pABC [out]

Pointer to an ABC structure in which this function retrieves the ABC width for the entire run.

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.

The function returns E_PENDING if the script cache specified by the psc parameter does not contain enough information to place the glyphs, and the hdc parameter is set to NULL so that the function cannot complete the placement process. The application should set up a correct device context for the run, and call this function again with the appropriate device context and with all other parameters the same.


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

The composite ABC width for the whole item identifies how much the glyphs overhang to the left of the start position and to the right of the length implied by the sum of the advance widths. The total advance width of the line is exactly abcA+abcB+abcC. The abcA and abcC values are maintained as proportions of the cell height represented in 8 bits and are thus roughly +/-1 percent. The total width retrieved, which is the sum of the abcA+abcB+abcC values indicated by piAdvance, is accurate to the resolution of the TrueType shaping engine.

All arrays are in visual order unless the fLogicalOrder member is set in the SCRIPT_ANALYSIS structure indicated by the psa parameter.

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.


Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]







See also

Uniscribe Functions
Displaying Text with Uniscribe