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>Shaping and shape plans: 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="fonts-and-faces-variable.html" title="Working with OpenType Variable Fonts">
10 <link rel="next" href="shaping-opentype-features.html" title="OpenType features">
11 <meta name="generator" content="GTK-Doc V1.29 (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="fonts-and-faces-variable.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
20 <td><a accesskey="n" href="shaping-opentype-features.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="shaping-and-shape-plans"></a>Shaping and shape plans</h2></div></div></div>
25 <div class="toc"><dl class="toc">
26 <dt><span class="section"><a href="shaping-and-shape-plans.html#shaping-buffer-output">Shaping and buffer output</a></span></dt>
27 <dt><span class="section"><a href="shaping-opentype-features.html">OpenType features</a></span></dt>
28 <dt><span class="section"><a href="shaping-shaper-selection.html">Shaper selection</a></span></dt>
29 <dt><span class="section"><a href="shaping-plans-and-caching.html">Plans and caching</a></span></dt>
32 Once you have your face and font objects configured as desired and
33 your input buffer is filled with the characters you need to shape,
34 all you need to do is call <code class="function">hb_shape()</code>.
37 HarfBuzz will return the shaped version of the text in the same
38 buffer that you provided, but it will be in output mode. At that
39 point, you can iterate through the glyphs in the buffer, drawing
40 each one at the specified position or handing them off to the
41 appropriate graphics library.
44 For the most part, HarfBuzz's shaping step is straightforward from
45 the outside. But that doesn't mean there will never be cases where
46 you want to look under the hood and see what is happening on the
47 inside. HarfBuzz provides facilities for doing that, too.
50 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
51 <a name="shaping-buffer-output"></a>Shaping and buffer output</h2></div></div></div>
53 The <code class="function">hb_shape()</code> function call takes four arguments: the font
54 object to use, the buffer of characters to shape, an array of
55 user-specified features to apply, and the length of that feature
56 array. The feature array can be NULL, so for the sake of
57 simplicity we will start with that case.
60 Internally, HarfBuzz looks at the tables of the font file to
61 determine where glyph classes, substitutions, and positioning
62 are defined, using that information to decide which
63 <span class="emphasis"><em>shaper</em></span> to use (<code class="literal">ot</code> for
64 OpenType fonts, <code class="literal">aat</code> for Apple Advanced
65 Typography fonts, and so on). It also looks at the direction,
66 script, and language properties of the segment to figure out
67 which script-specific shaping model is needed (at least, in
68 shapers that support multiple options).
71 If a font has a GDEF table, then that is used for
72 glyph classes; if not, HarfBuzz will fall back to Unicode
73 categorization by code point. If a font has an AAT "morx" table,
74 then it is used for substitutions; if not, but there is a GSUB
75 table, then the GSUB table is used. If the font has an AAT
76 "kerx" table, then it is used for positioning; if not, but
77 there is a GPOS table, then the GPOS table is used. If neither
78 table is found, but there is a "kern" table, then HarfBuzz will
79 use the "kern" table. If there is no "kerx", no GPOS, and no
80 "kern", HarfBuzz will fall back to positioning marks itself.
83 With a well-behaved OpenType font, you expect GDEF, GSUB, and
84 GPOS tables to all be applied. HarfBuzz implements the
85 script-specific shaping models in internal functions, rather
86 than in the public API.
90 used for complex scripts can be quite involved; HarfBuzz tries
91 to be compatible with the OpenType Layout specification
92 and, wherever there is any ambiguity, HarfBuzz attempts to replicate the
93 output of Microsoft's Uniscribe engine. See the <a class="ulink" href="https://docs.microsoft.com/en-us/typography/script-development/standard" target="_top">Microsoft
94 Typography pages</a> for more detail.
97 In general, though, all that you need to know is that
98 <code class="function">hb_shape()</code> returns the results of shaping
99 in the same buffer that you provided. The buffer's content type
101 <code class="literal">HB_BUFFER_CONTENT_TYPE_GLYPHS</code>, indicating
102 that it contains shaped output, rather than input text. You can
103 now extract the glyph information and positioning arrays:
105 <pre class="programlisting">
106 hb_glyph_info_t *glyph_info = hb_buffer_get_glyph_infos(buf, &glyph_count);
107 hb_glyph_position_t *glyph_pos = hb_buffer_get_glyph_positions(buf, &glyph_count);
110 The glyph information array holds a <span class="type">hb_glyph_info_t</span>
111 for each output glyph, which has two fields:
112 <em class="parameter"><code>codepoint</code></em> and
113 <em class="parameter"><code>cluster</code></em>. Whereas, in the input buffer,
114 the <em class="parameter"><code>codepoint</code></em> field contained the Unicode
115 code point, it now contains the glyph ID of the corresponding
116 glyph in the font. The <em class="parameter"><code>cluster</code></em> field is
117 an integer that you can use to help identify when shaping has
118 reordered, split, or combined code points; we will say more
119 about that in the next chapter.
122 The glyph positions array holds a corresponding
123 <span class="type">hb_glyph_position_t</span> for each output glyph,
124 containing four fields: <em class="parameter"><code>x_advance</code></em>,
125 <em class="parameter"><code>y_advance</code></em>,
126 <em class="parameter"><code>x_offset</code></em>, and
127 <em class="parameter"><code>y_offset</code></em>. The advances tell you how far
128 you need to move the drawing point after drawing this glyph,
129 depending on whether you are setting horizontal text (in which
130 case you will have x advances) or vertical text (for which you
131 will have y advances). The x and y offsets tell you where to
132 move to start drawing the glyph; usually you will have both and
133 x and a y offset, regardless of the text direction.
136 Most of the time, you will rely on a font-rendering library or
137 other graphics library to do the actual drawing of glyphs, so
138 you will need to iterate through the glyphs in the buffer and
139 pass the corresponding values off.
144 <hr>Generated by GTK-Doc V1.29</div>