Home | History | Annotate | Download | only in layout
      1 /*
      2  * (C) Copyright IBM Corp. 1998-2014 - All Rights Reserved
      3  *
      4  */
      5 
      6 #ifndef __OPENTYPELAYOUTENGINE_H
      7 #define __OPENTYPELAYOUTENGINE_H
      8 
      9 #include "LETypes.h"
     10 #include "LEGlyphFilter.h"
     11 #include "LEFontInstance.h"
     12 #include "LayoutEngine.h"
     13 #include "LETableReference.h"
     14 
     15 #include "GlyphSubstitutionTables.h"
     16 #include "GlyphDefinitionTables.h"
     17 #include "GlyphPositioningTables.h"
     18 
     19 U_NAMESPACE_BEGIN
     20 
     21 /**
     22  * OpenTypeLayoutEngine implements complex text layout for OpenType fonts - that is
     23  * fonts which have GSUB and GPOS tables associated with them. In order to do this,
     24  * the glyph processsing step described for LayoutEngine is further broken into three
     25  * steps:
     26  *
     27  * 1) Character processing - this step analyses the characters and assigns a list of OpenType
     28  *    feature tags to each one. It may also change, remove or add characters, and change
     29  *    their order.
     30  *
     31  * 2) Glyph processing - This step performs character to glyph mapping,and uses the GSUB
     32  *    table associated with the font to perform glyph substitutions, such as ligature substitution.
     33  *
     34  * 3) Glyph post processing - in cases where the font doesn't directly contain a GSUB table,
     35  *    the previous two steps may have generated "fake" glyph indices to use with a "canned" GSUB
     36  *    table. This step turns those glyph indices into actual font-specific glyph indices, and may
     37  *    perform any other adjustments requried by the previous steps.
     38  *
     39  * OpenTypeLayoutEngine will also use the font's GPOS table to apply position adjustments
     40  * such as kerning and accent positioning.
     41  *
     42  * @see LayoutEngine
     43  *
     44  * @internal
     45  */
     46 class U_LAYOUT_API OpenTypeLayoutEngine : public LayoutEngine
     47 {
     48 public:
     49     /**
     50      * This is the main constructor. It constructs an instance of OpenTypeLayoutEngine for
     51      * a particular font, script and language. It takes the GSUB table as a parameter since
     52      * LayoutEngine::layoutEngineFactory has to read the GSUB table to know that it has an
     53      * OpenType font.
     54      *
     55      * @param fontInstance - the font
     56      * @param scriptCode - the script
     57      * @param langaugeCode - the language
     58      * @param gsubTable - the GSUB table
     59      * @param success - set to an error code if the operation fails
     60      *
     61      * @see LayoutEngine::layoutEngineFactory
     62      * @see ScriptAndLangaugeTags.h for script and language codes
     63      *
     64      * @internal
     65      */
     66     OpenTypeLayoutEngine(const LEFontInstance *fontInstance, le_int32 scriptCode, le_int32 languageCode,
     67                             le_int32 typoFlags, const LEReferenceTo<GlyphSubstitutionTableHeader> &gsubTable, LEErrorCode &success);
     68 
     69     /**
     70      * This constructor is used when the font requires a "canned" GSUB table which can't be known
     71      * until after this constructor has been invoked.
     72      *
     73      * @param fontInstance - the font
     74      * @param scriptCode - the script
     75      * @param langaugeCode - the language
     76      * @param success - set to an error code if the operation fails
     77      *
     78      * @internal
     79      */
     80     OpenTypeLayoutEngine(const LEFontInstance *fontInstance, le_int32 scriptCode, le_int32 languageCode,
     81 			 le_int32 typoFlags, LEErrorCode &success);
     82 
     83     /**
     84      * The destructor, virtual for correct polymorphic invocation.
     85      *
     86      * @internal
     87      */
     88     virtual ~OpenTypeLayoutEngine();
     89 
     90     /**
     91      * A convenience method used to convert the script code into
     92      * the four byte script tag required by OpenType.
     93 	 * For Indic languages where multiple script tags exist,
     94 	 * the version 1 (old style) tag is returned.
     95      *
     96      * @param scriptCode - the script code
     97      *
     98      * @return the four byte script tag
     99      *
    100      * @internal
    101      */
    102     static LETag getScriptTag(le_int32 scriptCode);
    103     /**
    104      * A convenience method used to convert the script code into
    105      * the four byte script tag required by OpenType.
    106 	 * For Indic languages where multiple script tags exist,
    107 	 * the version 2 tag is returned.
    108      *
    109      * @param scriptCode - the script code
    110      *
    111      * @return the four byte script tag
    112      *
    113      * @internal
    114      */
    115     static LETag getV2ScriptTag(le_int32 scriptCode);
    116 
    117     /**
    118      * A convenience method used to convert the langauge code into
    119      * the four byte langauge tag required by OpenType.
    120      *
    121      * @param languageCode - the language code
    122      *
    123      * @return the four byte language tag
    124      *
    125      * @internal
    126      */
    127     static LETag getLangSysTag(le_int32 languageCode);
    128 
    129     /**
    130      * ICU "poor man's RTTI", returns a UClassID for the actual class.
    131      *
    132      * @deprecated ICU 54. See {@link icu::LayoutEngine}
    133      */
    134     virtual UClassID getDynamicClassID() const;
    135 
    136     /**
    137      * ICU "poor man's RTTI", returns a UClassID for this class.
    138      *
    139      * @deprecated ICU 54. See {@link icu::LayoutEngine}
    140      */
    141     static UClassID getStaticClassID();
    142 
    143     /**
    144      * The array of language tags, indexed by language code.
    145      *
    146      * @internal
    147      */
    148     static const LETag languageTags[];
    149 
    150 private:
    151 
    152     /**
    153      * This method is used by the constructors to convert the script
    154      * and language codes to four byte tags and save them.
    155      */
    156     void setScriptAndLanguageTags();
    157 
    158     /**
    159      * The array of script tags, indexed by script code.
    160      */
    161     static const LETag scriptTags[];
    162 
    163     /**
    164      * apply the typoflags. Only called by the c'tors.
    165      */
    166     void applyTypoFlags();
    167 
    168 protected:
    169     /**
    170      * A set of "default" features. The default characterProcessing method
    171      * will apply all of these features to every glyph.
    172      *
    173      * @internal
    174      */
    175     FeatureMask fFeatureMask;
    176 
    177     /**
    178      * A set of mappings from feature tags to feature masks. These may
    179      * be in the order in which the featues should be applied, but they
    180      * don't need to be.
    181      *
    182      * @internal
    183      */
    184     const FeatureMap *fFeatureMap;
    185 
    186     /**
    187      * The length of the feature map.
    188      *
    189      * @internal
    190      */
    191     le_int32 fFeatureMapCount;
    192 
    193     /**
    194      * <code>TRUE</code> if the features in the
    195      * feature map are in the order in which they
    196      * must be applied.
    197      *
    198      * @internal
    199      */
    200     le_bool fFeatureOrder;
    201 
    202     /**
    203      * The address of the GSUB table.
    204      *
    205      * @internal
    206      */
    207     LEReferenceTo<GlyphSubstitutionTableHeader> fGSUBTable;
    208 
    209     /**
    210      * The address of the GDEF table.
    211      *
    212      * @internal
    213      */
    214     LEReferenceTo<GlyphDefinitionTableHeader> fGDEFTable;
    215 
    216     /**
    217      * The address of the GPOS table.
    218      *
    219      * @internal
    220      */
    221     LEReferenceTo<GlyphPositioningTableHeader> fGPOSTable;
    222 
    223     /**
    224      * An optional filter used to inhibit substitutions
    225      * preformed by the GSUB table. This is used for some
    226      * "canned" GSUB tables to restrict substitutions to
    227      * glyphs that are in the font.
    228      *
    229      * @internal
    230      */
    231     LEGlyphFilter *fSubstitutionFilter;
    232 
    233     /**
    234      * The four byte script tag.
    235      *
    236      * @internal
    237      */
    238     LETag fScriptTag;
    239 
    240     /**
    241      * The four byte script tag for V2 fonts.
    242      *
    243      * @internal
    244      */
    245     LETag fScriptTagV2;
    246 
    247     /**
    248      * The four byte language tag
    249      *
    250      * @internal
    251      */
    252     LETag fLangSysTag;
    253 
    254     /**
    255      * This method does the OpenType character processing. It assigns the OpenType feature
    256      * tags to the characters, and may generate output characters that differ from the input
    257      * charcters due to insertions, deletions, or reorderings. In such cases, it will also
    258      * generate an output character index array reflecting these changes.
    259      *
    260      * Subclasses must override this method.
    261      *
    262      * Input parameters:
    263      * @param chars - the input character context
    264      * @param offset - the index of the first character to process
    265      * @param count - the number of characters to process
    266      * @param max - the number of characters in the input context
    267      * @param rightToLeft - TRUE if the characters are in a right to left directional run
    268      *
    269      * Output parameters:
    270      * @param outChars - the output character array, if different from the input
    271      * @param charIndices - the output character index array
    272      * @param featureTags - the output feature tag array
    273      * @param success - set to an error code if the operation fails
    274      *
    275      * @return the output character count (input character count if no change)
    276      *
    277      * @internal
    278      */
    279     virtual le_int32 characterProcessing(const LEUnicode /*chars*/[], le_int32 offset, le_int32 count, le_int32 max, le_bool /*rightToLeft*/,
    280             LEUnicode *&/*outChars*/, LEGlyphStorage &glyphStorage, LEErrorCode &success);
    281 
    282     /**
    283      * This method does character to glyph mapping, and applies the GSUB table. The
    284      * default implementation calls mapCharsToGlyphs and then applies the GSUB table,
    285      * if there is one.
    286      *
    287      * Note that in the case of "canned" GSUB tables, the output glyph indices may be
    288      * "fake" glyph indices that need to be converted to "real" glyph indices by the
    289      * glyphPostProcessing method.
    290      *
    291      * Input parameters:
    292      * @param chars - the input character context
    293      * @param offset - the index of the first character to process
    294      * @param count - the number of characters to process
    295      * @param max - the number of characters in the input context
    296      * @param rightToLeft - TRUE if the characters are in a right to left directional run
    297      * @param featureTags - the feature tag array
    298      *
    299      * Output parameters:
    300      * @param glyphs - the output glyph index array
    301      * @param charIndices - the output character index array
    302      * @param success - set to an error code if the operation fails
    303      *
    304      * @return the number of glyphs in the output glyph index array
    305      *
    306      * Note: if the character index array was already set by the characterProcessing
    307      * method, this method won't change it.
    308      *
    309      * @internal
    310      */
    311     virtual le_int32 glyphProcessing(const LEUnicode chars[], le_int32 offset, le_int32 count, le_int32 max, le_bool rightToLeft,
    312             LEGlyphStorage &glyphStorage, LEErrorCode &success);
    313 
    314     virtual le_int32 glyphSubstitution(le_int32 count, le_int32 max, le_bool rightToLeft, LEGlyphStorage &glyphStorage, LEErrorCode &success);
    315 
    316     /**
    317      * This method does any processing necessary to convert "fake"
    318      * glyph indices used by the glyphProcessing method into "real" glyph
    319      * indices which can be used to render the text. Note that in some
    320      * cases, such as CDAC Indic fonts, several "real" glyphs may be needed
    321      * to render one "fake" glyph.
    322      *
    323      * The default implementation of this method just returns the input glyph
    324      * index and character index arrays, assuming that no "fake" glyph indices
    325      * were needed to do GSUB processing.
    326      *
    327      * Input paramters:
    328      * @param tempGlyphs - the input "fake" glyph index array
    329      * @param tempCharIndices - the input "fake" character index array
    330      * @param tempGlyphCount - the number of "fake" glyph indices
    331      *
    332      * Output parameters:
    333      * @param glyphs - the output glyph index array
    334      * @param charIndices - the output character index array
    335      * @param success - set to an error code if the operation fails
    336      *
    337      * @return the number of glyph indices in the output glyph index array
    338      *
    339      * @internal
    340      */
    341     virtual le_int32 glyphPostProcessing(LEGlyphStorage &tempGlyphStorage, LEGlyphStorage &glyphStorage, LEErrorCode &success);
    342 
    343     /**
    344      * This method applies the characterProcessing, glyphProcessing and glyphPostProcessing
    345      * methods. Most subclasses will not need to override this method.
    346      *
    347      * Input parameters:
    348      * @param chars - the input character context
    349      * @param offset - the index of the first character to process
    350      * @param count - the number of characters to process
    351      * @param max - the number of characters in the input context
    352      * @param rightToLeft - TRUE if the text is in a right to left directional run
    353      *
    354      * Output parameters:
    355      * @param glyphs - the glyph index array
    356      * @param charIndices - the character index array
    357      * @param success - set to an error code if the operation fails
    358      *
    359      * @return the number of glyphs in the glyph index array
    360      *
    361      * @see LayoutEngine::computeGlyphs
    362      *
    363      * @internal
    364      */
    365     virtual le_int32 computeGlyphs(const LEUnicode chars[], le_int32 offset, le_int32 count, le_int32 max, le_bool rightToLeft, LEGlyphStorage &glyphStorage, LEErrorCode &success);
    366 
    367     /**
    368      * This method uses the GPOS table, if there is one, to adjust the glyph positions.
    369      *
    370      * Input parameters:
    371      * @param glyphs - the input glyph array
    372      * @param glyphCount - the number of glyphs in the glyph array
    373      * @param x - the starting X position
    374      * @param y - the starting Y position
    375      *
    376      * Output parameters:
    377      * @param positions - the output X and Y positions (two entries per glyph)
    378      * @param success - set to an error code if the operation fails
    379      *
    380      * @internal
    381      */
    382     virtual void adjustGlyphPositions(const LEUnicode chars[], le_int32 offset, le_int32 count, le_bool reverse, LEGlyphStorage &glyphStorage, LEErrorCode &success);
    383 
    384     /**
    385      * This method frees the feature tag array so that the
    386      * OpenTypeLayoutEngine can be reused for different text.
    387      * It is also called from our destructor.
    388      *
    389      * @internal
    390      */
    391     virtual void reset();
    392 };
    393 
    394 U_NAMESPACE_END
    395 #endif
    396 
    397