FM / harfbuzz

/usr/share/gtk-doc/html/harfbuzz

Name	Size	Mode	Actions
a-clustering-example-for-levels-0-and-1.html	5307	0644	edit dl rm
aat-shaping.html	2359	0644	edit dl rm
adding-text-to-the-buffer.html	5800	0644	edit dl rm
annotation-glossary.html	5644	0644	edit dl rm
api-index-0-9-2.html	44447	0644	edit dl rm
api-index-0-9-5.html	3339	0644	edit dl rm
api-index-0-9-7.html	12306	0644	edit dl rm
api-index-0-9-8.html	2088	0644	edit dl rm
api-index-0-9-10.html	3200	0644	edit dl rm
api-index-0-9-11.html	2070	0644	edit dl rm
api-index-0-9-20.html	2303	0644	edit dl rm
api-index-0-9-22.html	2115	0644	edit dl rm
api-index-0-9-28.html	2062	0644	edit dl rm
api-index-0-9-30.html	2525	0644	edit dl rm
api-index-0-9-31.html	2932	0644	edit dl rm
api-index-0-9-38.html	3822	0644	edit dl rm
api-index-0-9-39.html	2058	0644	edit dl rm
api-index-0-9-41.html	2067	0644	edit dl rm
api-index-0-9-42.html	2587	0644	edit dl rm
api-index-1-0-5.html	2737	0644	edit dl rm
api-index-1-1-2.html	2374	0644	edit dl rm
api-index-1-1-3.html	2957	0644	edit dl rm
api-index-1-2-3.html	2872	0644	edit dl rm
api-index-1-3-3.html	5536	0644	edit dl rm
api-index-1-4-0.html	2347	0644	edit dl rm
api-index-1-4-2.html	5369	0644	edit dl rm
api-index-1-4-3.html	2029	0644	edit dl rm
api-index-1-5-0.html	2900	0644	edit dl rm
api-index-1-6-0.html	2266	0644	edit dl rm
api-index-1-7-5.html	1701	0644	edit dl rm
api-index-1-7-7.html	5550	0644	edit dl rm
api-index-1-8-0.html	2662	0644	edit dl rm
api-index-1-8-1.html	2485	0644	edit dl rm
api-index-1-8-5.html	2088	0644	edit dl rm
api-index-1-8-6.html	3187	0644	edit dl rm
api-index-1-9-0.html	3460	0644	edit dl rm
api-index-2-0-0.html	5926	0644	edit dl rm
api-index-2-1-0.html	8069	0644	edit dl rm
api-index-2-2-0.html	5326	0644	edit dl rm
api-index-2-3-0.html	2650	0644	edit dl rm
api-index-2-4-0.html	2087	0644	edit dl rm
api-index-2-5-0.html	2108	0644	edit dl rm
api-index-2-6-0.html	5240	0644	edit dl rm
api-index-2-7-3.html	2824	0644	edit dl rm
api-index-full.html	140340	0644	edit dl rm
buffers-language-script-and-direction.html	4951	0644	edit dl rm
building.html	15346	0644	edit dl rm
ch01s03.html	4495	0644	edit dl rm
ch03s02.html	6078	0644	edit dl rm
ch03s03.html	4580	0644	edit dl rm
ch12.html	3557	0644	edit dl rm
ch13.html	3078	0644	edit dl rm
ch14.html	1876	0644	edit dl rm
ch15.html	3044	0644	edit dl rm
clusters.html	6499	0644	edit dl rm
complex-scripts.html	3001	0644	edit dl rm
customizing-unicode-functions.html	6400	0644	edit dl rm
deprecated-api-index.html	6223	0644	edit dl rm
fonts-and-faces-custom-functions.html	7398	0644	edit dl rm
fonts-and-faces-native-opentype.html	5196	0644	edit dl rm
fonts-and-faces-variable.html	5304	0644	edit dl rm
fonts-and-faces.html	7671	0644	edit dl rm
getting-started.html	5043	0644	edit dl rm
graphite-shaping.html	2308	0644	edit dl rm
harfbuzz-hb-aat-layout.html	139345	0644	edit dl rm
harfbuzz-hb-blob.html	35902	0644	edit dl rm
harfbuzz-hb-buffer.html	195491	0644	edit dl rm
harfbuzz-hb-common.html	65323	0644	edit dl rm
harfbuzz-hb-coretext.html	11371	0644	edit dl rm
harfbuzz-hb-deprecated.html	25328	0644	edit dl rm
harfbuzz-hb-directwrite.html	6155	0644	edit dl rm
harfbuzz-hb-face.html	52100	0644	edit dl rm
harfbuzz-hb-font.html	262696	0644	edit dl rm
harfbuzz-hb-ft.html	28719	0644	edit dl rm
harfbuzz-hb-gdi.html	4310	0644	edit dl rm
harfbuzz-hb-glib.html	10086	0644	edit dl rm
harfbuzz-hb-gobject.html	2953	0644	edit dl rm
harfbuzz-hb-graphite2.html	5828	0644	edit dl rm
harfbuzz-hb-icu.html	7969	0644	edit dl rm
harfbuzz-hb-map.html	29188	0644	edit dl rm
harfbuzz-hb-ot-color.html	39949	0644	edit dl rm
harfbuzz-hb-ot-font.html	4630	0644	edit dl rm
harfbuzz-hb-ot-layout.html	145088	0644	edit dl rm
harfbuzz-hb-ot-math.html	52886	0644	edit dl rm
harfbuzz-hb-ot-meta.html	10286	0644	edit dl rm
harfbuzz-hb-ot-metrics.html	17927	0644	edit dl rm
harfbuzz-hb-ot-name.html	19603	0644	edit dl rm
harfbuzz-hb-ot-shape.html	6257	0644	edit dl rm
harfbuzz-hb-ot-var.html	36708	0644	edit dl rm
harfbuzz-hb-set.html	59423	0644	edit dl rm
harfbuzz-hb-shape-plan.html	38412	0644	edit dl rm
harfbuzz-hb-shape.html	11702	0644	edit dl rm
harfbuzz-hb-unicode.html	106701	0644	edit dl rm
harfbuzz-hb-uniscribe.html	6099	0644	edit dl rm
harfbuzz-hb-version.html	10415	0644	edit dl rm
harfbuzz.devhelp2	179457	0644	edit dl rm
HarfBuzz.png	6254	0644	edit dl rm
HarfBuzz.svg	6745	0644	edit dl rm
home.png	169	0644	edit dl rm
index.html	19566	0644	edit dl rm
install-harfbuzz.html	3787	0644	edit dl rm
integration-coretext.html	6483	0644	edit dl rm
integration-freetype.html	9293	0644	edit dl rm
integration-icu.html	4186	0644	edit dl rm
integration-python.html	3181	0644	edit dl rm
integration-uniscribe.html	6725	0644	edit dl rm
integration.html	9936	0644	edit dl rm
left-insensitive.png	334	0644	edit dl rm
left.png	185	0644	edit dl rm
level-2.html	7009	0644	edit dl rm
object-model-blobs.html	2902	0644	edit dl rm
object-model-lifecycle.html	4978	0644	edit dl rm
object-model-object-types.html	4111	0644	edit dl rm
object-model-user-data.html	3255	0644	edit dl rm
object-model.html	3978	0644	edit dl rm
opentype-shaping-models.html	4463	0644	edit dl rm
pt01.html	9417	0644	edit dl rm
pt02.html	12674	0644	edit dl rm
reordering-in-levels-0-and-1.html	3102	0644	edit dl rm
right-insensitive.png	233	0644	edit dl rm
right.png	184	0644	edit dl rm
setting-buffer-properties.html	7830	0644	edit dl rm
shaping-and-shape-plans.html	8196	0644	edit dl rm
shaping-concepts.html	3869	0644	edit dl rm
shaping-opentype-features.html	6663	0644	edit dl rm
shaping-operations.html	4537	0644	edit dl rm
shaping-plans-and-caching.html	4641	0644	edit dl rm
shaping-shaper-selection.html	3406	0644	edit dl rm
style.css	11606	0644	edit dl rm
text-runs.html	2533	0644	edit dl rm
the-distinction-between-levels-0-and-1.html	4864	0644	edit dl rm
unicode-character-categories.html	4204	0644	edit dl rm
up-insensitive.png	288	0644	edit dl rm
up.png	186	0644	edit dl rm
utilities-common-types-apis.html	4365	0644	edit dl rm
utilities-ucdn.html	2632	0644	edit dl rm
utilities.html	9274	0644	edit dl rm
what-harfbuzz-doesnt-do.html	5535	0644	edit dl rm
what-is-harfbuzz.html	5503	0644	edit dl rm
why-do-i-need-a-shaping-engine.html	8124	0644	edit dl rm
why-is-it-called-harfbuzz.html	2171	0644	edit dl rm
working-with-harfbuzz-clusters.html	10083	0644	edit dl rm

