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>Plans and caching: 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="shaping-and-shape-plans.html" title="Shaping and shape plans">
9 <link rel="prev" href="shaping-shaper-selection.html" title="Shaper selection">
10 <link rel="next" href="clusters.html" title="Clusters">
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="shaping-and-shape-plans.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
19 <td><a accesskey="p" href="shaping-shaper-selection.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
20 <td><a accesskey="n" href="clusters.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="shaping-plans-and-caching"></a>Plans and caching</h2></div></div></div>
26 Internally, HarfBuzz uses a structure called a shape plan to
27 track its decisions about how to shape the contents of a
28 buffer. The <code class="function">hb_shape()</code> function builds up the shape plan by
29 examining segment properties and by inspecting the contents of
33 This process can involve some decision-making and
34 trade-offs — for example, HarfBuzz inspects the GSUB and GPOS
35 lookups for the script and language tags set on the segment
36 properties, but it falls back on the lookups under the
37 <code class="literal">DFLT</code> tag (and sometimes other common tags)
38 if there are actually no lookups for the tag requested.
41 HarfBuzz also includes some work-arounds for
42 handling well-known older font conventions that do not follow
43 OpenType or Unicode specifications, for buggy system fonts, and for
44 peculiarities of Microsoft Uniscribe. All of that means that a
45 shape plan, while not something that you should edit directly in
46 client code, still might be an object that you want to
47 inspect. Furthermore, if resources are tight, you might want to
48 cache the shape plan that HarfBuzz builds for your buffer and
49 font, so that you do not have to rebuild it for every shaping call.
52 You can create a cacheable shape plan with
53 <code class="function">hb_shape_plan_create_cached(face, props,
54 user_features, num_user_features, shaper_list)</code>, where
55 <em class="parameter"><code>face</code></em> is a face object (not a font object,
56 notably), <em class="parameter"><code>props</code></em> is an
57 <span class="type">hb_segment_properties_t</span>,
58 <em class="parameter"><code>user_features</code></em> is an array of
59 <span class="type">hb_feature_t</span>s (with length
60 <em class="parameter"><code>num_user_features</code></em>), and
61 <em class="parameter"><code>shaper_list</code></em> is a list of shapers to try.
64 Shape plans are objects in HarfBuzz, so there are
65 reference-counting functions and user-data attachment functions
67 use. <code class="function">hb_shape_plan_reference(shape_plan)</code>
68 increases the reference count on a shape plan, while
69 <code class="function">hb_shape_plan_destroy(shape_plan)</code> decreases
70 the reference count, destroying the shape plan when the last
74 You can attach user data to a shaper (with a key) using the
75 <code class="function">hb_shape_plan_set_user_data(shape_plan,key,data,destroy,replace)</code>
76 function, optionally supplying a <code class="function">destroy</code>
77 callback to use. You can then fetch the user data attached to a
79 <code class="function">hb_shape_plan_get_user_data(shape_plan, key)</code>.
83 <hr>Generated by GTK-Doc V1.29</div>