hb-vector: HarfBuzz Manual

hb-vector

hb-vector — Glyph vector conversion

Functions

hb_vector_draw_t *	hb_vector_draw_create_or_fail ()
hb_vector_draw_t *	hb_vector_draw_reference ()
void	hb_vector_draw_destroy ()
hb_bool_t	hb_vector_draw_set_user_data ()
void *	hb_vector_draw_get_user_data ()
void	hb_vector_draw_set_transform ()
void	hb_vector_draw_get_transform ()
void	hb_vector_draw_set_scale_factor ()
void	hb_vector_draw_get_scale_factor ()
void	hb_vector_draw_set_extents ()
hb_bool_t	hb_vector_draw_get_extents ()
hb_bool_t	hb_vector_draw_set_glyph_extents ()
hb_draw_funcs_t *	hb_vector_draw_get_funcs ()
hb_bool_t	hb_vector_draw_glyph ()
void	hb_vector_svg_set_flat ()
void	hb_vector_svg_set_precision ()
hb_blob_t *	hb_vector_draw_render ()
void	hb_vector_draw_reset ()
void	hb_vector_draw_recycle_blob ()
hb_vector_paint_t *	hb_vector_paint_create_or_fail ()
hb_vector_paint_t *	hb_vector_paint_reference ()
void	hb_vector_paint_destroy ()
hb_bool_t	hb_vector_paint_set_user_data ()
void *	hb_vector_paint_get_user_data ()
void	hb_vector_paint_set_transform ()
void	hb_vector_paint_get_transform ()
void	hb_vector_paint_set_scale_factor ()
void	hb_vector_paint_get_scale_factor ()
void	hb_vector_paint_set_extents ()
hb_bool_t	hb_vector_paint_get_extents ()
hb_bool_t	hb_vector_paint_set_glyph_extents ()
void	hb_vector_paint_set_foreground ()
void	hb_vector_paint_set_palette ()
void	hb_vector_paint_set_custom_palette_color ()
void	hb_vector_paint_clear_custom_palette_colors ()
hb_paint_funcs_t *	hb_vector_paint_get_funcs ()
hb_bool_t	hb_vector_paint_glyph ()
void	hb_vector_svg_paint_set_flat ()
void	hb_vector_svg_paint_set_precision ()
hb_blob_t *	hb_vector_paint_render ()
void	hb_vector_paint_reset ()
void	hb_vector_paint_recycle_blob ()

Types and Values

enum	hb_vector_format_t
	hb_vector_extents_t
enum	hb_vector_extents_mode_t
typedef	hb_vector_draw_t
typedef	hb_vector_paint_t

Includes

#include <hb-vector.h>

Description

Functions for converting glyph draw and paint callbacks to vector output.

The initial backend is SVG. Extents must be set before calling render functions; otherwise render returns NULL.

Functions

hb_vector_draw_create_or_fail ()

hb_vector_draw_t *
hb_vector_draw_create_or_fail (hb_vector_format_t format);

Creates a new draw context for vector output.

Parameters

format

output format.

Returns

a newly allocated hb_vector_draw_t, or NULL on failure.

[nullable]

Since: 13.0.0

hb_vector_draw_reference ()

hb_vector_draw_t *
hb_vector_draw_reference (hb_vector_draw_t *draw);

Increases the reference count of draw .

Parameters

draw

a draw context.

Returns

referenced draw .

[transfer full]

Since: 13.0.0

hb_vector_draw_destroy ()

void
hb_vector_draw_destroy (hb_vector_draw_t *draw);

Decreases the reference count of draw and destroys it when it reaches zero.

Parameters

draw

a draw context.

Since: 13.0.0

hb_vector_draw_set_user_data ()

hb_bool_t
hb_vector_draw_set_user_data (hb_vector_draw_t *draw,
                              hb_user_data_key_t *key,
                              void *data,
                              hb_destroy_func_t destroy,
                              hb_bool_t replace);

