diff options
Diffstat (limited to 'thirdparty/harfbuzz/src/hb-font.h')
| -rw-r--r-- | thirdparty/harfbuzz/src/hb-font.h | 391 |
1 files changed, 302 insertions, 89 deletions
diff --git a/thirdparty/harfbuzz/src/hb-font.h b/thirdparty/harfbuzz/src/hb-font.h index e1a5719f1d..05f6c03f47 100644 --- a/thirdparty/harfbuzz/src/hb-font.h +++ b/thirdparty/harfbuzz/src/hb-font.h @@ -45,6 +45,19 @@ typedef struct hb_font_t hb_font_t; * hb_font_funcs_t */ +/** + * hb_font_funcs_t: + * + * Data type containing a set of virtual methods used for + * working on #hb_font_t font objects. + * + * HarfBuzz provides a lightweight default function for each of + * the methods in #hb_font_funcs_t. Client programs can implement + * their own replacements for the individual font functions, as + * needed, and replace the default by calling the setter for a + * method. + * + **/ typedef struct hb_font_funcs_t hb_font_funcs_t; HB_EXTERN hb_font_funcs_t * @@ -81,12 +94,21 @@ hb_font_funcs_is_immutable (hb_font_funcs_t *ffuncs); /* font and glyph extents */ -/* Note that typically ascender is positive and descender negative in coordinate systems that grow up. */ -typedef struct hb_font_extents_t -{ - hb_position_t ascender; /* typographic ascender. */ - hb_position_t descender; /* typographic descender. */ - hb_position_t line_gap; /* suggested line spacing gap. */ +/** + * hb_font_extents_t: + * @ascender: The height of typographic ascenders. + * @descender: The depth of typographic descenders. + * @line_gap: The suggested line-spacing gap. + * + * Font-wide extent values, measured in font units. + * + * Note that typically @ascender is positive and @descender + * negative, in coordinate systems that grow up. + **/ +typedef struct hb_font_extents_t { + hb_position_t ascender; + hb_position_t descender; + hb_position_t line_gap; /*< private >*/ hb_position_t reserved9; hb_position_t reserved8; @@ -99,13 +121,22 @@ typedef struct hb_font_extents_t hb_position_t reserved1; } hb_font_extents_t; -/* Note that height is negative in coordinate systems that grow up. */ -typedef struct hb_glyph_extents_t -{ - hb_position_t x_bearing; /* left side of glyph from origin. */ - hb_position_t y_bearing; /* top side of glyph from origin. */ - hb_position_t width; /* distance from left to right side. */ - hb_position_t height; /* distance from top to bottom side. */ +/** + * hb_glyph_extents_t: + * @x_bearing: Distance from the x-origin to the left extremum of the glyph. + * @y_bearing: Distance from the top extremum of the glyph to the y-origin. + * @width: Distance from the left extremum of the glyph to the right extremum. + * @height: Distance from the top extremum of the glyph to the bottom extremum. + * + * Glyph extent values, measured in font units. + * + * Note that @height is negative, in coordinate systems that grow up. + **/ +typedef struct hb_glyph_extents_t { + hb_position_t x_bearing; + hb_position_t y_bearing; + hb_position_t width; + hb_position_t height; } hb_glyph_extents_t; /* func types */ @@ -113,19 +144,72 @@ typedef struct hb_glyph_extents_t typedef hb_bool_t (*hb_font_get_font_extents_func_t) (hb_font_t *font, void *font_data, hb_font_extents_t *extents, void *user_data); + +/** + * hb_font_get_font_h_extents_func_t: + * + * A virtual method for the #hb_font_funcs_t of an #hb_font_t object. + * + * This method should retrieve the extents for a font, in horizontal-direction + * text segments. Extents must be returned in an #hb_glyph_extents output + * parameter. + * + **/ typedef hb_font_get_font_extents_func_t hb_font_get_font_h_extents_func_t; + +/** + * hb_font_get_font_v_extents_func_t: + * + * A virtual method for the #hb_font_funcs_t of an #hb_font_t object. + * + * This method should retrieve the extents for a font, in vertical-direction + * text segments. Extents must be returned in an #hb_glyph_extents output + * parameter. + * + **/ typedef hb_font_get_font_extents_func_t hb_font_get_font_v_extents_func_t; +/** + * hb_font_get_nominal_glyph_func_t: + * + * A virtual method for the #hb_font_funcs_t of an #hb_font_t object. + * + * This method should retrieve the nominal glyph ID for a specified Unicode code + * point. Glyph IDs must be returned in a #hb_codepoint_t output parameter. + * + **/ typedef hb_bool_t (*hb_font_get_nominal_glyph_func_t) (hb_font_t *font, void *font_data, hb_codepoint_t unicode, hb_codepoint_t *glyph, void *user_data); + +/** + * hb_font_get_variation_glyph_func_t: + * + * A virtual method for the #hb_font_funcs_t of an #hb_font_t object. + * + * This method should retrieve the glyph ID for a specified Unicode code point + * followed by a specified Variation Selector code point. Glyph IDs must be + * returned in a #hb_codepoint_t output parameter. + * + **/ typedef hb_bool_t (*hb_font_get_variation_glyph_func_t) (hb_font_t *font, void *font_data, hb_codepoint_t unicode, hb_codepoint_t variation_selector, hb_codepoint_t *glyph, void *user_data); + +/** + * hb_font_get_nominal_glyphs_func_t: + * + * A virtual method for the #hb_font_funcs_t of an #hb_font_t object. + * + * This method should retrieve the nominal glyph IDs for a sequence of + * Unicode code points. Glyph IDs must be returned in a #hb_codepoint_t + * output parameter. + * + **/ typedef unsigned int (*hb_font_get_nominal_glyphs_func_t) (hb_font_t *font, void *font_data, unsigned int count, const hb_codepoint_t *first_unicode, @@ -134,13 +218,51 @@ typedef unsigned int (*hb_font_get_nominal_glyphs_func_t) (hb_font_t *font, void unsigned int glyph_stride, void *user_data); - +/** + * hb_font_get_glyph_advance_func_t: + * + * A virtual method for the #hb_font_funcs_t of an #hb_font_t object. + * + * This method should retrieve the advance for a specified glyph. The + * method must return an #hb_position_t. + * + **/ typedef hb_position_t (*hb_font_get_glyph_advance_func_t) (hb_font_t *font, void *font_data, hb_codepoint_t glyph, void *user_data); + +/** + * hb_font_get_glyph_h_advance_func_t: + * + * A virtual method for the #hb_font_funcs_t of an #hb_font_t object. + * + * This method should retrieve the advance for a specified glyph, in + * horizontal-direction text segments. Advances must be returned in + * an #hb_position_t output parameter. + * + **/ typedef hb_font_get_glyph_advance_func_t hb_font_get_glyph_h_advance_func_t; + +/** + * hb_font_get_glyph_v_advance_func_t: + * + * A virtual method for the #hb_font_funcs_t of an #hb_font_t object. + * + * This method should retrieve the advance for a specified glyph, in + * vertical-direction text segments. Advances must be returned in + * an #hb_position_t output parameter. + * + **/ typedef hb_font_get_glyph_advance_func_t hb_font_get_glyph_v_advance_func_t; +/** + * hb_font_get_glyph_advances_func_t: + * + * A virtual method for the #hb_font_funcs_t of an #hb_font_t object. + * + * This method should retrieve the advances for a sequence of glyphs. + * + **/ typedef void (*hb_font_get_glyph_advances_func_t) (hb_font_t* font, void* font_data, unsigned int count, const hb_codepoint_t *first_glyph, @@ -148,14 +270,66 @@ typedef void (*hb_font_get_glyph_advances_func_t) (hb_font_t* font, void* font_d hb_position_t *first_advance, unsigned advance_stride, void *user_data); + +/** + * hb_font_get_glyph_h_advances_func_t: + * + * A virtual method for the #hb_font_funcs_t of an #hb_font_t object. + * + * This method should retrieve the advances for a sequence of glyphs, in + * horizontal-direction text segments. + * + **/ typedef hb_font_get_glyph_advances_func_t hb_font_get_glyph_h_advances_func_t; + +/** + * hb_font_get_glyph_v_advances_func_t: + * + * A virtual method for the #hb_font_funcs_t of an #hb_font_t object. + * + * This method should retrieve the advances for a sequence of glyphs, in + * vertical-direction text segments. + * + **/ typedef hb_font_get_glyph_advances_func_t hb_font_get_glyph_v_advances_func_t; +/** + * hb_font_get_glyph_origin_func_t: + * + * A virtual method for the #hb_font_funcs_t of an #hb_font_t object. + * + * This method should retrieve the (X,Y) coordinates (in font units) of the + * origin for a glyph. Each coordinate must be returned in an #hb_position_t + * output parameter. + * + **/ typedef hb_bool_t (*hb_font_get_glyph_origin_func_t) (hb_font_t *font, void *font_data, hb_codepoint_t glyph, hb_position_t *x, hb_position_t *y, void *user_data); + +/** + * hb_font_get_glyph_h_origin_func_t: + * + * A virtual method for the #hb_font_funcs_t of an #hb_font_t object. + * + * This method should retrieve the (X,Y) coordinates (in font units) of the + * origin for a glyph, in horizontal-direction text segments. Each + * coordinate must be returned in an #hb_position_t output parameter. + * + **/ typedef hb_font_get_glyph_origin_func_t hb_font_get_glyph_h_origin_func_t; + +/** + * hb_font_get_glyph_v_origin_func_t: + * + * A virtual method for the #hb_font_funcs_t of an #hb_font_t object. + * + * This method should retrieve the (X,Y) coordinates (in font units) of the + * origin for a glyph, in vertical-direction text segments. Each coordinate + * must be returned in an #hb_position_t output parameter. + * + **/ typedef hb_font_get_glyph_origin_func_t hb_font_get_glyph_v_origin_func_t; typedef hb_position_t (*hb_font_get_glyph_kerning_func_t) (hb_font_t *font, void *font_data, @@ -164,20 +338,59 @@ typedef hb_position_t (*hb_font_get_glyph_kerning_func_t) (hb_font_t *font, void typedef hb_font_get_glyph_kerning_func_t hb_font_get_glyph_h_kerning_func_t; +/** + * hb_font_get_glyph_extents_func_t: + * + * A virtual method for the #hb_font_funcs_t of an #hb_font_t object. + * + * This method should retrieve the extents for a specified glyph. Extents must be + * returned in an #hb_glyph_extents output parameter. + * + **/ typedef hb_bool_t (*hb_font_get_glyph_extents_func_t) (hb_font_t *font, void *font_data, hb_codepoint_t glyph, hb_glyph_extents_t *extents, void *user_data); + +/** + * hb_font_get_glyph_contour_point_func_t: + * + * A virtual method for the #hb_font_funcs_t of an #hb_font_t object. + * + * This method should retrieve the (X,Y) coordinates (in font units) for a + * specified contour point in a glyph. Each coordinate must be returned as + * an #hb_position_t output parameter. + * + **/ typedef hb_bool_t (*hb_font_get_glyph_contour_point_func_t) (hb_font_t *font, void *font_data, hb_codepoint_t glyph, unsigned int point_index, hb_position_t *x, hb_position_t *y, void *user_data); +/** + * hb_font_get_glyph_name_func_t: + * + * A virtual method for the #hb_font_funcs_t of an #hb_font_t object. + * + * This method should retrieve the glyph name that corresponds to a + * glyph ID. The name should be returned in a string output parameter. + * + **/ typedef hb_bool_t (*hb_font_get_glyph_name_func_t) (hb_font_t *font, void *font_data, hb_codepoint_t glyph, char *name, unsigned int size, void *user_data); + +/** + * hb_font_get_glyph_from_name_func_t: + * + * A virtual method for the #hb_font_funcs_t of an #hb_font_t object. + * + * This method should retrieve the glyph ID that corresponds to a glyph-name + * string. + * + **/ typedef hb_bool_t (*hb_font_get_glyph_from_name_func_t) (hb_font_t *font, void *font_data, const char *name, int len, /* -1 means nul-terminated */ hb_codepoint_t *glyph, @@ -188,12 +401,12 @@ typedef hb_bool_t (*hb_font_get_glyph_from_name_func_t) (hb_font_t *font, void * /** * hb_font_funcs_set_font_h_extents_func: - * @ffuncs: font functions. - * @func: (closure user_data) (destroy destroy) (scope notified): - * @user_data: - * @destroy: - * + * @ffuncs: A font-function structure + * @func: (closure user_data) (destroy destroy) (scope notified): The callback function to assign + * @user_data: Data to pass to @func + * @destroy: (optional): The function to call when @user_data is not needed anymore * + * Sets the implementation function for #hb_font_get_font_h_extents_func_t. * * Since: 1.1.2 **/ @@ -204,12 +417,12 @@ hb_font_funcs_set_font_h_extents_func (hb_font_funcs_t *ffuncs, /** * hb_font_funcs_set_font_v_extents_func: - * @ffuncs: font functions. - * @func: (closure user_data) (destroy destroy) (scope notified): - * @user_data: - * @destroy: - * + * @ffuncs: A font-function structure + * @func: (closure user_data) (destroy destroy) (scope notified): The callback function to assign + * @user_data: Data to pass to @func + * @destroy: (optional): The function to call when @user_data is not needed anymore * + * Sets the implementation function for #hb_font_get_font_v_extents_func_t. * * Since: 1.1.2 **/ @@ -220,12 +433,12 @@ hb_font_funcs_set_font_v_extents_func (hb_font_funcs_t *ffuncs, /** * hb_font_funcs_set_nominal_glyph_func: - * @ffuncs: font functions. - * @func: (closure user_data) (destroy destroy) (scope notified): - * @user_data: - * @destroy: - * + * @ffuncs: A font-function structure + * @func: (closure user_data) (destroy destroy) (scope notified): The callback function to assign + * @user_data: Data to pass to @func + * @destroy: (optional): The function to call when @user_data is not needed anymore * + * Sets the implementation function for #hb_font_get_nominal_glyph_func_t. * * Since: 1.2.3 **/ @@ -236,12 +449,12 @@ hb_font_funcs_set_nominal_glyph_func (hb_font_funcs_t *ffuncs, /** * hb_font_funcs_set_nominal_glyphs_func: - * @ffuncs: font functions. - * @func: (closure user_data) (destroy destroy) (scope notified): - * @user_data: - * @destroy: - * + * @ffuncs: A font-function structure + * @func: (closure user_data) (destroy destroy) (scope notified): The callback function to assign + * @user_data: Data to pass to @func + * @destroy: (optional): The function to call when @user_data is not needed anymore * + * Sets the implementation function for #hb_font_get_nominal_glyphs_func_t. * * Since: 2.0.0 **/ @@ -252,12 +465,12 @@ hb_font_funcs_set_nominal_glyphs_func (hb_font_funcs_t *ffuncs, /** * hb_font_funcs_set_variation_glyph_func: - * @ffuncs: font functions. - * @func: (closure user_data) (destroy destroy) (scope notified): - * @user_data: - * @destroy: - * + * @ffuncs: A font-function structure + * @func: (closure user_data) (destroy destroy) (scope notified): The callback function to assign + * @user_data: Data to pass to @func + * @destroy: (optional): The function to call when @user_data is not needed anymore * + * Sets the implementation function for #hb_font_get_variation_glyph_func_t. * * Since: 1.2.3 **/ @@ -268,12 +481,12 @@ hb_font_funcs_set_variation_glyph_func (hb_font_funcs_t *ffuncs, /** * hb_font_funcs_set_glyph_h_advance_func: - * @ffuncs: font functions. - * @func: (closure user_data) (destroy destroy) (scope notified): - * @user_data: - * @destroy: - * + * @ffuncs: A font-function structure + * @func: (closure user_data) (destroy destroy) (scope notified): The callback function to assign + * @user_data: Data to pass to @func + * @destroy: (optional): The function to call when @user_data is not needed anymore * + * Sets the implementation function for #hb_font_get_glyph_h_advance_func_t. * * Since: 0.9.2 **/ @@ -284,12 +497,12 @@ hb_font_funcs_set_glyph_h_advance_func (hb_font_funcs_t *ffuncs, /** * hb_font_funcs_set_glyph_v_advance_func: - * @ffuncs: font functions. - * @func: (closure user_data) (destroy destroy) (scope notified): - * @user_data: - * @destroy: - * + * @ffuncs: A font-function structure + * @func: (closure user_data) (destroy destroy) (scope notified): The callback function to assign + * @user_data: Data to pass to @func + * @destroy: (optional): The function to call when @user_data is not needed anymore * + * Sets the implementation function for #hb_font_get_glyph_v_advance_func_t. * * Since: 0.9.2 **/ @@ -300,12 +513,12 @@ hb_font_funcs_set_glyph_v_advance_func (hb_font_funcs_t *ffuncs, /** * hb_font_funcs_set_glyph_h_advances_func: - * @ffuncs: font functions. - * @func: (closure user_data) (destroy destroy) (scope notified): - * @user_data: - * @destroy: - * + * @ffuncs: A font-function structure + * @func: (closure user_data) (destroy destroy) (scope notified): The callback function to assign + * @user_data: Data to pass to @func + * @destroy: (optional): The function to call when @user_data is not needed anymore * + * Sets the implementation function for #hb_font_get_glyph_h_advances_func_t. * * Since: 1.8.6 **/ @@ -316,12 +529,12 @@ hb_font_funcs_set_glyph_h_advances_func (hb_font_funcs_t *ffuncs, /** * hb_font_funcs_set_glyph_v_advances_func: - * @ffuncs: font functions. - * @func: (closure user_data) (destroy destroy) (scope notified): - * @user_data: - * @destroy: - * + * @ffuncs: A font-function structure + * @func: (closure user_data) (destroy destroy) (scope notified): The callback function to assign + * @user_data: Data to pass to @func + * @destroy: (optional): The function to call when @user_data is not needed anymore * + * Sets the implementation function for #hb_font_get_glyph_v_advances_func_t. * * Since: 1.8.6 **/ @@ -332,12 +545,12 @@ hb_font_funcs_set_glyph_v_advances_func (hb_font_funcs_t *ffuncs, /** * hb_font_funcs_set_glyph_h_origin_func: - * @ffuncs: font functions. - * @func: (closure user_data) (destroy destroy) (scope notified): - * @user_data: - * @destroy: - * + * @ffuncs: A font-function structure + * @func: (closure user_data) (destroy destroy) (scope notified): The callback function to assign + * @user_data: Data to pass to @func + * @destroy: (optional): The function to call when @user_data is not needed anymore * + * Sets the implementation function for #hb_font_get_glyph_h_origin_func_t. * * Since: 0.9.2 **/ @@ -348,12 +561,12 @@ hb_font_funcs_set_glyph_h_origin_func (hb_font_funcs_t *ffuncs, /** * hb_font_funcs_set_glyph_v_origin_func: - * @ffuncs: font functions. - * @func: (closure user_data) (destroy destroy) (scope notified): - * @user_data: - * @destroy: - * + * @ffuncs: A font-function structure + * @func: (closure user_data) (destroy destroy) (scope notified): The callback function to assign + * @user_data: Data to pass to @func + * @destroy: (optional): The function to call when @user_data is not needed anymore * + * Sets the implementation function for #hb_font_get_glyph_v_origin_func_t. * * Since: 0.9.2 **/ @@ -380,12 +593,12 @@ hb_font_funcs_set_glyph_h_kerning_func (hb_font_funcs_t *ffuncs, /** * hb_font_funcs_set_glyph_extents_func: - * @ffuncs: font functions. - * @func: (closure user_data) (destroy destroy) (scope notified): - * @user_data: - * @destroy: - * + * @ffuncs: A font-function structure + * @func: (closure user_data) (destroy destroy) (scope notified): The callback function to assign + * @user_data: Data to pass to @func + * @destroy: (optional): The function to call when @user_data is not needed anymore * + * Sets the implementation function for #hb_font_get_glyph_extents_func_t. * * Since: 0.9.2 **/ @@ -396,12 +609,12 @@ hb_font_funcs_set_glyph_extents_func (hb_font_funcs_t *ffuncs, /** * hb_font_funcs_set_glyph_contour_point_func: - * @ffuncs: font functions. - * @func: (closure user_data) (destroy destroy) (scope notified): - * @user_data: - * @destroy: - * + * @ffuncs: A font-function structure + * @func: (closure user_data) (destroy destroy) (scope notified): The callback function to assign + * @user_data: Data to pass to @func + * @destroy: (optional): The function to call when @user_data is not needed anymore * + * Sets the implementation function for #hb_font_get_glyph_contour_point_func_t. * * Since: 0.9.2 **/ @@ -412,12 +625,12 @@ hb_font_funcs_set_glyph_contour_point_func (hb_font_funcs_t *ffuncs, /** * hb_font_funcs_set_glyph_name_func: - * @ffuncs: font functions. - * @func: (closure user_data) (destroy destroy) (scope notified): - * @user_data: - * @destroy: - * + * @ffuncs: A font-function structure + * @func: (closure user_data) (destroy destroy) (scope notified): The callback function to assign + * @user_data: Data to pass to @func + * @destroy: (optional): The function to call when @user_data is not needed anymore * + * Sets the implementation function for #hb_font_get_glyph_name_func_t. * * Since: 0.9.2 **/ @@ -428,12 +641,12 @@ hb_font_funcs_set_glyph_name_func (hb_font_funcs_t *ffuncs, /** * hb_font_funcs_set_glyph_from_name_func: - * @ffuncs: font functions. - * @func: (closure user_data) (destroy destroy) (scope notified): - * @user_data: - * @destroy: - * + * @ffuncs: A font-function structure + * @func: (closure user_data) (destroy destroy) (scope notified): The callback function to assign + * @user_data: Data to pass to @func + * @destroy: (optional): The function to call when @user_data is not needed anymore * + * Sets the implementation function for #hb_font_get_glyph_from_name_func_t. * * Since: 0.9.2 **/ |