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