<chapter id="buffers-language-script-and-direction"> <title>Buffers, language, script and direction</title> <para> The input to Harfbuzz is a series of Unicode characters, stored in a buffer. In this chapter, we'll look at how to set up a buffer with the text that we want and then customize the properties of the buffer. </para> <section id="creating-and-destroying-buffers"> <title>Creating and destroying buffers</title> <para> As we saw in our initial example, a buffer is created and initialized with <literal>hb_buffer_create()</literal>. This produces a new, empty buffer object, instantiated with some default values and ready to accept your Unicode strings. </para> <para> Harfbuzz manages the memory of objects that it creates (such as buffers), so you don't have to. When you have finished working on a buffer, you can call <literal>hb_buffer_destroy()</literal>: </para> <programlisting language="C"> hb_buffer_t *buffer = hb_buffer_create(); ... hb_buffer_destroy(buffer); </programlisting> <para> This will destroy the object and free its associated memory - unless some other part of the program holds a reference to this buffer. If you acquire a Harfbuzz buffer from another subsystem and want to ensure that it is not garbage collected by someone else destroying it, you should increase its reference count: </para> <programlisting language="C"> void somefunc(hb_buffer_t *buffer) { buffer = hb_buffer_reference(buffer); ... </programlisting> <para> And then decrease it once you're done with it: </para> <programlisting language="C"> hb_buffer_destroy(buffer); } </programlisting> <para> To throw away all the data in your buffer and start from scratch, call <literal>hb_buffer_reset(buffer)</literal>. If you want to throw away the string in the buffer but keep the options, you can instead call <literal>hb_buffer_clear_contents(buffer)</literal>. </para> </section> <section id="adding-text-to-the-buffer"> <title>Adding text to the buffer</title> <para> Now we have a brand new Harfbuzz buffer. Let's start filling it with text! From Harfbuzz's perspective, a buffer is just a stream of Unicode codepoints, but your input string is probably in one of the standard Unicode character encodings (UTF-8, UTF-16, UTF-32) </para> </section> <section id="setting-buffer-properties"> <title>Setting buffer properties</title> <para> </para> </section> <section id="what-about-the-other-scripts"> <title>What about the other scripts?</title> <para> </para> </section> <section id="customizing-unicode-functions"> <title>Customizing Unicode functions</title> <para> </para> </section> </chapter>