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