[apple/icu.git] / icuSources / layout / unicode / loengine.h

/*
 * @(#)loengine.h	1.0 00/12/11
 *
 * (C) Copyright IBM Corp. 1998-2003 - All Rights Reserved
 *
 */

#ifndef __LOENGINE_H
#define __LOENGINE_H

#include "unicode/utypes.h"
#include "unicode/uobject.h"
#include "unicode/uscript.h"
#include "unicode/unistr.h"

#include "layout/LETypes.h"
#include "layout/LayoutEngine.h"

U_NAMESPACE_BEGIN

/**
 * This is a wrapper class designed to allow ICU clients to
 * use LayoutEngine in a way that is consistent with the rest
 * of ICU.
 *
 * (LayoutEngine was developed seperately from ICU and
 * the same source is used in non-ICU environments, so it cannot
 * be changed to match ICU coding conventions).
 *
 * This class is designed for clients who wish to use LayoutEngine
 * to layout complex text. If you need to subclass LayoutEngine,
 * you'll need to use the LayoutEngine interfaces directly.
 *
 * Basically, it creates an instance of LayoutEngine, stashes
 * it in fLayoutEngine, and uses it to implement the layout
 * functionality.
 *
 * Use the createInstance method to create an ICULayoutEngine. Use
 * delete to destroy it. The layoutChars method computes the glyphs
 * and positions, and saves them in the ICULayoutEngine object.
 * Use getGlyphs, getPositions and getCharIndices to retreive this
 * data.
 *
 * You'll also need an implementation of LEFontInstance for your platform.
 *
 * @see LayoutEngine.h
 * @see LEFontInstance.h
 *
 * @draft ICU 2.2
 */
class U_LAYOUT_API ICULayoutEngine : public UObject {
private:
    /**
     * This holds the instance of LayoutEngine that does all
     * the work.
     */
    LayoutEngine *fLayoutEngine;

    /**
     * This no argument constructor is private so that clients
     * can't envoke it. Clients should use createInstance.
     *
     * @see createInstance
     */
    ICULayoutEngine();

    /**
     * The main constructor. It is defined as private to
     * stop clients from invoking it. Clients should use
     * createInstance.
     *
     * @param layoutEngine - the LayoutEngine that this instance wraps.
     *
     * @see createInstance
     */
    ICULayoutEngine(LayoutEngine *layoutEngine);

public:

    /**
     * The destructor. At least on Windows it needs to be
     * virtual to ensure that it deletes the object from the
     * same heap that createInstance will allocate it from. We
     * don't know why this is...
     *
     * @see createInstance
     *
     * @draft ICU 2.2
     */
    virtual ~ICULayoutEngine();

    /**
     * This method computes the glyph, character index and position arrays
     * for the input characters.
     *
     * @param chars - the input character context
     * @param startOffset - the starting offset of the characters to process
     * @param endOffset - the ending offset of the characters to process
     * @param max - the number of characters in the input context
     * @param rightToLeft - true if the characers are in a right to left directional run
     * @param x - the initial X position
     * @param y - the initial Y position
     * @param success - output parameter set to an error code if the operation fails
     *
     * @return the number of glyphs in the glyph array
     *
     * Note; the glyph, character index and position array can be accessed
     * using the getter method below.
     *
     * @draft ICU 2.2
     */
    int32_t layoutChars(const UChar chars[],
                        int32_t startOffset,
                        int32_t endOffset,
                        int32_t maxOffset,
                        UBool rightToLeft,
                        float x, float y,
                        UErrorCode &success);


    /**
     * This method computes the glyph, character index and position arrays
     * for the input characters.
     *
     * @param str - the input character context
     * @param startOffset - the starting offset of the characters to process
     * @param endOffset - the ending offset of the characters to process
     * @param rightToLeft - true if the characers are in a right to left directional run
     * @param x - the initial X position
     * @param y - the initial Y position
     * @param success - output parameter set to an error code if the operation fails
     *
     * @return the number of glyphs in the glyph array
     *
     * Note; the glyph, character index and position array can be accessed
     * using the getter method below.
     *
     * @draft ICU 2.2
     */
    int32_t layoutString(const UnicodeString &str,
                         int32_t startOffset,
                         int32_t endOffset,
                         UBool rightToLeft,
                         float x, float y,
                         UErrorCode &success);

