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