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