ScriptPlace function (usp10.h)

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.

Requirements

See also

Displaying Text with Uniscribe

GOFFSET

SCRIPT_ANALYSIS

SCRIPT_CACHE

SCRIPT_VISATTR

ScriptItemize

ScriptPlaceOpenType

ScriptShape

Uniscribe

Uniscribe Functions