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>Fonts, faces, and output: 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="pt01.html" title="Part I. User's manual">
9 <link rel="prev" href="customizing-unicode-functions.html" title="Customizing Unicode functions">
10 <link rel="next" href="fonts-and-faces-custom-functions.html" title="Customizing font functions">
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="pt01.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
19 <td><a accesskey="p" href="customizing-unicode-functions.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
20 <td><a accesskey="n" href="fonts-and-faces-custom-functions.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
23 <div class="titlepage"><div><div><h2 class="title">
24 <a name="fonts-and-faces"></a>Fonts, faces, and output</h2></div></div></div>
25 <div class="toc"><dl class="toc">
26 <dt><span class="section"><a href="fonts-and-faces.html#fonts-and-faces-objects">Font and face objects</a></span></dt>
27 <dt><span class="section"><a href="fonts-and-faces-custom-functions.html">Customizing font functions</a></span></dt>
28 <dt><span class="section"><a href="fonts-and-faces-native-opentype.html">Font objects and HarfBuzz's native OpenType implementation</a></span></dt>
29 <dt><span class="section"><a href="fonts-and-faces-variable.html">Working with OpenType Variable Fonts</a></span></dt>
32 In the previous chapter, we saw how to set up a buffer and fill
33 it with text as Unicode code points. In order to shape this
34 buffer text with HarfBuzz, you will need also need a font
38 HarfBuzz provides abstractions to help you cache and reuse the
39 heavier parts of working with binary fonts, so we will look at
40 how to do that. We will also look at how to work with the
41 FreeType font-rendering library and at how you can customize
42 HarfBuzz to work with other libraries.
45 Finally, we will look at how to work with OpenType variable
46 fonts, the latest update to the OpenType font format, and at
47 some other recent additions to OpenType.
50 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
51 <a name="fonts-and-faces-objects"></a>Font and face objects</h2></div></div></div>
53 The outcome of shaping a run of text depends on the contents of
54 a specific font file (such as the substitutions and positioning
55 moves in the 'GSUB' and 'GPOS' tables), so HarfBuzz makes
56 accessing those internals fast.
59 An <span class="type">hb_face_t</span> represents a <span class="emphasis"><em>face</em></span>
60 in HarfBuzz. This data type is a wrapper around an
61 <span class="type">hb_blob_t</span> blob that holds the contents of a binary
62 font file. Since HarfBuzz supports TrueType Collections and
63 OpenType Collections (each of which can include multiple
64 typefaces), a HarfBuzz face also requires an index number
65 specifying which typeface in the file you want to use. Most of
66 the font files you will encounter in the wild include just a
67 single face, however, so most of the time you would pass in
68 <code class="literal">0</code> as the index when you create a face:
70 <pre class="programlisting">
71 hb_blob_t* blob = hb_blob_create_from_file(file);
73 hb_face_t* face = hb_face_create(blob, 0);
76 On its own, a face object is not quite ready to use for
77 shaping. The typeface must be set to a specific point size in
78 order for some details (such as hinting) to work. In addition,
79 if the font file in question is an OpenType Variable Font, then
80 you may need to specify one or variation-axis settings (or a
81 named instance) in order to get the output you need.
84 In HarfBuzz, you do this by creating a <span class="emphasis"><em>font</em></span>
85 object from your face.
88 Font objects also have the advantage of being considerably
89 lighter-weight than face objects (remember that a face contains
90 the contents of a binary font file mapped into memory). As a
91 result, you can cache and reuse a font object, but you could
92 also create a new one for each additional size you needed.
93 Creating new fonts incurs some additional overhead, of course,
94 but whether or not it is excessive is your call in the end. In
95 contrast, face objects are substantially larger, and you really
96 should cache them and reuse them whenever possible.
99 You can create a font object from a face object:
101 <pre class="programlisting">
102 hb_font_t* hb_font = hb_font_create(hb_face);
105 After creating a font, there are a few properties you should
106 set. Many fonts enable and disable hints based on the size it
107 is used at, so setting this is important for font
108 objects. <code class="function">hb_font_set_ppem(font, x_ppem,
109 y_ppem)</code> sets the pixels-per-EM value of the font. You
110 can also set the point size of the font with
111 <code class="function">hb_font_set_ptem(font, ptem)</code>. HarfBuzz uses the
112 industry standard 72 points per inch.
115 HarfBuzz lets you specify the degree subpixel precision you want
116 through a scaling factor. You can set horizontal and
117 vertical scaling factors on the
118 font by calling <code class="function">hb_font_set_scale(font, x_scale,
122 There may be times when you are handed a font object and need to
123 access the face object that it comes from. For that, you can call
125 <pre class="programlisting">
126 hb_face = hb_font_get_face(hb_font);
129 You can also create a font object from an existing font object
130 using the <code class="function">hb_font_create_sub_font()</code>
131 function. This creates a child font object that is initiated
132 with the same attributes as its parent; it can be used to
133 quickly set up a new font for the purpose of overriding a specific
134 font-functions method.
137 All face objects and font objects are lifecycle-managed by
138 HarfBuzz. After creating a face, you increase its reference
139 count with <code class="function">hb_face_reference(face)</code> and
141 <code class="function">hb_face_destroy(face)</code>. Likewise, you
142 increase the reference count on a font with
143 <code class="function">hb_font_reference(font)</code> and decrease it
144 with <code class="function">hb_font_destroy(font)</code>.
147 You can also attach user data to face objects and font objects.
152 <hr>Generated by GTK-Doc V1.32.1</div>