walkero
/
harfbuzz
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Docs: update and extended GTK-Doc comments for hb-ot-math.

This commit is contained in:
Nathan Willis 2019-04-14 15:33:56 +01:00
parent 3f74b7a14b
commit cd9889cac3
2 changed files with 98 additions and 54 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

131
src/hb-ot-math.cc
View File

@ -37,6 +37,11 @@
* @include: hb-ot.h * @include: hb-ot.h
* *
* Functions for fetching mathematics layout data from OpenType fonts. * Functions for fetching mathematics layout data from OpenType fonts.
*
* HarfBuzz itself does not implement a math layout solution. The
* functions and types provided can be used by client programs to access
* the font data necessary for typesetting OpenType Math layout.
*
**/ **/
@ -48,10 +53,9 @@
* hb_ot_math_has_data: * hb_ot_math_has_data:
* @face: #hb_face_t to test * @face: #hb_face_t to test
* *
* This function allows to verify the presence of an OpenType MATH table on the * Tests whether a face has a `MATH` table.
* face.
* *
* Return value: true if face has a MATH table, false otherwise * Return value: true if the table is found, false otherwise
* *
* Since: 1.3.3 * Since: 1.3.3
**/ **/
@ -63,16 +67,18 @@ hb_ot_math_has_data (hb_face_t *face)
/** /**
* hb_ot_math_get_constant: * hb_ot_math_get_constant:
* @font: #hb_font_t from which to retrieve the value * @font: #hb_font_t to work upon
* @constant: #hb_ot_math_constant_t the constant to retrieve * @constant: #hb_ot_math_constant_t the constant to retrieve
* *
* This function returns the requested math constants as a #hb_position_t. * Fetches the specified math constant. For most constants, the value returned
* If the request constant is HB_OT_MATH_CONSTANT_SCRIPT_PERCENT_SCALE_DOWN, * is an #hb_position_t.
* HB_OT_MATH_CONSTANT_SCRIPT_SCRIPT_PERCENT_SCALE_DOWN or
* HB_OT_MATH_CONSTANT_SCRIPT_PERCENT_SCALE_DOWN then the return value is
* actually an integer between 0 and 100 representing that percentage.
* *
* Return value: the requested constant or 0 * However, if the requested constant is #HB_OT_MATH_CONSTANT_SCRIPT_PERCENT_SCALE_DOWN,
* #HB_OT_MATH_CONSTANT_SCRIPT_SCRIPT_PERCENT_SCALE_DOWN or
* #HB_OT_MATH_CONSTANT_SCRIPT_PERCENT_SCALE_DOWN, then the return value is
* an integer between 0 and 100 representing that percentage.
*
* Return value: the requested constant or zero
* *
* Since: 1.3.3 * Since: 1.3.3
**/ **/
@ -85,8 +91,11 @@ hb_ot_math_get_constant (hb_font_t *font,
/** /**
* hb_ot_math_get_glyph_italics_correction: * hb_ot_math_get_glyph_italics_correction:
* @font: #hb_font_t from which to retrieve the value * @font: #hb_font_t to work upon
* @glyph: glyph index from which to retrieve the value * @glyph: The glyph index from which to retrieve the value
*
* Fetches an italics-correction value (if one exists) for the specified
* glyph index.
* *
* Return value: the italics correction of the glyph or 0 * Return value: the italics correction of the glyph or 0
* *
@ -101,8 +110,11 @@ hb_ot_math_get_glyph_italics_correction (hb_font_t *font,
/** /**
* hb_ot_math_get_glyph_top_accent_attachment: * hb_ot_math_get_glyph_top_accent_attachment:
* @font: #hb_font_t from which to retrieve the value * @font: #hb_font_t to work upon
* @glyph: glyph index from which to retrieve the value * @glyph: The glyph index from which to retrieve the value
*
* Fetches a top-accent-attachment value (if one exists) for the specified
* glyph index.
* *
* Return value: the top accent attachment of the glyph or 0 * Return value: the top accent attachment of the glyph or 0
* *
@ -117,8 +129,10 @@ hb_ot_math_get_glyph_top_accent_attachment (hb_font_t *font,
/** /**
* hb_ot_math_is_glyph_extended_shape: * hb_ot_math_is_glyph_extended_shape:
* @face: a #hb_face_t to test * @face: #hb_face_t to work upon
* @glyph: a glyph index to test * @glyph: The glyph index to test
*
* Tests whether the given glyph index is an extended shape in the face.
* *
* Return value: true if the glyph is an extended shape, false otherwise * Return value: true if the glyph is an extended shape, false otherwise
* *
@ -133,18 +147,20 @@ hb_ot_math_is_glyph_extended_shape (hb_face_t *face,
/** /**
* hb_ot_math_get_glyph_kerning: * hb_ot_math_get_glyph_kerning:
* @font: #hb_font_t from which to retrieve the value * @font: #hb_font_t to work upon
* @glyph: glyph index from which to retrieve the value * @glyph: The glyph index from which to retrieve the value
* @kern: the #hb_ot_math_kern_t from which to retrieve the value * @kern: The #hb_ot_math_kern_t from which to retrieve the value
* @correction_height: the correction height to use to determine the kerning. * @correction_height: the correction height to use to determine the kerning.
* *
* This function tries to retrieve the MathKern table for the specified font, * Fetches the MathKern table for the specified font, glyph index, and
* glyph and #hb_ot_math_kern_t. Then it browses the list of heights from the * @kern.
* MathKern table to find one value that is greater or equal to specified
* correction_height. If one is found the corresponding value from the list of
* kerns is returned and otherwise the last kern value is returned.
* *
* Return value: requested kerning or 0 * If the MathKern table is found, the function examines it to find a height
* value that is greater or equal to @correction_height. If such a height
* value is found, corresponding kerning value from the table is returned. If
* no such height value is found, the last kerning value is returned.
*
* Return value: requested kerning value or zero
* *
* Since: 1.3.3 * Since: 1.3.3
**/ **/
@ -162,20 +178,22 @@ hb_ot_math_get_glyph_kerning (hb_font_t *font,
/** /**
* hb_ot_math_get_glyph_variants: * hb_ot_math_get_glyph_variants:
* @font: #hb_font_t from which to retrieve the values * @font: #hb_font_t to work upon
* @glyph: index of the glyph to stretch * @glyph: The index of the glyph to stretch
* @direction: direction of the stretching * @direction: The direction of the stretching (H or V)
* @start_offset: offset of the first variant to retrieve * @start_offset: offset of the first variant to retrieve
* @variants_count: maximum number of variants to retrieve after start_offset * @variants_count: (inout): Input = the maximum number of variants to return;
* (IN) and actual number of variants retrieved (OUT) * Output = the actual number of variants returned
* @variants: array of size at least @variants_count to store the result * @variants: (out) (array length=variants_count): array of variants returned
* *
* This function tries to retrieve the MathGlyphConstruction for the specified * Fetches the MathGlyphConstruction for the specified font, glyph index, and
* font, glyph and direction. Note that only the value of * direction. The corresponding list of size variants is returned as a list of
* #HB_DIRECTION_IS_HORIZONTAL is considered. It provides the corresponding list * #hb_ot_math_glyph_variant_t structs.
* of size variants as an array of hb_ot_math_glyph_variant_t structs.
* *
* Return value: the total number of size variants available or 0 * <note>Note that only the value of #HB_DIRECTION_IS_HORIZONTAL is considered
* from the @direction parameter.</note>
*
* Return value: the total number of size variants available or zero
* *
* Since: 1.3.3 * Since: 1.3.3
**/ **/
@ -195,15 +213,17 @@ hb_ot_math_get_glyph_variants (hb_font_t *font,
/** /**
* hb_ot_math_get_min_connector_overlap: * hb_ot_math_get_min_connector_overlap:
* @font: #hb_font_t from which to retrieve the value * @font: #hb_font_t to work upon
* @direction: direction of the stretching * @direction: direction of the stretching (H or V)
* *
* This function tries to retrieve the MathVariants table for the specified * Fetches the MathVariants table for the specified font and returns the
* font and returns the minimum overlap of connecting glyphs to draw a glyph * minimum overlap of connecting glyphs that are required to draw a glyph
* assembly in the specified direction. Note that only the value of * assembly in the specified direction.
* #HB_DIRECTION_IS_HORIZONTAL is considered.
* *
* Return value: requested min connector overlap or 0 * <note>Note that only the value of #HB_DIRECTION_IS_HORIZONTAL is considered
* from the @direction parameter.</note>
*
* Return value: requested minimum connector overlap or zero
* *
* Since: 1.3.3 * Since: 1.3.3
**/ **/
@ -216,19 +236,22 @@ hb_ot_math_get_min_connector_overlap (hb_font_t *font,
/** /**
* hb_ot_math_get_glyph_assembly: * hb_ot_math_get_glyph_assembly:
* @font: #hb_font_t from which to retrieve the values * @font: #hb_font_t to work upon
* @glyph: index of the glyph to stretch * @glyph: The index of the glyph to stretch
* @direction: direction of the stretching * @direction: direction of the stretching (H or V)
* @start_offset: offset of the first glyph part to retrieve * @start_offset: offset of the first glyph part to retrieve
* @parts_count: maximum number of glyph parts to retrieve after start_offset * @parts_count: (inout): Input = maximum number of glyph parts to return;
* (IN) and actual number of parts retrieved (OUT) * Output = actual number of parts returned
* @parts: array of size at least @parts_count to store the result * @parts: (out) (array length=parts_count): the glyph parts returned
* @italics_correction: italic correction of the glyph assembly * @italics_correction: (out): italics correction of the glyph assembly
* *
* This function tries to retrieve the GlyphAssembly for the specified font, * Fetches the GlyphAssembly for the specified font, glyph index, and direction.
* glyph and direction. Note that only the value of #HB_DIRECTION_IS_HORIZONTAL * Returned are a list of #hb_ot_math_glyph_part_t glyph parts that can be
* is considered. It provides the information necessary to draw the glyph * used to draw the glyph and an italics-correction value (if one is defined
* assembly as an array of #hb_ot_math_glyph_part_t. * in the font).
*
* <note>Note that only the value of #HB_DIRECTION_IS_HORIZONTAL is considered
* from the @direction parameter.</note>
* *
* Return value: the total number of parts in the glyph assembly * Return value: the total number of parts in the glyph assembly
* *

21
src/hb-ot-math.h
View File

@ -50,6 +50,9 @@ HB_BEGIN_DECLS
/** /**
* hb_ot_math_constant_t: * hb_ot_math_constant_t:
* *
* The 'MATH' table constants specified at
* https://docs.microsoft.com/en-us/typography/opentype/spec/math
*
* Since: 1.3.3 * Since: 1.3.3
*/ */
typedef enum { typedef enum {
@ -114,6 +117,9 @@ typedef enum {
/** /**
* hb_ot_math_kern_t: * hb_ot_math_kern_t:
* *
* The math kerning-table types defined for the four corners
* of a glyph.
*
* Since: 1.3.3 * Since: 1.3.3
*/ */
typedef enum { typedef enum {
@ -125,6 +131,10 @@ typedef enum {
/** /**
* hb_ot_math_glyph_variant_t: * hb_ot_math_glyph_variant_t:
* @glyph: The glyph index of the variant
* @advance: The advance width of the variant
*
* Data type to hold math-variant information for a glyph.
* *
* Since: 1.3.3 * Since: 1.3.3
*/ */
@ -136,6 +146,8 @@ typedef struct hb_ot_math_glyph_variant_t {
/** /**
* hb_ot_math_glyph_part_flags_t: * hb_ot_math_glyph_part_flags_t:
* *
* Flags for math glyph parts.
*
* Since: 1.3.3 * Since: 1.3.3
*/ */
typedef enum { /*< flags >*/ typedef enum { /*< flags >*/
@ -144,6 +156,15 @@ typedef enum { /*< flags >*/
/** /**
* hb_ot_math_glyph_part_t: * hb_ot_math_glyph_part_t:
* @glyph: The glyph index of the variant part
* @start_connector_length: The length of the connector on the starting side of the variant part
* @end_connection_length: The length of the conector on the ending side of the variant part
* @full_advance: The total advance of the part
* @flags: #hb_ot_math_glyph_part_flags_t flags for the part
*
* Data type to hold information for a "part" component of a math-variant glyph.
* Large variants for stretchable math glyphs (such as parentheses) can be constructed
* on the fly from parts.
* *
* Since: 1.3.3 * Since: 1.3.3
*/ */