docs/html/shaping-plans-and-caching.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>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.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="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>
  21 </tr></table>
  22 <div class="section">
  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>
  25 <p>
  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
  30       the font.
  31     </p>
  32 <p>
  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.
  39     </p>
  40 <p>
  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.
  50     </p>
  51 <p>
  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.
  62     </p>
  63 <p>
  64       Shape plans are objects in HarfBuzz, so there are
  65       reference-counting functions and user-data attachment functions
  66       you can
  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
  71       reference is dropped.
  72     </p>
  73 <p>
  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
  78       shape plan with
  79       <code class="function">hb_shape_plan_get_user_data(shape_plan, key)</code>.
  80     </p>
  81 </div>
  82 <div class="footer">
  83 <hr>Generated by GTK-Doc V1.32.1</div>
  84 </body>
  85 </html>