1 /**************************************************************************** 2 * 3 * ftmodapi.h 4 * 5 * FreeType modules public interface (specification). 6 * 7 * Copyright (C) 1996-2021 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 FTMODAPI_H_ 20 #define FTMODAPI_H_ 21 22 23 #include <freetype/freetype.h> 24 25 #ifdef FREETYPE_H 26 #error "freetype.h of FreeType 1 has been loaded!" 27 #error "Please fix the directory search order for header files" 28 #error "so that freetype.h of FreeType 2 is found first." 29 #endif 30 31 32 FT_BEGIN_HEADER 33 34 35 /************************************************************************** 36 * 37 * @section: 38 * module_management 39 * 40 * @title: 41 * Module Management 42 * 43 * @abstract: 44 * How to add, upgrade, remove, and control modules from FreeType. 45 * 46 * @description: 47 * The definitions below are used to manage modules within FreeType. 48 * Internal and external modules can be added, upgraded, and removed at 49 * runtime. For example, an alternative renderer or proprietary font 50 * driver can be registered and prioritized. Additionally, some module 51 * properties can also be controlled. 52 * 53 * Here is a list of existing values of the `module_name` field in the 54 * @FT_Module_Class structure. 55 * 56 * ``` 57 * autofitter 58 * bdf 59 * cff 60 * gxvalid 61 * otvalid 62 * pcf 63 * pfr 64 * psaux 65 * pshinter 66 * psnames 67 * raster1 68 * sfnt 69 * smooth 70 * truetype 71 * type1 72 * type42 73 * t1cid 74 * winfonts 75 * ``` 76 * 77 * Note that the FreeType Cache sub-system is not a FreeType module. 78 * 79 * @order: 80 * FT_Module 81 * FT_Module_Constructor 82 * FT_Module_Destructor 83 * FT_Module_Requester 84 * FT_Module_Class 85 * 86 * FT_Add_Module 87 * FT_Get_Module 88 * FT_Remove_Module 89 * FT_Add_Default_Modules 90 * 91 * FT_FACE_DRIVER_NAME 92 * FT_Property_Set 93 * FT_Property_Get 94 * FT_Set_Default_Properties 95 * 96 * FT_New_Library 97 * FT_Done_Library 98 * FT_Reference_Library 99 * 100 * FT_Renderer 101 * FT_Renderer_Class 102 * 103 * FT_Get_Renderer 104 * FT_Set_Renderer 105 * 106 * FT_Set_Debug_Hook 107 * 108 */ 109 110 111 /* module bit flags */ 112 #define FT_MODULE_FONT_DRIVER 1 /* this module is a font driver */ 113 #define FT_MODULE_RENDERER 2 /* this module is a renderer */ 114 #define FT_MODULE_HINTER 4 /* this module is a glyph hinter */ 115 #define FT_MODULE_STYLER 8 /* this module is a styler */ 116 117 #define FT_MODULE_DRIVER_SCALABLE 0x100 /* the driver supports */ 118 /* scalable fonts */ 119 #define FT_MODULE_DRIVER_NO_OUTLINES 0x200 /* the driver does not */ 120 /* support vector outlines */ 121 #define FT_MODULE_DRIVER_HAS_HINTER 0x400 /* the driver provides its */ 122 /* own hinter */ 123 #define FT_MODULE_DRIVER_HINTS_LIGHTLY 0x800 /* the driver's hinter */ 124 /* produces LIGHT hints */ 125 126 127 /* deprecated values */ 128 #define ft_module_font_driver FT_MODULE_FONT_DRIVER 129 #define ft_module_renderer FT_MODULE_RENDERER 130 #define ft_module_hinter FT_MODULE_HINTER 131 #define ft_module_styler FT_MODULE_STYLER 132 133 #define ft_module_driver_scalable FT_MODULE_DRIVER_SCALABLE 134 #define ft_module_driver_no_outlines FT_MODULE_DRIVER_NO_OUTLINES 135 #define ft_module_driver_has_hinter FT_MODULE_DRIVER_HAS_HINTER 136 #define ft_module_driver_hints_lightly FT_MODULE_DRIVER_HINTS_LIGHTLY 137 138 139 typedef FT_Pointer FT_Module_Interface; 140 141 142 /************************************************************************** 143 * 144 * @functype: 145 * FT_Module_Constructor 146 * 147 * @description: 148 * A function used to initialize (not create) a new module object. 149 * 150 * @input: 151 * module :: 152 * The module to initialize. 153 */ 154 typedef FT_Error 155 (*FT_Module_Constructor)( FT_Module module ); 156 157 158 /************************************************************************** 159 * 160 * @functype: 161 * FT_Module_Destructor 162 * 163 * @description: 164 * A function used to finalize (not destroy) a given module object. 165 * 166 * @input: 167 * module :: 168 * The module to finalize. 169 */ 170 typedef void 171 (*FT_Module_Destructor)( FT_Module module ); 172 173 174 /************************************************************************** 175 * 176 * @functype: 177 * FT_Module_Requester 178 * 179 * @description: 180 * A function used to query a given module for a specific interface. 181 * 182 * @input: 183 * module :: 184 * The module to be searched. 185 * 186 * name :: 187 * The name of the interface in the module. 188 */ 189 typedef FT_Module_Interface 190 (*FT_Module_Requester)( FT_Module module, 191 const char* name ); 192 193 194 /************************************************************************** 195 * 196 * @struct: 197 * FT_Module_Class 198 * 199 * @description: 200 * The module class descriptor. While being a public structure necessary 201 * for FreeType's module bookkeeping, most of the fields are essentially 202 * internal, not to be used directly by an application. 203 * 204 * @fields: 205 * module_flags :: 206 * Bit flags describing the module. 207 * 208 * module_size :: 209 * The size of one module object/instance in bytes. 210 * 211 * module_name :: 212 * The name of the module. 213 * 214 * module_version :: 215 * The version, as a 16.16 fixed number (major.minor). 216 * 217 * module_requires :: 218 * The version of FreeType this module requires, as a 16.16 fixed 219 * number (major.minor). Starts at version 2.0, i.e., 0x20000. 220 * 221 * module_interface :: 222 * A typeless pointer to a structure (which varies between different 223 * modules) that holds the module's interface functions. This is 224 * essentially what `get_interface` returns. 225 * 226 * module_init :: 227 * The initializing function. 228 * 229 * module_done :: 230 * The finalizing function. 231 * 232 * get_interface :: 233 * The interface requesting function. 234 */ 235 typedef struct FT_Module_Class_ 236 { 237 FT_ULong module_flags; 238 FT_Long module_size; 239 const FT_String* module_name; 240 FT_Fixed module_version; 241 FT_Fixed module_requires; 242 243 const void* module_interface; 244 245 FT_Module_Constructor module_init; 246 FT_Module_Destructor module_done; 247 FT_Module_Requester get_interface; 248 249 } FT_Module_Class; 250 251 252 /************************************************************************** 253 * 254 * @function: 255 * FT_Add_Module 256 * 257 * @description: 258 * Add a new module to a given library instance. 259 * 260 * @inout: 261 * library :: 262 * A handle to the library object. 263 * 264 * @input: 265 * clazz :: 266 * A pointer to class descriptor for the module. 267 * 268 * @return: 269 * FreeType error code. 0~means success. 270 * 271 * @note: 272 * An error will be returned if a module already exists by that name, or 273 * if the module requires a version of FreeType that is too great. 274 */ 275 FT_EXPORT( FT_Error ) 276 FT_Add_Module( FT_Library library, 277 const FT_Module_Class* clazz ); 278 279 280 /************************************************************************** 281 * 282 * @function: 283 * FT_Get_Module 284 * 285 * @description: 286 * Find a module by its name. 287 * 288 * @input: 289 * library :: 290 * A handle to the library object. 291 * 292 * module_name :: 293 * The module's name (as an ASCII string). 294 * 295 * @return: 296 * A module handle. 0~if none was found. 297 * 298 * @note: 299 * FreeType's internal modules aren't documented very well, and you 300 * should look up the source code for details. 301 */ 302 FT_EXPORT( FT_Module ) 303 FT_Get_Module( FT_Library library, 304 const char* module_name ); 305 306 307 /************************************************************************** 308 * 309 * @function: 310 * FT_Remove_Module 311 * 312 * @description: 313 * Remove a given module from a library instance. 314 * 315 * @inout: 316 * library :: 317 * A handle to a library object. 318 * 319 * @input: 320 * module :: 321 * A handle to a module object. 322 * 323 * @return: 324 * FreeType error code. 0~means success. 325 * 326 * @note: 327 * The module object is destroyed by the function in case of success. 328 */ 329 FT_EXPORT( FT_Error ) 330 FT_Remove_Module( FT_Library library, 331 FT_Module module ); 332 333 334 /************************************************************************** 335 * 336 * @macro: 337 * FT_FACE_DRIVER_NAME 338 * 339 * @description: 340 * A macro that retrieves the name of a font driver from a face object. 341 * 342 * @note: 343 * The font driver name is a valid `module_name` for @FT_Property_Set 344 * and @FT_Property_Get. This is not the same as @FT_Get_Font_Format. 345 * 346 * @since: 347 * 2.11 348 * 349 */ 350 #define FT_FACE_DRIVER_NAME( face ) \ 351 ( ( *(FT_Module_Class**)( ( face )->driver ) )->module_name ) 352 353 354 /************************************************************************** 355 * 356 * @function: 357 * FT_Property_Set 358 * 359 * @description: 360 * Set a property for a given module. 361 * 362 * @input: 363 * library :: 364 * A handle to the library the module is part of. 365 * 366 * module_name :: 367 * The module name. 368 * 369 * property_name :: 370 * The property name. Properties are described in section 371 * @properties. 372 * 373 * Note that only a few modules have properties. 374 * 375 * value :: 376 * A generic pointer to a variable or structure that gives the new 377 * value of the property. The exact definition of `value` is 378 * dependent on the property; see section @properties. 379 * 380 * @return: 381 * FreeType error code. 0~means success. 382 * 383 * @note: 384 * If `module_name` isn't a valid module name, or `property_name` 385 * doesn't specify a valid property, or if `value` doesn't represent a 386 * valid value for the given property, an error is returned. 387 * 388 * The following example sets property 'bar' (a simple integer) in 389 * module 'foo' to value~1. 390 * 391 * ``` 392 * FT_UInt bar; 393 * 394 * 395 * bar = 1; 396 * FT_Property_Set( library, "foo", "bar", &bar ); 397 * ``` 398 * 399 * Note that the FreeType Cache sub-system doesn't recognize module 400 * property changes. To avoid glyph lookup confusion within the cache 401 * you should call @FTC_Manager_Reset to completely flush the cache if a 402 * module property gets changed after @FTC_Manager_New has been called. 403 * 404 * It is not possible to set properties of the FreeType Cache sub-system 405 * itself with FT_Property_Set; use @FTC_Property_Set instead. 406 * 407 * @since: 408 * 2.4.11 409 * 410 */ 411 FT_EXPORT( FT_Error ) 412 FT_Property_Set( FT_Library library, 413 const FT_String* module_name, 414 const FT_String* property_name, 415 const void* value ); 416 417 418 /************************************************************************** 419 * 420 * @function: 421 * FT_Property_Get 422 * 423 * @description: 424 * Get a module's property value. 425 * 426 * @input: 427 * library :: 428 * A handle to the library the module is part of. 429 * 430 * module_name :: 431 * The module name. 432 * 433 * property_name :: 434 * The property name. Properties are described in section 435 * @properties. 436 * 437 * @inout: 438 * value :: 439 * A generic pointer to a variable or structure that gives the value 440 * of the property. The exact definition of `value` is dependent on 441 * the property; see section @properties. 442 * 443 * @return: 444 * FreeType error code. 0~means success. 445 * 446 * @note: 447 * If `module_name` isn't a valid module name, or `property_name` 448 * doesn't specify a valid property, or if `value` doesn't represent a 449 * valid value for the given property, an error is returned. 450 * 451 * The following example gets property 'baz' (a range) in module 'foo'. 452 * 453 * ``` 454 * typedef range_ 455 * { 456 * FT_Int32 min; 457 * FT_Int32 max; 458 * 459 * } range; 460 * 461 * range baz; 462 * 463 * 464 * FT_Property_Get( library, "foo", "baz", &baz ); 465 * ``` 466 * 467 * It is not possible to retrieve properties of the FreeType Cache 468 * sub-system with FT_Property_Get; use @FTC_Property_Get instead. 469 * 470 * @since: 471 * 2.4.11 472 * 473 */ 474 FT_EXPORT( FT_Error ) 475 FT_Property_Get( FT_Library library, 476 const FT_String* module_name, 477 const FT_String* property_name, 478 void* value ); 479 480 481 /************************************************************************** 482 * 483 * @function: 484 * FT_Set_Default_Properties 485 * 486 * @description: 487 * If compilation option `FT_CONFIG_OPTION_ENVIRONMENT_PROPERTIES` is 488 * set, this function reads the `FREETYPE_PROPERTIES` environment 489 * variable to control driver properties. See section @properties for 490 * more. 491 * 492 * If the compilation option is not set, this function does nothing. 493 * 494 * `FREETYPE_PROPERTIES` has the following syntax form (broken here into 495 * multiple lines for better readability). 496 * 497 * ``` 498 * <optional whitespace> 499 * <module-name1> ':' 500 * <property-name1> '=' <property-value1> 501 * <whitespace> 502 * <module-name2> ':' 503 * <property-name2> '=' <property-value2> 504 * ... 505 * ``` 506 * 507 * Example: 508 * 509 * ``` 510 * FREETYPE_PROPERTIES=truetype:interpreter-version=35 \ 511 * cff:no-stem-darkening=0 512 * ``` 513 * 514 * @inout: 515 * library :: 516 * A handle to a new library object. 517 * 518 * @since: 519 * 2.8 520 */ 521 FT_EXPORT( void ) 522 FT_Set_Default_Properties( FT_Library library ); 523 524 525 /************************************************************************** 526 * 527 * @function: 528 * FT_Reference_Library 529 * 530 * @description: 531 * A counter gets initialized to~1 at the time an @FT_Library structure 532 * is created. This function increments the counter. @FT_Done_Library 533 * then only destroys a library if the counter is~1, otherwise it simply 534 * decrements the counter. 535 * 536 * This function helps in managing life-cycles of structures that 537 * reference @FT_Library objects. 538 * 539 * @input: 540 * library :: 541 * A handle to a target library object. 542 * 543 * @return: 544 * FreeType error code. 0~means success. 545 * 546 * @since: 547 * 2.4.2 548 */ 549 FT_EXPORT( FT_Error ) 550 FT_Reference_Library( FT_Library library ); 551 552 553 /************************************************************************** 554 * 555 * @function: 556 * FT_New_Library 557 * 558 * @description: 559 * This function is used to create a new FreeType library instance from a 560 * given memory object. It is thus possible to use libraries with 561 * distinct memory allocators within the same program. Note, however, 562 * that the used @FT_Memory structure is expected to remain valid for the 563 * life of the @FT_Library object. 564 * 565 * Normally, you would call this function (followed by a call to 566 * @FT_Add_Default_Modules or a series of calls to @FT_Add_Module, and a 567 * call to @FT_Set_Default_Properties) instead of @FT_Init_FreeType to 568 * initialize the FreeType library. 569 * 570 * Don't use @FT_Done_FreeType but @FT_Done_Library to destroy a library 571 * instance. 572 * 573 * @input: 574 * memory :: 575 * A handle to the original memory object. 576 * 577 * @output: 578 * alibrary :: 579 * A pointer to handle of a new library object. 580 * 581 * @return: 582 * FreeType error code. 0~means success. 583 * 584 * @note: 585 * See the discussion of reference counters in the description of 586 * @FT_Reference_Library. 587 */ 588 FT_EXPORT( FT_Error ) 589 FT_New_Library( FT_Memory memory, 590 FT_Library *alibrary ); 591 592 593 /************************************************************************** 594 * 595 * @function: 596 * FT_Done_Library 597 * 598 * @description: 599 * Discard a given library object. This closes all drivers and discards 600 * all resource objects. 601 * 602 * @input: 603 * library :: 604 * A handle to the target library. 605 * 606 * @return: 607 * FreeType error code. 0~means success. 608 * 609 * @note: 610 * See the discussion of reference counters in the description of 611 * @FT_Reference_Library. 612 */ 613 FT_EXPORT( FT_Error ) 614 FT_Done_Library( FT_Library library ); 615 616 617 /************************************************************************** 618 * 619 * @functype: 620 * FT_DebugHook_Func 621 * 622 * @description: 623 * A drop-in replacement (or rather a wrapper) for the bytecode or 624 * charstring interpreter's main loop function. 625 * 626 * Its job is essentially 627 * 628 * - to activate debug mode to enforce single-stepping, 629 * 630 * - to call the main loop function to interpret the next opcode, and 631 * 632 * - to show the changed context to the user. 633 * 634 * An example for such a main loop function is `TT_RunIns` (declared in 635 * FreeType's internal header file `src/truetype/ttinterp.h`). 636 * 637 * Have a look at the source code of the `ttdebug` FreeType demo program 638 * for an example of a drop-in replacement. 639 * 640 * @inout: 641 * arg :: 642 * A typeless pointer, to be cast to the main loop function's data 643 * structure (which depends on the font module). For TrueType fonts 644 * it is bytecode interpreter's execution context, `TT_ExecContext`, 645 * which is declared in FreeType's internal header file `tttypes.h`. 646 */ 647 typedef FT_Error 648 (*FT_DebugHook_Func)( void* arg ); 649 650 651 /************************************************************************** 652 * 653 * @enum: 654 * FT_DEBUG_HOOK_XXX 655 * 656 * @description: 657 * A list of named debug hook indices. 658 * 659 * @values: 660 * FT_DEBUG_HOOK_TRUETYPE:: 661 * This hook index identifies the TrueType bytecode debugger. 662 */ 663 #define FT_DEBUG_HOOK_TRUETYPE 0 664 665 666 /************************************************************************** 667 * 668 * @function: 669 * FT_Set_Debug_Hook 670 * 671 * @description: 672 * Set a debug hook function for debugging the interpreter of a font 673 * format. 674 * 675 * While this is a public API function, an application needs access to 676 * FreeType's internal header files to do something useful. 677 * 678 * Have a look at the source code of the `ttdebug` FreeType demo program 679 * for an example of its usage. 680 * 681 * @inout: 682 * library :: 683 * A handle to the library object. 684 * 685 * @input: 686 * hook_index :: 687 * The index of the debug hook. You should use defined enumeration 688 * macros like @FT_DEBUG_HOOK_TRUETYPE. 689 * 690 * debug_hook :: 691 * The function used to debug the interpreter. 692 * 693 * @note: 694 * Currently, four debug hook slots are available, but only one (for the 695 * TrueType interpreter) is defined. 696 */ 697 FT_EXPORT( void ) 698 FT_Set_Debug_Hook( FT_Library library, 699 FT_UInt hook_index, 700 FT_DebugHook_Func debug_hook ); 701 702 703 /************************************************************************** 704 * 705 * @function: 706 * FT_Add_Default_Modules 707 * 708 * @description: 709 * Add the set of default drivers to a given library object. This is 710 * only useful when you create a library object with @FT_New_Library 711 * (usually to plug a custom memory manager). 712 * 713 * @inout: 714 * library :: 715 * A handle to a new library object. 716 */ 717 FT_EXPORT( void ) 718 FT_Add_Default_Modules( FT_Library library ); 719 720 721 722 /************************************************************************** 723 * 724 * @section: 725 * truetype_engine 726 * 727 * @title: 728 * The TrueType Engine 729 * 730 * @abstract: 731 * TrueType bytecode support. 732 * 733 * @description: 734 * This section contains a function used to query the level of TrueType 735 * bytecode support compiled in this version of the library. 736 * 737 */ 738 739 740 /************************************************************************** 741 * 742 * @enum: 743 * FT_TrueTypeEngineType 744 * 745 * @description: 746 * A list of values describing which kind of TrueType bytecode engine is 747 * implemented in a given FT_Library instance. It is used by the 748 * @FT_Get_TrueType_Engine_Type function. 749 * 750 * @values: 751 * FT_TRUETYPE_ENGINE_TYPE_NONE :: 752 * The library doesn't implement any kind of bytecode interpreter. 753 * 754 * FT_TRUETYPE_ENGINE_TYPE_UNPATENTED :: 755 * Deprecated and removed. 756 * 757 * FT_TRUETYPE_ENGINE_TYPE_PATENTED :: 758 * The library implements a bytecode interpreter that covers the full 759 * instruction set of the TrueType virtual machine (this was governed 760 * by patents until May 2010, hence the name). 761 * 762 * @since: 763 * 2.2 764 * 765 */ 766 typedef enum FT_TrueTypeEngineType_ 767 { 768 FT_TRUETYPE_ENGINE_TYPE_NONE = 0, 769 FT_TRUETYPE_ENGINE_TYPE_UNPATENTED, 770 FT_TRUETYPE_ENGINE_TYPE_PATENTED 771 772 } FT_TrueTypeEngineType; 773 774 775 /************************************************************************** 776 * 777 * @function: 778 * FT_Get_TrueType_Engine_Type 779 * 780 * @description: 781 * Return an @FT_TrueTypeEngineType value to indicate which level of the 782 * TrueType virtual machine a given library instance supports. 783 * 784 * @input: 785 * library :: 786 * A library instance. 787 * 788 * @return: 789 * A value indicating which level is supported. 790 * 791 * @since: 792 * 2.2 793 * 794 */ 795 FT_EXPORT( FT_TrueTypeEngineType ) 796 FT_Get_TrueType_Engine_Type( FT_Library library ); 797 798 /* */ 799 800 801 FT_END_HEADER 802 803 #endif /* FTMODAPI_H_ */ 804 805 806 /* END */ 807