docs/html/fonts-and-faces.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>Fonts, faces, and output: HarfBuzz Manual</title>
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
   7 <link rel="home" href="index.html" title="HarfBuzz Manual">
   8 <link rel="up" href="user-manual.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 (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="user-manual.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>
  21 </tr></table>
  22 <div class="chapter">
  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>
  30 <dt><span class="section"><a href="glyphs-and-rendering.html">Glyphs and rendering</a></span></dt>
  31 </dl></div>
  32 <p>
  33       In the previous chapter, we saw how to set up a buffer and fill
  34       it with text as Unicode code points. In order to shape this
  35       buffer text with HarfBuzz, you will need also need a font
  36       object.
  37     </p>
  38 <p>
  39       HarfBuzz provides abstractions to help you cache and reuse the
  40       heavier parts of working with binary fonts, so we will look at
  41       how to do that. We will also look at how to work with the
  42       FreeType font-rendering library and at how you can customize
  43       HarfBuzz to work with other libraries.
  44     </p>
  45 <p>
  46       Finally, we will look at how to work with OpenType variable
  47       fonts, the latest update to the OpenType font format, and at
  48       some other recent additions to OpenType.
  49     </p>
  50 <div class="section">
  51 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
  52 <a name="fonts-and-faces-objects"></a>Font and face objects</h2></div></div></div>
  53 <p>
  54       The outcome of shaping a run of text depends on the contents of
  55       a specific font file (such as the substitutions and positioning
  56       moves in the 'GSUB' and 'GPOS' tables), so HarfBuzz makes
  57       accessing those internals fast.
  58     </p>
  59 <p>
  60       An <span class="type">hb_face_t</span> represents a <span class="emphasis"><em>face</em></span>
  61       in HarfBuzz. This data type is a wrapper around an
  62       <span class="type">hb_blob_t</span> blob that holds the contents of a binary
  63       font file. Since HarfBuzz supports TrueType Collections and
  64       OpenType Collections (each of which can include multiple
  65       typefaces), a HarfBuzz face also requires an index number
  66       specifying which typeface in the file you want to use. Most of
  67       the font files you will encounter in the wild include just a
  68       single face, however, so most of the time you would pass in
  69       <code class="literal">0</code> as the index when you create a face:
  70     </p>
  71 <pre class="programlisting">
  72       hb_blob_t* blob = hb_blob_create_from_file(file);
  73       ...
  74       hb_face_t* face = hb_face_create(blob, 0);
  75     </pre>
  76 <p>
  77       On its own, a face object is not quite ready to use for
  78       shaping. The typeface must be set to a specific point size in
  79       order for some details (such as hinting) to work. In addition,
  80       if the font file in question is an OpenType Variable Font, then
  81       you may need to specify one or more variation-axis settings (or a
  82       named instance) in order to get the output you need.
  83     </p>
  84 <p>
  85       In HarfBuzz, you do this by creating a <span class="emphasis"><em>font</em></span>
  86       object from your face.
  87     </p>
  88 <p>
  89       Font objects also have the advantage of being considerably
  90       lighter-weight than face objects (remember that a face contains
  91       the contents of a binary font file mapped into memory). As a
  92       result, you can cache and reuse a font object, but you could
  93       also create a new one for each additional size you needed.
  94       Creating new fonts incurs some additional overhead, of course,
  95       but whether or not it is excessive is your call in the end. In
  96       contrast, face objects are substantially larger, and you really
  97       should cache them and reuse them whenever possible.
  98     </p>
  99 <p>
 100       You can create a font object from a face object:
 101     </p>
 102 <pre class="programlisting">
 103       hb_font_t* hb_font = hb_font_create(hb_face);
 104     </pre>
 105 <p>
 106       After creating a font, there are a few properties you should
 107       set. Many fonts enable and disable hints based on the size it
 108       is used at, so setting this is important for font
 109       objects. <code class="function">hb_font_set_ppem(font, x_ppem,
 110       y_ppem)</code> sets the pixels-per-EM value of the font. You
 111       can also set the point size of the font with
 112       <code class="function">hb_font_set_ptem(font, ptem)</code>. HarfBuzz uses the
 113       industry standard 72 points per inch.
 114     </p>
 115 <p>
 116       HarfBuzz lets you specify the degree subpixel precision you want
 117       through a scaling factor. You can set horizontal and
 118       vertical scaling factors on the
 119       font by calling <code class="function">hb_font_set_scale(font, x_scale,
 120       y_scale)</code>.
 121     </p>
 122 <p>
 123       There may be times when you are handed a font object and need to
 124       access the face object that it comes from. For that, you can call
 125     </p>
 126 <pre class="programlisting">
 127       hb_face = hb_font_get_face(hb_font);
 128     </pre>
 129 <p>
 130       You can also create a font object from an existing font object
 131       using the <code class="function">hb_font_create_sub_font()</code>
 132       function. This creates a child font object that is initiated
 133       with the same attributes as its parent; it can be used to
 134       quickly set up a new font for the purpose of overriding a specific
 135       font-functions method.
 136     </p>
 137 <p>
 138       All face objects and font objects are lifecycle-managed by
 139       HarfBuzz. After creating a face, you increase its reference
 140       count with <code class="function">hb_face_reference(face)</code> and
 141       decrease it with
 142       <code class="function">hb_face_destroy(face)</code>. Likewise, you
 143       increase the reference count on a font with
 144       <code class="function">hb_font_reference(font)</code> and decrease it
 145       with <code class="function">hb_font_destroy(font)</code>.
 146     </p>
 147 <p>
 148       You can also attach user data to face objects and font objects.
 149     </p>
 150 </div>
 151 </div>
 152 <div class="footer">
 153 <hr>Generated by GTK-Doc V1.32</div>
 154 </body>
 155 </html>