icuSources/layout/LayoutEngine.h

   1
   2 /*
   3  *
   4  * (C) Copyright IBM Corp. 1998-2004 - All Rights Reserved
   5  *
   6  */
   7
   8 #ifndef __LAYOUTENGINE_H
   9 #define __LAYOUTENGINE_H
  10
  11 #include "LETypes.h"
  12
  13 U_NAMESPACE_BEGIN
  14
  15 class LEFontInstance;
  16 class LEGlyphFilter;
  17 class LEGlyphStorage;
  18
  19 /**
  20  * This is a virtual base class used to do complex text layout. The text must all
  21  * be in a single font, script, and language. An instance of a LayoutEngine can be
  22  * created by calling the layoutEngineFactory method. Fonts are identified by
  23  * instances of the LEFontInstance class. Script and language codes are identified
  24  * by integer codes, which are defined in ScriptAndLanuageTags.h.
  25  *
  26  * Note that this class is not public API. It is declared public so that it can be
  27  * exported from the library that it is a part of.
  28  *
  29  * The input to the layout process is an array of characters in logical order,
  30  * and a starting X, Y position for the text. The output is an array of glyph indices,
  31  * an array of character indices for the glyphs, and an array of glyph positions.
  32  * These arrays are protected members of LayoutEngine which can be retreived by a
  33  * public method. The reset method can be called to free these arrays so that the
  34  * LayoutEngine can be reused.
  35  *
  36  * The layout process is done in three steps. There is a protected virtual method
  37  * for each step. These methods have a default implementation which only does
  38  * character to glyph mapping and default positioning using the glyph's advance
  39  * widths. Subclasses can override these methods for more advanced layout.
  40  * There is a public method which invokes the steps in the correct order.
  41  *
  42  * The steps are:
  43  *
  44  * 1) Glyph processing - character to glyph mapping and any other glyph processing
  45  *    such as ligature substitution and contextual forms.
  46  *
  47  * 2) Glyph positioning - position the glyphs based on their advance widths.
  48  *
  49  * 3) Glyph position adjustments - adjustment of glyph positions for kerning,
  50  *    accent placement, etc.
  51  *
  52  * NOTE: in all methods below, output parameters are references to pointers so
  53  * the method can allocate and free the storage as needed. All storage allocated
  54  * in this way is owned by the object which created it, and will be freed when it
  55  * is no longer needed, or when the object's destructor is invoked.
  56  *
  57  * @see LEFontInstance
  58  * @see ScriptAndLanguageTags.h
  59  *
  60  * @stable ICU 2.8
  61  */
  62 class U_LAYOUT_API LayoutEngine : public UObject {
  63 protected:
  64     /**
  65      * The object which holds the glyph storage
  66      *
  67      * @internal
  68      */
  69     LEGlyphStorage *fGlyphStorage;
  70
  71     /**
  72      * The font instance for the text font.
  73      *
  74      * @see LEFontInstance
  75      *
  76      * @internal
  77      */
  78     const LEFontInstance *fFontInstance;
  79
  80     /**
  81      * The script code for the text
  82      *
  83      * @see ScriptAndLanguageTags.h for script codes.
  84      *
  85      * @internal
  86      */
  87     le_int32 fScriptCode;
  88
  89     /**
  90      * The langauge code for the text
  91      *
  92      * @see ScriptAndLanguageTags.h for language codes.
  93      *
  94      * @internal
  95      */
  96     le_int32 fLanguageCode;
  97
  98     /**
  99      * This constructs an instance for a given font, script and language. Subclass constructors
 100      * must call this constructor.
 101      *
 102      * @param fontInstance - the font for the text
 103      * @param scriptCode - the script for the text
 104      * @param languageCode - the language for the text
 105      *
 106      * @see LEFontInstance
 107      * @see ScriptAndLanguageTags.h
 108      *
 109      * @internal
 110      */
 111     LayoutEngine(const LEFontInstance *fontInstance, le_int32 scriptCode, le_int32 languageCode);
 112
 113     /**
 114      * This overrides the default no argument constructor to make it
 115      * difficult for clients to call it. Clients are expected to call
 116      * layoutEngineFactory.
 117      *
 118      * @internal
 119      */
 120     LayoutEngine();
 121
 122     /**
 123      * This method does any required pre-processing to the input characters. It
 124      * may generate output characters that differ from the input charcters due to
 125      * insertions, deletions, or reorderings. In such cases, it will also generate an
 126      * output character index array reflecting these changes.
 127      *
 128      * Subclasses must override this method.
 129      *
 130      * Input parameters:
 131      * @param chars - the input character context
 132      * @param offset - the index of the first character to process
 133      * @param count - the number of characters to process
 134      * @param max - the number of characters in the input context
 135      * @param rightToLeft - TRUE if the characters are in a right to left directional run
 136      * @param outChars - the output character array, if different from the input
 137      * @param glyphStorage - the object that holds the per-glyph storage. The character index array may be set.
 138      * @param success - set to an error code if the operation fails
 139      *
 140      * @return the output character count (input character count if no change)
 141      *
 142      * @internal
 143      */
 144     virtual le_int32 characterProcessing(const LEUnicode chars[], le_int32 offset, le_int32 count, le_int32 max, le_bool rightToLeft,
 145             LEUnicode *&outChars, LEGlyphStorage &glyphStorage, LEErrorCode &success);
 146
 147     /**
 148      * This method does the glyph processing. It converts an array of characters
 149      * into an array of glyph indices and character indices. The characters to be
 150      * processed are passed in a surrounding context. The context is specified as
 151      * a starting address and a maximum character count. An offset and a count are
 152      * used to specify the characters to be processed.
 153      *
 154      * The default implementation of this method only does character to glyph mapping.
 155      * Subclasses needing more elaborate glyph processing must override this method.
 156      *
 157      * Input parameters:
 158      * @param chars - the character context
 159      * @param offset - the offset of the first character to process
 160      * @param count - the number of characters to process
 161      * @param max - the number of characters in the context.
 162      * @param rightToLeft - TRUE if the text is in a right to left directional run
 163      * @param glyphStorage - the object which holds the per-glyph storage. The glyph and char indices arrays
 164      *                       will be set.
 165      *
 166      * Output parameters:
 167      * @param success - set to an error code if the operation fails
 168      *
 169      * @return the number of glyphs in the glyph index array
 170      *
 171      * @internal
 172      */
 173     virtual le_int32 computeGlyphs(const LEUnicode chars[], le_int32 offset, le_int32 count, le_int32 max, le_bool rightToLeft, LEGlyphStorage &glyphStorage, LEErrorCode &success);
 174
 175     /**
 176      * This method does basic glyph positioning. The default implementation positions
 177      * the glyphs based on their advance widths. This is sufficient for most uses. It
 178      * is not expected that many subclasses will override this method.
 179      *
 180      * Input parameters:
 181      * @param glyphStorage - the object which holds the per-glyph storage. The glyph position array will be set.
 182      * @param x - the starting X position
 183      * @param y - the starting Y position
 184      * @param success - set to an error code if the operation fails
 185      *
 186      * @internal
 187      */
 188     virtual void positionGlyphs(LEGlyphStorage &glyphStorage, float x, float y, LEErrorCode &success);
 189
 190     /**
 191      * This method does positioning adjustments like accent positioning and
 192      * kerning. The default implementation does nothing. Subclasses needing
 193      * position adjustments must override this method.
 194      *
 195      * Note that this method has both characters and glyphs as input so that
 196      * it can use the character codes to determine glyph types if that information
 197      * isn't directly available. (e.g. Some Arabic OpenType fonts don't have a GDEF
 198      * table)
 199      *
 200      * @param chars - the input character context
 201      * @param offset - the offset of the first character to process
 202      * @param count - the number of characters to process
 203      * @param reverse - <code>TRUE</code> if the glyphs in the glyph array have been reordered
 204      * @param glyphStorage - the object which holds the per-glyph storage. The glyph positions will be
 205      *                       adjusted as needed.
 206      * @param success - output parameter set to an error code if the operation fails
 207      *
 208      * @internal
 209      */
 210     virtual void adjustGlyphPositions(const LEUnicode chars[], le_int32 offset, le_int32 count, le_bool reverse, LEGlyphStorage &glyphStorage, LEErrorCode &success);
 211
 212     /**
 213      * This method gets a table from the font associated with
 214      * the text. The default implementation gets the table from
 215      * the font instance. Subclasses which need to get the tables
 216      * some other way must override this method.
 217      *
 218      * @param tableTag - the four byte table tag.
 219      *
 220      * @return the address of the table.
 221      *
 222      * @internal
 223      */
 224     virtual const void *getFontTable(LETag tableTag) const;
 225
 226     /**
 227      * This method does character to glyph mapping. The default implementation
 228      * uses the font instance to do the mapping. It will allocate the glyph and
 229      * character index arrays if they're not already allocated. If it allocates the
 230      * character index array, it will fill it it.
 231      *
 232      * This method supports right to left
 233      * text with the ability to store the glyphs in reverse order, and by supporting
 234      * character mirroring, which will replace a character which has a left and right
 235      * form, such as parens, with the opposite form before mapping it to a glyph index.
 236      *
 237      * Input parameters:
 238      * @param chars - the input character context
 239      * @param offset - the offset of the first character to be mapped
 240      * @param count - the number of characters to be mapped
 241      * @param reverse - if <code>TRUE</code>, the output will be in reverse order
 242      * @param mirror - if <code>TRUE</code>, do character mirroring
 243      * @param glyphStorage - the object which holds the per-glyph storage. The glyph and char
 244      *                       indices arrays will be filled in.
 245      * @param success - set to an error code if the operation fails
 246      *
 247      * @see LEFontInstance
 248      *
 249      * @internal
 250      */
 251     virtual void mapCharsToGlyphs(const LEUnicode chars[], le_int32 offset, le_int32 count, le_bool reverse, le_bool mirror, LEGlyphStorage &glyphStorage, LEErrorCode &success);
 252
 253     /**
 254      * This is a convenience method that forces the advance width of mark
 255      * glyphs to be zero, which is required for proper selection and highlighting.
 256      *
 257      * @param glyphStorage - the object containing the per-glyph storage. The positions array will be modified.
 258      * @param markFilter - used to identify mark glyphs
 259      * @param success - output parameter set to an error code if the operation fails
 260      *
 261      * @see LEGlyphFilter
 262      *
 263      * @internal
 264      */
 265     static void adjustMarkGlyphs(LEGlyphStorage &glyphStorage, LEGlyphFilter *markFilter, LEErrorCode &success);
 266
 267
 268     /**
 269      * This is a convenience method that forces the advance width of mark
 270      * glyphs to be zero, which is required for proper selection and highlighting.
 271      * This method uses the input characters to identify marks. This is required in
 272      * cases where the font does not contain enough information to identify them based
 273      * on the glyph IDs.
 274      *
 275      * @param chars - the array of input characters
 276      * @param charCount - the number of input characers
 277      * @param glyphStorage - the object containing the per-glyph storage. The positions array will be modified.
 278      * @param reverse - <code>TRUE</code> if the glyph array has been reordered
 279      * @param markFilter - used to identify mark glyphs
 280      * @param success - output parameter set to an error code if the operation fails
 281      *
 282      * @see LEGlyphFilter
 283      *
 284      * @internal
 285      */
 286     static void adjustMarkGlyphs(const LEUnicode chars[], le_int32 charCount, le_bool reverse, LEGlyphStorage &glyphStorage, LEGlyphFilter *markFilter, LEErrorCode &success);
 287
 288
 289 public:
 290     /**
 291      * The destructor. It will free any storage allocated for the
 292      * glyph, character index and position arrays by calling the reset
 293      * method. It is declared virtual so that it will be invoked by the
 294      * subclass destructors.
 295      *
 296      * @stable ICU 2.8
 297      */
 298     virtual ~LayoutEngine();
 299
 300     /**
 301      * This method will invoke the layout steps in their correct order by calling
 302      * the computeGlyphs, positionGlyphs and adjustGlyphPosition methods.. It will
 303      * compute the glyph, character index and position arrays.
 304      *
 305      * @param chars - the input character context
 306      * @param offset - the offset of the first character to process
 307      * @param count - the number of characters to process
 308      * @param max - the number of characters in the input context
 309      * @param rightToLeft - TRUE if the characers are in a right to left directional run
 310      * @param x - the initial X position
 311      * @param y - the initial Y position
 312      * @param success - output parameter set to an error code if the operation fails
 313      *
 314      * @return the number of glyphs in the glyph array
 315      *
 316      * Note; the glyph, character index and position array can be accessed
 317      * using the getter method below.
 318      *
 319      * @stable ICU 2.8
 320      */
 321     virtual le_int32 layoutChars(const LEUnicode chars[], le_int32 offset, le_int32 count, le_int32 max, le_bool rightToLeft, float x, float y, LEErrorCode &success);
 322
 323     /**
 324      * This method returns the number of glyphs in the glyph array. Note
 325      * that the number of glyphs will be greater than or equal to the number
 326      * of characters used to create the LayoutEngine.
 327      *
 328      * @return the number of glyphs in the glyph array
 329      *
 330      * @stable ICU 2.8
 331      */
 332     le_int32 getGlyphCount() const;
 333
 334     /**
 335      * This method copies the glyph array into a caller supplied array.
 336      * The caller must ensure that the array is large enough to hold all
 337      * the glyphs.
 338      *
 339      * @param glyphs - the destiniation glyph array
 340      * @param success - set to an error code if the operation fails
 341      *
 342      * @stable ICU 2.8
 343      */
 344     void getGlyphs(LEGlyphID glyphs[], LEErrorCode &success) const;
 345
 346     /**
 347      * This method copies the glyph array into a caller supplied array,
 348      * ORing in extra bits. (This functionality is needed by the JDK,
 349      * which uses 32 bits pre glyph idex, with the high 16 bits encoding
 350      * the composite font slot number)
 351      *
 352      * @param glyphs - the destination (32 bit) glyph array
 353      * @param extraBits - this value will be ORed with each glyph index
 354      * @param success - set to an error code if the operation fails
 355      *
 356      * @stable ICU 2.8
 357      */
 358     virtual void getGlyphs(le_uint32 glyphs[], le_uint32 extraBits, LEErrorCode &success) const;
 359
 360     /**
 361      * This method copies the character index array into a caller supplied array.
 362      * The caller must ensure that the array is large enough to hold a
 363      * character index for each glyph.
 364      *
 365      * @param charIndices - the destiniation character index array
 366      * @param success - set to an error code if the operation fails
 367      *
 368      * @stable ICU 2.8
 369      */
 370     void getCharIndices(le_int32 charIndices[], LEErrorCode &success) const;
 371
 372     /**
 373      * This method copies the character index array into a caller supplied array.
 374      * The caller must ensure that the array is large enough to hold a
 375      * character index for each glyph.
 376      *
 377      * @param charIndices - the destiniation character index array
 378      * @param indexBase - an offset which will be added to each index
 379      * @param success - set to an error code if the operation fails
 380      *
 381      * @stable ICU 2.8
 382      */
 383     void getCharIndices(le_int32 charIndices[], le_int32 indexBase, LEErrorCode &success) const;
 384
 385     /**
 386      * This method copies the position array into a caller supplied array.
 387      * The caller must ensure that the array is large enough to hold an
 388      * X and Y position for each glyph, plus an extra X and Y for the
 389      * advance of the last glyph.
 390      *
 391      * @param positions - the destiniation position array
 392      * @param success - set to an error code if the operation fails
 393      *
 394      * @stable ICU 2.8
 395      */
 396     void getGlyphPositions(float positions[], LEErrorCode &success) const;
 397
 398     /**
 399      * This method returns the X and Y position of the glyph at
 400      * the given index.
 401      *
 402      * Input parameters:
 403      * @param glyphIndex - the index of the glyph
 404      *
 405      * Output parameters:
 406      * @param x - the glyph's X position
 407      * @param y - the glyph's Y position
 408      * @param success - set to an error code if the operation fails
 409      *
 410      * @stable ICU 2.8
 411      */
 412     void getGlyphPosition(le_int32 glyphIndex, float &x, float &y, LEErrorCode &success) const;
 413
 414     /**
 415      * This method frees the glyph, character index and position arrays
 416      * so that the LayoutEngine can be reused to layout a different
 417      * characer array. (This method is also called by the destructor)
 418      *
 419      * @stable ICU 2.8
 420      */
 421     virtual void reset();
 422
 423     /**
 424      * This method returns a LayoutEngine capable of laying out text
 425      * in the given font, script and langauge. Note that the LayoutEngine
 426      * returned may be a subclass of LayoutEngine.
 427      *
 428      * @param fontInstance - the font of the text
 429      * @param scriptCode - the script of the text
 430      * @param languageCode - the language of the text
 431      * @param success - output parameter set to an error code if the operation fails
 432      *
 433      * @return a LayoutEngine which can layout text in the given font.
 434      *
 435      * @see LEFontInstance
 436      *
 437      * @stable ICU 2.8
 438      */
 439     static LayoutEngine *layoutEngineFactory(const LEFontInstance *fontInstance, le_int32 scriptCode, le_int32 languageCode, LEErrorCode &success);
 440
 441     /**
 442      * ICU "poor man's RTTI", returns a UClassID for the actual class.
 443      *
 444      * @stable ICU 2.8
 445      */
 446     virtual UClassID getDynamicClassID() const;
 447
 448     /**
 449      * ICU "poor man's RTTI", returns a UClassID for this class.
 450      *
 451      * @stable ICU 2.8
 452      */
 453     static UClassID getStaticClassID();
 454
 455 };
 456
 457 U_NAMESPACE_END
 458 #endif
 459