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