1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
5 <title>Adding text to the buffer: HarfBuzz Manual</title>
6 <meta name="generator" content="DocBook XSL Stylesheets Vsnapshot">
7 <link rel="home" href="index.html" title="HarfBuzz Manual">
8 <link rel="up" href="buffers-language-script-and-direction.html" title="Buffers, language, script and direction">
9 <link rel="prev" href="buffers-language-script-and-direction.html" title="Buffers, language, script and direction">
10 <link rel="next" href="setting-buffer-properties.html" title="Setting buffer properties">
11 <meta name="generator" content="GTK-Doc V1.32.1 (XML mode)">
12 <link rel="stylesheet" href="style.css" type="text/css">
14 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
15 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle">
16 <td width="100%" align="left" class="shortcuts"></td>
17 <td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
18 <td><a accesskey="u" href="buffers-language-script-and-direction.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
19 <td><a accesskey="p" href="buffers-language-script-and-direction.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
20 <td><a accesskey="n" href="setting-buffer-properties.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
23 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
24 <a name="adding-text-to-the-buffer"></a>Adding text to the buffer</h2></div></div></div>
26 Now we have a brand new HarfBuzz buffer. Let's start filling it
27 with text! From HarfBuzz's perspective, a buffer is just a stream
28 of Unicode code points, but your input string is probably in one of
29 the standard Unicode character encodings (UTF-8, UTF-16, or
30 UTF-32). HarfBuzz provides convenience functions that accept
31 each of these encodings:
32 <code class="function">hb_buffer_add_utf8()</code>,
33 <code class="function">hb_buffer_add_utf16()</code>, and
34 <code class="function">hb_buffer_add_utf32()</code>. Other than the
35 character encoding they accept, they function identically.
38 You can add UTF-8 text to a buffer by passing in the text array,
39 the array's length, an offset into the array for the first
40 character to add, and the length of the segment to add:
42 <pre class="programlisting">
43 hb_buffer_add_utf8 (hb_buffer_t *buf,
46 unsigned int item_offset,
50 So, in practice, you can say:
52 <pre class="programlisting">
53 hb_buffer_add_utf8(buf, text, strlen(text), 0, strlen(text));
56 This will append your new characters to
57 <em class="parameter"><code>buf</code></em>, not replace its existing
58 contents. Also, note that you can use <code class="literal">-1</code> in
59 place of the first instance of <code class="function">strlen(text)</code>
60 if your text array is NULL-terminated. Similarly, you can also use
61 <code class="literal">-1</code> as the final argument want to add its full
65 Whatever start <em class="parameter"><code>item_offset</code></em> and
66 <em class="parameter"><code>item_length</code></em> you provide, HarfBuzz will also
67 attempt to grab the five characters <span class="emphasis"><em>before</em></span>
68 the offset point and the five characters
69 <span class="emphasis"><em>after</em></span> the designated end. These are the
70 before and after "context" segments, which are used internally
71 for HarfBuzz to make shaping decisions. They will not be part of
72 the final output, but they ensure that HarfBuzz's
73 script-specific shaping operations are correct. If there are
74 fewer than five characters available for the before or after
75 contexts, HarfBuzz will just grab what is there.
78 For longer text runs, such as full paragraphs, it might be
79 tempting to only add smaller sub-segments to a buffer and
80 shape them in piecemeal fashion. Generally, this is not a good
81 idea, however, because a lot of shaping decisions are
82 dependent on this context information. For example, in Arabic
83 and other connected scripts, HarfBuzz needs to know the code
84 points before and after each character in order to correctly
85 determine which glyph to return.
88 The safest approach is to add all of the text available, then
89 use <em class="parameter"><code>item_offset</code></em> and
90 <em class="parameter"><code>item_length</code></em> to indicate which characters you
91 want shaped, so that HarfBuzz has access to any context.
94 You can also add Unicode code points directly with
95 <code class="function">hb_buffer_add_codepoints()</code>. The arguments
96 to this function are the same as those for the UTF
97 encodings. But it is particularly important to note that
98 HarfBuzz does not do validity checking on the text that is added
99 to a buffer. Invalid code points will be replaced, but it is up
100 to you to do any deep-sanity checking necessary.
104 <hr>Generated by GTK-Doc V1.32.1</div>