hb-raster: HarfBuzz Manual

## hb-raster hb-raster — Glyph rasterization |

## Functions

hb_raster_image_t * | hb_raster_image_create_or_fail ()
hb_raster_image_t * | hb_raster_image_reference ()
void | hb_raster_image_destroy ()
hb_bool_t | hb_raster_image_set_user_data ()
void * | hb_raster_image_get_user_data ()
hb_bool_t | hb_raster_image_configure ()
void | hb_raster_image_clear ()
const uint8_t * | hb_raster_image_get_buffer ()
void | hb_raster_image_get_extents ()
hb_raster_format_t | hb_raster_image_get_format ()
hb_bool_t | hb_raster_image_deserialize_from_png_or_fail ()
hb_blob_t * | hb_raster_image_serialize_to_png_or_fail ()
hb_raster_draw_t * | hb_raster_draw_create_or_fail ()
hb_raster_draw_t * | hb_raster_draw_reference ()
void | hb_raster_draw_destroy ()
hb_bool_t | hb_raster_draw_set_user_data ()
void * | hb_raster_draw_get_user_data ()
void | hb_raster_draw_set_transform ()
void | hb_raster_draw_set_scale_factor ()
void | hb_raster_draw_get_scale_factor ()
void | hb_raster_draw_get_transform ()
void | hb_raster_draw_set_extents ()
hb_bool_t | hb_raster_draw_get_extents ()
hb_bool_t | hb_raster_draw_set_glyph_extents ()
void | hb_raster_draw_clear ()
void | hb_raster_draw_reset ()
hb_draw_funcs_t * | hb_raster_draw_get_funcs ()
void | hb_raster_draw_glyph ()
hb_bool_t | hb_raster_draw_glyph_or_fail ()
hb_raster_image_t * | hb_raster_draw_render ()
void | hb_raster_draw_recycle_image ()
hb_raster_paint_t * | hb_raster_paint_create_or_fail ()
hb_raster_paint_t * | hb_raster_paint_reference ()
void | hb_raster_paint_destroy ()
hb_bool_t | hb_raster_paint_set_user_data ()
void * | hb_raster_paint_get_user_data ()
void | hb_raster_paint_set_transform ()
void | hb_raster_paint_get_transform ()
void | hb_raster_paint_set_scale_factor ()
void | hb_raster_paint_get_scale_factor ()
void | hb_raster_paint_set_extents ()
hb_bool_t | hb_raster_paint_get_extents ()
hb_bool_t | hb_raster_paint_set_glyph_extents ()
void | hb_raster_paint_set_foreground ()
hb_color_t | hb_raster_paint_get_foreground ()
void | hb_raster_paint_set_background ()
hb_color_t | hb_raster_paint_get_background ()
void | hb_raster_paint_set_palette ()
unsigned | hb_raster_paint_get_palette ()
void | hb_raster_paint_clear_custom_palette_colors ()
hb_bool_t | hb_raster_paint_set_custom_palette_color ()
hb_paint_funcs_t * | hb_raster_paint_get_funcs ()
void | hb_raster_paint_glyph ()
hb_bool_t | hb_raster_paint_glyph_or_fail ()
hb_raster_image_t * | hb_raster_paint_render ()
void | hb_raster_paint_clear ()
void | hb_raster_paint_reset ()
void | hb_raster_paint_recycle_image ()

## Types and Values

enum | hb_raster_format_t
| hb_raster_extents_t
typedef | hb_raster_image_t
typedef | hb_raster_draw_t
typedef | hb_raster_paint_t

## Includes

    #include <hb-raster.h>

## Description

Functions for rasterizing glyph outlines into pixel buffers.

hb_raster_draw_t rasterizes outline geometry and always outputs `HB_RASTER_FORMAT_A8` . Typical flow:

    hb_raster_draw_t *draw = hb_raster_draw_create_or_fail ();
    hb_raster_draw_set_scale_factor (draw, 64.f, 64.f);
    hb_raster_draw_set_transform (draw, 1.f, 0.f, 0.f, 1.f, 0.f, 0.f);
    hb_raster_draw_set_glyph_extents (draw, &glyph_extents);
    hb_raster_draw_glyph (draw, font, gid, pen_x, pen_y);
    hb_raster_image_t *mask = hb_raster_draw_render (draw);