    /**
     * This method returns the number of glyphs in the glyph array. Note
     * that the number of glyphs will be greater than or equal to the number
     * of characters used to create the LayoutEngine.
     *
     * @return the number of glyphs in the glyph array
     *
     * @draft ICU 2.2
     */
    int32_t countGlyphs() const;

    /**
     * This method copies the glyph array into a caller supplied array.
     * The caller must ensure that the array is large enough to hold all
     * the glyphs.
     *
     * @param glyphs - the destiniation glyph array
     * @param success - output parameter set to an error code if the operation fails
     *
     * @draft ICU 2.2
     */
    void getGlyphs(uint32_t glyphs[], UErrorCode &success);

    /**
     * This method copies the character index array into a caller supplied array.
     * The caller must ensure that the array is large enough to hold a character
     * index for each glyph.
     *
     * @param charIndices - the destiniation character index array
     * @param success - output parameter set to an error code if the operation fails
     *
     * @draft ICU 2.2
     */
    void getCharIndices(int32_t charIndices[], UErrorCode &success);

    /**
     * This method copies the character index array into a caller supplied array.
     * The caller must ensure that the array is large enough to hold a character
     * index for each glyph.
     *
     * @param charIndices - the destiniation character index array
     * @param indexBase - an offset which will be added to each index
     * @param success - output parameter set to an error code if the operation fails
     *
     * @draft ICU 2.2
     */
    void getCharIndices(int32_t charIndices[], int32_t indexBase, UErrorCode &success);

    /**
     * This method copies the position array into a caller supplied array.
     * The caller must ensure that the array is large enough to hold an
     * X and Y position for each glyph, plus an extra X and Y for the
     * advance of the last glyph.
     *
     * @param glyphs - the destiniation position array
     * @param success - output parameter set to an error code if the operation fails
     *
     * @draft ICU 2.2
     */
    void getGlyphPositions(float positions[], UErrorCode &success);

    /**
     * This method returns the X and Y position of the glyph at the
     * given index.
     *
     * Input parameters:
     * @param glyphIndex - the index of the glyph
     *
     * Output parameters:
     * @param x - the glyph's X position
     * @param y - the glyph's Y position
     * @param success - output parameter set to an error code if the operation fails
     *
     * @draft ICU 2.2
     */
    void getGlyphPosition(int32_t glyphIndex, float &x, float &y, UErrorCode &success);

    /**
     * This method returns an ICULayoutEngine capable of laying out text
     * in the given font, script and langauge.
     *
     * @param fontInstance - the font of the text
     * @param scriptCode - the script of the text
     * @param locale - used to determine the language of the text
     * @param success - output parameter set to an error code if the operation fails
     *
     * @return an ICULayoutEngine which can layout text in the given font.
     *
     * NOTE: currently, locale is ignored...
     *
     * @see LEFontInstance
     *
     * @draft ICU 2.2
     */
    static ICULayoutEngine *createInstance(const LEFontInstance *fontInstance,
                                           UScriptCode scriptCode, Locale &locale,
                                           UErrorCode &success);

    /**
     * ICU "poor man's RTTI", returns a UClassID for the actual class.
     *
     * @draft ICU 2.2
     */
    virtual inline UClassID getDynamicClassID() const { return getStaticClassID(); }

    /**
     * ICU "poor man's RTTI", returns a UClassID for this class.
     *
     * @draft ICU 2.2
     */
    static inline UClassID getStaticClassID() { return (UClassID)&fgClassID; }

private:

