1 /***************************************************************************/ 2 /* */ 3 /* sfnt.h */ 4 /* */ 5 /* High-level `sfnt' driver interface (specification). */ 6 /* */ 7 /* Copyright 1996-2015 by */ 8 /* David Turner, Robert Wilhelm, and Werner Lemberg. */ 9 /* */ 10 /* This file is part of the FreeType project, and may only be used, */ 11 /* modified, and distributed under the terms of the FreeType project */ 12 /* license, LICENSE.TXT. By continuing to use, modify, or distribute */ 13 /* this file you indicate that you have read the license and */ 14 /* understand and accept it fully. */ 15 /* */ 16 /***************************************************************************/ 17 18 19 #ifndef __SFNT_H__ 20 #define __SFNT_H__ 21 22 23 #include <ft2build.h> 24 #include FT_INTERNAL_DRIVER_H 25 #include FT_INTERNAL_TRUETYPE_TYPES_H 26 27 28 FT_BEGIN_HEADER 29 30 31 /*************************************************************************/ 32 /* */ 33 /* <FuncType> */ 34 /* TT_Init_Face_Func */ 35 /* */ 36 /* <Description> */ 37 /* First part of the SFNT face object initialization. This finds */ 38 /* the face in a SFNT file or collection, and load its format tag in */ 39 /* face->format_tag. */ 40 /* */ 41 /* <Input> */ 42 /* stream :: The input stream. */ 43 /* */ 44 /* face :: A handle to the target face object. */ 45 /* */ 46 /* face_index :: The index of the TrueType font, if we are opening a */ 47 /* collection. */ 48 /* */ 49 /* num_params :: The number of additional parameters. */ 50 /* */ 51 /* params :: Optional additional parameters. */ 52 /* */ 53 /* <Return> */ 54 /* FreeType error code. 0 means success. */ 55 /* */ 56 /* <Note> */ 57 /* The stream cursor must be at the font file's origin. */ 58 /* */ 59 /* This function recognizes fonts embedded in a `TrueType */ 60 /* collection'. */ 61 /* */ 62 /* Once the format tag has been validated by the font driver, it */ 63 /* should then call the TT_Load_Face_Func() callback to read the rest */ 64 /* of the SFNT tables in the object. */ 65 /* */ 66 typedef FT_Error 67 (*TT_Init_Face_Func)( FT_Stream stream, 68 TT_Face face, 69 FT_Int face_index, 70 FT_Int num_params, 71 FT_Parameter* params ); 72 73 74 /*************************************************************************/ 75 /* */ 76 /* <FuncType> */ 77 /* TT_Load_Face_Func */ 78 /* */ 79 /* <Description> */ 80 /* Second part of the SFNT face object initialization. This loads */ 81 /* the common SFNT tables (head, OS/2, maxp, metrics, etc.) in the */ 82 /* face object. */ 83 /* */ 84 /* <Input> */ 85 /* stream :: The input stream. */ 86 /* */ 87 /* face :: A handle to the target face object. */ 88 /* */ 89 /* face_index :: The index of the TrueType font, if we are opening a */ 90 /* collection. */ 91 /* */ 92 /* num_params :: The number of additional parameters. */ 93 /* */ 94 /* params :: Optional additional parameters. */ 95 /* */ 96 /* <Return> */ 97 /* FreeType error code. 0 means success. */ 98 /* */ 99 /* <Note> */ 100 /* This function must be called after TT_Init_Face_Func(). */ 101 /* */ 102 typedef FT_Error 103 (*TT_Load_Face_Func)( FT_Stream stream, 104 TT_Face face, 105 FT_Int face_index, 106 FT_Int num_params, 107 FT_Parameter* params ); 108 109 110 /*************************************************************************/ 111 /* */ 112 /* <FuncType> */ 113 /* TT_Done_Face_Func */ 114 /* */ 115 /* <Description> */ 116 /* A callback used to delete the common SFNT data from a face. */ 117 /* */ 118 /* <Input> */ 119 /* face :: A handle to the target face object. */ 120 /* */ 121 /* <Note> */ 122 /* This function does NOT destroy the face object. */ 123 /* */ 124 typedef void 125 (*TT_Done_Face_Func)( TT_Face face ); 126 127 128 /*************************************************************************/ 129 /* */ 130 /* <FuncType> */ 131 /* TT_Load_Any_Func */ 132 /* */ 133 /* <Description> */ 134 /* Load any font table into client memory. */ 135 /* */ 136 /* <Input> */ 137 /* face :: The face object to look for. */ 138 /* */ 139 /* tag :: The tag of table to load. Use the value 0 if you want */ 140 /* to access the whole font file, else set this parameter */ 141 /* to a valid TrueType table tag that you can forge with */ 142 /* the MAKE_TT_TAG macro. */ 143 /* */ 144 /* offset :: The starting offset in the table (or the file if */ 145 /* tag == 0). */ 146 /* */ 147 /* length :: The address of the decision variable: */ 148 /* */ 149 /* If length == NULL: */ 150 /* Loads the whole table. Returns an error if */ 151 /* `offset' == 0! */ 152 /* */ 153 /* If *length == 0: */ 154 /* Exits immediately; returning the length of the given */ 155 /* table or of the font file, depending on the value of */ 156 /* `tag'. */ 157 /* */ 158 /* If *length != 0: */ 159 /* Loads the next `length' bytes of table or font, */ 160 /* starting at offset `offset' (in table or font too). */ 161 /* */ 162 /* <Output> */ 163 /* buffer :: The address of target buffer. */ 164 /* */ 165 /* <Return> */ 166 /* TrueType error code. 0 means success. */ 167 /* */ 168 typedef FT_Error 169 (*TT_Load_Any_Func)( TT_Face face, 170 FT_ULong tag, 171 FT_Long offset, 172 FT_Byte *buffer, 173 FT_ULong* length ); 174 175 176 /*************************************************************************/ 177 /* */ 178 /* <FuncType> */ 179 /* TT_Find_SBit_Image_Func */ 180 /* */ 181 /* <Description> */ 182 /* Check whether an embedded bitmap (an `sbit') exists for a given */ 183 /* glyph, at a given strike. */ 184 /* */ 185 /* <Input> */ 186 /* face :: The target face object. */ 187 /* */ 188 /* glyph_index :: The glyph index. */ 189 /* */ 190 /* strike_index :: The current strike index. */ 191 /* */ 192 /* <Output> */ 193 /* arange :: The SBit range containing the glyph index. */ 194 /* */ 195 /* astrike :: The SBit strike containing the glyph index. */ 196 /* */ 197 /* aglyph_offset :: The offset of the glyph data in `EBDT' table. */ 198 /* */ 199 /* <Return> */ 200 /* FreeType error code. 0 means success. Returns */ 201 /* SFNT_Err_Invalid_Argument if no sbit exists for the requested */ 202 /* glyph. */ 203 /* */ 204 typedef FT_Error 205 (*TT_Find_SBit_Image_Func)( TT_Face face, 206 FT_UInt glyph_index, 207 FT_ULong strike_index, 208 TT_SBit_Range *arange, 209 TT_SBit_Strike *astrike, 210 FT_ULong *aglyph_offset ); 211 212 213 /*************************************************************************/ 214 /* */ 215 /* <FuncType> */ 216 /* TT_Load_SBit_Metrics_Func */ 217 /* */ 218 /* <Description> */ 219 /* Get the big metrics for a given embedded bitmap. */ 220 /* */ 221 /* <Input> */ 222 /* stream :: The input stream. */ 223 /* */ 224 /* range :: The SBit range containing the glyph. */ 225 /* */ 226 /* <Output> */ 227 /* big_metrics :: A big SBit metrics structure for the glyph. */ 228 /* */ 229 /* <Return> */ 230 /* FreeType error code. 0 means success. */ 231 /* */ 232 /* <Note> */ 233 /* The stream cursor must be positioned at the glyph's offset within */ 234 /* the `EBDT' table before the call. */ 235 /* */ 236 /* If the image format uses variable metrics, the stream cursor is */ 237 /* positioned just after the metrics header in the `EBDT' table on */ 238 /* function exit. */ 239 /* */ 240 typedef FT_Error 241 (*TT_Load_SBit_Metrics_Func)( FT_Stream stream, 242 TT_SBit_Range range, 243 TT_SBit_Metrics metrics ); 244 245 246 /*************************************************************************/ 247 /* */ 248 /* <FuncType> */ 249 /* TT_Load_SBit_Image_Func */ 250 /* */ 251 /* <Description> */ 252 /* Load a given glyph sbit image from the font resource. This also */ 253 /* returns its metrics. */ 254 /* */ 255 /* <Input> */ 256 /* face :: */ 257 /* The target face object. */ 258 /* */ 259 /* strike_index :: */ 260 /* The strike index. */ 261 /* */ 262 /* glyph_index :: */ 263 /* The current glyph index. */ 264 /* */ 265 /* load_flags :: */ 266 /* The current load flags. */ 267 /* */ 268 /* stream :: */ 269 /* The input stream. */ 270 /* */ 271 /* <Output> */ 272 /* amap :: */ 273 /* The target pixmap. */ 274 /* */ 275 /* ametrics :: */ 276 /* A big sbit metrics structure for the glyph image. */ 277 /* */ 278 /* <Return> */ 279 /* FreeType error code. 0 means success. Returns an error if no */ 280 /* glyph sbit exists for the index. */ 281 /* */ 282 /* <Note> */ 283 /* The `map.buffer' field is always freed before the glyph is loaded. */ 284 /* */ 285 typedef FT_Error 286 (*TT_Load_SBit_Image_Func)( TT_Face face, 287 FT_ULong strike_index, 288 FT_UInt glyph_index, 289 FT_UInt load_flags, 290 FT_Stream stream, 291 FT_Bitmap *amap, 292 TT_SBit_MetricsRec *ametrics ); 293 294 295 /*************************************************************************/ 296 /* */ 297 /* <FuncType> */ 298 /* TT_Set_SBit_Strike_Func */ 299 /* */ 300 /* <Description> */ 301 /* Select an sbit strike for a given size request. */ 302 /* */ 303 /* <Input> */ 304 /* face :: The target face object. */ 305 /* */ 306 /* req :: The size request. */ 307 /* */ 308 /* <Output> */ 309 /* astrike_index :: The index of the sbit strike. */ 310 /* */ 311 /* <Return> */ 312 /* FreeType error code. 0 means success. Returns an error if no */ 313 /* sbit strike exists for the selected ppem values. */ 314 /* */ 315 typedef FT_Error 316 (*TT_Set_SBit_Strike_Func)( TT_Face face, 317 FT_Size_Request req, 318 FT_ULong* astrike_index ); 319 320 321 /*************************************************************************/ 322 /* */ 323 /* <FuncType> */ 324 /* TT_Load_Strike_Metrics_Func */ 325 /* */ 326 /* <Description> */ 327 /* Load the metrics of a given strike. */ 328 /* */ 329 /* <Input> */ 330 /* face :: The target face object. */ 331 /* */ 332 /* strike_index :: The strike index. */ 333 /* */ 334 /* <Output> */ 335 /* metrics :: the metrics of the strike. */ 336 /* */ 337 /* <Return> */ 338 /* FreeType error code. 0 means success. Returns an error if no */ 339 /* such sbit strike exists. */ 340 /* */ 341 typedef FT_Error 342 (*TT_Load_Strike_Metrics_Func)( TT_Face face, 343 FT_ULong strike_index, 344 FT_Size_Metrics* metrics ); 345 346 347 /*************************************************************************/ 348 /* */ 349 /* <FuncType> */ 350 /* TT_Get_PS_Name_Func */ 351 /* */ 352 /* <Description> */ 353 /* Get the PostScript glyph name of a glyph. */ 354 /* */ 355 /* <Input> */ 356 /* idx :: The glyph index. */ 357 /* */ 358 /* PSname :: The address of a string pointer. Will be NULL in case */ 359 /* of error, otherwise it is a pointer to the glyph name. */ 360 /* */ 361 /* You must not modify the returned string! */ 362 /* */ 363 /* <Output> */ 364 /* FreeType error code. 0 means success. */ 365 /* */ 366 typedef FT_Error 367 (*TT_Get_PS_Name_Func)( TT_Face face, 368 FT_UInt idx, 369 FT_String** PSname ); 370 371 372 /*************************************************************************/ 373 /* */ 374 /* <FuncType> */ 375 /* TT_Load_Metrics_Func */ 376 /* */ 377 /* <Description> */ 378 /* Load a metrics table, which is a table with a horizontal and a */ 379 /* vertical version. */ 380 /* */ 381 /* <Input> */ 382 /* face :: A handle to the target face object. */ 383 /* */ 384 /* stream :: The input stream. */ 385 /* */ 386 /* vertical :: A boolean flag. If set, load the vertical one. */ 387 /* */ 388 /* <Return> */ 389 /* FreeType error code. 0 means success. */ 390 /* */ 391 typedef FT_Error 392 (*TT_Load_Metrics_Func)( TT_Face face, 393 FT_Stream stream, 394 FT_Bool vertical ); 395 396 397 /*************************************************************************/ 398 /* */ 399 /* <FuncType> */ 400 /* TT_Get_Metrics_Func */ 401 /* */ 402 /* <Description> */ 403 /* Load the horizontal or vertical header in a face object. */ 404 /* */ 405 /* <Input> */ 406 /* face :: A handle to the target face object. */ 407 /* */ 408 /* vertical :: A boolean flag. If set, load vertical metrics. */ 409 /* */ 410 /* gindex :: The glyph index. */ 411 /* */ 412 /* <Output> */ 413 /* abearing :: The horizontal (or vertical) bearing. Set to zero in */ 414 /* case of error. */ 415 /* */ 416 /* aadvance :: The horizontal (or vertical) advance. Set to zero in */ 417 /* case of error. */ 418 /* */ 419 typedef void 420 (*TT_Get_Metrics_Func)( TT_Face face, 421 FT_Bool vertical, 422 FT_UInt gindex, 423 FT_Short* abearing, 424 FT_UShort* aadvance ); 425 426 427 /*************************************************************************/ 428 /* */ 429 /* <FuncType> */ 430 /* TT_Load_Table_Func */ 431 /* */ 432 /* <Description> */ 433 /* Load a given TrueType table. */ 434 /* */ 435 /* <Input> */ 436 /* face :: A handle to the target face object. */ 437 /* */ 438 /* stream :: The input stream. */ 439 /* */ 440 /* <Return> */ 441 /* FreeType error code. 0 means success. */ 442 /* */ 443 /* <Note> */ 444 /* The function uses `face->goto_table' to seek the stream to the */ 445 /* start of the table, except while loading the font directory. */ 446 /* */ 447 typedef FT_Error 448 (*TT_Load_Table_Func)( TT_Face face, 449 FT_Stream stream ); 450 451 452 /*************************************************************************/ 453 /* */ 454 /* <FuncType> */ 455 /* TT_Free_Table_Func */ 456 /* */ 457 /* <Description> */ 458 /* Free a given TrueType table. */ 459 /* */ 460 /* <Input> */ 461 /* face :: A handle to the target face object. */ 462 /* */ 463 typedef void 464 (*TT_Free_Table_Func)( TT_Face face ); 465 466 467 /* 468 * @functype: 469 * TT_Face_GetKerningFunc 470 * 471 * @description: 472 * Return the horizontal kerning value between two glyphs. 473 * 474 * @input: 475 * face :: A handle to the source face object. 476 * left_glyph :: The left glyph index. 477 * right_glyph :: The right glyph index. 478 * 479 * @return: 480 * The kerning value in font units. 481 */ 482 typedef FT_Int 483 (*TT_Face_GetKerningFunc)( TT_Face face, 484 FT_UInt left_glyph, 485 FT_UInt right_glyph ); 486 487 488 /*************************************************************************/ 489 /* */ 490 /* <Struct> */ 491 /* SFNT_Interface */ 492 /* */ 493 /* <Description> */ 494 /* This structure holds pointers to the functions used to load and */ 495 /* free the basic tables that are required in a `sfnt' font file. */ 496 /* */ 497 /* <Fields> */ 498 /* Check the various xxx_Func() descriptions for details. */ 499 /* */ 500 typedef struct SFNT_Interface_ 501 { 502 TT_Loader_GotoTableFunc goto_table; 503 504 TT_Init_Face_Func init_face; 505 TT_Load_Face_Func load_face; 506 TT_Done_Face_Func done_face; 507 FT_Module_Requester get_interface; 508 509 TT_Load_Any_Func load_any; 510 511 /* these functions are called by `load_face' but they can also */ 512 /* be called from external modules, if there is a need to do so */ 513 TT_Load_Table_Func load_head; 514 TT_Load_Metrics_Func load_hhea; 515 TT_Load_Table_Func load_cmap; 516 TT_Load_Table_Func load_maxp; 517 TT_Load_Table_Func load_os2; 518 TT_Load_Table_Func load_post; 519 520 TT_Load_Table_Func load_name; 521 TT_Free_Table_Func free_name; 522 523 /* this field was called `load_kerning' up to version 2.1.10 */ 524 TT_Load_Table_Func load_kern; 525 526 TT_Load_Table_Func load_gasp; 527 TT_Load_Table_Func load_pclt; 528 529 /* see `ttload.h'; this field was called `load_bitmap_header' up to */ 530 /* version 2.1.10 */ 531 TT_Load_Table_Func load_bhed; 532 533 TT_Load_SBit_Image_Func load_sbit_image; 534 535 /* see `ttpost.h' */ 536 TT_Get_PS_Name_Func get_psname; 537 TT_Free_Table_Func free_psnames; 538 539 /* starting here, the structure differs from version 2.1.7 */ 540 541 /* this field was introduced in version 2.1.8, named `get_psname' */ 542 TT_Face_GetKerningFunc get_kerning; 543 544 /* new elements introduced after version 2.1.10 */ 545 546 /* load the font directory, i.e., the offset table and */ 547 /* the table directory */ 548 TT_Load_Table_Func load_font_dir; 549 TT_Load_Metrics_Func load_hmtx; 550 551 TT_Load_Table_Func load_eblc; 552 TT_Free_Table_Func free_eblc; 553 554 TT_Set_SBit_Strike_Func set_sbit_strike; 555 TT_Load_Strike_Metrics_Func load_strike_metrics; 556 557 TT_Get_Metrics_Func get_metrics; 558 559 } SFNT_Interface; 560 561 562 /* transitional */ 563 typedef SFNT_Interface* SFNT_Service; 564 565 #ifndef FT_CONFIG_OPTION_PIC 566 567 #define FT_DEFINE_SFNT_INTERFACE( \ 568 class_, \ 569 goto_table_, \ 570 init_face_, \ 571 load_face_, \ 572 done_face_, \ 573 get_interface_, \ 574 load_any_, \ 575 load_head_, \ 576 load_hhea_, \ 577 load_cmap_, \ 578 load_maxp_, \ 579 load_os2_, \ 580 load_post_, \ 581 load_name_, \ 582 free_name_, \ 583 load_kern_, \ 584 load_gasp_, \ 585 load_pclt_, \ 586 load_bhed_, \ 587 load_sbit_image_, \ 588 get_psname_, \ 589 free_psnames_, \ 590 get_kerning_, \ 591 load_font_dir_, \ 592 load_hmtx_, \ 593 load_eblc_, \ 594 free_eblc_, \ 595 set_sbit_strike_, \ 596 load_strike_metrics_, \ 597 get_metrics_ ) \ 598 static const SFNT_Interface class_ = \ 599 { \ 600 goto_table_, \ 601 init_face_, \ 602 load_face_, \ 603 done_face_, \ 604 get_interface_, \ 605 load_any_, \ 606 load_head_, \ 607 load_hhea_, \ 608 load_cmap_, \ 609 load_maxp_, \ 610 load_os2_, \ 611 load_post_, \ 612 load_name_, \ 613 free_name_, \ 614 load_kern_, \ 615 load_gasp_, \ 616 load_pclt_, \ 617 load_bhed_, \ 618 load_sbit_image_, \ 619 get_psname_, \ 620 free_psnames_, \ 621 get_kerning_, \ 622 load_font_dir_, \ 623 load_hmtx_, \ 624 load_eblc_, \ 625 free_eblc_, \ 626 set_sbit_strike_, \ 627 load_strike_metrics_, \ 628 get_metrics_, \ 629 }; 630 631 #else /* FT_CONFIG_OPTION_PIC */ 632 633 #define FT_INTERNAL( a, a_ ) \ 634 clazz->a = a_; 635 636 #define FT_DEFINE_SFNT_INTERFACE( \ 637 class_, \ 638 goto_table_, \ 639 init_face_, \ 640 load_face_, \ 641 done_face_, \ 642 get_interface_, \ 643 load_any_, \ 644 load_head_, \ 645 load_hhea_, \ 646 load_cmap_, \ 647 load_maxp_, \ 648 load_os2_, \ 649 load_post_, \ 650 load_name_, \ 651 free_name_, \ 652 load_kern_, \ 653 load_gasp_, \ 654 load_pclt_, \ 655 load_bhed_, \ 656 load_sbit_image_, \ 657 get_psname_, \ 658 free_psnames_, \ 659 get_kerning_, \ 660 load_font_dir_, \ 661 load_hmtx_, \ 662 load_eblc_, \ 663 free_eblc_, \ 664 set_sbit_strike_, \ 665 load_strike_metrics_, \ 666 get_metrics_ ) \ 667 void \ 668 FT_Init_Class_ ## class_( FT_Library library, \ 669 SFNT_Interface* clazz ) \ 670 { \ 671 FT_UNUSED( library ); \ 672 \ 673 clazz->goto_table = goto_table_; \ 674 clazz->init_face = init_face_; \ 675 clazz->load_face = load_face_; \ 676 clazz->done_face = done_face_; \ 677 clazz->get_interface = get_interface_; \ 678 clazz->load_any = load_any_; \ 679 clazz->load_head = load_head_; \ 680 clazz->load_hhea = load_hhea_; \ 681 clazz->load_cmap = load_cmap_; \ 682 clazz->load_maxp = load_maxp_; \ 683 clazz->load_os2 = load_os2_; \ 684 clazz->load_post = load_post_; \ 685 clazz->load_name = load_name_; \ 686 clazz->free_name = free_name_; \ 687 clazz->load_kern = load_kern_; \ 688 clazz->load_gasp = load_gasp_; \ 689 clazz->load_pclt = load_pclt_; \ 690 clazz->load_bhed = load_bhed_; \ 691 clazz->load_sbit_image = load_sbit_image_; \ 692 clazz->get_psname = get_psname_; \ 693 clazz->free_psnames = free_psnames_; \ 694 clazz->get_kerning = get_kerning_; \ 695 clazz->load_font_dir = load_font_dir_; \ 696 clazz->load_hmtx = load_hmtx_; \ 697 clazz->load_eblc = load_eblc_; \ 698 clazz->free_eblc = free_eblc_; \ 699 clazz->set_sbit_strike = set_sbit_strike_; \ 700 clazz->load_strike_metrics = load_strike_metrics_; \ 701 clazz->get_metrics = get_metrics_; \ 702 } 703 704 #endif /* FT_CONFIG_OPTION_PIC */ 705 706 FT_END_HEADER 707 708 #endif /* __SFNT_H__ */ 709 710 711 /* END */ 712