hb_raster_paint_t renders color paint graphs and always outputs `HB_RASTER_FORMAT_BGRA32` . Typical flow:

    hb_raster_paint_t *paint = hb_raster_paint_create_or_fail ();
    hb_raster_paint_set_scale_factor (paint, 64.f, 64.f);
    hb_raster_paint_set_transform (paint, 1.f, 0.f, 0.f, 1.f, 0.f, 0.f);
    hb_raster_paint_set_foreground (paint, foreground);
    hb_glyph_extents_t glyph_extents;
    hb_font_get_glyph_extents (font, gid, &glyph_extents);
    hb_raster_paint_set_glyph_extents (paint, &glyph_extents);
    hb_raster_paint_glyph (paint, font, gid, pen_x, pen_y);
    hb_raster_image_t *img = hb_raster_paint_render (paint);

In both modes, set extents explicitly (or via glyph extents) before rendering to avoid implicit allocations and to get deterministic bounds.

## Functions

### hb_raster_image_create_or_fail ()

    hb_raster_image_t *
    hb_raster_image_create_or_fail (void);

Creates a new raster image object.

#### Returns

A newly allocated hb_raster_image_t with a reference count of 1, or `NULL` on allocation failure.

The returned image can be released with `hb_raster_image_destroy()`, or transferred for reuse with `hb_raster_draw_recycle_image()` or `hb_raster_paint_recycle_image()`.

[transfer full]

Since: 13.0.0

### hb_raster_image_reference ()

    hb_raster_image_t *
    hb_raster_image_reference (hb_raster_image_t *image);

Increases the reference count on `image` by one.

This prevents `image` from being destroyed until a matching call to `hb_raster_image_destroy()` is made.

[skip]

#### Parameters

image | a raster image |

#### Returns

The referenced hb_raster_image_t.

[transfer full]

Since: 13.0.0

### hb_raster_image_destroy ()

    void
    hb_raster_image_destroy (hb_raster_image_t *image);

Decreases the reference count on `image` by one. When the reference count reaches zero, the image and its pixel buffer are freed.

[skip]

#### Parameters

image | a raster image |

Since: 13.0.0

### hb_raster_image_set_user_data ()

    hb_bool_t
    hb_raster_image_set_user_data (hb_raster_image_t *image,
                                   hb_user_data_key_t *key,
                                   void *data,
                                   hb_destroy_func_t destroy,
                                   hb_bool_t replace);

Attaches a user-data key/data pair to the specified raster image.

[skip]

#### Parameters

image | a raster image |
key | the user-data key |
data | a pointer to the user data |
destroy | a callback to call when `data` is not needed anymore. | [nullable]
replace | whether to replace an existing data with the same key |

#### Returns

`true` if success, `false` otherwise

Since: 13.0.0

### hb_raster_image_get_user_data ()

    void *
    hb_raster_image_get_user_data (const hb_raster_image_t *image,
                                   hb_user_data_key_t *key);

Fetches the user-data associated with the specified key, attached to the specified raster image.

[skip]

#### Parameters

image | a raster image |
key | the user-data key |

#### Returns

A pointer to the user data.

[transfer none]

Since: 13.0.0

### hb_raster_image_configure ()

    hb_bool_t
    hb_raster_image_configure (hb_raster_image_t *image,
                               hb_raster_format_t format,
                               const hb_raster_extents_t *extents);

Configures `image` format and extents together, resizing backing storage at most once. This function does not clear pixel contents.

Passing `NULL` for `extents` clears extents and releases the backing allocation.

#### Parameters

image | a raster image |
format | the pixel format |
extents | desired image extents. | [nullable]

#### Returns

`true` if configuration succeeds, `false` on allocation failure

Since: 13.0.0

### hb_raster_image_clear ()

    void
    hb_raster_image_clear (hb_raster_image_t *image);

Clears `image` pixels to zero while keeping current extents and format.

#### Parameters

image | a raster image |

Since: 13.0.0

