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; 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_position_t: 76 * @x_advance: how much the line advances after drawing this glyph when setting 77 * text in horizontal direction. 78 * @y_advance: how much the line advances after drawing this glyph when setting 79 * text in vertical direction. 80 * @x_offset: how much the glyph moves on the X-axis before drawing it, this 81 * should not affect how much the line advances. 82 * @y_offset: how much the glyph moves on the Y-axis before drawing it, this 83 * should not affect how much the line advances. 84 * 85 * The #hb_glyph_position_t is the structure that holds the positions of the 86 * glyph in both horizontal and vertical directions. All positions in 87 * #hb_glyph_position_t are relative to the current point. 88 * 89 */ 90 typedef struct hb_glyph_position_t { 91 hb_position_t x_advance; 92 hb_position_t y_advance; 93 hb_position_t x_offset; 94 hb_position_t y_offset; 95 96 /*< private >*/ 97 hb_var_int_t var; 98 } hb_glyph_position_t; 99 100 /** 101 * hb_segment_properties_t: 102 * @direction: the #hb_direction_t of the buffer, see hb_buffer_set_direction(). 103 * @script: the #hb_script_t of the buffer, see hb_buffer_set_script(). 104 * @language: the #hb_language_t of the buffer, see hb_buffer_set_language(). 105 * 106 * The structure that holds various text properties of an #hb_buffer_t. Can be 107 * set and retrieved using hb_buffer_set_segment_properties() and 108 * hb_buffer_get_segment_properties(), respectively. 109 */ 110 typedef struct hb_segment_properties_t { 111 hb_direction_t direction; 112 hb_script_t script; 113 hb_language_t language; 114 /*< private >*/ 115 void *reserved1; 116 void *reserved2; 117 } hb_segment_properties_t; 118 119 #define HB_SEGMENT_PROPERTIES_DEFAULT {HB_DIRECTION_INVALID, \ 120 HB_SCRIPT_INVALID, \ 121 HB_LANGUAGE_INVALID, \ 122 NULL, \ 123 NULL} 124 125 HB_EXTERN hb_bool_t 126 hb_segment_properties_equal (const hb_segment_properties_t *a, 127 const hb_segment_properties_t *b); 128 129 HB_EXTERN unsigned int 130 hb_segment_properties_hash (const hb_segment_properties_t *p); 131 132 133 134 /** 135 * hb_buffer_t: 136 * 137 * The main structure holding the input text and its properties before shaping, 138 * and output glyphs and their information after shaping. 139 */ 140 141 typedef struct hb_buffer_t hb_buffer_t; 142 143 HB_EXTERN hb_buffer_t * 144 hb_buffer_create (void); 145 146 HB_EXTERN hb_buffer_t * 147 hb_buffer_get_empty (void); 148 149 HB_EXTERN hb_buffer_t * 150 hb_buffer_reference (hb_buffer_t *buffer); 151 152 HB_EXTERN void 153 hb_buffer_destroy (hb_buffer_t *buffer); 154 155 HB_EXTERN hb_bool_t 156 hb_buffer_set_user_data (hb_buffer_t *buffer, 157 hb_user_data_key_t *key, 158 void * data, 159 hb_destroy_func_t destroy, 160 hb_bool_t replace); 161 162 HB_EXTERN void * 163 hb_buffer_get_user_data (hb_buffer_t *buffer, 164 hb_user_data_key_t *key); 165 166 /** 167 * hb_buffer_content_type_t: 168 * @HB_BUFFER_CONTENT_TYPE_INVALID: Initial value for new buffer. 169 * @HB_BUFFER_CONTENT_TYPE_UNICODE: The buffer contains input characters (before shaping). 170 * @HB_BUFFER_CONTENT_TYPE_GLYPHS: The buffer contains output glyphs (after shaping). 171 */ 172 typedef enum { 173 HB_BUFFER_CONTENT_TYPE_INVALID = 0, 174 HB_BUFFER_CONTENT_TYPE_UNICODE, 175 HB_BUFFER_CONTENT_TYPE_GLYPHS 176 } hb_buffer_content_type_t; 177 178 HB_EXTERN void 179 hb_buffer_set_content_type (hb_buffer_t *buffer, 180 hb_buffer_content_type_t content_type); 181 182 HB_EXTERN hb_buffer_content_type_t 183 hb_buffer_get_content_type (hb_buffer_t *buffer); 184 185 186 HB_EXTERN void 187 hb_buffer_set_unicode_funcs (hb_buffer_t *buffer, 188 hb_unicode_funcs_t *unicode_funcs); 189 190 HB_EXTERN hb_unicode_funcs_t * 191 hb_buffer_get_unicode_funcs (hb_buffer_t *buffer); 192 193 HB_EXTERN void 194 hb_buffer_set_direction (hb_buffer_t *buffer, 195 hb_direction_t direction); 196 197 HB_EXTERN hb_direction_t 198 hb_buffer_get_direction (hb_buffer_t *buffer); 199 200 HB_EXTERN void 201 hb_buffer_set_script (hb_buffer_t *buffer, 202 hb_script_t script); 203 204 HB_EXTERN hb_script_t 205 hb_buffer_get_script (hb_buffer_t *buffer); 206 207 HB_EXTERN void 208 hb_buffer_set_language (hb_buffer_t *buffer, 209 hb_language_t language); 210 211 212 HB_EXTERN hb_language_t 213 hb_buffer_get_language (hb_buffer_t *buffer); 214 215 HB_EXTERN void 216 hb_buffer_set_segment_properties (hb_buffer_t *buffer, 217 const hb_segment_properties_t *props); 218 219 HB_EXTERN void 220 hb_buffer_get_segment_properties (hb_buffer_t *buffer, 221 hb_segment_properties_t *props); 222 223 HB_EXTERN void 224 hb_buffer_guess_segment_properties (hb_buffer_t *buffer); 225 226 227 /** 228 * hb_buffer_flags_t: 229 * @HB_BUFFER_FLAG_DEFAULT: the default buffer flag. 230 * @HB_BUFFER_FLAG_BOT: flag indicating that special handling of the beginning 231 * of text paragraph can be applied to this buffer. Should usually 232 * be set, unless you are passing to the buffer only part 233 * of the text without the full context. 234 * @HB_BUFFER_FLAG_EOT: flag indicating that special handling of the end of text 235 * paragraph can be applied to this buffer, similar to 236 * @HB_BUFFER_FLAG_EOT. 237 * @HB_BUFFER_FLAG_PRESERVE_DEFAULT_IGNORABLES: 238 * flag indication that character with Default_Ignorable 239 * Unicode property should use the corresponding glyph 240 * from the font, instead of hiding them (currently done 241 * by replacing them with the space glyph and zeroing the 242 * advance width.) 243 * 244 * Since: 0.9.20 245 */ 246 typedef enum { /*< flags >*/ 247 HB_BUFFER_FLAG_DEFAULT = 0x00000000u, 248 HB_BUFFER_FLAG_BOT = 0x00000001u, /* Beginning-of-text */ 249 HB_BUFFER_FLAG_EOT = 0x00000002u, /* End-of-text */ 250 HB_BUFFER_FLAG_PRESERVE_DEFAULT_IGNORABLES = 0x00000004u 251 } hb_buffer_flags_t; 252 253 HB_EXTERN void 254 hb_buffer_set_flags (hb_buffer_t *buffer, 255 hb_buffer_flags_t flags); 256 257 HB_EXTERN hb_buffer_flags_t 258 hb_buffer_get_flags (hb_buffer_t *buffer); 259 260 /* 261 * Since: 0.9.42 262 */ 263 typedef enum { 264 HB_BUFFER_CLUSTER_LEVEL_MONOTONE_GRAPHEMES = 0, 265 HB_BUFFER_CLUSTER_LEVEL_MONOTONE_CHARACTERS = 1, 266 HB_BUFFER_CLUSTER_LEVEL_CHARACTERS = 2, 267 HB_BUFFER_CLUSTER_LEVEL_DEFAULT = HB_BUFFER_CLUSTER_LEVEL_MONOTONE_GRAPHEMES 268 } hb_buffer_cluster_level_t; 269 270 HB_EXTERN void 271 hb_buffer_set_cluster_level (hb_buffer_t *buffer, 272 hb_buffer_cluster_level_t cluster_level); 273 274 HB_EXTERN hb_buffer_cluster_level_t 275 hb_buffer_get_cluster_level (hb_buffer_t *buffer); 276 277 /** 278 * HB_BUFFER_REPLACEMENT_CODEPOINT_DEFAULT: 279 * 280 * The default code point for replacing invalid characters in a given encoding. 281 * Set to U+FFFD REPLACEMENT CHARACTER. 282 * 283 * Since: 0.9.31 284 */ 285 #define HB_BUFFER_REPLACEMENT_CODEPOINT_DEFAULT 0xFFFDu 286 287 HB_EXTERN void 288 hb_buffer_set_replacement_codepoint (hb_buffer_t *buffer, 289 hb_codepoint_t replacement); 290 291 HB_EXTERN hb_codepoint_t 292 hb_buffer_get_replacement_codepoint (hb_buffer_t *buffer); 293 294 295 HB_EXTERN void 296 hb_buffer_reset (hb_buffer_t *buffer); 297 298 HB_EXTERN void 299 hb_buffer_clear_contents (hb_buffer_t *buffer); 300 301 HB_EXTERN hb_bool_t 302 hb_buffer_pre_allocate (hb_buffer_t *buffer, 303 unsigned int size); 304 305 306 HB_EXTERN hb_bool_t 307 hb_buffer_allocation_successful (hb_buffer_t *buffer); 308 309 HB_EXTERN void 310 hb_buffer_reverse (hb_buffer_t *buffer); 311 312 HB_EXTERN void 313 hb_buffer_reverse_range (hb_buffer_t *buffer, 314 unsigned int start, unsigned int end); 315 316 HB_EXTERN void 317 hb_buffer_reverse_clusters (hb_buffer_t *buffer); 318 319 320 /* Filling the buffer in */ 321 322 HB_EXTERN void 323 hb_buffer_add (hb_buffer_t *buffer, 324 hb_codepoint_t codepoint, 325 unsigned int cluster); 326 327 HB_EXTERN void 328 hb_buffer_add_utf8 (hb_buffer_t *buffer, 329 const char *text, 330 int text_length, 331 unsigned int item_offset, 332 int item_length); 333 334 HB_EXTERN void 335 hb_buffer_add_utf16 (hb_buffer_t *buffer, 336 const uint16_t *text, 337 int text_length, 338 unsigned int item_offset, 339 int item_length); 340 341 HB_EXTERN void 342 hb_buffer_add_utf32 (hb_buffer_t *buffer, 343 const uint32_t *text, 344 int text_length, 345 unsigned int item_offset, 346 int item_length); 347 348 HB_EXTERN void 349 hb_buffer_add_latin1 (hb_buffer_t *buffer, 350 const uint8_t *text, 351 int text_length, 352 unsigned int item_offset, 353 int item_length); 354 355 HB_EXTERN void 356 hb_buffer_add_codepoints (hb_buffer_t *buffer, 357 const hb_codepoint_t *text, 358 int text_length, 359 unsigned int item_offset, 360 int item_length); 361 362 363 HB_EXTERN hb_bool_t 364 hb_buffer_set_length (hb_buffer_t *buffer, 365 unsigned int length); 366 367 HB_EXTERN unsigned int 368 hb_buffer_get_length (hb_buffer_t *buffer); 369 370 /* Getting glyphs out of the buffer */ 371 372 HB_EXTERN hb_glyph_info_t * 373 hb_buffer_get_glyph_infos (hb_buffer_t *buffer, 374 unsigned int *length); 375 376 HB_EXTERN hb_glyph_position_t * 377 hb_buffer_get_glyph_positions (hb_buffer_t *buffer, 378 unsigned int *length); 379 380 381 HB_EXTERN void 382 hb_buffer_normalize_glyphs (hb_buffer_t *buffer); 383 384 385 /* 386 * Serialize 387 */ 388 389 /** 390 * hb_buffer_serialize_flags_t: 391 * @HB_BUFFER_SERIALIZE_FLAG_DEFAULT: serialize glyph names, clusters and positions. 392 * @HB_BUFFER_SERIALIZE_FLAG_NO_CLUSTERS: do not serialize glyph cluster. 393 * @HB_BUFFER_SERIALIZE_FLAG_NO_POSITIONS: do not serialize glyph position information. 394 * @HB_BUFFER_SERIALIZE_FLAG_NO_GLYPH_NAMES: do no serialize glyph name. 395 * @HB_BUFFER_SERIALIZE_FLAG_GLYPH_EXTENTS: serialize glyph extents. 396 * 397 * Flags that control what glyph information are serialized in hb_buffer_serialize_glyphs(). 398 * 399 * Since: 0.9.20 400 */ 401 typedef enum { /*< flags >*/ 402 HB_BUFFER_SERIALIZE_FLAG_DEFAULT = 0x00000000u, 403 HB_BUFFER_SERIALIZE_FLAG_NO_CLUSTERS = 0x00000001u, 404 HB_BUFFER_SERIALIZE_FLAG_NO_POSITIONS = 0x00000002u, 405 HB_BUFFER_SERIALIZE_FLAG_NO_GLYPH_NAMES = 0x00000004u, 406 HB_BUFFER_SERIALIZE_FLAG_GLYPH_EXTENTS = 0x00000008u 407 } hb_buffer_serialize_flags_t; 408 409 /** 410 * hb_buffer_serialize_format_t: 411 * @HB_BUFFER_SERIALIZE_FORMAT_TEXT: a human-readable, plain text format. 412 * @HB_BUFFER_SERIALIZE_FORMAT_JSON: a machine-readable JSON format. 413 * @HB_BUFFER_SERIALIZE_FORMAT_INVALID: invalid format. 414 * 415 * The buffer serialization and de-serialization format used in 416 * hb_buffer_serialize_glyphs() and hb_buffer_deserialize_glyphs(). 417 * 418 * Since: 0.9.2 419 */ 420 typedef enum { 421 HB_BUFFER_SERIALIZE_FORMAT_TEXT = HB_TAG('T','E','X','T'), 422 HB_BUFFER_SERIALIZE_FORMAT_JSON = HB_TAG('J','S','O','N'), 423 HB_BUFFER_SERIALIZE_FORMAT_INVALID = HB_TAG_NONE 424 } hb_buffer_serialize_format_t; 425 426 HB_EXTERN hb_buffer_serialize_format_t 427 hb_buffer_serialize_format_from_string (const char *str, int len); 428 429 HB_EXTERN const char * 430 hb_buffer_serialize_format_to_string (hb_buffer_serialize_format_t format); 431 432 HB_EXTERN const char ** 433 hb_buffer_serialize_list_formats (void); 434 435 HB_EXTERN unsigned int 436 hb_buffer_serialize_glyphs (hb_buffer_t *buffer, 437 unsigned int start, 438 unsigned int end, 439 char *buf, 440 unsigned int buf_size, 441 unsigned int *buf_consumed, 442 hb_font_t *font, 443 hb_buffer_serialize_format_t format, 444 hb_buffer_serialize_flags_t flags); 445 446 HB_EXTERN hb_bool_t 447 hb_buffer_deserialize_glyphs (hb_buffer_t *buffer, 448 const char *buf, 449 int buf_len, 450 const char **end_ptr, 451 hb_font_t *font, 452 hb_buffer_serialize_format_t format); 453 454 455 /* 456 * Debugging. 457 */ 458 459 typedef hb_bool_t (*hb_buffer_message_func_t) (hb_buffer_t *buffer, 460 hb_font_t *font, 461 const char *message, 462 void *user_data); 463 464 HB_EXTERN void 465 hb_buffer_set_message_func (hb_buffer_t *buffer, 466 hb_buffer_message_func_t func, 467 void *user_data, hb_destroy_func_t destroy); 468 469 470 HB_END_DECLS 471 472 #endif /* HB_BUFFER_H */ 473
