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