1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
5 <title>Why do I need a shaping engine?: HarfBuzz Manual</title>
6 <meta name="generator" content="DocBook XSL Stylesheets Vsnapshot">
7 <link rel="home" href="index.html" title="HarfBuzz Manual">
8 <link rel="up" href="what-is-harfbuzz.html" title="What is HarfBuzz?">
9 <link rel="prev" href="what-is-harfbuzz.html" title="What is HarfBuzz?">
10 <link rel="next" href="ch01s03.html" title="What does HarfBuzz do?">
11 <meta name="generator" content="GTK-Doc V1.32.1 (XML mode)">
12 <link rel="stylesheet" href="style.css" type="text/css">
14 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
15 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle">
16 <td width="100%" align="left" class="shortcuts"></td>
17 <td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
18 <td><a accesskey="u" href="what-is-harfbuzz.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
19 <td><a accesskey="p" href="what-is-harfbuzz.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
20 <td><a accesskey="n" href="ch01s03.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
23 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
24 <a name="why-do-i-need-a-shaping-engine"></a>Why do I need a shaping engine?</h2></div></div></div>
26 Text shaping is an integral part of preparing text for
27 display. Before a Unicode sequence can be rendered, the
28 codepoints in the sequence must be mapped to the corresponding
29 glyphs provided in the font, and those glyphs must be positioned
30 correctly relative to each other. For many of the scripts
31 supported in Unicode, these steps involve script-specific layout
32 rules, including complex joining, reordering, and positioning
33 behavior. Implementing these rules is the job of the shaping engine.
36 Text shaping is a fairly low-level operation. HarfBuzz is
37 used directly by text-handling libraries like <a class="ulink" href="https://www.pango.org/" target="_top">Pango</a>, as well as by the layout
38 engines in Firefox, LibreOffice, and Chromium. Unless you are
39 <span class="emphasis"><em>writing</em></span> one of these layout engines
40 yourself, you will probably not need to use HarfBuzz: normally,
41 a layout engine, toolkit, or other library will turn text into
45 However, if you <span class="emphasis"><em>are</em></span> writing a layout engine
46 or graphics library yourself, then you will need to perform text
47 shaping, and this is where HarfBuzz can help you.
50 Here are some specific scenarios where a text-shaping engine
51 like HarfBuzz helps you:
53 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
56 OpenType fonts contain a set of glyphs (that is, shapes
57 to represent the letters, numbers, punctuation marks, and
58 all other symbols), which are indexed by a <code class="literal">glyph ID</code>.
61 A particular glyph ID within the font does not necessarily
62 correlate to a predictable Unicode codepoint. For instance,
63 some fonts have the letter "a" as glyph ID 1, but
64 many others do not. In order to retrieve the right glyph
65 from the font to display "a", you need to consult
66 the table inside the font (the <code class="literal">cmap</code>
67 table) that maps Unicode codepoints to glyph IDs. In other
68 words, <span class="emphasis"><em>text shaping turns codepoints into glyph
74 Many OpenType fonts contain ligatures: combinations of
75 characters that are rendered as a single unit. For instance,
76 it is common for the "f, i" letter
77 sequence to appear in print as the single ligature glyph
81 Whether you should render an "f, i" sequence
82 as <code class="literal">fi</code> or as "fi" does not
83 depend on the input text. Instead, it depends on the whether
84 or not the font includes an "fi" glyph and on the
85 level of ligature application you wish to perform. The font
86 and the amount of ligature application used are under your
87 control. In other words, <span class="emphasis"><em>text shaping involves
88 querying the font's ligature tables and determining what
89 substitutions should be made</em></span>.
94 While ligatures like "fi" are optional typographic
95 refinements, some languages <span class="emphasis"><em>require</em></span> certain
96 substitutions to be made in order to display text correctly.
99 For example, in Tamil, when the letter "TTA" (ட)
100 letter is followed by the vowel sign "U" (ு), the pair
101 must be replaced by the single glyph "டு". The
102 sequence of Unicode characters "ட,ு" needs to be
103 substituted with a single "டு" glyph from the
107 But "டு" does not have a Unicode codepoint. To
108 find this glyph, you need to consult the table inside
109 the font (the <code class="literal">GSUB</code> table) that contains
110 substitution information. In other words, <span class="emphasis"><em>text shaping
111 chooses the correct glyph for a sequence of characters
112 provided</em></span>.
115 <li class="listitem">
117 Similarly, each Arabic character has four different variants
118 corresponding to the different positions it might appear in
119 within a sequence. Inside a font, there will be separate
120 glyphs for the initial, medial, final, and isolated forms of
121 each letter, each at a different glyph ID.
124 Unicode only assigns one codepoint per character, so a
125 Unicode string will not tell you which glyph variant to use
126 for each character. To decide, you need to analyze the whole
127 string and determine the appropriate glyph for each character
128 based on its position. In other words, <span class="emphasis"><em>text
129 shaping chooses the correct form of the letter by its
130 position and returns the correct glyph from the font</em></span>.
133 <li class="listitem">
135 Other languages involve marks and accents that need to be
136 rendered in specific positions relative a base character. For
137 instance, the Moldovan language includes the Cyrillic letter
138 "zhe" (ж) with a breve accent, like so: "ӂ".
141 Some fonts will provide this character as a single
142 zhe-with-breve glyph, but other fonts will not and, instead,
143 will expect the rendering engine to form the character by
144 superimposing the separate "ж" and "˘"
148 But exactly where you should draw the breve depends on the
149 height and width of the preceding zhe glyph. To find the
150 right position, you need to consult the table inside
151 the font (the <code class="literal">GPOS</code> table) that contains
152 positioning information.
153 In other words, <span class="emphasis"><em>text shaping tells you whether you
154 have a precomposed glyph within your font or if you need to
155 compose a glyph yourself out of combining marks—and,
156 if so, where to position those marks.</em></span>
161 If tasks like these are something that you need to do, then you
162 need a text shaping engine. You could use Uniscribe if you are
163 writing Windows software; you could use CoreText on macOS; or
164 you could use HarfBuzz.
166 <div class="note"><p>
167 In the rest of this manual, the text will assume that the reader
168 is that implementor of a text-layout engine.
172 <hr>Generated by GTK-Doc V1.32.1</div>