src/hb-ot-math.cc

   1 /*
   2  * Copyright © 2016  Igalia S.L.
   3  *
   4  *  This is part of HarfBuzz, a text shaping library.
   5  *
   6  * Permission is hereby granted, without written agreement and without
   7  * license or royalty fees, to use, copy, modify, and distribute this
   8  * software and its documentation for any purpose, provided that the
   9  * above copyright notice and the following two paragraphs appear in
  10  * all copies of this software.
  11  *
  12  * IN NO EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE TO ANY PARTY FOR
  13  * DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
  14  * ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN
  15  * IF THE COPYRIGHT HOLDER HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
  16  * DAMAGE.
  17  *
  18  * THE COPYRIGHT HOLDER SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING,
  19  * BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
  20  * FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
  21  * ON AN "AS IS" BASIS, AND THE COPYRIGHT HOLDER HAS NO OBLIGATION TO
  22  * PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
  23  *
  24  * Igalia Author(s): Frédéric Wang
  25  */
  26
  27 #include "hb.hh"
  28
  29 #ifndef HB_NO_MATH
  30
  31 #include "hb-ot-math-table.hh"
  32
  33
  34 /**
  35  * SECTION:hb-ot-math
  36  * @title: hb-ot-math
  37  * @short_description: OpenType Math information
  38  * @include: hb-ot.h
  39  *
  40  * Functions for fetching mathematics layout data from OpenType fonts.
  41  *
  42  * HarfBuzz itself does not implement a math layout solution. The
  43  * functions and types provided can be used by client programs to access
  44  * the font data necessary for typesetting OpenType Math layout.
  45  *
  46  **/
  47
  48
  49 /*
  50  * OT::MATH
  51  */
  52
  53 /**
  54  * hb_ot_math_has_data:
  55  * @face: #hb_face_t to test
  56  *
  57  * Tests whether a face has a `MATH` table.
  58  *
  59  * Return value: `true` if the table is found, `false` otherwise
  60  *
  61  * Since: 1.3.3
  62  **/
  63 hb_bool_t
  64 hb_ot_math_has_data (hb_face_t *face)
  65 {
  66   return face->table.MATH->has_data ();
  67 }
  68
  69 /**
  70  * hb_ot_math_get_constant:
  71  * @font: #hb_font_t to work upon
  72  * @constant: #hb_ot_math_constant_t the constant to retrieve
  73  *
  74  * Fetches the specified math constant. For most constants, the value returned
  75  * is an #hb_position_t.
  76  *
  77  * However, if the requested constant is #HB_OT_MATH_CONSTANT_SCRIPT_PERCENT_SCALE_DOWN,
  78  * #HB_OT_MATH_CONSTANT_SCRIPT_SCRIPT_PERCENT_SCALE_DOWN or
  79  * #HB_OT_MATH_CONSTANT_RADICAL_DEGREE_BOTTOM_RAISE_PERCENT, then the return value is
  80  * an integer between 0 and 100 representing that percentage.
  81  *
  82  * Return value: the requested constant or zero
  83  *
  84  * Since: 1.3.3
  85  **/
  86 hb_position_t
  87 hb_ot_math_get_constant (hb_font_t *font,
  88                          hb_ot_math_constant_t constant)
  89 {
  90   return font->face->table.MATH->get_constant(constant, font);
  91 }
  92
  93 /**
  94  * hb_ot_math_get_glyph_italics_correction:
  95  * @font: #hb_font_t to work upon
  96  * @glyph: The glyph index from which to retrieve the value
  97  *
  98  * Fetches an italics-correction value (if one exists) for the specified
  99  * glyph index.
 100  *
 101   * Return value: the italics correction of the glyph or zero
 102  *
 103  * Since: 1.3.3
 104  **/
 105 hb_position_t
 106 hb_ot_math_get_glyph_italics_correction (hb_font_t *font,
 107                                          hb_codepoint_t glyph)
 108 {
 109   return font->face->table.MATH->get_glyph_info().get_italics_correction (glyph, font);
 110 }
 111
 112 /**
 113  * hb_ot_math_get_glyph_top_accent_attachment:
 114  * @font: #hb_font_t to work upon
 115  * @glyph: The glyph index from which to retrieve the value
 116  *
 117  * Fetches a top-accent-attachment value (if one exists) for the specified
 118  * glyph index.
 119  *
 120  * For any glyph that does not have a top-accent-attachment value - that is,
 121  * a glyph not covered by the `MathTopAccentAttachment` table (or, when
 122  * @font has no `MathTopAccentAttachment` table or no `MATH` table, any
 123  * glyph) - the function synthesizes a value, returning the position at
 124  * one-half the glyph's advance width.
 125  *
 126  * Return value: the top accent attachment of the glyph or 0.5 * the advance
 127  *               width of @glyph
 128  *
 129  * Since: 1.3.3
 130  **/
 131 hb_position_t
 132 hb_ot_math_get_glyph_top_accent_attachment (hb_font_t *font,
 133                                             hb_codepoint_t glyph)
 134 {
 135   return font->face->table.MATH->get_glyph_info().get_top_accent_attachment (glyph, font);
 136 }
 137
 138 /**
 139  * hb_ot_math_is_glyph_extended_shape:
 140  * @face: #hb_face_t to work upon
 141  * @glyph: The glyph index to test
 142  *
 143  * Tests whether the given glyph index is an extended shape in the face.
 144  *
 145  * Return value: `true` if the glyph is an extended shape, `false` otherwise
 146  *
 147  * Since: 1.3.3
 148  **/
 149 hb_bool_t
 150 hb_ot_math_is_glyph_extended_shape (hb_face_t *face,
 151                                     hb_codepoint_t glyph)
 152 {
 153   return face->table.MATH->get_glyph_info().is_extended_shape (glyph);
 154 }
 155
 156 /**
 157  * hb_ot_math_get_glyph_kerning:
 158  * @font: #hb_font_t to work upon
 159  * @glyph: The glyph index from which to retrieve the value
 160  * @kern: The #hb_ot_math_kern_t from which to retrieve the value
 161  * @correction_height: the correction height to use to determine the kerning.
 162  *
 163  * Fetches the math kerning (cut-ins) value for the specified font, glyph index, and
 164  * @kern.
 165  *
 166  * If the MathKern table is found, the function examines it to find a height
 167  * value that is greater or equal to @correction_height. If such a height
 168  * value is found, corresponding kerning value from the table is returned. If
 169  * no such height value is found, the last kerning value is returned.
 170  *
 171  * Return value: requested kerning value or zero
 172  *
 173  * Since: 1.3.3
 174  **/
 175 hb_position_t
 176 hb_ot_math_get_glyph_kerning (hb_font_t *font,
 177                               hb_codepoint_t glyph,
 178                               hb_ot_math_kern_t kern,
 179                               hb_position_t correction_height)
 180 {
 181   return font->face->table.MATH->get_glyph_info().get_kerning (glyph,
 182                                                                kern,
 183                                                                correction_height,
 184                                                                font);
 185 }
 186
 187 /**
 188  * hb_ot_math_get_glyph_kernings:
 189  * @font: #hb_font_t to work upon
 190  * @glyph: The glyph index from which to retrieve the kernings
 191  * @kern: The #hb_ot_math_kern_t from which to retrieve the kernings
 192  * @start_offset: offset of the first kern entry to retrieve
 193  * @entries_count: (inout) (optional): Input = the maximum number of kern entries to return;
 194  *                                     Output = the actual number of kern entries returned
 195  * @kern_entries: (out caller-allocates) (array length=entries_count): array of kern entries returned
 196  *
 197  * Fetches the raw MathKern (cut-in) data for the specified font, glyph index,
 198  * and @kern. The corresponding list of kern values and correction heights is
 199  * returned as a list of #hb_ot_math_kern_entry_t structs.
 200  *
 201  * See also #hb_ot_math_get_glyph_kerning, which handles selecting the
 202  * appropriate kern value for a given correction height.
 203  *
 204  * <note>For a glyph with @n defined kern values (where @n > 0), there are only
 205  * @n−1 defined correction heights, as each correction height defines a boundary
 206  * past which the next kern value should be selected. Therefore, only the
 207  * #hb_ot_math_kern_entry_t.kern_value of the uppermost #hb_ot_math_kern_entry_t
 208  * actually comes from the font; its corresponding
 209  * #hb_ot_math_kern_entry_t.max_correction_height is always set to
 210  * <code>INT32_MAX</code>.</note>
 211  *
 212  * Return value: the total number of kern values available or zero
 213  *
 214  * Since: 3.4.0
 215  **/
 216 unsigned int
 217 hb_ot_math_get_glyph_kernings (hb_font_t *font,
 218                                hb_codepoint_t glyph,
 219                                hb_ot_math_kern_t kern,
 220                                unsigned int start_offset,
 221                                unsigned int *entries_count, /* IN/OUT */
 222                                hb_ot_math_kern_entry_t *kern_entries /* OUT */)
 223 {
 224   return font->face->table.MATH->get_glyph_info().get_kernings (glyph,
 225                                                                 kern,
 226                                                                 start_offset,
 227                                                                 entries_count,
 228                                                                 kern_entries,
 229                                                                 font);
 230 }
 231
 232 /**
 233  * hb_ot_math_get_glyph_variants:
 234  * @font: #hb_font_t to work upon
 235  * @glyph: The index of the glyph to stretch
 236  * @direction: The direction of the stretching (horizontal or vertical)
 237  * @start_offset: offset of the first variant to retrieve
 238  * @variants_count: (inout): Input = the maximum number of variants to return;
 239  *                           Output = the actual number of variants returned
 240  * @variants: (out) (array length=variants_count): array of variants returned
 241  *
 242  * Fetches the MathGlyphConstruction for the specified font, glyph index, and
 243  * direction. The corresponding list of size variants is returned as a list of
 244  * #hb_ot_math_glyph_variant_t structs.
 245  *
 246  * <note>The @direction parameter is only used to select between horizontal
 247  * or vertical directions for the construction. Even though all #hb_direction_t
 248  * values are accepted, only the result of #HB_DIRECTION_IS_HORIZONTAL is
 249  * considered.</note>
 250  *
 251  * Return value: the total number of size variants available or zero
 252  *
 253  * Since: 1.3.3
 254  **/
 255 unsigned int
 256 hb_ot_math_get_glyph_variants (hb_font_t *font,
 257                                hb_codepoint_t glyph,
 258                                hb_direction_t direction,
 259                                unsigned int start_offset,
 260                                unsigned int *variants_count, /* IN/OUT */
 261                                hb_ot_math_glyph_variant_t *variants /* OUT */)
 262 {
 263   return font->face->table.MATH->get_variants().get_glyph_variants (glyph, direction, font,
 264                                                                     start_offset,
 265                                                                     variants_count,
 266                                                                     variants);
 267 }
 268
 269 /**
 270  * hb_ot_math_get_min_connector_overlap:
 271  * @font: #hb_font_t to work upon
 272  * @direction: direction of the stretching (horizontal or vertical)
 273  *
 274  * Fetches the MathVariants table for the specified font and returns the
 275  * minimum overlap of connecting glyphs that are required to draw a glyph
 276  * assembly in the specified direction.
 277  *
 278  * <note>The @direction parameter is only used to select between horizontal
 279  * or vertical directions for the construction. Even though all #hb_direction_t
 280  * values are accepted, only the result of #HB_DIRECTION_IS_HORIZONTAL is
 281  * considered.</note>
 282  *
 283  * Return value: requested minimum connector overlap or zero
 284  *
 285  * Since: 1.3.3
 286  **/
 287 hb_position_t
 288 hb_ot_math_get_min_connector_overlap (hb_font_t *font,
 289                                       hb_direction_t direction)
 290 {
 291   return font->face->table.MATH->get_variants().get_min_connector_overlap (direction, font);
 292 }
 293
 294 /**
 295  * hb_ot_math_get_glyph_assembly:
 296  * @font: #hb_font_t to work upon
 297  * @glyph: The index of the glyph to stretch
 298  * @direction: direction of the stretching (horizontal or vertical)
 299  * @start_offset: offset of the first glyph part to retrieve
 300  * @parts_count: (inout): Input = maximum number of glyph parts to return;
 301  *               Output = actual number of parts returned
 302  * @parts: (out) (array length=parts_count): the glyph parts returned
 303  * @italics_correction: (out): italics correction of the glyph assembly
 304  *
 305  * Fetches the GlyphAssembly for the specified font, glyph index, and direction.
 306  * Returned are a list of #hb_ot_math_glyph_part_t glyph parts that can be
 307  * used to draw the glyph and an italics-correction value (if one is defined
 308  * in the font).
 309  *
 310  * <note>The @direction parameter is only used to select between horizontal
 311  * or vertical directions for the construction. Even though all #hb_direction_t
 312  * values are accepted, only the result of #HB_DIRECTION_IS_HORIZONTAL is
 313  * considered.</note>
 314  *
 315  * Return value: the total number of parts in the glyph assembly
 316  *
 317  * Since: 1.3.3
 318  **/
 319 unsigned int
 320 hb_ot_math_get_glyph_assembly (hb_font_t *font,
 321                                hb_codepoint_t glyph,
 322                                hb_direction_t direction,
 323                                unsigned int start_offset,
 324                                unsigned int *parts_count, /* IN/OUT */
 325                                hb_ot_math_glyph_part_t *parts, /* OUT */
 326                                hb_position_t *italics_correction /* OUT */)
 327 {
 328   return font->face->table.MATH->get_variants().get_glyph_parts (glyph,
 329                                                                  direction,
 330                                                                  font,
 331                                                                  start_offset,
 332                                                                  parts_count,
 333                                                                  parts,
 334                                                                  italics_correction);
 335 }
 336
 337
 338 #endif