ICU 56.1: icu::LEFontInstance 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
icu::LEFontInstance Class Referenceabstract

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 icu::LEFontInstance:

## Public Member Functions
virtual | ~LEFontInstance ()
| This virtual destructor is here so that the subclass destructors can be invoked through the base class. More...
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. More...
virtual const void * | getFontTable (LETag tableTag, size_t &length) const =0
| This method reads a table from the font. More...
virtual le_bool | canDisplay (LEUnicode32 ch) const
| This method is used to determine if the font can render the given character. More...
virtual le_int32 | getUnitsPerEM () const =0
| This method returns the number of design units in the font's EM square. More...
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. More...
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. More...
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. More...
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. More...
virtual void | getGlyphAdvance (LEGlyphID glyph, LEPoint &advance) const =0
| This method gets the X and Y advance of a particular glyph, in pixels. More...
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. More...
virtual float | getXPixelsPerEm () const =0
| This method returns the width of the font's EM square in pixels. More...
virtual float | getYPixelsPerEm () const =0
| This method returns the height of the font's EM square in pixels. More...
virtual float | xUnitsToPoints (float xUnits) const
| This method converts font design units in the X direction to points. More...
virtual float | yUnitsToPoints (float yUnits) const
| This method converts font design units in the Y direction to points. More...
virtual void | unitsToPoints (LEPoint &units, LEPoint &points) const
| This method converts font design units to points. More...
virtual float | xPixelsToUnits (float xPixels) const
| This method converts pixels in the X direction to font design units. More...
virtual float | yPixelsToUnits (float yPixels) const
| This method converts pixels in the Y direction to font design units. More...
virtual void | pixelsToUnits (LEPoint &pixels, LEPoint &units) const
| This method converts pixels to font design units. More...
virtual float | getScaleFactorX () const =0
| Get the X scale factor from the font's transform. More...
virtual float | getScaleFactorY () const =0
| Get the Y scale factor from the font's transform. More...
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. More...
virtual le_int32 | getAscent () const =0
| Get the font's ascent. More...
virtual le_int32 | getDescent () const =0
| Get the font's descent. More...
virtual le_int32 | getLeading () const =0
| Get the font's leading. More...
virtual le_int32 | getLineHeight () const
| Get the line height required to display text in this font. 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 float | fixedToFloat (le_int32 fixed)
| This is a convenience method used to convert values in a 16.16 fixed point format to floating point. More...
static le_int32 | floatToFixed (float theFloat)
| This is a convenience method used to convert floating point values to 16.16 fixed point format. More...
static UClassID | getStaticClassID ()
| ICU "poor man's RTTI", returns a UClassID for this class. More...

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

Deprecated:
  ICU 54. See icu::LayoutEngine

Definition at line 81 of file LEFontInstance.h.

## Constructor & Destructor Documentation

virtual icu::LEFontInstance::~LEFontInstance | ( |  | ) |
| virtual

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

Deprecated:
  ICU 54. See icu::LayoutEngine

## Member Function Documentation

virtual le_bool icu::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.

Deprecated:
  ICU 54. See icu::LayoutEngine

float icu::LEFontInstance::fixedToFloat | ( | le_int32 | fixed | ) |
| inlinestatic

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

Deprecated:
  ICU 54. See icu::LayoutEngine

Definition at line 513 of file LEFontInstance.h.

le_int32 icu::LEFontInstance::floatToFixed | ( | float | theFloat | ) |
| inlinestatic

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

Deprecated:
  ICU 54. See icu::LayoutEngine

Definition at line 518 of file LEFontInstance.h.

virtual le_int32 icu::LEFontInstance::getAscent | ( |  | ) | const
| pure virtual

Get the font's ascent.

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

Deprecated:
  ICU 54. See icu::LayoutEngine

virtual le_int32 icu::LEFontInstance::getDescent | ( |  | ) | const
| pure virtual

Get the font's descent.

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

Deprecated:
  ICU 54. See icu::LayoutEngine

virtual UClassID icu::LEFontInstance::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::LEFontInstance::getFontTable | ( | LETag | tableTag,
|  | size_t & | length
| ) |  | 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')
  length | - ignored on entry, on exit will be the length of the table if known, or -1 if unknown.

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

Deprecated:
  ICU 54. See LayoutEngine

virtual void icu::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

Deprecated:
  ICU 54. See icu::LayoutEngine

virtual le_bool icu::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.

Deprecated:
  ICU 54. See icu::LayoutEngine

virtual le_int32 icu::LEFontInstance::getLeading | ( |  | ) | const
| pure virtual

Get the font's leading.

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

Deprecated:
  ICU 54. See icu::LayoutEngine

virtual le_int32 icu::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.

Deprecated:
  ICU 54. See icu::LayoutEngine

virtual float icu::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

Deprecated:
  ICU 54. See icu::LayoutEngine

virtual float icu::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

Deprecated:
  ICU 54. See icu::LayoutEngine

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

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

Deprecated:
  ICU 54. See icu::LayoutEngine

virtual const LEFontInstance* icu::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

Deprecated:
  ICU 54. See icu::LayoutEngine

virtual le_int32 icu::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.

Deprecated:
  ICU 54. See icu::LayoutEngine

virtual float icu::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

Deprecated:
  ICU 54. See icu::LayoutEngine

virtual float icu::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

Deprecated:
  ICU 54. See icu::LayoutEngine

virtual void icu::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

Deprecated:
  ICU 54. See icu::LayoutEngine

virtual LEGlyphID icu::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

Deprecated:
  ICU 54. See icu::LayoutEngine

virtual LEGlyphID icu::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

Deprecated:
  ICU 54. See icu::LayoutEngine

virtual LEGlyphID icu::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

Deprecated:
  ICU 54. See icu::LayoutEngine

virtual void icu::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

Deprecated:
  ICU 54. See icu::LayoutEngine

virtual void icu::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

Deprecated:
  ICU 54. See icu::LayoutEngine

virtual void icu::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

Deprecated:
  ICU 54. See icu::LayoutEngine

virtual float icu::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

Deprecated:
  ICU 54. See icu::LayoutEngine

virtual float icu::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

Deprecated:
  ICU 54. See icu::LayoutEngine

virtual float icu::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

Deprecated:
  ICU 54. See icu::LayoutEngine

virtual float icu::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

Deprecated:
  ICU 54. See icu::LayoutEngine

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

- LEFontInstance.h