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