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 #ifndef HB_H_IN 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 * @mask: 48 * @cluster: the index of the character in the original text that corresponds 49 * to this #hb_glyph_info_t, or whatever the client passes to 50 * hb_buffer_add(). More than one #hb_glyph_info_t can have the same 51 * @cluster value, if they resulted from the same character (e.g. one 52 * to many glyph substitution), and when more than one character gets 53 * merged in the same glyph (e.g. many to one glyph substitution) the 54 * #hb_glyph_info_t will have the smallest cluster value of them. 55 * By default some characters are merged into the same cluster 56 * (e.g. combining marks have the same cluster as their bases) 57 * even if they are separate glyphs, hb_buffer_set_cluster_level() 58 * allow selecting more fine-grained cluster handling. 59 * 60 * The #hb_glyph_info_t is the structure that holds information about the 61 * glyphs and their relation to input text. 62 * 63 */ 64 typedef struct hb_glyph_info_t { 65 hb_codepoint_t codepoint; 66 hb_mask_t mask; /* Holds hb_glyph_flags_t after hb_shape(), plus other things. */ 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 typedef enum { /*< flags >*/ 75 HB_GLYPH_FLAG_UNSAFE_TO_BREAK = 0x00000001, 76 77 HB_GLYPH_FLAG_DEFINED = 0x00000001 /* OR of all defined flags */ 78 } hb_glyph_flags_t; 79 80 HB_EXTERN hb_glyph_flags_t 81 hb_glyph_info_get_glyph_flags (const hb_glyph_info_t *info); 82 83 #define hb_glyph_info_get_glyph_flags(info) \ 84 ((hb_glyph_flags_t) ((unsigned int) (info)->mask & HB_GLYPH_FLAG_DEFINED)) 85 86 87 /** 88 * hb_glyph_position_t: 89 * @x_advance: how much the line advances after drawing this glyph when setting 90 * text in horizontal direction. 91 * @y_advance: how much the line advances after drawing this glyph when setting 92 * text in vertical direction. 93 * @x_offset: how much the glyph moves on the X-axis before drawing it, this 94 * should not affect how much the line advances. 95 * @y_offset: how much the glyph moves on the Y-axis before drawing it, this 96 * should not affect how much the line advances. 97 * 98 * The #hb_glyph_position_t is the structure that holds the positions of the 99 * glyph in both horizontal and vertical directions. All positions in 100 * #hb_glyph_position_t are relative to the current point. 101 * 102 */ 103 typedef struct hb_glyph_position_t { 104 hb_position_t x_advance; 105 hb_position_t y_advance; 106 hb_position_t x_offset; 107 hb_position_t y_offset; 108 109 /*< private >*/ 110 hb_var_int_t var; 111 } hb_glyph_position_t; 112 113 /** 114 * hb_segment_properties_t: 115 * @direction: the #hb_direction_t of the buffer, see hb_buffer_set_direction(). 116 * @script: the #hb_script_t of the buffer, see hb_buffer_set_script(). 117 * @language: the #hb_language_t of the buffer, see hb_buffer_set_language(). 118 * 119 * The structure that holds various text properties of an #hb_buffer_t. Can be 120 * set and retrieved using hb_buffer_set_segment_properties() and 121 * hb_buffer_get_segment_properties(), respectively. 122 */ 123 typedef struct hb_segment_properties_t { 124 hb_direction_t direction; 125 hb_script_t script; 126 hb_language_t language; 127 /*< private >*/ 128 void *reserved1; 129 void *reserved2; 130 } hb_segment_properties_t; 131 132 #define HB_SEGMENT_PROPERTIES_DEFAULT {HB_DIRECTION_INVALID, \ 133 HB_SCRIPT_INVALID, \ 134 HB_LANGUAGE_INVALID, \ 135 (void *) 0, \ 136 (void *) 0} 137 138 HB_EXTERN hb_bool_t 139 hb_segment_properties_equal (const hb_segment_properties_t *a, 140 const hb_segment_properties_t *b); 141 142 HB_EXTERN unsigned int 143 hb_segment_properties_hash (const hb_segment_properties_t *p); 144 145 146 147 /** 148 * hb_buffer_t: 149 * 150 * The main structure holding the input text and its properties before shaping, 151 * and output glyphs and their information after shaping. 152 */ 153 154 typedef struct hb_buffer_t hb_buffer_t; 155 156 HB_EXTERN hb_buffer_t * 157 hb_buffer_create (void); 158 159 HB_EXTERN hb_buffer_t * 160 hb_buffer_get_empty (void); 161 162 HB_EXTERN hb_buffer_t * 163 hb_buffer_reference (hb_buffer_t *buffer); 164 165 HB_EXTERN void 166 hb_buffer_destroy (hb_buffer_t *buffer); 167 168 HB_EXTERN hb_bool_t 169 hb_buffer_set_user_data (hb_buffer_t *buffer, 170 hb_user_data_key_t *key, 171 void * data, 172 hb_destroy_func_t destroy, 173 hb_bool_t replace); 174 175 HB_EXTERN void * 176 hb_buffer_get_user_data (hb_buffer_t *buffer, 177 hb_user_data_key_t *key); 178 179 180 /** 181 * hb_buffer_content_type_t: 182 * @HB_BUFFER_CONTENT_TYPE_INVALID: Initial value for new buffer. 183 * @HB_BUFFER_CONTENT_TYPE_UNICODE: The buffer contains input characters (before shaping). 184 * @HB_BUFFER_CONTENT_TYPE_GLYPHS: The buffer contains output glyphs (after shaping). 185 */ 186 typedef enum { 187 HB_BUFFER_CONTENT_TYPE_INVALID = 0, 188 HB_BUFFER_CONTENT_TYPE_UNICODE, 189 HB_BUFFER_CONTENT_TYPE_GLYPHS 190 } hb_buffer_content_type_t; 191 192 HB_EXTERN void 193 hb_buffer_set_content_type (hb_buffer_t *buffer, 194 hb_buffer_content_type_t content_type); 195 196 HB_EXTERN hb_buffer_content_type_t 197 hb_buffer_get_content_type (hb_buffer_t *buffer); 198 199 200 HB_EXTERN void 201 hb_buffer_set_unicode_funcs (hb_buffer_t *buffer, 202 hb_unicode_funcs_t *unicode_funcs); 203 204 HB_EXTERN hb_unicode_funcs_t * 205 hb_buffer_get_unicode_funcs (hb_buffer_t *buffer); 206 207 HB_EXTERN void 208 hb_buffer_set_direction (hb_buffer_t *buffer, 209 hb_direction_t direction); 210 211 HB_EXTERN hb_direction_t 212 hb_buffer_get_direction (hb_buffer_t *buffer); 213 214 HB_EXTERN void 215 hb_buffer_set_script (hb_buffer_t *buffer, 216 hb_script_t script); 217 218 HB_EXTERN hb_script_t 219 hb_buffer_get_script (hb_buffer_t *buffer); 220 221 HB_EXTERN void 222 hb_buffer_set_language (hb_buffer_t *buffer, 223 hb_language_t language); 224 225 226 HB_EXTERN hb_language_t 227 hb_buffer_get_language (hb_buffer_t *buffer); 228 229 HB_EXTERN void 230 hb_buffer_set_segment_properties (hb_buffer_t *buffer, 231 const hb_segment_properties_t *props); 232 233 HB_EXTERN void 234 hb_buffer_get_segment_properties (hb_buffer_t *buffer, 235 hb_segment_properties_t *props); 236 237 HB_EXTERN void 238 hb_buffer_guess_segment_properties (hb_buffer_t *buffer); 239 240 241 /** 242 * hb_buffer_flags_t: 243 * @HB_BUFFER_FLAG_DEFAULT: the default buffer flag. 244 * @HB_BUFFER_FLAG_BOT: flag indicating that special handling of the beginning 245 * of text paragraph can be applied to this buffer. Should usually 246 * be set, unless you are passing to the buffer only part 247 * of the text without the full context. 248 * @HB_BUFFER_FLAG_EOT: flag indicating that special handling of the end of text 249 * paragraph can be applied to this buffer, similar to 250 * @HB_BUFFER_FLAG_EOT. 251 * @HB_BUFFER_FLAG_PRESERVE_DEFAULT_IGNORABLES: 252 * flag indication that character with Default_Ignorable 253 * Unicode property should use the corresponding glyph 254 * from the font, instead of hiding them (currently done 255 * by replacing them with the space glyph and zeroing the 256 * advance width.) 257 * 258 * Since: 0.9.20 259 */ 260 typedef enum { /*< flags >*/ 261 HB_BUFFER_FLAG_DEFAULT = 0x00000000u, 262 HB_BUFFER_FLAG_BOT = 0x00000001u, /* Beginning-of-text */ 263 HB_BUFFER_FLAG_EOT = 0x00000002u, /* End-of-text */ 264 HB_BUFFER_FLAG_PRESERVE_DEFAULT_IGNORABLES = 0x00000004u 265 } hb_buffer_flags_t; 266 267 HB_EXTERN void 268 hb_buffer_set_flags (hb_buffer_t *buffer, 269 hb_buffer_flags_t flags); 270 271 HB_EXTERN hb_buffer_flags_t 272 hb_buffer_get_flags (hb_buffer_t *buffer); 273 274 /* 275 * Since: 0.9.42 276 */ 277 typedef enum { 278 HB_BUFFER_CLUSTER_LEVEL_MONOTONE_GRAPHEMES = 0, 279 HB_BUFFER_CLUSTER_LEVEL_MONOTONE_CHARACTERS = 1, 280 HB_BUFFER_CLUSTER_LEVEL_CHARACTERS = 2, 281 HB_BUFFER_CLUSTER_LEVEL_DEFAULT = HB_BUFFER_CLUSTER_LEVEL_MONOTONE_GRAPHEMES 282 } hb_buffer_cluster_level_t; 283 284 HB_EXTERN void 285 hb_buffer_set_cluster_level (hb_buffer_t *buffer, 286 hb_buffer_cluster_level_t cluster_level); 287 288 HB_EXTERN hb_buffer_cluster_level_t 289 hb_buffer_get_cluster_level (hb_buffer_t *buffer); 290 291 /** 292 * HB_BUFFER_REPLACEMENT_CODEPOINT_DEFAULT: 293 * 294 * The default code point for replacing invalid characters in a given encoding. 295 * Set to U+FFFD REPLACEMENT CHARACTER. 296 * 297 * Since: 0.9.31 298 */ 299 #define HB_BUFFER_REPLACEMENT_CODEPOINT_DEFAULT 0xFFFDu 300 301 HB_EXTERN void 302 hb_buffer_set_replacement_codepoint (hb_buffer_t *buffer, 303 hb_codepoint_t replacement); 304 305 HB_EXTERN hb_codepoint_t 306 hb_buffer_get_replacement_codepoint (hb_buffer_t *buffer); 307 308 309 HB_EXTERN void 310 hb_buffer_reset (hb_buffer_t *buffer); 311 312 HB_EXTERN void 313 hb_buffer_clear_contents (hb_buffer_t *buffer); 314 315 HB_EXTERN hb_bool_t 316 hb_buffer_pre_allocate (hb_buffer_t *buffer, 317 unsigned int size); 318 319 320 HB_EXTERN hb_bool_t 321 hb_buffer_allocation_successful (hb_buffer_t *buffer); 322 323 HB_EXTERN void 324 hb_buffer_reverse (hb_buffer_t *buffer); 325 326 HB_EXTERN void 327 hb_buffer_reverse_range (hb_buffer_t *buffer, 328 unsigned int start, unsigned int end); 329 330 HB_EXTERN void 331 hb_buffer_reverse_clusters (hb_buffer_t *buffer); 332 333 334 /* Filling the buffer in */ 335 336 HB_EXTERN void 337 hb_buffer_add (hb_buffer_t *buffer, 338 hb_codepoint_t codepoint, 339 unsigned int cluster); 340 341 HB_EXTERN void 342 hb_buffer_add_utf8 (hb_buffer_t *buffer, 343 const char *text, 344 int text_length, 345 unsigned int item_offset, 346 int item_length); 347 348 HB_EXTERN void 349 hb_buffer_add_utf16 (hb_buffer_t *buffer, 350 const uint16_t *text, 351 int text_length, 352 unsigned int item_offset, 353 int item_length); 354 355 HB_EXTERN void 356 hb_buffer_add_utf32 (hb_buffer_t *buffer, 357 const uint32_t *text, 358 int text_length, 359 unsigned int item_offset, 360 int item_length); 361 362 HB_EXTERN void 363 hb_buffer_add_latin1 (hb_buffer_t *buffer, 364 const uint8_t *text, 365 int text_length, 366 unsigned int item_offset, 367 int item_length); 368 369 HB_EXTERN void 370 hb_buffer_add_codepoints (hb_buffer_t *buffer, 371 const hb_codepoint_t *text, 372 int text_length, 373 unsigned int item_offset, 374 int item_length); 375 376 HB_EXTERN void 377 hb_buffer_append (hb_buffer_t *buffer, 378 hb_buffer_t *source, 379 unsigned int start, 380 unsigned int end); 381 382 HB_EXTERN hb_bool_t 383 hb_buffer_set_length (hb_buffer_t *buffer, 384 unsigned int length); 385 386 HB_EXTERN unsigned int 387 hb_buffer_get_length (hb_buffer_t *buffer); 388 389 /* Getting glyphs out of the buffer */ 390 391 HB_EXTERN hb_glyph_info_t * 392 hb_buffer_get_glyph_infos (hb_buffer_t *buffer, 393 unsigned int *length); 394 395 HB_EXTERN hb_glyph_position_t * 396 hb_buffer_get_glyph_positions (hb_buffer_t *buffer, 397 unsigned int *length); 398 399 400 HB_EXTERN void 401 hb_buffer_normalize_glyphs (hb_buffer_t *buffer); 402 403 404 /* 405 * Serialize 406 */ 407 408 /** 409 * hb_buffer_serialize_flags_t: 410 * @HB_BUFFER_SERIALIZE_FLAG_DEFAULT: serialize glyph names, clusters and positions. 411 * @HB_BUFFER_SERIALIZE_FLAG_NO_CLUSTERS: do not serialize glyph cluster. 412 * @HB_BUFFER_SERIALIZE_FLAG_NO_POSITIONS: do not serialize glyph position information. 413 * @HB_BUFFER_SERIALIZE_FLAG_NO_GLYPH_NAMES: do no serialize glyph name. 414 * @HB_BUFFER_SERIALIZE_FLAG_GLYPH_EXTENTS: serialize glyph extents. 415 * 416 * Flags that control what glyph information are serialized in hb_buffer_serialize_glyphs(). 417 * 418 * Since: 0.9.20 419 */ 420 typedef enum { /*< flags >*/ 421 HB_BUFFER_SERIALIZE_FLAG_DEFAULT = 0x00000000u, 422 HB_BUFFER_SERIALIZE_FLAG_NO_CLUSTERS = 0x00000001u, 423 HB_BUFFER_SERIALIZE_FLAG_NO_POSITIONS = 0x00000002u, 424 HB_BUFFER_SERIALIZE_FLAG_NO_GLYPH_NAMES = 0x00000004u, 425 HB_BUFFER_SERIALIZE_FLAG_GLYPH_EXTENTS = 0x00000008u, 426 HB_BUFFER_SERIALIZE_FLAG_GLYPH_FLAGS = 0x00000010u 427 } hb_buffer_serialize_flags_t; 428 429 /** 430 * hb_buffer_serialize_format_t: 431 * @HB_BUFFER_SERIALIZE_FORMAT_TEXT: a human-readable, plain text format. 432 * @HB_BUFFER_SERIALIZE_FORMAT_JSON: a machine-readable JSON format. 433 * @HB_BUFFER_SERIALIZE_FORMAT_INVALID: invalid format. 434 * 435 * The buffer serialization and de-serialization format used in 436 * hb_buffer_serialize_glyphs() and hb_buffer_deserialize_glyphs(). 437 * 438 * Since: 0.9.2 439 */ 440 typedef enum { 441 HB_BUFFER_SERIALIZE_FORMAT_TEXT = HB_TAG('T','E','X','T'), 442 HB_BUFFER_SERIALIZE_FORMAT_JSON = HB_TAG('J','S','O','N'), 443 HB_BUFFER_SERIALIZE_FORMAT_INVALID = HB_TAG_NONE 444 } hb_buffer_serialize_format_t; 445 446 HB_EXTERN hb_buffer_serialize_format_t 447 hb_buffer_serialize_format_from_string (const char *str, int len); 448 449 HB_EXTERN const char * 450 hb_buffer_serialize_format_to_string (hb_buffer_serialize_format_t format); 451 452 HB_EXTERN const char ** 453 hb_buffer_serialize_list_formats (void); 454 455 HB_EXTERN unsigned int 456 hb_buffer_serialize_glyphs (hb_buffer_t *buffer, 457 unsigned int start, 458 unsigned int end, 459 char *buf, 460 unsigned int buf_size, 461 unsigned int *buf_consumed, 462 hb_font_t *font, 463 hb_buffer_serialize_format_t format, 464 hb_buffer_serialize_flags_t flags); 465 466 HB_EXTERN hb_bool_t 467 hb_buffer_deserialize_glyphs (hb_buffer_t *buffer, 468 const char *buf, 469 int buf_len, 470 const char **end_ptr, 471 hb_font_t *font, 472 hb_buffer_serialize_format_t format); 473 474 475 /* 476 * Compare buffers 477 */ 478 479 typedef enum { /*< flags >*/ 480 HB_BUFFER_DIFF_FLAG_EQUAL = 0x0000, 481 482 /* Buffers with different content_type cannot be meaningfully compared 483 * in any further detail. */ 484 HB_BUFFER_DIFF_FLAG_CONTENT_TYPE_MISMATCH = 0x0001, 485 486 /* For buffers with differing length, the per-glyph comparison is not 487 * attempted, though we do still scan reference for dottedcircle / .notdef 488 * glyphs. */ 489 HB_BUFFER_DIFF_FLAG_LENGTH_MISMATCH = 0x0002, 490 491 /* We want to know if dottedcircle / .notdef glyphs are present in the 492 * reference, as we may not care so much about other differences in this 493 * case. */ 494 HB_BUFFER_DIFF_FLAG_NOTDEF_PRESENT = 0x0004, 495 HB_BUFFER_DIFF_FLAG_DOTTED_CIRCLE_PRESENT = 0x0008, 496 497 /* If the buffers have the same length, we compare them glyph-by-glyph 498 * and report which aspect(s) of the glyph info/position are different. */ 499 HB_BUFFER_DIFF_FLAG_CODEPOINT_MISMATCH = 0x0010, 500 HB_BUFFER_DIFF_FLAG_CLUSTER_MISMATCH = 0x0020, 501 HB_BUFFER_DIFF_FLAG_GLYPH_FLAGS_MISMATCH = 0x0040, 502 HB_BUFFER_DIFF_FLAG_POSITION_MISMATCH = 0x0080 503 504 } hb_buffer_diff_flags_t; 505 506 /* Compare the contents of two buffers, report types of differences. */ 507 HB_EXTERN hb_buffer_diff_flags_t 508 hb_buffer_diff (hb_buffer_t *buffer, 509 hb_buffer_t *reference, 510 hb_codepoint_t dottedcircle_glyph, 511 unsigned int position_fuzz); 512 513 514 /* 515 * Debugging. 516 */ 517 518 typedef hb_bool_t (*hb_buffer_message_func_t) (hb_buffer_t *buffer, 519 hb_font_t *font, 520 const char *message, 521 void *user_data); 522 523 HB_EXTERN void 524 hb_buffer_set_message_func (hb_buffer_t *buffer, 525 hb_buffer_message_func_t func, 526 void *user_data, hb_destroy_func_t destroy); 527 528 529 HB_END_DECLS 530 531 #endif /* HB_BUFFER_H */ 532