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_glyph_extents_t glyph_extents;
    hb_font_get_glyph_extents (font, gid, &glyph_extents);
    hb_raster_draw_set_glyph_extents (draw, &glyph_extents);
    hb_raster_draw_glyph (draw, font, gid);
    hb_raster_image_t *mask = hb_raster_draw_render (draw);
    hb_raster_extents_t image_extents;
    hb_raster_image_get_extents (mask, &image_extents);

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);
    hb_raster_image_t *img = hb_raster_paint_render (paint);
    hb_raster_extents_t image_extents;
    hb_raster_image_get_extents (img, &image_extents);

In both modes, set extents explicitly (or via glyph extents) before rendering to avoid implicit allocations and to get deterministic bounds. When caching individual glyph images for later composition, position each image using the `x_origin` and `y_origin` members returned by `hb_raster_image_get_extents()`. These are the pixel-space left and bottom edges after raster-bound rounding; do not reconstruct them from glyph bearings and image dimensions.

## 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