# Font

## Typedefs
typedef int(* | hpgs_moveto_func_t )(void *ctxt, const hpgs_point *p)
typedef int(* | hpgs_lineto_func_t )(void *ctxt, const hpgs_point *p)
typedef int(* | hpgs_curveto_func_t )(void *ctxt, const hpgs_point *p1, const hpgs_point *p2, const hpgs_point *p3)
typedef int(* | hpgs_fill_func_t )(void *ctxt, hpgs_bool winding)
## Functions
HPGS_API hpgs_font * | hpgs_find_font (const char *name)
HPGS_API void | hpgs_destroy_font (hpgs_font *font)
HPGS_API double | hpgs_font_get_ascent (hpgs_font *font)
HPGS_API double | hpgs_font_get_descent (hpgs_font *font)
HPGS_API double | hpgs_font_get_line_gap (hpgs_font *font)
HPGS_API double | hpgs_font_get_cap_height (hpgs_font *font)
HPGS_API unsigned | hpgs_font_get_glyph_count (hpgs_font *font)
HPGS_API unsigned | hpgs_font_get_glyph_id (hpgs_font *font, int uc)
HPGS_API const char * | hpgs_font_get_glyph_name (hpgs_font *font, unsigned gid)
HPGS_API int | hpgs_font_get_glyph_bbox (hpgs_font *font, hpgs_bbox *bb, unsigned gid)
HPGS_API int | hpgs_font_get_glyph_metrics (hpgs_font *font, hpgs_point *m, unsigned gid)
HPGS_API int | hpgs_font_get_kern_metrics (hpgs_font *font, hpgs_point *m, unsigned gid_l, unsigned gid_r)
HPGS_API int | hpgs_font_get_utf8_metrics (hpgs_font *font, hpgs_point *m, const char *str, int strlen)
HPGS_API int | hpgs_font_decompose_glyph (hpgs_font *font, void *ctxt, hpgs_moveto_func_t moveto_func, hpgs_lineto_func_t lineto_func, hpgs_curveto_func_t curveto_func, const hpgs_matrix *m, unsigned gid)
HPGS_API int | hpgs_font_draw_glyph (hpgs_font *font, hpgs_device *device, const hpgs_matrix *m, unsigned gid)
HPGS_API int | hpgs_font_decompose_utf8 (hpgs_font *font, void *ctxt, hpgs_moveto_func_t moveto_func, hpgs_lineto_func_t lineto_func, hpgs_curveto_func_t curveto_func, hpgs_fill_func_t fill_func, const hpgs_matrix *m, const char *str, int strlen)
HPGS_API int | hpgs_font_draw_utf8 (hpgs_font *font, hpgs_device *device, const hpgs_matrix *m, const char *str, int strlen)

## Function Documentation

HPGS_API void hpgs_destroy_font | ( | hpgs_font * | font | ) |

Frees all resources associated with this font object.

References hpgs_font_st::cmap_data, hpgs_font_st::glyph_cache, hpgs_font_st::glyph_cache_positions, hpgs_font_st::hmtx_data, hpgs_istream_close(), hpgs_font_st::is, hpgs_font_st::kern_data, hpgs_font_st::loca_data, hpgs_font_st::mutex, hpgs_font_st::n_cached_glyphs, hpgs_font_st::nref, and hpgs_font_st::post_data.

HPGS_API hpgs_font* hpgs_find_font | ( | const char * | name | ) |

Loads the given font from disk. Depending on your operating system, the appropriate font directories are scanned for a truetype file which contains the font of the given name. `name` is expected to be utf-8 encoded, which is almost no problem, since all known font names are ASCII-encoded.

References hpgs_font_dentry_st::font, hpgs_set_error(), hpgs_font_st::mutex, and hpgs_font_st::nref.

HPGS_API int hpgs_font_decompose_glyph | ( | hpgs_font * | font,
|  | void * | ctxt,
|  | hpgs_moveto_func_t | moveto_func,
|  | hpgs_lineto_func_t | lineto_func,
|  | hpgs_curveto_func_t | curveto_func,
|  | const hpgs_matrix * | m,
|  | unsigned | gid |
| ) |  |  |

Decomposes the outline of the given glyph id using the given moveto/linto/curveto functions and the specified transformation matrix.

You can get a glyph id for a given unicode character using `hpgs_font_get_glyph_id`.

Returns the number of outlines drawn or -1, if an error occurrs.

Referenced by hpgs_font_draw_glyph().

HPGS_API int hpgs_font_decompose_utf8 | ( | hpgs_font * | font,
|  | void * | ctxt,
|  | hpgs_moveto_func_t | moveto_func,
|  | hpgs_lineto_func_t | lineto_func,
|  | hpgs_curveto_func_t | curveto_func,
|  | hpgs_fill_func_t | fill_func,
|  | const hpgs_matrix * | m,
|  | const char * | str,
|  | int | strlen |
| ) |  |  |

Decomposes the outline of the given utf8-encoded unicode string using the given moveto/linto/curveto/fill functions and the specified transformation matrix.

Returns -1, if an error occurrs.

References hpgs_matrix_st::dx, hpgs_matrix_st::dy, hpgs_font_st::head_data, hpgs_font_st::hmtx_data, hpgs_next_utf8(), hpgs_matrix_st::mxx, and hpgs_matrix_st::myx.

Referenced by hpgs_font_draw_utf8().