Edit: /usr/share/gtk-doc/html/harfbuzz/working-with-harfbuzz-clusters.html (10083B)

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Working with HarfBuzz clusters: 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="clusters.html" title="Clusters">
<link rel="next" href="a-clustering-example-for-levels-0-and-1.html" title="A clustering example for levels 0 and 1">
<meta name="generator" content="GTK-Doc V1.32 (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="clusters.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
<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>
</tr></table>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="working-with-harfbuzz-clusters"></a>Working with HarfBuzz clusters</h2></div></div></div>

 When you add text to a HarfBuzz buffer, each code point must be
 assigned a cluster value.
 

 This cluster value is an arbitrary number; HarfBuzz uses it only
 to distinguish between clusters. Many client programs will use
 the index of each code point in the input text stream as the
 cluster value. This is for the sake of convenience; the actual
 value does not matter.
 

 Some of the shaping operations performed by HarfBuzz —
 such as reordering, composition, decomposition, and substitution
 — may alter the cluster values of some characters. The
 final cluster values in the buffer at the end of the shaping
 process will indicate to client programs which subsequences of
 glyphs represent a cluster and, therefore, must not be
 separated.
 

 In addition, client programs can query the final cluster values
 to discern other potentially important information about the
 glyphs in the output buffer (such as whether or not a ligature
 was formed).
 

 For example, if the initial sequence of cluster values was:
 
