docs/html/shaping-and-shape-plans.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   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.32.1 (XML mode)">
  12 <link rel="stylesheet" href="style.css" type="text/css">
  13 </head>
  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>
  21 </tr></table>
  22 <div class="chapter">
  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>
  30 </dl></div>
  31 <p>
  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>.
  35   </p>
  36 <p>
  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.
  42   </p>
  43 <p>
  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.
  48   </p>
  49 <div class="section">
  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>
  52 <p>
  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.
  58     </p>
  59 <p>
  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).
  69     </p>
  70 <p>
  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.
  81     </p>
  82 <p>
  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.
  87     </p>
  88 <p>
  89       The algorithms
  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.
  95     </p>
  96 <p>
  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
 100       will now be set to
 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:
 104     </p>
 105 <pre class="programlisting">
 106       hb_glyph_info_t *glyph_info    = hb_buffer_get_glyph_infos(buf, &amp;glyph_count);
 107       hb_glyph_position_t *glyph_pos = hb_buffer_get_glyph_positions(buf, &amp;glyph_count);
 108     </pre>
 109 <p>
 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.
 120     </p>
 121 <p>
 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.
 134     </p>
 135 <p>
 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.
 140     </p>
 141 </div>
 142 </div>
 143 <div class="footer">
 144 <hr>Generated by GTK-Doc V1.32.1</div>
 145 </body>
 146 </html>