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