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