hb-draw: HarfBuzz Manual

## hb-draw hb-draw — Glyph drawing |

## Functions

hb_draw_funcs_t * | hb_draw_funcs_create ()
hb_draw_funcs_t * | hb_draw_funcs_get_empty ()
hb_draw_funcs_t * | hb_draw_funcs_reference ()
void | hb_draw_funcs_destroy ()
hb_bool_t | hb_draw_funcs_set_user_data ()
void * | hb_draw_funcs_get_user_data ()
void | hb_draw_funcs_make_immutable ()
hb_bool_t | hb_draw_funcs_is_immutable ()
void | (*hb_draw_move_to_func_t) ()
void | hb_draw_funcs_set_move_to_func ()
void | (*hb_draw_line_to_func_t) ()
void | hb_draw_funcs_set_line_to_func ()
void | (*hb_draw_quadratic_to_func_t) ()
void | hb_draw_funcs_set_quadratic_to_func ()
void | (*hb_draw_cubic_to_func_t) ()
void | hb_draw_funcs_set_cubic_to_func ()
void | (*hb_draw_close_path_func_t) ()
void | hb_draw_funcs_set_close_path_func ()
void | hb_draw_move_to ()
void | hb_draw_line_to ()
void | hb_draw_quadratic_to ()
void | hb_draw_cubic_to ()
void | hb_draw_close_path ()
void | hb_draw_line ()
void | hb_draw_rectangle ()
void | hb_draw_circle ()

## Types and Values

enum | hb_draw_line_cap_t
#define | HB_DRAW_STATE_DEFAULT
typedef | hb_draw_funcs_t
| hb_draw_state_t

## Includes

    #include <hb.h>

## Description

Functions for drawing (extracting) glyph shapes.

The hb_draw_funcs_t struct can be used with `hb_font_draw_glyph()`.

## Functions

### hb_draw_funcs_create ()

    hb_draw_funcs_t *
    hb_draw_funcs_create (void);

Creates a new draw callbacks object.

#### Returns

A newly allocated hb_draw_funcs_t with a reference count of 1. The initial reference count should be released with hb_draw_funcs_destroy when you are done using the hb_draw_funcs_t. This function never returns `NULL`. If memory cannot be allocated, a special singleton hb_draw_funcs_t object will be returned.

[transfer full]

Since: 4.0.0

### hb_draw_funcs_get_empty ()

    hb_draw_funcs_t *
    hb_draw_funcs_get_empty (void);

Fetches the singleton empty draw-functions structure.

#### Returns

The empty draw-functions structure.

[transfer full]

Since: 7.0.0

### hb_draw_funcs_reference ()

    hb_draw_funcs_t *
    hb_draw_funcs_reference (hb_draw_funcs_t *dfuncs);

Increases the reference count on `dfuncs` by one.

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

[skip]

#### Parameters

dfuncs | draw functions |

#### Returns

The referenced hb_draw_funcs_t.

[transfer full]

Since: 4.0.0

### hb_draw_funcs_destroy ()

    void
    hb_draw_funcs_destroy (hb_draw_funcs_t *dfuncs);

Deallocate the `dfuncs` . Decreases the reference count on `dfuncs` by one. If the result is zero, then `dfuncs` and all associated resources are freed. See `hb_draw_funcs_reference()`.

[skip]

#### Parameters

dfuncs | draw functions |

Since: 4.0.0

