1 /**************************************************************************** 2 * 3 * sfnt.h 4 * 5 * High-level 'sfnt' driver interface (specification). 6 * 7 * Copyright (C) 1996-2019 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 #include FT_INTERNAL_WOFF_TYPES_H 27 28 29 FT_BEGIN_HEADER 30 31 32 /************************************************************************** 33 * 34 * @functype: 35 * TT_Init_Face_Func 36 * 37 * @description: 38 * First part of the SFNT face object initialization. This finds the 39 * face in a SFNT file or collection, and load its format tag in 40 * face->format_tag. 41 * 42 * @input: 43 * stream :: 44 * The input stream. 45 * 46 * face :: 47 * A handle to the target face object. 48 * 49 * face_index :: 50 * The index of the TrueType font, if we are opening a collection, in 51 * bits 0-15. The numbered instance index~+~1 of a GX (sub)font, if 52 * applicable, in bits 16-30. 53 * 54 * num_params :: 55 * The number of additional parameters. 56 * 57 * params :: 58 * Optional additional parameters. 59 * 60 * @return: 61 * FreeType error code. 0 means success. 62 * 63 * @note: 64 * The stream cursor must be at the font file's origin. 65 * 66 * This function recognizes fonts embedded in a 'TrueType collection'. 67 * 68 * Once the format tag has been validated by the font driver, it should 69 * then call the TT_Load_Face_Func() callback to read the rest of the 70 * SFNT tables in the object. 71 */ 72 typedef FT_Error 73 (*TT_Init_Face_Func)( FT_Stream stream, 74 TT_Face face, 75 FT_Int face_index, 76 FT_Int num_params, 77 FT_Parameter* params ); 78 79 80 /************************************************************************** 81 * 82 * @functype: 83 * TT_Load_Face_Func 84 * 85 * @description: 86 * Second part of the SFNT face object initialization. This loads the 87 * common SFNT tables (head, OS/2, maxp, metrics, etc.) in the face 88 * object. 89 * 90 * @input: 91 * stream :: 92 * The input stream. 93 * 94 * face :: 95 * A handle to the target face object. 96 * 97 * face_index :: 98 * The index of the TrueType font, if we are opening a collection, in 99 * bits 0-15. The numbered instance index~+~1 of a GX (sub)font, if 100 * applicable, in bits 16-30. 101 * 102 * num_params :: 103 * The number of additional parameters. 104 * 105 * params :: 106 * Optional additional parameters. 107 * 108 * @return: 109 * FreeType error code. 0 means success. 110 * 111 * @note: 112 * This function must be called after TT_Init_Face_Func(). 113 */ 114 typedef FT_Error 115 (*TT_Load_Face_Func)( FT_Stream stream, 116 TT_Face face, 117 FT_Int face_index, 118 FT_Int num_params, 119 FT_Parameter* params ); 120 121 122 /************************************************************************** 123 * 124 * @functype: 125 * TT_Done_Face_Func 126 * 127 * @description: 128 * A callback used to delete the common SFNT data from a face. 129 * 130 * @input: 131 * face :: 132 * A handle to the target face object. 133 * 134 * @note: 135 * This function does NOT destroy the face object. 136 */ 137 typedef void 138 (*TT_Done_Face_Func)( TT_Face face ); 139 140 141 /************************************************************************** 142 * 143 * @functype: 144 * TT_Load_Any_Func 145 * 146 * @description: 147 * Load any font table into client memory. 148 * 149 * @input: 150 * face :: 151 * The face object to look for. 152 * 153 * tag :: 154 * The tag of table to load. Use the value 0 if you want to access the 155 * whole font file, else set this parameter to a valid TrueType table 156 * tag that you can forge with the MAKE_TT_TAG macro. 157 * 158 * offset :: 159 * The starting offset in the table (or the file if tag == 0). 160 * 161 * length :: 162 * The address of the decision variable: 163 * 164 * If `length == NULL`: Loads the whole table. Returns an error if 165 * 'offset' == 0! 166 * 167 * If `*length == 0`: Exits immediately; returning the length of the 168 * given table or of the font file, depending on the value of 'tag'. 169 * 170 * If `*length != 0`: Loads the next 'length' bytes of table or font, 171 * starting at offset 'offset' (in table or font too). 172 * 173 * @output: 174 * buffer :: 175 * The address of target buffer. 176 * 177 * @return: 178 * TrueType error code. 0 means success. 179 */ 180 typedef FT_Error 181 (*TT_Load_Any_Func)( TT_Face face, 182 FT_ULong tag, 183 FT_Long offset, 184 FT_Byte *buffer, 185 FT_ULong* length ); 186 187 188 /************************************************************************** 189 * 190 * @functype: 191 * TT_Find_SBit_Image_Func 192 * 193 * @description: 194 * Check whether an embedded bitmap (an 'sbit') exists for a given glyph, 195 * at a given strike. 196 * 197 * @input: 198 * face :: 199 * The target face object. 200 * 201 * glyph_index :: 202 * The glyph index. 203 * 204 * strike_index :: 205 * The current strike index. 206 * 207 * @output: 208 * arange :: 209 * The SBit range containing the glyph index. 210 * 211 * astrike :: 212 * The SBit strike containing the glyph index. 213 * 214 * aglyph_offset :: 215 * The offset of the glyph data in 'EBDT' table. 216 * 217 * @return: 218 * FreeType error code. 0 means success. Returns 219 * SFNT_Err_Invalid_Argument if no sbit exists for the requested glyph. 220 */ 221 typedef FT_Error 222 (*TT_Find_SBit_Image_Func)( TT_Face face, 223 FT_UInt glyph_index, 224 FT_ULong strike_index, 225 TT_SBit_Range *arange, 226 TT_SBit_Strike *astrike, 227 FT_ULong *aglyph_offset ); 228 229 230 /************************************************************************** 231 * 232 * @functype: 233 * TT_Load_SBit_Metrics_Func 234 * 235 * @description: 236 * Get the big metrics for a given embedded bitmap. 237 * 238 * @input: 239 * stream :: 240 * The input stream. 241 * 242 * range :: 243 * The SBit range containing the glyph. 244 * 245 * @output: 246 * big_metrics :: 247 * A big SBit metrics structure for the glyph. 248 * 249 * @return: 250 * FreeType error code. 0 means success. 251 * 252 * @note: 253 * The stream cursor must be positioned at the glyph's offset within the 254 * 'EBDT' table before the call. 255 * 256 * If the image format uses variable metrics, the stream cursor is 257 * positioned just after the metrics header in the 'EBDT' table on 258 * function exit. 259 */ 260 typedef FT_Error 261 (*TT_Load_SBit_Metrics_Func)( FT_Stream stream, 262 TT_SBit_Range range, 263 TT_SBit_Metrics metrics ); 264 265 266 /************************************************************************** 267 * 268 * @functype: 269 * TT_Load_SBit_Image_Func 270 * 271 * @description: 272 * Load a given glyph sbit image from the font resource. This also 273 * returns its metrics. 274 * 275 * @input: 276 * face :: 277 * The target face object. 278 * 279 * strike_index :: 280 * The strike index. 281 * 282 * glyph_index :: 283 * The current glyph index. 284 * 285 * load_flags :: 286 * The current load flags. 287 * 288 * stream :: 289 * The input stream. 290 * 291 * @output: 292 * amap :: 293 * The target pixmap. 294 * 295 * ametrics :: 296 * A big sbit metrics structure for the glyph image. 297 * 298 * @return: 299 * FreeType error code. 0 means success. Returns an error if no glyph 300 * sbit exists for the index. 301 * 302 * @note: 303 * The `map.buffer` field is always freed before the glyph is loaded. 304 */ 305 typedef FT_Error 306 (*TT_Load_SBit_Image_Func)( TT_Face face, 307 FT_ULong strike_index, 308 FT_UInt glyph_index, 309 FT_UInt load_flags, 310 FT_Stream stream, 311 FT_Bitmap *amap, 312 TT_SBit_MetricsRec *ametrics ); 313 314 315 /************************************************************************** 316 * 317 * @functype: 318 * TT_Set_SBit_Strike_Func 319 * 320 * @description: 321 * Select an sbit strike for a given size request. 322 * 323 * @input: 324 * face :: 325 * The target face object. 326 * 327 * req :: 328 * The size request. 329 * 330 * @output: 331 * astrike_index :: 332 * The index of the sbit strike. 333 * 334 * @return: 335 * FreeType error code. 0 means success. Returns an error if no sbit 336 * strike exists for the selected ppem values. 337 */ 338 typedef FT_Error 339 (*TT_Set_SBit_Strike_Func)( TT_Face face, 340 FT_Size_Request req, 341 FT_ULong* astrike_index ); 342 343 344 /************************************************************************** 345 * 346 * @functype: 347 * TT_Load_Strike_Metrics_Func 348 * 349 * @description: 350 * Load the metrics of a given strike. 351 * 352 * @input: 353 * face :: 354 * The target face object. 355 * 356 * strike_index :: 357 * The strike index. 358 * 359 * @output: 360 * metrics :: 361 * the metrics of the strike. 362 * 363 * @return: 364 * FreeType error code. 0 means success. Returns an error if no such 365 * sbit strike exists. 366 */ 367 typedef FT_Error 368 (*TT_Load_Strike_Metrics_Func)( TT_Face face, 369 FT_ULong strike_index, 370 FT_Size_Metrics* metrics ); 371 372 373 /************************************************************************** 374 * 375 * @functype: 376 * TT_Get_PS_Name_Func 377 * 378 * @description: 379 * Get the PostScript glyph name of a glyph. 380 * 381 * @input: 382 * idx :: 383 * The glyph index. 384 * 385 * PSname :: 386 * The address of a string pointer. Will be `NULL` in case of error, 387 * otherwise it is a pointer to the glyph name. 388 * 389 * You must not modify the returned string! 390 * 391 * @output: 392 * FreeType error code. 0 means success. 393 */ 394 typedef FT_Error 395 (*TT_Get_PS_Name_Func)( TT_Face face, 396 FT_UInt idx, 397 FT_String** PSname ); 398 399 400 /************************************************************************** 401 * 402 * @functype: 403 * TT_Load_Metrics_Func 404 * 405 * @description: 406 * Load a metrics table, which is a table with a horizontal and a 407 * vertical version. 408 * 409 * @input: 410 * face :: 411 * A handle to the target face object. 412 * 413 * stream :: 414 * The input stream. 415 * 416 * vertical :: 417 * A boolean flag. If set, load the vertical one. 418 * 419 * @return: 420 * FreeType error code. 0 means success. 421 */ 422 typedef FT_Error 423 (*TT_Load_Metrics_Func)( TT_Face face, 424 FT_Stream stream, 425 FT_Bool vertical ); 426 427 428 /************************************************************************** 429 * 430 * @functype: 431 * TT_Get_Metrics_Func 432 * 433 * @description: 434 * Load the horizontal or vertical header in a face object. 435 * 436 * @input: 437 * face :: 438 * A handle to the target face object. 439 * 440 * vertical :: 441 * A boolean flag. If set, load vertical metrics. 442 * 443 * gindex :: 444 * The glyph index. 445 * 446 * @output: 447 * abearing :: 448 * The horizontal (or vertical) bearing. Set to zero in case of error. 449 * 450 * aadvance :: 451 * The horizontal (or vertical) advance. Set to zero in case of error. 452 */ 453 typedef void 454 (*TT_Get_Metrics_Func)( TT_Face face, 455 FT_Bool vertical, 456 FT_UInt gindex, 457 FT_Short* abearing, 458 FT_UShort* aadvance ); 459 460 461 /************************************************************************** 462 * 463 * @functype: 464 * TT_Set_Palette_Func 465 * 466 * @description: 467 * Load the colors into `face->palette` for a given palette index. 468 * 469 * @input: 470 * face :: 471 * The target face object. 472 * 473 * idx :: 474 * The palette index. 475 * 476 * @return: 477 * FreeType error code. 0 means success. 478 */ 479 typedef FT_Error 480 (*TT_Set_Palette_Func)( TT_Face face, 481 FT_UInt idx ); 482 483 484 /************************************************************************** 485 * 486 * @functype: 487 * TT_Get_Colr_Layer_Func 488 * 489 * @description: 490 * Iteratively get the color layer data of a given glyph index. 491 * 492 * @input: 493 * face :: 494 * The target face object. 495 * 496 * base_glyph :: 497 * The glyph index the colored glyph layers are associated with. 498 * 499 * @inout: 500 * iterator :: 501 * An @FT_LayerIterator object. For the first call you should set 502 * `iterator->p` to `NULL`. For all following calls, simply use the 503 * same object again. 504 * 505 * @output: 506 * aglyph_index :: 507 * The glyph index of the current layer. 508 * 509 * acolor_index :: 510 * The color index into the font face's color palette of the current 511 * layer. The value 0xFFFF is special; it doesn't reference a palette 512 * entry but indicates that the text foreground color should be used 513 * instead (to be set up by the application outside of FreeType). 514 * 515 * @return: 516 * Value~1 if everything is OK. If there are no more layers (or if there 517 * are no layers at all), value~0 gets returned. In case of an error, 518 * value~0 is returned also. 519 */ 520 typedef FT_Bool 521 (*TT_Get_Colr_Layer_Func)( TT_Face face, 522 FT_UInt base_glyph, 523 FT_UInt *aglyph_index, 524 FT_UInt *acolor_index, 525 FT_LayerIterator* iterator ); 526 527 528 /************************************************************************** 529 * 530 * @functype: 531 * TT_Blend_Colr_Func 532 * 533 * @description: 534 * Blend the bitmap in `new_glyph` into `base_glyph` using the color 535 * specified by `color_index`. If `color_index` is 0xFFFF, use 536 * `face->foreground_color` if `face->have_foreground_color` is set. 537 * Otherwise check `face->palette_data.palette_flags`: If present and 538 * @FT_PALETTE_FOR_DARK_BACKGROUND is set, use BGRA value 0xFFFFFFFF 539 * (white opaque). Otherwise use BGRA value 0x000000FF (black opaque). 540 * 541 * @input: 542 * face :: 543 * The target face object. 544 * 545 * color_index :: 546 * Color index from the COLR table. 547 * 548 * base_glyph :: 549 * Slot for bitmap to be merged into. The underlying bitmap may get 550 * reallocated. 551 * 552 * new_glyph :: 553 * Slot to be incooperated into `base_glyph`. 554 * 555 * @return: 556 * FreeType error code. 0 means success. Returns an error if 557 * color_index is invalid or reallocation fails. 558 */ 559 typedef FT_Error 560 (*TT_Blend_Colr_Func)( TT_Face face, 561 FT_UInt color_index, 562 FT_GlyphSlot base_glyph, 563 FT_GlyphSlot new_glyph ); 564 565 566 /************************************************************************** 567 * 568 * @functype: 569 * TT_Get_Name_Func 570 * 571 * @description: 572 * From the 'name' table, return a given ENGLISH name record in ASCII. 573 * 574 * @input: 575 * face :: 576 * A handle to the source face object. 577 * 578 * nameid :: 579 * The name id of the name record to return. 580 * 581 * @inout: 582 * name :: 583 * The address of an allocated string pointer. `NULL` if no name is 584 * present. 585 * 586 * @return: 587 * FreeType error code. 0 means success. 588 */ 589 typedef FT_Error 590 (*TT_Get_Name_Func)( TT_Face face, 591 FT_UShort nameid, 592 FT_String** name ); 593 594 595 /************************************************************************** 596 * 597 * @functype: 598 * TT_Get_Name_ID_Func 599 * 600 * @description: 601 * Search whether an ENGLISH version for a given name ID is in the 'name' 602 * table. 603 * 604 * @input: 605 * face :: 606 * A handle to the source face object. 607 * 608 * nameid :: 609 * The name id of the name record to return. 610 * 611 * @output: 612 * win :: 613 * If non-negative, an index into the 'name' table with the 614 * corresponding (3,1) or (3,0) Windows entry. 615 * 616 * apple :: 617 * If non-negative, an index into the 'name' table with the 618 * corresponding (1,0) Apple entry. 619 * 620 * @return: 621 * 1 if there is either a win or apple entry (or both), 0 otheriwse. 622 */ 623 typedef FT_Bool 624 (*TT_Get_Name_ID_Func)( TT_Face face, 625 FT_UShort nameid, 626 FT_Int *win, 627 FT_Int *apple ); 628 629 630 /************************************************************************** 631 * 632 * @functype: 633 * TT_Load_Table_Func 634 * 635 * @description: 636 * Load a given TrueType table. 637 * 638 * @input: 639 * face :: 640 * A handle to the target face object. 641 * 642 * stream :: 643 * The input stream. 644 * 645 * @return: 646 * FreeType error code. 0 means success. 647 * 648 * @note: 649 * The function uses `face->goto_table` to seek the stream to the start 650 * of the table, except while loading the font directory. 651 */ 652 typedef FT_Error 653 (*TT_Load_Table_Func)( TT_Face face, 654 FT_Stream stream ); 655 656 657 /************************************************************************** 658 * 659 * @functype: 660 * TT_Free_Table_Func 661 * 662 * @description: 663 * Free a given TrueType table. 664 * 665 * @input: 666 * face :: 667 * A handle to the target face object. 668 */ 669 typedef void 670 (*TT_Free_Table_Func)( TT_Face face ); 671 672 673 /* 674 * @functype: 675 * TT_Face_GetKerningFunc 676 * 677 * @description: 678 * Return the horizontal kerning value between two glyphs. 679 * 680 * @input: 681 * face :: 682 * A handle to the source face object. 683 * 684 * left_glyph :: 685 * The left glyph index. 686 * 687 * right_glyph :: 688 * The right glyph index. 689 * 690 * @return: 691 * The kerning value in font units. 692 */ 693 typedef FT_Int 694 (*TT_Face_GetKerningFunc)( TT_Face face, 695 FT_UInt left_glyph, 696 FT_UInt right_glyph ); 697 698 699 /************************************************************************** 700 * 701 * @struct: 702 * SFNT_Interface 703 * 704 * @description: 705 * This structure holds pointers to the functions used to load and free 706 * the basic tables that are required in a 'sfnt' font file. 707 * 708 * @fields: 709 * Check the various xxx_Func() descriptions for details. 710 */ 711 typedef struct SFNT_Interface_ 712 { 713 TT_Loader_GotoTableFunc goto_table; 714 715 TT_Init_Face_Func init_face; 716 TT_Load_Face_Func load_face; 717 TT_Done_Face_Func done_face; 718 FT_Module_Requester get_interface; 719 720 TT_Load_Any_Func load_any; 721 722 /* these functions are called by `load_face' but they can also */ 723 /* be called from external modules, if there is a need to do so */ 724 TT_Load_Table_Func load_head; 725 TT_Load_Metrics_Func load_hhea; 726 TT_Load_Table_Func load_cmap; 727 TT_Load_Table_Func load_maxp; 728 TT_Load_Table_Func load_os2; 729 TT_Load_Table_Func load_post; 730 731 TT_Load_Table_Func load_name; 732 TT_Free_Table_Func free_name; 733 734 /* this field was called `load_kerning' up to version 2.1.10 */ 735 TT_Load_Table_Func load_kern; 736 737 TT_Load_Table_Func load_gasp; 738 TT_Load_Table_Func load_pclt; 739 740 /* see `ttload.h'; this field was called `load_bitmap_header' up to */ 741 /* version 2.1.10 */ 742 TT_Load_Table_Func load_bhed; 743 744 TT_Load_SBit_Image_Func load_sbit_image; 745 746 /* see `ttpost.h' */ 747 TT_Get_PS_Name_Func get_psname; 748 TT_Free_Table_Func free_psnames; 749 750 /* starting here, the structure differs from version 2.1.7 */ 751 752 /* this field was introduced in version 2.1.8, named `get_psname' */ 753 TT_Face_GetKerningFunc get_kerning; 754 755 /* new elements introduced after version 2.1.10 */ 756 757 /* load the font directory, i.e., the offset table and */ 758 /* the table directory */ 759 TT_Load_Table_Func load_font_dir; 760 TT_Load_Metrics_Func load_hmtx; 761 762 TT_Load_Table_Func load_eblc; 763 TT_Free_Table_Func free_eblc; 764 765 TT_Set_SBit_Strike_Func set_sbit_strike; 766 TT_Load_Strike_Metrics_Func load_strike_metrics; 767 768 TT_Load_Table_Func load_cpal; 769 TT_Load_Table_Func load_colr; 770 TT_Free_Table_Func free_cpal; 771 TT_Free_Table_Func free_colr; 772 TT_Set_Palette_Func set_palette; 773 TT_Get_Colr_Layer_Func get_colr_layer; 774 TT_Blend_Colr_Func colr_blend; 775 776 TT_Get_Metrics_Func get_metrics; 777 778 TT_Get_Name_Func get_name; 779 TT_Get_Name_ID_Func get_name_id; 780 781 } SFNT_Interface; 782 783 784 /* transitional */ 785 typedef SFNT_Interface* SFNT_Service; 786 787 788 #define FT_DEFINE_SFNT_INTERFACE( \ 789 class_, \ 790 goto_table_, \ 791 init_face_, \ 792 load_face_, \ 793 done_face_, \ 794 get_interface_, \ 795 load_any_, \ 796 load_head_, \ 797 load_hhea_, \ 798 load_cmap_, \ 799 load_maxp_, \ 800 load_os2_, \ 801 load_post_, \ 802 load_name_, \ 803 free_name_, \ 804 load_kern_, \ 805 load_gasp_, \ 806 load_pclt_, \ 807 load_bhed_, \ 808 load_sbit_image_, \ 809 get_psname_, \ 810 free_psnames_, \ 811 get_kerning_, \ 812 load_font_dir_, \ 813 load_hmtx_, \ 814 load_eblc_, \ 815 free_eblc_, \ 816 set_sbit_strike_, \ 817 load_strike_metrics_, \ 818 load_cpal_, \ 819 load_colr_, \ 820 free_cpal_, \ 821 free_colr_, \ 822 set_palette_, \ 823 get_colr_layer_, \ 824 colr_blend_, \ 825 get_metrics_, \ 826 get_name_, \ 827 get_name_id_ ) \ 828 static const SFNT_Interface class_ = \ 829 { \ 830 goto_table_, \ 831 init_face_, \ 832 load_face_, \ 833 done_face_, \ 834 get_interface_, \ 835 load_any_, \ 836 load_head_, \ 837 load_hhea_, \ 838 load_cmap_, \ 839 load_maxp_, \ 840 load_os2_, \ 841 load_post_, \ 842 load_name_, \ 843 free_name_, \ 844 load_kern_, \ 845 load_gasp_, \ 846 load_pclt_, \ 847 load_bhed_, \ 848 load_sbit_image_, \ 849 get_psname_, \ 850 free_psnames_, \ 851 get_kerning_, \ 852 load_font_dir_, \ 853 load_hmtx_, \ 854 load_eblc_, \ 855 free_eblc_, \ 856 set_sbit_strike_, \ 857 load_strike_metrics_, \ 858 load_cpal_, \ 859 load_colr_, \ 860 free_cpal_, \ 861 free_colr_, \ 862 set_palette_, \ 863 get_colr_layer_, \ 864 colr_blend_, \ 865 get_metrics_, \ 866 get_name_, \ 867 get_name_id_ \ 868 }; 869 870 871 FT_END_HEADER 872 873 #endif /* SFNT_H_ */ 874 875 876 /* END */ 877