<pre class="programlisting">
 0,1,2,3,4
 </pre>

 and the final sequence of cluster values is:
 
<pre class="programlisting">
 0,0,3,3
 </pre>

 then there are two clusters in the output buffer: the first
 cluster includes the first two glyphs, and the second cluster
 includes the third and fourth glyphs. It is also evident that a
 ligature or conjunct has been formed, because there are fewer
 glyphs in the output buffer (four) than there were code points
 in the input buffer (five).
 

 Although client programs using HarfBuzz are free to assign
 initial cluster values in any manner they choose to, HarfBuzz
 does offer some useful guarantees if the cluster values are
 assigned in a monotonic (either non-decreasing or non-increasing)
 order.
 

 For buffers in the left-to-right (LTR)
 or top-to-bottom (TTB) text flow direction,
 HarfBuzz will preserve the monotonic property: client programs
 are guaranteed that monotonically increasing initial cluster
 values will be returned as monotonically increasing final
 cluster values.
 

 For buffers in the right-to-left (RTL)
 or bottom-to-top (BTT) text flow direction,
 the directionality of the buffer itself is reversed for final
 output as a matter of design. Therefore, HarfBuzz inverts the
 monotonic property: client programs are guaranteed that
 monotonically increasing initial cluster values will be
 returned as monotonically decreasing final
 cluster values.
 

 Client programs can adjust how HarfBuzz handles clusters during
 shaping by setting the
 <code class="literal">cluster_level</code> of the
 buffer. HarfBuzz offers three levels of
 clustering support for this property:
 
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
Level 0 is the default and
	reproduces the behavior of the old HarfBuzz library.
	

	 The distinguishing feature of level 0 behavior is that, at
	 the beginning of processing the buffer, all code points that
	 are categorized as marks,
	 modifier symbols, or
	 Emoji extended pictographic modifiers,
	 as well as the Zero Width Joiner and
	 Zero Width Non-Joiner code points, are
	 assigned the cluster value of the closest preceding code
	 point from different category. 
	

	 In essence, whenever a base character is followed by a mark
	 character or a sequence of mark characters, those marks are
	 reassigned to the same initial cluster value as the base
	 character. This reassignment is referred to as
	 "merging" the affected clusters. This behavior is based on
	 the Grapheme Cluster Boundary specification in <a class="ulink" href="https://www.unicode.org/reports/tr29/#Regex_Definitions" target="_top">Unicode
	 Technical Report 29</a>.
	

	 Client programs can specify level 0 behavior for a buffer by
	 setting its <code class="literal">cluster_level</code> to
	 <code class="literal">HB_BUFFER_CLUSTER_LEVEL_MONOTONE_GRAPHEMES</code>. 
	
