Main Page   Class Hierarchy   Alphabetical List   Compound List   File List   Compound Members   File Members   Search  

LayoutEngine Class Reference

This is a virtual base class used to do complex text layout. More...

#include <LayoutEngine.h>

Inheritance diagram for LayoutEngine::

UObject UMemory GXLayoutEngine OpenTypeLayoutEngine ThaiLayoutEngine ArabicOpenTypeLayoutEngine HanOpenTypeLayoutEngine IndicOpenTypeLayoutEngine UnicodeArabicOpenTypeLayoutEngine List of all members.

Public Methods

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...


Static Public Methods

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...

UClassID getStaticClassID ()
 ICU "poor man's RTTI", returns a UClassID for this class. More...


Protected Methods

 LayoutEngine (const LEFontInstance *fontInstance, le_int32 scriptCode, le_int32 languageCode)
 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 computeGlyphs (const LEUnicode chars[], le_int32 offset, le_int32 count, le_int32 max, le_bool rightToLeft, LEGlyphID *&glyphs, le_int32 *&charIndices, LEErrorCode &success)
 This method does the glyph processing. More...

virtual void positionGlyphs (const LEGlyphID glyphs[], le_int32 glyphCount, float x, float y, float *&positions, LEErrorCode &success)
 This method does basic glyph positioning. More...

virtual void adjustGlyphPositions (const LEUnicode chars[], le_int32 offset, le_int32 count, le_bool, LEGlyphID glyphs[], le_int32 glyphCount, float positions[], LEErrorCode &success)
 This method does positioning adjustments like accent positioning and kerning. More...

virtual const void * getFontTable (LETag tableTag) const
 This method gets a table from the font associated with the text. More...

virtual void mapCharsToGlyphs (const LEUnicode chars[], le_int32 offset, le_int32 count, le_bool reverse, le_bool mirror, LEGlyphID *&glyphs, le_int32 *&charIndices, LEErrorCode &success)
 This method does character to glyph mapping. More...


Static Protected Methods

