ScriptPositionSingleGlyph function (usp10.h)
Positions a single glyph with a single adjustment using a specified feature provided in the font for OpenType processing. Most often, applications use this function to align a glyph optically at the beginning or end of a line.
Syntax
HRESULT ScriptPositionSingleGlyph(
[in, optional] HDC hdc,
[in, out] SCRIPT_CACHE *psc,
[in, optional] SCRIPT_ANALYSIS *psa,
[in] OPENTYPE_TAG tagScript,
[in] OPENTYPE_TAG tagLangSys,
[in] OPENTYPE_TAG tagFeature,
[in] LONG lParameter,
[in] WORD wGlyphId,
[in] int iAdvance,
[in] GOFFSET GOffset,
[out] int *piOutAdvance,
[out] GOFFSET *pOutGoffset
);
Parameters
[in, optional] hdc
Handle to the device context. For more information, see Caching.
[in, out] psc
Pointer to a SCRIPT_CACHE structure identifying the script cache.
[in, optional] psa
Pointer to a SCRIPT_ANALYSIS structure obtained from a previous call to ScriptItemizeOpenType. This structure identifies the shaping engine, so that the advance widths can be retrieved.
Alternatively, the application can set this parameter to NULL to retrieve unfiltered results.
[in] tagScript
An OPENTYPE_TAG structure defining the script tag for shaping.
[in] tagLangSys
An OPENTYPE_TAG structure defining the language tag for shaping.
[in] tagFeature
An OPENTYPE_TAG structure defining the feature tag to use for shaping the alternate glyph.
[in] lParameter
A flag specifying if single substitution should be applied to the identifier specified in wGlyphId. The application sets this parameter to 1 to apply the single substitution feature to the identifier. The application sets the parameter to 0 if the function should not apply the feature.
[in] wGlyphId
The identifier of the original glyph being shaped.
[in] iAdvance
The original glyph advance width.
[in] GOffset
The original glyph offset. Typically, this value is an output of ScriptPlaceOpenType or ScriptPlace.
[out] piOutAdvance
Pointer to the location in which this function retrieves the new advance width adjusted for the alternate glyph.
[out] pOutGoffset
Pointer to the location in which this function retrieves the new glyph offset adjusted for the alternate glyph.
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.
Remarks
This function positions an individual glyph by adjusting the advance width and/or the offset of the given glyph. The function assumes that the font requires only one adjustment.
A typical use of this function is the slight adjustment of the margin to account for the visual impression made by certain characters. In Latin script, for example, at the beginning of a line it is common to make a slight adjustment to the left for an initial capital (such as "T" or "O") that does not have a vertical line on the left part of the glyph. Although doing this breaks the strict linear margin, the eye perceives the margin as more even.
The following examples demonstrate this effect. The first example shows strict alignment; the next two examples show an adjustment of the initial "T" to the left. The adjustments are by one pixel and two pixels, respectively. The magnified images to the right show how the "T" pushes slightly farther into the left margin in each successive case.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows Vista [desktop apps only] |
| Minimum supported server | Windows Server 2008 [desktop apps only] |
| Target Platform | Windows |
| Header | usp10.h |
| Library | Usp10.lib |
| DLL | Usp10.dll |
| Redistributable | Usp10.dll version 1.600 or greater on Windows XP |