hb-ot-var: HarfBuzz Manual

## hb-ot-var hb-ot-var — OpenType Font Variations |

## Functions

hb_bool_t | hb_ot_var_has_data ()
hb_bool_t | hb_ot_var_find_axis_info ()
unsigned int | hb_ot_var_get_axis_count ()
unsigned int | hb_ot_var_get_axis_infos ()
unsigned int | hb_ot_var_get_named_instance_count ()
hb_ot_name_id_t | hb_ot_var_named_instance_get_subfamily_name_id ()
hb_ot_name_id_t | hb_ot_var_named_instance_get_postscript_name_id ()
unsigned int | hb_ot_var_named_instance_get_design_coords ()
void | hb_ot_var_normalize_variations ()
void | hb_ot_var_normalize_coords ()

## Types and Values

#define | HB_OT_TAG_VAR_AXIS_ITALIC
#define | HB_OT_TAG_VAR_AXIS_OPTICAL_SIZE
#define | HB_OT_TAG_VAR_AXIS_SLANT
#define | HB_OT_TAG_VAR_AXIS_WEIGHT
#define | HB_OT_TAG_VAR_AXIS_WIDTH
enum | hb_ot_var_axis_flags_t
| hb_ot_var_axis_info_t

## Includes

    #include <hb-ot.h>

## Description

Functions for fetching information about OpenType Variable Fonts.

## Functions

### hb_ot_var_has_data ()

    hb_bool_t
    hb_ot_var_has_data (hb_face_t *face);

Tests whether a face includes any OpenType variation data in the `fvar` table.

#### Parameters

face | The hb_face_t to work on |

#### Returns

`true` if data found, `false` otherwise

Since: 1.4.2

### hb_ot_var_find_axis_info ()

    hb_bool_t
    hb_ot_var_find_axis_info (hb_face_t *face,
                              hb_tag_t axis_tag,
                              hb_ot_var_axis_info_t *axis_info);

Fetches the variation-axis information corresponding to the specified axis tag in the specified face.

#### Parameters

face | hb_face_t to work upon |
axis_tag | The hb_tag_t of the variation axis to query |
axis_info | The hb_ot_var_axis_info_t of the axis tag queried. | [out]

#### Returns

`true` if data found, `false` otherwise

Since: 2.2.0

### hb_ot_var_get_axis_count ()

    unsigned int
    hb_ot_var_get_axis_count (hb_face_t *face);

Fetches the number of OpenType variation axes included in the face.

#### Parameters

face | The hb_face_t to work on |

#### Returns

the number of variation axes defined

Since: 1.4.2

### hb_ot_var_get_axis_infos ()

    unsigned int
    hb_ot_var_get_axis_infos (hb_face_t *face,
                              unsigned int start_offset,
                              unsigned int *axes_count,
                              hb_ot_var_axis_info_t *axes_array);

Fetches a list of all variation axes in the specified face. The list returned will begin at the offset provided.

#### Parameters

face | hb_face_t to work upon |
start_offset | offset of the first lookup to retrieve |
axes_count | Input = the maximum number of variation axes to return; Output = the actual number of variation axes returned (may be zero). | [inout][optional]
axes_array | The array of variation axes found. | [out caller-allocates][array length=axes_count]

#### Returns

the number of variation axes in the face

Since: 2.2.0

### hb_ot_var_get_named_instance_count ()

    unsigned int
    hb_ot_var_get_named_instance_count (hb_face_t *face);

Fetches the number of named instances included in the face.

#### Parameters

face | The hb_face_t to work on |

#### Returns

the number of named instances defined

Since: 2.2.0

### hb_ot_var_named_instance_get_subfamily_name_id ()

    hb_ot_name_id_t
    hb_ot_var_named_instance_get_subfamily_name_id
                                   (hb_face_t *face,
                                    unsigned int instance_index);

Fetches the `name` table Name ID that provides display names for the "Subfamily name" defined for the given named instance in the face.

#### Parameters

face | The hb_face_t to work on |
instance_index | The index of the named instance to query |

#### Returns

the Name ID found for the Subfamily name

Since: 2.2.0

### hb_ot_var_named_instance_get_postscript_name_id ()

    hb_ot_name_id_t
    hb_ot_var_named_instance_get_postscript_name_id
                                   (hb_face_t *face,
                                    unsigned int instance_index);

Fetches the `name` table Name ID that provides display names for the "PostScript name" defined for the given named instance in the face.

#### Parameters

face | The hb_face_t to work on |
instance_index | The index of the named instance to query |

#### Returns

the Name ID found for the PostScript name

Since: 2.2.0

