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