hb-cairo: HarfBuzz Manual

## hb-cairo hb-cairo — Cairo integration |

## Functions

cairo_font_face_t * | hb_cairo_font_face_create_for_font ()
hb_font_t * | hb_cairo_font_face_get_font ()
cairo_font_face_t * | hb_cairo_font_face_create_for_face ()
hb_face_t * | hb_cairo_font_face_get_face ()
hb_font_t * | (*hb_cairo_font_init_func_t) ()
void | hb_cairo_font_face_set_font_init_func ()
hb_font_t * | hb_cairo_scaled_font_get_font ()
void | hb_cairo_font_face_set_scale_factor ()
unsigned int | hb_cairo_font_face_get_scale_factor ()
void | hb_cairo_glyphs_from_buffer ()

## Includes

    #include <hb-cairo.h>

## Description

Functions for using HarfBuzz with the cairo library.

HarfBuzz supports using cairo for rendering.

## Functions

### hb_cairo_font_face_create_for_font ()

    cairo_font_face_t *
    hb_cairo_font_face_create_for_font (hb_font_t *font);

Creates a cairo_font_face_t for rendering text according to `font` .

Note that the scale of `font` does not affect the rendering, but the variations and slant that are set on `font` do.

#### Parameters

font | a hb_font_t |

#### Returns

a newly created cairo_font_face_t.

[transfer full]

Since: 7.0.0

### hb_cairo_font_face_get_font ()

    hb_font_t *
    hb_cairo_font_face_get_font (cairo_font_face_t *font_face);

Gets the hb_font_t that `font_face` was created from.

#### Parameters

font_face | a cairo_font_face_t |

#### Returns

the hb_font_t that `font_face` was created from.

[nullable][transfer none]

Since: 7.0.0

### hb_cairo_font_face_create_for_face ()

    cairo_font_face_t *
    hb_cairo_font_face_create_for_face (hb_face_t *face);

Creates a cairo_font_face_t for rendering text according to `face` .

#### Parameters

face | a hb_face_t |

#### Returns

a newly created cairo_font_face_t.

[transfer full]

Since: 7.0.0

### hb_cairo_font_face_get_face ()

    hb_face_t *
    hb_cairo_font_face_get_face (cairo_font_face_t *font_face);

Gets the hb_face_t associated with `font_face` .

#### Parameters

font_face | a cairo_font_face_t |

#### Returns

the hb_face_t associated with `font_face` .

[nullable][transfer none]

Since: 7.0.0

### hb_cairo_font_init_func_t ()

    hb_font_t *
    (*hb_cairo_font_init_func_t) (hb_font_t *font,
                                  cairo_scaled_font_t *scaled_font,
                                  void *user_data);

The type of a virtual method to be called when a cairo face created using `hb_cairo_font_face_create_for_face()` creates an hb_font_t for a cairo_scaled_font_t.

#### Parameters

font | The hb_font_t being created |
scaled_font | The respective cairo_scaled_font_t |
user_data | User data accompanying this method |

#### Returns

the hb_font_t value to use; in most cases same as `font`

Since: 7.0.0

### hb_cairo_font_face_set_font_init_func ()

    void
    hb_cairo_font_face_set_font_init_func (cairo_font_face_t *font_face,
                                           hb_cairo_font_init_func_t func,
                                           void *user_data,
                                           hb_destroy_func_t destroy);

Set the virtual method to be called when a cairo face created using `hb_cairo_font_face_create_for_face()` creates an hb_font_t for a cairo_scaled_font_t.

#### Parameters

font_face | a cairo_font_face_t |
func | The virtual method to use |
user_data | user data accompanying the method |
destroy | function to call when `user_data` is not needed anymore |

Since: 7.0.0

### hb_cairo_scaled_font_get_font ()

    hb_font_t *
    hb_cairo_scaled_font_get_font (cairo_scaled_font_t *scaled_font);

Gets the hb_font_t associated with `scaled_font` .

#### Parameters

scaled_font | a cairo_scaled_font_t |

#### Returns

the hb_font_t associated with `scaled_font` .

[nullable][transfer none]

Since: 7.0.0

### hb_cairo_font_face_set_scale_factor ()

    void
    hb_cairo_font_face_set_scale_factor (cairo_font_face_t *font_face,
                                         unsigned int scale_factor);

Sets the scale factor of the `font_face` . Default scale factor is zero.

When a cairo_font_face_t is created from a hb_face_t using `hb_cairo_font_face_create_for_face()`, such face will create hb_font_t objects during scaled-font creation. The scale factor defines how the scale set on such hb_font_t objects relates to the font-matrix (as such font size) of the cairo scaled-font.

If the scale-factor is zero (default), then the scale of the hb_font_t object will be left at default, which is the UPEM value of the respective hb_face_t.

