ICU 56.1: icu::LayoutEngine Class Reference

ICU 56.1 56.1

- Main Page
- Related Pages
- Modules
- Namespaces
- Data Structures
- Files

- Data Structures
- Data Structure Index
- Class Hierarchy
- Data Fields

Public Member Functions | Static Public Member Functions | Static Public Attributes | Protected Member Functions | Static Protected Member Functions | Protected Attributes
icu::LayoutEngine Class Reference

NOTE: This class is deprecated, please instead use HarfBuzz. More...

`#include <LayoutEngine.h>`

Inheritance diagram for icu::LayoutEngine:

## Public Member Functions
virtual | ~LayoutEngine ()
| The destructor. More...
virtual le_int32 | layoutChars (const LEUnicode chars[], le_int32 offset, le_int32 count, le_int32 max, le_bool rightToLeft, float x, float y, LEErrorCode &success)
| This method will invoke the layout steps in their correct order by calling the computeGlyphs, positionGlyphs and adjustGlyphPosition methods. More...
le_int32 | getGlyphCount () const
| This method returns the number of glyphs in the glyph array. More...
void | getGlyphs (LEGlyphID glyphs[], LEErrorCode &success) const
| This method copies the glyph array into a caller supplied array. More...
virtual void | getGlyphs (le_uint32 glyphs[], le_uint32 extraBits, LEErrorCode &success) const
| This method copies the glyph array into a caller supplied array, ORing in extra bits. More...
void | getCharIndices (le_int32 charIndices[], LEErrorCode &success) const
| This method copies the character index array into a caller supplied array. More...
void | getCharIndices (le_int32 charIndices[], le_int32 indexBase, LEErrorCode &success) const
| This method copies the character index array into a caller supplied array. More...
void | getGlyphPositions (float positions[], LEErrorCode &success) const
| This method copies the position array into a caller supplied array. More...
void | getGlyphPosition (le_int32 glyphIndex, float &x, float &y, LEErrorCode &success) const
| This method returns the X and Y position of the glyph at the given index. More...
virtual void | reset ()
| This method frees the glyph, character index and position arrays so that the LayoutEngine can be reused to layout a different characer array. More...
virtual UClassID | getDynamicClassID () const
| ICU "poor man's RTTI", returns a UClassID for the actual class. More...
Public Member Functions inherited from icu::UObject
virtual | ~UObject ()
| Destructor. More...

## Static Public Member Functions
static LayoutEngine * | layoutEngineFactory (const LEFontInstance *fontInstance, le_int32 scriptCode, le_int32 languageCode, LEErrorCode &success)
| This method returns a LayoutEngine capable of laying out text in the given font, script and langauge. More...
static LayoutEngine * | layoutEngineFactory (const LEFontInstance *fontInstance, le_int32 scriptCode, le_int32 languageCode, le_int32 typo_flags, LEErrorCode &success)
| Override of existing call that provides flags to control typography. More...
static UClassID | getStaticClassID ()
| ICU "poor man's RTTI", returns a UClassID for this class. More...

## Static Public Attributes
static const le_int32 | kTypoFlagKern
static const le_int32 | kTypoFlagLiga

## Protected Member Functions
| LayoutEngine (const LEFontInstance *fontInstance, le_int32 scriptCode, le_int32 languageCode, le_int32 typoFlags, LEErrorCode &success)
| This constructs an instance for a given font, script and language. More...
| LayoutEngine ()
| This overrides the default no argument constructor to make it difficult for clients to call it. More...
virtual le_int32 | characterProcessing (const LEUnicode chars[], le_int32 offset, le_int32 count, le_int32 max, le_bool rightToLeft, LEUnicode *&outChars, LEGlyphStorage &glyphStorage, LEErrorCode &success)
| This method does any required pre-processing to the input characters. More...
virtual le_int32 | computeGlyphs (const LEUnicode chars[], le_int32 offset, le_int32 count, le_int32 max, le_bool rightToLeft, LEGlyphStorage &glyphStorage, LEErrorCode &success)
| This method does the glyph processing. More...
virtual void | positionGlyphs (LEGlyphStorage &glyphStorage, float x, float y, LEErrorCode &success)
| This method does basic glyph positioning. More...
virtual void | adjustGlyphPositions (const LEUnicode chars[], le_int32 offset, le_int32 count, le_bool reverse, LEGlyphStorage &glyphStorage, LEErrorCode &success)
| This method does positioning adjustments like accent positioning and kerning. More...
virtual const void * | getFontTable (LETag tableTag, size_t &length) const
| This method gets a table from the font associated with the text. More...
virtual const void * | getFontTable (LETag tableTag) const
virtual void | mapCharsToGlyphs (const LEUnicode chars[], le_int32 offset, le_int32 count, le_bool reverse, le_bool mirror, LEGlyphStorage &glyphStorage, LEErrorCode &success)
| This method does character to glyph mapping. More...

