1 

     2 /*

     3  *

     4  * (C) Copyright IBM Corp. 1998-2005 - All Rights Reserved

     5  *

     6  */

     7 

     8 #ifndef __LEFONTINSTANCE_H

     9 #define __LEFONTINSTANCE_H

    10 

    11 #include "LETypes.h"

    12 /**

    13  * \file 

    14  * \brief C++ API: Layout Engine Font Instance object

    15  */

    16 

    17 U_NAMESPACE_BEGIN

    18 

    19 /**

    20  * Instances of this class are used by <code>LEFontInstance::mapCharsToGlyphs</code> and

    21  * <code>LEFontInstance::mapCharToGlyph</code> to adjust character codes before the character

    22  * to glyph mapping process. Examples of this are filtering out control characters

    23  * and character mirroring - replacing a character which has both a left and a right

    24  * hand form with the opposite form.

    25  *

    26  * @stable ICU 3.2

    27  */

    28 class LECharMapper /* not : public UObject because this is an interface/mixin class */

    29 {

    30 public:

    31     /**

    32      * Destructor.

    33      * @stable ICU 3.2

    34      */

    35     virtual inline ~LECharMapper() {};

    36 

    37     /**

    38      * This method does the adjustments.

    39      *

    40      * @param ch - the input character

    41      *

    42      * @return the adjusted character

    43      *

    44      * @stable ICU 2.8

    45      */

    46     virtual LEUnicode32 mapChar(LEUnicode32 ch) const = 0;

    47 };

    48 

    49 /**

    50  * This is a forward reference to the class which holds the per-glyph

    51  * storage.

    52  *

    53  * @draft ICU 3.0

    54  */

    55 class LEGlyphStorage;

    56 

    57 /**

    58  * This is a virtual base class that serves as the interface between a LayoutEngine

    59  * and the platform font environment. It allows a LayoutEngine to access font tables, do

    60  * character to glyph mapping, and obtain metrics information without knowing any platform

    61  * specific details. There are also a few utility methods for converting between points,

    62  * pixels and funits. (font design units)

    63  *

    64  * An instance of an <code>LEFontInstance</code> represents a font at a particular point

    65  * size. Each instance can represent either a single physical font, or a composite font.

    66  * A composite font is a collection of physical fonts, each of which contains a subset of

    67  * the characters contained in the composite font.

    68  *

    69  * Note: with the exception of <code>getSubFont</code>, the methods in this class only

    70  * make sense for a physical font. If you have an <code>LEFontInstance</code> which

    71  * represents a composite font you should only call the methods below which have

    72  * an <code>LEGlyphID</code>, an <code>LEUnicode</code> or an <code>LEUnicode32</code>

    73  * as one of the arguments because these can be used to select a particular subfont.

    74  *

    75  * Subclasses which implement composite fonts should supply an implementation of these

    76  * methods with some default behavior such as returning constant values, or using the

    77  * values from the first subfont.

    78  *

    79  * @draft ICU 3.0

    80  */

    81 class U_LAYOUT_API LEFontInstance : public UObject

    82 {

    83 public:

    84 

    85     /**

    86      * This virtual destructor is here so that the subclass

    87      * destructors can be invoked through the base class.

    88      *

    89      * @stable ICU 2.8

    90      */

    91     virtual inline ~LEFontInstance() {};

    92 

    93     /**

    94      * Get a physical font which can render the given text. For composite fonts,

    95      * if there is no single physical font which can render all of the text,

    96      * return a physical font which can render an initial substring of the text,

    97      * and set the <code>offset</code> parameter to the end of that substring.

    98      *

    99      * Internally, the LayoutEngine works with runs of text all in the same

   100      * font and script, so it is best to call this method with text which is

   101      * in a single script, passing the script code in as a hint. If you don't

   102      * know the script of the text, you can use zero, which is the script code

   103      * for characters used in more than one script.

   104      *

   105      * The default implementation of this method is intended for instances of

   106      * <code>LEFontInstance</code> which represent a physical font. It returns

   107      * <code>this</code> and indicates that the entire string can be rendered.

   108      *

   109      * This method will return a valid <code>LEFontInstance</code> unless you

   110      * have passed illegal parameters, or an internal error has been encountered. 

   111      * For composite fonts, it may return the warning <code>LE_NO_SUBFONT_WARNING</code>

   112      * to indicate that the returned font may not be able to render all of

   113      * the text. Whenever a valid font is returned, the <code>offset</code> parameter

   114      * will be advanced by at least one.

   115      *

   116      * Subclasses which implement composite fonts must override this method.

   117      * Where it makes sense, they should use the script code as a hint to render

   118      * characters from the COMMON script in the font which is used for the given

   119      * script. For example, if the input text is a series of Arabic words separated

   120      * by spaces, and the script code passed in is <code>arabScriptCode</code> you

   121      * should return the font used for Arabic characters for all of the input text,

   122      * including the spaces. If, on the other hand, the input text contains characters

   123      * which cannot be rendered by the font used for Arabic characters, but which can

   124      * be rendered by another font, you should return that font for those characters.

   125      *

   126      * @param chars   - the array of Unicode characters.

   127      * @param offset  - a pointer to the starting offset in the text. On exit this

   128      *                  will be set the the limit offset of the text which can be

   129      *                  rendered using the returned font.

   130      * @param limit   - the limit offset for the input text.

   131      * @param script  - the script hint.

   132      * @param success - set to an error code if the arguments are illegal, or no font

   133      *                  can be returned for some reason. May also be set to

   134      *                  <code>LE_NO_SUBFONT_WARNING</code> if the subfont which

   135      *                  was returned cannot render all of the text.

   136      *

   137      * @return an <code>LEFontInstance</code> for the sub font which can render the characters, or

   138      *         <code>NULL</code> if there is an error.

   139      *

   140      * @see LEScripts.h

   141      *

   142      * @stable ICU 3.2

   143      */

   144     virtual const LEFontInstance *getSubFont(const LEUnicode chars[], le_int32 *offset, le_int32 limit, le_int32 script, LEErrorCode &success) const;

   145 

   146     //

   147     // Font file access

   148     //

   149 

   150     /**

   151      * This method reads a table from the font. Note that in general,

   152      * it only makes sense to call this method on an <code>LEFontInstance</code>

   153      * which represents a physical font - i.e. one which has been returned by

   154      * <code>getSubFont()</code>. This is because each subfont in a composite font

   155      * will have different tables, and there's no way to know which subfont to access.

   156      *

   157      * Subclasses which represent composite fonts should always return <code>NULL</code>.

   158      *

   159      * @param tableTag - the four byte table tag. (e.g. 'cmap') 

   160      *

   161      * @return the address of the table in memory, or <code>NULL</code>

   162      *         if the table doesn't exist.

   163      *

   164      * @stable ICU 2.8

   165      */

   166     virtual const void *getFontTable(LETag tableTag) const = 0;

   167 

   168     /**

   169      * This method is used to determine if the font can

   170      * render the given character. This can usually be done

   171      * by looking the character up in the font's character

   172      * to glyph mapping.

   173      *

   174      * The default implementation of this method will return

   175      * <code>TRUE</code> if <code>mapCharToGlyph(ch)</code>

   176      * returns a non-zero value.

   177      *

   178      * @param ch - the character to be tested

   179      *

   180      * @return <code>TRUE</code> if the font can render ch.

   181      *

   182      * @stable ICU 3.2

   183      */

   184     virtual inline le_bool canDisplay(LEUnicode32 ch) const;

   185 

   186     /**

   187      * This method returns the number of design units in

   188      * the font's EM square.

   189      *

   190      * @return the number of design units pre EM.

   191      *

   192      * @stable ICU 2.8

   193      */

   194     virtual le_int32 getUnitsPerEM() const = 0;

   195 

   196     /**

   197      * This method maps an array of character codes to an array of glyph

   198      * indices, using the font's character to glyph map.

   199      *

   200      * The default implementation iterates over all of the characters and calls

   201      * <code>mapCharToGlyph(ch, mapper)</code> on each one. It also handles surrogate

   202      * characters, storing the glyph ID for the high surrogate, and a deleted glyph (0xFFFF)

   203      * for the low surrogate.

   204      *

   205      * Most sublcasses will not need to implement this method.

   206      *

   207      * @param chars - the character array

   208      * @param offset - the index of the first character

   209      * @param count - the number of characters

   210      * @param reverse - if <code>TRUE</code>, store the glyph indices in reverse order.

   211      * @param mapper - the character mapper.

   212      * @param glyphStorage - the object which contains the output glyph array

   213      *

   214      * @see LECharMapper

   215      *

   216      * @draft ICU 3.0

   217      */

   218     virtual void mapCharsToGlyphs(const LEUnicode chars[], le_int32 offset, le_int32 count, le_bool reverse, const LECharMapper *mapper, LEGlyphStorage &glyphStorage) const;

   219 

   220     /**

   221      * This method maps a single character to a glyph index, using the

   222      * font's character to glyph map. The default implementation of this

   223      * method calls the mapper, and then calls <code>mapCharToGlyph(mappedCh)</code>.

   224      *

   225      * @param ch - the character

   226      * @param mapper - the character mapper

   227      *

   228      * @return the glyph index

   229      *

   230      * @see LECharMapper

   231      *

   232      * @stable ICU 3.2

   233      */

   234     virtual LEGlyphID mapCharToGlyph(LEUnicode32 ch, const LECharMapper *mapper) const;

   235 

   236     /**

   237      * This method maps a single character to a glyph index, using the

   238      * font's character to glyph map. There is no default implementation

   239      * of this method because it requires information about the platform

   240      * font implementation.

   241      *

   242      * @param ch - the character

   243      *

   244      * @return the glyph index

   245      *

   246      * @stable ICU 3.2

   247      */

   248     virtual LEGlyphID mapCharToGlyph(LEUnicode32 ch) const = 0;

   249 

   250     //

   251     // Metrics

   252     //

   253 

   254     /**

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

   256      *

   257      * @param glyph - the glyph index

   258      * @param advance - the X and Y pixel values will be stored here

   259      *

   260      * @stable ICU 3.2

   261      */

   262     virtual void getGlyphAdvance(LEGlyphID glyph, LEPoint &advance) const = 0;

   263 

   264     /**

   265      * This method gets the hinted X and Y pixel coordinates of a particular

   266      * point in the outline of the given glyph.

   267      *

   268      * @param glyph - the glyph index

   269      * @param pointNumber - the number of the point

   270      * @param point - the point's X and Y pixel values will be stored here

   271      *

   272      * @return <code>TRUE</code> if the point coordinates could be stored.

   273      *

   274      * @stable ICU 2.8

   275      */

   276     virtual le_bool getGlyphPoint(LEGlyphID glyph, le_int32 pointNumber, LEPoint &point) const = 0;

   277 

   278     /**

   279      * This method returns the width of the font's EM square

   280      * in pixels.

   281      *

   282      * @return the pixel width of the EM square

   283      *

   284      * @stable ICU 2.8

   285      */

   286     virtual float getXPixelsPerEm() const = 0;

   287 

   288     /**

   289      * This method returns the height of the font's EM square

   290      * in pixels.

   291      *

   292      * @return the pixel height of the EM square

   293      *

   294      * @stable ICU 2.8

   295      */

   296     virtual float getYPixelsPerEm() const = 0;

   297 

   298     /**

   299      * This method converts font design units in the

   300      * X direction to points.

   301      *

   302      * @param xUnits - design units in the X direction

   303      *

   304      * @return points in the X direction

   305      *

   306      * @stable ICU 3.2

   307      */

   308     virtual inline float xUnitsToPoints(float xUnits) const;

   309 

   310     /**

   311      * This method converts font design units in the

   312      * Y direction to points.

   313      *

   314      * @param yUnits - design units in the Y direction

   315      *

   316      * @return points in the Y direction

   317      *

   318      * @stable ICU 3.2

   319      */

   320     virtual inline float yUnitsToPoints(float yUnits) const;

   321 

   322     /**

   323      * This method converts font design units to points.

   324      *

   325      * @param units - X and Y design units

   326      * @param points - set to X and Y points

   327      *

   328      * @stable ICU 3.2

   329      */

   330     virtual inline void unitsToPoints(LEPoint &units, LEPoint &points) const;

   331 

   332     /**

   333      * This method converts pixels in the

   334      * X direction to font design units.

   335      *

   336      * @param xPixels - pixels in the X direction

   337      *

   338      * @return font design units in the X direction

   339      *

   340      * @stable ICU 3.2

   341      */

   342     virtual inline float xPixelsToUnits(float xPixels) const;

   343 

   344     /**

   345      * This method converts pixels in the

   346      * Y direction to font design units.

   347      *

   348      * @param yPixels - pixels in the Y direction

   349      *

   350      * @return font design units in the Y direction

   351      *

   352      * @stable ICU 3.2

   353      */

   354     virtual inline float yPixelsToUnits(float yPixels) const;

   355 

   356     /**

   357      * This method converts pixels to font design units.

   358      *

   359      * @param pixels - X and Y pixel

   360      * @param units - set to X and Y font design units

   361      *

   362      * @stable ICU 3.2

   363      */

   364     virtual inline void pixelsToUnits(LEPoint &pixels, LEPoint &units) const;

   365 

   366     /**

   367      * Get the X scale factor from the font's transform. The default

   368      * implementation of <code>transformFunits()</code> will call this method.

   369      *

   370      * @return the X scale factor.

   371      *

   372      *

   373      * @see transformFunits

   374      *

   375      * @stable ICU 3.2

   376      */

   377     virtual float getScaleFactorX() const = 0;

   378 

   379     /**

   380      * Get the Y scale factor from the font's transform. The default

   381      * implementation of <code>transformFunits()</code> will call this method.

   382      *

   383      * @return the Yscale factor.

   384      *

   385      * @see transformFunits

   386      *

   387      * @stable ICU 3.2

   388      */

   389     virtual float getScaleFactorY() const = 0;

   390 

   391     /**

   392      * This method transforms an X, Y point in font design units to a

   393      * pixel coordinate, applying the font's transform. The default

   394      * implementation of this method calls <code>getScaleFactorX()</code>

   395      * and <code>getScaleFactorY()</code>.

   396      *

   397      * @param xFunits - the X coordinate in font design units

   398      * @param yFunits - the Y coordinate in font design units

   399      * @param pixels - the tranformed co-ordinate in pixels

   400      *

   401      * @see getScaleFactorX

   402      * @see getScaleFactorY

   403      *

   404      * @stable ICU 3.2

   405      */

   406     virtual inline void transformFunits(float xFunits, float yFunits, LEPoint &pixels) const;

   407 

   408     /**

   409      * This is a convenience method used to convert

   410      * values in a 16.16 fixed point format to floating point.

   411      *

   412      * @param fixed - the fixed point value

   413      *

   414      * @return the floating point value

   415      *

   416      * @stable ICU 2.8

   417      */

   418     static inline float fixedToFloat(le_int32 fixed);

   419 

   420     /**

   421      * This is a convenience method used to convert

   422      * floating point values to 16.16 fixed point format.

   423      *

   424      * @param theFloat - the floating point value

   425      *

   426      * @return the fixed point value

   427      *

   428      * @stable ICU 2.8

   429      */

   430     static inline le_int32 floatToFixed(float theFloat);

   431 

   432     //

   433     // These methods won't ever be called by the LayoutEngine,

   434     // but are useful for clients of <code>LEFontInstance</code> who

   435     // need to render text.

   436     //

   437 

   438     /**

   439      * Get the font's ascent.

   440      *

   441      * @return the font's ascent, in points. This value

   442      * will always be positive.

   443      *

   444      * @stable ICU 3.2

   445      */

   446     virtual le_int32 getAscent() const = 0;

   447 

   448     /**

   449      * Get the font's descent.

   450      *

   451      * @return the font's descent, in points. This value

   452      * will always be positive.

   453      *

   454      * @stable ICU 3.2

   455      */

   456     virtual le_int32 getDescent() const = 0;

   457 

   458     /**

   459      * Get the font's leading.

   460      *

   461      * @return the font's leading, in points. This value

   462      * will always be positive.

   463      *

   464      * @stable ICU 3.2

   465      */

   466     virtual le_int32 getLeading() const = 0;

   467 

   468     /**

   469      * Get the line height required to display text in

   470      * this font. The default implementation of this method

   471      * returns the sum of the ascent, descent, and leading.

   472      *

   473      * @return the line height, in points. This vaule will

   474      * always be positive.

   475      *

   476      * @stable ICU 3.2

   477      */

   478     virtual le_int32 getLineHeight() const;

   479 

   480     /**

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

   482      *

   483      * @stable ICU 3.2

   484      */

   485     virtual UClassID getDynamicClassID() const;

   486 

   487     /**

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

   489      *

   490      * @stable ICU 3.2

   491      */

   492     static UClassID getStaticClassID();

   493 

   494 };

   495 

   496 inline le_bool LEFontInstance::canDisplay(LEUnicode32 ch) const

   497 {

   498     return LE_GET_GLYPH(mapCharToGlyph(ch)) != 0;

   499 }

   500 

   501 inline float LEFontInstance::xUnitsToPoints(float xUnits) const

   502 {

   503     return (xUnits * getXPixelsPerEm()) / (float) getUnitsPerEM();

   504 }

   505 

   506 inline float LEFontInstance::yUnitsToPoints(float yUnits) const

   507 {

   508     return (yUnits * getYPixelsPerEm()) / (float) getUnitsPerEM();

   509 }

   510 

   511 inline void LEFontInstance::unitsToPoints(LEPoint &units, LEPoint &points) const

   512 {

   513     points.fX = xUnitsToPoints(units.fX);

   514     points.fY = yUnitsToPoints(units.fY);

   515 }

   516 

   517 inline float LEFontInstance::xPixelsToUnits(float xPixels) const

   518 {

   519     return (xPixels * getUnitsPerEM()) / (float) getXPixelsPerEm();

   520 }

   521 

   522 inline float LEFontInstance::yPixelsToUnits(float yPixels) const

   523 {

   524     return (yPixels * getUnitsPerEM()) / (float) getYPixelsPerEm();

   525 }

   526 

   527 inline void LEFontInstance::pixelsToUnits(LEPoint &pixels, LEPoint &units) const

   528 {

   529     units.fX = xPixelsToUnits(pixels.fX);

   530     units.fY = yPixelsToUnits(pixels.fY);

   531 }

   532 

   533 inline void LEFontInstance::transformFunits(float xFunits, float yFunits, LEPoint &pixels) const

   534 {

   535     pixels.fX = xUnitsToPoints(xFunits) * getScaleFactorX();

   536     pixels.fY = yUnitsToPoints(yFunits) * getScaleFactorY();

   537 }

   538 

   539 inline float LEFontInstance::fixedToFloat(le_int32 fixed)

   540 {

   541     return (float) (fixed / 65536.0);

   542 }

   543 

   544 inline le_int32 LEFontInstance::floatToFixed(float theFloat)

   545 {

   546     return (le_int32) (theFloat * 65536.0);

   547 }

   548 

   549 inline le_int32 LEFontInstance::getLineHeight() const

   550 {

   551     return getAscent() + getDescent() + getLeading();

   552 }

   553 

   554 U_NAMESPACE_END

   555 #endif

   556 

   557