Imported Upstream version 58.1
[platform/upstream/icu.git] / source / layoutex / layout / ParagraphLayout.h
1 // Copyright (C) 2016 and later: Unicode, Inc. and others.
2 // License & terms of use: http://www.unicode.org/copyright.html
3 /*
4  **********************************************************************
5  *   Copyright (C) 2002-2014, International Business Machines
6  *   Corporation and others.  All Rights Reserved.
7  **********************************************************************
8  */
9
10 #ifndef __PARAGRAPHLAYOUT_H
11
12 #define __PARAGRAPHLAYOUT_H
13
14 /**
15  * \file 
16  * \brief C++ API: Paragraph Layout
17  */
18
19 /*
20  * ParagraphLayout doesn't make much sense without
21  * BreakIterator...
22  */
23 #include "unicode/uscript.h"
24 #if ! UCONFIG_NO_BREAK_ITERATION
25
26 #include "layout/LETypes.h"
27 #include "layout/LEFontInstance.h"
28 #include "layout/LayoutEngine.h"
29 #include "unicode/ubidi.h"
30 #include "unicode/brkiter.h"
31
32 #include "layout/RunArrays.h"
33
34 U_NAMESPACE_BEGIN
35
36 /**
37  * ParagraphLayout.
38  *
39  * The <code>ParagraphLayout</code> object will analyze the text into runs of text in the
40  * same font, script and direction, and will create a <code>LayoutEngine</code> object for each run.
41  * The <code>LayoutEngine</code> will transform the characters into glyph codes in visual order.
42  *
43  * Clients can use this to break a paragraph into lines, and to display the glyphs in each line.
44  *
45  * Note that {@link icu::LayoutEngine} is deprecated, but this class is not.
46  * You may use this class with the HarfBuzz icu-le-hb wrapper,
47  *  see http://www.freedesktop.org/wiki/Software/HarfBuzz/
48  *
49  *  See http://userguide.icu-project.org/layoutengine for special build instructions.
50  *
51  * @see icu::LayoutEngine
52  */
53 class U_LAYOUTEX_API ParagraphLayout : public UObject
54 {
55 public:
56     class VisualRun;
57
58     /**
59      * This class represents a single line of text in a <code>ParagraphLayout</code>. They
60      * can only be created by calling <code>ParagraphLayout::nextLine()</code>. Each line
61      * consists of multiple visual runs, represented by <code>ParagraphLayout::VisualRun</code>
62      * objects.
63      *
64      * @see ParagraphLayout
65      * @see ParagraphLayout::VisualRun
66      *
67      * @stable ICU 3.2
68      */
69     class U_LAYOUTEX_API Line : public UObject
70     {
71     public:
72         /**
73          * The constructor is private since these objects can only be
74          * created by <code>ParagraphLayout</code>. However, it is the
75          * clients responsibility to destroy the objects, so the destructor
76          * is public.
77         *
78         * @stable ICU 3.2
79          */
80         ~Line();
81
82         /**
83          * Count the number of visual runs in the line.
84          *
85          * @return the number of visual runs.
86          *
87          * @stable ICU 3.2
88          */
89         inline le_int32 countRuns() const;
90
91         /**
92          * Get the ascent of the line. This is the maximum ascent
93          * of all the fonts on the line.
94          *
95          * @return the ascent of the line.
96          *
97          * @stable ICU 3.2
98          */
99         le_int32 getAscent() const;
100
101         /**
102          * Get the descent of the line. This is the maximum descent
103          * of all the fonts on the line.
104          *
105          * @return the descent of the line.
106          *
107          * @stable ICU 3.2
108          */
109         le_int32 getDescent() const;
110
111         /**
112          * Get the leading of the line. This is the maximum leading
113          * of all the fonts on the line.
114          *
115          * @return the leading of the line.
116          *
117          * @stable ICU 3.2
118          */
119         le_int32 getLeading() const;
120
121         /**
122          * Get the width of the line. This is a convenience method
123          * which returns the last X position of the last visual run
124          * in the line.
125          *
126          * @return the width of the line.
127          *
128          * @stable ICU 2.8
129          */
130         le_int32 getWidth() const;
131     
132         /**
133          * Get a <code>ParagraphLayout::VisualRun</code> object for a given
134          * visual run in the line.
135          *
136          * @param runIndex is the index of the run, in visual order.
137          *
138          * @return the <code>ParagraphLayout::VisualRun</code> object representing the
139          *         visual run. This object is owned by the <code>Line</code> object which
140          *         created it, and will remain valid for as long as the <code>Line</code>
141          *         object is valid.
142          *
143          * @see ParagraphLayout::VisualRun
144          *
145          * @stable ICU 3.2
146          */
147         const VisualRun *getVisualRun(le_int32 runIndex) const;
148
149         /**
150          * ICU "poor man's RTTI", returns a UClassID for this class.
151          *
152          * @stable ICU 3.2
153          */
154         static inline UClassID getStaticClassID() { return (UClassID)&fgClassID; }
155
156         /**
157          * ICU "poor man's RTTI", returns a UClassID for the actual class.
158          *
159          * @stable ICU 3.2
160          */
161         virtual inline UClassID getDynamicClassID() const { return getStaticClassID(); }
162
163     private:
164
165         /**
166          * The address of this static class variable serves as this class's ID
167          * for ICU "poor man's RTTI".
168          */
169         static const char fgClassID;
170
171         friend class ParagraphLayout;
172
173         le_int32 fAscent;
174         le_int32 fDescent;
175         le_int32 fLeading;
176
177         le_int32 fRunCount;
178         le_int32 fRunCapacity;
179
180         VisualRun **fRuns;
181
182         inline Line();
183         inline Line(const Line &other);
184         inline Line &operator=(const Line & /*other*/) { return *this; };
185
186         void computeMetrics();
187
188         void append(const LEFontInstance *font, UBiDiDirection direction, le_int32 glyphCount,
189                     const LEGlyphID glyphs[], const float positions[], const le_int32 glyphToCharMap[]);
190     };
191
192     /**
193      * This object represents a single visual run in a line of text in
194      * a paragraph. A visual run is text which is in the same font, 
195      * script, and direction. The text is represented by an array of
196      * <code>LEGlyphIDs</code>, an array of (x, y) glyph positions and
197      * a table which maps indices into the glyph array to indices into
198      * the original character array which was used to create the paragraph.
199      *
200      * These objects are only created by <code>ParagraphLayout::Line</code> objects,
201      * so their constructors and destructors are private.
202      *
203      * @see ParagraphLayout::Line
204      *
205      * @stable ICU 3.2
206      */
207     class U_LAYOUTEX_API VisualRun : public UObject
208     {
209     public:
210         /**
211          * Get the <code>LEFontInstance</code> object which
212          * represents the font of the visual run. This will always
213          * be a non-composite font.
214          *
215          * @return the <code>LEFontInstance</code> object which represents the
216          *         font of the visual run.
217          *
218          * @see LEFontInstance
219          *
220          * @stable ICU 3.2
221          */
222         inline const LEFontInstance *getFont() const;
223
224         /**
225          * Get the direction of the visual run.
226          *
227          * @return the direction of the run. This will be UBIDI_LTR if the
228          *         run is left-to-right and UBIDI_RTL if the line is right-to-left.
229          *
230          * @stable ICU 3.2
231          */
232         inline UBiDiDirection getDirection() const;
233
234         /**
235          * Get the number of glyphs in the visual run.
236          *
237          * @return the number of glyphs.
238          *
239          * @stable ICU 3.2
240          */
241         inline le_int32 getGlyphCount() const;
242
243         /**
244          * Get the glyphs in the visual run. Glyphs with the values <code>0xFFFE</code> and
245          * <code>0xFFFF</code> should be ignored.
246          *
247          * @return the address of the array of glyphs for this visual run. The storage
248          *         is owned by the <code>VisualRun</code> object and must not be deleted.
249          *         It will remain valid as long as the <code>VisualRun</code> object is valid.
250          *
251          * @stable ICU 3.2
252          */
253         inline const LEGlyphID *getGlyphs() const;
254
255         /**
256          * Get the (x, y) positions of the glyphs in the visual run. To simplify storage
257          * management, the x and y positions are stored in a single array with the x positions
258          * at even offsets in the array and the corresponding y position in the following odd offset.
259          * There is an extra (x, y) pair at the end of the array which represents the advance of
260          * the final glyph in the run.
261          *
262          * @return the address of the array of glyph positions for this visual run. The storage
263          *         is owned by the <code>VisualRun</code> object and must not be deleted.
264          *         It will remain valid as long as the <code>VisualRun</code> object is valid.
265          *
266          * @stable ICU 3.2
267          */
268         inline const float *getPositions() const;
269
270         /**
271          * Get the glyph-to-character map for this visual run. This maps the indices into
272          * the glyph array to indices into the character array used to create the paragraph.
273          *
274          * @return the address of the character-to-glyph map for this visual run. The storage
275          *         is owned by the <code>VisualRun</code> object and must not be deleted.
276          *         It will remain valid as long as the <code>VisualRun</code> object is valid.
277          *
278          * @stable ICU 3.2
279          */
280         inline const le_int32 *getGlyphToCharMap() const;
281
282         /**
283          * A convenience method which returns the ascent value for the font
284          * associated with this run.
285          *
286          * @return the ascent value of this run's font.
287          *
288          * @stable ICU 3.2
289          */
290         inline le_int32 getAscent() const;
291
292         /**
293          * A convenience method which returns the descent value for the font
294          * associated with this run.
295          *
296          * @return the descent value of this run's font.
297          *
298          * @stable ICU 3.2
299          */
300         inline le_int32 getDescent() const;
301
302         /**
303          * A convenience method which returns the leading value for the font
304          * associated with this run.
305          *
306          * @return the leading value of this run's font.
307          *
308          * @stable ICU 3.2
309          */
310         inline le_int32 getLeading() const;
311
312         /**
313          * ICU "poor man's RTTI", returns a UClassID for this class.
314          *
315          * @stable ICU 3.2
316          */
317         static inline UClassID getStaticClassID() { return (UClassID)&fgClassID; }
318
319         /**
320          * ICU "poor man's RTTI", returns a UClassID for the actual class.
321          *
322          * @stable ICU 3.2
323          */
324         virtual inline UClassID getDynamicClassID() const { return getStaticClassID(); }
325
326     private:
327
328         /**
329          * The address of this static class variable serves as this class's ID
330          * for ICU "poor man's RTTI".
331          */
332         static const char fgClassID;
333
334         const LEFontInstance *fFont;
335         const UBiDiDirection  fDirection;
336
337         const le_int32 fGlyphCount;
338
339         const LEGlyphID *fGlyphs;
340         const float     *fPositions;
341         const le_int32  *fGlyphToCharMap;
342
343         friend class Line;
344
345         inline VisualRun();
346         inline VisualRun(const VisualRun &other);
347         inline VisualRun &operator=(const VisualRun &/*other*/) { return *this; };
348
349         inline VisualRun(const LEFontInstance *font, UBiDiDirection direction, le_int32 glyphCount,
350                   const LEGlyphID glyphs[], const float positions[], const le_int32 glyphToCharMap[]);
351
352         ~VisualRun();
353     };
354
355     /**
356      * Construct a <code>ParagraphLayout</code> object for a styled paragraph. The paragraph is specified
357      * as runs of text all in the same font. An <code>LEFontInstance</code> object and a limit offset
358      * are specified for each font run. The limit offset is the offset of the character immediately
359      * after the font run.
360      *
361      * Clients can optionally specify directional runs and / or script runs. If these aren't specified
362      * they will be computed.
363      *
364      * If any errors are encountered during construction, <code>status</code> will be set, and the object
365      * will be set to be empty.
366      *
367      * @param chars is an array of the characters in the paragraph
368      *
369      * @param count is the number of characters in the paragraph.
370      *
371      * @param fontRuns a pointer to a <code>FontRuns</code> object representing the font runs.
372      *
373      * @param levelRuns is a pointer to a <code>ValueRuns</code> object representing the directional levels.
374      *        If this pointer in <code>NULL</code> the levels will be determined by running the Unicde
375      *        Bidi algorithm.
376      *
377      * @param scriptRuns is a pointer to a <code>ValueRuns</code> object representing script runs.
378      *        If this pointer in <code>NULL</code> the script runs will be determined using the
379      *        Unicode code points.
380      *
381      * @param localeRuns is a pointer to a <code>LocaleRuns</code> object representing locale runs.
382      *        The <code>Locale</code> objects are used to determind the language of the text. If this
383      *        pointer is <code>NULL</code> the default locale will be used for all of the text. 
384      *
385      * @param paragraphLevel is the directionality of the paragraph, as in the UBiDi object.
386      *
387      * @param vertical is <code>TRUE</code> if the paragraph should be set vertically.
388      *
389      * @param status will be set to any error code encountered during construction.
390      *
391      * @see ubidi.h
392      * @see LEFontInstance.h
393      * @see LayoutEngine.h
394      * @see RunArrays.h
395      *
396      * @stable ICU 2.8
397      */
398     ParagraphLayout(const LEUnicode chars[], le_int32 count,
399                     const FontRuns *fontRuns,
400                     const ValueRuns *levelRuns,
401                     const ValueRuns *scriptRuns,
402                     const LocaleRuns *localeRuns,
403                     UBiDiLevel paragraphLevel, le_bool vertical,
404                     LEErrorCode &status);
405
406     /**
407      * The destructor. Virtual so that it works correctly with
408      * sublcasses.
409      *
410      * @stable ICU 3.2
411      */
412     ~ParagraphLayout();
413
414     // Note: the following is #if 0'd out because there's no good
415     // way to implement it without either calling layoutEngineFactory()
416     // or duplicating the logic there...
417 #if 0
418     /**
419      * Examine the given styled paragraph and determine if it contains any text which
420      * requires complex processing. (i.e. that cannot be correctly rendered by
421      * just mapping the characters to glyphs and rendering them in order)
422      *
423      * @param chars is an array of the characters in the paragraph
424      *
425      * @param count is the number of characters in the paragraph.
426      *
427      * @param fontRuns is a pointer to a <code>FontRuns</code> object representing the font runs.
428      *
429      * @return <code>TRUE</code> if the paragraph contains complex text.
430      *
431      * @stable ICU 3.2
432      */
433     static le_bool isComplex(const LEUnicode chars[], le_int32 count, const FontRuns *fontRuns);
434 #else
435     /**
436      * Examine the given text and determine if it contains characters in any
437      * script which requires complex processing to be rendered correctly.
438      *
439      * @param chars is an array of the characters in the paragraph
440      *
441      * @param count is the number of characters in the paragraph.
442      *
443      * @return <code>TRUE</code> if any of the text requires complex processing.
444      *
445      * @stable ICU 3.2
446      */
447     static le_bool isComplex(const LEUnicode chars[], le_int32 count);
448
449 #endif
450
451     /**
452      * Return the resolved paragraph level. This is useful for those cases
453      * where the bidi analysis has determined the level based on the first
454      * strong character in the paragraph.
455      *
456      * @return the resolved paragraph level.
457      *
458      * @stable ICU 3.2
459      */
460     inline UBiDiLevel getParagraphLevel();
461
462     /**
463      * Return the directionality of the text in the paragraph.
464      *
465      * @return <code>UBIDI_LTR</code> if the text is all left to right,
466      *         <code>UBIDI_RTL</code> if the text is all right to left,
467      *         or <code>UBIDI_MIXED</code> if the text has mixed direction.
468      *
469      * @stable ICU 3.2
470      */
471     inline UBiDiDirection getTextDirection();
472
473     /**
474      * Return the max ascent value for all the fonts
475      * in the paragraph.
476      *
477      * @return the ascent value.
478      *
479      * @stable ICU 3.2
480      */
481     virtual le_int32 getAscent() const;
482
483     /**
484      * Return the max descent value for all the fonts
485      * in the paragraph.
486      *
487      * @return the decent value.
488      *
489      * @stable ICU 3.2
490      */
491     virtual le_int32 getDescent() const;
492
493     /**
494      * Return the max leading value for all the fonts
495      * in the paragraph.
496      *
497      * @return the leading value.
498      *
499      * @stable ICU 3.2
500      */
501     virtual le_int32 getLeading() const;
502
503     /**
504      * Reset line breaking to start from the beginning of the paragraph.
505      *
506      *
507      * @stable ICU 3.2
508      */
509     inline void reflow();
510
511 #ifndef U_HIDE_INTERNAL_API
512     /**
513      *
514      * Convenience method for determining if paragraph layout processing is complete ( i.e. there
515      * are no more lines left to process. )
516      *
517      * @return true if there are no more lines to be processed
518      *
519      * @internal 
520      */
521     inline le_bool isDone() const;
522 #endif  /* U_HIDE_INTERNAL_API */
523
524     /**
525      * Return a <code>ParagraphLayout::Line</code> object which represents next line
526      * in the paragraph. The width of the line is specified each time so that it can
527      * be varied to support arbitrary paragraph shapes.
528      *
529      * @param width is the width of the line. If <code>width</code> is less than or equal
530      *              to zero, a <code>ParagraphLayout::Line</code> object representing the
531      *              rest of the paragraph will be returned.
532      *
533      * @return a <code>ParagraphLayout::Line</code> object which represents the line. The caller
534      *         is responsible for deleting the object. Returns <code>NULL</code> if there are no
535      *         more lines in the paragraph.
536      *
537      * @see ParagraphLayout::Line
538      *
539      * @stable ICU 3.2
540      */
541     Line *nextLine(float width);
542
543     /**
544      * ICU "poor man's RTTI", returns a UClassID for this class.
545      *
546      * @stable ICU 3.2
547      */
548     static inline UClassID getStaticClassID() { return (UClassID)&fgClassID; }
549
550     /**
551      * ICU "poor man's RTTI", returns a UClassID for the actual class.
552      *
553      * @stable ICU 3.2
554      */
555     virtual inline UClassID getDynamicClassID() const { return getStaticClassID(); }
556
557 private:
558
559
560     /**
561      * The address of this static class variable serves as this class's ID
562      * for ICU "poor man's RTTI".
563      */
564     static const char fgClassID;
565
566     struct StyleRunInfo
567     {
568           LayoutEngine   *engine;
569     const LEFontInstance *font;
570     const Locale         *locale;
571           LEGlyphID      *glyphs;
572           float          *positions;
573           UScriptCode     script;
574           UBiDiLevel      level;
575           le_int32        runBase;
576           le_int32        runLimit;
577           le_int32        glyphBase;
578           le_int32        glyphCount;
579     };
580
581     ParagraphLayout() {};
582     ParagraphLayout(const ParagraphLayout & /*other*/) : UObject( ){};
583     inline ParagraphLayout &operator=(const ParagraphLayout & /*other*/) { return *this; };
584
585     void computeLevels(UBiDiLevel paragraphLevel);
586
587     Line *computeVisualRuns();
588     void appendRun(Line *line, le_int32 run, le_int32 firstChar, le_int32 lastChar);
589
590     void computeScripts();
591
592     void computeLocales();
593
594     void computeSubFonts(const FontRuns *fontRuns, LEErrorCode &status);
595
596     void computeMetrics();
597
598     le_int32 getLanguageCode(const Locale *locale);
599
600     le_int32 getCharRun(le_int32 charIndex);
601
602     static le_bool isComplex(UScriptCode script);
603
604     le_int32 previousBreak(le_int32 charIndex);
605
606
607     const LEUnicode *fChars;
608           le_int32   fCharCount;
609
610     const FontRuns   *fFontRuns;
611     const ValueRuns  *fLevelRuns;
612     const ValueRuns  *fScriptRuns;
613     const LocaleRuns *fLocaleRuns;
614
615           le_bool fVertical;
616           le_bool fClientLevels;
617           le_bool fClientScripts;
618           le_bool fClientLocales;
619
620           UBiDiLevel *fEmbeddingLevels;
621
622           le_int32 fAscent;
623           le_int32 fDescent;
624           le_int32 fLeading;
625
626           le_int32 *fGlyphToCharMap;
627           le_int32 *fCharToMinGlyphMap;
628           le_int32 *fCharToMaxGlyphMap;
629           float    *fGlyphWidths;
630           le_int32  fGlyphCount;
631
632           UBiDi *fParaBidi;
633           UBiDi *fLineBidi;
634
635           le_int32     *fStyleRunLimits;
636           le_int32     *fStyleIndices;
637           StyleRunInfo *fStyleRunInfo;
638           le_int32      fStyleRunCount;
639
640           BreakIterator *fBreakIterator;
641           le_int32       fLineStart;
642           le_int32       fLineEnd;
643
644           le_int32       fFirstVisualRun;
645           le_int32       fLastVisualRun;
646           float          fVisualRunLastX;
647           float          fVisualRunLastY;
648 };
649
650 inline UBiDiLevel ParagraphLayout::getParagraphLevel()
651 {
652     return ubidi_getParaLevel(fParaBidi);
653 }
654
655 inline UBiDiDirection ParagraphLayout::getTextDirection()
656 {
657     return ubidi_getDirection(fParaBidi);
658 }
659
660 inline void ParagraphLayout::reflow()
661 {
662     fLineEnd = 0;
663 }
664
665 inline ParagraphLayout::Line::Line()
666     : UObject(), fAscent(0), fDescent(0), fLeading(0), fRunCount(0), fRunCapacity(0), fRuns(NULL)
667 {
668     // nothing else to do
669 }
670
671 inline ParagraphLayout::Line::Line(const Line & /*other*/)
672     : UObject(), fAscent(0), fDescent(0), fLeading(0), fRunCount(0), fRunCapacity(0), fRuns(NULL)
673 {
674     // nothing else to do
675 }
676
677 inline le_int32 ParagraphLayout::Line::countRuns() const
678 {
679     return fRunCount;
680 }
681
682 inline const LEFontInstance *ParagraphLayout::VisualRun::getFont() const
683 {
684     return fFont;
685 }
686
687 inline UBiDiDirection ParagraphLayout::VisualRun::getDirection() const
688 {
689     return fDirection;
690 }
691
692 inline le_int32 ParagraphLayout::VisualRun::getGlyphCount() const
693 {
694     return fGlyphCount;
695 }
696
697 inline const LEGlyphID *ParagraphLayout::VisualRun::getGlyphs() const
698 {
699     return fGlyphs;
700 }
701
702 inline const float *ParagraphLayout::VisualRun::getPositions() const
703 {
704     return fPositions;
705 }
706
707 inline const le_int32 *ParagraphLayout::VisualRun::getGlyphToCharMap() const
708 {
709     return fGlyphToCharMap;
710 }
711
712 inline le_int32 ParagraphLayout::VisualRun::getAscent() const
713 {
714     return fFont->getAscent();
715 }
716
717 inline le_int32 ParagraphLayout::VisualRun::getDescent() const
718 {
719     return fFont->getDescent();
720 }
721
722 inline le_int32 ParagraphLayout::VisualRun::getLeading() const
723 {
724     return fFont->getLeading();
725 }
726
727 inline ParagraphLayout::VisualRun::VisualRun()
728     : UObject(), fFont(NULL), fDirection(UBIDI_LTR), fGlyphCount(0), fGlyphs(NULL), fPositions(NULL), fGlyphToCharMap(NULL)
729 {
730     // nothing
731 }
732
733 inline ParagraphLayout::VisualRun::VisualRun(const VisualRun &/*other*/)
734     : UObject(), fFont(NULL), fDirection(UBIDI_LTR), fGlyphCount(0), fGlyphs(NULL), fPositions(NULL), fGlyphToCharMap(NULL)
735 {
736     // nothing
737 }
738
739 inline ParagraphLayout::VisualRun::VisualRun(const LEFontInstance *font, UBiDiDirection direction, le_int32 glyphCount,
740                                              const LEGlyphID glyphs[], const float positions[], const le_int32 glyphToCharMap[])
741     : fFont(font), fDirection(direction), fGlyphCount(glyphCount),
742       fGlyphs(glyphs), fPositions(positions), fGlyphToCharMap(glyphToCharMap)
743 {
744     // nothing else needs to be done!
745 }
746
747 U_NAMESPACE_END
748 #endif
749 #endif