X-Git-Url: https://git.saurik.com/apple/icu.git/blobdiff_plain/b75a7d8f3b4adbae880cab104ce2c6a50eee4db2..fd0068a84e9996f225edba706498f6ed413d0673:/icuSources/layout/LEFontInstance.h

diff --git a/icuSources/layout/LEFontInstance.h b/icuSources/layout/LEFontInstance.h
index 3fc9a659..451d7f2e 100644
--- a/icuSources/layout/LEFontInstance.h
+++ b/icuSources/layout/LEFontInstance.h
@@ -1,8 +1,7 @@
 
 /*
- * @(#)LEFontInstance.h 1.3 00/03/15
  *
- * (C) Copyright IBM Corp. 1998-2003 - All Rights Reserved
+ * (C) Copyright IBM Corp. 1998-2006 - All Rights Reserved
  *
  */
 
@@ -10,26 +9,30 @@
 #define __LEFONTINSTANCE_H
 
 #include "LETypes.h"
+/**
+ * \file 
+ * \brief C++ API: Layout Engine Font Instance object
+ */
 
 U_NAMESPACE_BEGIN
 
 /**
- * Instances of this class are used by LEFontInstance::mapCharsToGlyphs and
- * LEFontInstance::mapCharToGlyph to adjust character codes before the character
+ * Instances of this class are used by <code>LEFontInstance::mapCharsToGlyphs</code> and
+ * <code>LEFontInstance::mapCharToGlyph</code> to adjust character codes before the character
  * to glyph mapping process. Examples of this are filtering out control characters
  * and character mirroring - replacing a character which has both a left and a right
  * hand form with the opposite form.
  *
- * @draft ICU 2.2
+ * @stable ICU 3.2
  */
 class LECharMapper /* not : public UObject because this is an interface/mixin class */
 {
 public:
     /**
      * Destructor.
-     * @draft ICU 2.4
+     * @stable ICU 3.2
      */
-    virtual inline ~LECharMapper() {};
+    virtual ~LECharMapper();
 
     /**
      * This method does the adjustments.
@@ -38,11 +41,19 @@ public:
      *
      * @return the adjusted character
      *
-     * @draft ICU 2.2
+     * @stable ICU 2.8
      */
     virtual LEUnicode32 mapChar(LEUnicode32 ch) const = 0;
 };
 
