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 */ 27typedef void le_engine; 28 29/** 30 * The opaque type for a font instance. 31 * 32 * @internal 33 */ 34typedef 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 */ 51U_INTERNAL le_engine * U_EXPORT2 52le_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 */ 66U_INTERNAL void U_EXPORT2 67le_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 */ 93U_INTERNAL le_int32 U_EXPORT2 94le_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 */ 116U_INTERNAL le_int32 U_EXPORT2 117le_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 */ 131U_INTERNAL void U_EXPORT2 132le_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 */ 147U_INTERNAL void U_EXPORT2 148le_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 */ 164U_INTERNAL void U_EXPORT2 165le_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 */ 182U_INTERNAL void U_EXPORT2 183le_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 */ 202U_INTERNAL void U_EXPORT2 203le_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 */ 219U_INTERNAL void U_EXPORT2 220le_reset(le_engine *engine, 221 LEErrorCode *success); 222 223#endif 224