 |
 |
 |
 |
The input to the HarfBuzz shaper 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 how to customize the properties of the buffer. We'll also look at a piece of lower-level machinery that you will need to understand before proceeding: the functions that HarfBuzz uses to retrieve Unicode information.
After shaping is complete, HarfBuzz puts its output back into the buffer. But getting that output requires setting up a face and a font first, so we will look at that in the next chapter instead of here.
As we saw in our Getting Started example, a
buffer is created and
initialized with hb_buffer_create(). This
produces a new, empty buffer object, instantiated with some
default values and ready to accept your Unicode strings.
HarfBuzz manages the memory of objects (such as buffers) that it
creates, so you don't have to. When you have finished working on
a buffer, you can call hb_buffer_destroy():
hb_buffer_t *buf = hb_buffer_create();
...
hb_buffer_destroy(buf);
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:
void somefunc(hb_buffer_t *buf) {
buf = hb_buffer_reference(buf);
...
And then decrease it once you're done with it:
hb_buffer_destroy(buf);
}
While we are on the subject of reference-counting buffers, it is worth noting that an individual buffer can only meaningfully be used by one thread at a time.
To throw away all the data in your buffer and start from scratch,
call hb_buffer_reset(buf). If you want to
throw away the string in the buffer but keep the options, you can
instead call hb_buffer_clear_contents(buf).