115 lines
5.5 KiB
XML
115 lines
5.5 KiB
XML
|
<sect1 id="what-is-harfbuzz">
|
||
|
|
<title>What is Harfbuzz?</title>
|
||
|
|
<para>
|
||
|
|
Harfbuzz is a <emphasis>text shaping engine</emphasis>. It solves
|
||
|
|
the problem of selecting and positioning glyphs from a font given a
|
||
|
|
Unicode string.
|
||
|
|
</para>
|
||
|
|
<sect2 id="why-do-i-need-it">
|
||
|
|
<title>Why do I need it?</title>
|
||
|
|
<para>
|
||
|
|
Text shaping is an integral part of preparing text for display. It
|
||
|
|
is a fairly low level operation; Harfbuzz is used directly by
|
||
|
|
graphic rendering libraries such as Pango, and the layout engines
|
||
|
|
in Firefox, LibreOffice and Chromium. Unless you are
|
||
|
|
<emphasis>writing</emphasis> one of these layout engines yourself,
|
||
|
|
you will probably not need to use Harfbuzz - normally higher level
|
||
|
|
libraries will turn text into glyphs for you.
|
||
|
|
</para>
|
||
|
|
<para>
|
||
|
|
However, if you <emphasis>are</emphasis> writing a layout engine
|
||
|
|
or graphics library yourself, you will need to perform text
|
||
|
|
shaping, and this is where Harfbuzz can help you. Here are some
|
||
|
|
reasons why you need it:
|
||
|
|
</para>
|
||
|
|
<itemizedlist>
|
||
|
|
<listitem>
|
||
|
|
<para>
|
||
|
|
OpenType fonts contain a set of glyphs, indexed by glyph ID.
|
||
|
|
The glyph ID within the font does not necessarily relate to a
|
||
|
|
Unicode codepoint. For instance, some fonts have the letter
|
||
|
|
"a" as glyph ID 1. To pull the right glyph out of
|
||
|
|
the font in order to display it, you need to consult a table
|
||
|
|
within the font (the "cmap" table) which maps
|
||
|
|
Unicode codepoints to glyph IDs. Text shaping turns codepoints
|
||
|
|
into glyph IDs.
|
||
|
|
</para>
|
||
|
|
</listitem>
|
||
|
|
<listitem>
|
||
|
|
<para>
|
||
|
|
Many OpenType fonts contain ligatures: combinations of
|
||
|
|
characters which are rendered together. For instance, it's
|
||
|
|
common for the <literal>fi</literal> combination to appear in
|
||
|
|
print as the single ligature "fi". Whether you should
|
||
|
|
render text as <literal>fi</literal> or "fi" does not
|
||
|
|
depend on the input text, but on the capabilities of the font
|
||
|
|
and the level of ligature application you wish to perform.
|
||
|
|
Text shaping involves querying the font's ligature tables and
|
||
|
|
determining what substitutions should be made.
|
||
|
|
</para>
|
||
|
|
</listitem>
|
||
|
|
<listitem>
|
||
|
|
<para>
|
||
|
|
While ligatures like "fi" are typographic
|
||
|
|
refinements, some languages <emphasis>require</emphasis> such
|
||
|
|
substitutions to be made in order to display text correctly.
|
||
|
|
In Tamil, when the letter "TTA" (ட) letter is
|
||
|
|
followed by "U" (உ), the combination should appear
|
||
|
|
as the single glyph "டு". The sequence of Unicode
|
||
|
|
characters "டஉ" needs to be rendered as a single
|
||
|
|
glyph from the font - text shaping chooses the correct glyph
|
||
|
|
from the sequence of characters provided.
|
||
|
|
</para>
|
||
|
|
</listitem>
|
||
|
|
<listitem>
|
||
|
|
<para>
|
||
|
|
Similarly, each Arabic character has four different variants:
|
||
|
|
within a font, there will be glyphs for the initial, medial,
|
||
|
|
final, and isolated forms of each letter. Unicode only encodes
|
||
|
|
one codepoint per character, and so a Unicode string will not
|
||
|
|
tell you which glyph to use. Text shaping chooses the correct
|
||
|
|
form of the letter and returns the correct glyph from the font
|
||
|
|
that you need to render.
|
||
|
|
</para>
|
||
|
|
</listitem>
|
||
|
|
<listitem>
|
||
|
|
<para>
|
||
|
|
Other languages have marks and accents which need to be
|
||
|
|
rendered in certain positions around a base character. For
|
||
|
|
instance, the Moldovan language has the Cyrillic letter
|
||
|
|
"zhe" (ж) with a breve accent, like so: ӂ. Some
|
||
|
|
fonts will contain this character as an individual glyph,
|
||
|
|
whereas other fonts will not contain a zhe-with-breve glyph
|
||
|
|
but expect the rendering engine to form the character by
|
||
|
|
overlaying the two glyphs ж and ˘. Where you should draw the
|
||
|
|
combining breve depends on the height of the preceding glyph.
|
||
|
|
Again, for Arabic, the correct positioning of vowel marks
|
||
|
|
depends on the height of the character on which you are
|
||
|
|
placing the mark. Text shaping tells you whether you have a
|
||
|
|
precomposed glyph within your font or if you need to compose a
|
||
|
|
glyph yourself out of combining marks, and if so, where to
|
||
|
|
position those marks.
|
||
|
|
</para>
|
||
|
|
</listitem>
|
||
|
|
</itemizedlist>
|
||
|
|
<para>
|
||
|
|
If this is something that you need to do, then you need a text
|
||
|
|
shaping engine: you could use Uniscribe if you are using Windows;
|
||
|
|
you could use CoreText on OS X; or you could use Harfbuzz. In the
|
||
|
|
rest of this manual, we are going to assume that you are the
|
||
|
|
implementor of a text layout engine.
|
||
|
|
</para>
|
||
|
|
</sect2>
|
||
|
|
<sect2 id="why-is-it-called-harfbuzz">
|
||
|
|
<title>Why is it called Harfbuzz?</title>
|
||
|
|
<para>
|
||
|
|
Harfbuzz began its life as text shaping code within the FreeType
|
||
|
|
project, (and you will see references to the FreeType authors
|
||
|
|
within the source code copyright declarations) but was then
|
||
|
|
abstracted out to its own project. This project is maintained by
|
||
|
|
Behdad Esfahbod, and named Harfbuzz. Originally, it was a shaping
|
||
|
|
engine for OpenType fonts - "Harfbuzz" is the Persian
|
||
|
|
for "open type".
|
||
|
|
</para>
|
||
|
|
</sect2>
|
||
|
|
</sect1>
|