## Static Protected Member Functions
static void | adjustMarkGlyphs (LEGlyphStorage &glyphStorage, LEGlyphFilter *markFilter, LEErrorCode &success)
| This is a convenience method that forces the advance width of mark glyphs to be zero, which is required for proper selection and highlighting. More...
static void | adjustMarkGlyphs (const LEUnicode chars[], le_int32 charCount, le_bool reverse, LEGlyphStorage &glyphStorage, LEGlyphFilter *markFilter, LEErrorCode &success)
| This is a convenience method that forces the advance width of mark glyphs to be zero, which is required for proper selection and highlighting. More...

## Protected Attributes
LEGlyphStorage * | fGlyphStorage
| The object which holds the glyph storage. More...
const LEFontInstance * | fFontInstance
| The font instance for the text font. More...
le_int32 | fScriptCode
| The script code for the text. More...
le_int32 | fLanguageCode
| The langauge code for the text. More...
le_int32 | fTypoFlags
| The typographic control flags. More...
le_bool | fFilterZeroWidth
| `TRUE` if `mapCharsToGlyphs` should replace ZWJ / ZWNJ with a glyph with no contours. More...

## Detailed Description

NOTE: This class is deprecated, please instead use HarfBuzz.

See: http://www.freedesktop.org/wiki/Software/HarfBuzz/ and http://userguide.icu-project.org/layoutengine

This is a virtual base class used to do complex text layout. The text must all be in a single font, script, and language. An instance of a LayoutEngine can be created by calling the layoutEngineFactory method. Fonts are identified by instances of the LEFontInstance class. Script and language codes are identified by integer codes, which are defined in ScriptAndLanuageTags.h.

Note that this class is not public API. It is declared public so that it can be exported from the library that it is a part of.

The input to the layout process is an array of characters in logical order, and a starting X, Y position for the text. The output is an array of glyph indices, an array of character indices for the glyphs, and an array of glyph positions. These arrays are protected members of LayoutEngine which can be retreived by a public method. The reset method can be called to free these arrays so that the LayoutEngine can be reused.

The layout process is done in three steps. There is a protected virtual method for each step. These methods have a default implementation which only does character to glyph mapping and default positioning using the glyph's advance widths. Subclasses can override these methods for more advanced layout. There is a public method which invokes the steps in the correct order.

The steps are:

1) Glyph processing - character to glyph mapping and any other glyph processing such as ligature substitution and contextual forms.

2) Glyph positioning - position the glyphs based on their advance widths.

3) Glyph position adjustments - adjustment of glyph positions for kerning, accent placement, etc.

NOTE: in all methods below, output parameters are references to pointers so the method can allocate and free the storage as needed. All storage allocated in this way is owned by the object which created it, and will be freed when it is no longer needed, or when the object's destructor is invoked.

See also
  LEFontInstance
  ScriptAndLanguageTags.h

Deprecated:
  ICU 54. See icu::LayoutEngine Instead, please use HarfBuzz. see http://www.freedesktop.org/wiki/Software/HarfBuzz/ and http://userguide.icu-project.org/layoutengine

Definition at line 71 of file LayoutEngine.h.

## Constructor & Destructor Documentation

icu::LayoutEngine::LayoutEngine | ( | const LEFontInstance * | fontInstance,
|  | le_int32 | scriptCode,
|  | le_int32 | languageCode,
|  | le_int32 | typoFlags,
|  | LEErrorCode & | success
| ) |  |
| protected

This constructs an instance for a given font, script and language.

Subclass constructors must call this constructor.

