1 /*
2 **********************************************************************
3 * Copyright (C) 1998-2010, International Business Machines
4 * Corporation and others. All Rights Reserved.
5 **********************************************************************
6 */
7
8 #ifndef __LEGLYPHSTORAGE_H
9 #define __LEGLYPHSTORAGE_H
10
11 #include "LETypes.h"
12 #include "LEInsertionList.h"
13
14 /**
15 * \file
16 * \brief C++ API: This class encapsulates the per-glyph storage used by the ICU LayoutEngine.
17 */
18
19 U_NAMESPACE_BEGIN
20
21 /**
22 * This class encapsulates the per-glyph storage used by the ICU LayoutEngine.
23 * For each glyph it holds the glyph ID, the index of the backing store character
24 * which produced the glyph, the X and Y position of the glyph and an auxillary data
25 * pointer.
26 *
27 * The storage is growable using the <code>LEInsertionList</code> class.
28 *
29 *
30 * @see LEInsertionList.h
31 *
32 * @stable ICU 3.6
33 */
34 class U_LAYOUT_API LEGlyphStorage : public UObject, protected LEInsertionCallback
35 {
36 private:
37 /**
38 * The number of entries in the per-glyph arrays.
39 *
40 * @internal
41 */
42 le_int32 fGlyphCount;
43
44 /**
45 * The glyph ID array.
46 *
47 * @internal
48 */
49 LEGlyphID *fGlyphs;
50
51 /**
52 * The char indices array.
53 *
54 * @internal
55 */
56 le_int32 *fCharIndices;
57
58 /**
59 * The glyph positions array.
60 *
61 * @internal
62 */
63 float *fPositions;
64
65 /**
66 * The auxillary data array.
67 *
68 * @internal
69 */
70 le_uint32 *fAuxData;
71
72
73 /**
74 * The insertion list, used to grow the above arrays.
75 *
76 * @internal
77 */
78 LEInsertionList *fInsertionList;
79
80 /**
81 * The source index while growing the data arrays.
82 *
83 * @internal
84 */
85 le_int32 fSrcIndex;
86
87 /**
88 * The destination index used while growing the data arrays.
89 *
90 * @internal
91 */
92 le_int32 fDestIndex;
93
94 protected:
95 /**
96 * This implements <code>LEInsertionCallback</code>. The <code>LEInsertionList</code>
97 * will call this method once for each insertion.
98 *
99 * @param atPosition the position of the insertion
100 * @param count the number of glyphs being inserted
101 * @param newGlyphs the address of the new glyph IDs
102 *
103 * @return <code>true</code> if <code>LEInsertionList</code> should stop
104 * processing the insertion list after this insertion.
105 *
106 * @see LEInsertionList.h
107 *
108 * @stable ICU 3.0
109 */
110 virtual le_bool applyInsertion(le_int32 atPosition, le_int32 count, LEGlyphID newGlyphs[]);
111
112 public:
113
114 /**
115 * Allocates an empty <code>LEGlyphStorage</code> object. You must call
116 * <code>allocateGlyphArray, allocatePositions and allocateAuxData</code>
117 * to allocate the data.
118 *
119 * @stable ICU 3.0
120 */
121 LEGlyphStorage();
122
123 /**
124 * The destructor. This will deallocate all of the arrays.
125 *
126 * @stable ICU 3.0
127 */
128 ~LEGlyphStorage();
129
130 /**
131 * This method returns the number of glyphs in the glyph array.
132 *
133 * @return the number of glyphs in the glyph array
134 *
135 * @stable ICU 3.0
136 */
137 inline le_int32 getGlyphCount() const;
138
139 /**
140 * This method copies the glyph array into a caller supplied array.
141 * The caller must ensure that the array is large enough to hold all
142 * the glyphs.
143 *
144 * @param glyphs - the destiniation glyph array
145 * @param success - set to an error code if the operation fails
146 *
147 * @stable ICU 3.0
148 */
149 void getGlyphs(LEGlyphID glyphs[], LEErrorCode &success) const;
150
151 /**
152 * This method copies the glyph array into a caller supplied array,
153 * ORing in extra bits. (This functionality is needed by the JDK,
154 * which uses 32 bits pre glyph idex, with the high 16 bits encoding
155 * the composite font slot number)
156 *
157 * @param glyphs - the destination (32 bit) glyph array
158 * @param extraBits - this value will be ORed with each glyph index
159 * @param success - set to an error code if the operation fails
160 *
161 * @stable ICU 3.0
162 */
163 void getGlyphs(le_uint32 glyphs[], le_uint32 extraBits, LEErrorCode &success) const;
164
165 /**
166 * This method copies the character index array into a caller supplied array.
167 * The caller must ensure that the array is large enough to hold a
168 * character index for each glyph.
169 *
170 * @param charIndices - the destiniation character index array
171 * @param success - set to an error code if the operation fails
172 *
173 * @stable ICU 3.0
174 */
175 void getCharIndices(le_int32 charIndices[], LEErrorCode &success) const;
176
177 /**
178 * This method copies the character index array into a caller supplied array.
179 * The caller must ensure that the array is large enough to hold a
180 * character index for each glyph.
181 *
182 * @param charIndices - the destiniation character index array
183 * @param indexBase - an offset which will be added to each index
184 * @param success - set to an error code if the operation fails
185 *
186 * @stable ICU 3.0
187 */
188 void getCharIndices(le_int32 charIndices[], le_int32 indexBase, LEErrorCode &success) const;
189
190 /**
191 * This method copies the position array into a caller supplied array.
192 * The caller must ensure that the array is large enough to hold an
193 * X and Y position for each glyph, plus an extra X and Y for the
194 * advance of the last glyph.
195 *
196 * @param positions - the destiniation position array
197 * @param success - set to an error code if the operation fails
198 *
199 * @stable ICU 3.0
200 */
201 void getGlyphPositions(float positions[], LEErrorCode &success) const;
202
203 /**
204 * This method returns the X and Y position of the glyph at
205 * the given index.
206 *
207 * Input parameters:
208 * @param glyphIndex - the index of the glyph
209 *
210 * Output parameters:
211 * @param x - the glyph's X position
212 * @param y - the glyph's Y position
213 * @param success - set to an error code if the operation fails
214 *
215 * @stable ICU 3.0
216 */
217 void getGlyphPosition(le_int32 glyphIndex, float &x, float &y, LEErrorCode &success) const;
218
219 /**
220 * This method allocates the glyph array, the char indices array and the insertion list. You
221 * must call this method before using the object. This method also initializes the char indices
222 * array.
223 *
224 * @param initialGlyphCount the initial size of the glyph and char indices arrays.
225 * @param rightToLeft <code>true</code> if the original input text is right to left.
226 * @param success set to an error code if the storage cannot be allocated of if the initial
227 * glyph count is not positive.
228 *
229 * @stable ICU 3.0
230 */
231 void allocateGlyphArray(le_int32 initialGlyphCount, le_bool rightToLeft, LEErrorCode &success);
232
233 /**
234 * This method allocates the storage for the glyph positions. It allocates one extra X, Y
235 * position pair for the position just after the last glyph.
236 *
237 * @param success set to an error code if the positions array cannot be allocated.
238 *
239 * @return the number of X, Y position pairs allocated.
240 *
241 * @stable ICU 3.0
242 */
243 le_int32 allocatePositions(LEErrorCode &success);
244
245 /**
246 * This method allocates the storage for the auxillary glyph data.
247 *
248 * @param success set to an error code if the aulillary data array cannot be allocated.
249 *
250 * @return the size of the auxillary data array.
251 *
252 * @stable ICU 3.6
253 */
254 le_int32 allocateAuxData(LEErrorCode &success);
255
256 /**
257 * Copy the entire auxillary data array.
258 *
259 * @param auxData the auxillary data array will be copied to this address
260 * @param success set to an error code if the data cannot be copied
261 *
262 * @stable ICU 3.6
263 */
264 void getAuxData(le_uint32 auxData[], LEErrorCode &success) const;
265
266 /**
267 * Get the glyph ID for a particular glyph.
268 *
269 * @param glyphIndex the index into the glyph array
270 * @param success set to an error code if the glyph ID cannot be retrieved.
271 *
272 * @return the glyph ID
273 *
274 * @stable ICU 3.0
275 */
276 LEGlyphID getGlyphID(le_int32 glyphIndex, LEErrorCode &success) const;
277
278 /**
279 * Get the char index for a particular glyph.
280 *
281 * @param glyphIndex the index into the glyph array
282 * @param success set to an error code if the char index cannot be retrieved.
283 *
284 * @return the character index
285 *
286 * @stable ICU 3.0
287 */
288 le_int32 getCharIndex(le_int32 glyphIndex, LEErrorCode &success) const;
289
290
291 /**
292 * Get the auxillary data for a particular glyph.
293 *
294 * @param glyphIndex the index into the glyph array
295 * @param success set to an error code if the auxillary data cannot be retrieved.
296 *
297 * @return the auxillary data
298 *
299 * @stable ICU 3.6
300 */
301 le_uint32 getAuxData(le_int32 glyphIndex, LEErrorCode &success) const;
302
303 /**
304 * This operator allows direct access to the glyph array
305 * using the index operator.
306 *
307 * @param glyphIndex the index into the glyph array
308 *
309 * @return a reference to the given location in the glyph array
310 *
311 * @stable ICU 3.0
312 */
313 inline LEGlyphID &operator[](le_int32 glyphIndex) const;
314
315 /**
316 * Call this method to replace a single glyph in the glyph array
317 * with multiple glyphs. This method uses the <code>LEInsertionList</code>
318 * to do the insertion. It returns the address of storage where the new
319 * glyph IDs can be stored. They will not actually be inserted into the
320 * glyph array until <code>applyInsertions</code> is called.
321 *
322 * @param atIndex the index of the glyph to be replaced
323 * @param insertCount the number of glyphs to replace it with
324 * @param success set to an error code if the auxillary data cannot be retrieved.
325 *
326 * @return the address at which to store the replacement glyphs.
327 *
328 * @see LEInsertionList.h
329 *
330 * @stable ICU 4.2
331 */
332 LEGlyphID *insertGlyphs(le_int32 atIndex, le_int32 insertCount, LEErrorCode& success);
333
334 /**
335 * Call this method to replace a single glyph in the glyph array
336 * with multiple glyphs. This method uses the <code>LEInsertionList</code>
337 * to do the insertion. It returns the address of storage where the new
338 * glyph IDs can be stored. They will not actually be inserted into the
339 * glyph array until <code>applyInsertions</code> is called.
340 *
341 * Note: Don't use this version, use the other version of this function which has an error code.
342 *
343 * @param atIndex the index of the glyph to be replaced
344 * @param insertCount the number of glyphs to replace it with
345 *
346 * @return the address at which to store the replacement glyphs.
347 *
348 * @see LEInsertionList.h
349 *
350 * @stable ICU 3.0
351 */
352 LEGlyphID *insertGlyphs(le_int32 atIndex, le_int32 insertCount);
353
354 /**
355 * This method is used to reposition glyphs during Indic v2 processing. It moves
356 * all of the relevant glyph information ( glyph, indices, positions, and auxData ),
357 * from the source position to the target position, and also allows for a marker bit
358 * to be set in the target glyph's auxData so that it won't be reprocessed later in the
359 * cycle.
360 *
361 * @param fromPosition - position of the glyph to be moved
362 * @param toPosition - target position of the glyph
363 * @param marker marker bit
364 *
365 * @stable ICU 4.2
366 */
367 void moveGlyph(le_int32 fromPosition, le_int32 toPosition, le_uint32 marker);
368
369 /**
370 * This method causes all of the glyph insertions recorded by
371 * <code>insertGlyphs</code> to be applied to the glyph array. The
372 * new slots in the char indices and the auxillary data arrays
373 * will be filled in with the values for the glyph being replaced.
374 *
375 * @return the new size of the glyph array
376 *
377 * @see LEInsertionList.h
378 *
379 * @stable ICU 3.0
380 */
381 le_int32 applyInsertions();
382
383 /**
384 * Set the glyph ID for a particular glyph.
385 *
386 * @param glyphIndex the index of the glyph
387 * @param glyphID the new glyph ID
388 * @param success will be set to an error code if the glyph ID cannot be set.
389 *
390 * @stable ICU 3.0
391 */
392 void setGlyphID(le_int32 glyphIndex, LEGlyphID glyphID, LEErrorCode &success);
393
394 /**
395 * Set the char index for a particular glyph.
396 *
397 * @param glyphIndex the index of the glyph
398 * @param charIndex the new char index
399 * @param success will be set to an error code if the char index cannot be set.
400 *
401 * @stable ICU 3.0
402 */
403 void setCharIndex(le_int32 glyphIndex, le_int32 charIndex, LEErrorCode &success);
404
405 /**
406 * Set the X, Y position for a particular glyph.
407 *
408 * @param glyphIndex the index of the glyph
409 * @param x the new X position
410 * @param y the new Y position
411 * @param success will be set to an error code if the position cannot be set.
412 *
413 * @stable ICU 3.0
414 */
415 void setPosition(le_int32 glyphIndex, float x, float y, LEErrorCode &success);
416
417 /**
418 * Adjust the X, Y position for a particular glyph.
419 *
420 * @param glyphIndex the index of the glyph
421 * @param xAdjust the adjustment to the glyph's X position
422 * @param yAdjust the adjustment to the glyph's Y position
423 * @param success will be set to an error code if the glyph's position cannot be adjusted.
424 *
425 * @stable ICU 3.0
426 */
427 void adjustPosition(le_int32 glyphIndex, float xAdjust, float yAdjust, LEErrorCode &success);
428
429 /**
430 * Set the auxillary data for a particular glyph.
431 *
432 * @param glyphIndex the index of the glyph
433 * @param auxData the new auxillary data
434 * @param success will be set to an error code if the auxillary data cannot be set.
435 *
436 * @stable ICU 3.6
437 */
438 void setAuxData(le_int32 glyphIndex, le_uint32 auxData, LEErrorCode &success);
439
440 /**
441 * Delete the glyph array and replace it with the one
442 * in <code>from</code>. Set the glyph array pointer
443 * in <code>from</code> to <code>NULL</code>.
444 *
445 * @param from the <code>LEGlyphStorage</code> object from which
446 * to get the new glyph array.
447 *
448 * @stable ICU 3.0
449 */
450 void adoptGlyphArray(LEGlyphStorage &from);
451
452 /**
453 * Delete the char indices array and replace it with the one
454 * in <code>from</code>. Set the char indices array pointer
455 * in <code>from</code> to <code>NULL</code>.
456 *
457 * @param from the <code>LEGlyphStorage</code> object from which
458 * to get the new char indices array.
459 *
460 * @stable ICU 3.0
461 */
462 void adoptCharIndicesArray(LEGlyphStorage &from);
463
464 /**
465 * Delete the position array and replace it with the one
466 * in <code>from</code>. Set the position array pointer
467 * in <code>from</code> to <code>NULL</code>.
468 *
469 * @param from the <code>LEGlyphStorage</code> object from which
470 * to get the new position array.
471 *
472 * @stable ICU 3.0
473 */
474 void adoptPositionArray(LEGlyphStorage &from);
475
476 /**
477 * Delete the auxillary data array and replace it with the one
478 * in <code>from</code>. Set the auxillary data array pointer
479 * in <code>from</code> to <code>NULL</code>.
480 *
481 * @param from the <code>LEGlyphStorage</code> object from which
482 * to get the new auxillary data array.
483 *
484 * @stable ICU 3.0
485 */
486 void adoptAuxDataArray(LEGlyphStorage &from);
487
488 /**
489 * Change the glyph count of this object to be the same
490 * as the one in <code>from</code>.
491 *
492 * @param from the <code>LEGlyphStorage</code> object from which
493 * to get the new glyph count.
494 *
495 * @stable ICU 3.0
496 */
497 void adoptGlyphCount(LEGlyphStorage &from);
498
499 /**
500 * Change the glyph count of this object to the given value.
501 *
502 * @param newGlyphCount the new glyph count.
503 *
504 * @stable ICU 3.0
505 */
506 void adoptGlyphCount(le_int32 newGlyphCount);
507
508 /**
509 * This method frees the glyph, character index, position and
510 * auxillary data arrays so that the LayoutEngine can be reused
511 * to layout a different characer array. (This method is also called
512 * by the destructor)
513 *
514 * @stable ICU 3.0
515 */
516 void reset();
517
518 /**
519 * ICU "poor man's RTTI", returns a UClassID for the actual class.
520 *
521 * @stable ICU 3.0
522 */
523 virtual UClassID getDynamicClassID() const;
524
525 /**
526 * ICU "poor man's RTTI", returns a UClassID for this class.
527 *
528 * @stable ICU 3.0
529 */
530 static UClassID getStaticClassID();
531 };
532
getGlyphCount()533 inline le_int32 LEGlyphStorage::getGlyphCount() const
534 {
535 return fGlyphCount;
536 }
537
538 inline LEGlyphID &LEGlyphStorage::operator[](le_int32 glyphIndex) const
539 {
540 return fGlyphs[glyphIndex];
541 }
542
543
544 U_NAMESPACE_END
545 #endif
546
547