icuSources/layout/OpenTypeLayoutEngine.h

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