1---
2layout: default
3title: Layout Engine
4nav_order: 1500
5has_children: true
6---
7<!--
8© 2020 and later: Unicode, Inc. and others.
9License & terms of use: http://www.unicode.org/copyright.html
10-->
11
12# Layout Engine
13{: .no_toc }
14
15## Contents
16{: .no_toc .text-delta }
17
181. TOC
19{:toc}
20
21---
22
23## Line Layout Deprecation
24
25> :warning: ***The ICU Line LayoutEngine has been removed in ICU 58.***
26> It had not had active development for some time, had many open bugs,
27> and had been deprecated in ICU 54.
28>
29> Users of ICU Layout are **strongly** encouraged to consider the HarfBuzz project
30> as a replacement for the ICU Layout Engine. An ICU team member responsible for
31> the Layout Engine is contributing fixes and features to HarfBuzz, and a 
32> [drop in wrapper](https://github.com/harfbuzz/icu-le-hb) is available to allow
33> use of HarfBuzz as a direct replacement for the ICU layout engine.
34>
35> HarfBuzz has its own active mailing lists, please use those for discussion of
36> HarfBuzz and its use as a replacement for the ICU layout engine.
37> See: [https://harfbuzz.github.io/](https://harfbuzz.github.io/).
38> 
39
40
41> :point_right: **Users of the "layoutex" ParagraphLayout library**: Please see information
42about how to build "layoutex" on the [Paragraph Layout](paragraph.md) page.
43
44
45## Overview
46
47> :warning: **See the deletion/deprecation notice, above.**
48
49The Latin script, which is the most commonly used script among software
50developers, is also the least complex script to display especially when it is
51used to write English. Using the Latin script, characters can be displayed from
52left to right in the order that they are stored in memory. Some scripts require
53rendering behavior that is more complicated than the Latin script. We refer to
54these scripts as "complex scripts" and to text written in these scripts as
55"complex text." Examples of complex scripts are the Indic scripts (for example,
56Devanagari, Tamil, Telugu, and Gujarati), Thai, and Arabic.
57
58These complex scripts exhibit complications that are not found in the Latin
59script. The following lists the main complications in complex text:
60
61The ICU LayoutEngine is designed to handle these complications through a simple,
62uniform client interface. Clients supply Unicode code points in reading or
63"logical" order, and the LayoutEngine provides a list of what to display,
64indicates the correct order, and supplies the positioning information.
65
66Because the ICU LayoutEngine is platform independent and text rendering is
67inherently platform dependent, the LayoutEngine cannot directly display text.
68Instead, it uses an abstract base class to access font files. This base class
69models a TrueType font at a particular point size and device resolution. The
70TrueType fonts have the following characteristics:
71
721.  A font is a collection of images, called glyphs. Each glyph in the font is
73    referred to by a 16-bit glyph id.
74
752.  There is a mapping from Unicode code points to glyph ids. There may be
76    glyphs in the font for which there is no mapping.
77
783.  The font contains data tables referred to by 4 byte tags. (e.g. `GSUB`,
79    `cmap`). These tables can be read into memory for processing.
80
814.  There is a method to get the width of a glyph.
82
835.  There is a method to get the position of a control point from a glyph.
84
85Since many of the contextual forms, ligatures, and split characters needed to
86display complex text do not have Unicode code points, they can only be referred
87to by their glyph indices. Because of this, the LayoutEngine's output is a list
88of glyph indices. This means that the output must be displayed using an
89interface where the characters are specified by glyph indices rather than code
90points.
91
92A concrete instance of this base class must be written for each target platform.
93For a simple example which uses the standard C library to access a TrueType
94font, look at the PortableFontInstance class in
95[icu/source/test/letest](https://github.com/unicode-org/icu/tree/main/icu4c/source/test/letest)
96.
97
98The ICU LayoutEngine supports complex text in the following ways:
99
1001.  If the font contains OpenType® tables, the LayoutEngine uses those tables.
101
1022.  If the font contains Apple Advanced Typography (AAT) tables, the
103    LayoutEngine uses those tables.
104
1053.  For Arabic and Hebrew text, if OpenType tables are not present, the
106    LayoutEngine uses Unicode presentation forms.
107
1084.  For Thai text, the LayoutEngine uses either the Microsoft or Apple Thai
109    forms.
110
111OpenType processing requires script-specific processing to be done before the
112tables are used. The ICU LayoutEngine performs this processing for Arabic,
113Devanagari, Bengali, Gurmukhi, Gujarati, Oriya, Tamil, Telegu, Kannada, and
114Malayalam text.
115
116The AAT processing in the LayoutEngine is relatively basic as it only applies
117the default features in left-to-right text. This processing has been tested for
118Devanagari text. Since AAT processing is not script-specific, it might not work
119for other scripts.
120
121## Programming with the LayoutEngine
122
123**See deprecation notice, above.**
124
125The ICU LayoutEngine is designed to process a run of text which is in a single
126font. It is written in a single direction (left-to-right or right-to-left), and
127is written in a single script. Clients can use ICU's
128[Bidi](../transforms/bidi.md) processing to determine the direction of the text
129and use the ScriptRun class in
130[icu/source/extra/scrptrun](https://github.com/unicode-org/icu/tree/main/icu4c/source/extra/scrptrun)
131to find a run of text in the same script. Since the representation of font
132information is application specific, ICU cannot help clients find these runs of
133text.
134
135Once the text has been broken into pieces that the LayoutEngine can handle, call
136the LayoutEngineFactory method to create an instance of the LayoutEngine class
137that is specific to the text. The following demonstrates a call to the
138LayoutEngineFactory:
139
140```c
141LEFontInstace *font = <the text's font>;
142UScriptCode script = <the text's script>;
143LEErrorCode error = LE_NO_ERROR;
144LayoutEngine *engine;
145engine = LayoutEngine::layoutEngineFactory(font,
146script,
1470, // language - ignored
148error);
149The following example shows how to use the LayoutEngine to process the text:
150LEUnicode text[] = <the text to process>;
151le_int32 offset = <the starting offset of the text to process>;
152le_int32 count = <the number of code points to process>;
153le_int32 max = <the total number of characters in text>;
154le_bool rtl = <true if the text is right-to-left, false otherwise>;
155float x, y = <starting x, y position of the text>;
156le_int32 glyphCount;
157glyphCount = engine->layoutChars(text, offset, count, max, rtl,
158x, y, error);
159```
160
161This previous example computes three arrays: an array of glyph indices in
162display order, an array of x, y position pairs for each glyph, and an array that
163maps each output glyph back to the input text array. Use the following get
164methods to copy these arrays:
165
166```c
167LEGlyphID *glyphs = new LEGlyphID[glyphCount];
168le_int32 *indices = new le_int32[glyphCount];
169float *positions = new float[(glyphCount * 2) + 2];
170engine->getGlyphs(glyphs, error);
171engine->getCharIndices(indices, error);
172engine->getGlyphPositions(positions, error);
173```
174
175> :point_right: **Note** The positions array contains (glyphCount * 2) + 2 entries. This is because
176> there is an x and a y position for each glyph. The extra two positions hold the
177> x, y position of the end of the text run.
178
179Once users have the glyph indices and positions, they can use the
180platform-specific code to draw the glyphs. For example, on Windows 2000, users
181can call `ExtTextOut` with the `ETO_GLYPH_INDEX` option to draw the glyphs and on
182Linux, users can call `TT_Load_Glyph` to get the bitmap for each glyph. However,
183users must draw the bitmaps themselves.
184
185> :point_right: **Note:** The ICU LayoutEngine was developed separately from the rest of ICU and uses
186> different coding conventions and basic types. To use the LayoutEngine with ICU
187> coding conventions, users can use the ICULayoutEngine class, which is a thin
188> wrapper around the LayoutEngine class that incorporates ICU conventions and
189> basic types.
190
191For a more detailed example of how to call the LayoutEngine, look at
192[icu/source/test/letest/letest.cpp](https://github.com/unicode-org/icu/tree/main/icu4c/source/test/letest/letest.cpp)
193. This is a simple test used to verify that the LayoutEngine is working
194properly. It does not do any complex text rendering.
195
196For more information, see [ICU](https://icu.unicode.org/) , the [OpenType
197Specification](http://www.microsoft.com/typography/tt/tt.htm) , and the
198[TrueType Font File
199Specification](http://developer.apple.com/fonts/TTRefMan/RM06/Chap6.html) .
200
201> :warning: **Note:** See deprecation notice, above.
202