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