+/**
+ * This is a forward reference to the class which holds the per-glyph
+ * storage.
+ *
+ * @stable ICU 3.0
+ */
+class LEGlyphStorage;
+
 /**
  * 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
@@ -65,7 +76,7 @@ public:
  * methods with some default behavior such as returning constant values, or using the
  * values from the first subfont.
  *
- * @draft ICU 2.6
+ * @stable ICU 3.0
  */
 class U_LAYOUT_API LEFontInstance : public UObject
 {
@@ -75,9 +86,9 @@ public:
      * This virtual destructor is here so that the subclass
      * destructors can be invoked through the base class.
      *
-     * @draft ICU 2.2
+     * @stable ICU 2.8
      */
-    virtual inline ~LEFontInstance() {};
+    virtual ~LEFontInstance();
 
     /**
      * Get a physical font which can render the given text. For composite fonts,
@@ -128,7 +139,7 @@ public:
      *
      * @see LEScripts.h
      *
-     * @draft ICU 2.6
+     * @stable ICU 3.2
      */
     virtual const LEFontInstance *getSubFont(const LEUnicode chars[], le_int32 *offset, le_int32 limit, le_int32 script, LEErrorCode &success) const;
 
@@ -150,7 +161,7 @@ public:
      * @return the address of the table in memory, or <code>NULL</code>
      *         if the table doesn't exist.
      *
-     * @draft ICU 2.2
+     * @stable ICU 2.8
      */
     virtual const void *getFontTable(LETag tableTag) const = 0;
 
@@ -161,14 +172,14 @@ public:
      * to glyph mapping.
      *
      * The default implementation of this method will return
-     * <code>true</code> if <code>mapCharToGlyph(ch)</code>
+     * <code>TRUE</code> if <code>mapCharToGlyph(ch)</code>
      * returns a non-zero value.
      *
      * @param ch - the character to be tested
      *
-     * @return true if the font can render ch.
+     * @return <code>TRUE</code> if the font can render ch.
      *
-     * @draft ICU 2.6
+     * @stable ICU 3.2
      */
     virtual le_bool canDisplay(LEUnicode32 ch) const;
 
@@ -178,7 +189,7 @@ public:
      *
      * @return the number of design units pre EM.
      *
-     * @draft ICU 2.2
+     * @stable ICU 2.8
      */
     virtual le_int32 getUnitsPerEM() const = 0;
 
@@ -186,18 +197,26 @@ public:
      * 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
+     * <code>mapCharToGlyph(ch, mapper)</code> 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.
+     *
      * @param chars - the character array
      * @param offset - the index of the first character
      * @param count - the number of characters
-     * @param reverse - if true, store the glyph indices in reverse order.
+     * @param reverse - if <code>TRUE</code>, store the glyph indices in reverse order.
      * @param mapper - the character mapper.
-     * @param glyphs - the output glyph array
+     * @param filterZeroWidth - <code>TRUE</code> if ZWJ / ZWNJ characters should map to a glyph w/ no contours.
+     * @param glyphStorage - the object which contains the output glyph array
      *
      * @see LECharMapper
      *
-     * @draft ICU 2.6
+     * @draft ICU 3.6
      */
-    virtual void mapCharsToGlyphs(const LEUnicode chars[], le_int32 offset, le_int32 count, le_bool reverse, const LECharMapper *mapper, LEGlyphID glyphs[]) const;
+    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 a single character to a glyph index, using the
@@ -206,12 +225,30 @@ public:
      *
      * @param ch - the character
      * @param mapper - the character mapper
+     * @param filterZeroWidth - <code>TRUE</code> if ZWJ / ZWNJ characters should map to a glyph w/ no contours.
      *
      * @return the glyph index
      *
      * @see LECharMapper
      *
-     * @draft ICU 2.6
+     * @draft ICU 3.6
+     */
+    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. The default implementation of this
+     * method calls the mapper, and then calls <code>mapCharToGlyph(mappedCh)</code>.
+     *
+     * @param ch - the character
+     * @param mapper - the character mapper
+     *
+     * @return the glyph index
+     *
+     * @see LECharMapper
+     *
+     * @stable ICU 3.2
      */
     virtual LEGlyphID mapCharToGlyph(LEUnicode32 ch, const LECharMapper *mapper) const;
 
@@ -225,7 +262,7 @@ public:
      *
      * @return the glyph index
      *
-     * @draft ICU 2.6
+     * @stable ICU 3.2
      */
     virtual LEGlyphID mapCharToGlyph(LEUnicode32 ch) const = 0;
 
@@ -239,7 +276,7 @@ public:
      * @param glyph - the glyph index
      * @param advance - the X and Y pixel values will be stored here
      *
-     * @draft ICU 2.2
+     * @stable ICU 3.2
      */
     virtual void getGlyphAdvance(LEGlyphID glyph, LEPoint &advance) const = 0;
 
@@ -251,9 +288,9 @@ public:
      * @param pointNumber - the number of the point
      * @param point - the point's X and Y pixel values will be stored here
      *
-     * @return true if the point coordinates could be stored.
+     * @return <code>TRUE</code> if the point coordinates could be stored.
      *
-     * @draft ICU 2.2
+     * @stable ICU 2.8
      */
     virtual le_bool getGlyphPoint(LEGlyphID glyph, le_int32 pointNumber, LEPoint &point) const = 0;
 
@@ -263,7 +300,7 @@ public:
      *
      * @return the pixel width of the EM square
      *
-     * @draft ICU 2.2
+     * @stable ICU 2.8
      */
     virtual float getXPixelsPerEm() const = 0;
 
@@ -273,7 +310,7 @@ public:
      *
      * @return the pixel height of the EM square
      *
-     * @draft ICU 2.2
+     * @stable ICU 2.8
      */
     virtual float getYPixelsPerEm() const = 0;
 
@@ -285,7 +322,7 @@ public:
      *
      * @return points in the X direction
      *
-     * @draft ICU 2.6
+     * @stable ICU 3.2
      */
     virtual float xUnitsToPoints(float xUnits) const;
 
@@ -297,7 +334,7 @@ public:
      *
      * @return points in the Y direction
      *
-     * @draft ICU 2.6
+     * @stable ICU 3.2
      */
     virtual float yUnitsToPoints(float yUnits) const;
 
@@ -307,7 +344,7 @@ public:
      * @param units - X and Y design units
      * @param points - set to X and Y points
      *
-     * @draft ICU 2.6
+     * @stable ICU 3.2
      */
     virtual void unitsToPoints(LEPoint &units, LEPoint &points) const;
 
@@ -319,7 +356,7 @@ public:
      *
      * @return font design units in the X direction
      *
-     * @draft ICU 2.6
+     * @stable ICU 3.2
      */
     virtual float xPixelsToUnits(float xPixels) const;
 
@@ -331,7 +368,7 @@ public:
      *
      * @return font design units in the Y direction
      *
-     * @draft ICU 2.6
+     * @stable ICU 3.2
      */
     virtual float yPixelsToUnits(float yPixels) const;
 
@@ -341,7 +378,7 @@ public:
      * @param pixels - X and Y pixel
      * @param units - set to X and Y font design units
      *
-     * @draft ICU 2.6
+     * @stable ICU 3.2
      */
     virtual void pixelsToUnits(LEPoint &pixels, LEPoint &units) const;
 
@@ -354,7 +391,7 @@ public:
      *
      * @see transformFunits
      *
-     * @draft ICU 2.6
+     * @stable ICU 3.2
      */
     virtual float getScaleFactorX() const = 0;
 
@@ -366,7 +403,7 @@ public:
      *
      * @see transformFunits
      *
-     * @draft ICU 2.6
+     * @stable ICU 3.2
      */
     virtual float getScaleFactorY() const = 0;
 
@@ -383,7 +420,7 @@ public:
      * @see getScaleFactorX
      * @see getScaleFactorY
      *
-     * @draft ICU 2.6
+     * @stable ICU 3.2
      */
     virtual void transformFunits(float xFunits, float yFunits, LEPoint &pixels) const;
 
@@ -395,9 +432,9 @@ public:
      *
      * @return the floating point value
      *
-     * @draft ICU 2.2
+     * @stable ICU 2.8
      */
-    static float fixedToFloat(le_int32 fixed);
+    static inline float fixedToFloat(le_int32 fixed);
 
     /**
      * This is a convenience method used to convert
@@ -407,9 +444,9 @@ public:
      *
      * @return the fixed point value
      *
-     * @draft ICU 2.2
+     * @stable ICU 2.8
      */
-    static le_int32 floatToFixed(float theFloat);
+    static inline le_int32 floatToFixed(float theFloat);
 
     //
     // These methods won't ever be called by the LayoutEngine,
@@ -423,7 +460,7 @@ public:
      * @return the font's ascent, in points. This value
      * will always be positive.
      *
-     * @draft ICU 2.6
+     * @stable ICU 3.2
      */
     virtual le_int32 getAscent() const = 0;
 
@@ -433,7 +470,7 @@ public:
      * @return the font's descent, in points. This value
      * will always be positive.
      *
-     * @draft ICU 2.6
+     * @stable ICU 3.2
      */
     virtual le_int32 getDescent() const = 0;
 
@@ -443,7 +480,7 @@ public:
      * @return the font's leading, in points. This value
      * will always be positive.
      *
-     * @draft ICU 2.6
+     * @stable ICU 3.2
      */
     virtual le_int32 getLeading() const = 0;
 
@@ -455,76 +492,26 @@ public:
      * @return the line height, in points. This vaule will
      * always be positive.
      *
-     * @draft ICU 2.6
+     * @stable ICU 3.2
      */
     virtual le_int32 getLineHeight() const;
 
     /**
      * ICU "poor man's RTTI", returns a UClassID for the actual class.
      *
-     * @draft ICU 2.6
+     * @stable ICU 3.2
      */
-    virtual inline UClassID getDynamicClassID() const { return getStaticClassID(); }
+    virtual UClassID getDynamicClassID() const;
 
     /**
      * ICU "poor man's RTTI", returns a UClassID for this class.
      *
-     * @draft ICU 2.6
+     * @stable ICU 3.2
      */
-    static inline UClassID getStaticClassID() { return (UClassID)&fgClassID; }
-
-private:
+    static UClassID getStaticClassID();
 
-    /**
-     * The address of this static class variable serves as this class's ID
-     * for ICU "poor man's RTTI".
-     */
-    static const char fgClassID;
 };
 
