|  |  |  |  | 
FreeType is the free-software font-rendering engine included in desktop Linux distributions, Android, ChromeOS, iOS, and multiple Unix operating systems, and used by cross-platform programs like Chrome, Java, and GhostScript. Used together, HarfBuzz can perform shaping on Unicode text segments, outputting the glyph IDs that FreeType should rasterize from the active font as well as the positions at which those glyphs should be drawn.
      HarfBuzz provides integration points with FreeType at the
      face-object and font-object level and for the font-functions
      virtual-method structure of a font object. These functions
      make it easy for clients that use FreeType for rasterization
      or font-loading, to use HarfBuzz for shaping. To use the
      FreeType-integration API, include the
      hb-ft.h header.
    
In a typical client program, you will create your hb_face_t face object and hb_font_t font object from a FreeType FT_Face. HarfBuzz provides a suite of functions for doing this.
      In the most common case, you will want to use
      hb_ft_font_create_referenced(), which
      creates both an hb_face_t face object and
      hb_font_t font object (linked to that face object),
      and provides lifecycle management.
    
      It is important to note,
      though, that while HarfBuzz makes a distinction between its face and
      font objects, FreeType's FT_Face does not. After
      you create your FT_Face, you must set its size
      parameter using FT_Set_Char_Size(), because
      an hb_font_t is defined as an instance of an
      hb_face_t with size specified.
    
      #include <hb-ft.h>
      ...
      FT_New_Face(ft_library, font_path, index, &face);
      FT_Set_Char_Size(face, 0, 1000, 0, 0);
      hb_font_t *font = hb_ft_font_create(face);
    
      hb_ft_font_create_referenced() is
      the recommended function for creating an hb_face_t face
      object. This function calls FT_Reference_Face()
      before using the FT_Face and calls 
      FT_Done_Face() when it is finished using the
      FT_Face. Consequently, your client program does not need
      to worry about destroying the FT_Face while HarfBuzz
      is still using it.
    
      Although hb_ft_font_create_referenced() is
      the recommended function, there is another variant for client code
      where special circumstances make it necessary. The simpler
      version of the function is hb_ft_font_create(),
      which takes an FT_Face and an optional destroy callback 
      as its arguments. Because hb_ft_font_create() 
      does not offer lifecycle management, however, your client code will
      be responsible for tracking references to the FT_Face
      objects and destroying them when they are no longer needed. If you
      do not have a valid reason for doing this, use
      hb_ft_font_create_referenced(). 
    
      After you have created your font object from your
      FT_Face, you can set or retrieve the
      load_flags of the
      FT_Face through the hb_font_t
      object. HarfBuzz provides
      hb_ft_font_set_load_flags() and
      hb_ft_font_get_load_flags() for this
      purpose. The ability to set the
      load_flags through the font object
      could be useful for enabling or disabling hinting, for example,
      or to activate vertical layout.
    
      HarfBuzz also provides a utility function called
      hb_ft_font_has_changed() that you should
      call whenever you have altered the properties of your underlying
      FT_Face, as well as a
      hb_ft_get_face() that you can call on an
      hb_font_t font object to fetch its underlying FT_Face.
    
      With an hb_face_t and hb_font_t both linked
      to your FT_Face, you will typically also want to
      use FreeType for the font_funcs
      vtable of your hb_font_t. As a reminder, this
      font-functions structure is the set of methods that HarfBuzz
      will use to fetch important information from the font, such as
      the advances and extents of individual glyphs. 
    
All you need to do is call
      hb_ft_font_set_funcs(font);
    
      and HarfBuzz will use FreeType for the font-functions in
      font. 
    
As we noted above, an hb_font_t is derived from an hb_face_t with size (and, perhaps, other parameters, such as variation-axis coordinates) specified. Consequently, you can reuse an hb_face_t with several hb_font_t objects, and HarfBuzz provides functions to simplify this.
      The hb_ft_face_create_referenced()
      function creates just an hb_face_t from a FreeType
      FT_Face and, as with
      hb_ft_font_create_referenced() above,
      provides lifecycle management for the FT_Face.
    
      Similarly, there is an hb_ft_face_create()
      function variant that does not provide the lifecycle-management
      feature. As with the font-object case, if you use this version
      of the function, it will be your client code's respsonsibility
      to track usage of the FT_Face objects.
    
      A third variant of this function is
      hb_ft_face_create_cached(), which is the
      same as hb_ft_face_create() except that it
      also uses the generic field of the
      FT_Face structure to save a pointer to the newly
      created hb_face_t. Subsequently, function calls
      that pass the same FT_Face will get the same
      hb_face_t returned — and the
      hb_face_t will be correctly reference
      counted. Still, as with
      hb_ft_face_create(), your client code must
      track references to the FT_Face itself, and destroy
      it when it is unneeded.