### hb_draw_funcs_set_user_data ()

    hb_bool_t
    hb_draw_funcs_set_user_data (hb_draw_funcs_t *dfuncs,
                                 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 draw-functions structure.

[skip]

#### Parameters

dfuncs | The draw-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_draw_funcs_get_user_data ()

    void *
    hb_draw_funcs_get_user_data (const hb_draw_funcs_t *dfuncs,
                                 hb_user_data_key_t *key);

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

[skip]

#### Parameters

dfuncs | The draw-functions structure |
key | The user-data key to query |

#### Returns

A pointer to the user data.

[transfer none]

Since: 7.0.0

### hb_draw_funcs_make_immutable ()

    void
    hb_draw_funcs_make_immutable (hb_draw_funcs_t *dfuncs);

Makes `dfuncs` object immutable.

#### Parameters

dfuncs | draw functions |

Since: 4.0.0

### hb_draw_funcs_is_immutable ()

    hb_bool_t
    hb_draw_funcs_is_immutable (hb_draw_funcs_t *dfuncs);

Checks whether `dfuncs` is immutable.

#### Parameters

dfuncs | draw functions |

#### Returns

`true` if `dfuncs` is immutable, `false` otherwise

Since: 4.0.0

### hb_draw_move_to_func_t ()

    void
    (*hb_draw_move_to_func_t) (hb_draw_funcs_t *dfuncs,
                               void *draw_data,
                               hb_draw_state_t *st,
                               float to_x,
                               float to_y,
                               void *user_data);

A virtual method for the hb_draw_funcs_t to perform a "move-to" draw operation.

#### Parameters

dfuncs | draw functions object |
draw_data | The data accompanying the draw functions in `hb_font_draw_glyph()` |
st | current draw state |
to_x | X component of target point |
to_y | Y component of target point |
user_data | User data pointer passed to `hb_draw_funcs_set_move_to_func()` |

Since: 4.0.0

### hb_draw_funcs_set_move_to_func ()

    void
    hb_draw_funcs_set_move_to_func (hb_draw_funcs_t *dfuncs,
                                    hb_draw_move_to_func_t func,
                                    void *user_data,
                                    hb_destroy_func_t destroy);

Sets move-to callback to the draw functions object.

#### Parameters

dfuncs | draw functions object |
func | move-to callback. | [closure user_data][destroy destroy][scope notified]
user_data | Data to pass to `func` |
destroy | The function to call when `user_data` is not needed anymore. | [nullable]

Since: 4.0.0

### hb_draw_line_to_func_t ()

    void
    (*hb_draw_line_to_func_t) (hb_draw_funcs_t *dfuncs,
                               void *draw_data,
                               hb_draw_state_t *st,
                               float to_x,
                               float to_y,
                               void *user_data);

A virtual method for the hb_draw_funcs_t to perform a "line-to" draw operation.

#### Parameters

dfuncs | draw functions object |
draw_data | The data accompanying the draw functions in `hb_font_draw_glyph()` |
st | current draw state |
to_x | X component of target point |
to_y | Y component of target point |
user_data | User data pointer passed to `hb_draw_funcs_set_line_to_func()` |

Since: 4.0.0

### hb_draw_funcs_set_line_to_func ()

    void
    hb_draw_funcs_set_line_to_func (hb_draw_funcs_t *dfuncs,
                                    hb_draw_line_to_func_t func,
                                    void *user_data,
                                    hb_destroy_func_t destroy);

Sets line-to callback to the draw functions object.

#### Parameters

dfuncs | draw functions object |
func | line-to callback. | [closure user_data][destroy destroy][scope notified]
user_data | Data to pass to `func` |
destroy | The function to call when `user_data` is not needed anymore. | [nullable]

Since: 4.0.0

### hb_draw_quadratic_to_func_t ()

    void
    (*hb_draw_quadratic_to_func_t) (hb_draw_funcs_t *dfuncs,
                                    void *draw_data,
                                    hb_draw_state_t *st,
                                    float control_x,
                                    float control_y,
                                    float to_x,
                                    float to_y,
                                    void *user_data);

A virtual method for the hb_draw_funcs_t to perform a "quadratic-to" draw operation.

#### Parameters

dfuncs | draw functions object |
draw_data | The data accompanying the draw functions in `hb_font_draw_glyph()` |
st | current draw state |
control_x | X component of control point |
control_y | Y component of control point |
to_x | X component of target point |
to_y | Y component of target point |
user_data | User data pointer passed to `hb_draw_funcs_set_quadratic_to_func()` |

Since: 4.0.0

### hb_draw_funcs_set_quadratic_to_func ()

    void
    hb_draw_funcs_set_quadratic_to_func (hb_draw_funcs_t *dfuncs,
                                         hb_draw_quadratic_to_func_t func,
                                         void *user_data,
                                         hb_destroy_func_t destroy);

Sets quadratic-to callback to the draw functions object.

#### Parameters

dfuncs | draw functions object |
func | quadratic-to callback. | [closure user_data][destroy destroy][scope notified]
user_data | Data to pass to `func` |
destroy | The function to call when `user_data` is not needed anymore. | [nullable]

Since: 4.0.0

### hb_draw_cubic_to_func_t ()

    void
    (*hb_draw_cubic_to_func_t) (hb_draw_funcs_t *dfuncs,
                                void *draw_data,
                                hb_draw_state_t *st,
                                float control1_x,
                                float control1_y,
                                float control2_x,
                                float control2_y,
                                float to_x,
                                float to_y,
                                void *user_data);

A virtual method for the hb_draw_funcs_t to perform a "cubic-to" draw operation.

#### Parameters

dfuncs | draw functions object |
draw_data | The data accompanying the draw functions in `hb_font_draw_glyph()` |
st | current draw state |
control1_x | X component of first control point |
control1_y | Y component of first control point |
control2_x | X component of second control point |
control2_y | Y component of second control point |
to_x | X component of target point |
to_y | Y component of target point |
user_data | User data pointer passed to `hb_draw_funcs_set_cubic_to_func()` |

Since: 4.0.0

### hb_draw_funcs_set_cubic_to_func ()

    void
    hb_draw_funcs_set_cubic_to_func (hb_draw_funcs_t *dfuncs,
                                     hb_draw_cubic_to_func_t func,
                                     void *user_data,
                                     hb_destroy_func_t destroy);

Sets cubic-to callback to the draw functions object.

#### Parameters

dfuncs | draw functions |
func | cubic-to callback. | [closure user_data][destroy destroy][scope notified]
user_data | Data to pass to `func` |
destroy | The function to call when `user_data` is not needed anymore. | [nullable]

Since: 4.0.0

### hb_draw_close_path_func_t ()

    void
    (*hb_draw_close_path_func_t) (hb_draw_funcs_t *dfuncs,
                                  void *draw_data,
                                  hb_draw_state_t *st,
                                  void *user_data);

A virtual method for the hb_draw_funcs_t to perform a "close-path" draw operation.

#### Parameters

dfuncs | draw functions object |
draw_data | The data accompanying the draw functions in `hb_font_draw_glyph()` |
st | current draw state |
user_data | User data pointer passed to `hb_draw_funcs_set_close_path_func()` |

Since: 4.0.0

### hb_draw_funcs_set_close_path_func ()

    void
    hb_draw_funcs_set_close_path_func (hb_draw_funcs_t *dfuncs,
                                       hb_draw_close_path_func_t func,
                                       void *user_data,
                                       hb_destroy_func_t destroy);

Sets close-path callback to the draw functions object.

#### Parameters

dfuncs | draw functions object |
func | close-path callback. | [closure user_data][destroy destroy][scope notified]
user_data | Data to pass to `func` |
destroy | The function to call when `user_data` is not needed anymore. | [nullable]

Since: 4.0.0

### hb_draw_move_to ()

    void
    hb_draw_move_to (hb_draw_funcs_t *dfuncs,
                     void *draw_data,
                     hb_draw_state_t *st,
                     float to_x,
                     float to_y);

Perform a "move-to" draw operation.

#### Parameters

dfuncs | draw functions |
draw_data | associated draw data passed by the caller |
st | current draw state |
to_x | X component of target point |
to_y | Y component of target point |

Since: 4.0.0

### hb_draw_line_to ()

    void
    hb_draw_line_to (hb_draw_funcs_t *dfuncs,
                     void *draw_data,
                     hb_draw_state_t *st,
                     float to_x,
                     float to_y);

Perform a "line-to" draw operation.

#### Parameters

dfuncs | draw functions |
draw_data | associated draw data passed by the caller |
st | current draw state |
to_x | X component of target point |
to_y | Y component of target point |

Since: 4.0.0

### hb_draw_quadratic_to ()

    void
    hb_draw_quadratic_to (hb_draw_funcs_t *dfuncs,
                          void *draw_data,
                          hb_draw_state_t *st,
                          float control_x,
                          float control_y,
                          float to_x,
                          float to_y);

Perform a "quadratic-to" draw operation.

#### Parameters

dfuncs | draw functions |
draw_data | associated draw data passed by the caller |
st | current draw state |
control_x | X component of control point |
control_y | Y component of control point |
to_x | X component of target point |
to_y | Y component of target point |

Since: 4.0.0

### hb_draw_cubic_to ()

    void
    hb_draw_cubic_to (hb_draw_funcs_t *dfuncs,
                      void *draw_data,
                      hb_draw_state_t *st,
                      float control1_x,
                      float control1_y,
                      float control2_x,
                      float control2_y,
                      float to_x,
                      float to_y);

Perform a "cubic-to" draw operation.

#### Parameters

dfuncs | draw functions |
draw_data | associated draw data passed by the caller |
st | current draw state |
control1_x | X component of first control point |
control1_y | Y component of first control point |
control2_x | X component of second control point |
control2_y | Y component of second control point |
to_x | X component of target point |
to_y | Y component of target point |

Since: 4.0.0

### hb_draw_close_path ()

    void
    hb_draw_close_path (hb_draw_funcs_t *dfuncs,
                        void *draw_data,
                        hb_draw_state_t *st);

Perform a "close-path" draw operation.

#### Parameters

dfuncs | draw functions |
draw_data | associated draw data passed by the caller |
st | current draw state |

Since: 4.0.0

### hb_draw_line ()

    void
    hb_draw_line (hb_draw_funcs_t *dfuncs,
                  void *draw_data,
                  hb_draw_state_t *st,
                  float x0,
                  float y0,
                  float w0,
                  float x1,
                  float y1,
                  float w1,
                  hb_draw_line_cap_t cap);

Emits a tapered line segment as a filled trapezoid. `w0` and `w1` are the full stroke widths at the start and end points respectively; they may differ for a tapered stroke or match for a uniform one. Pass `NaN` for `w1` to use `w0` (uniform stroke) without repeating the value.

With HB_DRAW_LINE_CAP_SQUARE each endpoint is extended along the line direction by half its local stroke width, so four ``hb_draw_line()`` calls form a closed rectangle without gaps at the corners.

#### Parameters

dfuncs | draw functions |
draw_data | associated draw data passed by the caller |
st | current draw state |
x0 | start X coordinate |
y0 | start Y coordinate |
w0 | stroke width at the start |
x1 | end X coordinate |
y1 | end Y coordinate |
w1 | stroke width at the end |
cap | end-cap shape (butt or square) |

Since: 14.2.0

### hb_draw_rectangle ()

    void
    hb_draw_rectangle (hb_draw_funcs_t *dfuncs,
                       void *draw_data,
                       hb_draw_state_t *st,
                       float x,
                       float y,
                       float w,
                       float h,
                       float stroke_width);

Emits an axis-aligned rectangle. If `stroke_width` is a finite positive value, the rectangle is rendered as an outlined ring of that thickness centered on the edges; if `stroke_width` is `NaN`, the rectangle is rendered filled.

Note: stroked rectangles produce a bounding box covering the full outer rectangle, so if the pen is a GPU fragment-shader backend, the shader runs for every interior pixel even though only the outline contributes coverage. For very thin outlines where the interior is much larger than the stroke, emitting four `hb_draw_line()` segments (one per edge) is considerably cheaper per frame.

#### Parameters

dfuncs | draw functions |
draw_data | associated draw data passed by the caller |
st | current draw state |
x | top-left X coordinate |
y | top-left Y coordinate |
w | width (may be negative) |
h | height (may be negative) |
stroke_width | stroke width, or `NaN` for a filled rectangle |

Since: 14.2.0

### hb_draw_circle ()

    void
    hb_draw_circle (hb_draw_funcs_t *dfuncs,
                    void *draw_data,
                    hb_draw_state_t *st,
                    float cx,
                    float cy,
                    float r,
                    float stroke_width);

Emits a circle approximated by four cubic Bezier curves. If `stroke_width` is a finite positive value, the circle is rendered as an outlined ring of that thickness centered on the nominal radius; if `stroke_width` is `NaN`, the circle is rendered as a filled disc.

#### Parameters

dfuncs | draw functions |
draw_data | associated draw data passed by the caller |
st | current draw state |
cx | center X coordinate |
cy | center Y coordinate |
r | radius |
stroke_width | stroke width, or `NaN` for a filled disc |

Since: 14.2.0

## Types and Values

### enum hb_draw_line_cap_t

End-cap shape for `hb_draw_line()`.

#### Members

HB_DRAW_LINE_CAP_BUTT | No cap; the line ends exactly at its endpoint. |
HB_DRAW_LINE_CAP_SQUARE | Square cap; the line is extended past its endpoint by half the local stroke width. Useful for composing closed shapes from line segments (e.g. a rectangle made from four lines). |

Since: 14.2.0

### HB_DRAW_STATE_DEFAULT

    #define HB_DRAW_STATE_DEFAULT {0, 0.f, 0.f, 0.f, 0.f, {0}, {0}, {0}, {0}, {0}, {0}, {0}}

The default hb_draw_state_t at the start of glyph drawing.

### hb_draw_funcs_t

    typedef struct hb_draw_funcs_t hb_draw_funcs_t;

Glyph draw callbacks.

hb_draw_move_to_func_t, hb_draw_line_to_func_t and hb_draw_cubic_to_func_t calls are necessary to be defined but we translate hb_draw_quadratic_to_func_t calls to hb_draw_cubic_to_func_t if the callback isn't defined.

Since: 4.0.0

### hb_draw_state_t

    typedef struct {
      hb_bool_t path_open;

      float path_start_x;
      float path_start_y;

      float current_x;
      float current_y;
    } hb_draw_state_t;

Current drawing state.

#### Members

hb_bool_t `path_open`; | Whether there is an open path |
float `path_start_x`; | X component of the start of current path |
float `path_start_y`; | Y component of the start of current path |
float `current_x`; | X component of current point |
float `current_y`; | Y component of current point |

Since: 4.0.0