|  |  |  |  | 
In the previous chapter, we saw how to set up a buffer and fill it with text as Unicode code points. In order to shape this buffer text with HarfBuzz, you will need also need a font object.
HarfBuzz provides abstractions to help you cache and reuse the heavier parts of working with binary fonts, so we will look at how to do that. We will also look at how to work with the FreeType font-rendering library and at how you can customize HarfBuzz to work with other libraries.
Finally, we will look at how to work with OpenType variable fonts, the latest update to the OpenType font format, and at some other recent additions to OpenType.
The outcome of shaping a run of text depends on the contents of a specific font file (such as the substitutions and positioning moves in the 'GSUB' and 'GPOS' tables), so HarfBuzz makes accessing those internals fast.
      An hb_face_t represents a face
      in HarfBuzz. This data type is a wrapper around an
      hb_blob_t blob that holds the contents of a binary
      font file. Since HarfBuzz supports TrueType Collections and
      OpenType Collections (each of which can include multiple
      typefaces), a HarfBuzz face also requires an index number
      specifying which typeface in the file you want to use. Most of
      the font files you will encounter in the wild include just a
      single face, however, so most of the time you would pass in
      0 as the index when you create a face:
    
      hb_blob_t* blob = hb_blob_create_from_file(file);
      ...
      hb_face_t* face = hb_face_create(blob, 0);
    
On its own, a face object is not quite ready to use for shaping. The typeface must be set to a specific point size in order for some details (such as hinting) to work. In addition, if the font file in question is an OpenType Variable Font, then you may need to specify one or more variation-axis settings (or a named instance) in order to get the output you need.
In HarfBuzz, you do this by creating a font object from your face.
Font objects also have the advantage of being considerably lighter-weight than face objects (remember that a face contains the contents of a binary font file mapped into memory). As a result, you can cache and reuse a font object, but you could also create a new one for each additional size you needed. Creating new fonts incurs some additional overhead, of course, but whether or not it is excessive is your call in the end. In contrast, face objects are substantially larger, and you really should cache them and reuse them whenever possible.
You can create a font object from a face object:
      hb_font_t* hb_font = hb_font_create(hb_face);
    
      After creating a font, there are a few properties you should
      set. Many fonts enable and disable hints based on the size it
      is used at, so setting this is important for font
      objects. hb_font_set_ppem(font, x_ppem,
      y_ppem) sets the pixels-per-EM value of the font. You
      can also set the point size of the font with
      hb_font_set_ptem(font, ptem). HarfBuzz uses the
      industry standard 72 points per inch.
    
      HarfBuzz lets you specify the degree subpixel precision you want
      through a scaling factor. You can set horizontal and
      vertical scaling factors on the
      font by calling hb_font_set_scale(font, x_scale,
      y_scale). 
    
There may be times when you are handed a font object and need to access the face object that it comes from. For that, you can call
      hb_face = hb_font_get_face(hb_font);
    
      You can also create a font object from an existing font object
      using the hb_font_create_sub_font()
      function. This creates a child font object that is initiated
      with the same attributes as its parent; it can be used to
      quickly set up a new font for the purpose of overriding a specific
      font-functions method.
    
      All face objects and font objects are lifecycle-managed by
      HarfBuzz. After creating a face, you increase its reference
      count with hb_face_reference(face) and
      decrease it with
      hb_face_destroy(face). Likewise, you
      increase the reference count on a font with
      hb_font_reference(font) and decrease it
      with hb_font_destroy(font).
    
You can also attach user data to face objects and font objects.