Parameters

  fontInstance | - the font for the text
  scriptCode | - the script for the text
  languageCode | - the language for the text
  typoFlags | - the typographic control flags for the text (a bitfield). Use kTypoFlagKern if kerning is desired, kTypoFlagLiga if ligature formation is desired. Others are reserved.
  success | - set to an error code if the operation fails

See also
  LEFontInstance
  ScriptAndLanguageTags.h

Internal:
  Do not use. This API is for internal use only.

icu::LayoutEngine::LayoutEngine | ( |  | ) |
| protected

This overrides the default no argument constructor to make it difficult for clients to call it.

Clients are expected to call layoutEngineFactory.

Internal:
  Do not use. This API is for internal use only.

virtual icu::LayoutEngine::~LayoutEngine | ( |  | ) |
| virtual

The destructor.

It will free any storage allocated for the glyph, character index and position arrays by calling the reset method. It is declared virtual so that it will be invoked by the subclass destructors.

Deprecated:
  ICU 54. See icu::LayoutEngine

## Member Function Documentation

virtual void icu::LayoutEngine::adjustGlyphPositions | ( | const LEUnicode | chars[],
|  | le_int32 | offset,
|  | le_int32 | count,
|  | le_bool | reverse,
|  | LEGlyphStorage & | glyphStorage,
|  | LEErrorCode & | success
| ) |  |
| protectedvirtual

This method does positioning adjustments like accent positioning and kerning.

The default implementation does nothing. Subclasses needing position adjustments must override this method.

Note that this method has both characters and glyphs as input so that it can use the character codes to determine glyph types if that information isn't directly available. (e.g. Some Arabic OpenType fonts don't have a GDEF table)

Parameters

  chars | - the input character context
  offset | - the offset of the first character to process
  count | - the number of characters to process
  reverse | - `TRUE` if the glyphs in the glyph array have been reordered
  glyphStorage | - the object which holds the per-glyph storage. The glyph positions will be adjusted as needed.
  success | - output parameter set to an error code if the operation fails

Internal:
  Do not use. This API is for internal use only.

static void icu::LayoutEngine::adjustMarkGlyphs | ( | LEGlyphStorage & | glyphStorage,
|  | LEGlyphFilter * | markFilter,
|  | LEErrorCode & | success
| ) |  |
| staticprotected

This is a convenience method that forces the advance width of mark glyphs to be zero, which is required for proper selection and highlighting.

Parameters

  glyphStorage | - the object containing the per-glyph storage. The positions array will be modified.
  markFilter | - used to identify mark glyphs
  success | - output parameter set to an error code if the operation fails

See also
  LEGlyphFilter

Internal:
  Do not use. This API is for internal use only.

static void icu::LayoutEngine::adjustMarkGlyphs | ( | const LEUnicode | chars[],
|  | le_int32 | charCount,
|  | le_bool | reverse,
|  | LEGlyphStorage & | glyphStorage,
|  | LEGlyphFilter * | markFilter,
|  | LEErrorCode & | success
| ) |  |
| staticprotected

This is a convenience method that forces the advance width of mark glyphs to be zero, which is required for proper selection and highlighting.

This method uses the input characters to identify marks. This is required in cases where the font does not contain enough information to identify them based on the glyph IDs.

Parameters

  chars | - the array of input characters
  charCount | - the number of input characers
  glyphStorage | - the object containing the per-glyph storage. The positions array will be modified.
  reverse | - `TRUE` if the glyph array has been reordered
  markFilter | - used to identify mark glyphs
  success | - output parameter set to an error code if the operation fails

See also
  LEGlyphFilter

Internal:
  Do not use. This API is for internal use only.

virtual le_int32 icu::LayoutEngine::characterProcessing | ( | const LEUnicode | chars[],
|  | le_int32 | offset,
|  | le_int32 | count,
|  | le_int32 | max,
|  | le_bool | rightToLeft,
|  | LEUnicode *& | outChars,
|  | LEGlyphStorage & | glyphStorage,
|  | LEErrorCode & | success
| ) |  |
| protectedvirtual

This method does any required pre-processing to the input characters.

It may generate output characters that differ from the input charcters due to insertions, deletions, or reorderings. In such cases, it will also generate an output character index array reflecting these changes.

Subclasses must override this method.