Attaches user data to draw .

Parameters

draw	a draw context.
key	user-data key.
data	user-data value.
destroy	destroy callback for `data` .	[nullable]
replace	whether to replace an existing value for `key` .

Returns

true on success, false otherwise.

Since: 13.0.0

hb_vector_draw_get_user_data ()

void *
hb_vector_draw_get_user_data (hb_vector_draw_t *draw,
                              hb_user_data_key_t *key);

Gets previously attached user data from draw .

Parameters

draw	a draw context.
key	user-data key.

Returns

user-data value associated with key .

[nullable]

Since: 13.0.0

hb_vector_draw_set_transform ()

void
hb_vector_draw_set_transform (hb_vector_draw_t *draw,
                              float xx,
                              float yx,
                              float xy,
                              float yy,
                              float dx,
                              float dy);

Sets the affine transform used when drawing glyphs.

Parameters

draw	a draw context.
xx	transform xx component.
yx	transform yx component.
xy	transform xy component.
yy	transform yy component.
dx	transform x translation.
dy	transform y translation.

Since: 13.0.0

hb_vector_draw_get_transform ()

void
hb_vector_draw_get_transform (hb_vector_draw_t *draw,
                              float *xx,
                              float *yx,
                              float *xy,
                              float *yy,
                              float *dx,
                              float *dy);

Gets the affine transform used when drawing glyphs.

Parameters

draw	a draw context.
xx	transform xx component.	[out][nullable]
yx	transform yx component.	[out][nullable]
xy	transform xy component.	[out][nullable]
yy	transform yy component.	[out][nullable]
dx	transform x translation.	[out][nullable]
dy	transform y translation.	[out][nullable]

Since: 13.0.0

hb_vector_draw_set_scale_factor ()

void
hb_vector_draw_set_scale_factor (hb_vector_draw_t *draw,
                                 float x_scale_factor,
                                 float y_scale_factor);

Sets additional output scaling factors.

Parameters

draw	a draw context.
x_scale_factor	x scale factor.
y_scale_factor	y scale factor.

Since: 13.0.0

hb_vector_draw_get_scale_factor ()

void
hb_vector_draw_get_scale_factor (hb_vector_draw_t *draw,
                                 float *x_scale_factor,
                                 float *y_scale_factor);

Gets additional output scaling factors.

Parameters

draw	a draw context.
x_scale_factor	x scale factor.	[out][nullable]
y_scale_factor	y scale factor.	[out][nullable]

Since: 13.0.0

hb_vector_draw_set_extents ()

void
hb_vector_draw_set_extents (hb_vector_draw_t *draw,
                            const hb_vector_extents_t *extents);

Sets or expands output extents on draw . Passing NULL clears extents.

Parameters

draw	a draw context.
extents	output extents to set or expand.	[nullable]

Since: 13.0.0

hb_vector_draw_get_extents ()

hb_bool_t
hb_vector_draw_get_extents (hb_vector_draw_t *draw,
                            hb_vector_extents_t *extents);

Gets current output extents from draw .

Parameters

draw	a draw context.
extents	where to store current output extents.	[out][nullable]

Returns

true if extents are set, false otherwise.

Since: 13.0.0

hb_vector_draw_set_glyph_extents ()

hb_bool_t
hb_vector_draw_set_glyph_extents (hb_vector_draw_t *draw,
                                  const hb_glyph_extents_t *glyph_extents);

Expands draw extents using glyph_extents under the current transform.

Parameters

draw	a draw context.
glyph_extents	glyph extents in font units.

Returns

true on success, false otherwise.

Since: 13.0.0

hb_vector_draw_get_funcs ()

hb_draw_funcs_t *
hb_vector_draw_get_funcs (void);

Gets draw callbacks implemented by the vector draw backend.

Returns

immutable hb_draw_funcs_t singleton.

[transfer none]

Since: 13.0.0

hb_vector_draw_glyph ()

