1 

     2 /*

     3  *

     4  * (C) Copyright IBM Corp. 1998-2005 - 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      * The glyph ID of Malayalam RA for RAKAR

   112      *

   113      * @internal

   114      */

   115     LEGlyphID fGidOfRA;

   116     

   117     /**

   118      * This constructs an instance for a given font, script and language. Subclass constructors

   119      * must call this constructor.

   120      *

   121      * @param fontInstance - the font for the text

   122      * @param scriptCode - the script for the text

   123      * @param languageCode - the language for the text

   124      * @param typoFlags - the typographic control flags for the text.  Set bit 1 if kerning

   125      * is desired, set bit 2 if ligature formation is desired.  Others are reserved.

   126      *

   127      * @see LEFontInstance

   128      * @see ScriptAndLanguageTags.h

   129      *

   130      * @internal

   131      */

   132     LayoutEngine(const LEFontInstance *fontInstance, le_int32 scriptCode, le_int32 languageCode, le_int32 typoFlags);

   133 

   134     /**

   135      * Returns true if the constructor failed, leaving the object in an

   136      * inconsistent state.

   137      *

   138      * @internal

   139      */

   140     le_bool isBogus();

   141 

   142     /**

   143      * This overrides the default no argument constructor to make it

   144      * difficult for clients to call it. Clients are expected to call

   145      * layoutEngineFactory.

   146      *

   147      * @internal

   148      */

   149     LayoutEngine();

   150 

   151     /**

   152      * This method does any required pre-processing to the input characters. It

   153      * may generate output characters that differ from the input charcters due to

   154      * insertions, deletions, or reorderings. In such cases, it will also generate an

   155      * output character index array reflecting these changes.

   156      *

   157      * Subclasses must override this method.

   158      *

   159      * Input parameters:

   160      * @param chars - the input character context

   161      * @param offset - the index of the first character to process

   162      * @param count - the number of characters to process

   163      * @param max - the number of characters in the input context

   164      * @param rightToLeft - TRUE if the characters are in a right to left directional run

   165      * @param outChars - the output character array, if different from the input

   166      * @param glyphStorage - the object that holds the per-glyph storage. The character index array may be set.

   167      * @param success - set to an error code if the operation fails

   168      *

   169      * @return the output character count (input character count if no change)

   170      *

   171      * @internal

   172      */

   173     virtual le_int32 characterProcessing(const LEUnicode chars[], le_int32 offset, le_int32 count, le_int32 max, le_bool rightToLeft,

   174             LEUnicode *&outChars, LEGlyphStorage &glyphStorage, LEErrorCode &success);

   175 

   176     /**

   177      * This method does the glyph processing. It converts an array of characters

   178      * into an array of glyph indices and character indices. The characters to be

   179      * processed are passed in a surrounding context. The context is specified as

   180      * a starting address and a maximum character count. An offset and a count are

   181      * used to specify the characters to be processed.

   182      *

   183      * The default implementation of this method only does character to glyph mapping.

   184      * Subclasses needing more elaborate glyph processing must override this method.

   185      *

   186      * Input parameters:

   187      * @param chars - the character context

   188      * @param offset - the offset of the first character to process

   189      * @param count - the number of characters to process

   190      * @param max - the number of characters in the context.

   191      * @param rightToLeft - TRUE if the text is in a right to left directional run

   192      * @param glyphStorage - the object which holds the per-glyph storage. The glyph and char indices arrays

   193      *                       will be set.

   194      *

   195      * Output parameters:

   196      * @param success - set to an error code if the operation fails

   197      *

   198      * @return the number of glyphs in the glyph index array

   199      *

   200      * @internal

   201      */

   202     virtual le_int32 computeGlyphs(const LEUnicode chars[], le_int32 offset, le_int32 count, le_int32 max, le_bool rightToLeft, LEGlyphStorage &glyphStorage, LEErrorCode &success);

   203 

   204     /**

   205      * This method does basic glyph positioning. The default implementation positions

   206      * the glyphs based on their advance widths. This is sufficient for most uses. It

   207      * is not expected that many subclasses will override this method.

   208      *

   209      * Input parameters:

   210      * @param glyphStorage - the object which holds the per-glyph storage. The glyph position array will be set.

   211      * @param x - the starting X position

   212      * @param y - the starting Y position

   213      * @param success - set to an error code if the operation fails

   214      *

   215      * @internal

   216      */

   217     virtual void positionGlyphs(LEGlyphStorage &glyphStorage, float x, float y, LEErrorCode &success);

   218 

   219     /**

   220      * This method does positioning adjustments like accent positioning and

   221      * kerning. The default implementation does nothing. Subclasses needing

   222      * position adjustments must override this method.

   223      *

   224      * Note that this method has both characters and glyphs as input so that

   225      * it can use the character codes to determine glyph types if that information

   226      * isn't directly available. (e.g. Some Arabic OpenType fonts don't have a GDEF

   227      * table)

   228      *

   229      * @param chars - the input character context

   230      * @param offset - the offset of the first character to process

   231      * @param count - the number of characters to process

   232      * @param reverse - <code>TRUE</code> if the glyphs in the glyph array have been reordered

   233      * @param glyphStorage - the object which holds the per-glyph storage. The glyph positions will be

   234      *                       adjusted as needed.

   235      * @param success - output parameter set to an error code if the operation fails

   236      *

   237      * @internal

   238      */

   239     virtual void adjustGlyphPositions(const LEUnicode chars[], le_int32 offset, le_int32 count, le_bool reverse, LEGlyphStorage &glyphStorage, LEErrorCode &success);

   240 

   241     /**

   242      * This method gets a table from the font associated with

   243      * the text. The default implementation gets the table from

   244      * the font instance. Subclasses which need to get the tables

   245      * some other way must override this method.

   246      * 

   247      * @param tableTag - the four byte table tag.

   248      *

   249      * @return the address of the table.

   250      *

   251      * @internal

   252      */

   253     virtual const void *getFontTable(LETag tableTag) const;

   254 

   255     /**

   256      * This method does character to glyph mapping. The default implementation

   257      * uses the font instance to do the mapping. It will allocate the glyph and

   258      * character index arrays if they're not already allocated. If it allocates the

   259      * character index array, it will fill it it.

   260      *

   261      * This method supports right to left

   262      * text with the ability to store the glyphs in reverse order, and by supporting

   263      * character mirroring, which will replace a character which has a left and right

   264      * form, such as parens, with the opposite form before mapping it to a glyph index.

   265      *

   266      * Input parameters:

   267      * @param chars - the input character context

   268      * @param offset - the offset of the first character to be mapped

   269      * @param count - the number of characters to be mapped

   270      * @param reverse - if <code>TRUE</code>, the output will be in reverse order

   271      * @param mirror - if <code>TRUE</code>, do character mirroring

   272      * @param glyphStorage - the object which holds the per-glyph storage. The glyph and char

   273      *                       indices arrays will be filled in.

   274      * @param success - set to an error code if the operation fails

   275      *

   276      * @see LEFontInstance

   277      *

   278      * @internal

   279      */

   280     virtual void mapCharsToGlyphs(const LEUnicode chars[], le_int32 offset, le_int32 count, le_bool reverse, le_bool mirror, LEGlyphStorage &glyphStorage, LEErrorCode &success);

   281 

   282     /**

   283      * This is a convenience method that forces the advance width of mark

   284      * glyphs to be zero, which is required for proper selection and highlighting.

   285      * 

   286      * @param glyphStorage - the object containing the per-glyph storage. The positions array will be modified.

   287      * @param markFilter - used to identify mark glyphs

   288      * @param success - output parameter set to an error code if the operation fails

   289      *

   290      * @see LEGlyphFilter

   291      *

   292      * @internal

   293      */

   294     static void adjustMarkGlyphs(LEGlyphStorage &glyphStorage, LEGlyphFilter *markFilter, LEErrorCode &success);

   295 

   296 

   297     /**

   298      * This is a convenience method that forces the advance width of mark

   299      * glyphs to be zero, which is required for proper selection and highlighting.

   300      * This method uses the input characters to identify marks. This is required in

   301      * cases where the font does not contain enough information to identify them based

   302      * on the glyph IDs.

   303      * 

   304      * @param chars - the array of input characters

   305      * @param charCount - the number of input characers

   306      * @param glyphStorage - the object containing the per-glyph storage. The positions array will be modified.

   307      * @param reverse - <code>TRUE</code> if the glyph array has been reordered

   308      * @param markFilter - used to identify mark glyphs

   309      * @param success - output parameter set to an error code if the operation fails

   310      *

   311      * @see LEGlyphFilter

   312      *

   313      * @internal

   314      */

   315     static void adjustMarkGlyphs(const LEUnicode chars[], le_int32 charCount, le_bool reverse, LEGlyphStorage &glyphStorage, LEGlyphFilter *markFilter, LEErrorCode &success);

   316 

   317 

   318 public:

   319     /**

   320      * The destructor. It will free any storage allocated for the

   321      * glyph, character index and position arrays by calling the reset

   322      * method. It is declared virtual so that it will be invoked by the

   323      * subclass destructors.

   324      *

   325      * @stable ICU 2.8

   326      */

   327     virtual ~LayoutEngine();

   328 

   329     /**

   330      * This method will invoke the layout steps in their correct order by calling

   331      * the computeGlyphs, positionGlyphs and adjustGlyphPosition methods.. It will

   332      * compute the glyph, character index and position arrays.

   333      *

   334      * @param chars - the input character context

   335      * @param offset - the offset of the first character to process

   336      * @param count - the number of characters to process

   337      * @param max - the number of characters in the input context

   338      * @param rightToLeft - TRUE if the characers are in a right to left directional run

   339      * @param x - the initial X position

   340      * @param y - the initial Y position

   341      * @param success - output parameter set to an error code if the operation fails

   342      *

   343      * @return the number of glyphs in the glyph array

   344      *

   345      * Note; the glyph, character index and position array can be accessed

   346      * using the getter method below.

   347      *

   348      * @stable ICU 2.8

   349      */

   350     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);

   351 

   352     /**

   353      * This method returns the number of glyphs in the glyph array. Note

   354      * that the number of glyphs will be greater than or equal to the number

   355      * of characters used to create the LayoutEngine.

   356      *

   357      * @return the number of glyphs in the glyph array

   358      *

   359      * @stable ICU 2.8

   360      */

   361     le_int32 getGlyphCount() const;

   362 

   363     /**

   364      * This method copies the glyph array into a caller supplied array.

   365      * The caller must ensure that the array is large enough to hold all

   366      * the glyphs.

   367      *

   368      * @param glyphs - the destiniation glyph array

   369      * @param success - set to an error code if the operation fails

   370      *

   371      * @stable ICU 2.8

   372      */

   373     void getGlyphs(LEGlyphID glyphs[], LEErrorCode &success) const;

   374 

   375     /**

   376      * This method copies the glyph array into a caller supplied array,

   377      * ORing in extra bits. (This functionality is needed by the JDK,

   378      * which uses 32 bits pre glyph idex, with the high 16 bits encoding

   379      * the composite font slot number)

   380      *

   381      * @param glyphs - the destination (32 bit) glyph array

   382      * @param extraBits - this value will be ORed with each glyph index

   383      * @param success - set to an error code if the operation fails

   384      *

   385      * @stable ICU 2.8

   386      */

   387     virtual void getGlyphs(le_uint32 glyphs[], le_uint32 extraBits, LEErrorCode &success) const;

   388 

   389     /**

   390      * This method copies the character index array into a caller supplied array.

   391      * The caller must ensure that the array is large enough to hold a

   392      * character index for each glyph.

   393      *

   394      * @param charIndices - the destiniation character index array

   395      * @param success - set to an error code if the operation fails

   396      *

   397      * @stable ICU 2.8

   398      */

   399     void getCharIndices(le_int32 charIndices[], LEErrorCode &success) const;

   400 

   401     /**

   402      * This method copies the character index array into a caller supplied array.

   403      * The caller must ensure that the array is large enough to hold a

   404      * character index for each glyph.

   405      *

   406      * @param charIndices - the destiniation character index array

   407      * @param indexBase - an offset which will be added to each index

   408      * @param success - set to an error code if the operation fails

   409      *

   410      * @stable ICU 2.8

   411      */

   412     void getCharIndices(le_int32 charIndices[], le_int32 indexBase, LEErrorCode &success) const;

   413 

   414     /**

   415      * This method copies the position array into a caller supplied array.

   416      * The caller must ensure that the array is large enough to hold an

   417      * X and Y position for each glyph, plus an extra X and Y for the

   418      * advance of the last glyph.

   419      *

   420      * @param positions - the destiniation position array

   421      * @param success - set to an error code if the operation fails

   422      *

   423      * @stable ICU 2.8

   424      */

   425     void getGlyphPositions(float positions[], LEErrorCode &success) const;

   426 

   427     /**

   428      * This method returns the X and Y position of the glyph at

   429      * the given index.

   430      *

   431      * Input parameters:

   432      * @param glyphIndex - the index of the glyph

   433      *

   434      * Output parameters:

   435      * @param x - the glyph's X position

   436      * @param y - the glyph's Y position

   437      * @param success - set to an error code if the operation fails

   438      *

   439      * @stable ICU 2.8

   440      */

   441     void getGlyphPosition(le_int32 glyphIndex, float &x, float &y, LEErrorCode &success) const;

   442 

   443     /**

   444      * This method frees the glyph, character index and position arrays

   445      * so that the LayoutEngine can be reused to layout a different

   446      * characer array. (This method is also called by the destructor)

   447      *

   448      * @stable ICU 2.8

   449      */

   450     virtual void reset();

   451 

   452     /**

   453      * This method returns a LayoutEngine capable of laying out text

   454      * in the given font, script and langauge. Note that the LayoutEngine

   455      * returned may be a subclass of LayoutEngine.

   456      *

   457      * @param fontInstance - the font of the text

   458      * @param scriptCode - the script of the text

   459      * @param languageCode - the language of the text

   460      * @param success - output parameter set to an error code if the operation fails

   461      *

   462      * @return a LayoutEngine which can layout text in the given font.

   463      *

   464      * @see LEFontInstance

   465      *

   466      * @stable ICU 2.8

   467      */

   468     static LayoutEngine *layoutEngineFactory(const LEFontInstance *fontInstance, le_int32 scriptCode, le_int32 languageCode, LEErrorCode &success);

   469 

   470     /**

   471      * Override of existing call that provides flags to control typography.

   472      * @draft ICU 3.4

   473      */

   474     static LayoutEngine *layoutEngineFactory(const LEFontInstance *fontInstance, le_int32 scriptCode, le_int32 languageCode, le_int32 typo_flags, LEErrorCode &success);

   475 

   476     /**

   477      * ICU "poor man's RTTI", returns a UClassID for the actual class.

   478      *

   479      * @stable ICU 2.8

   480      */

   481     virtual UClassID getDynamicClassID() const;

   482 

   483     /**

   484      * ICU "poor man's RTTI", returns a UClassID for this class.

   485      *

   486      * @stable ICU 2.8

   487      */

   488     static UClassID getStaticClassID();

   489 

   490 };

   491 

   492 U_NAMESPACE_END

   493 #endif

   494