Working with OpenType Variable Fonts: HarfBuzz Manual

## Working with OpenType Variable Fonts

If you are working with OpenType Variable Fonts, there are a few additional functions you should use to specify the variation-axis settings of your font object. Without doing so, your variable font's font object can still be used, but only at the default setting for every axis (which, of course, is sometimes what you want, but does not cover general usage).

HarfBuzz manages variation settings in the hb_variation_t data type, which holds a tag for the variation-axis identifier tag and a value for its setting. You can retrieve the list of variation axes in a font binary from the face object (not from a font object, notably) by calling `hb_ot_var_get_axis_count(face)` to find the number of axes, then using `hb_ot_var_get_axis_infos()` to collect the axis structures:

    axes = hb_ot_var_get_axis_count(face);
    ...
    hb_ot_var_get_axis_infos(face, 0, axes, axes_array);

For each axis returned in the array, you can can access the identifier in its tag. HarfBuzz also has tag definitions predefined for the five standard axes specified in OpenType (`ital` for italic, `opsz` for optical size, `slnt` for slant, `wdth` for width, and `wght` for weight). Each axis also has a min_value, a default_value, and a max_value.

To set your font object's variation settings, you call the `hb_font_set_variations()` function with an array of hb_variation_t variation settings. Let's say our font has weight and width axes. We need to specify each of the axes by tag and assign a value on the axis:

    unsigned int variation_count = 2;
    hb_variation_t variation_data[variation_count];
    variation_data[0].tag = HB_OT_TAG_VAR_AXIS_WIDTH;
    variation_data[1].tag = HB_OT_TAG_VAR_AXIS_WEIGHT;
    variation_data[0].value = 80;
    variation_data[1].value = 750;
    ...
    hb_font_set_variations(font, variation_data, variation_count);

That should give us a slightly condensed font ("normal" on the `wdth` axis is 100) at a noticeably bolder weight ("regular" is 400 on the `wght` axis).

In practice, though, you should always check that the value you want to set on the axis is within the [min_value,max_value] range actually implemented in the font's variation axis. After all, a font might only provide lighter-than-regular weights, and setting a heavier value on the `wght` axis will not change that.

Once your variation settings are specified on your font object, however, shaping with a variable font is just like shaping a static font.

In addition to providing the variation axes themselves, fonts may also pre-define certain variation coordinates as named instances. HarfBuzz makes these coordinates (and their associated names) available via `hb_ot_var_named_instance_get_design_coords()` and `hb_ot_var_named_instance_get_subfamily_name_id()`.

Applications should treat named instances like multiple independent, static fonts.