1 2 /* 3 * 4 * (C) Copyright IBM Corp. 1998-2007 - 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 * 128 * @see LEFontInstance 129 * @see ScriptAndLanguageTags.h 130 * 131 * @internal 132 */ 133 LayoutEngine(const LEFontInstance *fontInstance, le_int32 scriptCode, le_int32 languageCode, le_int32 typoFlags); 134 135 /** 136 * This overrides the default no argument constructor to make it 137 * difficult for clients to call it. Clients are expected to call 138 * layoutEngineFactory. 139 * 140 * @internal 141 */ 142 LayoutEngine(); 143 144 /** 145 * This method does any required pre-processing to the input characters. It 146 * may generate output characters that differ from the input charcters due to 147 * insertions, deletions, or reorderings. In such cases, it will also generate an 148 * output character index array reflecting these changes. 149 * 150 * Subclasses must override this method. 151 * 152 * Input parameters: 153 * @param chars - the input character context 154 * @param offset - the index of the first character to process 155 * @param count - the number of characters to process 156 * @param max - the number of characters in the input context 157 * @param rightToLeft - TRUE if the characters are in a right to left directional run 158 * @param outChars - the output character array, if different from the input 159 * @param glyphStorage - the object that holds the per-glyph storage. The character index array may be set. 160 * @param success - set to an error code if the operation fails 161 * 162 * @return the output character count (input character count if no change) 163 * 164 * @internal 165 */ 166 virtual le_int32 characterProcessing(const LEUnicode chars[], le_int32 offset, le_int32 count, le_int32 max, le_bool rightToLeft, 167 LEUnicode *&outChars, LEGlyphStorage &glyphStorage, LEErrorCode &success); 168 169 /** 170 * This method does the glyph processing. It converts an array of characters 171 * into an array of glyph indices and character indices. The characters to be 172 * processed are passed in a surrounding context. The context is specified as 173 * a starting address and a maximum character count. An offset and a count are 174 * used to specify the characters to be processed. 175 * 176 * The default implementation of this method only does character to glyph mapping. 177 * Subclasses needing more elaborate glyph processing must override this method. 178 * 179 * Input parameters: 180 * @param chars - the character context 181 * @param offset - the offset of the first character to process 182 * @param count - the number of characters to process 183 * @param max - the number of characters in the context. 184 * @param rightToLeft - TRUE if the text is in a right to left directional run 185 * @param glyphStorage - the object which holds the per-glyph storage. The glyph and char indices arrays 186 * will be set. 187 * 188 * Output parameters: 189 * @param success - set to an error code if the operation fails 190 * 191 * @return the number of glyphs in the glyph index array 192 * 193 * @internal 194 */ 195 virtual le_int32 computeGlyphs(const LEUnicode chars[], le_int32 offset, le_int32 count, le_int32 max, le_bool rightToLeft, LEGlyphStorage &glyphStorage, LEErrorCode &success); 196 197 /** 198 * This method does basic glyph positioning. The default implementation positions 199 * the glyphs based on their advance widths. This is sufficient for most uses. It 200 * is not expected that many subclasses will override this method. 201 * 202 * Input parameters: 203 * @param glyphStorage - the object which holds the per-glyph storage. The glyph position array will be set. 204 * @param x - the starting X position 205 * @param y - the starting Y position 206 * @param success - set to an error code if the operation fails 207 * 208 * @internal 209 */ 210 virtual void positionGlyphs(LEGlyphStorage &glyphStorage, float x, float y, LEErrorCode &success); 211 212 /** 213 * This method does positioning adjustments like accent positioning and 214 * kerning. The default implementation does nothing. Subclasses needing 215 * position adjustments must override this method. 216 * 217 * Note that this method has both characters and glyphs as input so that 218 * it can use the character codes to determine glyph types if that information 219 * isn't directly available. (e.g. Some Arabic OpenType fonts don't have a GDEF 220 * table) 221 * 222 * @param chars - the input character context 223 * @param offset - the offset of the first character to process 224 * @param count - the number of characters to process 225 * @param reverse - <code>TRUE</code> if the glyphs in the glyph array have been reordered 226 * @param glyphStorage - the object which holds the per-glyph storage. The glyph positions will be 227 * adjusted as needed. 228 * @param success - output parameter set to an error code if the operation fails 229 * 230 * @internal 231 */ 232 virtual void adjustGlyphPositions(const LEUnicode chars[], le_int32 offset, le_int32 count, le_bool reverse, LEGlyphStorage &glyphStorage, LEErrorCode &success); 233 234 /** 235 * This method gets a table from the font associated with 236 * the text. The default implementation gets the table from 237 * the font instance. Subclasses which need to get the tables 238 * some other way must override this method. 239 * 240 * @param tableTag - the four byte table tag. 241 * 242 * @return the address of the table. 243 * 244 * @internal 245 */ 246 virtual const void *getFontTable(LETag tableTag) const; 247 248 /** 249 * This method does character to glyph mapping. The default implementation 250 * uses the font instance to do the mapping. It will allocate the glyph and 251 * character index arrays if they're not already allocated. If it allocates the 252 * character index array, it will fill it it. 253 * 254 * This method supports right to left 255 * text with the ability to store the glyphs in reverse order, and by supporting 256 * character mirroring, which will replace a character which has a left and right 257 * form, such as parens, with the opposite form before mapping it to a glyph index. 258 * 259 * Input parameters: 260 * @param chars - the input character context 261 * @param offset - the offset of the first character to be mapped 262 * @param count - the number of characters to be mapped 263 * @param reverse - if <code>TRUE</code>, the output will be in reverse order 264 * @param mirror - if <code>TRUE</code>, do character mirroring 265 * @param glyphStorage - the object which holds the per-glyph storage. The glyph and char 266 * indices arrays will be filled in. 267 * @param success - set to an error code if the operation fails 268 * 269 * @see LEFontInstance 270 * 271 * @internal 272 */ 273 virtual void mapCharsToGlyphs(const LEUnicode chars[], le_int32 offset, le_int32 count, le_bool reverse, le_bool mirror, LEGlyphStorage &glyphStorage, LEErrorCode &success); 274 275 /** 276 * This is a convenience method that forces the advance width of mark 277 * glyphs to be zero, which is required for proper selection and highlighting. 278 * 279 * @param glyphStorage - the object containing the per-glyph storage. The positions array will be modified. 280 * @param markFilter - used to identify mark glyphs 281 * @param success - output parameter set to an error code if the operation fails 282 * 283 * @see LEGlyphFilter 284 * 285 * @internal 286 */ 287 static void adjustMarkGlyphs(LEGlyphStorage &glyphStorage, LEGlyphFilter *markFilter, LEErrorCode &success); 288 289 290 /** 291 * This is a convenience method that forces the advance width of mark 292 * glyphs to be zero, which is required for proper selection and highlighting. 293 * This method uses the input characters to identify marks. This is required in 294 * cases where the font does not contain enough information to identify them based 295 * on the glyph IDs. 296 * 297 * @param chars - the array of input characters 298 * @param charCount - the number of input characers 299 * @param glyphStorage - the object containing the per-glyph storage. The positions array will be modified. 300 * @param reverse - <code>TRUE</code> if the glyph array has been reordered 301 * @param markFilter - used to identify mark glyphs 302 * @param success - output parameter set to an error code if the operation fails 303 * 304 * @see LEGlyphFilter 305 * 306 * @internal 307 */ 308 static void adjustMarkGlyphs(const LEUnicode chars[], le_int32 charCount, le_bool reverse, LEGlyphStorage &glyphStorage, LEGlyphFilter *markFilter, LEErrorCode &success); 309 310 311 public: 312 /** 313 * The destructor. It will free any storage allocated for the 314 * glyph, character index and position arrays by calling the reset 315 * method. It is declared virtual so that it will be invoked by the 316 * subclass destructors. 317 * 318 * @stable ICU 2.8 319 */ 320 virtual ~LayoutEngine(); 321 322 /** 323 * This method will invoke the layout steps in their correct order by calling 324 * the computeGlyphs, positionGlyphs and adjustGlyphPosition methods. It will 325 * compute the glyph, character index and position arrays. 326 * 327 * @param chars - the input character context 328 * @param offset - the offset of the first character to process 329 * @param count - the number of characters to process 330 * @param max - the number of characters in the input context 331 * @param rightToLeft - TRUE if the characers are in a right to left directional run 332 * @param x - the initial X position 333 * @param y - the initial Y position 334 * @param success - output parameter set to an error code if the operation fails 335 * 336 * @return the number of glyphs in the glyph array 337 * 338 * Note: The glyph, character index and position array can be accessed 339 * using the getter methods below. 340 * 341 * Note: If you call this method more than once, you must call the reset() 342 * method first to free the glyph, character index and position arrays 343 * allocated by the previous call. 344 * 345 * @stable ICU 2.8 346 */ 347 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); 348 349 /** 350 * This method returns the number of glyphs in the glyph array. Note 351 * that the number of glyphs will be greater than or equal to the number 352 * of characters used to create the LayoutEngine. 353 * 354 * @return the number of glyphs in the glyph array 355 * 356 * @stable ICU 2.8 357 */ 358 le_int32 getGlyphCount() const; 359 360 /** 361 * This method copies the glyph array into a caller supplied array. 362 * The caller must ensure that the array is large enough to hold all 363 * the glyphs. 364 * 365 * @param glyphs - the destiniation glyph array 366 * @param success - set to an error code if the operation fails 367 * 368 * @stable ICU 2.8 369 */ 370 void getGlyphs(LEGlyphID glyphs[], LEErrorCode &success) const; 371 372 /** 373 * This method copies the glyph array into a caller supplied array, 374 * ORing in extra bits. (This functionality is needed by the JDK, 375 * which uses 32 bits pre glyph idex, with the high 16 bits encoding 376 * the composite font slot number) 377 * 378 * @param glyphs - the destination (32 bit) glyph array 379 * @param extraBits - this value will be ORed with each glyph index 380 * @param success - set to an error code if the operation fails 381 * 382 * @stable ICU 2.8 383 */ 384 virtual void getGlyphs(le_uint32 glyphs[], le_uint32 extraBits, LEErrorCode &success) const; 385 386 /** 387 * This method copies the character index array into a caller supplied array. 388 * The caller must ensure that the array is large enough to hold a 389 * character index for each glyph. 390 * 391 * @param charIndices - the destiniation character index array 392 * @param success - set to an error code if the operation fails 393 * 394 * @stable ICU 2.8 395 */ 396 void getCharIndices(le_int32 charIndices[], LEErrorCode &success) const; 397 398 /** 399 * This method copies the character index array into a caller supplied array. 400 * The caller must ensure that the array is large enough to hold a 401 * character index for each glyph. 402 * 403 * @param charIndices - the destiniation character index array 404 * @param indexBase - an offset which will be added to each index 405 * @param success - set to an error code if the operation fails 406 * 407 * @stable ICU 2.8 408 */ 409 void getCharIndices(le_int32 charIndices[], le_int32 indexBase, LEErrorCode &success) const; 410 411 /** 412 * This method copies the position array into a caller supplied array. 413 * The caller must ensure that the array is large enough to hold an 414 * X and Y position for each glyph, plus an extra X and Y for the 415 * advance of the last glyph. 416 * 417 * @param positions - the destiniation position array 418 * @param success - set to an error code if the operation fails 419 * 420 * @stable ICU 2.8 421 */ 422 void getGlyphPositions(float positions[], LEErrorCode &success) const; 423 424 /** 425 * This method returns the X and Y position of the glyph at 426 * the given index. 427 * 428 * Input parameters: 429 * @param glyphIndex - the index of the glyph 430 * 431 * Output parameters: 432 * @param x - the glyph's X position 433 * @param y - the glyph's Y position 434 * @param success - set to an error code if the operation fails 435 * 436 * @stable ICU 2.8 437 */ 438 void getGlyphPosition(le_int32 glyphIndex, float &x, float &y, LEErrorCode &success) const; 439 440 /** 441 * This method frees the glyph, character index and position arrays 442 * so that the LayoutEngine can be reused to layout a different 443 * characer array. (This method is also called by the destructor) 444 * 445 * @stable ICU 2.8 446 */ 447 virtual void reset(); 448 449 /** 450 * This method returns a LayoutEngine capable of laying out text 451 * in the given font, script and langauge. Note that the LayoutEngine 452 * returned may be a subclass of LayoutEngine. 453 * 454 * @param fontInstance - the font of the text 455 * @param scriptCode - the script of the text 456 * @param languageCode - the language of the text 457 * @param success - output parameter set to an error code if the operation fails 458 * 459 * @return a LayoutEngine which can layout text in the given font. 460 * 461 * @see LEFontInstance 462 * 463 * @stable ICU 2.8 464 */ 465 static LayoutEngine *layoutEngineFactory(const LEFontInstance *fontInstance, le_int32 scriptCode, le_int32 languageCode, LEErrorCode &success); 466 467 /** 468 * Override of existing call that provides flags to control typography. 469 * @stable ICU 3.4 470 */ 471 static LayoutEngine *layoutEngineFactory(const LEFontInstance *fontInstance, le_int32 scriptCode, le_int32 languageCode, le_int32 typo_flags, LEErrorCode &success); 472 473 /** 474 * ICU "poor man's RTTI", returns a UClassID for the actual class. 475 * 476 * @stable ICU 2.8 477 */ 478 virtual UClassID getDynamicClassID() const; 479 480 /** 481 * ICU "poor man's RTTI", returns a UClassID for this class. 482 * 483 * @stable ICU 2.8 484 */ 485 static UClassID getStaticClassID(); 486 487 }; 488 489 U_NAMESPACE_END 490 #endif 491 492