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