hb_bool_t
hb_vector_draw_glyph (hb_vector_draw_t *draw,
                      hb_font_t *font,
                      hb_codepoint_t glyph,
                      float pen_x,
                      float pen_y,
                      hb_vector_extents_mode_t extents_mode);

Draws one glyph into draw .

Parameters

draw	a draw context.
font	font object.
glyph	glyph ID.
pen_x	glyph x origin before context transform.
pen_y	glyph y origin before context transform.
extents_mode	extents update mode.

Returns

true if glyph data was emitted, false otherwise.

Since: 13.0.0

hb_vector_svg_set_flat ()

void
hb_vector_svg_set_flat (hb_vector_draw_t *draw,
                        hb_bool_t flat);

Enables or disables SVG draw flattening.

Parameters

draw	a draw context.
flat	whether to flatten geometry and disable reuse.

Since: 13.0.0

hb_vector_svg_set_precision ()

void
hb_vector_svg_set_precision (hb_vector_draw_t *draw,
                             unsigned  precision);

Sets numeric output precision for SVG draw output.

Parameters

draw	a draw context.
precision	decimal precision.

Since: 13.0.0

hb_vector_draw_render ()

hb_blob_t *
hb_vector_draw_render (hb_vector_draw_t *draw);

Renders accumulated draw content to an SVG blob.

Parameters

draw

a draw context.

Returns

output blob, or NULL if rendering cannot proceed.

[transfer full][nullable]

Since: 13.0.0

hb_vector_draw_reset ()

void
hb_vector_draw_reset (hb_vector_draw_t *draw);

Resets draw state and clears accumulated content.

Parameters

draw

a draw context.

Since: 13.0.0

hb_vector_draw_recycle_blob ()

void
hb_vector_draw_recycle_blob (hb_vector_draw_t *draw,
                             hb_blob_t *blob);

Provides a blob for internal buffer reuse by later render calls.

Parameters

draw	a draw context.
blob	previously rendered blob to recycle.	[nullable]

Since: 13.0.0

hb_vector_paint_create_or_fail ()

hb_vector_paint_t *
hb_vector_paint_create_or_fail (hb_vector_format_t format);

Creates a new paint context for vector output.

Parameters

format

output format.

Returns

a newly allocated hb_vector_paint_t, or NULL on failure.

[nullable]

Since: 13.0.0

hb_vector_paint_reference ()

hb_vector_paint_t *
hb_vector_paint_reference (hb_vector_paint_t *paint);

Increases the reference count of paint .

Parameters

paint

a paint context.

Returns

referenced paint .

[transfer full]

Since: 13.0.0

hb_vector_paint_destroy ()

void
hb_vector_paint_destroy (hb_vector_paint_t *paint);

Decreases the reference count of paint and destroys it when it reaches zero.

Parameters

paint

a paint context.

Since: 13.0.0

hb_vector_paint_set_user_data ()

hb_bool_t
hb_vector_paint_set_user_data (hb_vector_paint_t *paint,
                               hb_user_data_key_t *key,
                               void *data,
                               hb_destroy_func_t destroy,
                               hb_bool_t replace);

Attaches user data to paint .

Parameters

paint	a paint context.
key	user-data key.
data	user-data value.
destroy	destroy callback for `data` .	[nullable]
replace	whether to replace an existing value for `key` .

Returns

true on success, false otherwise.

Since: 13.0.0

hb_vector_paint_get_user_data ()

void *
hb_vector_paint_get_user_data (hb_vector_paint_t *paint,
                               hb_user_data_key_t *key);

Gets previously attached user data from paint .

Parameters

paint	a paint context.
key	user-data key.

Returns

user-data value associated with key .

[nullable]

Since: 13.0.0

hb_vector_paint_set_transform ()

void
hb_vector_paint_set_transform (hb_vector_paint_t *paint,
                               float xx,
                               float yx,
                               float xy,
                               float yy,
                               float dx,
                               float dy);

