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