HPGS_API int hpgs_font_draw_glyph | ( | hpgs_font * | font,
|  | hpgs_device * | device,
|  | const hpgs_matrix * | m,
|  | unsigned | gid |
| ) |  |  |

Draws the outline of the given glyph id to the given device by issuing moveto/linto/curveto/fill operations.

You can get a glyph id for a given unicode character using `hpgs_font_get_glyph_id`.

Returns -1, if an error occurrs.

References hpgs_device_vtable_st::curveto, hpgs_fill(), hpgs_font_decompose_glyph(), hpgs_device_vtable_st::lineto, hpgs_device_vtable_st::moveto, and hpgs_device_st::vtable.

HPGS_API int hpgs_font_draw_utf8 | ( | hpgs_font * | font,
|  | hpgs_device * | device,
|  | const hpgs_matrix * | m,
|  | const char * | str,
|  | int | strlen |
| ) |  |  |

Draws the outline of the given utf8-encoded unicode string to the given device by issuing moveto/linto/curveto/fill operations.

Returns -1, if an error occurrs.

References hpgs_device_vtable_st::curveto, hpgs_device_vtable_st::fill, hpgs_font_decompose_utf8(), hpgs_device_vtable_st::lineto, hpgs_device_vtable_st::moveto, and hpgs_device_st::vtable.

HPGS_API double hpgs_font_get_ascent | ( | hpgs_font * | font | ) |

Gets the maximal ascent of the font.

References hpgs_font_st::head_data, and hpgs_font_st::hhea_data.

HPGS_API double hpgs_font_get_cap_height | ( | hpgs_font * | font | ) |

Gets the height of capital letters above the baseline, computed from the size of the capital letter M.

References hpgs_set_error().

HPGS_API double hpgs_font_get_descent | ( | hpgs_font * | font | ) |

Gets the maximal descent of the font.

References hpgs_font_st::head_data, and hpgs_font_st::hhea_data.

HPGS_API int hpgs_font_get_glyph_bbox | ( | hpgs_font * | font,
|  | hpgs_bbox * | bb,
|  | unsigned | gid |
| ) |  |  |

Gets the bounding box of the specified glpyh id.

You can get a glyph id for a given unicode character using `hpgs_font_get_glyph_id`.

Return -1, if an error occurrs.

References hpgs_set_error().

HPGS_API unsigned hpgs_font_get_glyph_count | ( | hpgs_font * | font | ) |

Gets the number of glyphs in this font. This information might be useful, if you keep a hash map with additional information for the glyphs.

References hpgs_font_st::maxp_data.

HPGS_API unsigned hpgs_font_get_glyph_id | ( | hpgs_font * | font,
|  | int | uc |
| ) |  |  |

Gets the glyph ID of the given unicode character. The returned glpyh id is used by several other font functions.

HPGS_API int hpgs_font_get_glyph_metrics | ( | hpgs_font * | font,
|  | hpgs_point * | m,
|  | unsigned | gid |
| ) |  |  |

Gets the horizontal and vertical advance of the given glyph id. The unit of the returned vector is em, the nominal size of the letter M of the font. For almost any font one em is actually larger than the size of the capital letter M.

You can get a glyph id for a given unicode character using `hpgs_font_get_glyph_id`.

Return -1, if an error occurrs.

References hpgs_font_st::head_data, hpgs_font_st::hmtx_data, hpgs_font_st::maxp_data, hpgs_point_st::x, and hpgs_point_st::y.

HPGS_API const char* hpgs_font_get_glyph_name | ( | hpgs_font * | font,
|  | unsigned | gid |
| ) |  |  |

Gets the PostScript glyph name of the specified glpyh id. This function retunrs a null pointer, if the glyph does not have a PostScript name. In this situation you can use a glyph name of the form `uniXXXX`, where XXXX is the upppercase 4-digit hexadecimal unicode of the glpyh.

You can get a glyph id for a given unicode character using `hpgs_font_get_glyph_id`.

Return -1, if an error occurrs.

References hpgs_font_st::post_data.

HPGS_API int hpgs_font_get_kern_metrics | ( | hpgs_font * | font,
|  | hpgs_point * | m,
|  | unsigned | gid_l,
|  | unsigned | gid_r |
| ) |  |  |

Gets the horizontal and vertical kerning correction for the given glyph ids. The unit of the returned vector is em, the nominal size of the letter M of the font. For almost any font one em is actually larger than the size of the capital letter M.

You can get a glyph id for a given unicode character using `hpgs_font_get_glyph_id`.

Return -1, if an error occurrs.

References hpgs_font_st::kern_data, hpgs_point_st::x, and hpgs_point_st::y.

HPGS_API double hpgs_font_get_line_gap | ( | hpgs_font * | font | ) |

Gets the typographical line gap of the font.

References hpgs_font_st::head_data, and hpgs_font_st::hhea_data.

HPGS_API int hpgs_font_get_utf8_metrics | ( | hpgs_font * | font,
|  | hpgs_point * | m,
|  | const char * | str,
|  | int | strlen |
| ) |  |  |

Gets the horizontal and vertical advance of the given unicode string given in utf8 encoding. The unit of the returned vector is em, the nominal size of the letter M of the font. For almost any font one em is actually larger than the size of the capital letter M.

Return -1, if an error occurrs.

References hpgs_font_st::head_data, hpgs_font_st::hmtx_data, hpgs_next_utf8(), hpgs_point_st::x, and hpgs_point_st::y.