icuSources/layout/OpenTypeLayoutEngine.h

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