icuSources/layout/loengine.h

   1 /*
   2  *
   3  * (C) Copyright IBM Corp. 1998-2011 - All Rights Reserved
   4  *
   5  */
   6
   7 #ifndef __LOENGINE_H
   8 #define __LOENGINE_H
   9
  10 #include "LETypes.h"
  11
  12 #ifndef U_HIDE_INTERNAL_API
  13 /**
  14  * \file
  15  * \brief C API for complex text layout.
  16  * \internal
  17  *
  18  * This is a technology preview. The API may
  19  * change significantly.
  20  *
  21  */
  22
  23 /**
  24  * The opaque type for a LayoutEngine.
  25  *
  26  * @internal
  27  */
  28 typedef void le_engine;
  29
  30 /**
  31  * The opaque type for a font instance.
  32  *
  33  * @internal
  34  */
  35 typedef void le_font;
  36
  37 /**
  38  * This function returns an le_engine capable of laying out text
  39  * in the given font, script and langauge. Note that the LayoutEngine
  40  * returned may be a subclass of LayoutEngine.
  41  *
  42  * @param font - the font of the text
  43  * @param scriptCode - the script of the text
  44  * @param languageCode - the language of the text
  45  * @param typo_flags - flags that control layout features like kerning and ligatures.
  46  * @param success - output parameter set to an error code if the operation fails
  47  *
  48  * @return an le_engine which can layout text in the given font.
  49  *
  50  * @internal
  51  */
  52 U_INTERNAL le_engine * U_EXPORT2
  53 le_create(const le_font *font,
  54           le_int32 scriptCode,
  55           le_int32 languageCode,
  56           le_int32 typo_flags,
  57           LEErrorCode *success);
  58
  59 /**
  60  * This function closes the given LayoutEngine. After
  61  * it returns, the le_engine is no longer valid.
  62  *
  63  * @param engine - the LayoutEngine to close.
  64  *
  65  * @internal
  66  */
  67 U_INTERNAL void U_EXPORT2
  68 le_close(le_engine *engine);
  69
  70 /**
  71  * This routine will compute the glyph, character index and position arrays.
  72  *
  73  * @param engine - the LayoutEngine
  74  * @param chars - the input character context
  75  * @param offset - the offset of the first character to process
  76  * @param count - the number of characters to process
  77  * @param max - the number of characters in the input context
  78  * @param rightToLeft - TRUE if the characers are in a right to left directional run
  79  * @param x - the initial X position
  80  * @param y - the initial Y position
  81  * @param success - output parameter set to an error code if the operation fails
  82  *
  83  * @return the number of glyphs in the glyph array
  84  *
  85  * Note: The glyph, character index and position array can be accessed
  86  * using the getter routines below.
  87  *
  88  * Note: If you call this function more than once, you must call the reset()
  89  * function first to free the glyph, character index and position arrays
  90  * allocated by the previous call.
  91  *
  92  * @internal
  93  */
  94 U_INTERNAL le_int32 U_EXPORT2
  95 le_layoutChars(le_engine *engine,
  96                const LEUnicode chars[],
  97                le_int32 offset,
  98                le_int32 count,
  99                le_int32 max,
 100                le_bool rightToLeft,
 101                float x,
 102                float y,
 103                LEErrorCode *success);
 104
 105 /**
 106  * This function returns the number of glyphs in the glyph array. Note
 107  * that the number of glyphs will be greater than or equal to the number
 108  * of characters used to create the LayoutEngine.
 109  *
 110  * @param engine - the LayoutEngine
 111  * @param success - output parameter set to an error code if the operation fails.
 112  *
 113  * @return the number of glyphs in the glyph array
 114  *
 115  * @internal
 116  */
 117 U_INTERNAL le_int32 U_EXPORT2
 118 le_getGlyphCount(le_engine *engine,
 119                  LEErrorCode *success);
 120
 121 /**
 122  * This function copies the glyph array into a caller supplied array.
 123  * The caller must ensure that the array is large enough to hold all
 124  * the glyphs.
 125  *
 126  * @param engine - the LayoutEngine
 127  * @param glyphs - the destiniation glyph array
 128  * @param success - set to an error code if the operation fails
 129  *
 130  * @internal
 131  */
 132 U_INTERNAL void U_EXPORT2
 133 le_getGlyphs(le_engine *engine,
 134              LEGlyphID glyphs[],
 135              LEErrorCode *success);
 136
 137 /**
 138  * This function copies the character index array into a caller supplied array.
 139  * The caller must ensure that the array is large enough to hold a
 140  * character index for each glyph.
 141  *
 142  * @param engine - the LayoutEngine
 143  * @param charIndices - the destiniation character index array
 144  * @param success - set to an error code if the operation fails
 145  *
 146  * @internal
 147  */
 148 U_INTERNAL void U_EXPORT2
 149 le_getCharIndices(le_engine *engine,
 150                   le_int32 charIndices[],
 151                   LEErrorCode *success);
 152
 153 /**
 154  * This function copies the character index array into a caller supplied array.
 155  * The caller must ensure that the array is large enough to hold a
 156  * character index for each glyph.
 157  *
 158  * @param engine - the LayoutEngine
 159  * @param charIndices - the destiniation character index array
 160  * @param indexBase - an offset that will be added to each index.
 161  * @param success - set to an error code if the operation fails
 162  *
 163  * @internal
 164  */
 165 U_INTERNAL void U_EXPORT2
 166 le_getCharIndicesWithBase(le_engine *engine,
 167                   le_int32 charIndices[],
 168                   le_int32 indexBase,
 169                   LEErrorCode *success);
 170
 171 /**
 172  * This function copies the position array into a caller supplied array.
 173  * The caller must ensure that the array is large enough to hold an
 174  * X and Y position for each glyph, plus an extra X and Y for the
 175  * advance of the last glyph.
 176  *
 177  * @param engine - the LayoutEngine
 178  * @param positions - the destiniation position array
 179  * @param success - set to an error code if the operation fails
 180  *
 181  * @internal
 182  */
 183 U_INTERNAL void U_EXPORT2
 184 le_getGlyphPositions(le_engine *engine,
 185                      float positions[],
 186                      LEErrorCode *success);
 187
 188 /**
 189  * This function returns the X and Y position of the glyph at
 190  * the given index.
 191  *
 192  * Input parameters:
 193  * @param engine - the LayoutEngine
 194  * @param glyphIndex - the index of the glyph
 195  *
 196  * Output parameters:
 197  * @param x - the glyph's X position
 198  * @param y - the glyph's Y position
 199  * @param success - set to an error code if the operation fails
 200  *
 201  * @internal
 202  */
 203 U_INTERNAL void U_EXPORT2
 204 le_getGlyphPosition(le_engine *engine,
 205                     le_int32 glyphIndex,
 206                     float *x,
 207                     float *y,
 208                     LEErrorCode *success);
 209
 210 /**
 211  * This function frees the glyph, character index and position arrays
 212  * so that the LayoutEngine can be reused to layout a different
 213  * characer array. (This function is also called by le_close)
 214  *
 215  * @param engine - the LayoutEngine
 216  * @param success - set to an error code if the operation fails
 217  *
 218  * @internal
 219  */
 220 U_INTERNAL void U_EXPORT2
 221 le_reset(le_engine *engine,
 222          LEErrorCode *success);
 223 #endif  /* U_HIDE_INTERNAL_API */
 224
 225 #endif