icuSources/layout/OpenTypeLayoutEngine.h

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