### hb_ot_var_named_instance_get_design_coords ()

    unsigned int
    hb_ot_var_named_instance_get_design_coords
                                   (hb_face_t *face,
                                    unsigned int instance_index,
                                    unsigned int *coords_length,
                                    float *coords);

Fetches the design-space coordinates corresponding to the given named instance in the face.

#### Parameters

face | The hb_face_t to work on |
instance_index | The index of the named instance to query |
coords_length | Input = the maximum number of coordinates to return; Output = the actual number of coordinates returned (may be zero). | [inout][optional]
coords | The array of coordinates found for the query. | [out][array length=coords_length]

#### Returns

the number of variation axes in the face

Since: 2.2.0

### hb_ot_var_normalize_variations ()

    void
    hb_ot_var_normalize_variations (hb_face_t *face,
                                    const hb_variation_t *variations,
                                    unsigned int variations_length,
                                    int *coords,
                                    unsigned int coords_length);

Normalizes all of the coordinates in the given list of variation axes.

#### Parameters

face | The hb_face_t to work on |
variations | The array of variations to normalize |
variations_length | The number of variations to normalize |
coords | The array of normalized coordinates. | [out][array length=coords_length]
coords_length | The length of the coordinate array |

Since: 1.4.2

### hb_ot_var_normalize_coords ()

    void
    hb_ot_var_normalize_coords (hb_face_t *face,
                                unsigned int coords_length,
                                const float *design_coords,
                                int *normalized_coords);

Normalizes the given design-space coordinates. The minimum and maximum values for the axis are mapped to the interval [-1,1], with the default axis value mapped to 0.

The normalized values have 14 bits of fixed-point sub-integer precision as per OpenType specification.

Any additional scaling defined in the face's `avar` table is also applied, as described at https://docs.microsoft.com/en-us/typography/opentype/spec/avar

Note: `coords_length` must be the same as the number of axes in the face, as for example returned by `hb_ot_var_get_axis_count()`. Otherwise, the behavior is undefined.

#### Parameters

face | The hb_face_t to work on |
coords_length | The length of the coordinate array |
design_coords | The design-space coordinates to normalize |
normalized_coords | The normalized coordinates. | [out]

Since: 1.4.2

## Types and Values

### HB_OT_TAG_VAR_AXIS_ITALIC

    #define HB_OT_TAG_VAR_AXIS_ITALIC HB_TAG('i','t','a','l')

Registered tag for the roman/italic axis.

### HB_OT_TAG_VAR_AXIS_OPTICAL_SIZE

    #define HB_OT_TAG_VAR_AXIS_OPTICAL_SIZE HB_TAG('o','p','s','z')

Registered tag for the optical-size axis.

Note: The optical-size axis supersedes the OpenType `size` feature.

### HB_OT_TAG_VAR_AXIS_SLANT

    #define HB_OT_TAG_VAR_AXIS_SLANT HB_TAG('s','l','n','t')

Registered tag for the slant axis

### HB_OT_TAG_VAR_AXIS_WEIGHT

    #define HB_OT_TAG_VAR_AXIS_WEIGHT HB_TAG('w','g','h','t')

Registered tag for the weight axis.

### HB_OT_TAG_VAR_AXIS_WIDTH

    #define HB_OT_TAG_VAR_AXIS_WIDTH HB_TAG('w','d','t','h')

Registered tag for the width axis.

### enum hb_ot_var_axis_flags_t

Flags for hb_ot_var_axis_info_t.

#### Members

HB_OT_VAR_AXIS_FLAG_HIDDEN | The axis should not be exposed directly in user interfaces. |

Since: 2.2.0

### hb_ot_var_axis_info_t

    typedef struct {
      unsigned int			axis_index;
      hb_tag_t			tag;
      hb_ot_name_id_t		name_id;
      hb_ot_var_axis_flags_t flags;
      float				min_value;
      float				default_value;
      float				max_value;
    } hb_ot_var_axis_info_t;

Data type for holding variation-axis values.

The minimum, default, and maximum values are in un-normalized, user scales.

Note: at present, the only flag defined for `flags` is HB_OT_VAR_AXIS_FLAG_HIDDEN.

#### Members

unsigned int `axis_index`; | Index of the axis in the variation-axis array |
hb_tag_t `tag`; | The hb_tag_t tag identifying the design variation of the axis |
hb_ot_name_id_t `name_id`; | The `name` table Name ID that provides display names for the axis |
hb_ot_var_axis_flags_t `flags`; | The hb_ot_var_axis_flags_t flags for the axis |
float `min_value`; | The minimum value on the variation axis that the font covers |
float `default_value`; | The position on the variation axis corresponding to the font's defaults |
float `max_value`; | The maximum value on the variation axis that the font covers |

Since: 2.2.0