ScriptPlace function (usp10.h)

Article
10/13/2021

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

Syntax

HRESULT ScriptPlace(
  [in]      HDC                  hdc,
  [in, out] SCRIPT_CACHE         *psc,
  [in]      const WORD           *pwGlyphs,
  [in]      int                  cGlyphs,
  [in]      const SCRIPT_VISATTR *psva,
  [in, out] SCRIPT_ANALYSIS      *psa,
  [out]     int                  *piAdvance,
  [out]     GOFFSET              *pGoffset,
  [out]     ABC                  *pABC
);

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] pwGlyphs

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

[in] cGlyphs

Count of glyphs in the glyph buffer.

[in] psva

Pointer to an array of SCRIPT_VISATTR structures indicating visual attributes.

[in, out] psa

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.

[out] piAdvance

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

[out] pGoffset

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.

[out] pABC

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.

Remarks

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.

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