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>Level 2: HarfBuzz Manual</title>
6 <meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
7 <link rel="home" href="index.html" title="HarfBuzz Manual">
8 <link rel="up" href="clusters.html" title="Clusters">
9 <link rel="prev" href="the-distinction-between-levels-0-and-1.html" title="The distinction between levels 0 and 1">
10 <link rel="next" href="utilities.html" title="Utilities">
11 <meta name="generator" content="GTK-Doc V1.32 (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="clusters.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
19 <td><a accesskey="p" href="the-distinction-between-levels-0-and-1.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
20 <td><a accesskey="n" href="utilities.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="level-2"></a>Level 2</h2></div></div></div>
26 HarfBuzz's level 2 cluster behavior uses a significantly
27 different model than that of level 0 and level 1.
30 The level 2 behavior is easy to describe, but it may be
31 difficult to understand in practical terms. In brief, level 2
32 performs no merging of clusters whatsoever.
35 This means that there is no initial base-and-mark merging step
36 (as is done in level 0), and it means that reordering moves and
37 ligature substitutions do not trigger a cluster merge.
40 Only one shaping operation directly affects clusters when using
43 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
44 When a cluster <span class="emphasis"><em>decomposes</em></span>, all of the
45 resulting child clusters inherit as their cluster value the
46 cluster value of the parent cluster.
49 When glyphs do form a ligature (or when some other feature
50 substitutes multiple glyphs with one glyph) the cluster value
51 of the first glyph is retained as the cluster value for the
55 This occurrence sounds similar to a cluster merge, but it is
56 different. In particular, no subsequent characters —
57 including marks and modifiers — are affected. They retain
58 their previous cluster values.
61 Level 2 cluster behavior is ultimately less complex than level 0
62 or level 1, but there are several cases for which processing
63 cluster values produced at level 2 may be tricky.
66 <div class="titlepage"><div><div><h3 class="title">
67 <a name="ligatures-with-combining-marks-in-level-2"></a>Ligatures with combining marks in level 2</h3></div></div></div>
69 The first example of how HarfBuzz's level 2 cluster behavior
70 can be tricky is when the text to be shaped includes combining
71 marks attached to ligatures.
74 Let us start with an input sequence with the following
75 characters (top row) and initial cluster values (bottom row):
77 <pre class="programlisting">
78 A,acute,B,breve,C,circumflex
82 If the sequence <code class="literal">A,B,C</code> forms a ligature,
83 then these are the cluster values HarfBuzz will return under
84 the various cluster levels:
89 <pre class="programlisting">
90 ABC,acute,breve,circumflex
96 <pre class="programlisting">
97 ABC,acute,breve,circumflex
103 <pre class="programlisting">
104 ABC,acute,breve,circumflex
108 Making sense of the level 2 result is the hardest for a client
109 program, because there is nothing in the cluster values that
110 indicates that <code class="literal">B</code> and <code class="literal">C</code>
111 formed a ligature with <code class="literal">A</code>.
114 In contrast, the "merged" cluster values of the mark glyphs
115 that are seen in the level 0 and level 1 output are evidence
116 that a ligature substitution took place.
119 <div class="section">
120 <div class="titlepage"><div><div><h3 class="title">
121 <a name="reordering-in-level-2"></a>Reordering in level 2</h3></div></div></div>
123 Another example of how HarfBuzz's level 2 cluster behavior
124 can be tricky is when glyphs reorder. Consider an input sequence
125 with the following characters (top row) and initial cluster
128 <pre class="programlisting">
133 Now imagine <code class="literal">D</code> moves before
134 <code class="literal">B</code> in a reordering operation. The cluster
137 <pre class="programlisting">
142 Next, if <code class="literal">D</code> forms a ligature with
143 <code class="literal">B</code>, the output is:
145 <pre class="programlisting">
150 However, in a different scenario, in which the shaping rules
151 of the script instead caused <code class="literal">A</code> and
152 <code class="literal">B</code> to form a ligature
153 <span class="emphasis"><em>before</em></span> the <code class="literal">D</code> reordered, the
156 <pre class="programlisting">
161 There is no way for a client program to differentiate between
162 these two scenarios based on the cluster values
163 alone. Consequently, client programs that use level 2 might
164 need to undertake additional work in order to manage cursor
165 positioning, text attributes, or other desired features.
168 <div class="section">
169 <div class="titlepage"><div><div><h3 class="title">
170 <a name="other-considerations-in-level-2"></a>Other considerations in level 2</h3></div></div></div>
172 There may be other problems encountered with ligatures under
173 level 2, such as if the direction of the text is forced to
174 the opposite of its natural direction (for example, Arabic text
175 that is forced into left-to-right directionality). But,
176 generally speaking, these other scenarios are minor corner
177 cases that are too obscure for most client programs to need to
183 <hr>Generated by GTK-Doc V1.32</div>