### hb_raster_image_get_buffer ()

    const uint8_t *
    hb_raster_image_get_buffer (const hb_raster_image_t *image);

Fetches the raw pixel buffer of `image` . The buffer layout is described by the extents obtained from `hb_raster_image_get_extents()` and the format from `hb_raster_image_get_format()`. Rows are stored bottom-to-top.

#### Parameters

image | a raster image |

#### Returns

The pixel buffer, or `NULL`.

[transfer none][array]

Since: 13.0.0

### hb_raster_image_get_extents ()

    void
    hb_raster_image_get_extents (const hb_raster_image_t *image,
                                 hb_raster_extents_t *extents);

Fetches the pixel-buffer extents of `image` .

#### Parameters

image | a raster image |
extents | the image extents. | [out][nullable]

Since: 13.0.0

### hb_raster_image_get_format ()

    hb_raster_format_t
    hb_raster_image_get_format (const hb_raster_image_t *image);

Fetches the pixel format of `image` .

#### Parameters

image | a raster image |

#### Returns

The hb_raster_format_t of the image

Since: 13.0.0

### hb_raster_image_deserialize_from_png_or_fail ()

    hb_bool_t
    hb_raster_image_deserialize_from_png_or_fail
                                   (hb_raster_image_t *image,
                                    hb_blob_t *png);

Replaces `image` contents by deserializing a PNG blob into a HB_RASTER_FORMAT_BGRA32 raster image.

On success, `image` extents are reset to pixel extents with origin `(0, 0)`. Rows in the resulting image buffer are stored bottom-to-top. On failure, `image` is left unchanged.

#### Parameters

image | a raster image |
png | PNG data |

#### Returns

`true` if deserialization succeeded, `false` otherwise

Since: 13.1.0

### hb_raster_image_serialize_to_png_or_fail ()

    hb_blob_t *
    hb_raster_image_serialize_to_png_or_fail
                                   (const hb_raster_image_t *image);

Serializes `image` to a PNG blob.

Currently only HB_RASTER_FORMAT_BGRA32 images are supported.

#### Parameters

image | a raster image |

#### Returns

A newly allocated PNG hb_blob_t, or `NULL` on failure.

[transfer full]

Since: 13.1.0

### hb_raster_draw_create_or_fail ()

    hb_raster_draw_t *
    hb_raster_draw_create_or_fail (void);

Creates a new rasterizer object.

#### Returns

A newly allocated hb_raster_draw_t with a reference count of 1. The initial reference count should be released with `hb_raster_draw_destroy()` when you are done using the hb_raster_draw_t, or `NULL` on allocation failure.

[transfer full]

Since: 13.0.0

### hb_raster_draw_reference ()

    hb_raster_draw_t *
    hb_raster_draw_reference (hb_raster_draw_t *draw);

Increases the reference count on `draw` by one.

This prevents `draw` from being destroyed until a matching call to `hb_raster_draw_destroy()` is made.

[skip]

#### Parameters

draw | a rasterizer |

#### Returns

The referenced hb_raster_draw_t.

[transfer full]

Since: 13.0.0

### hb_raster_draw_destroy ()

    void
    hb_raster_draw_destroy (hb_raster_draw_t *draw);

Decreases the reference count on `draw` by one. When the reference count reaches zero, the rasterizer is freed.

[skip]

#### Parameters

draw | a rasterizer |

Since: 13.0.0

### hb_raster_draw_set_user_data ()

    hb_bool_t
    hb_raster_draw_set_user_data (hb_raster_draw_t *draw,
                                  hb_user_data_key_t *key,
                                  void *data,
                                  hb_destroy_func_t destroy,
                                  hb_bool_t replace);

Attaches a user-data key/data pair to the specified rasterizer.

[skip]

#### Parameters

draw | a rasterizer |
key | the user-data key |
data | a pointer to the user data |
destroy | a callback to call when `data` is not needed anymore. | [nullable]
replace | whether to replace an existing data with the same key |

#### Returns

`true` if success, `false` otherwise

Since: 13.0.0

### hb_raster_draw_get_user_data ()

    void *
    hb_raster_draw_get_user_data (const hb_raster_draw_t *draw,
                                  hb_user_data_key_t *key);

