icuSources/layout/OpenTypeLayoutEngine.h

   1 /*
   2  * (C) Copyright IBM Corp. 1998-2013 - 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      * @stable ICU 2.8
 133      */
 134     virtual UClassID getDynamicClassID() const;
 135
 136     /**
 137      * ICU "poor man's RTTI", returns a UClassID for this class.
 138      *
 139      * @stable ICU 2.8
 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