1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/textandloc/fontservices/textshaperplugin/IcuSource/layout/LayoutEngine.h Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,494 @@
1.4 +
1.5 +/*
1.6 + *
1.7 + * (C) Copyright IBM Corp. 1998-2005 - All Rights Reserved
1.8 + *
1.9 + */
1.10 +
1.11 +#ifndef __LAYOUTENGINE_H
1.12 +#define __LAYOUTENGINE_H
1.13 +
1.14 +#include "LETypes.h"
1.15 +
1.16 +/**
1.17 + * \file
1.18 + * \brief C++ API: Virtual base class for complex text layout.
1.19 + */
1.20 +
1.21 +U_NAMESPACE_BEGIN
1.22 +
1.23 +class LEFontInstance;
1.24 +class LEGlyphFilter;
1.25 +class LEGlyphStorage;
1.26 +
1.27 +/**
1.28 + * This is a virtual base class used to do complex text layout. The text must all
1.29 + * be in a single font, script, and language. An instance of a LayoutEngine can be
1.30 + * created by calling the layoutEngineFactory method. Fonts are identified by
1.31 + * instances of the LEFontInstance class. Script and language codes are identified
1.32 + * by integer codes, which are defined in ScriptAndLanuageTags.h.
1.33 + *
1.34 + * Note that this class is not public API. It is declared public so that it can be
1.35 + * exported from the library that it is a part of.
1.36 + *
1.37 + * The input to the layout process is an array of characters in logical order,
1.38 + * and a starting X, Y position for the text. The output is an array of glyph indices,
1.39 + * an array of character indices for the glyphs, and an array of glyph positions.
1.40 + * These arrays are protected members of LayoutEngine which can be retreived by a
1.41 + * public method. The reset method can be called to free these arrays so that the
1.42 + * LayoutEngine can be reused.
1.43 + *
1.44 + * The layout process is done in three steps. There is a protected virtual method
1.45 + * for each step. These methods have a default implementation which only does
1.46 + * character to glyph mapping and default positioning using the glyph's advance
1.47 + * widths. Subclasses can override these methods for more advanced layout.
1.48 + * There is a public method which invokes the steps in the correct order.
1.49 + *
1.50 + * The steps are:
1.51 + *
1.52 + * 1) Glyph processing - character to glyph mapping and any other glyph processing
1.53 + * such as ligature substitution and contextual forms.
1.54 + *
1.55 + * 2) Glyph positioning - position the glyphs based on their advance widths.
1.56 + *
1.57 + * 3) Glyph position adjustments - adjustment of glyph positions for kerning,
1.58 + * accent placement, etc.
1.59 + *
1.60 + * NOTE: in all methods below, output parameters are references to pointers so
1.61 + * the method can allocate and free the storage as needed. All storage allocated
1.62 + * in this way is owned by the object which created it, and will be freed when it
1.63 + * is no longer needed, or when the object's destructor is invoked.
1.64 + *
1.65 + * @see LEFontInstance
1.66 + * @see ScriptAndLanguageTags.h
1.67 + *
1.68 + * @stable ICU 2.8
1.69 + */
1.70 +class U_LAYOUT_API LayoutEngine : public UObject {
1.71 +protected:
1.72 + /**
1.73 + * The object which holds the glyph storage
1.74 + *
1.75 + * @internal
1.76 + */
1.77 + LEGlyphStorage *fGlyphStorage;
1.78 +
1.79 + /**
1.80 + * The font instance for the text font.
1.81 + *
1.82 + * @see LEFontInstance
1.83 + *
1.84 + * @internal
1.85 + */
1.86 + const LEFontInstance *fFontInstance;
1.87 +
1.88 + /**
1.89 + * The script code for the text
1.90 + *
1.91 + * @see ScriptAndLanguageTags.h for script codes.
1.92 + *
1.93 + * @internal
1.94 + */
1.95 + le_int32 fScriptCode;
1.96 +
1.97 + /**
1.98 + * The langauge code for the text
1.99 + *
1.100 + * @see ScriptAndLanguageTags.h for language codes.
1.101 + *
1.102 + * @internal
1.103 + */
1.104 + le_int32 fLanguageCode;
1.105 +
1.106 + /**
1.107 + * The typographic control flags
1.108 + *
1.109 + * @internal
1.110 + */
1.111 + le_int32 fTypoFlags;
1.112 +
1.113 + /**
1.114 + * The glyph ID of Malayalam RA for RAKAR
1.115 + *
1.116 + * @internal
1.117 + */
1.118 + LEGlyphID fGidOfRA;
1.119 +
1.120 + /**
1.121 + * This constructs an instance for a given font, script and language. Subclass constructors
1.122 + * must call this constructor.
1.123 + *
1.124 + * @param fontInstance - the font for the text
1.125 + * @param scriptCode - the script for the text
1.126 + * @param languageCode - the language for the text
1.127 + * @param typoFlags - the typographic control flags for the text. Set bit 1 if kerning
1.128 + * is desired, set bit 2 if ligature formation is desired. Others are reserved.
1.129 + *
1.130 + * @see LEFontInstance
1.131 + * @see ScriptAndLanguageTags.h
1.132 + *
1.133 + * @internal
1.134 + */
1.135 + LayoutEngine(const LEFontInstance *fontInstance, le_int32 scriptCode, le_int32 languageCode, le_int32 typoFlags);
1.136 +
1.137 + /**
1.138 + * Returns true if the constructor failed, leaving the object in an
1.139 + * inconsistent state.
1.140 + *
1.141 + * @internal
1.142 + */
1.143 + le_bool isBogus();
1.144 +
1.145 + /**
1.146 + * This overrides the default no argument constructor to make it
1.147 + * difficult for clients to call it. Clients are expected to call
1.148 + * layoutEngineFactory.
1.149 + *
1.150 + * @internal
1.151 + */
1.152 + LayoutEngine();
1.153 +
1.154 + /**
1.155 + * This method does any required pre-processing to the input characters. It
1.156 + * may generate output characters that differ from the input charcters due to
1.157 + * insertions, deletions, or reorderings. In such cases, it will also generate an
1.158 + * output character index array reflecting these changes.
1.159 + *
1.160 + * Subclasses must override this method.
1.161 + *
1.162 + * Input parameters:
1.163 + * @param chars - the input character context
1.164 + * @param offset - the index of the first character to process
1.165 + * @param count - the number of characters to process
1.166 + * @param max - the number of characters in the input context
1.167 + * @param rightToLeft - TRUE if the characters are in a right to left directional run
1.168 + * @param outChars - the output character array, if different from the input
1.169 + * @param glyphStorage - the object that holds the per-glyph storage. The character index array may be set.
1.170 + * @param success - set to an error code if the operation fails
1.171 + *
1.172 + * @return the output character count (input character count if no change)
1.173 + *
1.174 + * @internal
1.175 + */
1.176 + virtual le_int32 characterProcessing(const LEUnicode chars[], le_int32 offset, le_int32 count, le_int32 max, le_bool rightToLeft,
1.177 + LEUnicode *&outChars, LEGlyphStorage &glyphStorage, LEErrorCode &success);
1.178 +
1.179 + /**
1.180 + * This method does the glyph processing. It converts an array of characters
1.181 + * into an array of glyph indices and character indices. The characters to be
1.182 + * processed are passed in a surrounding context. The context is specified as
1.183 + * a starting address and a maximum character count. An offset and a count are
1.184 + * used to specify the characters to be processed.
1.185 + *
1.186 + * The default implementation of this method only does character to glyph mapping.
1.187 + * Subclasses needing more elaborate glyph processing must override this method.
1.188 + *
1.189 + * Input parameters:
1.190 + * @param chars - the character context
1.191 + * @param offset - the offset of the first character to process
1.192 + * @param count - the number of characters to process
1.193 + * @param max - the number of characters in the context.
1.194 + * @param rightToLeft - TRUE if the text is in a right to left directional run
1.195 + * @param glyphStorage - the object which holds the per-glyph storage. The glyph and char indices arrays
1.196 + * will be set.
1.197 + *
1.198 + * Output parameters:
1.199 + * @param success - set to an error code if the operation fails
1.200 + *
1.201 + * @return the number of glyphs in the glyph index array
1.202 + *
1.203 + * @internal
1.204 + */
1.205 + virtual le_int32 computeGlyphs(const LEUnicode chars[], le_int32 offset, le_int32 count, le_int32 max, le_bool rightToLeft, LEGlyphStorage &glyphStorage, LEErrorCode &success);
1.206 +
1.207 + /**
1.208 + * This method does basic glyph positioning. The default implementation positions
1.209 + * the glyphs based on their advance widths. This is sufficient for most uses. It
1.210 + * is not expected that many subclasses will override this method.
1.211 + *
1.212 + * Input parameters:
1.213 + * @param glyphStorage - the object which holds the per-glyph storage. The glyph position array will be set.
1.214 + * @param x - the starting X position
1.215 + * @param y - the starting Y position
1.216 + * @param success - set to an error code if the operation fails
1.217 + *
1.218 + * @internal
1.219 + */
1.220 + virtual void positionGlyphs(LEGlyphStorage &glyphStorage, float x, float y, LEErrorCode &success);
1.221 +
1.222 + /**
1.223 + * This method does positioning adjustments like accent positioning and
1.224 + * kerning. The default implementation does nothing. Subclasses needing
1.225 + * position adjustments must override this method.
1.226 + *
1.227 + * Note that this method has both characters and glyphs as input so that
1.228 + * it can use the character codes to determine glyph types if that information
1.229 + * isn't directly available. (e.g. Some Arabic OpenType fonts don't have a GDEF
1.230 + * table)
1.231 + *
1.232 + * @param chars - the input character context
1.233 + * @param offset - the offset of the first character to process
1.234 + * @param count - the number of characters to process
1.235 + * @param reverse - <code>TRUE</code> if the glyphs in the glyph array have been reordered
1.236 + * @param glyphStorage - the object which holds the per-glyph storage. The glyph positions will be
1.237 + * adjusted as needed.
1.238 + * @param success - output parameter set to an error code if the operation fails
1.239 + *
1.240 + * @internal
1.241 + */
1.242 + virtual void adjustGlyphPositions(const LEUnicode chars[], le_int32 offset, le_int32 count, le_bool reverse, LEGlyphStorage &glyphStorage, LEErrorCode &success);
1.243 +
1.244 + /**
1.245 + * This method gets a table from the font associated with
1.246 + * the text. The default implementation gets the table from
1.247 + * the font instance. Subclasses which need to get the tables
1.248 + * some other way must override this method.
1.249 + *
1.250 + * @param tableTag - the four byte table tag.
1.251 + *
1.252 + * @return the address of the table.
1.253 + *
1.254 + * @internal
1.255 + */
1.256 + virtual const void *getFontTable(LETag tableTag) const;
1.257 +
1.258 + /**
1.259 + * This method does character to glyph mapping. The default implementation
1.260 + * uses the font instance to do the mapping. It will allocate the glyph and
1.261 + * character index arrays if they're not already allocated. If it allocates the
1.262 + * character index array, it will fill it it.
1.263 + *
1.264 + * This method supports right to left
1.265 + * text with the ability to store the glyphs in reverse order, and by supporting
1.266 + * character mirroring, which will replace a character which has a left and right
1.267 + * form, such as parens, with the opposite form before mapping it to a glyph index.
1.268 + *
1.269 + * Input parameters:
1.270 + * @param chars - the input character context
1.271 + * @param offset - the offset of the first character to be mapped
1.272 + * @param count - the number of characters to be mapped
1.273 + * @param reverse - if <code>TRUE</code>, the output will be in reverse order
1.274 + * @param mirror - if <code>TRUE</code>, do character mirroring
1.275 + * @param glyphStorage - the object which holds the per-glyph storage. The glyph and char
1.276 + * indices arrays will be filled in.
1.277 + * @param success - set to an error code if the operation fails
1.278 + *
1.279 + * @see LEFontInstance
1.280 + *
1.281 + * @internal
1.282 + */
1.283 + virtual void mapCharsToGlyphs(const LEUnicode chars[], le_int32 offset, le_int32 count, le_bool reverse, le_bool mirror, LEGlyphStorage &glyphStorage, LEErrorCode &success);
1.284 +
1.285 + /**
1.286 + * This is a convenience method that forces the advance width of mark
1.287 + * glyphs to be zero, which is required for proper selection and highlighting.
1.288 + *
1.289 + * @param glyphStorage - the object containing the per-glyph storage. The positions array will be modified.
1.290 + * @param markFilter - used to identify mark glyphs
1.291 + * @param success - output parameter set to an error code if the operation fails
1.292 + *
1.293 + * @see LEGlyphFilter
1.294 + *
1.295 + * @internal
1.296 + */
1.297 + static void adjustMarkGlyphs(LEGlyphStorage &glyphStorage, LEGlyphFilter *markFilter, LEErrorCode &success);
1.298 +
1.299 +
1.300 + /**
1.301 + * This is a convenience method that forces the advance width of mark
1.302 + * glyphs to be zero, which is required for proper selection and highlighting.
1.303 + * This method uses the input characters to identify marks. This is required in
1.304 + * cases where the font does not contain enough information to identify them based
1.305 + * on the glyph IDs.
1.306 + *
1.307 + * @param chars - the array of input characters
1.308 + * @param charCount - the number of input characers
1.309 + * @param glyphStorage - the object containing the per-glyph storage. The positions array will be modified.
1.310 + * @param reverse - <code>TRUE</code> if the glyph array has been reordered
1.311 + * @param markFilter - used to identify mark glyphs
1.312 + * @param success - output parameter set to an error code if the operation fails
1.313 + *
1.314 + * @see LEGlyphFilter
1.315 + *
1.316 + * @internal
1.317 + */
1.318 + static void adjustMarkGlyphs(const LEUnicode chars[], le_int32 charCount, le_bool reverse, LEGlyphStorage &glyphStorage, LEGlyphFilter *markFilter, LEErrorCode &success);
1.319 +
1.320 +
1.321 +public:
1.322 + /**
1.323 + * The destructor. It will free any storage allocated for the
1.324 + * glyph, character index and position arrays by calling the reset
1.325 + * method. It is declared virtual so that it will be invoked by the
1.326 + * subclass destructors.
1.327 + *
1.328 + * @stable ICU 2.8
1.329 + */
1.330 + virtual ~LayoutEngine();
1.331 +
1.332 + /**
1.333 + * This method will invoke the layout steps in their correct order by calling
1.334 + * the computeGlyphs, positionGlyphs and adjustGlyphPosition methods.. It will
1.335 + * compute the glyph, character index and position arrays.
1.336 + *
1.337 + * @param chars - the input character context
1.338 + * @param offset - the offset of the first character to process
1.339 + * @param count - the number of characters to process
1.340 + * @param max - the number of characters in the input context
1.341 + * @param rightToLeft - TRUE if the characers are in a right to left directional run
1.342 + * @param x - the initial X position
1.343 + * @param y - the initial Y position
1.344 + * @param success - output parameter set to an error code if the operation fails
1.345 + *
1.346 + * @return the number of glyphs in the glyph array
1.347 + *
1.348 + * Note; the glyph, character index and position array can be accessed
1.349 + * using the getter method below.
1.350 + *
1.351 + * @stable ICU 2.8
1.352 + */
1.353 + 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);
1.354 +
1.355 + /**
1.356 + * This method returns the number of glyphs in the glyph array. Note
1.357 + * that the number of glyphs will be greater than or equal to the number
1.358 + * of characters used to create the LayoutEngine.
1.359 + *
1.360 + * @return the number of glyphs in the glyph array
1.361 + *
1.362 + * @stable ICU 2.8
1.363 + */
1.364 + le_int32 getGlyphCount() const;
1.365 +
1.366 + /**
1.367 + * This method copies the glyph array into a caller supplied array.
1.368 + * The caller must ensure that the array is large enough to hold all
1.369 + * the glyphs.
1.370 + *
1.371 + * @param glyphs - the destiniation glyph array
1.372 + * @param success - set to an error code if the operation fails
1.373 + *
1.374 + * @stable ICU 2.8
1.375 + */
1.376 + void getGlyphs(LEGlyphID glyphs[], LEErrorCode &success) const;
1.377 +
1.378 + /**
1.379 + * This method copies the glyph array into a caller supplied array,
1.380 + * ORing in extra bits. (This functionality is needed by the JDK,
1.381 + * which uses 32 bits pre glyph idex, with the high 16 bits encoding
1.382 + * the composite font slot number)
1.383 + *
1.384 + * @param glyphs - the destination (32 bit) glyph array
1.385 + * @param extraBits - this value will be ORed with each glyph index
1.386 + * @param success - set to an error code if the operation fails
1.387 + *
1.388 + * @stable ICU 2.8
1.389 + */
1.390 + virtual void getGlyphs(le_uint32 glyphs[], le_uint32 extraBits, LEErrorCode &success) const;
1.391 +
1.392 + /**
1.393 + * This method copies the character index array into a caller supplied array.
1.394 + * The caller must ensure that the array is large enough to hold a
1.395 + * character index for each glyph.
1.396 + *
1.397 + * @param charIndices - the destiniation character index array
1.398 + * @param success - set to an error code if the operation fails
1.399 + *
1.400 + * @stable ICU 2.8
1.401 + */
1.402 + void getCharIndices(le_int32 charIndices[], LEErrorCode &success) const;
1.403 +
1.404 + /**
1.405 + * This method copies the character index array into a caller supplied array.
1.406 + * The caller must ensure that the array is large enough to hold a
1.407 + * character index for each glyph.
1.408 + *
1.409 + * @param charIndices - the destiniation character index array
1.410 + * @param indexBase - an offset which will be added to each index
1.411 + * @param success - set to an error code if the operation fails
1.412 + *
1.413 + * @stable ICU 2.8
1.414 + */
1.415 + void getCharIndices(le_int32 charIndices[], le_int32 indexBase, LEErrorCode &success) const;
1.416 +
1.417 + /**
1.418 + * This method copies the position array into a caller supplied array.
1.419 + * The caller must ensure that the array is large enough to hold an
1.420 + * X and Y position for each glyph, plus an extra X and Y for the
1.421 + * advance of the last glyph.
1.422 + *
1.423 + * @param positions - the destiniation position array
1.424 + * @param success - set to an error code if the operation fails
1.425 + *
1.426 + * @stable ICU 2.8
1.427 + */
1.428 + void getGlyphPositions(float positions[], LEErrorCode &success) const;
1.429 +
1.430 + /**
1.431 + * This method returns the X and Y position of the glyph at
1.432 + * the given index.
1.433 + *
1.434 + * Input parameters:
1.435 + * @param glyphIndex - the index of the glyph
1.436 + *
1.437 + * Output parameters:
1.438 + * @param x - the glyph's X position
1.439 + * @param y - the glyph's Y position
1.440 + * @param success - set to an error code if the operation fails
1.441 + *
1.442 + * @stable ICU 2.8
1.443 + */
1.444 + void getGlyphPosition(le_int32 glyphIndex, float &x, float &y, LEErrorCode &success) const;
1.445 +
1.446 + /**
1.447 + * This method frees the glyph, character index and position arrays
1.448 + * so that the LayoutEngine can be reused to layout a different
1.449 + * characer array. (This method is also called by the destructor)
1.450 + *
1.451 + * @stable ICU 2.8
1.452 + */
1.453 + virtual void reset();
1.454 +
1.455 + /**
1.456 + * This method returns a LayoutEngine capable of laying out text
1.457 + * in the given font, script and langauge. Note that the LayoutEngine
1.458 + * returned may be a subclass of LayoutEngine.
1.459 + *
1.460 + * @param fontInstance - the font of the text
1.461 + * @param scriptCode - the script of the text
1.462 + * @param languageCode - the language of the text
1.463 + * @param success - output parameter set to an error code if the operation fails
1.464 + *
1.465 + * @return a LayoutEngine which can layout text in the given font.
1.466 + *
1.467 + * @see LEFontInstance
1.468 + *
1.469 + * @stable ICU 2.8
1.470 + */
1.471 + static LayoutEngine *layoutEngineFactory(const LEFontInstance *fontInstance, le_int32 scriptCode, le_int32 languageCode, LEErrorCode &success);
1.472 +
1.473 + /**
1.474 + * Override of existing call that provides flags to control typography.
1.475 + * @draft ICU 3.4
1.476 + */
1.477 + static LayoutEngine *layoutEngineFactory(const LEFontInstance *fontInstance, le_int32 scriptCode, le_int32 languageCode, le_int32 typo_flags, LEErrorCode &success);
1.478 +
1.479 + /**
1.480 + * ICU "poor man's RTTI", returns a UClassID for the actual class.
1.481 + *
1.482 + * @stable ICU 2.8
1.483 + */
1.484 + virtual UClassID getDynamicClassID() const;
1.485 +
1.486 + /**
1.487 + * ICU "poor man's RTTI", returns a UClassID for this class.
1.488 + *
1.489 + * @stable ICU 2.8
1.490 + */
1.491 + static UClassID getStaticClassID();
1.492 +
1.493 +};
1.494 +
1.495 +U_NAMESPACE_END
1.496 +#endif
1.497 +