1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
5 <title>The distinction between levels 0 and 1: 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="reordering-in-levels-0-and-1.html" title="Reordering in levels 0 and 1">
10 <link rel="next" href="level-2.html" title="Level 2">
11 <meta name="generator" content="GTK-Doc V1.29 (XML mode)">
12 <link rel="stylesheet" href="style.css" type="text/css">
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="reordering-in-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="level-2.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
23 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
24 <a name="the-distinction-between-levels-0-and-1"></a>The distinction between levels 0 and 1</h2></div></div></div>
26 The preceding examples demonstrate the main effects of using
27 cluster levels 0 and 1. The only difference between the two
28 levels is this: in level 0, at the very beginning of the shaping
29 process, HarfBuzz merges the cluster of each base character
30 with the clusters of all Unicode marks (combining or not) and
31 modifiers that follow it.
34 For example, let us start with the following character sequence
35 (top row) and accompanying initial cluster values (bottom row):
37 <pre class="programlisting">
42 The <code class="literal">acute</code> is a Unicode mark. If HarfBuzz is
43 using cluster level 0 on this sequence, then the
44 <code class="literal">A</code> and <code class="literal">acute</code> clusters will
45 merge, and the result will become:
47 <pre class="programlisting">
52 This merger is performed before any other script-shaping
56 This initial cluster merging is the default behavior of the
57 Windows shaping engine, and the old HarfBuzz codebase copied
58 that behavior to maintain compatibility. Consequently, it has
59 remained the default behavior in the new HarfBuzz codebase.
62 But this initial cluster-merging behavior makes it impossible
63 for client programs to implement some features (such as to
64 color diacritic marks differently from their base
65 characters). That is why, in level 1, HarfBuzz does not perform
66 the initial merging step.
69 For client programs that rely on HarfBuzz cluster values to
70 perform cursor positioning, level 0 is more convenient. But
71 relying on cluster boundaries for cursor positioning is wrong: cursor
72 positions should be determined based on Unicode grapheme
73 boundaries, not on shaping-cluster boundaries. As such, using
74 level 1 clustering behavior is recommended.
77 One final facet of levels 0 and 1 is worth noting. HarfBuzz
78 currently does not allow any
79 <span class="emphasis"><em>multiple-substitution</em></span> GSUB lookups to
80 replace a glyph with zero glyphs (in other words, to delete a
84 But, in some other situations, glyphs can be deleted. In
85 those cases, if the glyph being deleted is the last glyph of its
86 cluster, HarfBuzz makes sure to merge the deleted glyph's
87 cluster with a neighboring cluster.
90 This is done primarily to make sure that the starting cluster of the
91 text always has the cluster index pointing to the start of the text
92 for the run; more than one client program currently relies on this
96 Incidentally, Apple's CoreText does something different to
97 maintain the same promise: it inserts a glyph with id 65535 at
98 the beginning of the glyph string if the glyph corresponding to
99 the first character in the run was deleted. HarfBuzz might do
100 something similar in the future.
104 <hr>Generated by GTK-Doc V1.29</div>