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

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