Sets the affine transform used when painting glyphs.

Parameters

paint	a paint context.
xx	transform xx component.
yx	transform yx component.
xy	transform xy component.
yy	transform yy component.
dx	transform x translation.
dy	transform y translation.

Since: 13.0.0

hb_vector_paint_get_transform ()

void
hb_vector_paint_get_transform (hb_vector_paint_t *paint,
                               float *xx,
                               float *yx,
                               float *xy,
                               float *yy,
                               float *dx,
                               float *dy);

Gets the affine transform used when painting glyphs.

Parameters

paint	a paint context.
xx	transform xx component.	[out][nullable]
yx	transform yx component.	[out][nullable]
xy	transform xy component.	[out][nullable]
yy	transform yy component.	[out][nullable]
dx	transform x translation.	[out][nullable]
dy	transform y translation.	[out][nullable]

Since: 13.0.0

hb_vector_paint_set_scale_factor ()

void
hb_vector_paint_set_scale_factor (hb_vector_paint_t *paint,
                                  float x_scale_factor,
                                  float y_scale_factor);

Sets additional output scaling factors.

Parameters

paint	a paint context.
x_scale_factor	x scale factor.
y_scale_factor	y scale factor.

Since: 13.0.0

hb_vector_paint_get_scale_factor ()

void
hb_vector_paint_get_scale_factor (hb_vector_paint_t *paint,
                                  float *x_scale_factor,
                                  float *y_scale_factor);

Gets additional output scaling factors.

Parameters

paint	a paint context.
x_scale_factor	x scale factor.	[out][nullable]
y_scale_factor	y scale factor.	[out][nullable]

Since: 13.0.0

hb_vector_paint_set_extents ()

void
hb_vector_paint_set_extents (hb_vector_paint_t *paint,
                             const hb_vector_extents_t *extents);

Sets or expands output extents on paint . Passing NULL clears extents.

Parameters

paint	a paint context.
extents	output extents to set or expand.	[nullable]

Since: 13.0.0

hb_vector_paint_get_extents ()

hb_bool_t
hb_vector_paint_get_extents (hb_vector_paint_t *paint,
                             hb_vector_extents_t *extents);

Gets current output extents from paint .

Parameters

paint	a paint context.
extents	where to store current output extents.	[out][nullable]

Returns

true if extents are set, false otherwise.

Since: 13.0.0

hb_vector_paint_set_glyph_extents ()

hb_bool_t
hb_vector_paint_set_glyph_extents (hb_vector_paint_t *paint,
                                   const hb_glyph_extents_t *glyph_extents);

Expands paint extents using glyph_extents under the current transform.

Parameters

paint	a paint context.
glyph_extents	glyph extents in font units.

Returns

true on success, false otherwise.

Since: 13.0.0

hb_vector_paint_set_foreground ()

void
hb_vector_paint_set_foreground (hb_vector_paint_t *paint,
                                hb_color_t foreground);

Sets fallback foreground color used by paint operations.

Parameters

paint	a paint context.
foreground	foreground color used for COLR foreground paints.

Since: 13.0.0

hb_vector_paint_set_palette ()

void
hb_vector_paint_set_palette (hb_vector_paint_t *paint,
                             int palette);

Sets the color palette index used by paint operations.

Parameters

paint	a paint context.
palette	palette index for color glyph painting.

Since: 13.0.0

hb_vector_paint_set_custom_palette_color ()

void
hb_vector_paint_set_custom_palette_color
                               (hb_vector_paint_t *paint,
                                unsigned  color_index,
                                hb_color_t color);

Overrides one font palette color entry for subsequent paint operations. Overrides are keyed by color_index and persist on paint until cleared (or replaced for the same index).

These overrides are consulted by paint operations that resolve CPAL entries, including SVG glyph content using var(--colorN).

Parameters

paint	a paint context.
color_index	color index to override.
color	replacement color.

Since: 13.0.0

hb_vector_paint_clear_custom_palette_colors ()

