| /* |
| * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
| * |
| * This code is free software; you can redistribute it and/or modify it |
| * under the terms of the GNU General Public License version 2 only, as |
| * published by the Free Software Foundation. Sun designates this |
| * particular file as subject to the "Classpath" exception as provided |
| * by Sun in the LICENSE file that accompanied this code. |
| * |
| * This code is distributed in the hope that it will be useful, but WITHOUT |
| * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
| * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
| * version 2 for more details (a copy is included in the LICENSE file that |
| * accompanied this code). |
| * |
| * You should have received a copy of the GNU General Public License version |
| * 2 along with this work; if not, write to the Free Software Foundation, |
| * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
| * |
| * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, |
| * CA 95054 USA or visit www.sun.com if you need additional information or |
| * have any questions. |
| * |
| */ |
| |
| /* |
| * |
| * (C) Copyright IBM Corp. 1998-2005 - All Rights Reserved |
| * |
| */ |
| |
| #ifndef __LAYOUTENGINE_H |
| #define __LAYOUTENGINE_H |
| |
| #include "LETypes.h" |
| |
| #include <string.h> |
| |
| class LEFontInstance; |
| class LEGlyphFilter; |
| class LEGlyphStorage; |
| |
| /** |
| * This is a virtual base class used to do complex text layout. The |
| * text must all be in a single font, script, and language. An |
| * instance of a LayoutEngine can be created by calling the |
| * layoutEngineFactory method. Fonts are identified by instances of |
| * the LEFontInstance class. Script and language codes are identified |
| * by integer codes, which are defined in ScriptAndLanuageTags.h. |
| * |
| * Note that this class is not public API. It is declared public so |
| * that it can be exported from the library that it is a part of. |
| * |
| * The input to the layout process is an array of characters in |
| * logical order, and a starting X, Y position for the text. The |
| * output is an array of glyph indices, an array of character indices |
| * for the glyphs, and an array of glyph positions. These arrays are |
| * protected members of LayoutEngine which can be retreived by a |
| * public method. The reset method can be called to free these arrays |
| * so that the LayoutEngine can be reused. |
| * |
| * The layout process is done in three steps. There is a protected |
| * virtual method for each step. These methods have a default |
| * implementation which only does character to glyph mapping and |
| * default positioning using the glyph's advance widths. Subclasses |
| * can override these methods for more advanced layout. There is a |
| * public method which invokes the steps in the correct order. |
| * |
| * The steps are: |
| * |
| * 1) Glyph processing - character to glyph mapping and any other |
| * glyph processing such as ligature substitution and contextual |
| * forms. |
| * |
| * 2) Glyph positioning - position the glyphs based on their advance |
| * widths. |
| * |
| * 3) Glyph position adjustments - adjustment of glyph positions for |
| * kerning, accent placement, etc. |
| * |
| * NOTE: in all methods below, output parameters are references to |
| * pointers so the method can allocate and free the storage as |
| * needed. All storage allocated in this way is owned by the object |
| * which created it, and will be freed when it is no longer needed, or |
| * when the object's destructor is invoked. |
| * |
| * @see LEFontInstance |
| * @see ScriptAndLanguageTags.h |
| * |
| * @stable ICU 2.8 |
| */ |
| class U_LAYOUT_API LayoutEngine |
| { |
| protected: |
| /** |
| * The object which holds the glyph storage |
| * |
| * @internal |
| */ |
| LEGlyphStorage *fGlyphStorage; |
| |
| /** |
| * The font instance for the text font. |
| * |
| * @see LEFontInstance |
| * |
| * @internal |
| */ |
| const LEFontInstance *fFontInstance; |
| |
| /** |
| * The script code for the text |
| * |
| * @see ScriptAndLanguageTags.h for script codes. |
| * |
| * @internal |
| */ |
| le_int32 fScriptCode; |
| |
| /** |
| * The langauge code for the text |
| * |
| * @see ScriptAndLanguageTags.h for language codes. |
| * |
| * @internal |
| */ |
| le_int32 fLanguageCode; |
| |
| /** |
| * The typographic control flags |
| * |
| * @internal |
| */ |
| le_int32 fTypoFlags; |
| |
| /** |
| * This constructs an instance for a given font, script and |
| * language. Subclass constructors |
| * must call this constructor. |
| * |
| * @param fontInstance - the font for the text |
| * @param scriptCode - the script for the text |
| * @param languageCode - the language for the text |
| * |
| * @see LEFontInstance |
| * @see ScriptAndLanguageTags.h |
| * |
| * @internal |
| */ |
| LayoutEngine(const LEFontInstance *fontInstance, le_int32 scriptCode, |
| le_int32 languageCode, le_int32 typoFlags); |
| |
| /** |
| * This overrides the default no argument constructor to make it |
| * difficult for clients to call it. Clients are expected to call |
| * layoutEngineFactory. |
| * |
| * @internal |
| */ |
| LayoutEngine(); |
| |
| /** |
| * This method does any required pre-processing to the input |
| * characters. It may generate output characters that differ from |
| * the input charcters due to insertions, deletions, or |
| * reorderings. In such cases, it will also generate an output |
| * character index array reflecting these changes. |
| * |
| * Subclasses must override this method. |
| * |
| * Input parameters: |
| * @param chars - the input character context |
| * @param offset - the index of the first character to process |
| * @param count - the number of characters to process |
| * @param max - the number of characters in the input context |
| * @param rightToLeft - TRUE if the characters are in a right to |
| * left directional run |
| * @param outChars - the output character array, if different from |
| * the input |
| * @param glyphStorage - the object that holds the per-glyph |
| * storage. The character index array may be set. |
| * @param success - set to an error code if the operation fails |
| * @return the output character count (input character count if no |
| * change) |
| * |
| * @internal |
| */ |
| virtual le_int32 characterProcessing(const LEUnicode chars[], le_int32 offset, |
| le_int32 count, le_int32 max, le_bool rightToLeft, |
| LEUnicode *&outChars, LEGlyphStorage &glyphStorage, LEErrorCode &success); |
| |
| /** |
| * This method does the glyph processing. It converts an array of |
| * characters into an array of glyph indices and character |
| * indices. The characters to be processed are passed in a |
| * surrounding context. The context is specified as a starting |
| * address and a maximum character count. An offset and a count |
| * are used to specify the characters to be processed. |
| * |
| * The default implementation of this method only does character |
| * to glyph mapping. Subclasses needing more elaborate glyph |
| * processing must override this method. |
| * |
| * Input parameters: |
| * @param chars - the character context |
| * @param offset - the offset of the first character to process |
| * @param count - the number of characters to process |
| * @param max - the number of characters in the context. |
| * @param rightToLeft - TRUE if the text is in a right to left |
| * directional run |
| * @param glyphStorage - the object which holds the per-glyph |
| * storage. The glyph and char indices arrays will be |
| * set. |
| * |
| * Output parameters: |
| * @param success - set to an error code if the operation fails |
| * |
| * @return the number of glyphs in the glyph index array |
| * |
| * @internal |
| */ |
| virtual le_int32 computeGlyphs(const LEUnicode chars[], le_int32 offset, |
| le_int32 count, le_int32 max, le_bool rightToLeft, |
| LEGlyphStorage &glyphStorage, LEErrorCode &success); |
| |
| /** |
| * This method does basic glyph positioning. The default |
| * implementation positions the glyphs based on their advance |
| * widths. This is sufficient for most uses. It is not expected |
| * that many subclasses will override this method. |
| * |
| * Input parameters: |
| * @param glyphStorage - the object which holds the per-glyph storage. |
| * The glyph position array will be set. |
| * @param x - the starting X position |
| * @param y - the starting Y position |
| * @param success - set to an error code if the operation fails |
| * |
| * @internal |
| */ |
| virtual void positionGlyphs(LEGlyphStorage &glyphStorage, |
| float x, float y, LEErrorCode &success); |
| |
| /** |
| * This method does positioning adjustments like accent |
| * positioning and kerning. The default implementation does |
| * nothing. Subclasses needing position adjustments must override |
| * this method. |
| * |
| * Note that this method has both characters and glyphs as input |
| * so that it can use the character codes to determine glyph types |
| * if that information isn't directly available. (e.g. Some Arabic |
| * OpenType fonts don't have a GDEF table) |
| * |
| * @param chars - the input character context |
| * @param offset - the offset of the first character to process |
| * @param count - the number of characters to process |
| * @param reverse - <code>TRUE</code> if the glyphs in the glyph |
| * array have been reordered |
| * @param glyphStorage - the object which holds the per-glyph |
| * storage. The glyph positions will be adjusted as needed. |
| * @param success - output parameter set to an error code if the |
| * operation fails |
| * |
| * @internal |
| */ |
| virtual void adjustGlyphPositions(const LEUnicode chars[], |
| le_int32 offset, le_int32 count, le_bool reverse, |
| LEGlyphStorage &glyphStorage, LEErrorCode &success); |
| |
| /** |
| * This method gets a table from the font associated with the |
| * text. The default implementation gets the table from the font |
| * instance. Subclasses which need to get the tables some other |
| * way must override this method. |
| * |
| * @param tableTag - the four byte table tag. |
| * |
| * @return the address of the table. |
| * |
| * @internal |
| */ |
| virtual const void *getFontTable(LETag tableTag) const; |
| |
| /** |
| * This method does character to glyph mapping. The default |
| * implementation uses the font instance to do the mapping. It |
| * will allocate the glyph and character index arrays if they're |
| * not already allocated. If it allocates the character index |
| * array, it will fill it it. |
| * |
| * This method supports right to left text with the ability to |
| * store the glyphs in reverse order, and by supporting character |
| * mirroring, which will replace a character which has a left and |
| * right form, such as parens, with the opposite form before |
| * mapping it to a glyph index. |
| * |
| * Input parameters: |
| * @param chars - the input character context |
| * @param offset - the offset of the first character to be mapped |
| * @param count - the number of characters to be mapped |
| * @param reverse - if <code>TRUE</code>, the output will be in |
| * reverse order |
| * @param mirror - if <code>TRUE</code>, do character mirroring |
| * @param glyphStorage - the object which holds the per-glyph |
| * storage. The glyph and char indices arrays will be |
| * filled in. |
| * @param success - set to an error code if the operation fails |
| * |
| * @see LEFontInstance |
| * |
| * @internal |
| */ |
| virtual void mapCharsToGlyphs(const LEUnicode chars[], le_int32 offset, |
| le_int32 count, le_bool reverse, le_bool mirror, |
| LEGlyphStorage &glyphStorage, LEErrorCode &success); |
| |
| /** |
| * This is a convenience method that forces the advance width of |
| * mark glyphs to be zero, which is required for proper selection |
| * and highlighting. |
| * |
| * @param glyphStorage - the object containing the per-glyph |
| * storage. The positions array will be modified. |
| * @param markFilter - used to identify mark glyphs |
| * @param success - output parameter set to an error code if the |
| * operation fails |
| * |
| * @see LEGlyphFilter |
| * |
| * @internal |
| */ |
| static void adjustMarkGlyphs(LEGlyphStorage &glyphStorage, |
| LEGlyphFilter *markFilter, LEErrorCode &success); |
| |
| |
| /** |
| * This is a convenience method that forces the advance width of |
| * mark glyphs to be zero, which is required for proper selection |
| * and highlighting. This method uses the input characters to |
| * identify marks. This is required in cases where the font does |
| * not contain enough information to identify them based on the |
| * glyph IDs. |
| * |
| * @param chars - the array of input characters |
| * @param charCount - the number of input characers |
| * @param glyphStorage - the object containing the per-glyph |
| * storage. The positions array will be modified. |
| * @param reverse - <code>TRUE</code> if the glyph array has been |
| * reordered |
| * @param markFilter - used to identify mark glyphs |
| * @param success - output parameter set to an error code if the |
| * operation fails |
| * |
| * @see LEGlyphFilter |
| * |
| * @internal |
| */ |
| static void adjustMarkGlyphs(const LEUnicode chars[], |
| le_int32 charCount, le_bool reverse, |
| LEGlyphStorage &glyphStorage, LEGlyphFilter *markFilter, |
| LEErrorCode &success); |
| |
| public: |
| /** |
| * The destructor. It will free any storage allocated for the |
| * glyph, character index and position arrays by calling the reset |
| * method. It is declared virtual so that it will be invoked by |
| * the subclass destructors. |
| * |
| * @stable ICU 2.8 |
| */ |
| virtual ~LayoutEngine(); |
| |
| /** |
| * This method will invoke the layout steps in their correct order |
| * by calling the 32 bit versions of the computeGlyphs and |
| * positionGlyphs methods.(It doesn't * call the |
| * adjustGlyphPositions method because that doesn't apply for |
| * default * processing.) It will compute the glyph, character |
| * index and position arrays. |
| * |
| * @param chars - the input character context |
| * @param offset - the offset of the first character to process |
| * @param count - the number of characters to process |
| * @param max - the number of characters in the input context |
| * @param rightToLeft - true if the characers are in a right to |
| * left directional run |
| * @param x - the initial X position |
| * @param y - the initial Y position |
| * @param success - output parameter set to an error code if the |
| * operation fails |
| * @return the number of glyphs in the glyph array |
| * |
| * Note: the glyph, character index and position array can be |
| * accessed using the getter method below. |
| */ |
| le_int32 layoutChars(const LEUnicode chars[], le_int32 offset, |
| le_int32 count, le_int32 max, le_bool rightToLeft, float x, |
| float y, LEErrorCode &success); |
| |
| /** |
| * This method returns the number of glyphs in the glyph |
| * array. Note that the number of glyphs will be greater than or |
| * equal to the number of characters used to create the |
| * LayoutEngine. |
| * |
| * @return the number of glyphs in the glyph array |
| * |
| * @stable ICU 2.8 |
| */ |
| le_int32 getGlyphCount() const; |
| |
| /** |
| * This method copies the glyph array into a caller supplied |
| * array. The caller must ensure that the array is large enough |
| * to hold all the glyphs. |
| * |
| * @param glyphs - the destiniation glyph array |
| * @param success - set to an error code if the operation fails |
| * |
| * @stable ICU 2.8 |
| */ |
| void getGlyphs(LEGlyphID glyphs[], LEErrorCode &success) const; |
| |
| /** |
| * This method copies the glyph array into a caller supplied |
| * array, ORing in extra bits. (This functionality is needed by |
| * the JDK, which uses 32 bits pre glyph idex, with the high 16 |
| * bits encoding the composite font slot number) |
| * |
| * @param glyphs - the destination (32 bit) glyph array |
| * @param extraBits - this value will be ORed with each glyph index |
| * @param success - set to an error code if the operation fails |
| * |
| * @stable ICU 2.8 |
| */ |
| virtual void getGlyphs(le_uint32 glyphs[], le_uint32 extraBits, |
| LEErrorCode &success) const; |
| |
| /** |
| * This method copies the character index array into a caller |
| * supplied array. The caller must ensure that the array is large |
| * enough to hold a character index for each glyph. |
| * |
| * @param charIndices - the destiniation character index array |
| * @param success - set to an error code if the operation fails |
| * |
| * @stable ICU 2.8 |
| */ |
| void getCharIndices(le_int32 charIndices[], LEErrorCode &success) const; |
| |
| /** |
| * This method copies the character index array into a caller |
| * supplied array. The caller must ensure that the array is large |
| * enough to hold a character index for each glyph. |
| * |
| * @param charIndices - the destiniation character index array |
| * @param indexBase - an offset which will be added to each index |
| * @param success - set to an error code if the operation fails |
| * |
| * @stable ICU 2.8 |
| */ |
| void getCharIndices(le_int32 charIndices[], le_int32 indexBase, |
| LEErrorCode &success) const; |
| |
| /** |
| * This method copies the position array into a caller supplied |
| * array. The caller must ensure that the array is large enough |
| * to hold an X and Y position for each glyph, plus an extra X and |
| * Y for the advance of the last glyph. |
| * |
| * @param positions - the destiniation position array |
| * @param success - set to an error code if the operation fails |
| * |
| * @stable ICU 2.8 |
| */ |
| void getGlyphPositions(float positions[], LEErrorCode &success) const; |
| |
| /** |
| * This method returns the X and Y position of the glyph at |
| * the given index. |
| * |
| * Input parameters: |
| * @param glyphIndex - the index of the glyph |
| * |
| * Output parameters: |
| * @param x - the glyph's X position |
| * @param y - the glyph's Y position |
| * @param success - set to an error code if the operation fails |
| * |
| * @stable ICU 2.8 |
| */ |
| void getGlyphPosition(le_int32 glyphIndex, float &x, float &y, |
| LEErrorCode &success) const; |
| |
| /** |
| * This method frees the glyph, character index and position arrays |
| * so that the LayoutEngine can be reused to layout a different |
| * characer array. (This method is also called by the destructor) |
| * |
| * @stable ICU 2.8 |
| */ |
| virtual void reset(); |
| |
| /** |
| * This method returns a LayoutEngine capable of laying out text |
| * in the given font, script and langauge. Note that the LayoutEngine |
| * returned may be a subclass of LayoutEngine. |
| * |
| * @param fontInstance - the font of the text |
| * @param scriptCode - the script of the text |
| * @param languageCode - the language of the text |
| * @param success - output parameter set to an error code if the |
| * operation fails |
| * |
| * @return a LayoutEngine which can layout text in the given font. |
| * |
| * @see LEFontInstance |
| * |
| * @stable ICU 2.8 |
| */ |
| static LayoutEngine *layoutEngineFactory(const LEFontInstance *fontInstance, |
| le_int32 scriptCode, le_int32 languageCode, LEErrorCode &success); |
| |
| /** |
| * Override of existing call that provides flags to control typography. |
| * @draft ICU 3.4 |
| */ |
| static LayoutEngine *layoutEngineFactory( |
| const LEFontInstance *fontInstance, |
| le_int32 scriptCode, le_int32 languageCode, |
| le_int32 typo_flags, LEErrorCode &success); |
| }; |
| |
| #endif |