1 /***************************************************************************/ 2 /* */ 3 /* sfnt.h */ 4 /* */ 5 /* High-level `sfnt' driver interface (specification). */ 6 /* */ 7 /* Copyright 1996-2016 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_Load_Table_Func */ 462 /* */ 463 /* <Description> */ 464 /* Load a given TrueType table. */ 465 /* */ 466 /* <Input> */ 467 /* face :: A handle to the target face object. */ 468 /* */ 469 /* stream :: The input stream. */ 470 /* */ 471 /* <Return> */ 472 /* FreeType error code. 0 means success. */ 473 /* */ 474 /* <Note> */ 475 /* The function uses `face->goto_table' to seek the stream to the */ 476 /* start of the table, except while loading the font directory. */ 477 /* */ 478 typedef FT_Error 479 (*TT_Load_Table_Func)( TT_Face face, 480 FT_Stream stream ); 481 482 483 /*************************************************************************/ 484 /* */ 485 /* <FuncType> */ 486 /* TT_Free_Table_Func */ 487 /* */ 488 /* <Description> */ 489 /* Free a given TrueType table. */ 490 /* */ 491 /* <Input> */ 492 /* face :: A handle to the target face object. */ 493 /* */ 494 typedef void 495 (*TT_Free_Table_Func)( TT_Face face ); 496 497 498 /* 499 * @functype: 500 * TT_Face_GetKerningFunc 501 * 502 * @description: 503 * Return the horizontal kerning value between two glyphs. 504 * 505 * @input: 506 * face :: A handle to the source face object. 507 * left_glyph :: The left glyph index. 508 * right_glyph :: The right glyph index. 509 * 510 * @return: 511 * The kerning value in font units. 512 */ 513 typedef FT_Int 514 (*TT_Face_GetKerningFunc)( TT_Face face, 515 FT_UInt left_glyph, 516 FT_UInt right_glyph ); 517 518 519 /*************************************************************************/ 520 /* */ 521 /* <Struct> */ 522 /* SFNT_Interface */ 523 /* */ 524 /* <Description> */ 525 /* This structure holds pointers to the functions used to load and */ 526 /* free the basic tables that are required in a `sfnt' font file. */ 527 /* */ 528 /* <Fields> */ 529 /* Check the various xxx_Func() descriptions for details. */ 530 /* */ 531 typedef struct SFNT_Interface_ 532 { 533 TT_Loader_GotoTableFunc goto_table; 534 535 TT_Init_Face_Func init_face; 536 TT_Load_Face_Func load_face; 537 TT_Done_Face_Func done_face; 538 FT_Module_Requester get_interface; 539 540 TT_Load_Any_Func load_any; 541 542 /* these functions are called by `load_face' but they can also */ 543 /* be called from external modules, if there is a need to do so */ 544 TT_Load_Table_Func load_head; 545 TT_Load_Metrics_Func load_hhea; 546 TT_Load_Table_Func load_cmap; 547 TT_Load_Table_Func load_maxp; 548 TT_Load_Table_Func load_os2; 549 TT_Load_Table_Func load_post; 550 551 TT_Load_Table_Func load_name; 552 TT_Free_Table_Func free_name; 553 554 /* this field was called `load_kerning' up to version 2.1.10 */ 555 TT_Load_Table_Func load_kern; 556 557 TT_Load_Table_Func load_gasp; 558 TT_Load_Table_Func load_pclt; 559 560 /* see `ttload.h'; this field was called `load_bitmap_header' up to */ 561 /* version 2.1.10 */ 562 TT_Load_Table_Func load_bhed; 563 564 TT_Load_SBit_Image_Func load_sbit_image; 565 566 /* see `ttpost.h' */ 567 TT_Get_PS_Name_Func get_psname; 568 TT_Free_Table_Func free_psnames; 569 570 /* starting here, the structure differs from version 2.1.7 */ 571 572 /* this field was introduced in version 2.1.8, named `get_psname' */ 573 TT_Face_GetKerningFunc get_kerning; 574 575 /* new elements introduced after version 2.1.10 */ 576 577 /* load the font directory, i.e., the offset table and */ 578 /* the table directory */ 579 TT_Load_Table_Func load_font_dir; 580 TT_Load_Metrics_Func load_hmtx; 581 582 TT_Load_Table_Func load_eblc; 583 TT_Free_Table_Func free_eblc; 584 585 TT_Set_SBit_Strike_Func set_sbit_strike; 586 TT_Load_Strike_Metrics_Func load_strike_metrics; 587 588 TT_Get_Metrics_Func get_metrics; 589 590 TT_Get_Name_Func get_name; 591 592 } SFNT_Interface; 593 594 595 /* transitional */ 596 typedef SFNT_Interface* SFNT_Service; 597 598 #ifndef FT_CONFIG_OPTION_PIC 599 600 #define FT_DEFINE_SFNT_INTERFACE( \ 601 class_, \ 602 goto_table_, \ 603 init_face_, \ 604 load_face_, \ 605 done_face_, \ 606 get_interface_, \ 607 load_any_, \ 608 load_head_, \ 609 load_hhea_, \ 610 load_cmap_, \ 611 load_maxp_, \ 612 load_os2_, \ 613 load_post_, \ 614 load_name_, \ 615 free_name_, \ 616 load_kern_, \ 617 load_gasp_, \ 618 load_pclt_, \ 619 load_bhed_, \ 620 load_sbit_image_, \ 621 get_psname_, \ 622 free_psnames_, \ 623 get_kerning_, \ 624 load_font_dir_, \ 625 load_hmtx_, \ 626 load_eblc_, \ 627 free_eblc_, \ 628 set_sbit_strike_, \ 629 load_strike_metrics_, \ 630 get_metrics_, \ 631 get_name_ ) \ 632 static const SFNT_Interface class_ = \ 633 { \ 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 }; 665 666 #else /* FT_CONFIG_OPTION_PIC */ 667 668 #define FT_INTERNAL( a, a_ ) \ 669 clazz->a = a_; 670 671 #define FT_DEFINE_SFNT_INTERFACE( \ 672 class_, \ 673 goto_table_, \ 674 init_face_, \ 675 load_face_, \ 676 done_face_, \ 677 get_interface_, \ 678 load_any_, \ 679 load_head_, \ 680 load_hhea_, \ 681 load_cmap_, \ 682 load_maxp_, \ 683 load_os2_, \ 684 load_post_, \ 685 load_name_, \ 686 free_name_, \ 687 load_kern_, \ 688 load_gasp_, \ 689 load_pclt_, \ 690 load_bhed_, \ 691 load_sbit_image_, \ 692 get_psname_, \ 693 free_psnames_, \ 694 get_kerning_, \ 695 load_font_dir_, \ 696 load_hmtx_, \ 697 load_eblc_, \ 698 free_eblc_, \ 699 set_sbit_strike_, \ 700 load_strike_metrics_, \ 701 get_metrics_, \ 702 get_name_ ) \ 703 void \ 704 FT_Init_Class_ ## class_( FT_Library library, \ 705 SFNT_Interface* clazz ) \ 706 { \ 707 FT_UNUSED( library ); \ 708 \ 709 clazz->goto_table = goto_table_; \ 710 clazz->init_face = init_face_; \ 711 clazz->load_face = load_face_; \ 712 clazz->done_face = done_face_; \ 713 clazz->get_interface = get_interface_; \ 714 clazz->load_any = load_any_; \ 715 clazz->load_head = load_head_; \ 716 clazz->load_hhea = load_hhea_; \ 717 clazz->load_cmap = load_cmap_; \ 718 clazz->load_maxp = load_maxp_; \ 719 clazz->load_os2 = load_os2_; \ 720 clazz->load_post = load_post_; \ 721 clazz->load_name = load_name_; \ 722 clazz->free_name = free_name_; \ 723 clazz->load_kern = load_kern_; \ 724 clazz->load_gasp = load_gasp_; \ 725 clazz->load_pclt = load_pclt_; \ 726 clazz->load_bhed = load_bhed_; \ 727 clazz->load_sbit_image = load_sbit_image_; \ 728 clazz->get_psname = get_psname_; \ 729 clazz->free_psnames = free_psnames_; \ 730 clazz->get_kerning = get_kerning_; \ 731 clazz->load_font_dir = load_font_dir_; \ 732 clazz->load_hmtx = load_hmtx_; \ 733 clazz->load_eblc = load_eblc_; \ 734 clazz->free_eblc = free_eblc_; \ 735 clazz->set_sbit_strike = set_sbit_strike_; \ 736 clazz->load_strike_metrics = load_strike_metrics_; \ 737 clazz->get_metrics = get_metrics_; \ 738 clazz->get_name = get_name_; \ 739 } 740 741 #endif /* FT_CONFIG_OPTION_PIC */ 742 743 FT_END_HEADER 744 745 #endif /* SFNT_H_ */ 746 747 748 /* END */ 749