hb-paint: HarfBuzz Manual

hb-paint

hb-paint — Glyph painting

Functions

hb_paint_funcs_t *	hb_paint_funcs_create ()
hb_paint_funcs_t *	hb_paint_funcs_get_empty ()
hb_paint_funcs_t *	hb_paint_funcs_reference ()
void	hb_paint_funcs_destroy ()
hb_bool_t	hb_paint_funcs_set_user_data ()
void *	hb_paint_funcs_get_user_data ()
void	hb_paint_funcs_make_immutable ()
hb_bool_t	hb_paint_funcs_is_immutable ()
void	(*hb_paint_push_transform_func_t) ()
void	hb_paint_funcs_set_push_transform_func ()
void	(*hb_paint_pop_transform_func_t) ()
void	hb_paint_funcs_set_pop_transform_func ()
hb_bool_t	(*hb_paint_color_glyph_func_t) ()
void	hb_paint_funcs_set_color_glyph_func ()
void	(*hb_paint_push_clip_glyph_func_t) ()
void	hb_paint_funcs_set_push_clip_glyph_func ()
void	(*hb_paint_push_clip_rectangle_func_t) ()
void	hb_paint_funcs_set_push_clip_rectangle_func ()
void	(*hb_paint_pop_clip_func_t) ()
void	hb_paint_funcs_set_pop_clip_func ()
void	(*hb_paint_color_func_t) ()
void	hb_paint_funcs_set_color_func ()
hb_bool_t	(*hb_paint_image_func_t) ()
void	hb_paint_funcs_set_image_func ()
unsigned int	(*hb_color_line_get_color_stops_func_t) ()
unsigned int	hb_color_line_get_color_stops ()
hb_paint_extend_t	(*hb_color_line_get_extend_func_t) ()
hb_paint_extend_t	hb_color_line_get_extend ()
void	(*hb_paint_linear_gradient_func_t) ()
void	hb_paint_funcs_set_linear_gradient_func ()
void	(*hb_paint_radial_gradient_func_t) ()
void	hb_paint_funcs_set_radial_gradient_func ()
void	(*hb_paint_sweep_gradient_func_t) ()
void	hb_paint_funcs_set_sweep_gradient_func ()
void	(*hb_paint_push_group_func_t) ()
void	hb_paint_funcs_set_push_group_func ()
void	(*hb_paint_pop_group_func_t) ()
void	hb_paint_funcs_set_pop_group_func ()
hb_bool_t	(*hb_paint_custom_palette_color_func_t) ()
void	hb_paint_funcs_set_custom_palette_color_func ()
void	hb_paint_push_transform ()
void	hb_paint_pop_transform ()
hb_bool_t	hb_paint_color_glyph ()
void	hb_paint_push_clip_glyph ()
void	hb_paint_push_clip_rectangle ()
void	hb_paint_pop_clip ()
void	hb_paint_color ()
void	hb_paint_image ()
void	hb_paint_linear_gradient ()
void	hb_paint_radial_gradient ()
void	hb_paint_sweep_gradient ()
void	hb_paint_push_group ()
void	hb_paint_pop_group ()
hb_bool_t	hb_paint_custom_palette_color ()

Types and Values

typedef	hb_paint_funcs_t
#define	HB_PAINT_IMAGE_FORMAT_PNG
#define	HB_PAINT_IMAGE_FORMAT_SVG
#define	HB_PAINT_IMAGE_FORMAT_BGRA
typedef	hb_color_line_t
	hb_color_stop_t
enum	hb_paint_extend_t
enum	hb_paint_composite_mode_t

Includes

#include <hb.h>

Description

Functions for painting glyphs.

The main purpose of these functions is to paint (extract) color glyph layers from the COLRv1 table, but the API works for drawing ordinary outlines and images as well.

The hb_paint_funcs_t struct can be used with hb_font_paint_glyph().

Functions

hb_paint_funcs_create ()

hb_paint_funcs_t *
hb_paint_funcs_create (void);

Creates a new hb_paint_funcs_t structure of paint functions.

The initial reference count of 1 should be released with hb_paint_funcs_destroy() when you are done using the hb_paint_funcs_t. This function never returns NULL. If memory cannot be allocated, a special singleton hb_paint_funcs_t object will be returned.

Returns value: (transfer full): the paint-functions structure

Since: 7.0.0

hb_paint_funcs_get_empty ()

hb_paint_funcs_t *
hb_paint_funcs_get_empty (void);

Fetches the singleton empty paint-functions structure.

Returns

The empty paint-functions structure.

[transfer full]

Since: 7.0.0

hb_paint_funcs_reference ()

hb_paint_funcs_t *
hb_paint_funcs_reference (hb_paint_funcs_t *funcs);

Increases the reference count on a paint-functions structure.

This prevents funcs from being destroyed until a matching call to hb_paint_funcs_destroy() is made.

[skip]

Parameters

funcs

The paint-functions structure

Returns

The paint-functions structure

Since: 7.0.0

hb_paint_funcs_destroy ()

void
hb_paint_funcs_destroy (hb_paint_funcs_t *funcs);

Decreases the reference count on a paint-functions structure.

When the reference count reaches zero, the structure is destroyed, freeing all memory.

[skip]

Parameters

funcs

The paint-functions structure

Since: 7.0.0