Fetches the user-data associated with the specified key, attached to the specified rasterizer.

[skip]

#### Parameters

draw | a rasterizer |
key | the user-data key |

#### Returns

A pointer to the user data.

[transfer none]

Since: 13.0.0

### hb_raster_draw_set_transform ()

    void
    hb_raster_draw_set_transform (hb_raster_draw_t *draw,
                                  float xx,
                                  float yx,
                                  float xy,
                                  float yy,
                                  float dx,
                                  float dy);

Sets a 2×3 affine transform applied to all incoming draw coordinates before rasterization. The default is the identity.

#### Parameters

draw | a rasterizer |
xx | xx component of the transform matrix |
yx | yx component of the transform matrix |
xy | xy component of the transform matrix |
yy | yy component of the transform matrix |
dx | x translation |
dy | y translation |

Since: 13.0.0

### hb_raster_draw_set_scale_factor ()

    void
    hb_raster_draw_set_scale_factor (hb_raster_draw_t *draw,
                                     float x_scale_factor,
                                     float y_scale_factor);

Sets post-transform minification factors applied during rasterization. Factors larger than 1 shrink the output in pixels. The default is 1.

#### Parameters

draw | a rasterizer |
x_scale_factor | x-axis minification factor |
y_scale_factor | y-axis minification factor |

Since: 13.0.0

### hb_raster_draw_get_scale_factor ()

    void
    hb_raster_draw_get_scale_factor (const hb_raster_draw_t *draw,
                                     float *x_scale_factor,
                                     float *y_scale_factor);

Fetches the current post-transform minification factors.

#### Parameters

draw | a rasterizer |
x_scale_factor | x-axis minification factor. | [out][nullable]
y_scale_factor | y-axis minification factor. | [out][nullable]

Since: 13.0.0

### hb_raster_draw_get_transform ()

    void
    hb_raster_draw_get_transform (const hb_raster_draw_t *draw,
                                  float *xx,
                                  float *yx,
                                  float *xy,
                                  float *yy,
                                  float *dx,
                                  float *dy);

Fetches the current affine transform of the rasterizer.

#### Parameters

draw | a rasterizer |
xx | xx component of the transform matrix. | [out][nullable]
yx | yx component of the transform matrix. | [out][nullable]
xy | xy component of the transform matrix. | [out][nullable]
yy | yy component of the transform matrix. | [out][nullable]
dx | x translation. | [out][nullable]
dy | y translation. | [out][nullable]

Since: 13.0.0

### hb_raster_draw_set_extents ()

    void
    hb_raster_draw_set_extents (hb_raster_draw_t *draw,
                                const hb_raster_extents_t *extents);

Overrides the output image extents for the next render. When set, `hb_raster_draw_render()` uses the given extents instead of auto-computing them from the accumulated geometry.

#### Parameters

draw | a rasterizer |
extents | the desired output extents |

Since: 13.0.0

### hb_raster_draw_get_extents ()

    hb_bool_t
    hb_raster_draw_get_extents (const hb_raster_draw_t *draw,
                                hb_raster_extents_t *extents);

Gets currently configured output extents.

#### Parameters

draw | a rasterizer |
extents | where to write current extents. | [out][nullable]

#### Returns

`true` if extents are set, `false` otherwise.

Since: 13.0.0

### hb_raster_draw_set_glyph_extents ()

    hb_bool_t
    hb_raster_draw_set_glyph_extents (hb_raster_draw_t *draw,
                                      const hb_glyph_extents_t *glyph_extents);

Transforms `glyph_extents` with the rasterizer's current transform and sets the resulting pixel extents for the next render.

This is equivalent to computing a transformed bounding box in pixel space and calling `hb_raster_draw_set_extents()`.

The resulting dimensions are capped at 4096 pixels per side.

#### Parameters

draw | a rasterizer |
glyph_extents | glyph extents from `hb_font_get_glyph_extents()` |

#### Returns

`true` if transformed extents are non-empty and set; `false` otherwise.

Since: 13.0.0

### hb_raster_draw_clear ()

    void
    hb_raster_draw_clear (hb_raster_draw_t *draw);

