1 /***************************************************************************/ 2 /* */ 3 /* ftmodapi.h */ 4 /* */ 5 /* FreeType modules public 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 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 section 327 * @properties. 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 section @properties. 335 * 336 * @return: 337 * FreeType error code. 0~means success. 338 * 339 * @note: 340 * If `module_name' isn't a valid module name, or `property_name' 341 * doesn't specify a valid property, or if `value' doesn't represent a 342 * valid value for the given property, an error is returned. 343 * 344 * The following example sets property `bar' (a simple integer) in 345 * module `foo' to value~1. 346 * 347 * { 348 * FT_UInt bar; 349 * 350 * 351 * bar = 1; 352 * FT_Property_Set( library, "foo", "bar", &bar ); 353 * } 354 * 355 * Note that the FreeType Cache sub-system doesn't recognize module 356 * property changes. To avoid glyph lookup confusion within the cache 357 * you should call @FTC_Manager_Reset to completely flush the cache if 358 * a module property gets changed after @FTC_Manager_New has been 359 * called. 360 * 361 * It is not possible to set properties of the FreeType Cache 362 * sub-system itself with FT_Property_Set; use @FTC_Property_Set 363 * instead. 364 * 365 * @since: 366 * 2.4.11 367 * 368 */ 369 FT_EXPORT( FT_Error ) 370 FT_Property_Set( FT_Library library, 371 const FT_String* module_name, 372 const FT_String* property_name, 373 const void* value ); 374 375 376 /********************************************************************** 377 * 378 * @function: 379 * FT_Property_Get 380 * 381 * @description: 382 * Get a module's property value. 383 * 384 * @input: 385 * library :: 386 * A handle to the library the module is part of. 387 * 388 * module_name :: 389 * The module name. 390 * 391 * property_name :: 392 * The property name. Properties are described in section 393 * @properties. 394 * 395 * @inout: 396 * value :: 397 * A generic pointer to a variable or structure that gives the 398 * value of the property. The exact definition of `value' is 399 * dependent on the property; see section @properties. 400 * 401 * @return: 402 * FreeType error code. 0~means success. 403 * 404 * @note: 405 * If `module_name' isn't a valid module name, or `property_name' 406 * doesn't specify a valid property, or if `value' doesn't represent a 407 * valid value for the given property, an error is returned. 408 * 409 * The following example gets property `baz' (a range) in module `foo'. 410 * 411 * { 412 * typedef range_ 413 * { 414 * FT_Int32 min; 415 * FT_Int32 max; 416 * 417 * } range; 418 * 419 * range baz; 420 * 421 * 422 * FT_Property_Get( library, "foo", "baz", &baz ); 423 * } 424 * 425 * It is not possible to retrieve properties of the FreeType Cache 426 * sub-system with FT_Property_Get; use @FTC_Property_Get instead. 427 * 428 * @since: 429 * 2.4.11 430 * 431 */ 432 FT_EXPORT( FT_Error ) 433 FT_Property_Get( FT_Library library, 434 const FT_String* module_name, 435 const FT_String* property_name, 436 void* value ); 437 438 439 /*************************************************************************/ 440 /* */ 441 /* <Function> */ 442 /* FT_Set_Default_Properties */ 443 /* */ 444 /* <Description> */ 445 /* If compilation option FT_CONFIG_OPTION_ENVIRONMENT_PROPERTIES is */ 446 /* set, this function reads the `FREETYPE_PROPERTIES' environment */ 447 /* variable to control driver properties. See section @properties */ 448 /* for more. */ 449 /* */ 450 /* If the compilation option is not set, this function does nothing. */ 451 /* */ 452 /* `FREETYPE_PROPERTIES' has the following syntax form (broken here */ 453 /* into multiple lines for better readability). */ 454 /* */ 455 /* { */ 456 /* <optional whitespace> */ 457 /* <module-name1> ':' */ 458 /* <property-name1> '=' <property-value1> */ 459 /* <whitespace> */ 460 /* <module-name2> ':' */ 461 /* <property-name2> '=' <property-value2> */ 462 /* ... */ 463 /* } */ 464 /* */ 465 /* Example: */ 466 /* */ 467 /* { */ 468 /* FREETYPE_PROPERTIES=truetype:interpreter-version=35 \ */ 469 /* cff:no-stem-darkening=1 \ */ 470 /* autofitter:warping=1 */ 471 /* } */ 472 /* */ 473 /* <InOut> */ 474 /* library :: A handle to a new library object. */ 475 /* */ 476 /* <Since> */ 477 /* 2.8 */ 478 /* */ 479 FT_EXPORT( void ) 480 FT_Set_Default_Properties( FT_Library library ); 481 482 483 /*************************************************************************/ 484 /* */ 485 /* <Function> */ 486 /* FT_Reference_Library */ 487 /* */ 488 /* <Description> */ 489 /* A counter gets initialized to~1 at the time an @FT_Library */ 490 /* structure is created. This function increments the counter. */ 491 /* @FT_Done_Library then only destroys a library if the counter is~1, */ 492 /* otherwise it simply decrements the counter. */ 493 /* */ 494 /* This function helps in managing life-cycles of structures that */ 495 /* reference @FT_Library objects. */ 496 /* */ 497 /* <Input> */ 498 /* library :: A handle to a target library object. */ 499 /* */ 500 /* <Return> */ 501 /* FreeType error code. 0~means success. */ 502 /* */ 503 /* <Since> */ 504 /* 2.4.2 */ 505 /* */ 506 FT_EXPORT( FT_Error ) 507 FT_Reference_Library( FT_Library library ); 508 509 510 /*************************************************************************/ 511 /* */ 512 /* <Function> */ 513 /* FT_New_Library */ 514 /* */ 515 /* <Description> */ 516 /* This function is used to create a new FreeType library instance */ 517 /* from a given memory object. It is thus possible to use libraries */ 518 /* with distinct memory allocators within the same program. Note, */ 519 /* however, that the used @FT_Memory structure is expected to remain */ 520 /* valid for the life of the @FT_Library object. */ 521 /* */ 522 /* Normally, you would call this function (followed by a call to */ 523 /* @FT_Add_Default_Modules or a series of calls to @FT_Add_Module, */ 524 /* and a call to @FT_Set_Default_Properties) instead of */ 525 /* @FT_Init_FreeType to initialize the FreeType library. */ 526 /* */ 527 /* Don't use @FT_Done_FreeType but @FT_Done_Library to destroy a */ 528 /* library instance. */ 529 /* */ 530 /* <Input> */ 531 /* memory :: A handle to the original memory object. */ 532 /* */ 533 /* <Output> */ 534 /* alibrary :: A pointer to handle of a new library object. */ 535 /* */ 536 /* <Return> */ 537 /* FreeType error code. 0~means success. */ 538 /* */ 539 /* <Note> */ 540 /* See the discussion of reference counters in the description of */ 541 /* @FT_Reference_Library. */ 542 /* */ 543 FT_EXPORT( FT_Error ) 544 FT_New_Library( FT_Memory memory, 545 FT_Library *alibrary ); 546 547 548 /*************************************************************************/ 549 /* */ 550 /* <Function> */ 551 /* FT_Done_Library */ 552 /* */ 553 /* <Description> */ 554 /* Discard a given library object. This closes all drivers and */ 555 /* discards all resource objects. */ 556 /* */ 557 /* <Input> */ 558 /* library :: A handle to the target library. */ 559 /* */ 560 /* <Return> */ 561 /* FreeType error code. 0~means success. */ 562 /* */ 563 /* <Note> */ 564 /* See the discussion of reference counters in the description of */ 565 /* @FT_Reference_Library. */ 566 /* */ 567 FT_EXPORT( FT_Error ) 568 FT_Done_Library( FT_Library library ); 569 570 /* */ 571 572 typedef void 573 (*FT_DebugHook_Func)( void* arg ); 574 575 576 /*************************************************************************/ 577 /* */ 578 /* <Function> */ 579 /* FT_Set_Debug_Hook */ 580 /* */ 581 /* <Description> */ 582 /* Set a debug hook function for debugging the interpreter of a font */ 583 /* format. */ 584 /* */ 585 /* <InOut> */ 586 /* library :: A handle to the library object. */ 587 /* */ 588 /* <Input> */ 589 /* hook_index :: The index of the debug hook. You should use the */ 590 /* values defined in `ftobjs.h', e.g., */ 591 /* `FT_DEBUG_HOOK_TRUETYPE'. */ 592 /* */ 593 /* debug_hook :: The function used to debug the interpreter. */ 594 /* */ 595 /* <Note> */ 596 /* Currently, four debug hook slots are available, but only two (for */ 597 /* the TrueType and the Type~1 interpreter) are defined. */ 598 /* */ 599 /* Since the internal headers of FreeType are no longer installed, */ 600 /* the symbol `FT_DEBUG_HOOK_TRUETYPE' isn't available publicly. */ 601 /* This is a bug and will be fixed in a forthcoming release. */ 602 /* */ 603 FT_EXPORT( void ) 604 FT_Set_Debug_Hook( FT_Library library, 605 FT_UInt hook_index, 606 FT_DebugHook_Func debug_hook ); 607 608 609 /*************************************************************************/ 610 /* */ 611 /* <Function> */ 612 /* FT_Add_Default_Modules */ 613 /* */ 614 /* <Description> */ 615 /* Add the set of default drivers to a given library object. */ 616 /* This is only useful when you create a library object with */ 617 /* @FT_New_Library (usually to plug a custom memory manager). */ 618 /* */ 619 /* <InOut> */ 620 /* library :: A handle to a new library object. */ 621 /* */ 622 FT_EXPORT( void ) 623 FT_Add_Default_Modules( FT_Library library ); 624 625 626 627 /************************************************************************** 628 * 629 * @section: 630 * truetype_engine 631 * 632 * @title: 633 * The TrueType Engine 634 * 635 * @abstract: 636 * TrueType bytecode support. 637 * 638 * @description: 639 * This section contains a function used to query the level of TrueType 640 * bytecode support compiled in this version of the library. 641 * 642 */ 643 644 645 /************************************************************************** 646 * 647 * @enum: 648 * FT_TrueTypeEngineType 649 * 650 * @description: 651 * A list of values describing which kind of TrueType bytecode 652 * engine is implemented in a given FT_Library instance. It is used 653 * by the @FT_Get_TrueType_Engine_Type function. 654 * 655 * @values: 656 * FT_TRUETYPE_ENGINE_TYPE_NONE :: 657 * The library doesn't implement any kind of bytecode interpreter. 658 * 659 * FT_TRUETYPE_ENGINE_TYPE_UNPATENTED :: 660 * Deprecated and removed. 661 * 662 * FT_TRUETYPE_ENGINE_TYPE_PATENTED :: 663 * The library implements a bytecode interpreter that covers 664 * the full instruction set of the TrueType virtual machine (this 665 * was governed by patents until May 2010, hence the name). 666 * 667 * @since: 668 * 2.2 669 * 670 */ 671 typedef enum FT_TrueTypeEngineType_ 672 { 673 FT_TRUETYPE_ENGINE_TYPE_NONE = 0, 674 FT_TRUETYPE_ENGINE_TYPE_UNPATENTED, 675 FT_TRUETYPE_ENGINE_TYPE_PATENTED 676 677 } FT_TrueTypeEngineType; 678 679 680 /************************************************************************** 681 * 682 * @func: 683 * FT_Get_TrueType_Engine_Type 684 * 685 * @description: 686 * Return an @FT_TrueTypeEngineType value to indicate which level of 687 * the TrueType virtual machine a given library instance supports. 688 * 689 * @input: 690 * library :: 691 * A library instance. 692 * 693 * @return: 694 * A value indicating which level is supported. 695 * 696 * @since: 697 * 2.2 698 * 699 */ 700 FT_EXPORT( FT_TrueTypeEngineType ) 701 FT_Get_TrueType_Engine_Type( FT_Library library ); 702 703 /* */ 704 705 706 FT_END_HEADER 707 708 #endif /* FTMODAPI_H_ */ 709 710 711 /* END */ 712