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 ()

## Types and Values

#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

## Types and Values

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