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 */
28typedef void le_engine;
29
30/**
31 * The opaque type for a font instance.
32 *
33 * @internal
34 */
35typedef 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 */
52U_INTERNAL le_engine * U_EXPORT2
53le_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 */
67U_INTERNAL void U_EXPORT2
68le_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 */
94U_INTERNAL le_int32 U_EXPORT2
95le_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 */
117U_INTERNAL le_int32 U_EXPORT2
118le_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 */
132U_INTERNAL void U_EXPORT2
133le_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 */
148U_INTERNAL void U_EXPORT2
149le_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 */
165U_INTERNAL void U_EXPORT2
166le_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 */
183U_INTERNAL void U_EXPORT2
184le_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 */
203U_INTERNAL void U_EXPORT2
204le_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 */
220U_INTERNAL void U_EXPORT2
221le_reset(le_engine *engine,
222         LEErrorCode *success);
223#endif  /* U_HIDE_INTERNAL_API */
224
225#endif
226