Home | History | Annotate | Download | only in layout
      1 /*
      2  * (C) Copyright IBM Corp. and others 1998-2014 - All Rights Reserved
      3  */
      4 
      5 #ifndef __LAYOUTENGINE_H
      6 #define __LAYOUTENGINE_H
      7 
      8 #include "LETypes.h"
      9 
     10 /**
     11  * \file
     12  * \brief C++ API: DEPRECATED: Virtual base class for complex text layout.
     13  */
     14 
     15 U_NAMESPACE_BEGIN
     16 
     17 class LEFontInstance;
     18 class LEGlyphFilter;
     19 class LEGlyphStorage;
     20 
     21 /**
     22  * NOTE: This class is deprecated, please instead use HarfBuzz.
     23  * See: http://www.freedesktop.org/wiki/Software/HarfBuzz/
     24  * and http://userguide.icu-project.org/layoutengine
     25  *
     26  * This is a virtual base class used to do complex text layout. The text must all
     27  * be in a single font, script, and language. An instance of a LayoutEngine can be
     28  * created by calling the layoutEngineFactory method. Fonts are identified by
     29  * instances of the LEFontInstance class. Script and language codes are identified
     30  * by integer codes, which are defined in ScriptAndLanuageTags.h.
     31  *
     32  * Note that this class is not public API. It is declared public so that it can be
     33  * exported from the library that it is a part of.
     34  *
     35  * The input to the layout process is an array of characters in logical order,
     36  * and a starting X, Y position for the text. The output is an array of glyph indices,
     37  * an array of character indices for the glyphs, and an array of glyph positions.
     38  * These arrays are protected members of LayoutEngine which can be retreived by a
     39  * public method. The reset method can be called to free these arrays so that the
     40  * LayoutEngine can be reused.
     41  *
     42  * The layout process is done in three steps. There is a protected virtual method
     43  * for each step. These methods have a default implementation which only does
     44  * character to glyph mapping and default positioning using the glyph's advance
     45  * widths. Subclasses can override these methods for more advanced layout.
     46  * There is a public method which invokes the steps in the correct order.
     47  *
     48  * The steps are:
     49  *
     50  * 1) Glyph processing - character to glyph mapping and any other glyph processing
     51  *    such as ligature substitution and contextual forms.
     52  *
     53  * 2) Glyph positioning - position the glyphs based on their advance widths.
     54  *
     55  * 3) Glyph position adjustments - adjustment of glyph positions for kerning,
     56  *    accent placement, etc.
     57  *
     58  * NOTE: in all methods below, output parameters are references to pointers so
     59  * the method can allocate and free the storage as needed. All storage allocated
     60  * in this way is owned by the object which created it, and will be freed when it
     61  * is no longer needed, or when the object's destructor is invoked.
     62  *
     63  * @see LEFontInstance
     64  * @see ScriptAndLanguageTags.h
     65  *
     66  * @deprecated ICU 54. See {@link icu::LayoutEngine}
     67  *  Instead, please use HarfBuzz.
     68  *         see http://www.freedesktop.org/wiki/Software/HarfBuzz/
     69  *         and http://userguide.icu-project.org/layoutengine
     70  */
     71 class U_LAYOUT_API LayoutEngine : public UObject {
     72 public:
     73 #ifndef U_HIDE_INTERNAL_API
     74     /** @internal Flag to request kerning. Use LE_Kerning_FEATURE_FLAG instead. */
     75     static const le_int32 kTypoFlagKern;
     76     /** @internal Flag to request ligatures. Use LE_Ligatures_FEATURE_FLAG instead. */
     77     static const le_int32 kTypoFlagLiga;
     78 #endif  /* U_HIDE_INTERNAL_API */
     79 
     80 protected:
     81     /**
     82      * The object which holds the glyph storage
     83      *
     84      * @internal
     85      */
     86     LEGlyphStorage *fGlyphStorage;
     87 
     88     /**
     89      * The font instance for the text font.
     90      *
     91      * @see LEFontInstance
     92      *
     93      * @internal
     94      */
     95     const LEFontInstance *fFontInstance;
     96 
     97     /**
     98      * The script code for the text
     99      *
    100      * @see ScriptAndLanguageTags.h for script codes.
    101      *
    102      * @internal
    103      */
    104     le_int32 fScriptCode;
    105 
    106     /**
    107      * The langauge code for the text
    108      *
    109      * @see ScriptAndLanguageTags.h for language codes.
    110      *
    111      * @internal
    112      */
    113     le_int32 fLanguageCode;
    114 
    115     /**
    116      * The typographic control flags
    117      *
    118      * @internal
    119      */
    120     le_int32 fTypoFlags;
    121 
    122     /**
    123      * <code>TRUE</code> if <code>mapCharsToGlyphs</code> should replace ZWJ / ZWNJ with a glyph
    124      * with no contours.
    125      *
    126      * @internal
    127      */
    128     le_bool fFilterZeroWidth;
    129 
    130 #ifndef U_HIDE_INTERNAL_API
    131     /**
    132      * This constructs an instance for a given font, script and language. Subclass constructors
    133      * must call this constructor.
    134      *
    135      * @param fontInstance - the font for the text
    136      * @param scriptCode - the script for the text
    137      * @param languageCode - the language for the text
    138      * @param typoFlags - the typographic control flags for the text (a bitfield).  Use kTypoFlagKern
    139      * if kerning is desired, kTypoFlagLiga if ligature formation is desired.  Others are reserved.
    140      * @param success - set to an error code if the operation fails
    141      *
    142      * @see LEFontInstance
    143      * @see ScriptAndLanguageTags.h
    144      *
    145      * @internal
    146      */
    147     LayoutEngine(const LEFontInstance *fontInstance,
    148                  le_int32 scriptCode,
    149                  le_int32 languageCode,
    150                  le_int32 typoFlags,
    151                  LEErrorCode &success);
    152 #endif  /* U_HIDE_INTERNAL_API */
    153 
    154     // Do not enclose the protected default constructor with #ifndef U_HIDE_INTERNAL_API
    155     // or else the compiler will create a public default constructor.
    156     /**
    157      * This overrides the default no argument constructor to make it
    158      * difficult for clients to call it. Clients are expected to call
    159      * layoutEngineFactory.
    160      *
    161      * @internal
    162      */
    163     LayoutEngine();
    164 
    165     /**
    166      * This method does any required pre-processing to the input characters. It
    167      * may generate output characters that differ from the input charcters due to
    168      * insertions, deletions, or reorderings. In such cases, it will also generate an
    169      * output character index array reflecting these changes.
    170      *
    171      * Subclasses must override this method.
    172      *
    173      * Input parameters:
    174      * @param chars - the input character context
    175      * @param offset - the index of the first character to process
    176      * @param count - the number of characters to process
    177      * @param max - the number of characters in the input context
    178      * @param rightToLeft - TRUE if the characters are in a right to left directional run
    179      * @param outChars - the output character array, if different from the input
    180      * @param glyphStorage - the object that holds the per-glyph storage. The character index array may be set.
    181      * @param success - set to an error code if the operation fails
    182      *
    183      * @return the output character count (input character count if no change)
    184      *
    185      * @internal
    186      */
    187     virtual le_int32 characterProcessing(const LEUnicode chars[], le_int32 offset, le_int32 count, le_int32 max, le_bool rightToLeft,
    188             LEUnicode *&outChars, LEGlyphStorage &glyphStorage, LEErrorCode &success);
    189 
    190     /**
    191      * This method does the glyph processing. It converts an array of characters
    192      * into an array of glyph indices and character indices. The characters to be
    193      * processed are passed in a surrounding context. The context is specified as
    194      * a starting address and a maximum character count. An offset and a count are
    195      * used to specify the characters to be processed.
    196      *
    197      * The default implementation of this method only does character to glyph mapping.
    198      * Subclasses needing more elaborate glyph processing must override this method.
    199      *
    200      * Input parameters:
    201      * @param chars - the character context
    202      * @param offset - the offset of the first character to process
    203      * @param count - the number of characters to process
    204      * @param max - the number of characters in the context.
    205      * @param rightToLeft - TRUE if the text is in a right to left directional run
    206      * @param glyphStorage - the object which holds the per-glyph storage. The glyph and char indices arrays
    207      *                       will be set.
    208      *
    209      * Output parameters:
    210      * @param success - set to an error code if the operation fails
    211      *
    212      * @return the number of glyphs in the glyph index array
    213      *
    214      * @internal
    215      */
    216     virtual le_int32 computeGlyphs(const LEUnicode chars[], le_int32 offset, le_int32 count, le_int32 max, le_bool rightToLeft, LEGlyphStorage &glyphStorage, LEErrorCode &success);
    217 
    218     /**
    219      * This method does basic glyph positioning. The default implementation positions
    220      * the glyphs based on their advance widths. This is sufficient for most uses. It
    221      * is not expected that many subclasses will override this method.
    222      *
    223      * Input parameters:
    224      * @param glyphStorage - the object which holds the per-glyph storage. The glyph position array will be set.
    225      * @param x - the starting X position
    226      * @param y - the starting Y position
    227      * @param success - set to an error code if the operation fails
    228      *
    229      * @internal
    230      */
    231     virtual void positionGlyphs(LEGlyphStorage &glyphStorage, float x, float y, LEErrorCode &success);
    232 
    233     /**
    234      * This method does positioning adjustments like accent positioning and
    235      * kerning. The default implementation does nothing. Subclasses needing
    236      * position adjustments must override this method.
    237      *
    238      * Note that this method has both characters and glyphs as input so that
    239      * it can use the character codes to determine glyph types if that information
    240      * isn't directly available. (e.g. Some Arabic OpenType fonts don't have a GDEF
    241      * table)
    242      *
    243      * @param chars - the input character context
    244      * @param offset - the offset of the first character to process
    245      * @param count - the number of characters to process
    246      * @param reverse - <code>TRUE</code> if the glyphs in the glyph array have been reordered
    247      * @param glyphStorage - the object which holds the per-glyph storage. The glyph positions will be
    248      *                       adjusted as needed.
    249      * @param success - output parameter set to an error code if the operation fails
    250      *
    251      * @internal
    252      */
    253     virtual void adjustGlyphPositions(const LEUnicode chars[], le_int32 offset, le_int32 count, le_bool reverse, LEGlyphStorage &glyphStorage, LEErrorCode &success);
    254 
    255     /**
    256      * This method gets a table from the font associated with
    257      * the text. The default implementation gets the table from
    258      * the font instance. Subclasses which need to get the tables
    259      * some other way must override this method.
    260      *
    261      * @param tableTag - the four byte table tag.
    262      * @param length - length to use
    263      *
    264      * @return the address of the table.
    265      *
    266      * @internal
    267      */
    268     virtual const void *getFontTable(LETag tableTag, size_t &length) const;
    269 
    270     /**
    271      * @deprecated ICU 54. See {@link icu::LayoutEngine}
    272      */
    273     virtual const void *getFontTable(LETag tableTag) const { size_t ignored; return getFontTable(tableTag, ignored); }
    274 
    275     /**
    276      * This method does character to glyph mapping. The default implementation
    277      * uses the font instance to do the mapping. It will allocate the glyph and
    278      * character index arrays if they're not already allocated. If it allocates the
    279      * character index array, it will fill it it.
    280      *
    281      * This method supports right to left
    282      * text with the ability to store the glyphs in reverse order, and by supporting
    283      * character mirroring, which will replace a character which has a left and right
    284      * form, such as parens, with the opposite form before mapping it to a glyph index.
    285      *
    286      * Input parameters:
    287      * @param chars - the input character context
    288      * @param offset - the offset of the first character to be mapped
    289      * @param count - the number of characters to be mapped
    290      * @param reverse - if <code>TRUE</code>, the output will be in reverse order
    291      * @param mirror - if <code>TRUE</code>, do character mirroring
    292      * @param glyphStorage - the object which holds the per-glyph storage. The glyph and char
    293      *                       indices arrays will be filled in.
    294      * @param success - set to an error code if the operation fails
    295      *
    296      * @see LEFontInstance
    297      *
    298      * @internal
    299      */
    300     virtual void mapCharsToGlyphs(const LEUnicode chars[], le_int32 offset, le_int32 count, le_bool reverse, le_bool mirror, LEGlyphStorage &glyphStorage, LEErrorCode &success);
    301 
    302 #ifndef U_HIDE_INTERNAL_API
    303     /**
    304      * This is a convenience method that forces the advance width of mark
    305      * glyphs to be zero, which is required for proper selection and highlighting.
    306      *
    307      * @param glyphStorage - the object containing the per-glyph storage. The positions array will be modified.
    308      * @param markFilter - used to identify mark glyphs
    309      * @param success - output parameter set to an error code if the operation fails
    310      *
    311      * @see LEGlyphFilter
    312      *
    313      * @internal
    314      */
    315     static void adjustMarkGlyphs(LEGlyphStorage &glyphStorage, LEGlyphFilter *markFilter, LEErrorCode &success);
    316 
    317 
    318     /**
    319      * This is a convenience method that forces the advance width of mark
    320      * glyphs to be zero, which is required for proper selection and highlighting.
    321      * This method uses the input characters to identify marks. This is required in
    322      * cases where the font does not contain enough information to identify them based
    323      * on the glyph IDs.
    324      *
    325      * @param chars - the array of input characters
    326      * @param charCount - the number of input characers
    327      * @param glyphStorage - the object containing the per-glyph storage. The positions array will be modified.
    328      * @param reverse - <code>TRUE</code> if the glyph array has been reordered
    329      * @param markFilter - used to identify mark glyphs
    330      * @param success - output parameter set to an error code if the operation fails
    331      *
    332      * @see LEGlyphFilter
    333      *
    334      * @internal
    335      */
    336     static void adjustMarkGlyphs(const LEUnicode chars[], le_int32 charCount, le_bool reverse, LEGlyphStorage &glyphStorage, LEGlyphFilter *markFilter, LEErrorCode &success);
    337 #endif  /* U_HIDE_INTERNAL_API */
    338 
    339 public:
    340     /**
    341      * The destructor. It will free any storage allocated for the
    342      * glyph, character index and position arrays by calling the reset
    343      * method. It is declared virtual so that it will be invoked by the
    344      * subclass destructors.
    345      *
    346      * @deprecated ICU 54. See {@link icu::LayoutEngine}
    347      */
    348     virtual ~LayoutEngine();
    349 
    350     /**
    351      * This method will invoke the layout steps in their correct order by calling
    352      * the computeGlyphs, positionGlyphs and adjustGlyphPosition methods. It will
    353      * compute the glyph, character index and position arrays.
    354      *
    355      * @param chars - the input character context
    356      * @param offset - the offset of the first character to process
    357      * @param count - the number of characters to process
    358      * @param max - the number of characters in the input context
    359      * @param rightToLeft - TRUE if the characers are in a right to left directional run
    360      * @param x - the initial X position
    361      * @param y - the initial Y position
    362      * @param success - output parameter set to an error code if the operation fails
    363      *
    364      * @return the number of glyphs in the glyph array
    365      *
    366      * Note: The glyph, character index and position array can be accessed
    367      * using the getter methods below.
    368      *
    369      * Note: If you call this method more than once, you must call the reset()
    370      * method first to free the glyph, character index and position arrays
    371      * allocated by the previous call.
    372      *
    373      * @deprecated ICU 54. See {@link icu::LayoutEngine}
    374      */
    375     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);
    376 
    377     /**
    378      * This method returns the number of glyphs in the glyph array. Note
    379      * that the number of glyphs will be greater than or equal to the number
    380      * of characters used to create the LayoutEngine.
    381      *
    382      * @return the number of glyphs in the glyph array
    383      *
    384      * @deprecated ICU 54. See {@link icu::LayoutEngine}
    385      */
    386     le_int32 getGlyphCount() const;
    387 
    388     /**
    389      * This method copies the glyph array into a caller supplied array.
    390      * The caller must ensure that the array is large enough to hold all
    391      * the glyphs.
    392      *
    393      * @param glyphs - the destiniation glyph array
    394      * @param success - set to an error code if the operation fails
    395      *
    396      * @deprecated ICU 54. See {@link icu::LayoutEngine}
    397      */
    398     void getGlyphs(LEGlyphID glyphs[], LEErrorCode &success) const;
    399 
    400     /**
    401      * This method copies the glyph array into a caller supplied array,
    402      * ORing in extra bits. (This functionality is needed by the JDK,
    403      * which uses 32 bits pre glyph idex, with the high 16 bits encoding
    404      * the composite font slot number)
    405      *
    406      * @param glyphs - the destination (32 bit) glyph array
    407      * @param extraBits - this value will be ORed with each glyph index
    408      * @param success - set to an error code if the operation fails
    409      *
    410      * @deprecated ICU 54. See {@link icu::LayoutEngine}
    411      */
    412     virtual void getGlyphs(le_uint32 glyphs[], le_uint32 extraBits, LEErrorCode &success) const;
    413 
    414     /**
    415      * This method copies the character index array into a caller supplied array.
    416      * The caller must ensure that the array is large enough to hold a
    417      * character index for each glyph.
    418      *
    419      * @param charIndices - the destiniation character index array
    420      * @param success - set to an error code if the operation fails
    421      *
    422      * @deprecated ICU 54. See {@link icu::LayoutEngine}
    423      */
    424     void getCharIndices(le_int32 charIndices[], LEErrorCode &success) const;
    425 
    426     /**
    427      * This method copies the character index array into a caller supplied array.
    428      * The caller must ensure that the array is large enough to hold a
    429      * character index for each glyph.
    430      *
    431      * @param charIndices - the destiniation character index array
    432      * @param indexBase - an offset which will be added to each index
    433      * @param success - set to an error code if the operation fails
    434      *
    435      * @deprecated ICU 54. See {@link icu::LayoutEngine}
    436      */
    437     void getCharIndices(le_int32 charIndices[], le_int32 indexBase, LEErrorCode &success) const;
    438 
    439     /**
    440      * This method copies the position array into a caller supplied array.
    441      * The caller must ensure that the array is large enough to hold an
    442      * X and Y position for each glyph, plus an extra X and Y for the
    443      * advance of the last glyph.
    444      *
    445      * @param positions - the destiniation position array
    446      * @param success - set to an error code if the operation fails
    447      *
    448      * @deprecated ICU 54. See {@link icu::LayoutEngine}
    449      */
    450     void getGlyphPositions(float positions[], LEErrorCode &success) const;
    451 
    452     /**
    453      * This method returns the X and Y position of the glyph at
    454      * the given index.
    455      *
    456      * Input parameters:
    457      * @param glyphIndex - the index of the glyph
    458      *
    459      * Output parameters:
    460      * @param x - the glyph's X position
    461      * @param y - the glyph's Y position
    462      * @param success - set to an error code if the operation fails
    463      *
    464      * @deprecated ICU 54. See {@link icu::LayoutEngine}
    465      */
    466     void getGlyphPosition(le_int32 glyphIndex, float &x, float &y, LEErrorCode &success) const;
    467 
    468     /**
    469      * This method frees the glyph, character index and position arrays
    470      * so that the LayoutEngine can be reused to layout a different
    471      * characer array. (This method is also called by the destructor)
    472      *
    473      * @deprecated ICU 54. See {@link icu::LayoutEngine}
    474      */
    475     virtual void reset();
    476 
    477     /**
    478      * This method returns a LayoutEngine capable of laying out text
    479      * in the given font, script and langauge. Note that the LayoutEngine
    480      * returned may be a subclass of LayoutEngine.
    481      *
    482      * @param fontInstance - the font of the text
    483      * @param scriptCode - the script of the text
    484      * @param languageCode - the language of the text
    485      * @param success - output parameter set to an error code if the operation fails
    486      *
    487      * @return a LayoutEngine which can layout text in the given font.
    488      *
    489      * @see LEFontInstance
    490      *
    491      * @deprecated ICU 54. See {@link icu::LayoutEngine}
    492      */
    493     static LayoutEngine *layoutEngineFactory(const LEFontInstance *fontInstance, le_int32 scriptCode, le_int32 languageCode, LEErrorCode &success);
    494 
    495     /**
    496      * Override of existing call that provides flags to control typography.
    497      * @deprecated ICU 54. See {@link icu::LayoutEngine}
    498      */
    499     static LayoutEngine *layoutEngineFactory(const LEFontInstance *fontInstance, le_int32 scriptCode, le_int32 languageCode, le_int32 typo_flags, LEErrorCode &success);
    500 
    501     /**
    502      * ICU "poor man's RTTI", returns a UClassID for the actual class.
    503      *
    504      * @deprecated ICU 54. See {@link icu::LayoutEngine}
    505      */
    506     virtual UClassID getDynamicClassID() const;
    507 
    508     /**
    509      * ICU "poor man's RTTI", returns a UClassID for this class.
    510      *
    511      * @deprecated ICU 54. See {@link icu::LayoutEngine}
    512      */
    513     static UClassID getStaticClassID();
    514 
    515 };
    516 
    517 U_NAMESPACE_END
    518 #endif
    519