docs/html/working-with-harfbuzz-clusters.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>Working with HarfBuzz clusters: 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="clusters.html" title="Clusters">
  10 <link rel="next" href="a-clustering-example-for-levels-0-and-1.html" title="A clustering example for levels 0 and 1">
  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="clusters.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
  20 <td><a accesskey="n" href="a-clustering-example-for-levels-0-and-1.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="working-with-harfbuzz-clusters"></a>Working with HarfBuzz clusters</h2></div></div></div>
  25 <p>
  26       When you add text to a HarfBuzz buffer, each code point must be
  27       assigned a <span class="emphasis"><em>cluster value</em></span>.
  28     </p>
  29 <p>
  30       This cluster value is an arbitrary number; HarfBuzz uses it only
  31       to distinguish between clusters. Many client programs will use
  32       the index of each code point in the input text stream as the
  33       cluster value. This is for the sake of convenience; the actual
  34       value does not matter.
  35     </p>
  36 <p>
  37       Some of the shaping operations performed by HarfBuzz —
  38       such as reordering, composition, decomposition, and substitution
  39       — may alter the cluster values of some characters. The
  40       final cluster values in the buffer at the end of the shaping
  41       process will indicate to client programs which subsequences of
  42       glyphs represent a cluster and, therefore, must not be
  43       separated.
  44     </p>
  45 <p>
  46       In addition, client programs can query the final cluster values
  47       to discern other potentially important information about the
  48       glyphs in the output buffer (such as whether or not a ligature
  49       was formed).
  50     </p>
  51 <p>
  52       For example, if the initial sequence of cluster values was:
  53     </p>
  54 <pre class="programlisting">
  55       0,1,2,3,4
  56     </pre>
  57 <p>
  58       and the final sequence of cluster values is:
  59     </p>
  60 <pre class="programlisting">
  61       0,0,3,3
  62     </pre>
  63 <p>
  64       then there are two clusters in the output buffer: the first
  65       cluster includes the first two glyphs, and the second cluster
  66       includes the third and fourth glyphs. It is also evident that a
  67       ligature or conjunct has been formed, because there are fewer
  68       glyphs in the output buffer (four) than there were code points
  69       in the input buffer (five).
  70     </p>
  71 <p>
  72       Although client programs using HarfBuzz are free to assign
  73       initial cluster values in any manner they choose to, HarfBuzz
  74       does offer some useful guarantees if the cluster values are
  75       assigned in a monotonic (either non-decreasing or non-increasing)
  76       order.
  77     </p>
  78 <p>
  79       For buffers in the left-to-right (LTR)
  80       or top-to-bottom (TTB) text flow direction,
  81       HarfBuzz will preserve the monotonic property: client programs
  82       are guaranteed that monotonically increasing initial cluster
  83       values will be returned as monotonically increasing final
  84       cluster values.
  85     </p>
  86 <p>
  87       For buffers in the right-to-left (RTL)
  88       or bottom-to-top (BTT) text flow direction,
  89       the directionality of the buffer itself is reversed for final
  90       output as a matter of design. Therefore, HarfBuzz inverts the
  91       monotonic property: client programs are guaranteed that
  92       monotonically increasing initial cluster values will be
  93       returned as monotonically <span class="emphasis"><em>decreasing</em></span> final
  94       cluster values.
  95     </p>
  96 <p>
  97       Client programs can adjust how HarfBuzz handles clusters during
  98       shaping by setting the
  99       <code class="literal">cluster_level</code> of the
 100       buffer. HarfBuzz offers three <span class="emphasis"><em>levels</em></span> of
 101       clustering support for this property:
 102     </p>
 103 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 104 <li class="listitem">
 105 <p><span class="emphasis"><em>Level 0</em></span> is the default and
 106         reproduces the behavior of the old HarfBuzz library.
 107         </p>
 108 <p>
 109           The distinguishing feature of level 0 behavior is that, at
 110           the beginning of processing the buffer, all code points that
 111           are categorized as <span class="emphasis"><em>marks</em></span>,
 112           <span class="emphasis"><em>modifier symbols</em></span>, or
 113           <span class="emphasis"><em>Emoji extended pictographic</em></span> modifiers,
 114           as well as the <span class="emphasis"><em>Zero Width Joiner</em></span> and
 115           <span class="emphasis"><em>Zero Width Non-Joiner</em></span> code points, are
 116           assigned the cluster value of the closest preceding code
 117           point from <span class="emphasis"><em>different</em></span> category.
 118         </p>
 119 <p>
 120           In essence, whenever a base character is followed by a mark
 121           character or a sequence of mark characters, those marks are
 122           reassigned to the same initial cluster value as the base
 123           character. This reassignment is referred to as
 124           "merging" the affected clusters. This behavior is based on
 125           the Grapheme Cluster Boundary specification in <a class="ulink" href="https://www.unicode.org/reports/tr29/#Regex_Definitions" target="_top">Unicode
 126           Technical Report 29</a>.
 127         </p>
 128 <p>
 129           Client programs can specify level 0 behavior for a buffer by
 130           setting its <code class="literal">cluster_level</code> to
 131           <code class="literal">HB_BUFFER_CLUSTER_LEVEL_MONOTONE_GRAPHEMES</code>.
 132         </p>
 133 </li>
 134 <li class="listitem">
 135 <p>
 136           <span class="emphasis"><em>Level 1</em></span> tweaks the old behavior
 137           slightly to produce better results. Therefore, level 1
 138           clustering is recommended for code that is not required to
 139           implement backward compatibility with the old HarfBuzz.
 140         </p>
 141 <p>
 142           Level 1 differs from level 0 by not merging the
 143           clusters of marks and other modifier code points with the
 144           preceding "base" code point's cluster. By preserving the
 145           separate cluster values of these marks and modifier code
 146           points, script shapers can perform additional operations
 147           that might lead to improved results (for example, reordering
 148           a sequence of marks).
 149         </p>
 150 <p>
 151           Client programs can specify level 1 behavior for a buffer by
 152           setting its <code class="literal">cluster_level</code> to
 153           <code class="literal">HB_BUFFER_CLUSTER_LEVEL_MONOTONE_CHARACTERS</code>.
 154         </p>
 155 </li>
 156 <li class="listitem">
 157 <p>
 158           <span class="emphasis"><em>Level 2</em></span> differs significantly in how it
 159           treats cluster values. In level 2, HarfBuzz never merges
 160           clusters.
 161         </p>
 162 <p>
 163           This difference can be seen most clearly when HarfBuzz processes
 164           ligature substitutions and glyph decompositions. In level 0
 165           and level 1, ligatures and glyph decomposition both involve
 166           merging clusters; in level 2, neither of these operations
 167           triggers a merge.
 168         </p>
 169 <p>
 170           Client programs can specify level 2 behavior for a buffer by
 171           setting its <code class="literal">cluster_level</code> to
 172           <code class="literal">HB_BUFFER_CLUSTER_LEVEL_CHARACTERS</code>.
 173         </p>
 174 </li>
 175 </ul></div>
 176 <p>
 177       As mentioned earlier, client programs using HarfBuzz often
 178       assign initial cluster values in a buffer by reusing the indices
 179       of the code points in the input text. This gives a sequence of
 180       cluster values that is monotonically increasing (for example,
 181       0,1,2,3,4).
 182     </p>
 183 <p>
 184       It is not <span class="emphasis"><em>required</em></span> that the cluster values
 185       in a buffer be monotonically increasing. However, if the initial
 186       cluster values in a buffer are monotonic and the buffer is
 187       configured to use cluster level 0 or 1, then HarfBuzz
 188       guarantees that the final cluster values in the shaped buffer
 189       will also be monotonic. No such guarantee is made for cluster
 190       level 2.
 191     </p>
 192 <p>
 193       In levels 0 and 1, HarfBuzz implements the following conceptual
 194       model for cluster values:
 195     </p>
 196 <div class="itemizedlist"><ul class="itemizedlist compact" style="list-style-type: disc; ">
 197 <li class="listitem"><p>
 198           If the sequence of input cluster values is monotonic, the
 199           sequence of cluster values will remain monotonic.
 200         </p></li>
 201 <li class="listitem"><p>
 202           Each cluster value represents a single cluster.
 203         </p></li>
 204 <li class="listitem"><p>
 205           Each cluster contains one or more glyphs and one or more
 206           characters.
 207         </p></li>
 208 </ul></div>
 209 <p>
 210       In practice, this model offers several benefits. Assuming that
 211       the initial cluster values were monotonically increasing
 212       and distinct before shaping began, then, in the final output:
 213     </p>
 214 <div class="itemizedlist"><ul class="itemizedlist compact" style="list-style-type: disc; ">
 215 <li class="listitem"><p>
 216           All adjacent glyphs having the same final cluster
 217           value belong to the same cluster.
 218         </p></li>
 219 <li class="listitem"><p>
 220           Each character belongs to the cluster that has the highest
 221           cluster value <span class="emphasis"><em>not larger than</em></span> its
 222           initial cluster value.
 223         </p></li>
 224 </ul></div>
 225 </div>
 226 <div class="footer">
 227 <hr>Generated by GTK-Doc V1.32.1</div>
 228 </body>
 229 </html>