182 lines
6.7 KiB
XML
182 lines
6.7 KiB
XML
<sect1 id="hello-harfbuzz">
|
|
<title>Hello, Harfbuzz</title>
|
|
<para>
|
|
Here's the simplest Harfbuzz that can possibly work. We will improve
|
|
it later.
|
|
</para>
|
|
<orderedlist numeration="arabic">
|
|
<listitem>
|
|
<para>
|
|
Create a buffer and put your text in it.
|
|
</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
<programlisting language="C">
|
|
#include <hb.h>
|
|
hb_buffer_t *buf;
|
|
buf = hb_buffer_create();
|
|
hb_buffer_add_utf8(buf, text, strlen(text), 0, strlen(text));
|
|
</programlisting>
|
|
<orderedlist numeration="arabic">
|
|
<listitem override="2">
|
|
<para>
|
|
Guess the script, language and direction of the buffer.
|
|
</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
<programlisting language="C">
|
|
hb_buffer_guess_segment_properties(buf);
|
|
</programlisting>
|
|
<orderedlist numeration="arabic">
|
|
<listitem override="3">
|
|
<para>
|
|
Create a face and a font, using FreeType for now.
|
|
</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
<programlisting language="C">
|
|
#include <hb-ft.h>
|
|
FT_New_Face(ft_library, font_path, index, &face)
|
|
hb_font_t *font = hb_ft_font_create(face);
|
|
</programlisting>
|
|
<orderedlist numeration="arabic">
|
|
<listitem override="4">
|
|
<para>
|
|
Shape!
|
|
</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
<programlisting>
|
|
hb_shape(font, buf, NULL, 0);
|
|
</programlisting>
|
|
<orderedlist numeration="arabic">
|
|
<listitem override="5">
|
|
<para>
|
|
Get the glyph and position information.
|
|
</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
<programlisting language="C">
|
|
hb_glyph_info_t *glyph_info = hb_buffer_get_glyph_infos(buf, &glyph_count);
|
|
hb_glyph_position_t *glyph_pos = hb_buffer_get_glyph_positions(buf, &glyph_count);
|
|
</programlisting>
|
|
<orderedlist numeration="arabic">
|
|
<listitem override="6">
|
|
<para>
|
|
Iterate over each glyph.
|
|
</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
<programlisting language="C">
|
|
for (i = 0; i < glyph_count; ++i) {
|
|
glyphid = glyph_info[i].codepoint;
|
|
x_offset = glyph_pos[i].x_offset / 64.0;
|
|
y_offset = glyph_pos[i].y_offset / 64.0;
|
|
x_advance = glyph_pos[i].x_advance / 64.0;
|
|
y_advance = glyph_pos[i].y_advance / 64.0;
|
|
draw_glyph(glyphid, cursor_x + x_offset, cursor_y + y_offset);
|
|
cursor_x += x_advance;
|
|
cursor_y += y_advance;
|
|
}
|
|
</programlisting>
|
|
<orderedlist numeration="arabic">
|
|
<listitem override="7">
|
|
<para>
|
|
Tidy up.
|
|
</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
<programlisting language="C">
|
|
hb_buffer_destroy(buf);
|
|
hb_font_destroy(hb_ft_font);
|
|
</programlisting>
|
|
<sect2 id="what-harfbuzz-doesnt-do">
|
|
<title>What Harfbuzz doesn't do</title>
|
|
<para>
|
|
The code above will take a UTF8 string, shape it, and give you the
|
|
information required to lay it out correctly on a single
|
|
horizontal (or vertical) line using the font provided. That is the
|
|
extent of Harfbuzz's responsibility.
|
|
</para>
|
|
<para>
|
|
If you are implementing a text layout engine you may have other
|
|
responsibilities, that Harfbuzz will not help you with:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
Harfbuzz won't help you with bidirectionality. If you want to
|
|
lay out text with mixed Hebrew and English, you will need to
|
|
ensure that the buffer provided to Harfbuzz has those
|
|
characters in the correct layout order. This will be different
|
|
from the logical order in which the Unicode text is stored. In
|
|
other words, the user will hit the keys in the following
|
|
sequence:
|
|
</para>
|
|
<programlisting>
|
|
A B C [space] ג ב א [space] D E F
|
|
</programlisting>
|
|
<para>
|
|
but will expect to see in the output:
|
|
</para>
|
|
<programlisting>
|
|
ABC אבג DEF
|
|
</programlisting>
|
|
<para>
|
|
This reordering is called <emphasis>bidi processing</emphasis>
|
|
("bidi" is short for bidirectional), and there's an
|
|
algorithm as an annex to the Unicode Standard which tells you how
|
|
to reorder a string from logical order into presentation order.
|
|
Before sending your string to Harfbuzz, you may need to apply the
|
|
bidi algorithm to it. Libraries such as ICU and fribidi can do
|
|
this for you.
|
|
</para>
|
|
<listitem>
|
|
<para>
|
|
Harfbuzz won't help you with text that contains different font
|
|
properties. For instance, if you have the string "a
|
|
<emphasis>huge</emphasis> breakfast", and you expect
|
|
"huge" to be italic, you will need to send three
|
|
strings to Harfbuzz: <literal>a</literal>, in your Roman font;
|
|
<literal>huge</literal> using your italic font; and
|
|
<literal>breakfast</literal> using your Roman font again.
|
|
Similarly if you change font, font size, script, language or
|
|
direction within your string, you will need to shape each run
|
|
independently and then output them independently. Harfbuzz
|
|
expects to shape a run of characters sharing the same
|
|
properties.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Harfbuzz won't help you with line breaking, hyphenation or
|
|
justification. As mentioned above, it lays out the string
|
|
along a <emphasis>single line</emphasis> of, notionally,
|
|
infinite length. If you want to find out where the potential
|
|
word, sentence and line break points are in your text, you
|
|
could use the ICU library's break iterator functions.
|
|
</para>
|
|
<para>
|
|
Harfbuzz can tell you how wide a shaped piece of text is, which is
|
|
useful input to a justification algorithm, but it knows nothing
|
|
about paragraphs, lines or line lengths. Nor will it adjust the
|
|
space between words to fit them proportionally into a line. If you
|
|
want to layout text in paragraphs, you will probably want to send
|
|
each word of your text to Harfbuzz to determine its shaped width
|
|
after glyph substitutions, then work out how many words will fit
|
|
on a line, and then finally output each word of the line separated
|
|
by a space of the correct size to fully justify the paragraph.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
As a layout engine implementor, Harfbuzz will help you with the
|
|
interface between your text and your font, and that's something
|
|
that you'll need - what you then do with the glyphs that your font
|
|
returns is up to you. The example we saw above enough to get us
|
|
started using Harfbuzz. Now we are going to use the remainder of
|
|
Harfbuzz's API to refine that example and improve our text shaping
|
|
capabilities.
|
|
</para>
|
|
</sect2>
|
|
</sect1> |