ScriptPositionSingleGlyph (Compact 2013)

3/28/2014

This function positions a single glyph with a single adjustment using a 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(
  HDC hdc,
  SCRIPT_CACHE* psc,
  SCRIPT_ANALYSIS* psa,
  OPENTYPE_TAG tagScript,
  OPENTYPE_TAG tagLangSys,
  OPENTYPE_TAG tagFeature,
  LONG lParameter,
  WORD wGlyphId,
  int iAdvance,
  GOFFSET gOffset, 
  int* piOutAdvance,
  GOFFSET* pOutGoffset 
);

Parameters

• hdc
  [in] Optional. Handle to the device context.

• psc
  [in/out] Pointer to a SCRIPT_CACHE structure identifying the script cache.

• psa
  [in] 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 supply a null pointer to retrieve unfiltered results.

• tagScript
  [in] An OPENTYPE_TAG structure defining the script tag for shaping.

• tagLangSys
  [in] An OPENTYPE_TAG structure defining the language tag for shaping.

• tagFeature
  [in] An OPENTYPE_TAG structure defining the feature tag to use for shaping the alternate glyph.

• lParameter
  [in] 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.

• wGlyphId
  [in] The identifier of the original glyph being shaped.

• iAdvance
  [in] The original glyph advance width.

• gOffset
  [in] The original glyph offset. Typically, this value is an output of ScriptPlaceOpenType or ScriptPlace.

• piOutAdvance
  [out] Pointer to the location in which this function retrieves the new advance width adjusted for the alternate glyph.

• pOutGoffset
  [out] Pointer to the location in which this function retrieves the new glyph offset adjusted for the alternate glyph.

Return Values

If the function is successful, it returns 0. If it does not succeed, it returns a nonzero HRESULT value. 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

Header	usp10.h
Library	Uspce.lib

See Also

Reference

Uniscribe Functions
SCRIPT_CACHE
SCRIPT_ANALYSIS
ScriptItemizeOpenType
OPENTYPE_TAG
ScriptPlaceOpenType
ScriptPlace