1 /***************************************************************************/ 2 /* */ 3 /* ftmodapi.h */ 4 /* */ 5 /* FreeType modules public interface (specification). */ 6 /* */ 7 /* Copyright 1996-2003, 2006, 2008-2010, 2012 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 /*************************************************************************/ 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 * It is not possible to set properties of the FreeType Cache 326 * sub-system with FT_Property_Set; use @FTC_Property_Set instead. 327 * 328 * @since: 329 * 2.4.11 330 * 331 */ 332 FT_Error 333 FT_Property_Set( FT_Library library, 334 const FT_String* module_name, 335 const FT_String* property_name, 336 const void* value ); 337 338 339 /********************************************************************** 340 * 341 * @function: 342 * FT_Property_Get 343 * 344 * @description: 345 * Get a module's property value. 346 * 347 * @input: 348 * library :: 349 * A handle to the library the module is part of. 350 * 351 * module_name :: 352 * The module name. 353 * 354 * property_name :: 355 * The property name. Properties are described in the `Synopsis' 356 * subsection of the module's documentation. 357 * 358 * @inout: 359 * value :: 360 * A generic pointer to a variable or structure which gives the 361 * value of the property. The exact definition of `value' is 362 * dependent on the property; see the `Synopsis' subsection of the 363 * module's documentation. 364 * 365 * @return: 366 * FreeType error code. 0~means success. 367 * 368 * @note: 369 * If `module_name' isn't a valid module name, or `property_name' 370 * doesn't specify a valid property, or if `value' doesn't represent a 371 * valid value for the given property, an error is returned. 372 * 373 * The following example gets property `baz' (a range) in module `foo'. 374 * 375 * { 376 * typedef range_ 377 * { 378 * FT_Int32 min; 379 * FT_Int32 max; 380 * 381 * } range; 382 * 383 * range baz; 384 * 385 * 386 * FT_Property_Get( library, "foo", "baz", &baz ); 387 * } 388 * 389 * It is not possible to retrieve properties of the FreeType Cache 390 * sub-system with FT_Property_Get; use @FTC_Property_Get instead. 391 * 392 * @since: 393 * 2.4.11 394 * 395 */ 396 FT_Error 397 FT_Property_Get( FT_Library library, 398 const FT_String* module_name, 399 const FT_String* property_name, 400 void* value ); 401 402 403 /*************************************************************************/ 404 /* */ 405 /* <Function> */ 406 /* FT_Reference_Library */ 407 /* */ 408 /* <Description> */ 409 /* A counter gets initialized to~1 at the time an @FT_Library */ 410 /* structure is created. This function increments the counter. */ 411 /* @FT_Done_Library then only destroys a library if the counter is~1, */ 412 /* otherwise it simply decrements the counter. */ 413 /* */ 414 /* This function helps in managing life-cycles of structures which */ 415 /* reference @FT_Library objects. */ 416 /* */ 417 /* <Input> */ 418 /* library :: A handle to a target library object. */ 419 /* */ 420 /* <Return> */ 421 /* FreeType error code. 0~means success. */ 422 /* */ 423 /* <Since> */ 424 /* 2.4.2 */ 425 /* */ 426 FT_EXPORT( FT_Error ) 427 FT_Reference_Library( FT_Library library ); 428 429 430 /*************************************************************************/ 431 /* */ 432 /* <Function> */ 433 /* FT_New_Library */ 434 /* */ 435 /* <Description> */ 436 /* This function is used to create a new FreeType library instance */ 437 /* from a given memory object. It is thus possible to use libraries */ 438 /* with distinct memory allocators within the same program. */ 439 /* */ 440 /* Normally, you would call this function (followed by a call to */ 441 /* @FT_Add_Default_Modules or a series of calls to @FT_Add_Module) */ 442 /* instead of @FT_Init_FreeType to initialize the FreeType library. */ 443 /* */ 444 /* Don't use @FT_Done_FreeType but @FT_Done_Library to destroy a */ 445 /* library instance. */ 446 /* */ 447 /* <Input> */ 448 /* memory :: A handle to the original memory object. */ 449 /* */ 450 /* <Output> */ 451 /* alibrary :: A pointer to handle of a new library object. */ 452 /* */ 453 /* <Return> */ 454 /* FreeType error code. 0~means success. */ 455 /* */ 456 /* <Note> */ 457 /* See the discussion of reference counters in the description of */ 458 /* @FT_Reference_Library. */ 459 /* */ 460 FT_EXPORT( FT_Error ) 461 FT_New_Library( FT_Memory memory, 462 FT_Library *alibrary ); 463 464 465 /*************************************************************************/ 466 /* */ 467 /* <Function> */ 468 /* FT_Done_Library */ 469 /* */ 470 /* <Description> */ 471 /* Discard a given library object. This closes all drivers and */ 472 /* discards all resource objects. */ 473 /* */ 474 /* <Input> */ 475 /* library :: A handle to the target library. */ 476 /* */ 477 /* <Return> */ 478 /* FreeType error code. 0~means success. */ 479 /* */ 480 /* <Note> */ 481 /* See the discussion of reference counters in the description of */ 482 /* @FT_Reference_Library. */ 483 /* */ 484 FT_EXPORT( FT_Error ) 485 FT_Done_Library( FT_Library library ); 486 487 /* */ 488 489 typedef void 490 (*FT_DebugHook_Func)( void* arg ); 491 492 493 /*************************************************************************/ 494 /* */ 495 /* <Function> */ 496 /* FT_Set_Debug_Hook */ 497 /* */ 498 /* <Description> */ 499 /* Set a debug hook function for debugging the interpreter of a font */ 500 /* format. */ 501 /* */ 502 /* <InOut> */ 503 /* library :: A handle to the library object. */ 504 /* */ 505 /* <Input> */ 506 /* hook_index :: The index of the debug hook. You should use the */ 507 /* values defined in `ftobjs.h', e.g., */ 508 /* `FT_DEBUG_HOOK_TRUETYPE'. */ 509 /* */ 510 /* debug_hook :: The function used to debug the interpreter. */ 511 /* */ 512 /* <Note> */ 513 /* Currently, four debug hook slots are available, but only two (for */ 514 /* the TrueType and the Type~1 interpreter) are defined. */ 515 /* */ 516 /* Since the internal headers of FreeType are no longer installed, */ 517 /* the symbol `FT_DEBUG_HOOK_TRUETYPE' isn't available publicly. */ 518 /* This is a bug and will be fixed in a forthcoming release. */ 519 /* */ 520 FT_EXPORT( void ) 521 FT_Set_Debug_Hook( FT_Library library, 522 FT_UInt hook_index, 523 FT_DebugHook_Func debug_hook ); 524 525 526 /*************************************************************************/ 527 /* */ 528 /* <Function> */ 529 /* FT_Add_Default_Modules */ 530 /* */ 531 /* <Description> */ 532 /* Add the set of default drivers to a given library object. */ 533 /* This is only useful when you create a library object with */ 534 /* @FT_New_Library (usually to plug a custom memory manager). */ 535 /* */ 536 /* <InOut> */ 537 /* library :: A handle to a new library object. */ 538 /* */ 539 FT_EXPORT( void ) 540 FT_Add_Default_Modules( FT_Library library ); 541 542 543 544 /************************************************************************** 545 * 546 * @section: 547 * truetype_engine 548 * 549 * @title: 550 * The TrueType Engine 551 * 552 * @abstract: 553 * TrueType bytecode support. 554 * 555 * @description: 556 * This section contains a function used to query the level of TrueType 557 * bytecode support compiled in this version of the library. 558 * 559 */ 560 561 562 /************************************************************************** 563 * 564 * @enum: 565 * FT_TrueTypeEngineType 566 * 567 * @description: 568 * A list of values describing which kind of TrueType bytecode 569 * engine is implemented in a given FT_Library instance. It is used 570 * by the @FT_Get_TrueType_Engine_Type function. 571 * 572 * @values: 573 * FT_TRUETYPE_ENGINE_TYPE_NONE :: 574 * The library doesn't implement any kind of bytecode interpreter. 575 * 576 * FT_TRUETYPE_ENGINE_TYPE_UNPATENTED :: 577 * The library implements a bytecode interpreter that doesn't 578 * support the patented operations of the TrueType virtual machine. 579 * 580 * Its main use is to load certain Asian fonts which position and 581 * scale glyph components with bytecode instructions. It produces 582 * bad output for most other fonts. 583 * 584 * FT_TRUETYPE_ENGINE_TYPE_PATENTED :: 585 * The library implements a bytecode interpreter that covers 586 * the full instruction set of the TrueType virtual machine (this 587 * was governed by patents until May 2010, hence the name). 588 * 589 * @since: 590 * 2.2 591 * 592 */ 593 typedef enum FT_TrueTypeEngineType_ 594 { 595 FT_TRUETYPE_ENGINE_TYPE_NONE = 0, 596 FT_TRUETYPE_ENGINE_TYPE_UNPATENTED, 597 FT_TRUETYPE_ENGINE_TYPE_PATENTED 598 599 } FT_TrueTypeEngineType; 600 601 602 /************************************************************************** 603 * 604 * @func: 605 * FT_Get_TrueType_Engine_Type 606 * 607 * @description: 608 * Return an @FT_TrueTypeEngineType value to indicate which level of 609 * the TrueType virtual machine a given library instance supports. 610 * 611 * @input: 612 * library :: 613 * A library instance. 614 * 615 * @return: 616 * A value indicating which level is supported. 617 * 618 * @since: 619 * 2.2 620 * 621 */ 622 FT_EXPORT( FT_TrueTypeEngineType ) 623 FT_Get_TrueType_Engine_Type( FT_Library library ); 624 625 626 /* */ 627 628 629 FT_END_HEADER 630 631 #endif /* __FTMODAPI_H__ */ 632 633 634 /* END */ 635