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