    /**
     * The address of this static class variable serves as this class's ID
     * for ICU "poor man's RTTI".
     */
    static const char fgClassID;
};

inline ICULayoutEngine::ICULayoutEngine()
{
    // nothing at all...
}

inline ICULayoutEngine::ICULayoutEngine(LayoutEngine *layoutEngine)
    : fLayoutEngine(layoutEngine)
{
    // nothing else to do
}

inline ICULayoutEngine::~ICULayoutEngine()
{
    delete fLayoutEngine;
    fLayoutEngine = 0;
}

inline int32_t ICULayoutEngine::layoutChars(const UChar chars[],
                                            int32_t startOffset,
                                            int32_t endOffset,
                                            int32_t maxOffset,
                                            UBool rightToLeft,
                                            float x, float y,
                                            UErrorCode &success)
{
    // NOTE: call reset() so that clients can safely reuse
    fLayoutEngine->reset();
    return fLayoutEngine->layoutChars(chars,
                                      startOffset,
                                      endOffset - startOffset,
                                      maxOffset,
                                      rightToLeft,
                                      x, y,
                                      (LEErrorCode &) success);
}

inline int32_t ICULayoutEngine::layoutString(const UnicodeString &str,
                                            int32_t startOffset,
                                            int32_t endOffset,
                                            UBool rightToLeft,
                                            float x, float y,
                                            UErrorCode &success)
{
    // NOTE: call reset() so that clients can safely reuse
    fLayoutEngine->reset();
    return fLayoutEngine->layoutChars(str.getBuffer(),
                                      startOffset,
                                      endOffset - startOffset,
                                      str.length(),
                                      rightToLeft,
                                      x, y,
                                      (LEErrorCode &) success);
}

inline int32_t ICULayoutEngine::countGlyphs() const
{
    return fLayoutEngine->getGlyphCount();
}

inline void ICULayoutEngine::getGlyphs(uint32_t glyphs[], UErrorCode &success)
{
    fLayoutEngine->getGlyphs(glyphs, (LEErrorCode &) success);
}

inline void ICULayoutEngine::getCharIndices(int32_t charIndices[], UErrorCode &success)
{
    fLayoutEngine->getCharIndices(charIndices, (LEErrorCode &) success);
}

inline void ICULayoutEngine::getCharIndices(int32_t charIndices[], int32_t indexBase, UErrorCode &success)
{
    fLayoutEngine->getCharIndices(charIndices, indexBase, (LEErrorCode &) success);
}

inline void ICULayoutEngine::getGlyphPositions(float positions[], UErrorCode &success)
{
    fLayoutEngine->getGlyphPositions(positions, (LEErrorCode &) success);
}

inline void ICULayoutEngine::getGlyphPosition(int32_t glyphIndex, float &x, float &y, UErrorCode &success)
{
    fLayoutEngine->getGlyphPosition(glyphIndex, x, y, (LEErrorCode &) success);
}

inline ICULayoutEngine *ICULayoutEngine::createInstance(const LEFontInstance *fontInstance,
                                                        UScriptCode scriptCode,
                                                        Locale &locale, UErrorCode &success)
{
    LayoutEngine *engine = LayoutEngine::layoutEngineFactory(fontInstance,
                                                             (le_int32) scriptCode,
                                                             0,
                                                             (LEErrorCode &) success);

    return new ICULayoutEngine(engine);
}

