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