Input parameters:

Parameters

  chars | - the input character context
  offset | - the index of the first character to process
  count | - the number of characters to process
  max | - the number of characters in the input context
  rightToLeft | - TRUE if the characters are in a right to left directional run
  outChars | - the output character array, if different from the input
  glyphStorage | - the object that holds the per-glyph storage. The character index array may be set.
  success | - set to an error code if the operation fails

Returns
  the output character count (input character count if no change)

Internal:
  Do not use. This API is for internal use only.

virtual le_int32 icu::LayoutEngine::computeGlyphs | ( | const LEUnicode | chars[],
|  | le_int32 | offset,
|  | le_int32 | count,
|  | le_int32 | max,
|  | le_bool | rightToLeft,
|  | LEGlyphStorage & | glyphStorage,
|  | LEErrorCode & | success
| ) |  |
| protectedvirtual

This method does the glyph processing.

It converts an array of characters into an array of glyph indices and character indices. The characters to be processed are passed in a surrounding context. The context is specified as a starting address and a maximum character count. An offset and a count are used to specify the characters to be processed.

The default implementation of this method only does character to glyph mapping. Subclasses needing more elaborate glyph processing must override this method.

Input parameters:

Parameters

  chars | - the character context
  offset | - the offset of the first character to process
  count | - the number of characters to process
  max | - the number of characters in the context.
  rightToLeft | - TRUE if the text is in a right to left directional run
  glyphStorage | - the object which holds the per-glyph storage. The glyph and char indices arrays will be set.

Output parameters:

Parameters

  success | - set to an error code if the operation fails

Returns
  the number of glyphs in the glyph index array

Internal:
  Do not use. This API is for internal use only.

void icu::LayoutEngine::getCharIndices | ( | le_int32 | charIndices[],
|  | LEErrorCode & | success
| ) |  | const

This method copies the character index array into a caller supplied array.

The caller must ensure that the array is large enough to hold a character index for each glyph.

Parameters

  charIndices | - the destiniation character index array
  success | - set to an error code if the operation fails

Deprecated:
  ICU 54. See icu::LayoutEngine

void icu::LayoutEngine::getCharIndices | ( | le_int32 | charIndices[],
|  | le_int32 | indexBase,
|  | LEErrorCode & | success
| ) |  | const

This method copies the character index array into a caller supplied array.

The caller must ensure that the array is large enough to hold a character index for each glyph.

Parameters

  charIndices | - the destiniation character index array
  indexBase | - an offset which will be added to each index
  success | - set to an error code if the operation fails

Deprecated:
  ICU 54. See icu::LayoutEngine

virtual UClassID icu::LayoutEngine::getDynamicClassID | ( |  | ) | const
| virtual

ICU "poor man's RTTI", returns a UClassID for the actual class.

Deprecated:
  ICU 54. See icu::LayoutEngine

Reimplemented from icu::UObject.

virtual const void* icu::LayoutEngine::getFontTable | ( | LETag | tableTag,
|  | size_t & | length
| ) |  | const
| protectedvirtual

This method gets a table from the font associated with the text.

The default implementation gets the table from the font instance. Subclasses which need to get the tables some other way must override this method.

Parameters

  tableTag | - the four byte table tag.
  length | - length to use

Returns
  the address of the table.

Internal:
  Do not use. This API is for internal use only.

virtual const void* icu::LayoutEngine::getFontTable | ( | LETag | tableTag | ) | const
| inlineprotectedvirtual

Deprecated:
  ICU 54. See icu::LayoutEngine

Definition at line 273 of file LayoutEngine.h.

References getFontTable().

Referenced by getFontTable().

le_int32 icu::LayoutEngine::getGlyphCount | ( |  | ) | const

This method returns the number of glyphs in the glyph array.

Note that the number of glyphs will be greater than or equal to the number of characters used to create the LayoutEngine.

Returns
  the number of glyphs in the glyph array

Deprecated:
  ICU 54. See icu::LayoutEngine

void icu::LayoutEngine::getGlyphPosition | ( | le_int32 | glyphIndex,
|  | float & | x,
|  | float & | y,
|  | LEErrorCode & | success
| ) |  | const

This method returns the X and Y position of the glyph at the given index.

Input parameters:

