docs/html/buffers-language-script-and-direction.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>Buffers, language, script and direction: 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="pt01.html" title="Part I. User's manual">
   9 <link rel="prev" href="object-model-blobs.html" title="Blobs">
  10 <link rel="next" href="adding-text-to-the-buffer.html" title="Adding text to the buffer">
  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="pt01.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
  19 <td><a accesskey="p" href="object-model-blobs.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
  20 <td><a accesskey="n" href="adding-text-to-the-buffer.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><div><h2 class="title">
  24 <a name="buffers-language-script-and-direction"></a>Buffers, language, script and direction</h2></div></div></div>
  25 <div class="toc"><dl class="toc">
  26 <dt><span class="section"><a href="buffers-language-script-and-direction.html#creating-and-destroying-buffers">Creating and destroying buffers</a></span></dt>
  27 <dt><span class="section"><a href="adding-text-to-the-buffer.html">Adding text to the buffer</a></span></dt>
  28 <dt><span class="section"><a href="setting-buffer-properties.html">Setting buffer properties</a></span></dt>
  29 <dt><span class="section"><a href="customizing-unicode-functions.html">Customizing Unicode functions</a></span></dt>
  30 </dl></div>
  31 <p>
  32     The input to the HarfBuzz shaper is a series of Unicode characters, stored in a
  33     buffer. In this chapter, we'll look at how to set up a buffer with
  34     the text that we want and how to customize the properties of the
  35     buffer. We'll also look at a piece of lower-level machinery that
  36     you will need to understand before proceeding: the functions that
  37     HarfBuzz uses to retrieve Unicode information.
  38   </p>
  39 <p>
  40     After shaping is complete, HarfBuzz puts its output back
  41     into the buffer. But getting that output requires setting up a
  42     face and a font first, so we will look at that in the next chapter
  43     instead of here.
  44   </p>
  45 <div class="section">
  46 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
  47 <a name="creating-and-destroying-buffers"></a>Creating and destroying buffers</h2></div></div></div>
  48 <p>
  49       As we saw in our <span class="emphasis"><em>Getting Started</em></span> example, a
  50       buffer is created and
  51       initialized with <code class="function">hb_buffer_create()</code>. This
  52       produces a new, empty buffer object, instantiated with some
  53       default values and ready to accept your Unicode strings.
  54     </p>
  55 <p>
  56       HarfBuzz manages the memory of objects (such as buffers) that it
  57       creates, so you don't have to. When you have finished working on
  58       a buffer, you can call <code class="function">hb_buffer_destroy()</code>:
  59     </p>
  60 <pre class="programlisting">
  61       hb_buffer_t *buf = hb_buffer_create();
  62       ...
  63       hb_buffer_destroy(buf);
  64     </pre>
  65 <p>
  66       This will destroy the object and free its associated memory -
  67       unless some other part of the program holds a reference to this
  68       buffer. If you acquire a HarfBuzz buffer from another subsystem
  69       and want to ensure that it is not garbage collected by someone
  70       else destroying it, you should increase its reference count:
  71     </p>
  72 <pre class="programlisting">
  73       void somefunc(hb_buffer_t *buf) {
  74       buf = hb_buffer_reference(buf);
  75       ...
  76     </pre>
  77 <p>
  78       And then decrease it once you're done with it:
  79     </p>
  80 <pre class="programlisting">
  81       hb_buffer_destroy(buf);
  82       }
  83     </pre>
  84 <p>
  85       While we are on the subject of reference-counting buffers, it is
  86       worth noting that an individual buffer can only meaningfully be
  87       used by one thread at a time.
  88     </p>
  89 <p>
  90       To throw away all the data in your buffer and start from scratch,
  91       call <code class="function">hb_buffer_reset(buf)</code>. If you want to
  92       throw away the string in the buffer but keep the options, you can
  93       instead call <code class="function">hb_buffer_clear_contents(buf)</code>.
  94     </p>
  95 </div>
  96 </div>
  97 <div class="footer">
  98 <hr>Generated by GTK-Doc V1.32.1</div>
  99 </body>
 100 </html>