# LEFontInstance Class Reference

This is a virtual base class that serves as the interface between a LayoutEngine and the platform font environment. More...

`#include <LEFontInstance.h>`

Inheritance diagram for LEFontInstance:

## Public Member Functions
virtual | ~LEFontInstance ()
| This virtual destructor is here so that the subclass destructors can be invoked through the base class.
virtual const LEFontInstance * | getSubFont (const LEUnicode chars[], le_int32 *offset, le_int32 limit, le_int32 script, LEErrorCode &success) const
| Get a physical font which can render the given text.
virtual const void * | getFontTable (LETag tableTag) const =0
| This method reads a table from the font.
virtual le_bool | canDisplay (LEUnicode32 ch) const
| This method is used to determine if the font can render the given character.
virtual le_int32 | getUnitsPerEM () const =0
| This method returns the number of design units in the font's EM square.
virtual void | mapCharsToGlyphs (const LEUnicode chars[], le_int32 offset, le_int32 count, le_bool reverse, const LECharMapper *mapper, le_bool filterZeroWidth, LEGlyphStorage &glyphStorage) const
| This method maps an array of character codes to an array of glyph indices, using the font's character to glyph map.
virtual LEGlyphID | mapCharToGlyph (LEUnicode32 ch, const LECharMapper *mapper, le_bool filterZeroWidth) const
| This method maps a single character to a glyph index, using the font's character to glyph map.
virtual LEGlyphID | mapCharToGlyph (LEUnicode32 ch, const LECharMapper *mapper) const
| This method maps a single character to a glyph index, using the font's character to glyph map.
virtual LEGlyphID | mapCharToGlyph (LEUnicode32 ch) const =0
| This method maps a single character to a glyph index, using the font's character to glyph map.
virtual void | getGlyphAdvance (LEGlyphID glyph, LEPoint &advance) const =0
| This method gets the X and Y advance of a particular glyph, in pixels.
virtual le_bool | getGlyphPoint (LEGlyphID glyph, le_int32 pointNumber, LEPoint &point) const =0
| This method gets the hinted X and Y pixel coordinates of a particular point in the outline of the given glyph.
virtual float | getXPixelsPerEm () const =0
| This method returns the width of the font's EM square in pixels.
virtual float | getYPixelsPerEm () const =0
| This method returns the height of the font's EM square in pixels.
virtual float | xUnitsToPoints (float xUnits) const
| This method converts font design units in the X direction to points.
virtual float | yUnitsToPoints (float yUnits) const
| This method converts font design units in the Y direction to points.
virtual void | unitsToPoints (LEPoint &units, LEPoint &points) const
| This method converts font design units to points.
virtual float | xPixelsToUnits (float xPixels) const
| This method converts pixels in the X direction to font design units.
virtual float | yPixelsToUnits (float yPixels) const
| This method converts pixels in the Y direction to font design units.
virtual void | pixelsToUnits (LEPoint &pixels, LEPoint &units) const
| This method converts pixels to font design units.
virtual float | getScaleFactorX () const =0
| Get the X scale factor from the font's transform.
virtual float | getScaleFactorY () const =0
| Get the Y scale factor from the font's transform.
virtual void | transformFunits (float xFunits, float yFunits, LEPoint &pixels) const
| This method transforms an X, Y point in font design units to a pixel coordinate, applying the font's transform.
virtual le_int32 | getAscent () const =0
| Get the font's ascent.
virtual le_int32 | getDescent () const =0
| Get the font's descent.
virtual le_int32 | getLeading () const =0
| Get the font's leading.
virtual le_int32 | getLineHeight () const
| Get the line height required to display text in this font.
virtual UClassID | getDynamicClassID () const
| ICU "poor man's RTTI", returns a UClassID for the actual class.
## Static Public Member Functions
static float | fixedToFloat (le_int32 fixed)
| This is a convenience method used to convert values in a 16.16 fixed point format to floating point.
static le_int32 | floatToFixed (float theFloat)
| This is a convenience method used to convert floating point values to 16.16 fixed point format.
static UClassID | getStaticClassID ()
| ICU "poor man's RTTI", returns a UClassID for this class.

## Detailed Description

This is a virtual base class that serves as the interface between a LayoutEngine and the platform font environment.

It allows a LayoutEngine to access font tables, do character to glyph mapping, and obtain metrics information without knowing any platform specific details. There are also a few utility methods for converting between points, pixels and funits. (font design units)

An instance of an `LEFontInstance` represents a font at a particular point size. Each instance can represent either a single physical font, or a composite font. A composite font is a collection of physical fonts, each of which contains a subset of the characters contained in the composite font.

