Cairo integration: HarfBuzz Manual

## Cairo integration

Cairo is a 2D graphics library that is frequently used together with GTK and Pango. Cairo supports rendering text using FreeType, or by using callback-based 'user fonts'.

HarfBuzz provides integration points with cairo for fonts as well as for buffers. To use the Cairo-integration API, link against libharfbuzz-cairo, and include the `hb-cairo.h` header. For easy buildsystem integration, HarfBuzz comes with a `harfbuzz-cairo.pc` pkg-config file.

To create a cairo_scaled_font_t font from a HarfBuzz hb_font_t, you can use `hb_cairo_font_face_create_for_font()` or `hb_cairo_font_face_create_for_face()`. The former API applies variations and synthetic slant from the hb_font_t when rendering, the latter takes them from the cairo_font_options_t that were passed when creating the cairo_scaled_font_t.

The Cairo fonts created in this way make use of Cairo's user-font facilities. They can be used to render on any Cairo context, and provide full support for font rendering features, including color. One current limitation of the implementation is that it does not support hinting for glyph outlines.

When using color fonts with this API, the color palette index is taken from the cairo_font_options_t (with new enough Cairo), and the foreground color is extracted from the source of the Cairo context.

To render the results of shaping a piece of text, use `hb_cairo_glyphs_from_buffer()` to obtain the glyphs in a form that can be passed to `cairo_show_text_glyphs()` or `cairo_show_glyphs()`.