1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/modules/freetype2/include/ftmodapi.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,641 @@
1.4 +/***************************************************************************/
1.5 +/* */
1.6 +/* ftmodapi.h */
1.7 +/* */
1.8 +/* FreeType modules public interface (specification). */
1.9 +/* */
1.10 +/* Copyright 1996-2003, 2006, 2008-2010, 2012, 2013 by */
1.11 +/* David Turner, Robert Wilhelm, and Werner Lemberg. */
1.12 +/* */
1.13 +/* This file is part of the FreeType project, and may only be used, */
1.14 +/* modified, and distributed under the terms of the FreeType project */
1.15 +/* license, LICENSE.TXT. By continuing to use, modify, or distribute */
1.16 +/* this file you indicate that you have read the license and */
1.17 +/* understand and accept it fully. */
1.18 +/* */
1.19 +/***************************************************************************/
1.20 +
1.21 +
1.22 +#ifndef __FTMODAPI_H__
1.23 +#define __FTMODAPI_H__
1.24 +
1.25 +
1.26 +#include <ft2build.h>
1.27 +#include FT_FREETYPE_H
1.28 +
1.29 +#ifdef FREETYPE_H
1.30 +#error "freetype.h of FreeType 1 has been loaded!"
1.31 +#error "Please fix the directory search order for header files"
1.32 +#error "so that freetype.h of FreeType 2 is found first."
1.33 +#endif
1.34 +
1.35 +
1.36 +FT_BEGIN_HEADER
1.37 +
1.38 +
1.39 + /*************************************************************************/
1.40 + /* */
1.41 + /* <Section> */
1.42 + /* module_management */
1.43 + /* */
1.44 + /* <Title> */
1.45 + /* Module Management */
1.46 + /* */
1.47 + /* <Abstract> */
1.48 + /* How to add, upgrade, remove, and control modules from FreeType. */
1.49 + /* */
1.50 + /* <Description> */
1.51 + /* The definitions below are used to manage modules within FreeType. */
1.52 + /* Modules can be added, upgraded, and removed at runtime. */
1.53 + /* Additionally, some module properties can be controlled also. */
1.54 + /* */
1.55 + /* Here is a list of possible values of the `module_name' field in */
1.56 + /* the @FT_Module_Class structure. */
1.57 + /* */
1.58 + /* { */
1.59 + /* autofitter */
1.60 + /* bdf */
1.61 + /* cff */
1.62 + /* gxvalid */
1.63 + /* otvalid */
1.64 + /* pcf */
1.65 + /* pfr */
1.66 + /* psaux */
1.67 + /* pshinter */
1.68 + /* psnames */
1.69 + /* raster1, raster5 */
1.70 + /* sfnt */
1.71 + /* smooth, smooth-lcd, smooth-lcdv */
1.72 + /* truetype */
1.73 + /* type1 */
1.74 + /* type42 */
1.75 + /* t1cid */
1.76 + /* winfonts */
1.77 + /* } */
1.78 + /* */
1.79 + /* Note that the FreeType Cache sub-system is not a FreeType module. */
1.80 + /* */
1.81 + /*************************************************************************/
1.82 +
1.83 +
1.84 + /* module bit flags */
1.85 +#define FT_MODULE_FONT_DRIVER 1 /* this module is a font driver */
1.86 +#define FT_MODULE_RENDERER 2 /* this module is a renderer */
1.87 +#define FT_MODULE_HINTER 4 /* this module is a glyph hinter */
1.88 +#define FT_MODULE_STYLER 8 /* this module is a styler */
1.89 +
1.90 +#define FT_MODULE_DRIVER_SCALABLE 0x100 /* the driver supports */
1.91 + /* scalable fonts */
1.92 +#define FT_MODULE_DRIVER_NO_OUTLINES 0x200 /* the driver does not */
1.93 + /* support vector outlines */
1.94 +#define FT_MODULE_DRIVER_HAS_HINTER 0x400 /* the driver provides its */
1.95 + /* own hinter */
1.96 +
1.97 +
1.98 + /* deprecated values */
1.99 +#define ft_module_font_driver FT_MODULE_FONT_DRIVER
1.100 +#define ft_module_renderer FT_MODULE_RENDERER
1.101 +#define ft_module_hinter FT_MODULE_HINTER
1.102 +#define ft_module_styler FT_MODULE_STYLER
1.103 +
1.104 +#define ft_module_driver_scalable FT_MODULE_DRIVER_SCALABLE
1.105 +#define ft_module_driver_no_outlines FT_MODULE_DRIVER_NO_OUTLINES
1.106 +#define ft_module_driver_has_hinter FT_MODULE_DRIVER_HAS_HINTER
1.107 +
1.108 +
1.109 + typedef FT_Pointer FT_Module_Interface;
1.110 +
1.111 +
1.112 + /*************************************************************************/
1.113 + /* */
1.114 + /* <FuncType> */
1.115 + /* FT_Module_Constructor */
1.116 + /* */
1.117 + /* <Description> */
1.118 + /* A function used to initialize (not create) a new module object. */
1.119 + /* */
1.120 + /* <Input> */
1.121 + /* module :: The module to initialize. */
1.122 + /* */
1.123 + typedef FT_Error
1.124 + (*FT_Module_Constructor)( FT_Module module );
1.125 +
1.126 +
1.127 + /*************************************************************************/
1.128 + /* */
1.129 + /* <FuncType> */
1.130 + /* FT_Module_Destructor */
1.131 + /* */
1.132 + /* <Description> */
1.133 + /* A function used to finalize (not destroy) a given module object. */
1.134 + /* */
1.135 + /* <Input> */
1.136 + /* module :: The module to finalize. */
1.137 + /* */
1.138 + typedef void
1.139 + (*FT_Module_Destructor)( FT_Module module );
1.140 +
1.141 +
1.142 + /*************************************************************************/
1.143 + /* */
1.144 + /* <FuncType> */
1.145 + /* FT_Module_Requester */
1.146 + /* */
1.147 + /* <Description> */
1.148 + /* A function used to query a given module for a specific interface. */
1.149 + /* */
1.150 + /* <Input> */
1.151 + /* module :: The module to be searched. */
1.152 + /* */
1.153 + /* name :: The name of the interface in the module. */
1.154 + /* */
1.155 + typedef FT_Module_Interface
1.156 + (*FT_Module_Requester)( FT_Module module,
1.157 + const char* name );
1.158 +
1.159 +
1.160 + /*************************************************************************/
1.161 + /* */
1.162 + /* <Struct> */
1.163 + /* FT_Module_Class */
1.164 + /* */
1.165 + /* <Description> */
1.166 + /* The module class descriptor. */
1.167 + /* */
1.168 + /* <Fields> */
1.169 + /* module_flags :: Bit flags describing the module. */
1.170 + /* */
1.171 + /* module_size :: The size of one module object/instance in */
1.172 + /* bytes. */
1.173 + /* */
1.174 + /* module_name :: The name of the module. */
1.175 + /* */
1.176 + /* module_version :: The version, as a 16.16 fixed number */
1.177 + /* (major.minor). */
1.178 + /* */
1.179 + /* module_requires :: The version of FreeType this module requires, */
1.180 + /* as a 16.16 fixed number (major.minor). Starts */
1.181 + /* at version 2.0, i.e., 0x20000. */
1.182 + /* */
1.183 + /* module_init :: The initializing function. */
1.184 + /* */
1.185 + /* module_done :: The finalizing function. */
1.186 + /* */
1.187 + /* get_interface :: The interface requesting function. */
1.188 + /* */
1.189 + typedef struct FT_Module_Class_
1.190 + {
1.191 + FT_ULong module_flags;
1.192 + FT_Long module_size;
1.193 + const FT_String* module_name;
1.194 + FT_Fixed module_version;
1.195 + FT_Fixed module_requires;
1.196 +
1.197 + const void* module_interface;
1.198 +
1.199 + FT_Module_Constructor module_init;
1.200 + FT_Module_Destructor module_done;
1.201 + FT_Module_Requester get_interface;
1.202 +
1.203 + } FT_Module_Class;
1.204 +
1.205 +
1.206 + /*************************************************************************/
1.207 + /* */
1.208 + /* <Function> */
1.209 + /* FT_Add_Module */
1.210 + /* */
1.211 + /* <Description> */
1.212 + /* Add a new module to a given library instance. */
1.213 + /* */
1.214 + /* <InOut> */
1.215 + /* library :: A handle to the library object. */
1.216 + /* */
1.217 + /* <Input> */
1.218 + /* clazz :: A pointer to class descriptor for the module. */
1.219 + /* */
1.220 + /* <Return> */
1.221 + /* FreeType error code. 0~means success. */
1.222 + /* */
1.223 + /* <Note> */
1.224 + /* An error will be returned if a module already exists by that name, */
1.225 + /* or if the module requires a version of FreeType that is too great. */
1.226 + /* */
1.227 + FT_EXPORT( FT_Error )
1.228 + FT_Add_Module( FT_Library library,
1.229 + const FT_Module_Class* clazz );
1.230 +
1.231 +
1.232 + /*************************************************************************/
1.233 + /* */
1.234 + /* <Function> */
1.235 + /* FT_Get_Module */
1.236 + /* */
1.237 + /* <Description> */
1.238 + /* Find a module by its name. */
1.239 + /* */
1.240 + /* <Input> */
1.241 + /* library :: A handle to the library object. */
1.242 + /* */
1.243 + /* module_name :: The module's name (as an ASCII string). */
1.244 + /* */
1.245 + /* <Return> */
1.246 + /* A module handle. 0~if none was found. */
1.247 + /* */
1.248 + /* <Note> */
1.249 + /* FreeType's internal modules aren't documented very well, and you */
1.250 + /* should look up the source code for details. */
1.251 + /* */
1.252 + FT_EXPORT( FT_Module )
1.253 + FT_Get_Module( FT_Library library,
1.254 + const char* module_name );
1.255 +
1.256 +
1.257 + /*************************************************************************/
1.258 + /* */
1.259 + /* <Function> */
1.260 + /* FT_Remove_Module */
1.261 + /* */
1.262 + /* <Description> */
1.263 + /* Remove a given module from a library instance. */
1.264 + /* */
1.265 + /* <InOut> */
1.266 + /* library :: A handle to a library object. */
1.267 + /* */
1.268 + /* <Input> */
1.269 + /* module :: A handle to a module object. */
1.270 + /* */
1.271 + /* <Return> */
1.272 + /* FreeType error code. 0~means success. */
1.273 + /* */
1.274 + /* <Note> */
1.275 + /* The module object is destroyed by the function in case of success. */
1.276 + /* */
1.277 + FT_EXPORT( FT_Error )
1.278 + FT_Remove_Module( FT_Library library,
1.279 + FT_Module module );
1.280 +
1.281 +
1.282 + /**********************************************************************
1.283 + *
1.284 + * @function:
1.285 + * FT_Property_Set
1.286 + *
1.287 + * @description:
1.288 + * Set a property for a given module.
1.289 + *
1.290 + * @input:
1.291 + * library ::
1.292 + * A handle to the library the module is part of.
1.293 + *
1.294 + * module_name ::
1.295 + * The module name.
1.296 + *
1.297 + * property_name ::
1.298 + * The property name. Properties are described in the `Synopsis'
1.299 + * subsection of the module's documentation.
1.300 + *
1.301 + * Note that only a few modules have properties.
1.302 + *
1.303 + * value ::
1.304 + * A generic pointer to a variable or structure that gives the new
1.305 + * value of the property. The exact definition of `value' is
1.306 + * dependent on the property; see the `Synopsis' subsection of the
1.307 + * module's documentation.
1.308 + *
1.309 + * @return:
1.310 + * FreeType error code. 0~means success.
1.311 + *
1.312 + * @note:
1.313 + * If `module_name' isn't a valid module name, or `property_name'
1.314 + * doesn't specify a valid property, or if `value' doesn't represent a
1.315 + * valid value for the given property, an error is returned.
1.316 + *
1.317 + * The following example sets property `bar' (a simple integer) in
1.318 + * module `foo' to value~1.
1.319 + *
1.320 + * {
1.321 + * FT_UInt bar;
1.322 + *
1.323 + *
1.324 + * bar = 1;
1.325 + * FT_Property_Set( library, "foo", "bar", &bar );
1.326 + * }
1.327 + *
1.328 + * Note that the FreeType Cache sub-system doesn't recognize module
1.329 + * property changes. To avoid glyph lookup confusion within the cache
1.330 + * you should call @FTC_Manager_Reset to completely flush the cache if
1.331 + * a module property gets changed after @FTC_Manager_New has been
1.332 + * called.
1.333 + *
1.334 + * It is not possible to set properties of the FreeType Cache
1.335 + * sub-system itself with FT_Property_Set; use @FTC_Property_Set
1.336 + * instead.
1.337 + *
1.338 + * @since:
1.339 + * 2.4.11
1.340 + *
1.341 + */
1.342 + FT_EXPORT( FT_Error )
1.343 + FT_Property_Set( FT_Library library,
1.344 + const FT_String* module_name,
1.345 + const FT_String* property_name,
1.346 + const void* value );
1.347 +
1.348 +
1.349 + /**********************************************************************
1.350 + *
1.351 + * @function:
1.352 + * FT_Property_Get
1.353 + *
1.354 + * @description:
1.355 + * Get a module's property value.
1.356 + *
1.357 + * @input:
1.358 + * library ::
1.359 + * A handle to the library the module is part of.
1.360 + *
1.361 + * module_name ::
1.362 + * The module name.
1.363 + *
1.364 + * property_name ::
1.365 + * The property name. Properties are described in the `Synopsis'
1.366 + * subsection of the module's documentation.
1.367 + *
1.368 + * @inout:
1.369 + * value ::
1.370 + * A generic pointer to a variable or structure that gives the
1.371 + * value of the property. The exact definition of `value' is
1.372 + * dependent on the property; see the `Synopsis' subsection of the
1.373 + * module's documentation.
1.374 + *
1.375 + * @return:
1.376 + * FreeType error code. 0~means success.
1.377 + *
1.378 + * @note:
1.379 + * If `module_name' isn't a valid module name, or `property_name'
1.380 + * doesn't specify a valid property, or if `value' doesn't represent a
1.381 + * valid value for the given property, an error is returned.
1.382 + *
1.383 + * The following example gets property `baz' (a range) in module `foo'.
1.384 + *
1.385 + * {
1.386 + * typedef range_
1.387 + * {
1.388 + * FT_Int32 min;
1.389 + * FT_Int32 max;
1.390 + *
1.391 + * } range;
1.392 + *
1.393 + * range baz;
1.394 + *
1.395 + *
1.396 + * FT_Property_Get( library, "foo", "baz", &baz );
1.397 + * }
1.398 + *
1.399 + * It is not possible to retrieve properties of the FreeType Cache
1.400 + * sub-system with FT_Property_Get; use @FTC_Property_Get instead.
1.401 + *
1.402 + * @since:
1.403 + * 2.4.11
1.404 + *
1.405 + */
1.406 + FT_EXPORT( FT_Error )
1.407 + FT_Property_Get( FT_Library library,
1.408 + const FT_String* module_name,
1.409 + const FT_String* property_name,
1.410 + void* value );
1.411 +
1.412 +
1.413 + /*************************************************************************/
1.414 + /* */
1.415 + /* <Function> */
1.416 + /* FT_Reference_Library */
1.417 + /* */
1.418 + /* <Description> */
1.419 + /* A counter gets initialized to~1 at the time an @FT_Library */
1.420 + /* structure is created. This function increments the counter. */
1.421 + /* @FT_Done_Library then only destroys a library if the counter is~1, */
1.422 + /* otherwise it simply decrements the counter. */
1.423 + /* */
1.424 + /* This function helps in managing life-cycles of structures that */
1.425 + /* reference @FT_Library objects. */
1.426 + /* */
1.427 + /* <Input> */
1.428 + /* library :: A handle to a target library object. */
1.429 + /* */
1.430 + /* <Return> */
1.431 + /* FreeType error code. 0~means success. */
1.432 + /* */
1.433 + /* <Since> */
1.434 + /* 2.4.2 */
1.435 + /* */
1.436 + FT_EXPORT( FT_Error )
1.437 + FT_Reference_Library( FT_Library library );
1.438 +
1.439 +
1.440 + /*************************************************************************/
1.441 + /* */
1.442 + /* <Function> */
1.443 + /* FT_New_Library */
1.444 + /* */
1.445 + /* <Description> */
1.446 + /* This function is used to create a new FreeType library instance */
1.447 + /* from a given memory object. It is thus possible to use libraries */
1.448 + /* with distinct memory allocators within the same program. */
1.449 + /* */
1.450 + /* Normally, you would call this function (followed by a call to */
1.451 + /* @FT_Add_Default_Modules or a series of calls to @FT_Add_Module) */
1.452 + /* instead of @FT_Init_FreeType to initialize the FreeType library. */
1.453 + /* */
1.454 + /* Don't use @FT_Done_FreeType but @FT_Done_Library to destroy a */
1.455 + /* library instance. */
1.456 + /* */
1.457 + /* <Input> */
1.458 + /* memory :: A handle to the original memory object. */
1.459 + /* */
1.460 + /* <Output> */
1.461 + /* alibrary :: A pointer to handle of a new library object. */
1.462 + /* */
1.463 + /* <Return> */
1.464 + /* FreeType error code. 0~means success. */
1.465 + /* */
1.466 + /* <Note> */
1.467 + /* See the discussion of reference counters in the description of */
1.468 + /* @FT_Reference_Library. */
1.469 + /* */
1.470 + FT_EXPORT( FT_Error )
1.471 + FT_New_Library( FT_Memory memory,
1.472 + FT_Library *alibrary );
1.473 +
1.474 +
1.475 + /*************************************************************************/
1.476 + /* */
1.477 + /* <Function> */
1.478 + /* FT_Done_Library */
1.479 + /* */
1.480 + /* <Description> */
1.481 + /* Discard a given library object. This closes all drivers and */
1.482 + /* discards all resource objects. */
1.483 + /* */
1.484 + /* <Input> */
1.485 + /* library :: A handle to the target library. */
1.486 + /* */
1.487 + /* <Return> */
1.488 + /* FreeType error code. 0~means success. */
1.489 + /* */
1.490 + /* <Note> */
1.491 + /* See the discussion of reference counters in the description of */
1.492 + /* @FT_Reference_Library. */
1.493 + /* */
1.494 + FT_EXPORT( FT_Error )
1.495 + FT_Done_Library( FT_Library library );
1.496 +
1.497 +/* */
1.498 +
1.499 + typedef void
1.500 + (*FT_DebugHook_Func)( void* arg );
1.501 +
1.502 +
1.503 + /*************************************************************************/
1.504 + /* */
1.505 + /* <Function> */
1.506 + /* FT_Set_Debug_Hook */
1.507 + /* */
1.508 + /* <Description> */
1.509 + /* Set a debug hook function for debugging the interpreter of a font */
1.510 + /* format. */
1.511 + /* */
1.512 + /* <InOut> */
1.513 + /* library :: A handle to the library object. */
1.514 + /* */
1.515 + /* <Input> */
1.516 + /* hook_index :: The index of the debug hook. You should use the */
1.517 + /* values defined in `ftobjs.h', e.g., */
1.518 + /* `FT_DEBUG_HOOK_TRUETYPE'. */
1.519 + /* */
1.520 + /* debug_hook :: The function used to debug the interpreter. */
1.521 + /* */
1.522 + /* <Note> */
1.523 + /* Currently, four debug hook slots are available, but only two (for */
1.524 + /* the TrueType and the Type~1 interpreter) are defined. */
1.525 + /* */
1.526 + /* Since the internal headers of FreeType are no longer installed, */
1.527 + /* the symbol `FT_DEBUG_HOOK_TRUETYPE' isn't available publicly. */
1.528 + /* This is a bug and will be fixed in a forthcoming release. */
1.529 + /* */
1.530 + FT_EXPORT( void )
1.531 + FT_Set_Debug_Hook( FT_Library library,
1.532 + FT_UInt hook_index,
1.533 + FT_DebugHook_Func debug_hook );
1.534 +
1.535 +
1.536 + /*************************************************************************/
1.537 + /* */
1.538 + /* <Function> */
1.539 + /* FT_Add_Default_Modules */
1.540 + /* */
1.541 + /* <Description> */
1.542 + /* Add the set of default drivers to a given library object. */
1.543 + /* This is only useful when you create a library object with */
1.544 + /* @FT_New_Library (usually to plug a custom memory manager). */
1.545 + /* */
1.546 + /* <InOut> */
1.547 + /* library :: A handle to a new library object. */
1.548 + /* */
1.549 + FT_EXPORT( void )
1.550 + FT_Add_Default_Modules( FT_Library library );
1.551 +
1.552 +
1.553 +
1.554 + /**************************************************************************
1.555 + *
1.556 + * @section:
1.557 + * truetype_engine
1.558 + *
1.559 + * @title:
1.560 + * The TrueType Engine
1.561 + *
1.562 + * @abstract:
1.563 + * TrueType bytecode support.
1.564 + *
1.565 + * @description:
1.566 + * This section contains a function used to query the level of TrueType
1.567 + * bytecode support compiled in this version of the library.
1.568 + *
1.569 + */
1.570 +
1.571 +
1.572 + /**************************************************************************
1.573 + *
1.574 + * @enum:
1.575 + * FT_TrueTypeEngineType
1.576 + *
1.577 + * @description:
1.578 + * A list of values describing which kind of TrueType bytecode
1.579 + * engine is implemented in a given FT_Library instance. It is used
1.580 + * by the @FT_Get_TrueType_Engine_Type function.
1.581 + *
1.582 + * @values:
1.583 + * FT_TRUETYPE_ENGINE_TYPE_NONE ::
1.584 + * The library doesn't implement any kind of bytecode interpreter.
1.585 + *
1.586 + * FT_TRUETYPE_ENGINE_TYPE_UNPATENTED ::
1.587 + * The library implements a bytecode interpreter that doesn't
1.588 + * support the patented operations of the TrueType virtual machine.
1.589 + *
1.590 + * Its main use is to load certain Asian fonts that position and
1.591 + * scale glyph components with bytecode instructions. It produces
1.592 + * bad output for most other fonts.
1.593 + *
1.594 + * FT_TRUETYPE_ENGINE_TYPE_PATENTED ::
1.595 + * The library implements a bytecode interpreter that covers
1.596 + * the full instruction set of the TrueType virtual machine (this
1.597 + * was governed by patents until May 2010, hence the name).
1.598 + *
1.599 + * @since:
1.600 + * 2.2
1.601 + *
1.602 + */
1.603 + typedef enum FT_TrueTypeEngineType_
1.604 + {
1.605 + FT_TRUETYPE_ENGINE_TYPE_NONE = 0,
1.606 + FT_TRUETYPE_ENGINE_TYPE_UNPATENTED,
1.607 + FT_TRUETYPE_ENGINE_TYPE_PATENTED
1.608 +
1.609 + } FT_TrueTypeEngineType;
1.610 +
1.611 +
1.612 + /**************************************************************************
1.613 + *
1.614 + * @func:
1.615 + * FT_Get_TrueType_Engine_Type
1.616 + *
1.617 + * @description:
1.618 + * Return an @FT_TrueTypeEngineType value to indicate which level of
1.619 + * the TrueType virtual machine a given library instance supports.
1.620 + *
1.621 + * @input:
1.622 + * library ::
1.623 + * A library instance.
1.624 + *
1.625 + * @return:
1.626 + * A value indicating which level is supported.
1.627 + *
1.628 + * @since:
1.629 + * 2.2
1.630 + *
1.631 + */
1.632 + FT_EXPORT( FT_TrueTypeEngineType )
1.633 + FT_Get_TrueType_Engine_Type( FT_Library library );
1.634 +
1.635 +
1.636 + /* */
1.637 +
1.638 +
1.639 +FT_END_HEADER
1.640 +
1.641 +#endif /* __FTMODAPI_H__ */
1.642 +
1.643 +
1.644 +/* END */