Note: with the exception of `getSubFont`, the methods in this class only make sense for a physical font. If you have an `LEFontInstance` which represents a composite font you should only call the methods below which have an `LEGlyphID`, an `LEUnicode` or an `LEUnicode32` as one of the arguments because these can be used to select a particular subfont.

Subclasses which implement composite fonts should supply an implementation of these methods with some default behavior such as returning constant values, or using the values from the first subfont.

Stable:
  ICU 3.0

Definition at line 81 of file LEFontInstance.h.

## Constructor & Destructor Documentation

virtual LEFontInstance::~LEFontInstance | ( |  | ) | `[virtual]`

This virtual destructor is here so that the subclass destructors can be invoked through the base class.

Stable:
  ICU 2.8

## Member Function Documentation

virtual le_bool LEFontInstance::canDisplay | ( | LEUnicode32 | ch | ) | const`[virtual]`

This method is used to determine if the font can render the given character.

This can usually be done by looking the character up in the font's character to glyph mapping.

The default implementation of this method will return `TRUE` if `mapCharToGlyph(ch)` returns a non-zero value.

Parameters:

  | ch | - the character to be tested

Returns:
  `TRUE` if the font can render ch.

Stable:
  ICU 3.2

float LEFontInstance::fixedToFloat | ( | le_int32 | fixed | ) | `[inline, static]`

This is a convenience method used to convert values in a 16.16 fixed point format to floating point.

Parameters:

  | fixed | - the fixed point value

Returns:
  the floating point value

Stable:
  ICU 2.8

Definition at line 514 of file LEFontInstance.h.

le_int32 LEFontInstance::floatToFixed | ( | float | theFloat | ) | `[inline, static]`

This is a convenience method used to convert floating point values to 16.16 fixed point format.

Parameters:

  | theFloat | - the floating point value

Returns:
  the fixed point value

Stable:
  ICU 2.8

Definition at line 519 of file LEFontInstance.h.

virtual le_int32 LEFontInstance::getAscent | ( |  | ) | const`[pure virtual]`

Get the font's ascent.

Returns:
  the font's ascent, in points. This value will always be positive.

Stable:
  ICU 3.2

Referenced by ParagraphLayout::VisualRun::getAscent().

virtual le_int32 LEFontInstance::getDescent | ( |  | ) | const`[pure virtual]`

Get the font's descent.

Returns:
  the font's descent, in points. This value will always be positive.

Stable:
  ICU 3.2

Referenced by ParagraphLayout::VisualRun::getDescent().

virtual UClassID LEFontInstance::getDynamicClassID | ( |  | ) | const`[virtual]`

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

Stable:
  ICU 3.2

Implements UObject.

virtual const void* LEFontInstance::getFontTable | ( | LETag | tableTag | ) | const`[pure virtual]`

This method reads a table from the font.

Note that in general, it only makes sense to call this method on an `LEFontInstance` which represents a physical font - i.e. one which has been returned by `getSubFont()`. This is because each subfont in a composite font will have different tables, and there's no way to know which subfont to access.

Subclasses which represent composite fonts should always return `NULL`.

Parameters:

  | tableTag | - the four byte table tag. (e.g. 'cmap')

Returns:
  the address of the table in memory, or `NULL` if the table doesn't exist.

Stable:
  ICU 2.8

virtual void LEFontInstance::getGlyphAdvance | ( | LEGlyphID | glyph,
|  | LEPoint & | advance |
| ) |  |  | const`[pure virtual]`

This method gets the X and Y advance of a particular glyph, in pixels.

Parameters:

  | glyph | - the glyph index
  | advance | - the X and Y pixel values will be stored here

Stable:
  ICU 3.2

virtual le_bool LEFontInstance::getGlyphPoint | ( | LEGlyphID | glyph,
|  | le_int32 | pointNumber,
|  | LEPoint & | point |
| ) |  |  | const`[pure virtual]`

This method gets the hinted X and Y pixel coordinates of a particular point in the outline of the given glyph.

Parameters:

  | glyph | - the glyph index
  | pointNumber | - the number of the point
  | point | - the point's X and Y pixel values will be stored here

Returns:
  `TRUE` if the point coordinates could be stored.

Stable:
  ICU 2.8

virtual le_int32 LEFontInstance::getLeading | ( |  | ) | const`[pure virtual]`

Get the font's leading.

Returns:
  the font's leading, in points. This value will always be positive.

Stable:
  ICU 3.2

Referenced by ParagraphLayout::VisualRun::getLeading().

