include/freetype/ftmodapi.h

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