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 226
