icuSources/layout/OpenTypeLayoutEngine.h

   1
   2 /*
   3  * %W% %E%
   4  *
   5  * (C) Copyright IBM Corp. 1998-2003 - 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      * @draft ICU 2.2
 117      */
 118     virtual inline UClassID getDynamicClassID() const { return getStaticClassID(); }
 119
 120     /**
 121      * ICU "poor man's RTTI", returns a UClassID for this class.
 122      *
 123      * @draft ICU 2.2
 124      */
 125     static inline UClassID getStaticClassID() { return (UClassID)&fgClassID; }
 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     /**
 146      * The address of this static class variable serves as this class's ID
 147      * for ICU "poor man's RTTI".
 148      */
 149     static const char fgClassID;
 150
 151 protected:
 152     /**
 153      * An array of pointers to four byte feature tags.
 154      * Each pointer points to a list of tags, terminated
 155      * by a special empty tag.
 156      *
 157      * @internal
 158      */
 159     const LETag **fFeatureTags;
 160
 161     /**
 162      * A list of tags in the order in which the features in
 163      * the font should be applied, as opposed to using the
 164      * order of the lookups in the font.
 165      *
 166      * @internal
 167      */
 168     const LETag *fFeatureOrder;
 169
 170     /**
 171      * The address of the GSUB table.
 172      *
 173      * @internal
 174      */
 175     const GlyphSubstitutionTableHeader *fGSUBTable;
 176
 177     /**
 178      * The address of the GDEF table.
 179      *
 180      * @internal
 181      */
 182     const GlyphDefinitionTableHeader   *fGDEFTable;
 183
 184     /**
 185      * The address of the GPOS table.
 186      *
 187      * @internal
 188      */
 189     const GlyphPositioningTableHeader  *fGPOSTable;
 190
 191     /**
 192      * An optional filter used to inhibit substitutions
 193      * preformed by the GSUB table. This is used for some
 194      * "canned" GSUB tables to restrict substitutions to
 195      * glyphs that are in the font.
 196      *
 197      * @internal
 198      */
 199     LEGlyphFilter *fSubstitutionFilter;
 200
 201     /**
 202      * The four byte script tag.
 203      *
 204      * @internal
 205      */
 206     LETag fScriptTag;
 207
 208     /**
 209      * The four byte language tag
 210      *
 211      * @internal
 212      */
 213     LETag fLangSysTag;
 214
 215     /**
 216      * This method does the OpenType character processing. It assigns the OpenType feature
 217      * tags to the characters, and may generate output characters that differ from the input
 218      * charcters dueto insertions, deletions, or reorderings. In such cases, it will also
 219      * generate an output character index array reflecting these changes.
 220      *
 221      * Subclasses must override this method.
 222      *
 223      * Input parameters:
 224      * @param chars - the input character context
 225      * @param offset - the index of the first character to process
 226      * @param count - the number of characters to process
 227      * @param max - the number of characters in the input context
 228      * @param rightToLeft - true if the characters are in a right to left directional run
 229      *
 230      * Output parameters:
 231      * @param outChars - the output character array, if different from the input
 232      * @param charIndices - the output character index array
 233      * @param featureTags - the output feature tag array
 234      * @param success - set to an error code if the operation fails
 235      *
 236      * @return the output character count (input character count if no change)
 237      *
 238      * @internal
 239      */
 240     virtual le_int32 characterProcessing(const LEUnicode /*chars*/[], le_int32 offset, le_int32 count, le_int32 max, le_bool /*rightToLeft*/,
 241             LEUnicode *&/*outChars*/, le_int32 *&/*charIndices*/, const LETag **&/*featureTags*/, LEErrorCode &success) /*= 0;*/
 242     {
 243         if (LE_FAILURE(success)) {
 244             return 0;
 245         }
 246
 247         if (offset < 0 || count < 0 || max < 0 || offset >= max || offset + count > max) {
 248             success = LE_ILLEGAL_ARGUMENT_ERROR;
 249             return 0;
 250         }
 251
 252         return count;
 253     };
 254
 255     /**
 256      * This method does character to glyph mapping, and applies the GSUB table. The
 257      * default implementation calls mapCharsToGlyphs and then applies the GSUB table,
 258      * if there is one.
 259      *
 260      * Note that in the case of "canned" GSUB tables, the output glyph indices may be
 261      * "fake" glyph indices that need to be converted to "real" glyph indices by the
 262      * glyphPostProcessing method.
 263      *
 264      * Input parameters:
 265      * @param chars - the input character context
 266      * @param offset - the index of the first character to process
 267      * @param count - the number of characters to process
 268      * @param max - the number of characters in the input context
 269      * @param rightToLeft - true if the characters are in a right to left directional run
 270      * @param featureTags - the feature tag array
 271      *
 272      * Output parameters:
 273      * @param glyphs - the output glyph index array
 274      * @param charIndices - the output character index array
 275      * @param success - set to an error code if the operation fails
 276      *
 277      * @return the number of glyphs in the output glyph index array
 278      *
 279      * Note: if the character index array was already set by the characterProcessing
 280      * method, this method won't change it.
 281      *
 282      * @internal
 283      */
 284     virtual le_int32 glyphProcessing(const LEUnicode chars[], le_int32 offset, le_int32 count, le_int32 max, le_bool rightToLeft,
 285             const LETag **featureTags, LEGlyphID *&glyphs, le_int32 *&charIndices, LEErrorCode &success);
 286
 287     /**
 288      * This method does any processing necessary to convert "fake"
 289      * glyph indices used by the glyphProcessing method into "real" glyph
 290      * indices which can be used to render the text. Note that in some
 291      * cases, such as CDAC Indic fonts, several "real" glyphs may be needed
 292      * to render one "fake" glyph.
 293      *
 294      * The default implementation of this method just returns the input glyph
 295      * index and character index arrays, assuming that no "fake" glyph indices
 296      * were needed to do GSUB processing.
 297      *
 298      * Input paramters:
 299      * @param tempGlyphs - the input "fake" glyph index array
 300      * @param tempCharIndices - the input "fake" character index array
 301      * @param tempGlyphCount - the number of "fake" glyph indices
 302      *
 303      * Output parameters:
 304      * @param glyphs - the output glyph index array
 305      * @param charIndices - the output character index array
 306      * @param success - set to an error code if the operation fails
 307      *
 308      * @return the number of glyph indices in the output glyph index array
 309      *
 310      * @internal
 311      */
 312     virtual le_int32 glyphPostProcessing(LEGlyphID tempGlyphs[], le_int32 tempCharIndices[], le_int32 tempGlyphCount,
 313                     LEGlyphID *&glyphs, le_int32 *&charIndices, LEErrorCode &success)
 314     {
 315         if (LE_FAILURE(success)) {
 316             return 0;
 317         }
 318
 319         glyphs = tempGlyphs;
 320         charIndices = tempCharIndices;
 321
 322         return tempGlyphCount;
 323     };
 324
 325     /**
 326      * This method applies the characterProcessing, glyphProcessing and glyphPostProcessing
 327      * methods. Most subclasses will not need to override this method.
 328      *
 329      * Input parameters:
 330      * @param chars - the input character context
 331      * @param offset - the index of the first character to process
 332      * @param count - the number of characters to process
 333      * @param max - the number of characters in the input context
 334      * @param rightToLeft - true if the text is in a right to left directional run
 335      *
 336      * Output parameters:
 337      * @param glyphs - the glyph index array
 338      * @param charIndices - the character index array
 339      * @param success - set to an error code if the operation fails
 340      *
 341      * @return the number of glyphs in the glyph index array
 342      *
 343      * @see LayoutEngine::computeGlyphs
 344      *
 345      * @internal
 346      */
 347     virtual le_int32 computeGlyphs(const LEUnicode chars[], le_int32 offset, le_int32 count, le_int32 max, le_bool rightToLeft, LEGlyphID *&glyphs, le_int32 *&charIndices, LEErrorCode &success);
 348
 349     /**
 350      * This method uses the GPOS table, if there is one, to adjust the glyph positions.
 351      *
 352      * Input parameters:
 353      * @param glyphs - the input glyph array
 354      * @param glyphCount - the number of glyphs in the glyph array
 355      * @param x - the starting X position
 356      * @param y - the starting Y position
 357      *
 358      * Output parameters:
 359      * @param positions - the output X and Y positions (two entries per glyph)
 360      * @param success - set to an error code if the operation fails
 361      *
 362      * @internal
 363      */
 364     virtual void adjustGlyphPositions(const LEUnicode chars[], le_int32 offset, le_int32 count, le_bool reverse, LEGlyphID glyphs[], le_int32 glyphCount, float positions[], LEErrorCode &success);
 365
 366     /**
 367      * This method frees the feature tag array so that the
 368      * OpenTypeLayoutEngine can be reused for different text.
 369      * It is also called from our destructor.
 370      *
 371      * @internal
 372      */
 373     virtual void reset();
 374 };
 375
 376 U_NAMESPACE_END
 377 #endif
 378