Parameters

  glyphIndex | - the index of the glyph

Output parameters:

Parameters

  x | - the glyph's X position
  y | - the glyph's Y position
  success | - set to an error code if the operation fails

Deprecated:
  ICU 54. See icu::LayoutEngine

void icu::LayoutEngine::getGlyphPositions | ( | float | positions[],
|  | LEErrorCode & | success
| ) |  | const

This method copies the position array into a caller supplied array.

The caller must ensure that the array is large enough to hold an X and Y position for each glyph, plus an extra X and Y for the advance of the last glyph.

Parameters

  positions | - the destiniation position array
  success | - set to an error code if the operation fails

Deprecated:
  ICU 54. See icu::LayoutEngine

void icu::LayoutEngine::getGlyphs | ( | LEGlyphID | glyphs[],
|  | LEErrorCode & | success
| ) |  | const

This method copies the glyph array into a caller supplied array.

The caller must ensure that the array is large enough to hold all the glyphs.

Parameters

  glyphs | - the destiniation glyph array
  success | - set to an error code if the operation fails

Deprecated:
  ICU 54. See icu::LayoutEngine

virtual void icu::LayoutEngine::getGlyphs | ( | le_uint32 | glyphs[],
|  | le_uint32 | extraBits,
|  | LEErrorCode & | success
| ) |  | const
| virtual

This method copies the glyph array into a caller supplied array, ORing in extra bits.

(This functionality is needed by the JDK, which uses 32 bits pre glyph idex, with the high 16 bits encoding the composite font slot number)

Parameters

  glyphs | - the destination (32 bit) glyph array
  extraBits | - this value will be ORed with each glyph index
  success | - set to an error code if the operation fails

Deprecated:
  ICU 54. See icu::LayoutEngine

static UClassID icu::LayoutEngine::getStaticClassID | ( |  | ) |
| static

ICU "poor man's RTTI", returns a UClassID for this class.

Deprecated:
  ICU 54. See icu::LayoutEngine

virtual le_int32 icu::LayoutEngine::layoutChars | ( | const LEUnicode | chars[],
|  | le_int32 | offset,
|  | le_int32 | count,
|  | le_int32 | max,
|  | le_bool | rightToLeft,
|  | float | x,
|  | float | y,
|  | LEErrorCode & | success
| ) |  |
| virtual

This method will invoke the layout steps in their correct order by calling the computeGlyphs, positionGlyphs and adjustGlyphPosition methods.

It will compute the glyph, character index and position arrays.

Parameters

  chars | - the input character context
  offset | - the offset of the first character to process
  count | - the number of characters to process
  max | - the number of characters in the input context
  rightToLeft | - TRUE if the characers are in a right to left directional run
  x | - the initial X position
  y | - the initial Y position
  success | - output parameter set to an error code if the operation fails

Returns
  the number of glyphs in the glyph array

Note: The glyph, character index and position array can be accessed using the getter methods below.

Note: If you call this method more than once, you must call the reset() method first to free the glyph, character index and position arrays allocated by the previous call.

Deprecated:
  ICU 54. See icu::LayoutEngine

static LayoutEngine* icu::LayoutEngine::layoutEngineFactory | ( | const LEFontInstance * | fontInstance,
|  | le_int32 | scriptCode,
|  | le_int32 | languageCode,
|  | LEErrorCode & | success
| ) |  |
| static

This method returns a LayoutEngine capable of laying out text in the given font, script and langauge.

Note that the LayoutEngine returned may be a subclass of LayoutEngine.

Parameters

  fontInstance | - the font of the text
  scriptCode | - the script of the text
  languageCode | - the language of the text
  success | - output parameter set to an error code if the operation fails

Returns
  a LayoutEngine which can layout text in the given font.

See also
  LEFontInstance

Deprecated:
  ICU 54. See icu::LayoutEngine

static LayoutEngine* icu::LayoutEngine::layoutEngineFactory | ( | const LEFontInstance * | fontInstance,
|  | le_int32 | scriptCode,
|  | le_int32 | languageCode,
|  | le_int32 | typo_flags,
|  | LEErrorCode & | success
| ) |  |
| static

Override of existing call that provides flags to control typography.

Deprecated:
  ICU 54. See icu::LayoutEngine