Discards accumulated geometry and extents so `draw` can be reused for another render. User configuration (transform, scale factors) is preserved. Call `hb_raster_draw_reset()` to also reset user configuration to defaults.

#### Parameters

draw | a rasterizer |

Since: 14.2.0

### hb_raster_draw_reset ()

    void
    hb_raster_draw_reset (hb_raster_draw_t *draw);

Resets the rasterizer to its initial state, clearing all accumulated geometry, the transform, and fixed extents. The object can then be reused for a new glyph.

#### Parameters

draw | a rasterizer |

Since: 13.0.0

### hb_raster_draw_get_funcs ()

    hb_draw_funcs_t *
    hb_raster_draw_get_funcs (const hb_raster_draw_t *draw);

Fetches the hb_draw_funcs_t that feeds outline data into `draw` . Pass `draw` as the `draw_data` argument when calling the draw functions.

#### Parameters

draw | a rasterizer draw context. |

#### Returns

The rasterizer draw functions.

[transfer none]

Since: 14.2.0

### hb_raster_draw_glyph ()

    void
    hb_raster_draw_glyph (hb_raster_draw_t *draw,
                          hb_font_t *font,
                          hb_codepoint_t glyph);

Draws one glyph into `draw` using the rasterizer's current transform. Equivalent to `hb_raster_draw_glyph_or_fail()` with the return value ignored.

#### Parameters

draw | a rasterizer |
font | font to draw from |
glyph | glyph ID to draw |

Since: 14.2.0

### hb_raster_draw_glyph_or_fail ()

    hb_bool_t
    hb_raster_draw_glyph_or_fail (hb_raster_draw_t *draw,
                                  hb_font_t *font,
                                  hb_codepoint_t glyph);

Convenience to draw one glyph. Equivalent to:

    hb_font_draw_glyph_or_fail (font, glyph,
      hb_raster_draw_get_funcs (draw), draw);

#### Parameters

draw | a rasterizer |
font | font to draw from |
glyph | glyph ID to draw |

#### Returns

`true` if the glyph was drawn, `false` if the font has no outlines for `glyph` .

Since: 14.2.0

### hb_raster_draw_render ()

    hb_raster_image_t *
    hb_raster_draw_render (hb_raster_draw_t *draw);

Rasterizes the accumulated outline geometry into a new hb_raster_image_t. After rendering, the accumulated edges are cleared so the rasterizer can be reused. Output format is always `HB_RASTER_FORMAT_A8` .

#### Parameters

draw | a rasterizer |

#### Returns

A rendered hb_raster_image_t. Returns `NULL` on allocation/configuration failure. If no geometry was accumulated, returns an empty image.

[transfer full]

Since: 13.0.0

### hb_raster_draw_recycle_image ()

    void
    hb_raster_draw_recycle_image (hb_raster_draw_t *draw,
                                  hb_raster_image_t *image);

Recycles `image` for reuse by a subsequent `hb_raster_draw_render()` call, avoiding per-render memory allocation. The caller transfers ownership of `image` to `draw` and must not use it afterwards.

If `draw` already holds a recycled image, the previously recycled image is destroyed.

#### Parameters

draw | a rasterizer |
image | a raster image to recycle |

Since: 13.0.0

### hb_raster_paint_create_or_fail ()

    hb_raster_paint_t *
    hb_raster_paint_create_or_fail (void);

Creates a new color-glyph paint context.

#### Returns

A newly allocated hb_raster_paint_t, or `NULL` on allocation failure.

[transfer full]

Since: 13.0.0

### hb_raster_paint_reference ()

    hb_raster_paint_t *
    hb_raster_paint_reference (hb_raster_paint_t *paint);

Increases the reference count on `paint` by one.

[skip]

#### Parameters

paint | a paint context |

#### Returns

The referenced hb_raster_paint_t.

[transfer full]

Since: 13.0.0

### hb_raster_paint_destroy ()

    void
    hb_raster_paint_destroy (hb_raster_paint_t *paint);

Decreases the reference count on `paint` by one. When the reference count reaches zero, the paint context is freed.

[skip]

#### Parameters