</li>
<li class="listitem">

	 Level 1 tweaks the old behavior
	 slightly to produce better results. Therefore, level 1
	 clustering is recommended for code that is not required to
	 implement backward compatibility with the old HarfBuzz.
	

	 Level 1 differs from level 0 by not merging the 
	 clusters of marks and other modifier code points with the
	 preceding "base" code point's cluster. By preserving the
	 separate cluster values of these marks and modifier code
	 points, script shapers can perform additional operations
	 that might lead to improved results (for example, reordering
	 a sequence of marks).
	

	 Client programs can specify level 1 behavior for a buffer by
	 setting its <code class="literal">cluster_level</code> to
	 <code class="literal">HB_BUFFER_CLUSTER_LEVEL_MONOTONE_CHARACTERS</code>. 
	
</li>
<li class="listitem">

	 Level 2 differs significantly in how it
	 treats cluster values. In level 2, HarfBuzz never merges
	 clusters.
	

	 This difference can be seen most clearly when HarfBuzz processes
	 ligature substitutions and glyph decompositions. In level 0 
	 and level 1, ligatures and glyph decomposition both involve
	 merging clusters; in level 2, neither of these operations
	 triggers a merge.
	

	 Client programs can specify level 2 behavior for a buffer by
	 setting its <code class="literal">cluster_level</code> to
	 <code class="literal">HB_BUFFER_CLUSTER_LEVEL_CHARACTERS</code>. 
	
</li>
</ul></div>

 As mentioned earlier, client programs using HarfBuzz often
 assign initial cluster values in a buffer by reusing the indices
 of the code points in the input text. This gives a sequence of
 cluster values that is monotonically increasing (for example,
 0,1,2,3,4). 
 

 It is not required that the cluster values
 in a buffer be monotonically increasing. However, if the initial
 cluster values in a buffer are monotonic and the buffer is
 configured to use cluster level 0 or 1, then HarfBuzz
 guarantees that the final cluster values in the shaped buffer
 will also be monotonic. No such guarantee is made for cluster
 level 2.
 

 In levels 0 and 1, HarfBuzz implements the following conceptual
 model for cluster values:
 
<div class="itemizedlist"><ul class="itemizedlist compact" style="list-style-type: disc; ">
<li class="listitem">
 If the sequence of input cluster values is monotonic, the
	 sequence of cluster values will remain monotonic.
	</li>
<li class="listitem">
 Each cluster value represents a single cluster.
	</li>
<li class="listitem">
 Each cluster contains one or more glyphs and one or more
 characters.
	</li>
</ul></div>

 In practice, this model offers several benefits. Assuming that
 the initial cluster values were monotonically increasing
 and distinct before shaping began, then, in the final output:
 
<div class="itemizedlist"><ul class="itemizedlist compact" style="list-style-type: disc; ">
<li class="listitem">
	 All adjacent glyphs having the same final cluster
	 value belong to the same cluster.
	</li>
<li class="listitem">
 Each character belongs to the cluster that has the highest
	 cluster value not larger than its
	 initial cluster value.
	</li>
</ul></div>
</div>
<div class="footer">
<hr>Generated by GTK-Doc V1.32</div>
</body>
</html>

cmd: