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