paint | a paint context |

Since: 13.0.0

### hb_raster_paint_set_user_data ()

    hb_bool_t
    hb_raster_paint_set_user_data (hb_raster_paint_t *paint,
                                   hb_user_data_key_t *key,
                                   void *data,
                                   hb_destroy_func_t destroy,
                                   hb_bool_t replace);

Attaches a user-data key/data pair to the specified paint context.

[skip]

#### Parameters

paint | a paint context |
key | the user-data key |
data | a pointer to the user data |
destroy | a callback to call when `data` is not needed anymore. | [nullable]
replace | whether to replace an existing data with the same key |

#### Returns

`true` if success, `false` otherwise

Since: 13.0.0

### hb_raster_paint_get_user_data ()

    void *
    hb_raster_paint_get_user_data (const hb_raster_paint_t *paint,
                                   hb_user_data_key_t *key);

Fetches the user-data associated with the specified key, attached to the specified paint context.

[skip]

#### Parameters

paint | a paint context |
key | the user-data key |

#### Returns

A pointer to the user data.

[transfer none]

Since: 13.0.0

### hb_raster_paint_set_transform ()

    void
    hb_raster_paint_set_transform (hb_raster_paint_t *paint,
                                   float xx,
                                   float yx,
                                   float xy,
                                   float yy,
                                   float dx,
                                   float dy);

Sets the base 2×3 affine transform that maps from glyph-space coordinates to pixel-space coordinates.

#### Parameters

paint | a paint context |
xx | xx component of the transform matrix |
yx | yx component of the transform matrix |
xy | xy component of the transform matrix |
yy | yy component of the transform matrix |
dx | x translation |
dy | y translation |

Since: 13.0.0

### hb_raster_paint_get_transform ()

    void
    hb_raster_paint_get_transform (const hb_raster_paint_t *paint,
                                   float *xx,
                                   float *yx,
                                   float *xy,
                                   float *yy,
                                   float *dx,
                                   float *dy);

Gets the current base 2x3 affine transform.

#### Parameters

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

Since: 13.0.0

### hb_raster_paint_set_scale_factor ()

    void
    hb_raster_paint_set_scale_factor (hb_raster_paint_t *paint,
                                      float x_scale_factor,
                                      float y_scale_factor);

Sets post-transform minification factors applied during painting. Factors larger than 1 shrink the output in pixels. The default is 1.

#### Parameters

paint | a paint context |
x_scale_factor | x-axis minification factor |
y_scale_factor | y-axis minification factor |

Since: 13.0.0

### hb_raster_paint_get_scale_factor ()

    void
    hb_raster_paint_get_scale_factor (const hb_raster_paint_t *paint,
                                      float *x_scale_factor,
                                      float *y_scale_factor);

Fetches the current post-transform minification factors.

#### Parameters

paint | a paint context |
x_scale_factor | x-axis minification factor. | [out][nullable]
y_scale_factor | y-axis minification factor. | [out][nullable]

Since: 13.0.0

### hb_raster_paint_set_extents ()

    void
    hb_raster_paint_set_extents (hb_raster_paint_t *paint,
                                 const hb_raster_extents_t *extents);

Sets the output image extents (pixel rectangle).

Call this before `hb_font_paint_glyph()` for each render. A common pattern is:

    hb_glyph_extents_t gext;
    if (hb_font_get_glyph_extents (font, gid, &gext))
      hb_raster_paint_set_glyph_extents (paint, &gext);

#### Parameters

paint | a paint context |
extents | the desired output extents |

Since: 13.0.0

### hb_raster_paint_get_extents ()

    hb_bool_t
    hb_raster_paint_get_extents (const hb_raster_paint_t *paint,
                                 hb_raster_extents_t *extents);

Gets currently configured output extents.

#### Parameters

paint | a paint context |
extents | where to write current extents. | [out][nullable]

#### Returns

`true` if extents are set, `false` otherwise.

Since: 13.0.0

### hb_raster_paint_set_glyph_extents ()

    hb_bool_t
    hb_raster_paint_set_glyph_extents (hb_raster_paint_t *paint,
                                       const hb_glyph_extents_t *glyph_extents);