U_NAMESPACE_END
#endif
Commit	Line	Data
b75a7d8f A	1	/*
	2	* @(#)loengine.h 1.0 00/12/11
	3	*
	4	* (C) Copyright IBM Corp. 1998-2003 - All Rights Reserved
	5	*
	6	*/
	7
	8	#ifndef __LOENGINE_H
	9	#define __LOENGINE_H
	10
	11	#include "unicode/utypes.h"
	12	#include "unicode/uobject.h"
	13	#include "unicode/uscript.h"
	14	#include "unicode/unistr.h"
	15
	16	#include "layout/LETypes.h"
	17	#include "layout/LayoutEngine.h"
	18
	19	U_NAMESPACE_BEGIN
	20
	21	/**
	22	* This is a wrapper class designed to allow ICU clients to
	23	* use LayoutEngine in a way that is consistent with the rest
	24	* of ICU.
	25	*
	26	* (LayoutEngine was developed seperately from ICU and
	27	* the same source is used in non-ICU environments, so it cannot
	28	* be changed to match ICU coding conventions).
	29	*
	30	* This class is designed for clients who wish to use LayoutEngine
	31	* to layout complex text. If you need to subclass LayoutEngine,
	32	* you'll need to use the LayoutEngine interfaces directly.
	33	*
	34	* Basically, it creates an instance of LayoutEngine, stashes
	35	* it in fLayoutEngine, and uses it to implement the layout
	36	* functionality.
	37	*
	38	* Use the createInstance method to create an ICULayoutEngine. Use
	39	* delete to destroy it. The layoutChars method computes the glyphs
	40	* and positions, and saves them in the ICULayoutEngine object.
	41	* Use getGlyphs, getPositions and getCharIndices to retreive this
	42	* data.
	43	*
	44	* You'll also need an implementation of LEFontInstance for your platform.
	45	*
	46	* @see LayoutEngine.h
	47	* @see LEFontInstance.h
	48	*
	49	* @draft ICU 2.2
	50	*/
	51	class U_LAYOUT_API ICULayoutEngine : public UObject {
	52	private:
	53	/**
	54	* This holds the instance of LayoutEngine that does all
	55	* the work.
	56	*/
	57	LayoutEngine *fLayoutEngine;
	58
	59	/**
	60	* This no argument constructor is private so that clients
	61	* can't envoke it. Clients should use createInstance.
	62	*
	63	* @see createInstance
	64	*/
65	ICULayoutEngine();
66
67	/**
68	* The main constructor. It is defined as private to
69	* stop clients from invoking it. Clients should use
70	* createInstance.
71	*
72	* @param layoutEngine - the LayoutEngine that this instance wraps.
73	*
74	* @see createInstance
75	*/
76	ICULayoutEngine(LayoutEngine *layoutEngine);
77
78	public:
79
80	/**
81	* The destructor. At least on Windows it needs to be
82	* virtual to ensure that it deletes the object from the
83	* same heap that createInstance will allocate it from. We
84	* don't know why this is...
85	*
86	* @see createInstance
87	*
88	* @draft ICU 2.2
89	*/
90	virtual ~ICULayoutEngine();
91
92	/**
93	* This method computes the glyph, character index and position arrays
94	* for the input characters.
95	*
96	* @param chars - the input character context
97	* @param startOffset - the starting offset of the characters to process
98	* @param endOffset - the ending offset of the characters to process
99	* @param max - the number of characters in the input context
100	* @param rightToLeft - true if the characers are in a right to left directional run
101	* @param x - the initial X position
102	* @param y - the initial Y position
103	* @param success - output parameter set to an error code if the operation fails
104	*
105	* @return the number of glyphs in the glyph array
106	*
107	* Note; the glyph, character index and position array can be accessed
108	* using the getter method below.
109	*
110	* @draft ICU 2.2
111	*/
112	int32_t layoutChars(const UChar chars[],
113	int32_t startOffset,
114	int32_t endOffset,
115	int32_t maxOffset,
116	UBool rightToLeft,
117	float x, float y,
118	UErrorCode &success);
119
120
121	/**
122	* This method computes the glyph, character index and position arrays
123	* for the input characters.
124	*
125	* @param str - the input character context
126	* @param startOffset - the starting offset of the characters to process
127	* @param endOffset - the ending offset of the characters to process
128	* @param rightToLeft - true if the characers are in a right to left directional run
129	* @param x - the initial X position
130	* @param y - the initial Y position
131	* @param success - output parameter set to an error code if the operation fails
132	*
133	* @return the number of glyphs in the glyph array
134	*
135	* Note; the glyph, character index and position array can be accessed
136	* using the getter method below.
137	*
138	* @draft ICU 2.2
139	*/
140	int32_t layoutString(const UnicodeString &str,
141	int32_t startOffset,
142	int32_t endOffset,
143	UBool rightToLeft,
144	float x, float y,
145	UErrorCode &success);
146
147	/**
148	* This method returns the number of glyphs in the glyph array. Note
149	* that the number of glyphs will be greater than or equal to the number
150	* of characters used to create the LayoutEngine.
151	*
152	* @return the number of glyphs in the glyph array
153	*
154	* @draft ICU 2.2
155	*/
156	int32_t countGlyphs() const;
157
158	/**
159	* This method copies the glyph array into a caller supplied array.
160	* The caller must ensure that the array is large enough to hold all
161	* the glyphs.
162	*
163	* @param glyphs - the destiniation glyph array
164	* @param success - output parameter set to an error code if the operation fails
165	*
166	* @draft ICU 2.2
167	*/
168	void getGlyphs(uint32_t glyphs[], UErrorCode &success);
169
170	/**
171	* This method copies the character index array into a caller supplied array.
172	* The caller must ensure that the array is large enough to hold a character
173	* index for each glyph.
174	*
175	* @param charIndices - the destiniation character index array
176	* @param success - output parameter set to an error code if the operation fails
177	*
178	* @draft ICU 2.2
179	*/
180	void getCharIndices(int32_t charIndices[], UErrorCode &success);
181
182	/**
183	* This method copies the character index array into a caller supplied array.
184	* The caller must ensure that the array is large enough to hold a character
185	* index for each glyph.
186	*
187	* @param charIndices - the destiniation character index array
188	* @param indexBase - an offset which will be added to each index
189	* @param success - output parameter set to an error code if the operation fails
190	*
191	* @draft ICU 2.2
192	*/
193	void getCharIndices(int32_t charIndices[], int32_t indexBase, UErrorCode &success);
194
195	/**
196	* This method copies the position array into a caller supplied array.
197	* The caller must ensure that the array is large enough to hold an
198	* X and Y position for each glyph, plus an extra X and Y for the
199	* advance of the last glyph.
200	*
201	* @param glyphs - the destiniation position array
202	* @param success - output parameter set to an error code if the operation fails
203	*
204	* @draft ICU 2.2
205	*/
206	void getGlyphPositions(float positions[], UErrorCode &success);
207
208	/**
209	* This method returns the X and Y position of the glyph at the
210	* given index.
211	*
212	* Input parameters:
213	* @param glyphIndex - the index of the glyph
214	*
215	* Output parameters:
216	* @param x - the glyph's X position
217	* @param y - the glyph's Y position
218	* @param success - output parameter set to an error code if the operation fails
219	*
220	* @draft ICU 2.2
221	*/
222	void getGlyphPosition(int32_t glyphIndex, float &x, float &y, UErrorCode &success);
223
224	/**
225	* This method returns an ICULayoutEngine capable of laying out text
226	* in the given font, script and langauge.
227	*
228	* @param fontInstance - the font of the text
229	* @param scriptCode - the script of the text
230	* @param locale - used to determine the language of the text
231	* @param success - output parameter set to an error code if the operation fails
232	*
233	* @return an ICULayoutEngine which can layout text in the given font.
234	*
235	* NOTE: currently, locale is ignored...
236	*
237	* @see LEFontInstance
238	*
239	* @draft ICU 2.2
240	*/
241	static ICULayoutEngine createInstance(const LEFontInstance fontInstance,
242	UScriptCode scriptCode, Locale &locale,
243	UErrorCode &success);
244
245	/**
246	* ICU "poor man's RTTI", returns a UClassID for the actual class.
247	*
248	* @draft ICU 2.2
249	*/
250	virtual inline UClassID getDynamicClassID() const { return getStaticClassID(); }
251
252	/**
253	* ICU "poor man's RTTI", returns a UClassID for this class.
254	*
255	* @draft ICU 2.2
256	*/
257	static inline UClassID getStaticClassID() { return (UClassID)&fgClassID; }
258
259	private:
260
261	/**
262	* The address of this static class variable serves as this class's ID
263	* for ICU "poor man's RTTI".
264	*/
265	static const char fgClassID;
266	};
267
268	inline ICULayoutEngine::ICULayoutEngine()
269	{
270	// nothing at all...
271	}
272
273	inline ICULayoutEngine::ICULayoutEngine(LayoutEngine *layoutEngine)
274	: fLayoutEngine(layoutEngine)
275	{
276	// nothing else to do
277	}
278
279	inline ICULayoutEngine::~ICULayoutEngine()
280	{
281	delete fLayoutEngine;
282	fLayoutEngine = 0;
283	}
284
285	inline int32_t ICULayoutEngine::layoutChars(const UChar chars[],
286	int32_t startOffset,
287	int32_t endOffset,
288	int32_t maxOffset,
289	UBool rightToLeft,
290	float x, float y,
291	UErrorCode &success)
292	{
293	// NOTE: call reset() so that clients can safely reuse
294	fLayoutEngine->reset();
295	return fLayoutEngine->layoutChars(chars,
296	startOffset,
297	endOffset - startOffset,
298	maxOffset,
299	rightToLeft,
300	x, y,
301	(LEErrorCode &) success);
302	}
303
304	inline int32_t ICULayoutEngine::layoutString(const UnicodeString &str,
305	int32_t startOffset,
306	int32_t endOffset,
307	UBool rightToLeft,
308	float x, float y,
309	UErrorCode &success)
310	{
311	// NOTE: call reset() so that clients can safely reuse
312	fLayoutEngine->reset();
313	return fLayoutEngine->layoutChars(str.getBuffer(),
314	startOffset,
315	endOffset - startOffset,
316	str.length(),
317	rightToLeft,
318	x, y,
319	(LEErrorCode &) success);
320	}
321
322	inline int32_t ICULayoutEngine::countGlyphs() const
323	{
324	return fLayoutEngine->getGlyphCount();
325	}
326
327	inline void ICULayoutEngine::getGlyphs(uint32_t glyphs[], UErrorCode &success)
328	{
329	fLayoutEngine->getGlyphs(glyphs, (LEErrorCode &) success);
330	}
331
332	inline void ICULayoutEngine::getCharIndices(int32_t charIndices[], UErrorCode &success)
333	{
334	fLayoutEngine->getCharIndices(charIndices, (LEErrorCode &) success);
335	}
336
337	inline void ICULayoutEngine::getCharIndices(int32_t charIndices[], int32_t indexBase, UErrorCode &success)
338	{
339	fLayoutEngine->getCharIndices(charIndices, indexBase, (LEErrorCode &) success);
340	}
341
342	inline void ICULayoutEngine::getGlyphPositions(float positions[], UErrorCode &success)
343	{
344	fLayoutEngine->getGlyphPositions(positions, (LEErrorCode &) success);
345	}
346
347	inline void ICULayoutEngine::getGlyphPosition(int32_t glyphIndex, float &x, float &y, UErrorCode &success)
348	{
349	fLayoutEngine->getGlyphPosition(glyphIndex, x, y, (LEErrorCode &) success);
350	}
351
352	inline ICULayoutEngine ICULayoutEngine::createInstance(const LEFontInstance fontInstance,
353	UScriptCode scriptCode,
354	Locale &locale, UErrorCode &success)
355	{
356	LayoutEngine *engine = LayoutEngine::layoutEngineFactory(fontInstance,
357	(le_int32) scriptCode,
358	0,
359	(LEErrorCode &) success);
360
361	return new ICULayoutEngine(engine);
362	}
363
364	U_NAMESPACE_END
365	#endif