src/hb-buffer.h

   1 /*
   2  * Copyright © 1998-2004  David Turner and Werner Lemberg
   3  * Copyright © 2004,2007,2009  Red Hat, Inc.
   4  * Copyright © 2011,2012  Google, Inc.
   5  *
   6  *  This is part of HarfBuzz, a text shaping library.
   7  *
   8  * Permission is hereby granted, without written agreement and without
   9  * license or royalty fees, to use, copy, modify, and distribute this
  10  * software and its documentation for any purpose, provided that the
  11  * above copyright notice and the following two paragraphs appear in
  12  * all copies of this software.
  13  *
  14  * IN NO EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE TO ANY PARTY FOR
  15  * DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
  16  * ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN
  17  * IF THE COPYRIGHT HOLDER HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
  18  * DAMAGE.
  19  *
  20  * THE COPYRIGHT HOLDER SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING,
  21  * BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
  22  * FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
  23  * ON AN "AS IS" BASIS, AND THE COPYRIGHT HOLDER HAS NO OBLIGATION TO
  24  * PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
  25  *
  26  * Red Hat Author(s): Owen Taylor, Behdad Esfahbod
  27  * Google Author(s): Behdad Esfahbod
  28  */
  29
  30 #if !defined(HB_H_IN) && !defined(HB_NO_SINGLE_HEADER_ERROR)
  31 #error "Include <hb.h> instead."
  32 #endif
  33
  34 #ifndef HB_BUFFER_H
  35 #define HB_BUFFER_H
  36
  37 #include "hb-common.h"
  38 #include "hb-unicode.h"
  39 #include "hb-font.h"
  40
  41 HB_BEGIN_DECLS
  42
  43 /**
  44  * hb_glyph_info_t:
  45  * @codepoint: either a Unicode code point (before shaping) or a glyph index
  46  *             (after shaping).
  47  * @cluster: the index of the character in the original text that corresponds
  48  *           to this #hb_glyph_info_t, or whatever the client passes to
  49  *           hb_buffer_add(). More than one #hb_glyph_info_t can have the same
  50  *           @cluster value, if they resulted from the same character (e.g. one
  51  *           to many glyph substitution), and when more than one character gets
  52  *           merged in the same glyph (e.g. many to one glyph substitution) the
  53  *           #hb_glyph_info_t will have the smallest cluster value of them.
  54  *           By default some characters are merged into the same cluster
  55  *           (e.g. combining marks have the same cluster as their bases)
  56  *           even if they are separate glyphs, hb_buffer_set_cluster_level()
  57  *           allow selecting more fine-grained cluster handling.
  58  *
  59  * The #hb_glyph_info_t is the structure that holds information about the
  60  * glyphs and their relation to input text.
  61  */
  62 typedef struct hb_glyph_info_t {
  63   hb_codepoint_t codepoint;
  64   /*< private >*/
  65   hb_mask_t      mask;
  66   /*< public >*/
  67   uint32_t       cluster;
  68
  69   /*< private >*/
  70   hb_var_int_t   var1;
  71   hb_var_int_t   var2;
  72 } hb_glyph_info_t;
  73
  74 /**
  75  * hb_glyph_flags_t:
  76  * @HB_GLYPH_FLAG_UNSAFE_TO_BREAK: Indicates that if input text is broken at the
  77  *                                 beginning of the cluster this glyph is part of,
  78  *                                 then both sides need to be re-shaped, as the
  79  *                                 result might be different.
  80  *                                 On the flip side, it means that when this
  81  *                                 flag is not present, then it is safe to break
  82  *                                 the glyph-run at the beginning of this
  83  *                                 cluster, and the two sides will represent the
  84  *                                 exact same result one would get if breaking
  85  *                                 input text at the beginning of this cluster
  86  *                                 and shaping the two sides separately.
  87  *                                 This can be used to optimize paragraph
  88  *                                 layout, by avoiding re-shaping of each line
  89  *                                 after line-breaking.
  90  * @HB_GLYPH_FLAG_UNSAFE_TO_CONCAT: Indicates that if input text is changed on one
  91  *                                 side of the beginning of the cluster this glyph
  92  *                                 is part of, then the shaping results for the
  93  *                                 other side might change.
  94  *                                 Note that the absence of this flag will NOT by
  95  *                                 itself mean that it IS safe to concat text.
  96  *                                 Only two pieces of text both of which clear of
  97  *                                 this flag can be concatenated safely.
  98  *                                 This can be used to optimize paragraph
  99  *                                 layout, by avoiding re-shaping of each line
 100  *                                 after line-breaking, by limiting the
 101  *                                 reshaping to a small piece around the
 102  *                                 breaking positin only, even if the breaking
 103  *                                 position carries the
 104  *                                 #HB_GLYPH_FLAG_UNSAFE_TO_BREAK or when
 105  *                                 hyphenation or other text transformation
 106  *                                 happens at line-break position, in the following
 107  *                                 way:
 108  *                                 1. Iterate back from the line-break position
 109  *                                 until the first cluster start position that is
 110  *                                 NOT unsafe-to-concat, 2. shape the segment from
 111  *                                 there till the end of line, 3. check whether the
 112  *                                 resulting glyph-run also is clear of the
 113  *                                 unsafe-to-concat at its start-of-text position;
 114  *                                 if it is, just splice it into place and the line
 115  *                                 is shaped; If not, move on to a position further
 116  *                                 back that is clear of unsafe-to-concat and retry
 117  *                                 from there, and repeat.
 118  *                                 At the start of next line a similar algorithm can
 119  *                                 be implemented. That is: 1. Iterate forward from
 120  *                                 the line-break position untill the first cluster
 121  *                                 start position that is NOT unsafe-to-concat, 2.
 122  *                                 shape the segment from beginning of the line to
 123  *                                 that position, 3. check whether the resulting
 124  *                                 glyph-run also is clear of the unsafe-to-concat
 125  *                                 at its end-of-text position; if it is, just splice
 126  *                                 it into place and the beginning is shaped; If not,
 127  *                                 move on to a position further forward that is clear
 128  *                                 of unsafe-to-concat and retry up to there, and repeat.
 129  *                                 A slight complication will arise in the
 130  *                                 implementation of the algorithm above,
 131  *                                 because while our buffer API has a way to
 132  *                                 return flags for position corresponding to
 133  *                                 start-of-text, there is currently no position
 134  *                                 corresponding to end-of-text.  This limitation
 135  *                                 can be alleviated by shaping more text than needed
 136  *                                 and looking for unsafe-to-concat flag within text
 137  *                                 clusters.
 138  *                                 The #HB_GLYPH_FLAG_UNSAFE_TO_BREAK flag will
 139  *                                 always imply this flag.
 140  *                                 Since: 3.3.0
 141  * @HB_GLYPH_FLAG_DEFINED: All the currently defined flags.
 142  *
 143  * Flags for #hb_glyph_info_t.
 144  *
 145  * Since: 1.5.0
 146  */
 147 typedef enum { /*< flags >*/
 148   HB_GLYPH_FLAG_UNSAFE_TO_BREAK         = 0x00000001,
 149   HB_GLYPH_FLAG_UNSAFE_TO_CONCAT        = 0x00000002,
 150
 151   HB_GLYPH_FLAG_DEFINED                 = 0x00000003 /* OR of all defined flags */
 152 } hb_glyph_flags_t;
 153
 154 HB_EXTERN hb_glyph_flags_t
 155 hb_glyph_info_get_glyph_flags (const hb_glyph_info_t *info);
 156
 157 #define hb_glyph_info_get_glyph_flags(info) \
 158         ((hb_glyph_flags_t) ((unsigned int) (info)->mask & HB_GLYPH_FLAG_DEFINED))
 159
 160
 161 /**
 162  * hb_glyph_position_t:
 163  * @x_advance: how much the line advances after drawing this glyph when setting
 164  *             text in horizontal direction.
 165  * @y_advance: how much the line advances after drawing this glyph when setting
 166  *             text in vertical direction.
 167  * @x_offset: how much the glyph moves on the X-axis before drawing it, this
 168  *            should not affect how much the line advances.
 169  * @y_offset: how much the glyph moves on the Y-axis before drawing it, this
 170  *            should not affect how much the line advances.
 171  *
 172  * The #hb_glyph_position_t is the structure that holds the positions of the
 173  * glyph in both horizontal and vertical directions. All positions in
 174  * #hb_glyph_position_t are relative to the current point.
 175  *
 176  */
 177 typedef struct hb_glyph_position_t {
 178   hb_position_t  x_advance;
 179   hb_position_t  y_advance;
 180   hb_position_t  x_offset;
 181   hb_position_t  y_offset;
 182
 183   /*< private >*/
 184   hb_var_int_t   var;
 185 } hb_glyph_position_t;
 186
 187 /**
 188  * hb_segment_properties_t:
 189  * @direction: the #hb_direction_t of the buffer, see hb_buffer_set_direction().
 190  * @script: the #hb_script_t of the buffer, see hb_buffer_set_script().
 191  * @language: the #hb_language_t of the buffer, see hb_buffer_set_language().
 192  *
 193  * The structure that holds various text properties of an #hb_buffer_t. Can be
 194  * set and retrieved using hb_buffer_set_segment_properties() and
 195  * hb_buffer_get_segment_properties(), respectively.
 196  */
 197 typedef struct hb_segment_properties_t {
 198   hb_direction_t  direction;
 199   hb_script_t     script;
 200   hb_language_t   language;
 201   /*< private >*/
 202   void           *reserved1;
 203   void           *reserved2;
 204 } hb_segment_properties_t;
 205
 206 /**
 207  * HB_SEGMENT_PROPERTIES_DEFAULT:
 208  *
 209  * The default #hb_segment_properties_t of of freshly created #hb_buffer_t.
 210  */
 211 #define HB_SEGMENT_PROPERTIES_DEFAULT {HB_DIRECTION_INVALID, \
 212                                        HB_SCRIPT_INVALID, \
 213                                        HB_LANGUAGE_INVALID, \
 214                                        (void *) 0, \
 215                                        (void *) 0}
 216
 217 HB_EXTERN hb_bool_t
 218 hb_segment_properties_equal (const hb_segment_properties_t *a,
 219                              const hb_segment_properties_t *b);
 220
 221 HB_EXTERN unsigned int
 222 hb_segment_properties_hash (const hb_segment_properties_t *p);
 223
 224 HB_EXTERN void
 225 hb_segment_properties_overlay (hb_segment_properties_t *p,
 226                                const hb_segment_properties_t *src);
 227
 228
 229 /**
 230  * hb_buffer_t:
 231  *
 232  * The main structure holding the input text and its properties before shaping,
 233  * and output glyphs and their information after shaping.
 234  */
 235
 236 typedef struct hb_buffer_t hb_buffer_t;
 237
 238 HB_EXTERN hb_buffer_t *
 239 hb_buffer_create (void);
 240
 241 HB_EXTERN hb_buffer_t *
 242 hb_buffer_create_similar (const hb_buffer_t *src);
 243
 244 HB_EXTERN void
 245 hb_buffer_reset (hb_buffer_t *buffer);
 246
 247
 248 HB_EXTERN hb_buffer_t *
 249 hb_buffer_get_empty (void);
 250
 251 HB_EXTERN hb_buffer_t *
 252 hb_buffer_reference (hb_buffer_t *buffer);
 253
 254 HB_EXTERN void
 255 hb_buffer_destroy (hb_buffer_t *buffer);
 256
 257 HB_EXTERN hb_bool_t
 258 hb_buffer_set_user_data (hb_buffer_t        *buffer,
 259                          hb_user_data_key_t *key,
 260                          void *              data,
 261                          hb_destroy_func_t   destroy,
 262                          hb_bool_t           replace);
 263
 264 HB_EXTERN void *
 265 hb_buffer_get_user_data (hb_buffer_t        *buffer,
 266                          hb_user_data_key_t *key);
 267
 268
 269 /**
 270  * hb_buffer_content_type_t:
 271  * @HB_BUFFER_CONTENT_TYPE_INVALID: Initial value for new buffer.
 272  * @HB_BUFFER_CONTENT_TYPE_UNICODE: The buffer contains input characters (before shaping).
 273  * @HB_BUFFER_CONTENT_TYPE_GLYPHS: The buffer contains output glyphs (after shaping).
 274  *
 275  * The type of #hb_buffer_t contents.
 276  */
 277 typedef enum {
 278   HB_BUFFER_CONTENT_TYPE_INVALID = 0,
 279   HB_BUFFER_CONTENT_TYPE_UNICODE,
 280   HB_BUFFER_CONTENT_TYPE_GLYPHS
 281 } hb_buffer_content_type_t;
 282
 283 HB_EXTERN void
 284 hb_buffer_set_content_type (hb_buffer_t              *buffer,
 285                             hb_buffer_content_type_t  content_type);
 286
 287 HB_EXTERN hb_buffer_content_type_t
 288 hb_buffer_get_content_type (hb_buffer_t *buffer);
 289
 290
 291 HB_EXTERN void
 292 hb_buffer_set_unicode_funcs (hb_buffer_t        *buffer,
 293                              hb_unicode_funcs_t *unicode_funcs);
 294
 295 HB_EXTERN hb_unicode_funcs_t *
 296 hb_buffer_get_unicode_funcs (hb_buffer_t        *buffer);
 297
 298 HB_EXTERN void
 299 hb_buffer_set_direction (hb_buffer_t    *buffer,
 300                          hb_direction_t  direction);
 301
 302 HB_EXTERN hb_direction_t
 303 hb_buffer_get_direction (hb_buffer_t *buffer);
 304
 305 HB_EXTERN void
 306 hb_buffer_set_script (hb_buffer_t *buffer,
 307                       hb_script_t  script);
 308
 309 HB_EXTERN hb_script_t
 310 hb_buffer_get_script (hb_buffer_t *buffer);
 311
 312 HB_EXTERN void
 313 hb_buffer_set_language (hb_buffer_t   *buffer,
 314                         hb_language_t  language);
 315
 316
 317 HB_EXTERN hb_language_t
 318 hb_buffer_get_language (hb_buffer_t *buffer);
 319
 320 HB_EXTERN void
 321 hb_buffer_set_segment_properties (hb_buffer_t *buffer,
 322                                   const hb_segment_properties_t *props);
 323
 324 HB_EXTERN void
 325 hb_buffer_get_segment_properties (hb_buffer_t *buffer,
 326                                   hb_segment_properties_t *props);
 327
 328 HB_EXTERN void
 329 hb_buffer_guess_segment_properties (hb_buffer_t *buffer);
 330
 331
 332 /**
 333  * hb_buffer_flags_t:
 334  * @HB_BUFFER_FLAG_DEFAULT: the default buffer flag.
 335  * @HB_BUFFER_FLAG_BOT: flag indicating that special handling of the beginning
 336  *                      of text paragraph can be applied to this buffer. Should usually
 337  *                      be set, unless you are passing to the buffer only part
 338  *                      of the text without the full context.
 339  * @HB_BUFFER_FLAG_EOT: flag indicating that special handling of the end of text
 340  *                      paragraph can be applied to this buffer, similar to
 341  *                      @HB_BUFFER_FLAG_BOT.
 342  * @HB_BUFFER_FLAG_PRESERVE_DEFAULT_IGNORABLES:
 343  *                      flag indication that character with Default_Ignorable
 344  *                      Unicode property should use the corresponding glyph
 345  *                      from the font, instead of hiding them (done by
 346  *                      replacing them with the space glyph and zeroing the
 347  *                      advance width.)  This flag takes precedence over
 348  *                      @HB_BUFFER_FLAG_REMOVE_DEFAULT_IGNORABLES.
 349  * @HB_BUFFER_FLAG_REMOVE_DEFAULT_IGNORABLES:
 350  *                      flag indication that character with Default_Ignorable
 351  *                      Unicode property should be removed from glyph string
 352  *                      instead of hiding them (done by replacing them with the
 353  *                      space glyph and zeroing the advance width.)
 354  *                      @HB_BUFFER_FLAG_PRESERVE_DEFAULT_IGNORABLES takes
 355  *                      precedence over this flag. Since: 1.8.0
 356  * @HB_BUFFER_FLAG_DO_NOT_INSERT_DOTTED_CIRCLE:
 357  *                      flag indicating that a dotted circle should
 358  *                      not be inserted in the rendering of incorrect
 359  *                      character sequences (such at <0905 093E>). Since: 2.4.0
 360  * @HB_BUFFER_FLAG_VERIFY:
 361  *                      flag indicating that the hb_shape() call and its variants
 362  *                      should perform various verification processes on the results
 363  *                      of the shaping operation on the buffer.  If the verification
 364  *                      fails, then either a buffer message is sent, if a message
 365  *                      handler is installed on the buffer, or a message is written
 366  *                      to standard error.  In either case, the shaping result might
 367  *                      be modified to show the failed output. Since: 3.4.0
 368  *
 369  * Flags for #hb_buffer_t.
 370  *
 371  * Since: 0.9.20
 372  */
 373 typedef enum { /*< flags >*/
 374   HB_BUFFER_FLAG_DEFAULT                        = 0x00000000u,
 375   HB_BUFFER_FLAG_BOT                            = 0x00000001u, /* Beginning-of-text */
 376   HB_BUFFER_FLAG_EOT                            = 0x00000002u, /* End-of-text */
 377   HB_BUFFER_FLAG_PRESERVE_DEFAULT_IGNORABLES    = 0x00000004u,
 378   HB_BUFFER_FLAG_REMOVE_DEFAULT_IGNORABLES      = 0x00000008u,
 379   HB_BUFFER_FLAG_DO_NOT_INSERT_DOTTED_CIRCLE    = 0x00000010u,
 380   HB_BUFFER_FLAG_VERIFY                         = 0x00000020u
 381 } hb_buffer_flags_t;
 382
 383 HB_EXTERN void
 384 hb_buffer_set_flags (hb_buffer_t       *buffer,
 385                      hb_buffer_flags_t  flags);
 386
 387 HB_EXTERN hb_buffer_flags_t
 388 hb_buffer_get_flags (hb_buffer_t *buffer);
 389
 390 /**
 391  * hb_buffer_cluster_level_t:
 392  * @HB_BUFFER_CLUSTER_LEVEL_MONOTONE_GRAPHEMES: Return cluster values grouped by graphemes into
 393  *   monotone order.
 394  * @HB_BUFFER_CLUSTER_LEVEL_MONOTONE_CHARACTERS: Return cluster values grouped into monotone order.
 395  * @HB_BUFFER_CLUSTER_LEVEL_CHARACTERS: Don't group cluster values.
 396  * @HB_BUFFER_CLUSTER_LEVEL_DEFAULT: Default cluster level,
 397  *   equal to @HB_BUFFER_CLUSTER_LEVEL_MONOTONE_GRAPHEMES.
 398  *
 399  * Data type for holding HarfBuzz's clustering behavior options. The cluster level
 400  * dictates one aspect of how HarfBuzz will treat non-base characters
 401  * during shaping.
 402  *
 403  * In @HB_BUFFER_CLUSTER_LEVEL_MONOTONE_GRAPHEMES, non-base
 404  * characters are merged into the cluster of the base character that precedes them.
 405  *
 406  * In @HB_BUFFER_CLUSTER_LEVEL_MONOTONE_CHARACTERS, non-base characters are initially
 407  * assigned their own cluster values, which are not merged into preceding base
 408  * clusters. This allows HarfBuzz to perform additional operations like reorder
 409  * sequences of adjacent marks.
 410  *
 411  * @HB_BUFFER_CLUSTER_LEVEL_MONOTONE_GRAPHEMES is the default, because it maintains
 412  * backward compatibility with older versions of HarfBuzz. New client programs that
 413  * do not need to maintain such backward compatibility are recommended to use
 414  * @HB_BUFFER_CLUSTER_LEVEL_MONOTONE_CHARACTERS instead of the default.
 415  *
 416  * Since: 0.9.42
 417  */
 418 typedef enum {
 419   HB_BUFFER_CLUSTER_LEVEL_MONOTONE_GRAPHEMES    = 0,
 420   HB_BUFFER_CLUSTER_LEVEL_MONOTONE_CHARACTERS   = 1,
 421   HB_BUFFER_CLUSTER_LEVEL_CHARACTERS            = 2,
 422   HB_BUFFER_CLUSTER_LEVEL_DEFAULT = HB_BUFFER_CLUSTER_LEVEL_MONOTONE_GRAPHEMES
 423 } hb_buffer_cluster_level_t;
 424
 425 HB_EXTERN void
 426 hb_buffer_set_cluster_level (hb_buffer_t               *buffer,
 427                              hb_buffer_cluster_level_t  cluster_level);
 428
 429 HB_EXTERN hb_buffer_cluster_level_t
 430 hb_buffer_get_cluster_level (hb_buffer_t *buffer);
 431
 432 /**
 433  * HB_BUFFER_REPLACEMENT_CODEPOINT_DEFAULT:
 434  *
 435  * The default code point for replacing invalid characters in a given encoding.
 436  * Set to U+FFFD REPLACEMENT CHARACTER.
 437  *
 438  * Since: 0.9.31
 439  */
 440 #define HB_BUFFER_REPLACEMENT_CODEPOINT_DEFAULT 0xFFFDu
 441
 442 HB_EXTERN void
 443 hb_buffer_set_replacement_codepoint (hb_buffer_t    *buffer,
 444                                      hb_codepoint_t  replacement);
 445
 446 HB_EXTERN hb_codepoint_t
 447 hb_buffer_get_replacement_codepoint (hb_buffer_t    *buffer);
 448
 449 HB_EXTERN void
 450 hb_buffer_set_invisible_glyph (hb_buffer_t    *buffer,
 451                                hb_codepoint_t  invisible);
 452
 453 HB_EXTERN hb_codepoint_t
 454 hb_buffer_get_invisible_glyph (hb_buffer_t    *buffer);
 455
 456 HB_EXTERN void
 457 hb_buffer_set_not_found_glyph (hb_buffer_t    *buffer,
 458                                hb_codepoint_t  not_found);
 459
 460 HB_EXTERN hb_codepoint_t
 461 hb_buffer_get_not_found_glyph (hb_buffer_t    *buffer);
 462
 463
 464 /*
 465  * Content API.
 466  */
 467
 468 HB_EXTERN void
 469 hb_buffer_clear_contents (hb_buffer_t *buffer);
 470
 471 HB_EXTERN hb_bool_t
 472 hb_buffer_pre_allocate (hb_buffer_t  *buffer,
 473                         unsigned int  size);
 474
 475
 476 HB_EXTERN hb_bool_t
 477 hb_buffer_allocation_successful (hb_buffer_t  *buffer);
 478
 479 HB_EXTERN void
 480 hb_buffer_reverse (hb_buffer_t *buffer);
 481
 482 HB_EXTERN void
 483 hb_buffer_reverse_range (hb_buffer_t *buffer,
 484                          unsigned int start, unsigned int end);
 485
 486 HB_EXTERN void
 487 hb_buffer_reverse_clusters (hb_buffer_t *buffer);
 488
 489
 490 /* Filling the buffer in */
 491
 492 HB_EXTERN void
 493 hb_buffer_add (hb_buffer_t    *buffer,
 494                hb_codepoint_t  codepoint,
 495                unsigned int    cluster);
 496
 497 HB_EXTERN void
 498 hb_buffer_add_utf8 (hb_buffer_t  *buffer,
 499                     const char   *text,
 500                     int           text_length,
 501                     unsigned int  item_offset,
 502                     int           item_length);
 503
 504 HB_EXTERN void
 505 hb_buffer_add_utf16 (hb_buffer_t    *buffer,
 506                      const uint16_t *text,
 507                      int             text_length,
 508                      unsigned int    item_offset,
 509                      int             item_length);
 510
 511 HB_EXTERN void
 512 hb_buffer_add_utf32 (hb_buffer_t    *buffer,
 513                      const uint32_t *text,
 514                      int             text_length,
 515                      unsigned int    item_offset,
 516                      int             item_length);
 517
 518 HB_EXTERN void
 519 hb_buffer_add_latin1 (hb_buffer_t   *buffer,
 520                       const uint8_t *text,
 521                       int            text_length,
 522                       unsigned int   item_offset,
 523                       int            item_length);
 524
 525 HB_EXTERN void
 526 hb_buffer_add_codepoints (hb_buffer_t          *buffer,
 527                           const hb_codepoint_t *text,
 528                           int                   text_length,
 529                           unsigned int          item_offset,
 530                           int                   item_length);
 531
 532 HB_EXTERN void
 533 hb_buffer_append (hb_buffer_t *buffer,
 534                   const hb_buffer_t *source,
 535                   unsigned int start,
 536                   unsigned int end);
 537
 538 HB_EXTERN hb_bool_t
 539 hb_buffer_set_length (hb_buffer_t  *buffer,
 540                       unsigned int  length);
 541
 542 HB_EXTERN unsigned int
 543 hb_buffer_get_length (hb_buffer_t *buffer);
 544
 545 /* Getting glyphs out of the buffer */
 546
 547 HB_EXTERN hb_glyph_info_t *
 548 hb_buffer_get_glyph_infos (hb_buffer_t  *buffer,
 549                            unsigned int *length);
 550
 551 HB_EXTERN hb_glyph_position_t *
 552 hb_buffer_get_glyph_positions (hb_buffer_t  *buffer,
 553                                unsigned int *length);
 554
 555 HB_EXTERN hb_bool_t
 556 hb_buffer_has_positions (hb_buffer_t  *buffer);
 557
 558
 559 HB_EXTERN void
 560 hb_buffer_normalize_glyphs (hb_buffer_t *buffer);
 561
 562
 563 /*
 564  * Serialize
 565  */
 566
 567 /**
 568  * hb_buffer_serialize_flags_t:
 569  * @HB_BUFFER_SERIALIZE_FLAG_DEFAULT: serialize glyph names, clusters and positions.
 570  * @HB_BUFFER_SERIALIZE_FLAG_NO_CLUSTERS: do not serialize glyph cluster.
 571  * @HB_BUFFER_SERIALIZE_FLAG_NO_POSITIONS: do not serialize glyph position information.
 572  * @HB_BUFFER_SERIALIZE_FLAG_NO_GLYPH_NAMES: do no serialize glyph name.
 573  * @HB_BUFFER_SERIALIZE_FLAG_GLYPH_EXTENTS: serialize glyph extents.
 574  * @HB_BUFFER_SERIALIZE_FLAG_GLYPH_FLAGS: serialize glyph flags. Since: 1.5.0
 575  * @HB_BUFFER_SERIALIZE_FLAG_NO_ADVANCES: do not serialize glyph advances,
 576  *  glyph offsets will reflect absolute glyph positions. Since: 1.8.0
 577  *
 578  * Flags that control what glyph information are serialized in hb_buffer_serialize_glyphs().
 579  *
 580  * Since: 0.9.20
 581  */
 582 typedef enum { /*< flags >*/
 583   HB_BUFFER_SERIALIZE_FLAG_DEFAULT              = 0x00000000u,
 584   HB_BUFFER_SERIALIZE_FLAG_NO_CLUSTERS          = 0x00000001u,
 585   HB_BUFFER_SERIALIZE_FLAG_NO_POSITIONS         = 0x00000002u,
 586   HB_BUFFER_SERIALIZE_FLAG_NO_GLYPH_NAMES       = 0x00000004u,
 587   HB_BUFFER_SERIALIZE_FLAG_GLYPH_EXTENTS        = 0x00000008u,
 588   HB_BUFFER_SERIALIZE_FLAG_GLYPH_FLAGS          = 0x00000010u,
 589   HB_BUFFER_SERIALIZE_FLAG_NO_ADVANCES          = 0x00000020u
 590 } hb_buffer_serialize_flags_t;
 591
 592 /**
 593  * hb_buffer_serialize_format_t:
 594  * @HB_BUFFER_SERIALIZE_FORMAT_TEXT: a human-readable, plain text format.
 595  * @HB_BUFFER_SERIALIZE_FORMAT_JSON: a machine-readable JSON format.
 596  * @HB_BUFFER_SERIALIZE_FORMAT_INVALID: invalid format.
 597  *
 598  * The buffer serialization and de-serialization format used in
 599  * hb_buffer_serialize_glyphs() and hb_buffer_deserialize_glyphs().
 600  *
 601  * Since: 0.9.2
 602  */
 603 typedef enum {
 604   HB_BUFFER_SERIALIZE_FORMAT_TEXT       = HB_TAG('T','E','X','T'),
 605   HB_BUFFER_SERIALIZE_FORMAT_JSON       = HB_TAG('J','S','O','N'),
 606   HB_BUFFER_SERIALIZE_FORMAT_INVALID    = HB_TAG_NONE
 607 } hb_buffer_serialize_format_t;
 608
 609 HB_EXTERN hb_buffer_serialize_format_t
 610 hb_buffer_serialize_format_from_string (const char *str, int len);
 611
 612 HB_EXTERN const char *
 613 hb_buffer_serialize_format_to_string (hb_buffer_serialize_format_t format);
 614
 615 HB_EXTERN const char **
 616 hb_buffer_serialize_list_formats (void);
 617
 618 HB_EXTERN unsigned int
 619 hb_buffer_serialize_glyphs (hb_buffer_t *buffer,
 620                             unsigned int start,
 621                             unsigned int end,
 622                             char *buf,
 623                             unsigned int buf_size,
 624                             unsigned int *buf_consumed,
 625                             hb_font_t *font,
 626                             hb_buffer_serialize_format_t format,
 627                             hb_buffer_serialize_flags_t flags);
 628
 629 HB_EXTERN unsigned int
 630 hb_buffer_serialize_unicode (hb_buffer_t *buffer,
 631                              unsigned int start,
 632                              unsigned int end,
 633                              char *buf,
 634                              unsigned int buf_size,
 635                              unsigned int *buf_consumed,
 636                              hb_buffer_serialize_format_t format,
 637                              hb_buffer_serialize_flags_t flags);
 638
 639 HB_EXTERN unsigned int
 640 hb_buffer_serialize (hb_buffer_t *buffer,
 641                      unsigned int start,
 642                      unsigned int end,
 643                      char *buf,
 644                      unsigned int buf_size,
 645                      unsigned int *buf_consumed,
 646                      hb_font_t *font,
 647                      hb_buffer_serialize_format_t format,
 648                      hb_buffer_serialize_flags_t flags);
 649
 650 HB_EXTERN hb_bool_t
 651 hb_buffer_deserialize_glyphs (hb_buffer_t *buffer,
 652                               const char *buf,
 653                               int buf_len,
 654                               const char **end_ptr,
 655                               hb_font_t *font,
 656                               hb_buffer_serialize_format_t format);
 657
 658 HB_EXTERN hb_bool_t
 659 hb_buffer_deserialize_unicode (hb_buffer_t *buffer,
 660                                const char *buf,
 661                                int buf_len,
 662                                const char **end_ptr,
 663                                hb_buffer_serialize_format_t format);
 664
 665
 666
 667 /*
 668  * Compare buffers
 669  */
 670
 671 /**
 672  * hb_buffer_diff_flags_t:
 673  * @HB_BUFFER_DIFF_FLAG_EQUAL: equal buffers.
 674  * @HB_BUFFER_DIFF_FLAG_CONTENT_TYPE_MISMATCH: buffers with different
 675  *     #hb_buffer_content_type_t.
 676  * @HB_BUFFER_DIFF_FLAG_LENGTH_MISMATCH: buffers with differing length.
 677  * @HB_BUFFER_DIFF_FLAG_NOTDEF_PRESENT: `.notdef` glyph is present in the
 678  *     reference buffer.
 679  * @HB_BUFFER_DIFF_FLAG_DOTTED_CIRCLE_PRESENT: dotted circle glyph is present
 680  *     in the reference buffer.
 681  * @HB_BUFFER_DIFF_FLAG_CODEPOINT_MISMATCH: difference in #hb_glyph_info_t.codepoint
 682  * @HB_BUFFER_DIFF_FLAG_CLUSTER_MISMATCH: difference in #hb_glyph_info_t.cluster
 683  * @HB_BUFFER_DIFF_FLAG_GLYPH_FLAGS_MISMATCH: difference in #hb_glyph_flags_t.
 684  * @HB_BUFFER_DIFF_FLAG_POSITION_MISMATCH: difference in #hb_glyph_position_t.
 685  *
 686  * Flags from comparing two #hb_buffer_t's.
 687  *
 688  * Buffer with different #hb_buffer_content_type_t cannot be meaningfully
 689  * compared in any further detail.
 690  *
 691  * For buffers with differing length, the per-glyph comparison is not
 692  * attempted, though we do still scan reference buffer for dotted circle and
 693  * `.notdef` glyphs.
 694  *
 695  * If the buffers have the same length, we compare them glyph-by-glyph and
 696  * report which aspect(s) of the glyph info/position are different.
 697  *
 698  * Since: 1.5.0
 699  */
 700 typedef enum { /*< flags >*/
 701   HB_BUFFER_DIFF_FLAG_EQUAL                     = 0x0000,
 702
 703   /* Buffers with different content_type cannot be meaningfully compared
 704    * in any further detail. */
 705   HB_BUFFER_DIFF_FLAG_CONTENT_TYPE_MISMATCH     = 0x0001,
 706
 707   /* For buffers with differing length, the per-glyph comparison is not
 708    * attempted, though we do still scan reference for dottedcircle / .notdef
 709    * glyphs. */
 710   HB_BUFFER_DIFF_FLAG_LENGTH_MISMATCH           = 0x0002,
 711
 712   /* We want to know if dottedcircle / .notdef glyphs are present in the
 713    * reference, as we may not care so much about other differences in this
 714    * case. */
 715   HB_BUFFER_DIFF_FLAG_NOTDEF_PRESENT            = 0x0004,
 716   HB_BUFFER_DIFF_FLAG_DOTTED_CIRCLE_PRESENT     = 0x0008,
 717
 718   /* If the buffers have the same length, we compare them glyph-by-glyph
 719    * and report which aspect(s) of the glyph info/position are different. */
 720   HB_BUFFER_DIFF_FLAG_CODEPOINT_MISMATCH        = 0x0010,
 721   HB_BUFFER_DIFF_FLAG_CLUSTER_MISMATCH          = 0x0020,
 722   HB_BUFFER_DIFF_FLAG_GLYPH_FLAGS_MISMATCH      = 0x0040,
 723   HB_BUFFER_DIFF_FLAG_POSITION_MISMATCH         = 0x0080
 724
 725 } hb_buffer_diff_flags_t;
 726
 727 /* Compare the contents of two buffers, report types of differences. */
 728 HB_EXTERN hb_buffer_diff_flags_t
 729 hb_buffer_diff (hb_buffer_t *buffer,
 730                 hb_buffer_t *reference,
 731                 hb_codepoint_t dottedcircle_glyph,
 732                 unsigned int position_fuzz);
 733
 734
 735 /*
 736  * Debugging.
 737  */
 738
 739 /**
 740  * hb_buffer_message_func_t:
 741  * @buffer: An #hb_buffer_t to work upon
 742  * @font: The #hb_font_t the @buffer is shaped with
 743  * @message: %NULL-terminated message passed to the function
 744  * @user_data: User data pointer passed by the caller
 745  *
 746  * A callback method for #hb_buffer_t. The method gets called with the
 747  * #hb_buffer_t it was set on, the #hb_font_t the buffer is shaped with and a
 748  * message describing what step of the shaping process will be performed.
 749  * Returning %false from this method will skip this shaping step and move to
 750  * the next one.
 751  *
 752  * Return value: %true to perform the shaping step, %false to skip it.
 753  *
 754  * Since: 1.1.3
 755  */
 756 typedef hb_bool_t       (*hb_buffer_message_func_t)     (hb_buffer_t *buffer,
 757                                                          hb_font_t   *font,
 758                                                          const char  *message,
 759                                                          void        *user_data);
 760
 761 HB_EXTERN void
 762 hb_buffer_set_message_func (hb_buffer_t *buffer,
 763                             hb_buffer_message_func_t func,
 764                             void *user_data, hb_destroy_func_t destroy);
 765
 766
 767 HB_END_DECLS
 768
 769 #endif /* HB_BUFFER_H */