void adjustMarkGlyphs (const LEGlyphID glyphs[], le_int32 glyphCount, le_bool reverse, LEGlyphFilter *markFilter, float positions[], 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

le_int32 fGlyphCount
 The number of glyphs in the output. More...

LEGlyphIDfGlyphs
 The output glyph array. More...

le_int32fCharIndices
 The character index array. More...

float * fPositions
 The glyph position array. More...

const LEFontInstancefFontInstance
 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...


Static Private Attributes

const char fgClassID
 The address of this static class variable serves as this class's ID for ICU "poor man's RTTI". More...


Detailed Description

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
Draft:
This API has been introduced in ICU 2.2. It is still in draft state and may be modified in a future release.

Definition at line 66 of file LayoutEngine.h.


Constructor & Destructor Documentation

LayoutEngine::LayoutEngine const LEFontInstance   fontInstance,
le_int32    scriptCode,
le_int32    languageCode
[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
langaugeCode  - the language for the text
See also:
LEFontInstance , ScriptAndLanguageTags.h
Internal:
For internal use only.

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:
For internal use only.

virtual 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.

Draft:
This API has been introduced in ICU 2.2. It is still in draft state and may be modified in a future release.


Member Function Documentation

virtual void LayoutEngine::adjustGlyphPositions const LEUnicode    chars[],
le_int32    offset,
le_int32    count,
le_bool    reverse,
LEGlyphID    glyphs[],
le_int32    glyphCount,
float    positions[],
LEErrorCode   success
[protected, virtual]
 

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
glyphs  - the input glyph array
glyphCount  - the number of glyphs
positions  - the position array, will be updated as needed
success  - output parameter set to an error code if the operation fails
Note: the positions are passed as a plain array because this method should not need to reallocate them.

Internal:
For internal use only.

Reimplemented in ArabicOpenTypeLayoutEngine, UnicodeArabicOpenTypeLayoutEngine, GXLayoutEngine, and OpenTypeLayoutEngine.

void LayoutEngine::adjustMarkGlyphs const LEGlyphID    glyphs[],
le_int32    glyphCount,
le_bool    reverse,
LEGlyphFilter   markFilter,
float    positions[],
LEErrorCode   success
[static, protected]
 

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:
glyphs  - the glyph array
glyphCount  - the number of glyphs
reverse  - true if the glyph array has been reordered
markFilter  - used to identify mark glyphs
positions  - the glyph position array - updated as required
success  - output parameter set to an error code if the operation fails
See also:
LEGlyphFilter
Internal:
For internal use only.

virtual le_int32 LayoutEngine::computeGlyphs const LEUnicode    chars[],
le_int32    offset,
le_int32    count,
le_int32    max,
le_bool    rightToLeft,
LEGlyphID *&    glyphs,
le_int32 *&    charIndices,
LEErrorCode   success
[protected, virtual]
 

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
Output parameters:
Parameters:
glyphs  - the glyph index array
charIndices  - the character index array
success  - set to an error code if the operation fails
Returns:
the number of glyphs in the glyph index array
Internal:
For internal use only.

Reimplemented in GXLayoutEngine, OpenTypeLayoutEngine, and ThaiLayoutEngine.

void 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
Draft:
This API has been introduced in ICU 2.2. It is still in draft state and may be modified in a future release.

void 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
Draft:
This API has been introduced in ICU 2.2. It is still in draft state and may be modified in a future release.

Referenced by ICULayoutEngine::getCharIndices().

virtual UClassID LayoutEngine::getDynamicClassID void    const [inline, virtual]
 

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

Draft:
This API has been introduced in ICU 2.2. It is still in draft state and may be modified in a future release.

Reimplemented from UObject.

Reimplemented in ArabicOpenTypeLayoutEngine, GXLayoutEngine, HanOpenTypeLayoutEngine, IndicOpenTypeLayoutEngine, OpenTypeLayoutEngine, and ThaiLayoutEngine.

Definition at line 443 of file LayoutEngine.h.

virtual const void* LayoutEngine::getFontTable LETag    tableTag const [protected, virtual]
 

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.
Returns:
the address of the table.
Internal:
For internal use only.

le_int32 LayoutEngine::getGlyphCount   const [inline]
 

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
Draft:
This API has been introduced in ICU 2.2. It is still in draft state and may be modified in a future release.

Definition at line 326 of file LayoutEngine.h.

Referenced by ICULayoutEngine::countGlyphs().

void 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
Draft:
This API has been introduced in ICU 2.2. It is still in draft state and may be modified in a future release.

Referenced by ICULayoutEngine::getGlyphPosition().

void 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:
glyphs  - the destiniation position array
success  - set to an error code if the operation fails
Draft:
This API has been introduced in ICU 2.2. It is still in draft state and may be modified in a future release.

Referenced by ICULayoutEngine::getGlyphPositions().

virtual void 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
Draft:
This API has been introduced in ICU 2.2. It is still in draft state and may be modified in a future release.

void 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
Draft:
This API has been introduced in ICU 2.2. It is still in draft state and may be modified in a future release.

Referenced by ICULayoutEngine::getGlyphs().

UClassID LayoutEngine::getStaticClassID void    [inline, static]
 

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

Draft:
This API has been introduced in ICU 2.2. It is still in draft state and may be modified in a future release.

Reimplemented in ArabicOpenTypeLayoutEngine, GXLayoutEngine, HanOpenTypeLayoutEngine, IndicOpenTypeLayoutEngine, OpenTypeLayoutEngine, and ThaiLayoutEngine.

Definition at line 450 of file LayoutEngine.h.

Referenced by ThaiLayoutEngine::getDynamicClassID(), OpenTypeLayoutEngine::getDynamicClassID(), and GXLayoutEngine::getDynamicClassID().

virtual le_int32 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 method below.

Draft:
This API has been introduced in ICU 2.2. It is still in draft state and may be modified in a future release.

Referenced by ICULayoutEngine::layoutChars(), and ICULayoutEngine::layoutString().

LayoutEngine* 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
langaugeCode  - 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
Draft:
This API has been introduced in ICU 2.2. It is still in draft state and may be modified in a future release.

Referenced by ICULayoutEngine::createInstance().

virtual void LayoutEngine::mapCharsToGlyphs const LEUnicode    chars[],
le_int32    offset,
le_int32    count,
le_bool    reverse,
le_bool    mirror,
LEGlyphID *&    glyphs,
le_int32 *&    charIndices,
LEErrorCode   success
[protected, virtual]
 

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
Output parameters:
Parameters:
glyphs  - the glyph array
charIndices  - the character index array
success  - set to an error code if the operation fails
See also:
LEFontInstance
Internal:
For internal use only.

Reimplemented in UnicodeArabicOpenTypeLayoutEngine.

virtual void LayoutEngine::positionGlyphs const LEGlyphID    glyphs[],
le_int32    glyphCount,
float    x,
float    y,
float *&    positions,
LEErrorCode   success
[protected, virtual]
 

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:
glyphs  - the input glyph array
glyphCount  - the number of glyphs in the glyph array
x  - the starting X position
y  - the starting Y position
Output parameters:
Parameters:
positions  - the output X and Y positions (two entries per glyph)
Internal:
For internal use only.

virtual void LayoutEngine::reset void    [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)

Draft:
This API has been introduced in ICU 2.2. It is still in draft state and may be modified in a future release.

Reimplemented in OpenTypeLayoutEngine.

Referenced by ICULayoutEngine::layoutChars(), and ICULayoutEngine::layoutString().


Member Data Documentation

le_int32* LayoutEngine::fCharIndices [protected]
 

The character index array.

One entry for each output glyph, giving the index in the input character array of the character which corresponds to this glyph.

Internal:
For internal use only.

Definition at line 88 of file LayoutEngine.h.

const LEFontInstance* LayoutEngine::fFontInstance [protected]
 

The font instance for the text font.

See also:
LEFontInstance
Internal:
For internal use only.

Definition at line 107 of file LayoutEngine.h.

le_int32 LayoutEngine::fGlyphCount [protected]
 

The number of glyphs in the output.

Internal:
For internal use only.

Definition at line 73 of file LayoutEngine.h.

LEGlyphID* LayoutEngine::fGlyphs [protected]
 

The output glyph array.

Internal:
For internal use only.

Definition at line 80 of file LayoutEngine.h.

le_int32 LayoutEngine::fLanguageCode [protected]
 

The langauge code for the text.

See also:
ScriptAndLanguageTags.h for language codes.
Internal:
For internal use only.

Definition at line 125 of file LayoutEngine.h.

float* LayoutEngine::fPositions [protected]
 

The glyph position array.

There are two entries for each glyph giving the X and Y positions of the glyph. Thus, for glyph i, the X position is at index 2i, and the Y position is at index 2i + 1. There are also two entries for the X and Y position of the advance of the last glyph.

Internal:
For internal use only.

Definition at line 98 of file LayoutEngine.h.

le_int32 LayoutEngine::fScriptCode [protected]
 

The script code for the text.

See also:
ScriptAndLanguageTags.h for script codes.
Internal:
For internal use only.

Definition at line 116 of file LayoutEngine.h.

const char LayoutEngine::fgClassID [static, private]
 

The address of this static class variable serves as this class's ID for ICU "poor man's RTTI".

Reimplemented in ArabicOpenTypeLayoutEngine, GXLayoutEngine, HanOpenTypeLayoutEngine, IndicOpenTypeLayoutEngine, OpenTypeLayoutEngine, and ThaiLayoutEngine.

Definition at line 458 of file LayoutEngine.h.


The documentation for this class was generated from the following file:
Generated on Mon Nov 24 14:36:36 2003 for ICU 2.8 by doxygen1.2.11.1 written by Dimitri van Heesch, © 1997-2001