-inline le_bool LEFontInstance::canDisplay(LEUnicode32 ch) const
-{
-    return LE_GET_GLYPH(mapCharToGlyph(ch)) != 0;
-}
-
-inline float LEFontInstance::xUnitsToPoints(float xUnits) const
-{
-    return (xUnits * getXPixelsPerEm()) / (float) getUnitsPerEM();
-}
-
-inline float LEFontInstance::yUnitsToPoints(float yUnits) const
-{
-    return (yUnits * getYPixelsPerEm()) / (float) getUnitsPerEM();
-}
-
-inline void LEFontInstance::unitsToPoints(LEPoint &units, LEPoint &points) const
-{
-    points.fX = xUnitsToPoints(units.fX);
-    points.fY = yUnitsToPoints(units.fY);
-}
-
-inline float LEFontInstance::xPixelsToUnits(float xPixels) const
-{
-    return (xPixels * getUnitsPerEM()) / (float) getXPixelsPerEm();
-}
-
-inline float LEFontInstance::yPixelsToUnits(float yPixels) const
-{
-    return (yPixels * getUnitsPerEM()) / (float) getYPixelsPerEm();
-}
-
-inline void LEFontInstance::pixelsToUnits(LEPoint &pixels, LEPoint &units) const
-{
-    units.fX = xPixelsToUnits(pixels.fX);
-    units.fY = yPixelsToUnits(pixels.fY);
-}
-
-inline void LEFontInstance::transformFunits(float xFunits, float yFunits, LEPoint &pixels) const
-{
-    pixels.fX = xUnitsToPoints(xFunits) * getScaleFactorX();
-    pixels.fY = yUnitsToPoints(yFunits) * getScaleFactorY();
-}
-
 inline float LEFontInstance::fixedToFloat(le_int32 fixed)
 {
     return (float) (fixed / 65536.0);
@@ -535,11 +522,6 @@ inline le_int32 LEFontInstance::floatToFixed(float theFloat)
     return (le_int32) (theFloat * 65536.0);
 }
 
-inline le_int32 LEFontInstance::getLineHeight() const
-{
-    return getAscent() + getDescent() + getLeading();
-}
-
 U_NAMESPACE_END
 #endif