181 lines
8.4 KiB
HTML
181 lines
8.4 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
||
<html>
|
||
<head>
|
||
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
|
||
<title>Hello, Harfbuzz: HarfBuzz Manual</title>
|
||
<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
|
||
<link rel="home" href="index.html" title="HarfBuzz Manual">
|
||
<link rel="up" href="pt01.html" title="Part I. User's manual">
|
||
<link rel="prev" href="building.html" title="Building">
|
||
<link rel="next" href="buffers-language-script-and-direction.html" title="Buffers, language, script and direction">
|
||
<meta name="generator" content="GTK-Doc V1.24.1 (XML mode)">
|
||
<link rel="stylesheet" href="style.css" type="text/css">
|
||
</head>
|
||
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
|
||
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle">
|
||
<td width="100%" align="left" class="shortcuts"></td>
|
||
<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
|
||
<td><a accesskey="u" href="pt01.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
|
||
<td><a accesskey="p" href="building.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
|
||
<td><a accesskey="n" href="buffers-language-script-and-direction.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
|
||
</tr></table>
|
||
<div class="chapter">
|
||
<div class="titlepage"><div><div><h2 class="title">
|
||
<a name="hello-harfbuzz"></a>Hello, Harfbuzz</h2></div></div></div>
|
||
<div class="toc"><dl class="toc"><dt><span class="section"><a href="hello-harfbuzz.html#what-harfbuzz-doesnt-do">What Harfbuzz doesn't do</a></span></dt></dl></div>
|
||
<p>
|
||
Here's the simplest Harfbuzz that can possibly work. We will improve
|
||
it later.
|
||
</p>
|
||
<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
|
||
Create a buffer and put your text in it.
|
||
</p></li></ol></div>
|
||
<pre class="programlisting">
|
||
#include <hb.h>
|
||
hb_buffer_t *buf;
|
||
buf = hb_buffer_create();
|
||
hb_buffer_add_utf8(buf, text, strlen(text), 0, strlen(text));
|
||
</pre>
|
||
<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem" value="2"><p>
|
||
Guess the script, language and direction of the buffer.
|
||
</p></li></ol></div>
|
||
<pre class="programlisting">
|
||
hb_buffer_guess_segment_properties(buf);
|
||
</pre>
|
||
<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem" value="3"><p>
|
||
Create a face and a font, using FreeType for now.
|
||
</p></li></ol></div>
|
||
<pre class="programlisting">
|
||
#include <hb-ft.h>
|
||
FT_New_Face(ft_library, font_path, index, &face)
|
||
hb_font_t *font = hb_ft_font_create(face);
|
||
</pre>
|
||
<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem" value="4"><p>
|
||
Shape!
|
||
</p></li></ol></div>
|
||
<pre class="programlisting">
|
||
hb_shape(font, buf, NULL, 0);
|
||
</pre>
|
||
<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem" value="5"><p>
|
||
Get the glyph and position information.
|
||
</p></li></ol></div>
|
||
<pre class="programlisting">
|
||
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);
|
||
</pre>
|
||
<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem" value="6"><p>
|
||
Iterate over each glyph.
|
||
</p></li></ol></div>
|
||
<pre class="programlisting">
|
||
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;
|
||
}
|
||
</pre>
|
||
<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem" value="7"><p>
|
||
Tidy up.
|
||
</p></li></ol></div>
|
||
<pre class="programlisting">
|
||
hb_buffer_destroy(buf);
|
||
hb_font_destroy(hb_ft_font);
|
||
</pre>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
|
||
<a name="what-harfbuzz-doesnt-do"></a>What Harfbuzz doesn't do</h2></div></div></div>
|
||
<p>
|
||
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.
|
||
</p>
|
||
<p>
|
||
If you are implementing a text layout engine you may have other
|
||
responsibilities, that Harfbuzz will not help you with:
|
||
</p>
|
||
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
|
||
<li class="listitem">
|
||
<p>
|
||
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:
|
||
</p>
|
||
<pre class="programlisting">
|
||
A B C [space] ג ב א [space] D E F
|
||
</pre>
|
||
<p>
|
||
but will expect to see in the output:
|
||
</p>
|
||
<pre class="programlisting">
|
||
ABC אבג DEF
|
||
</pre>
|
||
<p>
|
||
This reordering is called <span class="emphasis"><em>bidi processing</em></span>
|
||
("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.
|
||
</p>
|
||
</li>
|
||
<li class="listitem"><p>
|
||
Harfbuzz won't help you with text that contains different font
|
||
properties. For instance, if you have the string "a
|
||
<span class="emphasis"><em>huge</em></span> breakfast", and you expect
|
||
"huge" to be italic, you will need to send three
|
||
strings to Harfbuzz: <code class="literal">a</code>, in your Roman font;
|
||
<code class="literal">huge</code> using your italic font; and
|
||
<code class="literal">breakfast</code> 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.
|
||
</p></li>
|
||
<li class="listitem">
|
||
<p>
|
||
Harfbuzz won't help you with line breaking, hyphenation or
|
||
justification. As mentioned above, it lays out the string
|
||
along a <span class="emphasis"><em>single line</em></span> 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.
|
||
</p>
|
||
<p>
|
||
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.
|
||
</p>
|
||
</li>
|
||
</ul></div>
|
||
<p>
|
||
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.
|
||
</p>
|
||
</div>
|
||
</div>
|
||
<div class="footer">
|
||
<hr>Generated by GTK-Doc V1.24.1</div>
|
||
</body>
|
||
</html> |