Transforms `glyph_extents` with the paint context's base transform and sets the resulting output image extents.

This is equivalent to computing a transformed bounding box in pixel space and calling `hb_raster_paint_set_extents()`.

The resulting dimensions are capped at 4096 pixels per side.

#### Parameters

paint | a paint context |
glyph_extents | glyph extents from `hb_font_get_glyph_extents()` |

#### Returns

`true` if transformed extents are non-empty and set; `false` otherwise.

Since: 13.0.0

### hb_raster_paint_set_foreground ()

    void
    hb_raster_paint_set_foreground (hb_raster_paint_t *paint,
                                    hb_color_t foreground);

Sets the foreground color used when paint callbacks request it (e.g. `is_foreground` in color stops or solid fills).

#### Parameters

paint | a paint context |
foreground | the foreground color |

Since: 13.0.0

### hb_raster_paint_get_foreground ()

    hb_color_t
    hb_raster_paint_get_foreground (const hb_raster_paint_t *paint);

Returns the foreground color previously set on `paint` , or the default opaque black if none was set.

#### Parameters

paint | a paint context |

#### Returns

the foreground color.

Since: 14.2.0

### hb_raster_paint_set_background ()

    void
    hb_raster_paint_set_background (hb_raster_paint_t *paint,
                                    hb_color_t background);

Sets the background color for `paint` . If set to a non-transparent value, the rendered image is pre-filled with this color before glyph content is composited on top. Default is transparent.

#### Parameters

paint | a paint context |
background | the background color |

Since: 14.2.0

### hb_raster_paint_get_background ()

    hb_color_t
    hb_raster_paint_get_background (const hb_raster_paint_t *paint);

Returns the background color previously set on `paint` , or transparent if none was set.

#### Parameters

paint | a paint context |

#### Returns

the background color.

Since: 14.2.0

### hb_raster_paint_set_palette ()

    void
    hb_raster_paint_set_palette (hb_raster_paint_t *paint,
                                 unsigned  palette);

Selects which font palette is used when paint callbacks look up indexed colors. Default is palette 0.

#### Parameters

paint | a paint context |
palette | palette index |

Since: 14.2.0

### hb_raster_paint_get_palette ()

    unsigned
    hb_raster_paint_get_palette (const hb_raster_paint_t *paint);

Returns the palette index previously set on `paint` , or 0 if none was set.

#### Parameters

paint | a paint context |

#### Returns

the palette index.

Since: 14.2.0

