third_party/rust_crates/vendor/harfbuzz-sys/harfbuzz/docs/html/level-2.html - fuchsia/ - Git at Google

 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
 <html>
 <head>
 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
 <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="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.25 (XML mode)">
 <link rel="stylesheet" href="style.css" type="text/css">
 </head>
 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle">
 <td width="100%" align="left" class="shortcuts"></td>
 <td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
 <td><a accesskey="u" href="clusters.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
 <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="section">
 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
 <a name="level-2"></a>Level 2</h2></div></div></div>
 <p>
       HarfBuzz's level 2 cluster behavior uses a significantly
       different model than that of level 0 and level 1.
     </p>
 <p>
       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>
 <p>
       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>
       Only one shaping operation directly affects clusters when using
       level 2:
     </p>
 <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>
       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>
 <p>
       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>
 <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="section">
 <div class="titlepage"><div><div><h3 class="title">
 <a name="reordering-in-level-2"></a>Reordering in level 2</h3></div></div></div>
 <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>
 <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>
 <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>
 	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>
 <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>
 	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.25</div>
 </body>
 </html>
	<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
	<html>
	<head>
	<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
	<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="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.25 (XML mode)">
	<link rel="stylesheet" href="style.css" type="text/css">
	</head>
	<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
	<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle">
	<td width="100%" align="left" class="shortcuts"></td>
	<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
	<td><a accesskey="u" href="clusters.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
	<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="section">
	<div class="titlepage"><div><div><h2 class="title" style="clear: both">
	<a name="level-2"></a>Level 2</h2></div></div></div>
	<p>
	HarfBuzz's level 2 cluster behavior uses a significantly
	different model than that of level 0 and level 1.
	</p>
	<p>
	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>
	<p>
	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>
	Only one shaping operation directly affects clusters when using
	level 2:
	</p>
	<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>
	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>
	<p>
	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>
	<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="section">
	<div class="titlepage"><div><div><h3 class="title">
	<a name="reordering-in-level-2"></a>Reordering in level 2</h3></div></div></div>
	<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>
	<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>
	<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>
	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>
	<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>
	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.25</div>
	</body>
	</html>