docs/html/level-2.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   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 Vsnapshot">
   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.1 (XML mode)">
  12 <link rel="stylesheet" href="style.css" type="text/css">
  13 </head>
  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>
  21 </tr></table>
  22 <div class="section">
  23 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
  24 <a name="level-2"></a>Level 2</h2></div></div></div>
  25 <p>
  26       HarfBuzz's level 2 cluster behavior uses a significantly
  27       different model than that of level 0 and level 1.
  28     </p>
  29 <p>
  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.
  33     </p>
  34 <p>
  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.
  38     </p>
  39 <p>
  40       Only one shaping operation directly affects clusters when using
  41       level 2:
  42     </p>
  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.
  47         </p></li></ul></div>
  48 <p>
  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
  52       resulting ligature.
  53     </p>
  54 <p>
  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.
  59     </p>
  60 <p>
  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.
  64     </p>
  65 <div class="section">
  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>
  68 <p>
  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.
  72       </p>
  73 <p>
  74         Let us start with an input sequence with the following
  75         characters (top row) and initial cluster values (bottom row):
  76       </p>
  77 <pre class="programlisting">
  78         A,acute,B,breve,C,circumflex
  79         0,1    ,2,3    ,4,5
  80       </pre>
  81 <p>
  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:
  85       </p>
  86 <p>
  87         Level 0:
  88       </p>
  89 <pre class="programlisting">
  90         ABC,acute,breve,circumflex
  91         0  ,0    ,0    ,0
  92       </pre>
  93 <p>
  94         Level 1:
  95       </p>
  96 <pre class="programlisting">
  97         ABC,acute,breve,circumflex
  98         0  ,0    ,0    ,5
  99       </pre>
 100 <p>
 101         Level 2:
 102       </p>
 103 <pre class="programlisting">
 104         ABC,acute,breve,circumflex
 105         0  ,1    ,3    ,5
 106       </pre>
 107 <p>
 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>.
 112       </p>
 113 <p>
 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.
 117       </p>
 118 </div>
 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>
 122 <p>
 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
 126         values (bottom row):
 127       </p>
 128 <pre class="programlisting">
 129         A,B,C,D,E
 130         0,1,2,3,4
 131       </pre>
 132 <p>
 133         Now imagine <code class="literal">D</code> moves before
 134         <code class="literal">B</code> in a reordering operation. The cluster
 135         values will then be:
 136       </p>
 137 <pre class="programlisting">
 138         A,D,B,C,E
 139         0,3,1,2,4
 140       </pre>
 141 <p>
 142         Next, if <code class="literal">D</code> forms a ligature with
 143         <code class="literal">B</code>, the output is:
 144       </p>
 145 <pre class="programlisting">
 146         A,DB,C,E
 147         0,3 ,2,4
 148       </pre>
 149 <p>
 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
 154         result would be:
 155       </p>
 156 <pre class="programlisting">
 157         AB,D,C,E
 158         0 ,3,2,4
 159       </pre>
 160 <p>
 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.
 166       </p>
 167 </div>
 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>
 171 <p>
 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
 178         worry about.
 179       </p>
 180 </div>
 181 </div>
 182 <div class="footer">
 183 <hr>Generated by GTK-Doc V1.32.1</div>
 184 </body>
 185 </html>