virtual void icu::LayoutEngine::mapCharsToGlyphs | ( | const LEUnicode | chars[],
|  | le_int32 | offset,
|  | le_int32 | count,
|  | le_bool | reverse,
|  | le_bool | mirror,
|  | LEGlyphStorage & | glyphStorage,
|  | LEErrorCode & | success
| ) |  |
| protectedvirtual

This method does character to glyph mapping.

The default implementation uses the font instance to do the mapping. It will allocate the glyph and character index arrays if they're not already allocated. If it allocates the character index array, it will fill it it.

This method supports right to left text with the ability to store the glyphs in reverse order, and by supporting character mirroring, which will replace a character which has a left and right form, such as parens, with the opposite form before mapping it to a glyph index.

Input parameters:

Parameters

  chars | - the input character context
  offset | - the offset of the first character to be mapped
  count | - the number of characters to be mapped
  reverse | - if `TRUE`, the output will be in reverse order
  mirror | - if `TRUE`, do character mirroring
  glyphStorage | - the object which holds the per-glyph storage. The glyph and char indices arrays will be filled in.
  success | - set to an error code if the operation fails

See also
  LEFontInstance

Internal:
  Do not use. This API is for internal use only.

virtual void icu::LayoutEngine::positionGlyphs | ( | LEGlyphStorage & | glyphStorage,
|  | float | x,
|  | float | y,
|  | LEErrorCode & | success
| ) |  |
| protectedvirtual

This method does basic glyph positioning.

The default implementation positions the glyphs based on their advance widths. This is sufficient for most uses. It is not expected that many subclasses will override this method.

Input parameters:

Parameters

  glyphStorage | - the object which holds the per-glyph storage. The glyph position array will be set.
  x | - the starting X position
  y | - the starting Y position
  success | - set to an error code if the operation fails

Internal:
  Do not use. This API is for internal use only.

virtual void icu::LayoutEngine::reset | ( |  | ) |
| virtual

This method frees the glyph, character index and position arrays so that the LayoutEngine can be reused to layout a different characer array.

(This method is also called by the destructor)

Deprecated:
  ICU 54. See icu::LayoutEngine

## Field Documentation

le_bool icu::LayoutEngine::fFilterZeroWidth
| protected

`TRUE` if `mapCharsToGlyphs` should replace ZWJ / ZWNJ with a glyph with no contours.

Internal:
  Do not use. This API is for internal use only.

Definition at line 128 of file LayoutEngine.h.

const LEFontInstance* icu::LayoutEngine::fFontInstance
| protected

The font instance for the text font.

See also
  LEFontInstance

Internal:
  Do not use. This API is for internal use only.

Definition at line 95 of file LayoutEngine.h.

LEGlyphStorage* icu::LayoutEngine::fGlyphStorage
| protected

The object which holds the glyph storage.

Internal:
  Do not use. This API is for internal use only.

Definition at line 86 of file LayoutEngine.h.

le_int32 icu::LayoutEngine::fLanguageCode
| protected

The langauge code for the text.

See also
  ScriptAndLanguageTags.h for language codes.

Internal:
  Do not use. This API is for internal use only.

Definition at line 113 of file LayoutEngine.h.

le_int32 icu::LayoutEngine::fScriptCode
| protected

The script code for the text.

See also
  ScriptAndLanguageTags.h for script codes.

Internal:
  Do not use. This API is for internal use only.

Definition at line 104 of file LayoutEngine.h.

le_int32 icu::LayoutEngine::fTypoFlags
| protected

The typographic control flags.

Internal:
  Do not use. This API is for internal use only.

Definition at line 120 of file LayoutEngine.h.

const le_int32 icu::LayoutEngine::kTypoFlagKern
| static

Internal:
  Do not use. This API is for internal use only. Flag to request kerning. Use LE_Kerning_FEATURE_FLAG instead.

Definition at line 75 of file LayoutEngine.h.

const le_int32 icu::LayoutEngine::kTypoFlagLiga
| static

Internal:
  Do not use. This API is for internal use only. Flag to request ligatures. Use LE_Ligatures_FEATURE_FLAG instead.

Definition at line 77 of file LayoutEngine.h.

The documentation for this class was generated from the following file:

- LayoutEngine.h