### hb_raster_paint_clear_custom_palette_colors ()

    void
    hb_raster_paint_clear_custom_palette_colors
                                   (hb_raster_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_raster_paint_set_custom_palette_color ()

    hb_bool_t
    hb_raster_paint_set_custom_palette_color
                                   (hb_raster_paint_t *paint,
                                    unsigned int 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.

#### Parameters

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

#### Returns

`true` if the override was set; `false` on allocation failure.

Since: 13.0.0

### hb_raster_paint_get_funcs ()

    hb_paint_funcs_t *
    hb_raster_paint_get_funcs (const hb_raster_paint_t *paint);

Fetches the hb_paint_funcs_t that renders color glyphs into `paint` . Pass `paint` as the `paint_data` argument when calling `hb_font_paint_glyph()`.

#### Parameters

paint | a rasterizer paint context. |

#### Returns

The rasterizer paint functions.

[transfer none]

Since: 14.2.0

### hb_raster_paint_glyph ()

    void
    hb_raster_paint_glyph (hb_raster_paint_t *paint,
                           hb_font_t *font,
                           hb_codepoint_t glyph);

Paints one glyph into `paint` . Unlike `hb_raster_paint_glyph_or_fail()`, glyphs with no color paint data fall back to a synthesized foreground-colored outline, so any glyph with an outline or bitmap image produces output.

#### Parameters

paint | a paint context |
font | font to paint from |
glyph | glyph ID to paint |

Since: 14.2.0

### hb_raster_paint_glyph_or_fail ()

    hb_bool_t
    hb_raster_paint_glyph_or_fail (hb_raster_paint_t *paint,
                                   hb_font_t *font,
                                   hb_codepoint_t glyph);

Convenience to paint one color glyph. Equivalent to:

    hb_font_paint_glyph_or_fail (font, glyph,
      hb_raster_paint_get_funcs (paint), paint,
      palette, foreground);

#### Parameters

paint | a paint context |
font | font to paint from |
glyph | glyph ID to paint |

#### Returns

`true` if painting succeeded, `false` otherwise.

Since: 14.2.0

### hb_raster_paint_render ()

    hb_raster_image_t *
    hb_raster_paint_render (hb_raster_paint_t *paint);

Extracts the rendered image after `hb_font_paint_glyph()` has completed. The paint context's surface stack is consumed and the result returned as a new hb_raster_image_t. Output format is always `HB_RASTER_FORMAT_BGRA32` .

Call `hb_font_paint_glyph()` before calling this function. `hb_raster_paint_set_extents()` or `hb_raster_paint_set_glyph_extents()` must be called before painting; otherwise this function returns `NULL`. Internal drawing state is cleared here so the same object can be reused without client-side clearing.

#### Parameters

paint | a paint context |

#### Returns

A rendered hb_raster_image_t. Returns `NULL` if extents were not set or if allocation/configuration fails. If extents were set but nothing was painted, returns an empty image.

[transfer full]

Since: 13.0.0

### hb_raster_paint_clear ()

    void
    hb_raster_paint_clear (hb_raster_paint_t *paint);

Discards accumulated paint output so `paint` can be reused for another render. User configuration (base transform, scale factors, foreground, custom palette colors) is preserved. Call `hb_raster_paint_reset()` to also reset user configuration to defaults.

#### Parameters

paint | a paint context |

Since: 14.2.0

### hb_raster_paint_reset ()

    void
    hb_raster_paint_reset (hb_raster_paint_t *paint);

Resets the paint context to its initial state, clearing all configuration while preserving internal image caches.

#### Parameters

paint | a paint context |

Since: 13.0.0

### hb_raster_paint_recycle_image ()

    void
    hb_raster_paint_recycle_image (hb_raster_paint_t *paint,
                                   hb_raster_image_t *image);

Recycles `image` for reuse by subsequent render calls. The caller transfers ownership of `image` to `paint` .

#### Parameters

paint | a paint context |
image | a raster image to recycle |

Since: 13.0.0

## Types and Values

### enum hb_raster_format_t

Pixel format for raster images.

#### Members

HB_RASTER_FORMAT_A8 | 8-bit alpha-only coverage |
HB_RASTER_FORMAT_BGRA32 | 32-bit BGRA color |

Since: 13.0.0

### hb_raster_extents_t

    typedef struct {
      int      x_origin, y_origin;
      unsigned int width, height;
      unsigned int stride;
    } hb_raster_extents_t;

Pixel-buffer extents for raster operations.

#### Members

int `x_origin`; | X coordinate of the left edge of the image in glyph space |
int `y_origin`; | Y coordinate of the bottom edge of the image in glyph space |
unsigned int `width`; | Width in pixels |
unsigned int `height`; | Height in pixels |
unsigned int `stride`; | Bytes per row; 0 means auto-calculate on input, filled on output |

Since: 13.0.0

### hb_raster_image_t

    typedef struct hb_raster_image_t hb_raster_image_t;

An opaque raster image object holding a pixel buffer produced by `hb_raster_draw_render()`. Use `hb_raster_image_get_buffer()` and `hb_raster_image_get_extents()` to access the pixels.

Since: 13.0.0

### hb_raster_draw_t

    typedef struct hb_raster_draw_t hb_raster_draw_t;

An opaque outline rasterizer object. Accumulates glyph outlines via hb_draw_funcs_t callbacks obtained from `hb_raster_draw_get_funcs()`, then produces an hb_raster_image_t with `hb_raster_draw_render()`.

Since: 13.0.0

### hb_raster_paint_t

    typedef struct hb_raster_paint_t hb_raster_paint_t;

An opaque color-glyph paint context. Implements hb_paint_funcs_t callbacks that render COLRv0/v1 color glyphs into a BGRA32 hb_raster_image_t.

Since: 13.0.0