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