<title>Level 2: HarfBuzz Manual</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="index.html" title="HarfBuzz Manual">
-<link rel="up" href="clusters.html" title="">
+<link rel="up" href="clusters.html" title="Clusters">
<link rel="prev" href="the-distinction-between-levels-0-and-1.html" title="The distinction between levels 0 and 1">
<link rel="next" href="shaping-and-shape-plans.html" title="Shaping and shape plans">
-<meta name="generator" content="GTK-Doc V1.27.1 (XML mode)">
+<meta name="generator" content="GTK-Doc V1.25 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<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>
<td><a accesskey="n" href="shaping-and-shape-plans.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
</tr></table>
-<div class="sect1">
+<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="level-2"></a>Level 2</h2></div></div></div>
<p>
- Level 2 is a different beast from levels 0 and 1. It is simple to
- describe, but hard to make sense of. It simply doesn't do any
- cluster merging whatsoever. When things ligate or otherwise multiple
- glyphs turn into one, the cluster value of the first glyph is
- retained.
- </p>
-<p>
- Here are a few examples of why processing cluster values produced at
- this level might be tricky:
- </p>
-<div class="sect2">
-<div class="titlepage"><div><div><h3 class="title">
-<a name="ligatures-with-combining-marks"></a>Ligatures with combining marks</h3></div></div></div>
+ HarfBuzz's level 2 cluster behavior uses a significantly
+ different model than that of level 0 and level 1.
+ </p>
<p>
- Imagine capital letters are bases and lower case letters are
- combining marks. With an input sequence like this:
+ The level 2 behavior is easy to describe, but it may be
+ difficult to understand in practical terms. In brief, level 2
+ performs no merging of clusters whatsoever.
</p>
-<pre class="programlisting">
- A,a,B,b,C,c
- 0,1,2,3,4,5
-</pre>
<p>
- if <code class="literal">A,B,C</code> ligate, then here are the cluster
- values one would get under the various levels:
+ This means that there is no initial base-and-mark merging step
+ (as is done in level 0), and it means that reordering moves and
+ ligature substitutions do not trigger a cluster merge.
</p>
<p>
- level 0:
+ Only one shaping operation directly affects clusters when using
+ level 2:
</p>
-<pre class="programlisting">
- ABC,a,b,c
- 0 ,0,0,0
-</pre>
+<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ When a cluster <span class="emphasis"><em>decomposes</em></span>, all of the
+ resulting child clusters inherit as their cluster value the
+ cluster value of the parent cluster.
+ </p></li></ul></div>
<p>
- level 1:
+ When glyphs do form a ligature (or when some other feature
+ substitutes multiple glyphs with one glyph) the cluster value
+ of the first glyph is retained as the cluster value for the
+ resulting ligature.
</p>
-<pre class="programlisting">
- ABC,a,b,c
- 0 ,0,0,5
-</pre>
<p>
- level 2:
+ This occurrence sounds similar to a cluster merge, but it is
+ different. In particular, no subsequent characters —
+ including marks and modifiers — are affected. They retain
+ their previous cluster values.
</p>
-<pre class="programlisting">
- ABC,a,b,c
- 0 ,1,3,5
-</pre>
-<p>
- Making sense of the last example is the hardest for a client,
- because there is nothing in the cluster values to suggest that
- <code class="literal">B</code> and <code class="literal">C</code> ligated with
- <code class="literal">A</code>.
+<p>
+ Level 2 cluster behavior is ultimately less complex than level 0
+ or level 1, but there are several cases for which processing
+ cluster values produced at level 2 may be tricky.
</p>
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="ligatures-with-combining-marks-in-level-2"></a>Ligatures with combining marks in level 2</h3></div></div></div>
+<p>
+ The first example of how HarfBuzz's level 2 cluster behavior
+ can be tricky is when the text to be shaped includes combining
+ marks attached to ligatures.
+ </p>
+<p>
+ Let us start with an input sequence with the following
+ characters (top row) and initial cluster values (bottom row):
+ </p>
+<pre class="programlisting">
+ A,acute,B,breve,C,circumflex
+ 0,1 ,2,3 ,4,5
+ </pre>
+<p>
+ If the sequence <code class="literal">A,B,C</code> forms a ligature,
+ then these are the cluster values HarfBuzz will return under
+ the various cluster levels:
+ </p>
+<p>
+ Level 0:
+ </p>
+<pre class="programlisting">
+ ABC,acute,breve,circumflex
+ 0 ,0 ,0 ,0
+ </pre>
+<p>
+ Level 1:
+ </p>
+<pre class="programlisting">
+ ABC,acute,breve,circumflex
+ 0 ,0 ,0 ,5
+ </pre>
+<p>
+ Level 2:
+ </p>
+<pre class="programlisting">
+ ABC,acute,breve,circumflex
+ 0 ,1 ,3 ,5
+ </pre>
+<p>
+ Making sense of the level 2 result is the hardest for a client
+ program, because there is nothing in the cluster values that
+ indicates that <code class="literal">B</code> and <code class="literal">C</code>
+ formed a ligature with <code class="literal">A</code>.
+ </p>
+<p>
+ In contrast, the "merged" cluster values of the mark glyphs
+ that are seen in the level 0 and level 1 output are evidence
+ that a ligature substitution took place.
+ </p>
</div>
-<div class="sect2">
+<div class="section">
<div class="titlepage"><div><div><h3 class="title">
-<a name="reordering"></a>Reordering</h3></div></div></div>
+<a name="reordering-in-level-2"></a>Reordering in level 2</h3></div></div></div>
<p>
- Another tricky case is when things reorder. Under level 2:
- </p>
+ Another example of how HarfBuzz's level 2 cluster behavior
+ can be tricky is when glyphs reorder. Consider an input sequence
+ with the following characters (top row) and initial cluster
+ values (bottom row):
+ </p>
<pre class="programlisting">
- A,B,C,D,E
- 0,1,2,3,4
-</pre>
+ A,B,C,D,E
+ 0,1,2,3,4
+ </pre>
<p>
- Now imagine <code class="literal">D</code> moves before
- <code class="literal">B</code>:
- </p>
+ Now imagine <code class="literal">D</code> moves before
+ <code class="literal">B</code> in a reordering operation. The cluster
+ values will then be:
+ </p>
<pre class="programlisting">
- A,D,B,C,E
- 0,3,1,2,4
-</pre>
+ A,D,B,C,E
+ 0,3,1,2,4
+ </pre>
<p>
- Now, if <code class="literal">D</code> ligates with <code class="literal">B</code>, we
- get:
- </p>
+ Next, if <code class="literal">D</code> forms a ligature with
+ <code class="literal">B</code>, the output is:
+ </p>
<pre class="programlisting">
- A,DB,C,E
- 0,3 ,2,4
-</pre>
-<p>
- In a different scenario, <code class="literal">A</code> and
- <code class="literal">B</code> could have ligated
- <span class="emphasis"><em>before</em></span> <code class="literal">D</code> reordered; that
- would have resulted in:
- </p>
+ A,DB,C,E
+ 0,3 ,2,4
+ </pre>
+<p>
+ However, in a different scenario, in which the shaping rules
+ of the script instead caused <code class="literal">A</code> and
+ <code class="literal">B</code> to form a ligature
+ <span class="emphasis"><em>before</em></span> the <code class="literal">D</code> reordered, the
+ result would be:
+ </p>
<pre class="programlisting">
- AB,D,C,E
- 0 ,3,2,4
-</pre>
+ AB,D,C,E
+ 0 ,3,2,4
+ </pre>
<p>
- There's no way to differentiate between these two scenarios based
- on the cluster numbers alone.
- </p>
+ There is no way for a client program to differentiate between
+ these two scenarios based on the cluster values
+ alone. Consequently, client programs that use level 2 might
+ need to undertake additional work in order to manage cursor
+ positioning, text attributes, or other desired features.
+ </p>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="other-considerations-in-level-2"></a>Other considerations in level 2</h3></div></div></div>
<p>
- Another problem happens with ligatures under level 2 if the
- direction of the text is forced to opposite of its natural
- direction (e.g. left-to-right Arabic). But that's too much of a
- corner case to worry about.
- </p>
+ There may be other problems encountered with ligatures under
+ level 2, such as if the direction of the text is forced to
+ opposite of its natural direction (for example, Arabic text
+ that is forced into left-to-right directionality). But,
+ generally speaking, these other scenarios are minor corner
+ cases that are too obscure for most client programs to need to
+ worry about.
+ </p>
</div>
</div>
<div class="footer">
-<hr>Generated by GTK-Doc V1.27.1</div>
+<hr>Generated by GTK-Doc V1.25</div>
</body>
</html>
\ No newline at end of file
projects / platform / upstream / harfbuzz.git / blobdiff