hb_paint_funcs_set_user_data ()

hb_bool_t
hb_paint_funcs_set_user_data (hb_paint_funcs_t *funcs,
                              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-functions structure.

[skip]

Parameters

funcs	The paint-functions structure
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: 7.0.0

hb_paint_funcs_get_user_data ()

void *
hb_paint_funcs_get_user_data (const hb_paint_funcs_t *funcs,
                              hb_user_data_key_t *key);

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

[skip]

Parameters

funcs	The paint-functions structure
key	The user-data key to query

Returns

A pointer to the user data.

[transfer none]

Since: 7.0.0

hb_paint_funcs_make_immutable ()

void
hb_paint_funcs_make_immutable (hb_paint_funcs_t *funcs);

Makes a paint-functions structure immutable.

After this call, all attempts to set one of the callbacks on funcs will fail.

Parameters

funcs

The paint-functions structure

Since: 7.0.0

hb_paint_funcs_is_immutable ()

hb_bool_t
hb_paint_funcs_is_immutable (hb_paint_funcs_t *funcs);

Tests whether a paint-functions structure is immutable.

Parameters

funcs

The paint-functions structure

Returns

true if funcs is immutable, false otherwise

Since: 7.0.0

hb_paint_push_transform_func_t ()

void
(*hb_paint_push_transform_func_t) (hb_paint_funcs_t *funcs,
                                   void *paint_data,
                                   float xx,
                                   float yx,
                                   float xy,
                                   float yy,
                                   float dx,
                                   float dy,
                                   void *user_data);

A virtual method for the hb_paint_funcs_t to apply a transform to subsequent paint calls.

This transform is applied after the current transform, and remains in effect until a matching call to the hb_paint_funcs_pop_transform_func_t vfunc.

Parameters

funcs	paint functions object
paint_data	The data accompanying the paint functions in `hb_font_paint_glyph()`
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	dx component of the transform matrix
dy	dy component of the transform matrix
user_data	User data pointer passed to `hb_paint_funcs_set_push_transform_func()`

Since: 7.0.0

hb_paint_funcs_set_push_transform_func ()

void
hb_paint_funcs_set_push_transform_func
                               (hb_paint_funcs_t *funcs,
                                hb_paint_push_transform_func_t func,
                                void *user_data,
                                hb_destroy_func_t destroy);

Sets the push-transform callback on the paint functions struct.

Parameters

funcs	A paint functions struct
func	The push-transform callback.	[closure user_data][destroy destroy][scope notified]
user_data	Data to pass to `func`
destroy	Function to call when `user_data` is no longer needed.	[nullable]

Since: 7.0.0

hb_paint_pop_transform_func_t ()

void
(*hb_paint_pop_transform_func_t) (hb_paint_funcs_t *funcs,
                                  void *paint_data,
                                  void *user_data);

A virtual method for the hb_paint_funcs_t to undo the effect of a prior call to the hb_paint_funcs_push_transform_func_t vfunc.

Parameters

funcs	paint functions object
paint_data	The data accompanying the paint functions in `hb_font_paint_glyph()`
user_data	User data pointer passed to `hb_paint_funcs_set_pop_transform_func()`

Since: 7.0.0

hb_paint_funcs_set_pop_transform_func ()

void
hb_paint_funcs_set_pop_transform_func (hb_paint_funcs_t *funcs,
                                       hb_paint_pop_transform_func_t func,
                                       void *user_data,
                                       hb_destroy_func_t destroy);

Sets the pop-transform callback on the paint functions struct.

Parameters

funcs	A paint functions struct
func	The pop-transform callback.	[closure user_data][destroy destroy][scope notified]
user_data	Data to pass to `func`
destroy	Function to call when `user_data` is no longer needed.	[nullable]

Since: 7.0.0

hb_paint_color_glyph_func_t ()

hb_bool_t
(*hb_paint_color_glyph_func_t) (hb_paint_funcs_t *funcs,
                                void *paint_data,
                                hb_codepoint_t glyph,
                                hb_font_t *font,
                                void *user_data);

A virtual method for the hb_paint_funcs_t to render a color glyph by glyph index.

Parameters

funcs	paint functions object
paint_data	The data accompanying the paint functions in `hb_font_paint_glyph()`
glyph	the glyph ID
font	the font
user_data	User data pointer passed to `hb_paint_funcs_set_color_glyph_func()`

Returns

true if the glyph was painted, false otherwise.

Since: 8.2.0

hb_paint_funcs_set_color_glyph_func ()

void
hb_paint_funcs_set_color_glyph_func (hb_paint_funcs_t *funcs,
                                     hb_paint_color_glyph_func_t func,
                                     void *user_data,
                                     hb_destroy_func_t destroy);

Sets the color-glyph callback on the paint functions struct.

Parameters

funcs	A paint functions struct
func	The color-glyph callback.	[closure user_data][destroy destroy][scope notified]
user_data	Data to pass to `func`
destroy	Function to call when `user_data` is no longer needed.	[nullable]

Since: 8.2.0

hb_paint_push_clip_glyph_func_t ()

void
(*hb_paint_push_clip_glyph_func_t) (hb_paint_funcs_t *funcs,
                                    void *paint_data,
                                    hb_codepoint_t glyph,
                                    hb_font_t *font,
                                    void *user_data);

A virtual method for the hb_paint_funcs_t to clip subsequent paint calls to the outline of a glyph.

The coordinates of the glyph outline are interpreted according to the current transform.

This clip is applied in addition to the current clip, and remains in effect until a matching call to the hb_paint_funcs_pop_clip_func_t vfunc.

Parameters

funcs	paint functions object
paint_data	The data accompanying the paint functions in `hb_font_paint_glyph()`
glyph	the glyph ID
font	the font
user_data	User data pointer passed to `hb_paint_funcs_set_push_clip_glyph_func()`

Since: 7.0.0

hb_paint_funcs_set_push_clip_glyph_func ()

void
hb_paint_funcs_set_push_clip_glyph_func
                               (hb_paint_funcs_t *funcs,
                                hb_paint_push_clip_glyph_func_t func,
                                void *user_data,
                                hb_destroy_func_t destroy);

Sets the push-clip-glyph callback on the paint functions struct.

Parameters

funcs	A paint functions struct
func	The push-clip-glyph callback.	[closure user_data][destroy destroy][scope notified]
user_data	Data to pass to `func`
destroy	Function to call when `user_data` is no longer needed.	[nullable]

Since: 7.0.0

hb_paint_push_clip_rectangle_func_t ()

void
(*hb_paint_push_clip_rectangle_func_t)
                               (hb_paint_funcs_t *funcs,
                                void *paint_data,
                                float xmin,
                                float ymin,
                                float xmax,
                                float ymax,
                                void *user_data);

A virtual method for the hb_paint_funcs_t to clip subsequent paint calls to a rectangle.

The coordinates of the rectangle are interpreted according to the current transform.

This clip is applied in addition to the current clip, and remains in effect until a matching call to the hb_paint_funcs_pop_clip_func_t vfunc.

Parameters

funcs	paint functions object
paint_data	The data accompanying the paint functions in `hb_font_paint_glyph()`
xmin	min X for the rectangle
ymin	min Y for the rectangle
xmax	max X for the rectangle
ymax	max Y for the rectangle
user_data	User data pointer passed to `hb_paint_funcs_set_push_clip_rectangle_func()`

Since: 7.0.0

hb_paint_funcs_set_push_clip_rectangle_func ()

void
hb_paint_funcs_set_push_clip_rectangle_func
                               (hb_paint_funcs_t *funcs,
                                hb_paint_push_clip_rectangle_func_t func,
                                void *user_data,
                                hb_destroy_func_t destroy);

Sets the push-clip-rect callback on the paint functions struct.

Parameters

funcs	A paint functions struct
func	The push-clip-rectangle callback.	[closure user_data][destroy destroy][scope notified]
user_data	Data to pass to `func`
destroy	Function to call when `user_data` is no longer needed.	[nullable]

Since: 7.0.0

hb_paint_pop_clip_func_t ()

void
(*hb_paint_pop_clip_func_t) (hb_paint_funcs_t *funcs,
                             void *paint_data,
                             void *user_data);

A virtual method for the hb_paint_funcs_t to undo the effect of a prior call to the hb_paint_funcs_push_clip_glyph_func_t or hb_paint_funcs_push_clip_rectangle_func_t vfuncs.

Parameters

funcs	paint functions object
paint_data	The data accompanying the paint functions in `hb_font_paint_glyph()`
user_data	User data pointer passed to `hb_paint_funcs_set_pop_clip_func()`

Since: 7.0.0

hb_paint_funcs_set_pop_clip_func ()

void
hb_paint_funcs_set_pop_clip_func (hb_paint_funcs_t *funcs,
                                  hb_paint_pop_clip_func_t func,
                                  void *user_data,
                                  hb_destroy_func_t destroy);

Sets the pop-clip callback on the paint functions struct.

Parameters

funcs	A paint functions struct
func	The pop-clip callback.	[closure user_data][destroy destroy][scope notified]
user_data	Data to pass to `func`
destroy	Function to call when `user_data` is no longer needed.	[nullable]

Since: 7.0.0

hb_paint_color_func_t ()

void
(*hb_paint_color_func_t) (hb_paint_funcs_t *funcs,
                          void *paint_data,
                          hb_bool_t is_foreground,
                          hb_color_t color,
                          void *user_data);

A virtual method for the hb_paint_funcs_t to paint a color everywhere within the current clip.

Parameters

funcs	paint functions object
paint_data	The data accompanying the paint functions in `hb_font_paint_glyph()`
is_foreground	whether the color is the foreground
color	The color to use, unpremultiplied
user_data	User data pointer passed to `hb_paint_funcs_set_color_func()`

Since: 7.0.0

hb_paint_funcs_set_color_func ()

void
hb_paint_funcs_set_color_func (hb_paint_funcs_t *funcs,
                               hb_paint_color_func_t func,
                               void *user_data,
                               hb_destroy_func_t destroy);

Sets the paint-color callback on the paint functions struct.

Parameters

funcs	A paint functions struct
func	The paint-color callback.	[closure user_data][destroy destroy][scope notified]
user_data	Data to pass to `func`
destroy	Function to call when `user_data` is no longer needed.	[nullable]

Since: 7.0.0

hb_paint_image_func_t ()

hb_bool_t
(*hb_paint_image_func_t) (hb_paint_funcs_t *funcs,
                          void *paint_data,
                          hb_blob_t *image,
                          unsigned int width,
                          unsigned int height,
                          hb_tag_t format,
                          float slant,
                          hb_glyph_extents_t *extents,
                          void *user_data);

A virtual method for the hb_paint_funcs_t to paint a glyph image.

This method is called for glyphs with image blobs in the CBDT, sbix or SVG tables. The format identifies the kind of data that is contained in image . Possible values include HB_PAINT_IMAGE_FORMAT_PNG, HB_PAINT_IMAGE_FORMAT_SVG and HB_PAINT_IMAGE_FORMAT_BGRA.

The image dimensions and glyph extents are provided if available, and should be used to size and position the image.

Parameters

funcs	paint functions object
paint_data	The data accompanying the paint functions in `hb_font_paint_glyph()`
image	the image data
width	width of the raster image in pixels, or 0
height	height of the raster image in pixels, or 0
format	the image format as a tag
slant	the synthetic slant ratio to be applied to the image during rendering
extents	glyph extents for desired rendering.	[nullable]
user_data	User data pointer passed to `hb_paint_funcs_set_image_func()`

Returns

Whether the operation was successful.

Since: 7.0.0

hb_paint_funcs_set_image_func ()

void
hb_paint_funcs_set_image_func (hb_paint_funcs_t *funcs,
                               hb_paint_image_func_t func,
                               void *user_data,
                               hb_destroy_func_t destroy);

Sets the paint-image callback on the paint functions struct.

Parameters

funcs	A paint functions struct
func	The paint-image callback.	[closure user_data][destroy destroy][scope notified]
user_data	Data to pass to `func`
destroy	Function to call when `user_data` is no longer needed.	[nullable]

Since: 7.0.0

hb_color_line_get_color_stops_func_t ()

unsigned int
(*hb_color_line_get_color_stops_func_t)
                               (hb_color_line_t *color_line,
                                void *color_line_data,
                                unsigned int start,
                                unsigned int *count,
                                hb_color_stop_t *color_stops,
                                void *user_data);

A virtual method for the hb_color_line_t to fetch color stops.

Parameters

color_line	a hb_color_line_t object
color_line_data	the data accompanying `color_line`
start	the index of the first color stop to return
count	Input = the maximum number of feature tags to return; Output = the actual number of feature tags returned (may be zero).	[inout][optional]
color_stops	Array of hb_color_stop_t to populate.	[out][array length=count][optional]
user_data	the data accompanying this method

Returns

the total number of color stops in color_line

Since: 7.0.0

hb_color_line_get_color_stops ()

unsigned int
hb_color_line_get_color_stops (hb_color_line_t *color_line,
                               unsigned int start,
                               unsigned int *count,
                               hb_color_stop_t *color_stops);

Fetches a list of color stops from the given color line object.

Note that due to variations being applied, the returned color stops may be out of order. It is the callers responsibility to ensure that color stops are sorted by their offset before they are used.

Parameters

color_line	a hb_color_line_t object
start	the index of the first color stop to return
count	Input = the maximum number of feature tags to return; Output = the actual number of feature tags returned (may be zero).	[inout][optional]
color_stops	Array of hb_color_stop_t to populate.	[out][array length=count][optional]

Returns

the total number of color stops in color_line

Since: 7.0.0

hb_color_line_get_extend_func_t ()

hb_paint_extend_t
(*hb_color_line_get_extend_func_t) (hb_color_line_t *color_line,
                                    void *color_line_data,
                                    void *user_data);

A virtual method for the hb_color_line_t to fetches the extend mode.

Parameters

color_line	a hb_color_line_t object
color_line_data	the data accompanying `color_line`
user_data	the data accompanying this method

Returns

the extend mode of color_line

Since: 7.0.0

hb_color_line_get_extend ()

hb_paint_extend_t
hb_color_line_get_extend (hb_color_line_t *color_line);

Fetches the extend mode of the color line object.

Parameters

color_line

a hb_color_line_t object

Returns

the extend mode of color_line

Since: 7.0.0

hb_paint_linear_gradient_func_t ()

void
(*hb_paint_linear_gradient_func_t) (hb_paint_funcs_t *funcs,
                                    void *paint_data,
                                    hb_color_line_t *color_line,
                                    float x0,
                                    float y0,
                                    float x1,
                                    float y1,
                                    float x2,
                                    float y2,
                                    void *user_data);

A virtual method for the hb_paint_funcs_t to paint a linear gradient everywhere within the current clip.

The color_line object contains information about the colors of the gradients. It is only valid for the duration of the callback, you cannot keep it around.

The coordinates of the points are interpreted according to the current transform.

See the OpenType spec COLR section for details on how the points define the direction of the gradient, and how to interpret the color_line .

Parameters

funcs	paint functions object
paint_data	The data accompanying the paint functions in `hb_font_paint_glyph()`
color_line	Color information for the gradient
x0	X coordinate of the first point
y0	Y coordinate of the first point
x1	X coordinate of the second point
y1	Y coordinate of the second point
x2	X coordinate of the third point
y2	Y coordinate of the third point
user_data	User data pointer passed to `hb_paint_funcs_set_linear_gradient_func()`

Since: 7.0.0

hb_paint_funcs_set_linear_gradient_func ()

void
hb_paint_funcs_set_linear_gradient_func
                               (hb_paint_funcs_t *funcs,
                                hb_paint_linear_gradient_func_t func,
                                void *user_data,
                                hb_destroy_func_t destroy);

Sets the linear-gradient callback on the paint functions struct.

Parameters

funcs	A paint functions struct
func	The linear-gradient callback.	[closure user_data][destroy destroy][scope notified]
user_data	Data to pass to `func`
destroy	Function to call when `user_data` is no longer needed.	[nullable]

Since: 7.0.0

hb_paint_radial_gradient_func_t ()

void
(*hb_paint_radial_gradient_func_t) (hb_paint_funcs_t *funcs,
                                    void *paint_data,
                                    hb_color_line_t *color_line,
                                    float x0,
                                    float y0,
                                    float r0,
                                    float x1,
                                    float y1,
                                    float r1,
                                    void *user_data);

A virtual method for the hb_paint_funcs_t to paint a radial gradient everywhere within the current clip.

The color_line object contains information about the colors of the gradients. It is only valid for the duration of the callback, you cannot keep it around.

The coordinates of the points are interpreted according to the current transform.

See the OpenType spec COLR section for details on how the points define the direction of the gradient, and how to interpret the color_line .

Parameters

funcs	paint functions object
paint_data	The data accompanying the paint functions in `hb_font_paint_glyph()`
color_line	Color information for the gradient
x0	X coordinate of the first circle's center
y0	Y coordinate of the first circle's center
r0	radius of the first circle
x1	X coordinate of the second circle's center
y1	Y coordinate of the second circle's center
r1	radius of the second circle
user_data	User data pointer passed to `hb_paint_funcs_set_radial_gradient_func()`

Since: 7.0.0

hb_paint_funcs_set_radial_gradient_func ()

void
hb_paint_funcs_set_radial_gradient_func
                               (hb_paint_funcs_t *funcs,
                                hb_paint_radial_gradient_func_t func,
                                void *user_data,
                                hb_destroy_func_t destroy);

Sets the radial-gradient callback on the paint functions struct.

Parameters

funcs	A paint functions struct
func	The radial-gradient callback.	[closure user_data][destroy destroy][scope notified]
user_data	Data to pass to `func`
destroy	Function to call when `user_data` is no longer needed.	[nullable]

Since: 7.0.0

hb_paint_sweep_gradient_func_t ()

void
(*hb_paint_sweep_gradient_func_t) (hb_paint_funcs_t *funcs,
                                   void *paint_data,
                                   hb_color_line_t *color_line,
                                   float x0,
                                   float y0,
                                   float start_angle,
                                   float end_angle,
                                   void *user_data);

A virtual method for the hb_paint_funcs_t to paint a sweep gradient everywhere within the current clip.

The color_line object contains information about the colors of the gradients. It is only valid for the duration of the callback, you cannot keep it around.

The coordinates of the points are interpreted according to the current transform.

See the OpenType spec COLR section for details on how the points define the direction of the gradient, and how to interpret the color_line .

Parameters

funcs	paint functions object
paint_data	The data accompanying the paint functions in `hb_font_paint_glyph()`
color_line	Color information for the gradient
x0	X coordinate of the circle's center
y0	Y coordinate of the circle's center
start_angle	the start angle, in radians
end_angle	the end angle, in radians
user_data	User data pointer passed to `hb_paint_funcs_set_sweep_gradient_func()`

Since: 7.0.0

hb_paint_funcs_set_sweep_gradient_func ()

void
hb_paint_funcs_set_sweep_gradient_func
                               (hb_paint_funcs_t *funcs,
                                hb_paint_sweep_gradient_func_t func,
                                void *user_data,
                                hb_destroy_func_t destroy);

Sets the sweep-gradient callback on the paint functions struct.

Parameters

funcs	A paint functions struct
func	The sweep-gradient callback.	[closure user_data][destroy destroy][scope notified]
user_data	Data to pass to `func`
destroy	Function to call when `user_data` is no longer needed.	[nullable]

Since: 7.0.0

hb_paint_push_group_func_t ()

void
(*hb_paint_push_group_func_t) (hb_paint_funcs_t *funcs,
                               void *paint_data,
                               void *user_data);

A virtual method for the hb_paint_funcs_t to use an intermediate surface for subsequent paint calls.

The drawing will be redirected to an intermediate surface until a matching call to the hb_paint_funcs_pop_group_func_t vfunc.

Parameters

funcs	paint functions object
paint_data	The data accompanying the paint functions in `hb_font_paint_glyph()`
user_data	User data pointer passed to `hb_paint_funcs_set_push_group_func()`

Since: 7.0.0

hb_paint_funcs_set_push_group_func ()

void
hb_paint_funcs_set_push_group_func (hb_paint_funcs_t *funcs,
                                    hb_paint_push_group_func_t func,
                                    void *user_data,
                                    hb_destroy_func_t destroy);

Sets the push-group callback on the paint functions struct.

Parameters

funcs	A paint functions struct
func	The push-group callback.	[closure user_data][destroy destroy][scope notified]
user_data	Data to pass to `func`
destroy	Function to call when `user_data` is no longer needed.	[nullable]

Since: 7.0.0

hb_paint_pop_group_func_t ()

void
(*hb_paint_pop_group_func_t) (hb_paint_funcs_t *funcs,
                              void *paint_data,
                              hb_paint_composite_mode_t mode,
                              void *user_data);

A virtual method for the hb_paint_funcs_t to undo the effect of a prior call to the hb_paint_funcs_push_group_func_t vfunc.

This call stops the redirection to the intermediate surface, and then composites it on the previous surface, using the compositing mode passed to this call.

Parameters

funcs	paint functions object
paint_data	The data accompanying the paint functions in `hb_font_paint_glyph()`
mode	the compositing mode to use
user_data	User data pointer passed to `hb_paint_funcs_set_pop_group_func()`

Since: 7.0.0

hb_paint_funcs_set_pop_group_func ()

void
hb_paint_funcs_set_pop_group_func (hb_paint_funcs_t *funcs,
                                   hb_paint_pop_group_func_t func,
                                   void *user_data,
                                   hb_destroy_func_t destroy);

Sets the pop-group callback on the paint functions struct.

Parameters

funcs	A paint functions struct
func	The pop-group callback.	[closure user_data][destroy destroy][scope notified]
user_data	Data to pass to `func`
destroy	Function to call when `user_data` is no longer needed.	[nullable]

Since: 7.0.0

hb_paint_custom_palette_color_func_t ()

hb_bool_t
(*hb_paint_custom_palette_color_func_t)
                               (hb_paint_funcs_t *funcs,
                                void *paint_data,
                                unsigned int color_index,
                                hb_color_t *color,
                                void *user_data);

A virtual method for the hb_paint_funcs_t to fetch a color from the custom color palette.

Custom palette colors override the colors from the fonts selected color palette. It is not necessary to override all palette entries; for entries that should be taken from the font palette, return false.

This function might get called multiple times, but the custom palette is expected to remain unchanged for duration of a hb_font_paint_glyph() call.

Parameters

funcs	paint functions object
paint_data	The data accompanying the paint functions in `hb_font_paint_glyph()`
color_index	the color index
color	fetched color.	[out]
user_data	User data pointer passed to `hb_paint_funcs_set_pop_group_func()`

Returns

true if found, false otherwise

Since: 7.0.0

hb_paint_funcs_set_custom_palette_color_func ()

void
hb_paint_funcs_set_custom_palette_color_func
                               (hb_paint_funcs_t *funcs,
                                hb_paint_custom_palette_color_func_t func,
                                void *user_data,
                                hb_destroy_func_t destroy);

Sets the custom-palette-color callback on the paint functions struct.

Parameters

funcs	A paint functions struct
func	The custom-palette-color callback.	[closure user_data][destroy destroy][scope notified]
user_data	Data to pass to `func`
destroy	Function to call when `user_data` is no longer needed.	[nullable]

Since: 7.0.0

hb_paint_push_transform ()

void
hb_paint_push_transform (hb_paint_funcs_t *funcs,
                         void *paint_data,
                         float xx,
                         float yx,
                         float xy,
                         float yy,
                         float dx,
                         float dy);

Perform a "push-transform" paint operation.

Parameters

funcs	paint functions
paint_data	associated data passed by the caller
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	dx component of the transform matrix
dy	dy component of the transform matrix

Since: 7.0.0

hb_paint_pop_transform ()

void
hb_paint_pop_transform (hb_paint_funcs_t *funcs,
                        void *paint_data);

Perform a "pop-transform" paint operation.

Parameters

funcs	paint functions
paint_data	associated data passed by the caller

Since: 7.0.0

hb_paint_color_glyph ()

hb_bool_t
hb_paint_color_glyph (hb_paint_funcs_t *funcs,
                      void *paint_data,
                      hb_codepoint_t glyph,
                      hb_font_t *font);

Perform a "color-glyph" paint operation.

Parameters

funcs	paint functions
paint_data	associated data passed by the caller
glyph	the glyph ID
font	the font

Since: 8.2.0

hb_paint_push_clip_glyph ()

void
hb_paint_push_clip_glyph (hb_paint_funcs_t *funcs,
                          void *paint_data,
                          hb_codepoint_t glyph,
                          hb_font_t *font);

Perform a "push-clip-glyph" paint operation.

Parameters

funcs	paint functions
paint_data	associated data passed by the caller
glyph	the glyph ID
font	the font

Since: 7.0.0

hb_paint_push_clip_rectangle ()

void
hb_paint_push_clip_rectangle (hb_paint_funcs_t *funcs,
                              void *paint_data,
                              float xmin,
                              float ymin,
                              float xmax,
                              float ymax);

Perform a "push-clip-rect" paint operation.

Parameters

funcs	paint functions
paint_data	associated data passed by the caller
xmin	min X for the rectangle
ymin	min Y for the rectangle
xmax	max X for the rectangle
ymax	max Y for the rectangle

Since: 7.0.0

hb_paint_pop_clip ()

void
hb_paint_pop_clip (hb_paint_funcs_t *funcs,
                   void *paint_data);

Perform a "pop-clip" paint operation.

Parameters

funcs	paint functions
paint_data	associated data passed by the caller

Since: 7.0.0

hb_paint_color ()

void
hb_paint_color (hb_paint_funcs_t *funcs,
                void *paint_data,
                hb_bool_t is_foreground,
                hb_color_t color);

Perform a "color" paint operation.

Parameters

funcs	paint functions
paint_data	associated data passed by the caller
is_foreground	whether the color is the foreground
color	The color to use

Since: 7.0.0

hb_paint_image ()

void
hb_paint_image (hb_paint_funcs_t *funcs,
                void *paint_data,
                hb_blob_t *image,
                unsigned int width,
                unsigned int height,
                hb_tag_t format,
                float slant,
                hb_glyph_extents_t *extents);

Perform a "image" paint operation.

Parameters

funcs	paint functions
paint_data	associated data passed by the caller
image	image data
width	width of the raster image in pixels, or 0
height	height of the raster image in pixels, or 0
format	the image format as a tag
slant	the synthetic slant ratio to be applied to the image during rendering
extents	the extents of the glyph.	[nullable]

Since: 7.0.0

hb_paint_linear_gradient ()

void
hb_paint_linear_gradient (hb_paint_funcs_t *funcs,
                          void *paint_data,
                          hb_color_line_t *color_line,
                          float x0,
                          float y0,
                          float x1,
                          float y1,
                          float x2,
                          float y2);

Perform a "linear-gradient" paint operation.

Parameters

funcs	paint functions
paint_data	associated data passed by the caller
color_line	Color information for the gradient
x0	X coordinate of the first point
y0	Y coordinate of the first point
x1	X coordinate of the second point
y1	Y coordinate of the second point
x2	X coordinate of the third point
y2	Y coordinate of the third point

Since: 7.0.0

hb_paint_radial_gradient ()

void
hb_paint_radial_gradient (hb_paint_funcs_t *funcs,
                          void *paint_data,
                          hb_color_line_t *color_line,
                          float x0,
                          float y0,
                          float r0,
                          float x1,
                          float y1,
                          float r1);

Perform a "radial-gradient" paint operation.

Parameters

funcs	paint functions
paint_data	associated data passed by the caller
color_line	Color information for the gradient
x0	X coordinate of the first circle's center
y0	Y coordinate of the first circle's center
r0	radius of the first circle
x1	X coordinate of the second circle's center
y1	Y coordinate of the second circle's center
r1	radius of the second circle

Since: 7.0.0

hb_paint_sweep_gradient ()

void
hb_paint_sweep_gradient (hb_paint_funcs_t *funcs,
                         void *paint_data,
                         hb_color_line_t *color_line,
                         float x0,
                         float y0,
                         float start_angle,
                         float end_angle);

Perform a "sweep-gradient" paint operation.

Parameters

funcs	paint functions
paint_data	associated data passed by the caller
color_line	Color information for the gradient
x0	X coordinate of the circle's center
y0	Y coordinate of the circle's center
start_angle	the start angle
end_angle	the end angle

Since: 7.0.0

hb_paint_push_group ()

void
hb_paint_push_group (hb_paint_funcs_t *funcs,
                     void *paint_data);

Perform a "push-group" paint operation.

Parameters

funcs	paint functions
paint_data	associated data passed by the caller

Since: 7.0.0

hb_paint_pop_group ()

void
hb_paint_pop_group (hb_paint_funcs_t *funcs,
                    void *paint_data,
                    hb_paint_composite_mode_t mode);

Perform a "pop-group" paint operation.

Parameters

funcs	paint functions
paint_data	associated data passed by the caller
mode	the compositing mode to use

Since: 7.0.0

hb_paint_custom_palette_color ()

hb_bool_t
hb_paint_custom_palette_color (hb_paint_funcs_t *funcs,
                               void *paint_data,
                               unsigned int color_index,
                               hb_color_t *color);

Gets the custom palette color for color_index .

Parameters

funcs	paint functions
paint_data	associated data passed by the caller
color_index	color index
color	fetched color.	[out]

Returns

true if found, false otherwise

Since: 7.0.0

Types and Values

hb_paint_funcs_t

typedef struct hb_paint_funcs_t hb_paint_funcs_t;

Glyph paint callbacks.

The callbacks assume that the caller maintains a stack of current transforms, clips and intermediate surfaces, as evidenced by the pairs of push/pop callbacks. The push/pop calls will be properly nested, so it is fine to store the different kinds of object on a single stack.

Not all callbacks are required for all kinds of glyphs. For rendering COLRv0 or non-color outline glyphs, the gradient callbacks are not needed, and the composite callback only needs to handle simple alpha compositing (HB_PAINT_COMPOSITE_MODE_SRC_OVER).

The paint-image callback is only needed for glyphs with image blobs in the CBDT, sbix or SVG tables.

The custom-palette-color callback is only necessary if you want to override colors from the font palette with custom colors.

Since: 7.0.0

HB_PAINT_IMAGE_FORMAT_PNG

#define HB_PAINT_IMAGE_FORMAT_PNG HB_TAG('p','n','g',' ')

Tag identifying PNG images in hb_paint_image_func_t callbacks.

Since: 7.0.0

HB_PAINT_IMAGE_FORMAT_SVG

#define HB_PAINT_IMAGE_FORMAT_SVG HB_TAG('s','v','g',' ')

Tag identifying SVG images in hb_paint_image_func_t callbacks.

Since: 7.0.0

HB_PAINT_IMAGE_FORMAT_BGRA

#define HB_PAINT_IMAGE_FORMAT_BGRA HB_TAG('B','G','R','A')

Tag identifying raw pixel-data images in hb_paint_image_func_t callbacks. The data is in BGRA pre-multiplied sRGBA color-space format.

Since: 7.0.0

hb_color_line_t

typedef struct hb_color_line_t hb_color_line_t;

A struct containing color information for a gradient.

Since: 7.0.0

hb_color_stop_t

typedef struct {
  float offset;
  hb_bool_t is_foreground;
  hb_color_t color;
} hb_color_stop_t;

Information about a color stop on a color line.

Color lines typically have offsets ranging between 0 and 1, but that is not required.

Note: despite color being unpremultiplied here, interpolation in gradients shall happen in premultiplied space. See the OpenType spec COLR section for details.

Members

float `offset`;	the offset of the color stop
hb_bool_t `is_foreground`;	whether the color is the foreground
hb_color_t `color`;	the color, unpremultiplied

Since: 7.0.0

enum hb_paint_extend_t

The values of this enumeration determine how color values outside the minimum and maximum defined offset on a hb_color_line_t are determined.

See the OpenType spec COLR section for details.

Members

HB_PAINT_EXTEND_PAD	Outside the defined interval, the color of the closest color stop is used.
HB_PAINT_EXTEND_REPEAT	The color line is repeated over repeated multiples of the defined interval
HB_PAINT_EXTEND_REFLECT	The color line is repeated over repeated intervals, as for the repeat mode. However, in each repeated interval, the ordering of color stops is the reverse of the adjacent interval.

Since: 7.0.0

enum hb_paint_composite_mode_t

The values of this enumeration describe the compositing modes that can be used when combining temporary redirected drawing with the backdrop.

See the OpenType spec COLR section for details.

Members

HB_PAINT_COMPOSITE_MODE_CLEAR	clear destination layer (bounded)
HB_PAINT_COMPOSITE_MODE_SRC	replace destination layer (bounded)
HB_PAINT_COMPOSITE_MODE_DEST	ignore the source
HB_PAINT_COMPOSITE_MODE_SRC_OVER	draw source layer on top of destination layer (bounded)
HB_PAINT_COMPOSITE_MODE_DEST_OVER	draw destination on top of source
HB_PAINT_COMPOSITE_MODE_SRC_IN	draw source where there was destination content (unbounded)
HB_PAINT_COMPOSITE_MODE_DEST_IN	leave destination only where there was source content (unbounded)
HB_PAINT_COMPOSITE_MODE_SRC_OUT	draw source where there was no destination content (unbounded)
HB_PAINT_COMPOSITE_MODE_DEST_OUT	leave destination only where there was no source content
HB_PAINT_COMPOSITE_MODE_SRC_ATOP	draw source on top of destination content and only there
HB_PAINT_COMPOSITE_MODE_DEST_ATOP	leave destination on top of source content and only there (unbounded)
HB_PAINT_COMPOSITE_MODE_XOR	source and destination are shown where there is only one of them
HB_PAINT_COMPOSITE_MODE_PLUS	source and destination layers are accumulated
HB_PAINT_COMPOSITE_MODE_SCREEN	source and destination are complemented and multiplied. This causes the result to be at least as light as the lighter inputs.
HB_PAINT_COMPOSITE_MODE_OVERLAY	multiplies or screens, depending on the lightness of the destination color.
HB_PAINT_COMPOSITE_MODE_DARKEN	replaces the destination with the source if it is darker, otherwise keeps the source.
HB_PAINT_COMPOSITE_MODE_LIGHTEN	replaces the destination with the source if it is lighter, otherwise keeps the source.
HB_PAINT_COMPOSITE_MODE_COLOR_DODGE	brightens the destination color to reflect the source color.
HB_PAINT_COMPOSITE_MODE_COLOR_BURN	darkens the destination color to reflect the source color.
HB_PAINT_COMPOSITE_MODE_HARD_LIGHT	Multiplies or screens, dependent on source color.
HB_PAINT_COMPOSITE_MODE_SOFT_LIGHT	Darkens or lightens, dependent on source color.
HB_PAINT_COMPOSITE_MODE_DIFFERENCE	Takes the difference of the source and destination color.
HB_PAINT_COMPOSITE_MODE_EXCLUSION	Produces an effect similar to difference, but with lower contrast.
HB_PAINT_COMPOSITE_MODE_MULTIPLY	source and destination layers are multiplied. This causes the result to be at least as dark as the darker inputs.
HB_PAINT_COMPOSITE_MODE_HSL_HUE	Creates a color with the hue of the source and the saturation and luminosity of the target.
HB_PAINT_COMPOSITE_MODE_HSL_SATURATION	Creates a color with the saturation of the source and the hue and luminosity of the target. Painting with this mode onto a gray area produces no change.
HB_PAINT_COMPOSITE_MODE_HSL_COLOR	Creates a color with the hue and saturation of the source and the luminosity of the target. This preserves the gray levels of the target and is useful for coloring monochrome images or tinting color images.
HB_PAINT_COMPOSITE_MODE_HSL_LUMINOSITY	Creates a color with the luminosity of the source and the hue and saturation of the target. This produces an inverse effect to `HB_PAINT_COMPOSITE_MODE_HSL_COLOR` .

Since: 7.0.0