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

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