void
hb_vector_paint_clear_custom_palette_colors
                               (hb_vector_paint_t *paint);

Clears all custom palette color overrides previously set on paint .

After this call, palette lookups use the selected font palette without custom override entries.

Parameters

paint

a paint context.

Since: 13.0.0

hb_vector_paint_get_funcs ()

hb_paint_funcs_t *
hb_vector_paint_get_funcs (void);

Gets paint callbacks implemented by the vector paint backend.

Returns

immutable hb_paint_funcs_t singleton.

[transfer none]

Since: 13.0.0

hb_vector_paint_glyph ()

hb_bool_t
hb_vector_paint_glyph (hb_vector_paint_t *paint,
                       hb_font_t *font,
                       hb_codepoint_t glyph,
                       float pen_x,
                       float pen_y,
                       hb_vector_extents_mode_t extents_mode);

Paints one color glyph into paint .

Parameters

paint	a paint context.
font	font object.
glyph	glyph ID.
pen_x	glyph x origin before context transform.
pen_y	glyph y origin before context transform.
extents_mode	extents update mode.

Returns

true if glyph paint data was emitted, false otherwise.

Since: 13.0.0

hb_vector_svg_paint_set_flat ()

void
hb_vector_svg_paint_set_flat (hb_vector_paint_t *paint,
                              hb_bool_t flat);

Enables or disables SVG paint flattening.

Parameters

paint	a paint context.
flat	whether to flatten paint output and disable glyph-group reuse.

Since: 13.0.0

hb_vector_svg_paint_set_precision ()

void
hb_vector_svg_paint_set_precision (hb_vector_paint_t *paint,
                                   unsigned  precision);

Sets numeric output precision for SVG paint output.

Parameters

paint	a paint context.
precision	decimal precision.

Since: 13.0.0

hb_vector_paint_render ()

hb_blob_t *
hb_vector_paint_render (hb_vector_paint_t *paint);

Renders accumulated paint content to an SVG blob.

Parameters

paint

a paint context.

Returns

output blob, or NULL if rendering cannot proceed.

[transfer full][nullable]

Since: 13.0.0

hb_vector_paint_reset ()

void
hb_vector_paint_reset (hb_vector_paint_t *paint);

Resets paint state and clears accumulated content.

Parameters

paint

a paint context.

Since: 13.0.0

hb_vector_paint_recycle_blob ()

void
hb_vector_paint_recycle_blob (hb_vector_paint_t *paint,
                              hb_blob_t *blob);

Provides a blob for internal buffer reuse by later render calls.

Parameters

paint	a paint context.
blob	previously rendered blob to recycle.	[nullable]

Since: 13.0.0

Types and Values

enum hb_vector_format_t

Output format for vector conversion.

Members

HB_VECTOR_FORMAT_INVALID	Invalid format.
HB_VECTOR_FORMAT_SVG	SVG output.

Since: 13.0.0

hb_vector_extents_t

typedef struct {
  float x, y;
  float width, height;
} hb_vector_extents_t;

Vector output extents, mapped to SVG viewBox.

Members

float `x`;	Left edge of the output coordinate system.
float `y`;	Top edge of the output coordinate system.
float `width`;	Width of the output coordinate system.
float `height`;	Height of the output coordinate system.

Since: 13.0.0

enum hb_vector_extents_mode_t

Controls whether convenience glyph APIs update context extents.

Members

HB_VECTOR_EXTENTS_MODE_NONE	Do not update extents.
HB_VECTOR_EXTENTS_MODE_EXPAND	Union glyph ink extents into current extents.

Since: 13.0.0

hb_vector_draw_t

typedef struct hb_vector_draw_t hb_vector_draw_t;

Opaque draw context for vector outline conversion.

Since: 13.0.0

hb_vector_paint_t

typedef struct hb_vector_paint_t hb_vector_paint_t;

Opaque paint context for vector color-glyph conversion.

Since: 13.0.0