If the scale-factor is set to non-zero, then the X and Y scale of the hb_font_t object will be respectively set to the `scale_factor` times the xx and yy elements of the scale-matrix of the cairo scaled-font being created.

When using the `hb_cairo_glyphs_from_buffer()` API to convert the HarfBuzz glyph buffer that resulted from shaping with such a hb_font_t, if the scale-factor was non-zero, you can pass it directly to that API as both X and Y scale factors.

If the scale-factor was zero however, or the cairo face was created using the alternative constructor `hb_cairo_font_face_create_for_font()`, you need to calculate the correct X/Y scale-factors to pass to `hb_cairo_glyphs_from_buffer()` by dividing the hb_font_t X/Y scale-factors by the cairo scaled-font's scale-matrix XX/YY components respectively and use those values. Or if you know that relationship offhand (because you set the scale of the hb_font_t yourself), use the conversion rate involved.

#### Parameters

scale_factor | The scale factor to use. See below |
font_face | a cairo_font_face_t |

Since: 7.0.0

### hb_cairo_font_face_get_scale_factor ()

    unsigned int
    hb_cairo_font_face_get_scale_factor (cairo_font_face_t *font_face);

Gets the scale factor set on the `font_face` . Defaults to zero. See `hb_cairo_font_face_set_scale_factor()` for details.

#### Parameters

font_face | a cairo_font_face_t |

#### Returns

the scale factor of `font_face`

Since: 7.0.0

### hb_cairo_glyphs_from_buffer ()

    void
    hb_cairo_glyphs_from_buffer (hb_buffer_t *buffer,
                                 hb_bool_t utf8_clusters,
                                 double x_scale_factor,
                                 double y_scale_factor,
                                 double x,
                                 double y,
                                 const char *utf8,
                                 int utf8_len,
                                 cairo_glyph_t **glyphs,
                                 unsigned int *num_glyphs,
                                 cairo_text_cluster_t **clusters,
                                 unsigned int *num_clusters,
                                 cairo_text_cluster_flags_t *cluster_flags);

Extracts information from `buffer` in a form that can be passed to `cairo_show_text_glyphs()` or `cairo_show_glyphs()`. This API is modeled after `cairo_scaled_font_text_to_glyphs()` and cairo_user_scaled_font_text_to_glyphs_func_t.

The `num_glyphs` argument should be preset to the number of glyph entries available in the `glyphs` buffer. If the `glyphs` buffer is `NULL`, the value of `num_glyphs` must be zero. If the provided glyph array is too short for the conversion (or for convenience), a new glyph array may be allocated using `cairo_glyph_allocate()` and placed in `glyphs` . Upon return, `num_glyphs` should contain the number of generated glyphs. If the value `glyphs` points at has changed after the call, the caller will free the allocated glyph array using `cairo_glyph_free()`. The caller will also free the original value of `glyphs` , so this function shouldn't do so.

If `clusters` is not `NULL`, then `num_clusters` and `cluster_flags` should not be either, and `utf8` must be provided, and cluster mapping will be computed. The semantics of how cluster array allocation works is similar to the glyph array. That is, if `clusters` initially points to a non-`NULL` value, that array may be used as a cluster buffer, and `num_clusters` points to the number of cluster entries available there. If the provided cluster array is too short for the conversion (or for convenience), a new cluster array may be allocated using `cairo_text_cluster_allocate()` and placed in `clusters` . In this case, the original value of `clusters` will still be freed by the caller. Upon return, `num_clusters` will contain the number of generated clusters. If the value `clusters` points at has changed after the call, the caller will free the allocated cluster array using `cairo_text_cluster_free()`.

See `hb_cairo_font_face_set_scale_factor()` for the details of the `scale_factor` argument.

The returned `glyphs` vector actually has `@num_glyphs + 1` entries in it and the x,y values of the extra entry at the end add up the advance x,y of all the glyphs in the `buffer` .

#### Parameters

buffer | a hb_buffer_t containing glyphs |
utf8_clusters | `true` if `buffer` clusters are in bytes, instead of characters |
x_scale_factor | scale factor to divide hb_position_t Y values by |
y_scale_factor | scale factor to divide hb_position_t X values by |
x | X position to place first glyph |
y | Y position to place first glyph |
utf8 | the text that was shaped in `buffer` . | [nullable]
utf8_len | the length of `utf8` in bytes |
glyphs | return location for an array of cairo_glyph_t. | [out]
num_glyphs | return location for the length of `glyphs` . | [inout]
clusters | return location for an array of cluster positions. | [out][nullable]
num_clusters | return location for the length of `clusters` . | [inout][nullable]
cluster_flags | return location for cluster flags. | [out][nullable]

Since: 7.0.0