virtual le_int32 LEFontInstance::getLineHeight | ( |  | ) | const`[virtual]`

Get the line height required to display text in this font.

The default implementation of this method returns the sum of the ascent, descent, and leading.

Returns:
  the line height, in points. This vaule will always be positive.

Stable:
  ICU 3.2

virtual float LEFontInstance::getScaleFactorX | ( |  | ) | const`[pure virtual]`

Get the X scale factor from the font's transform.

The default implementation of `transformFunits()` will call this method.

Returns:
  the X scale factor.

See also:
  transformFunits

Stable:
  ICU 3.2

virtual float LEFontInstance::getScaleFactorY | ( |  | ) | const`[pure virtual]`

Get the Y scale factor from the font's transform.

The default implementation of `transformFunits()` will call this method.

Returns:
  the Yscale factor.

See also:
  transformFunits

Stable:
  ICU 3.2

static UClassID LEFontInstance::getStaticClassID | ( |  | ) | `[static]`

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

Stable:
  ICU 3.2

virtual const LEFontInstance* LEFontInstance::getSubFont | ( | const LEUnicode | chars[],
|  | le_int32 * | offset,
|  | le_int32 | limit,
|  | le_int32 | script,
|  | LEErrorCode & | success |
| ) |  |  | const`[virtual]`

Get a physical font which can render the given text.

For composite fonts, if there is no single physical font which can render all of the text, return a physical font which can render an initial substring of the text, and set the `offset` parameter to the end of that substring.

Internally, the LayoutEngine works with runs of text all in the same font and script, so it is best to call this method with text which is in a single script, passing the script code in as a hint. If you don't know the script of the text, you can use zero, which is the script code for characters used in more than one script.

The default implementation of this method is intended for instances of `LEFontInstance` which represent a physical font. It returns `this` and indicates that the entire string can be rendered.

This method will return a valid `LEFontInstance` unless you have passed illegal parameters, or an internal error has been encountered. For composite fonts, it may return the warning `LE_NO_SUBFONT_WARNING` to indicate that the returned font may not be able to render all of the text. Whenever a valid font is returned, the `offset` parameter will be advanced by at least one.

Subclasses which implement composite fonts must override this method. Where it makes sense, they should use the script code as a hint to render characters from the COMMON script in the font which is used for the given script. For example, if the input text is a series of Arabic words separated by spaces, and the script code passed in is `arabScriptCode` you should return the font used for Arabic characters for all of the input text, including the spaces. If, on the other hand, the input text contains characters which cannot be rendered by the font used for Arabic characters, but which can be rendered by another font, you should return that font for those characters.

Parameters:

  | chars | - the array of Unicode characters.
  | offset | - a pointer to the starting offset in the text. On exit this will be set the the limit offset of the text which can be rendered using the returned font.
  | limit | - the limit offset for the input text.
  | script | - the script hint.
  | success | - set to an error code if the arguments are illegal, or no font can be returned for some reason. May also be set to `LE_NO_SUBFONT_WARNING` if the subfont which was returned cannot render all of the text.

Returns:
  an `LEFontInstance` for the sub font which can render the characters, or `NULL` if there is an error.

See also:
  LEScripts.h

Stable:
  ICU 3.2

virtual le_int32 LEFontInstance::getUnitsPerEM | ( |  | ) | const`[pure virtual]`

This method returns the number of design units in the font's EM square.

Returns:
  the number of design units pre EM.

Stable:
  ICU 2.8

virtual float LEFontInstance::getXPixelsPerEm | ( |  | ) | const`[pure virtual]`

This method returns the width of the font's EM square in pixels.

Returns:
  the pixel width of the EM square

Stable:
  ICU 2.8

virtual float LEFontInstance::getYPixelsPerEm | ( |  | ) | const`[pure virtual]`

This method returns the height of the font's EM square in pixels.

Returns:
  the pixel height of the EM square

Stable:
  ICU 2.8

virtual void LEFontInstance::mapCharsToGlyphs | ( | const LEUnicode | chars[],
|  | le_int32 | offset,
|  | le_int32 | count,
|  | le_bool | reverse,
|  | const LECharMapper * | mapper,
|  | le_bool | filterZeroWidth,
|  | LEGlyphStorage & | glyphStorage |
| ) |  |  | const`[virtual]`

This method maps an array of character codes to an array of glyph indices, using the font's character to glyph map.

The default implementation iterates over all of the characters and calls `mapCharToGlyph(ch, mapper)` on each one. It also handles surrogate characters, storing the glyph ID for the high surrogate, and a deleted glyph (0xFFFF) for the low surrogate.

