docs/html/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>: 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="pt01.html" title="Part I. User's manual">
   9 <link rel="prev" href="using-your-own-font-functions.html" title="Using your own font functions">
  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.27.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="pt01.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
  19 <td><a accesskey="p" href="using-your-own-font-functions.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="chapter">
  23 <div class="titlepage"></div>
  24 <div class="toc"><dl class="toc">
  25 <dt><span class="sect1"><a href="clusters.html#clusters">Clusters</a></span></dt>
  26 <dt><span class="sect1"><a href="a-clustering-example-for-levels-0-and-1.html">A clustering example for levels 0 and 1</a></span></dt>
  27 <dt><span class="sect1"><a href="reordering-in-levels-0-and-1.html">Reordering in levels 0 and 1</a></span></dt>
  28 <dt><span class="sect1"><a href="the-distinction-between-levels-0-and-1.html">The distinction between levels 0 and 1</a></span></dt>
  29 <dt><span class="sect1"><a href="level-2.html">Level 2</a></span></dt>
  30 <dd><dl>
  31 <dt><span class="sect2"><a href="level-2.html#ligatures-with-combining-marks">Ligatures with combining marks</a></span></dt>
  32 <dt><span class="sect2"><a href="level-2.html#reordering">Reordering</a></span></dt>
  33 </dl></dd>
  34 </dl></div>
  35 <div class="sect1">
  36 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
  37 <a name="clusters"></a>Clusters</h2></div></div></div>
  38 <p>
  39     In shaping text, a <span class="emphasis"><em>cluster</em></span> is a sequence of
  40     code points that needs to be treated as a single, indivisible unit.
  41   </p>
  42 <p>
  43     When you add text to a HB buffer, each character is associated with
  44     a <span class="emphasis"><em>cluster value</em></span>. This is an arbitrary number as
  45     far as HB is concerned.
  46   </p>
  47 <p>
  48     Most clients will use UTF-8, UTF-16, or UTF-32 indices, but the
  49     actual number does not matter. Moreover, it is not required for the
  50     cluster values to be monotonically increasing, but pretty much all
  51     of HB's tests are performed on monotonically increasing cluster
  52     numbers. Nevertheless, there is no such assumption in the code
  53     itself. With that in mind, let's examine what happens with cluster
  54     values during shaping under each cluster-level.
  55   </p>
  56 <p>
  57     HarfBuzz provides three <span class="emphasis"><em>levels</em></span> of clustering
  58     support. Level 0 is the default behavior and reproduces the behavior
  59     of the old HarfBuzz library. Level 1 tweaks this behavior slightly
  60     to produce better results, so level 1 clustering is recommended for
  61     code that is not required to implement backward compatibility with
  62     the old HarfBuzz.
  63   </p>
  64 <p>
  65     Level 2 differs significantly in how it treats cluster values.
  66     Levels 0 and 1 both process ligatures and glyph decomposition by
  67     merging clusters; level 2 does not.
  68   </p>
  69 <p>
  70     The conceptual model for what the cluster values mean, in levels 0
  71     and 1, is this:
  72   </p>
  73 <div class="itemizedlist"><ul class="itemizedlist compact" style="list-style-type: disc; ">
  74 <li class="listitem"><p>
  75         the sequence of cluster values will always remain monotone
  76       </p></li>
  77 <li class="listitem"><p>
  78         each value represents a single cluster
  79       </p></li>
  80 <li class="listitem"><p>
  81         each cluster contains one or more glyphs and one or more
  82         characters
  83       </p></li>
  84 </ul></div>
  85 <p>
  86     Assuming that initial cluster numbers were monotonically increasing
  87     and distinct, then all adjacent glyphs having the same cluster
  88     number belong to the same cluster, and all characters belong to the
  89     cluster that has the highest number not larger than their initial
  90     cluster number. This will become clearer with an example.
  91   </p>
  92 </div>
  93 </div>
  94 <div class="footer">
  95 <hr>Generated by GTK-Doc V1.27.1</div>
  96 </body>
  97 </html>