icuSources/layout/loengine.h

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