Most sublcasses will not need to implement this method.

Parameters:

  | chars | - the character array
  | offset | - the index of the first character
  | count | - the number of characters
  | reverse | - if `TRUE`, store the glyph indices in reverse order.
  | mapper | - the character mapper.
  | filterZeroWidth | - `TRUE` if ZWJ / ZWNJ characters should map to a glyph w/ no contours.
  | glyphStorage | - the object which contains the output glyph array

See also:
  LECharMapper

Stable:
  ICU 3.6

virtual LEGlyphID LEFontInstance::mapCharToGlyph | ( | LEUnicode32 | ch | ) | const`[pure virtual]`

This method maps a single character to a glyph index, using the font's character to glyph map.

There is no default implementation of this method because it requires information about the platform font implementation.

Parameters:

  | ch | - the character

Returns:
  the glyph index

Stable:
  ICU 3.2

virtual LEGlyphID LEFontInstance::mapCharToGlyph | ( | LEUnicode32 | ch,
|  | const LECharMapper * | mapper |
| ) |  |  | const`[virtual]`

This method maps a single character to a glyph index, using the font's character to glyph map.

The default implementation of this method calls the mapper, and then calls `mapCharToGlyph(mappedCh)`.

Parameters:

  | ch | - the character
  | mapper | - the character mapper

Returns:
  the glyph index

See also:
  LECharMapper

Stable:
  ICU 3.2

virtual LEGlyphID LEFontInstance::mapCharToGlyph | ( | LEUnicode32 | ch,
|  | const LECharMapper * | mapper,
|  | le_bool | filterZeroWidth |
| ) |  |  | const`[virtual]`

This method maps a single character to a glyph index, using the font's character to glyph map.

The default implementation of this method calls the mapper, and then calls `mapCharToGlyph(mappedCh)`.

Parameters:

  | ch | - the character
  | mapper | - the character mapper
  | filterZeroWidth | - `TRUE` if ZWJ / ZWNJ characters should map to a glyph w/ no contours.

Returns:
  the glyph index

See also:
  LECharMapper

Stable:
  ICU 3.6

virtual void LEFontInstance::pixelsToUnits | ( | LEPoint & | pixels,
|  | LEPoint & | units |
| ) |  |  | const`[virtual]`

This method converts pixels to font design units.

Parameters:

  | pixels | - X and Y pixel
  | units | - set to X and Y font design units

Stable:
  ICU 3.2

virtual void LEFontInstance::transformFunits | ( | float | xFunits,
|  | float | yFunits,
|  | LEPoint & | pixels |
| ) |  |  | const`[virtual]`

This method transforms an X, Y point in font design units to a pixel coordinate, applying the font's transform.

The default implementation of this method calls `getScaleFactorX()` and `getScaleFactorY()`.

Parameters:

  | xFunits | - the X coordinate in font design units
  | yFunits | - the Y coordinate in font design units
  | pixels | - the tranformed co-ordinate in pixels

See also:
  getScaleFactorX
  getScaleFactorY

Stable:
  ICU 3.2

virtual void LEFontInstance::unitsToPoints | ( | LEPoint & | units,
|  | LEPoint & | points |
| ) |  |  | const`[virtual]`

This method converts font design units to points.

Parameters:

  | units | - X and Y design units
  | points | - set to X and Y points

Stable:
  ICU 3.2

virtual float LEFontInstance::xPixelsToUnits | ( | float | xPixels | ) | const`[virtual]`

This method converts pixels in the X direction to font design units.

Parameters:

  | xPixels | - pixels in the X direction

Returns:
  font design units in the X direction

Stable:
  ICU 3.2

virtual float LEFontInstance::xUnitsToPoints | ( | float | xUnits | ) | const`[virtual]`

This method converts font design units in the X direction to points.

Parameters:

  | xUnits | - design units in the X direction

Returns:
  points in the X direction

Stable:
  ICU 3.2

virtual float LEFontInstance::yPixelsToUnits | ( | float | yPixels | ) | const`[virtual]`

This method converts pixels in the Y direction to font design units.

Parameters:

  | yPixels | - pixels in the Y direction

Returns:
  font design units in the Y direction

Stable:
  ICU 3.2

virtual float LEFontInstance::yUnitsToPoints | ( | float | yUnits | ) | const`[virtual]`

This method converts font design units in the Y direction to points.

Parameters:

  | yUnits | - design units in the Y direction

Returns:
  points in the Y direction

Stable:
  ICU 3.2

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

- LEFontInstance.h

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Defines