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