/usr/share/gtk-doc/html/harfbuzz
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> <title>Shaping and shape plans: HarfBuzz Manual</title> <meta name="generator" content="DocBook XSL Stylesheets V1.79.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="fonts-and-faces-variable.html" title="Working with OpenType Variable Fonts"> <link rel="next" href="shaping-opentype-features.html" title="OpenType features"> <meta name="generator" content="GTK-Doc V1.32 (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="fonts-and-faces-variable.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td> <td><a accesskey="n" href="shaping-opentype-features.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="shaping-and-shape-plans"></a>Shaping and shape plans</h2></div></div></div> <div class="toc"><dl class="toc"> <dt><span class="section"><a href="shaping-and-shape-plans.html#shaping-buffer-output">Shaping and buffer output</a></span></dt> <dt><span class="section"><a href="shaping-opentype-features.html">OpenType features</a></span></dt> <dt><span class="section"><a href="shaping-shaper-selection.html">Shaper selection</a></span></dt> <dt><span class="section"><a href="shaping-plans-and-caching.html">Plans and caching</a></span></dt> </dl></div> <p> Once you have your face and font objects configured as desired and your input buffer is filled with the characters you need to shape, all you need to do is call <code class="function">hb_shape()</code>. </p> <p> HarfBuzz will return the shaped version of the text in the same buffer that you provided, but it will be in output mode. At that point, you can iterate through the glyphs in the buffer, drawing each one at the specified position or handing them off to the appropriate graphics library. </p> <p> For the most part, HarfBuzz's shaping step is straightforward from the outside. But that doesn't mean there will never be cases where you want to look under the hood and see what is happening on the inside. HarfBuzz provides facilities for doing that, too. </p> <div class="section"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> <a name="shaping-buffer-output"></a>Shaping and buffer output</h2></div></div></div> <p> The <code class="function">hb_shape()</code> function call takes four arguments: the font object to use, the buffer of characters to shape, an array of user-specified features to apply, and the length of that feature array. The feature array can be NULL, so for the sake of simplicity we will start with that case. </p> <p> Internally, HarfBuzz looks at the tables of the font file to determine where glyph classes, substitutions, and positioning are defined, using that information to decide which <span class="emphasis"><em>shaper</em></span> to use (<code class="literal">ot</code> for OpenType fonts, <code class="literal">aat</code> for Apple Advanced Typography fonts, and so on). It also looks at the direction, script, and language properties of the segment to figure out which script-specific shaping model is needed (at least, in shapers that support multiple options). </p> <p> If a font has a GDEF table, then that is used for glyph classes; if not, HarfBuzz will fall back to Unicode categorization by code point. If a font has an AAT <code class="literal">morx</code> table, then it is used for substitutions; if not, but there is a GSUB table, then the GSUB table is used. If the font has an AAT <code class="literal">kerx</code> table, then it is used for positioning; if not, but there is a GPOS table, then the GPOS table is used. If neither table is found, but there is a <code class="literal">kern</code> table, then HarfBuzz will use the <code class="literal">kern</code> table. If there is no <code class="literal">kerx</code>, no GPOS, and no <code class="literal">kern</code>, HarfBuzz will fall back to positioning marks itself. </p> <p> With a well-behaved OpenType font, you expect GDEF, GSUB, and GPOS tables to all be applied. HarfBuzz implements the script-specific shaping models in internal functions, rather than in the public API. </p> <p> The algorithms used for complex scripts can be quite involved; HarfBuzz tries to be compatible with the OpenType Layout specification and, wherever there is any ambiguity, HarfBuzz attempts to replicate the 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 Typography pages</a> for more detail. </p> <p> In general, though, all that you need to know is that <code class="function">hb_shape()</code> returns the results of shaping in the same buffer that you provided. The buffer's content type will now be set to <code class="literal">HB_BUFFER_CONTENT_TYPE_GLYPHS</code>, indicating that it contains shaped output, rather than input text. You can now extract the glyph information and positioning arrays: </p> <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> <p> The glyph information array holds a <span class="type">hb_glyph_info_t</span> for each output glyph, which has two fields: <em class="parameter"><code>codepoint</code></em> and <em class="parameter"><code>cluster</code></em>. Whereas, in the input buffer, the <em class="parameter"><code>codepoint</code></em> field contained the Unicode code point, it now contains the glyph ID of the corresponding glyph in the font. The <em class="parameter"><code>cluster</code></em> field is an integer that you can use to help identify when shaping has reordered, split, or combined code points; we will say more about that in the next chapter. </p> <p> The glyph positions array holds a corresponding <span class="type">hb_glyph_position_t</span> for each output glyph, containing four fields: <em class="parameter"><code>x_advance</code></em>, <em class="parameter"><code>y_advance</code></em>, <em class="parameter"><code>x_offset</code></em>, and <em class="parameter"><code>y_offset</code></em>. The advances tell you how far you need to move the drawing point after drawing this glyph, depending on whether you are setting horizontal text (in which case you will have x advances) or vertical text (for which you will have y advances). The x and y offsets tell you where to move to start drawing the glyph; usually you will have both and x and a y offset, regardless of the text direction. </p> <p> Most of the time, you will rely on a font-rendering library or other graphics library to do the actual drawing of glyphs, so you will need to iterate through the glyphs in the buffer and pass the corresponding values off. </p> </div> </div> <div class="footer"> <hr>Generated by GTK-Doc V1.32</div> </body> </html>
.
Edit
..
Edit
HarfBuzz.png
Edit
HarfBuzz.svg
Edit
a-clustering-example-for-levels-0-and-1.html
Edit
aat-shaping.html
Edit
adding-text-to-the-buffer.html
Edit
annotation-glossary.html
Edit
api-index-0-9-10.html
Edit
api-index-0-9-11.html
Edit
api-index-0-9-2.html
Edit
api-index-0-9-20.html
Edit
api-index-0-9-22.html
Edit
api-index-0-9-28.html
Edit
api-index-0-9-30.html
Edit
api-index-0-9-31.html
Edit
api-index-0-9-38.html
Edit
api-index-0-9-39.html
Edit
api-index-0-9-41.html
Edit
api-index-0-9-42.html
Edit
api-index-0-9-5.html
Edit
api-index-0-9-7.html
Edit
api-index-0-9-8.html
Edit
api-index-1-0-5.html
Edit
api-index-1-1-2.html
Edit
api-index-1-1-3.html
Edit
api-index-1-2-3.html
Edit
api-index-1-3-3.html
Edit
api-index-1-4-0.html
Edit
api-index-1-4-2.html
Edit
api-index-1-4-3.html
Edit
api-index-1-5-0.html
Edit
api-index-1-6-0.html
Edit
api-index-1-7-5.html
Edit
api-index-1-7-7.html
Edit
api-index-1-8-0.html
Edit
api-index-1-8-1.html
Edit
api-index-1-8-5.html
Edit
api-index-1-8-6.html
Edit
api-index-1-9-0.html
Edit
api-index-2-0-0.html
Edit
api-index-2-1-0.html
Edit
api-index-2-2-0.html
Edit
api-index-2-3-0.html
Edit
api-index-2-4-0.html
Edit
api-index-2-5-0.html
Edit
api-index-2-6-0.html
Edit
api-index-2-7-3.html
Edit
api-index-full.html
Edit
buffers-language-script-and-direction.html
Edit
building.html
Edit
ch01s03.html
Edit
ch03s02.html
Edit
ch03s03.html
Edit
ch12.html
Edit
ch13.html
Edit
ch14.html
Edit
ch15.html
Edit
clusters.html
Edit
complex-scripts.html
Edit
customizing-unicode-functions.html
Edit
deprecated-api-index.html
Edit
fonts-and-faces-custom-functions.html
Edit
fonts-and-faces-native-opentype.html
Edit
fonts-and-faces-variable.html
Edit
fonts-and-faces.html
Edit
getting-started.html
Edit
graphite-shaping.html
Edit
harfbuzz-hb-aat-layout.html
Edit
harfbuzz-hb-blob.html
Edit
harfbuzz-hb-buffer.html
Edit
harfbuzz-hb-common.html
Edit
harfbuzz-hb-coretext.html
Edit
harfbuzz-hb-deprecated.html
Edit
harfbuzz-hb-directwrite.html
Edit
harfbuzz-hb-face.html
Edit
harfbuzz-hb-font.html
Edit
harfbuzz-hb-ft.html
Edit
harfbuzz-hb-gdi.html
Edit
harfbuzz-hb-glib.html
Edit
harfbuzz-hb-gobject.html
Edit
harfbuzz-hb-graphite2.html
Edit
harfbuzz-hb-icu.html
Edit
harfbuzz-hb-map.html
Edit
harfbuzz-hb-ot-color.html
Edit
harfbuzz-hb-ot-font.html
Edit
harfbuzz-hb-ot-layout.html
Edit
harfbuzz-hb-ot-math.html
Edit
harfbuzz-hb-ot-meta.html
Edit
harfbuzz-hb-ot-metrics.html
Edit
harfbuzz-hb-ot-name.html
Edit
harfbuzz-hb-ot-shape.html
Edit
harfbuzz-hb-ot-var.html
Edit
harfbuzz-hb-set.html
Edit
harfbuzz-hb-shape-plan.html
Edit
harfbuzz-hb-shape.html
Edit
harfbuzz-hb-unicode.html
Edit
harfbuzz-hb-uniscribe.html
Edit
harfbuzz-hb-version.html
Edit
harfbuzz.devhelp2
Edit
home.png
Edit
index.html
Edit
install-harfbuzz.html
Edit
integration-coretext.html
Edit
integration-freetype.html
Edit
integration-icu.html
Edit
integration-python.html
Edit
integration-uniscribe.html
Edit
integration.html
Edit
left-insensitive.png
Edit
left.png
Edit
level-2.html
Edit
object-model-blobs.html
Edit
object-model-lifecycle.html
Edit
object-model-object-types.html
Edit
object-model-user-data.html
Edit
object-model.html
Edit
opentype-shaping-models.html
Edit
pt01.html
Edit
pt02.html
Edit
reordering-in-levels-0-and-1.html
Edit
right-insensitive.png
Edit
right.png
Edit
setting-buffer-properties.html
Edit
shaping-and-shape-plans.html
Edit
shaping-concepts.html
Edit
shaping-opentype-features.html
Edit
shaping-operations.html
Edit
shaping-plans-and-caching.html
Edit
shaping-shaper-selection.html
Edit
style.css
Edit
text-runs.html
Edit
the-distinction-between-levels-0-and-1.html
Edit
unicode-character-categories.html
Edit
up-insensitive.png
Edit
up.png
Edit
utilities-common-types-apis.html
Edit
utilities-ucdn.html
Edit
utilities.html
Edit
what-harfbuzz-doesnt-do.html
Edit
what-is-harfbuzz.html
Edit
why-do-i-need-a-shaping-engine.html
Edit
why-is-it-called-harfbuzz.html
Edit
working-with-harfbuzz-clusters.html
Edit
