docs/usermanual-buffers-language-script-and-direction.xml

   1 <chapter id="buffers-language-script-and-direction">
   2   <title>Buffers, language, script and direction</title>
   3   <para>
   4     The input to Harfbuzz is a series of Unicode characters, stored in a
   5     buffer. In this chapter, we'll look at how to set up a buffer with
   6     the text that we want and then customize the properties of the
   7     buffer.
   8   </para>
   9   <section id="creating-and-destroying-buffers">
  10     <title>Creating and destroying buffers</title>
  11     <para>
  12       As we saw in our initial example, a buffer is created and
  13       initialized with <literal>hb_buffer_create()</literal>. This
  14       produces a new, empty buffer object, instantiated with some
  15       default values and ready to accept your Unicode strings.
  16     </para>
  17     <para>
  18       Harfbuzz manages the memory of objects that it creates (such as
  19       buffers), so you don't have to. When you have finished working on
  20       a buffer, you can call <literal>hb_buffer_destroy()</literal>:
  21     </para>
  22     <programlisting language="C">
  23   hb_buffer_t *buffer = hb_buffer_create();
  24   ...
  25   hb_buffer_destroy(buffer);
  26 </programlisting>
  27     <para>
  28       This will destroy the object and free its associated memory -
  29       unless some other part of the program holds a reference to this
  30       buffer. If you acquire a Harfbuzz buffer from another subsystem
  31       and want to ensure that it is not garbage collected by someone
  32       else destroying it, you should increase its reference count:
  33     </para>
  34     <programlisting language="C">
  35 void somefunc(hb_buffer_t *buffer) {
  36   buffer = hb_buffer_reference(buffer);
  37   ...
  38 </programlisting>
  39     <para>
  40       And then decrease it once you're done with it:
  41     </para>
  42     <programlisting language="C">
  43   hb_buffer_destroy(buffer);
  44 }
  45 </programlisting>
  46     <para>
  47       To throw away all the data in your buffer and start from scratch,
  48       call <literal>hb_buffer_reset(buffer)</literal>. If you want to
  49       throw away the string in the buffer but keep the options, you can
  50       instead call <literal>hb_buffer_clear_contents(buffer)</literal>.
  51     </para>
  52   </section>
  53   <section id="adding-text-to-the-buffer">
  54     <title>Adding text to the buffer</title>
  55     <para>
  56       Now we have a brand new Harfbuzz buffer. Let's start filling it
  57       with text! From Harfbuzz's perspective, a buffer is just a stream
  58       of Unicode codepoints, but your input string is probably in one of
  59       the standard Unicode character encodings (UTF-8, UTF-16, UTF-32)
  60     </para>
  61   </section>
  62   <section id="setting-buffer-properties">
  63     <title>Setting buffer properties</title>
  64     <para>
  65     </para>
  66   </section>
  67   <section id="what-about-the-other-scripts">
  68     <title>What about the other scripts?</title>
  69     <para>
  70     </para>
  71   </section>
  72   <section id="customizing-unicode-functions">
  73     <title>Customizing Unicode functions</title>
  74     <para>
  75     </para>
  76   </section>
  77 </chapter>