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>
