Clutter Engine 0.0.1
Loading...
Searching...
No Matches
freetype.h
1/***************************************************************************/
2/* */
3/* freetype.h */
4/* */
5/* FreeType high-level API and common types (specification only). */
6/* */
7/* Copyright 1996-2016 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 FREETYPE_H_
20#define FREETYPE_H_
21
22
23#ifndef FT_FREETYPE_H
24#error "`ft2build.h' hasn't been included yet!"
25#error "Please always use macros to include FreeType header files."
26#error "Example:"
27#error " #include <ft2build.h>"
28#error " #include FT_FREETYPE_H"
29#endif
30
31
32#include <ft2build.h>
33#include FT_CONFIG_CONFIG_H
34#include FT_TYPES_H
35#include FT_ERRORS_H
36
37
38FT_BEGIN_HEADER
39
40
41
42 /*************************************************************************/
43 /* */
44 /* <Section> */
45 /* header_inclusion */
46 /* */
47 /* <Title> */
48 /* FreeType's header inclusion scheme */
49 /* */
50 /* <Abstract> */
51 /* How client applications should include FreeType header files. */
52 /* */
53 /* <Description> */
54 /* To be as flexible as possible (and for historical reasons), */
55 /* FreeType uses a very special inclusion scheme to load header */
56 /* files, for example */
57 /* */
58 /* { */
59 /* #include <ft2build.h> */
60 /* */
61 /* #include FT_FREETYPE_H */
62 /* #include FT_OUTLINE_H */
63 /* } */
64 /* */
65 /* A compiler and its preprocessor only needs an include path to find */
66 /* the file `ft2build.h'; the exact locations and names of the other */
67 /* FreeType header files are hidden by preprocessor macro names, */
68 /* loaded by `ft2build.h'. The API documentation always gives the */
69 /* header macro name needed for a particular function. */
70 /* */
71 /*************************************************************************/
72
73
74 /*************************************************************************/
75 /* */
76 /* <Section> */
77 /* user_allocation */
78 /* */
79 /* <Title> */
80 /* User allocation */
81 /* */
82 /* <Abstract> */
83 /* How client applications should allocate FreeType data structures. */
84 /* */
85 /* <Description> */
86 /* FreeType assumes that structures allocated by the user and passed */
87 /* as arguments are zeroed out except for the actual data. In other */
88 /* words, it is recommended to use `calloc' (or variants of it) */
89 /* instead of `malloc' for allocation. */
90 /* */
91 /*************************************************************************/
92
93
94
95 /*************************************************************************/
96 /*************************************************************************/
97 /* */
98 /* B A S I C T Y P E S */
99 /* */
100 /*************************************************************************/
101 /*************************************************************************/
102
103
104 /*************************************************************************/
105 /* */
106 /* <Section> */
107 /* base_interface */
108 /* */
109 /* <Title> */
110 /* Base Interface */
111 /* */
112 /* <Abstract> */
113 /* The FreeType~2 base font interface. */
114 /* */
115 /* <Description> */
116 /* This section describes the most important public high-level API */
117 /* functions of FreeType~2. */
118 /* */
119 /* <Order> */
120 /* FT_Library */
121 /* FT_Face */
122 /* FT_Size */
123 /* FT_GlyphSlot */
124 /* FT_CharMap */
125 /* FT_Encoding */
126 /* FT_ENC_TAG */
127 /* */
128 /* FT_FaceRec */
129 /* */
130 /* FT_FACE_FLAG_SCALABLE */
131 /* FT_FACE_FLAG_FIXED_SIZES */
132 /* FT_FACE_FLAG_FIXED_WIDTH */
133 /* FT_FACE_FLAG_HORIZONTAL */
134 /* FT_FACE_FLAG_VERTICAL */
135 /* FT_FACE_FLAG_COLOR */
136 /* FT_FACE_FLAG_SFNT */
137 /* FT_FACE_FLAG_CID_KEYED */
138 /* FT_FACE_FLAG_TRICKY */
139 /* FT_FACE_FLAG_KERNING */
140 /* FT_FACE_FLAG_MULTIPLE_MASTERS */
141 /* FT_FACE_FLAG_GLYPH_NAMES */
142 /* FT_FACE_FLAG_EXTERNAL_STREAM */
143 /* FT_FACE_FLAG_HINTER */
144 /* */
145 /* FT_HAS_HORIZONTAL */
146 /* FT_HAS_VERTICAL */
147 /* FT_HAS_KERNING */
148 /* FT_HAS_FIXED_SIZES */
149 /* FT_HAS_GLYPH_NAMES */
150 /* FT_HAS_MULTIPLE_MASTERS */
151 /* FT_HAS_COLOR */
152 /* */
153 /* FT_IS_SFNT */
154 /* FT_IS_SCALABLE */
155 /* FT_IS_FIXED_WIDTH */
156 /* FT_IS_CID_KEYED */
157 /* FT_IS_TRICKY */
158 /* */
159 /* FT_STYLE_FLAG_BOLD */
160 /* FT_STYLE_FLAG_ITALIC */
161 /* */
162 /* FT_SizeRec */
163 /* FT_Size_Metrics */
164 /* */
165 /* FT_GlyphSlotRec */
166 /* FT_Glyph_Metrics */
167 /* FT_SubGlyph */
168 /* */
169 /* FT_Bitmap_Size */
170 /* */
171 /* FT_Init_FreeType */
172 /* FT_Done_FreeType */
173 /* */
174 /* FT_New_Face */
175 /* FT_Done_Face */
176 /* FT_Reference_Face */
177 /* FT_New_Memory_Face */
178 /* FT_Open_Face */
179 /* FT_Open_Args */
180 /* FT_Parameter */
181 /* FT_Attach_File */
182 /* FT_Attach_Stream */
183 /* */
184 /* FT_Set_Char_Size */
185 /* FT_Set_Pixel_Sizes */
186 /* FT_Request_Size */
187 /* FT_Select_Size */
188 /* FT_Size_Request_Type */
189 /* FT_Size_RequestRec */
190 /* FT_Size_Request */
191 /* FT_Set_Transform */
192 /* FT_Load_Glyph */
193 /* FT_Get_Char_Index */
194 /* FT_Get_First_Char */
195 /* FT_Get_Next_Char */
196 /* FT_Get_Name_Index */
197 /* FT_Load_Char */
198 /* */
199 /* FT_OPEN_MEMORY */
200 /* FT_OPEN_STREAM */
201 /* FT_OPEN_PATHNAME */
202 /* FT_OPEN_DRIVER */
203 /* FT_OPEN_PARAMS */
204 /* */
205 /* FT_LOAD_DEFAULT */
206 /* FT_LOAD_RENDER */
207 /* FT_LOAD_MONOCHROME */
208 /* FT_LOAD_LINEAR_DESIGN */
209 /* FT_LOAD_NO_SCALE */
210 /* FT_LOAD_NO_HINTING */
211 /* FT_LOAD_NO_BITMAP */
212 /* FT_LOAD_NO_AUTOHINT */
213 /* FT_LOAD_COLOR */
214 /* */
215 /* FT_LOAD_VERTICAL_LAYOUT */
216 /* FT_LOAD_IGNORE_TRANSFORM */
217 /* FT_LOAD_FORCE_AUTOHINT */
218 /* FT_LOAD_NO_RECURSE */
219 /* FT_LOAD_PEDANTIC */
220 /* */
221 /* FT_LOAD_TARGET_NORMAL */
222 /* FT_LOAD_TARGET_LIGHT */
223 /* FT_LOAD_TARGET_MONO */
224 /* FT_LOAD_TARGET_LCD */
225 /* FT_LOAD_TARGET_LCD_V */
226 /* */
227 /* FT_LOAD_TARGET_MODE */
228 /* */
229 /* FT_Render_Glyph */
230 /* FT_Render_Mode */
231 /* FT_Get_Kerning */
232 /* FT_Kerning_Mode */
233 /* FT_Get_Track_Kerning */
234 /* FT_Get_Glyph_Name */
235 /* FT_Get_Postscript_Name */
236 /* */
237 /* FT_CharMapRec */
238 /* FT_Select_Charmap */
239 /* FT_Set_Charmap */
240 /* FT_Get_Charmap_Index */
241 /* */
242 /* FT_Get_FSType_Flags */
243 /* FT_Get_SubGlyph_Info */
244 /* */
245 /* FT_Face_Internal */
246 /* FT_Size_Internal */
247 /* FT_Slot_Internal */
248 /* */
249 /* FT_FACE_FLAG_XXX */
250 /* FT_STYLE_FLAG_XXX */
251 /* FT_OPEN_XXX */
252 /* FT_LOAD_XXX */
253 /* FT_LOAD_TARGET_XXX */
254 /* FT_SUBGLYPH_FLAG_XXX */
255 /* FT_FSTYPE_XXX */
256 /* */
257 /* FT_HAS_FAST_GLYPHS */
258 /* */
259 /*************************************************************************/
260
261
262 /*************************************************************************/
263 /* */
264 /* <Struct> */
265 /* FT_Glyph_Metrics */
266 /* */
267 /* <Description> */
268 /* A structure used to model the metrics of a single glyph. The */
269 /* values are expressed in 26.6 fractional pixel format; if the flag */
270 /* @FT_LOAD_NO_SCALE has been used while loading the glyph, values */
271 /* are expressed in font units instead. */
272 /* */
273 /* <Fields> */
274 /* width :: */
275 /* The glyph's width. */
276 /* */
277 /* height :: */
278 /* The glyph's height. */
279 /* */
280 /* horiBearingX :: */
281 /* Left side bearing for horizontal layout. */
282 /* */
283 /* horiBearingY :: */
284 /* Top side bearing for horizontal layout. */
285 /* */
286 /* horiAdvance :: */
287 /* Advance width for horizontal layout. */
288 /* */
289 /* vertBearingX :: */
290 /* Left side bearing for vertical layout. */
291 /* */
292 /* vertBearingY :: */
293 /* Top side bearing for vertical layout. Larger positive values */
294 /* mean further below the vertical glyph origin. */
295 /* */
296 /* vertAdvance :: */
297 /* Advance height for vertical layout. Positive values mean the */
298 /* glyph has a positive advance downward. */
299 /* */
300 /* <Note> */
301 /* If not disabled with @FT_LOAD_NO_HINTING, the values represent */
302 /* dimensions of the hinted glyph (in case hinting is applicable). */
303 /* */
304 /* Stroking a glyph with an outside border does not increase */
305 /* `horiAdvance' or `vertAdvance'; you have to manually adjust these */
306 /* values to account for the added width and height. */
307 /* */
308 typedef struct FT_Glyph_Metrics_
309 {
310 FT_Pos width;
311 FT_Pos height;
312
313 FT_Pos horiBearingX;
314 FT_Pos horiBearingY;
315 FT_Pos horiAdvance;
316
317 FT_Pos vertBearingX;
318 FT_Pos vertBearingY;
319 FT_Pos vertAdvance;
320
321 } FT_Glyph_Metrics;
322
323
324 /*************************************************************************/
325 /* */
326 /* <Struct> */
327 /* FT_Bitmap_Size */
328 /* */
329 /* <Description> */
330 /* This structure models the metrics of a bitmap strike (i.e., a set */
331 /* of glyphs for a given point size and resolution) in a bitmap font. */
332 /* It is used for the `available_sizes' field of @FT_Face. */
333 /* */
334 /* <Fields> */
335 /* height :: The vertical distance, in pixels, between two */
336 /* consecutive baselines. It is always positive. */
337 /* */
338 /* width :: The average width, in pixels, of all glyphs in the */
339 /* strike. */
340 /* */
341 /* size :: The nominal size of the strike in 26.6 fractional */
342 /* points. This field is not very useful. */
343 /* */
344 /* x_ppem :: The horizontal ppem (nominal width) in 26.6 fractional */
345 /* pixels. */
346 /* */
347 /* y_ppem :: The vertical ppem (nominal height) in 26.6 fractional */
348 /* pixels. */
349 /* */
350 /* <Note> */
351 /* Windows FNT: */
352 /* The nominal size given in a FNT font is not reliable. Thus when */
353 /* the driver finds it incorrect, it sets `size' to some calculated */
354 /* values and sets `x_ppem' and `y_ppem' to the pixel width and */
355 /* height given in the font, respectively. */
356 /* */
357 /* TrueType embedded bitmaps: */
358 /* `size', `width', and `height' values are not contained in the */
359 /* bitmap strike itself. They are computed from the global font */
360 /* parameters. */
361 /* */
362 typedef struct FT_Bitmap_Size_
363 {
364 FT_Short height;
365 FT_Short width;
366
367 FT_Pos size;
368
369 FT_Pos x_ppem;
370 FT_Pos y_ppem;
371
372 } FT_Bitmap_Size;
373
374
375 /*************************************************************************/
376 /*************************************************************************/
377 /* */
378 /* O B J E C T C L A S S E S */
379 /* */
380 /*************************************************************************/
381 /*************************************************************************/
382
383 /*************************************************************************/
384 /* */
385 /* <Type> */
386 /* FT_Library */
387 /* */
388 /* <Description> */
389 /* A handle to a FreeType library instance. Each `library' is */
390 /* completely independent from the others; it is the `root' of a set */
391 /* of objects like fonts, faces, sizes, etc. */
392 /* */
393 /* It also embeds a memory manager (see @FT_Memory), as well as a */
394 /* scan-line converter object (see @FT_Raster). */
395 /* */
396 /* In multi-threaded applications it is easiest to use one */
397 /* `FT_Library' object per thread. In case this is too cumbersome, */
398 /* a single `FT_Library' object across threads is possible also */
399 /* (since FreeType version 2.5.6), as long as a mutex lock is used */
400 /* around @FT_New_Face and @FT_Done_Face. */
401 /* */
402 /* <Note> */
403 /* Library objects are normally created by @FT_Init_FreeType, and */
404 /* destroyed with @FT_Done_FreeType. If you need reference-counting */
405 /* (cf. @FT_Reference_Library), use @FT_New_Library and */
406 /* @FT_Done_Library. */
407 /* */
408 typedef struct FT_LibraryRec_ *FT_Library;
409
410
411 /*************************************************************************/
412 /* */
413 /* <Section> */
414 /* module_management */
415 /* */
416 /*************************************************************************/
417
418 /*************************************************************************/
419 /* */
420 /* <Type> */
421 /* FT_Module */
422 /* */
423 /* <Description> */
424 /* A handle to a given FreeType module object. Each module can be a */
425 /* font driver, a renderer, or anything else that provides services */
426 /* to the formers. */
427 /* */
428 typedef struct FT_ModuleRec_* FT_Module;
429
430
431 /*************************************************************************/
432 /* */
433 /* <Type> */
434 /* FT_Driver */
435 /* */
436 /* <Description> */
437 /* A handle to a given FreeType font driver object. Each font driver */
438 /* is a special module capable of creating faces from font files. */
439 /* */
440 typedef struct FT_DriverRec_* FT_Driver;
441
442
443 /*************************************************************************/
444 /* */
445 /* <Type> */
446 /* FT_Renderer */
447 /* */
448 /* <Description> */
449 /* A handle to a given FreeType renderer. A renderer is a special */
450 /* module in charge of converting a glyph image to a bitmap, when */
451 /* necessary. Each renderer supports a given glyph image format, and */
452 /* one or more target surface depths. */
453 /* */
454 typedef struct FT_RendererRec_* FT_Renderer;
455
456
457 /*************************************************************************/
458 /* */
459 /* <Section> */
460 /* base_interface */
461 /* */
462 /*************************************************************************/
463
464 /*************************************************************************/
465 /* */
466 /* <Type> */
467 /* FT_Face */
468 /* */
469 /* <Description> */
470 /* A handle to a given typographic face object. A face object models */
471 /* a given typeface, in a given style. */
472 /* */
473 /* <Note> */
474 /* Each face object also owns a single @FT_GlyphSlot object, as well */
475 /* as one or more @FT_Size objects. */
476 /* */
477 /* Use @FT_New_Face or @FT_Open_Face to create a new face object from */
478 /* a given filepathname or a custom input stream. */
479 /* */
480 /* Use @FT_Done_Face to destroy it (along with its slot and sizes). */
481 /* */
482 /* An `FT_Face' object can only be safely used from one thread at a */
483 /* time. Similarly, creation and destruction of `FT_Face' with the */
484 /* same @FT_Library object can only be done from one thread at a */
485 /* time. On the other hand, functions like @FT_Load_Glyph and its */
486 /* siblings are thread-safe and do not need the lock to be held as */
487 /* long as the same `FT_Face' object is not used from multiple */
488 /* threads at the same time. */
489 /* */
490 /* <Also> */
491 /* See @FT_FaceRec for the publicly accessible fields of a given face */
492 /* object. */
493 /* */
494 typedef struct FT_FaceRec_* FT_Face;
495
496
497 /*************************************************************************/
498 /* */
499 /* <Type> */
500 /* FT_Size */
501 /* */
502 /* <Description> */
503 /* A handle to an object used to model a face scaled to a given */
504 /* character size. */
505 /* */
506 /* <Note> */
507 /* Each @FT_Face has an _active_ @FT_Size object that is used by */
508 /* functions like @FT_Load_Glyph to determine the scaling */
509 /* transformation that in turn is used to load and hint glyphs and */
510 /* metrics. */
511 /* */
512 /* You can use @FT_Set_Char_Size, @FT_Set_Pixel_Sizes, */
513 /* @FT_Request_Size or even @FT_Select_Size to change the content */
514 /* (i.e., the scaling values) of the active @FT_Size. */
515 /* */
516 /* You can use @FT_New_Size to create additional size objects for a */
517 /* given @FT_Face, but they won't be used by other functions until */
518 /* you activate it through @FT_Activate_Size. Only one size can be */
519 /* activated at any given time per face. */
520 /* */
521 /* <Also> */
522 /* See @FT_SizeRec for the publicly accessible fields of a given size */
523 /* object. */
524 /* */
525 typedef struct FT_SizeRec_* FT_Size;
526
527
528 /*************************************************************************/
529 /* */
530 /* <Type> */
531 /* FT_GlyphSlot */
532 /* */
533 /* <Description> */
534 /* A handle to a given `glyph slot'. A slot is a container where it */
535 /* is possible to load any of the glyphs contained in its parent */
536 /* face. */
537 /* */
538 /* In other words, each time you call @FT_Load_Glyph or */
539 /* @FT_Load_Char, the slot's content is erased by the new glyph data, */
540 /* i.e., the glyph's metrics, its image (bitmap or outline), and */
541 /* other control information. */
542 /* */
543 /* <Also> */
544 /* See @FT_GlyphSlotRec for the publicly accessible glyph fields. */
545 /* */
546 typedef struct FT_GlyphSlotRec_* FT_GlyphSlot;
547
548
549 /*************************************************************************/
550 /* */
551 /* <Type> */
552 /* FT_CharMap */
553 /* */
554 /* <Description> */
555 /* A handle to a given character map. A charmap is used to translate */
556 /* character codes in a given encoding into glyph indexes for its */
557 /* parent's face. Some font formats may provide several charmaps per */
558 /* font. */
559 /* */
560 /* Each face object owns zero or more charmaps, but only one of them */
561 /* can be `active' and used by @FT_Get_Char_Index or @FT_Load_Char. */
562 /* */
563 /* The list of available charmaps in a face is available through the */
564 /* `face->num_charmaps' and `face->charmaps' fields of @FT_FaceRec. */
565 /* */
566 /* The currently active charmap is available as `face->charmap'. */
567 /* You should call @FT_Set_Charmap to change it. */
568 /* */
569 /* <Note> */
570 /* When a new face is created (either through @FT_New_Face or */
571 /* @FT_Open_Face), the library looks for a Unicode charmap within */
572 /* the list and automatically activates it. */
573 /* */
574 /* <Also> */
575 /* See @FT_CharMapRec for the publicly accessible fields of a given */
576 /* character map. */
577 /* */
578 typedef struct FT_CharMapRec_* FT_CharMap;
579
580
581 /*************************************************************************/
582 /* */
583 /* <Macro> */
584 /* FT_ENC_TAG */
585 /* */
586 /* <Description> */
587 /* This macro converts four-letter tags into an unsigned long. It is */
588 /* used to define `encoding' identifiers (see @FT_Encoding). */
589 /* */
590 /* <Note> */
591 /* Since many 16-bit compilers don't like 32-bit enumerations, you */
592 /* should redefine this macro in case of problems to something like */
593 /* this: */
594 /* */
595 /* { */
596 /* #define FT_ENC_TAG( value, a, b, c, d ) value */
597 /* } */
598 /* */
599 /* to get a simple enumeration without assigning special numbers. */
600 /* */
601
602#ifndef FT_ENC_TAG
603#define FT_ENC_TAG( value, a, b, c, d ) \
604 value = ( ( (FT_UInt32)(a) << 24 ) | \
605 ( (FT_UInt32)(b) << 16 ) | \
606 ( (FT_UInt32)(c) << 8 ) | \
607 (FT_UInt32)(d) )
608
609#endif /* FT_ENC_TAG */
610
611
612 /*************************************************************************/
613 /* */
614 /* <Enum> */
615 /* FT_Encoding */
616 /* */
617 /* <Description> */
618 /* An enumeration used to specify character sets supported by */
619 /* charmaps. Used in the @FT_Select_Charmap API function. */
620 /* */
621 /* <Note> */
622 /* Despite the name, this enumeration lists specific character */
623 /* repertories (i.e., charsets), and not text encoding methods (e.g., */
624 /* UTF-8, UTF-16, etc.). */
625 /* */
626 /* Other encodings might be defined in the future. */
627 /* */
628 /* <Values> */
629 /* FT_ENCODING_NONE :: */
630 /* The encoding value~0 is reserved. */
631 /* */
632 /* FT_ENCODING_UNICODE :: */
633 /* Corresponds to the Unicode character set. This value covers */
634 /* all versions of the Unicode repertoire, including ASCII and */
635 /* Latin-1. Most fonts include a Unicode charmap, but not all */
636 /* of them. */
637 /* */
638 /* For example, if you want to access Unicode value U+1F028 (and */
639 /* the font contains it), use value 0x1F028 as the input value for */
640 /* @FT_Get_Char_Index. */
641 /* */
642 /* FT_ENCODING_MS_SYMBOL :: */
643 /* Corresponds to the Microsoft Symbol encoding, used to encode */
644 /* mathematical symbols and wingdings. For more information, see */
645 /* `http://www.microsoft.com/typography/otspec/recom.htm', */
646 /* `http://www.kostis.net/charsets/symbol.htm', and */
647 /* `http://www.kostis.net/charsets/wingding.htm'. */
648 /* */
649 /* This encoding uses character codes from the PUA (Private Unicode */
650 /* Area) in the range U+F020-U+F0FF. */
651 /* */
652 /* FT_ENCODING_SJIS :: */
653 /* Corresponds to Japanese SJIS encoding. More info at */
654 /* at `http://en.wikipedia.org/wiki/Shift_JIS'. */
655 /* See note on multi-byte encodings below. */
656 /* */
657 /* FT_ENCODING_GB2312 :: */
658 /* Corresponds to an encoding system for Simplified Chinese as used */
659 /* used in mainland China. */
660 /* */
661 /* FT_ENCODING_BIG5 :: */
662 /* Corresponds to an encoding system for Traditional Chinese as */
663 /* used in Taiwan and Hong Kong. */
664 /* */
665 /* FT_ENCODING_WANSUNG :: */
666 /* Corresponds to the Korean encoding system known as Wansung. */
667 /* For more information see */
668 /* `https://msdn.microsoft.com/en-US/goglobal/cc305154'. */
669 /* */
670 /* FT_ENCODING_JOHAB :: */
671 /* The Korean standard character set (KS~C 5601-1992), which */
672 /* corresponds to MS Windows code page 1361. This character set */
673 /* includes all possible Hangeul character combinations. */
674 /* */
675 /* FT_ENCODING_ADOBE_LATIN_1 :: */
676 /* Corresponds to a Latin-1 encoding as defined in a Type~1 */
677 /* PostScript font. It is limited to 256 character codes. */
678 /* */
679 /* FT_ENCODING_ADOBE_STANDARD :: */
680 /* Corresponds to the Adobe Standard encoding, as found in Type~1, */
681 /* CFF, and OpenType/CFF fonts. It is limited to 256 character */
682 /* codes. */
683 /* */
684 /* FT_ENCODING_ADOBE_EXPERT :: */
685 /* Corresponds to the Adobe Expert encoding, as found in Type~1, */
686 /* CFF, and OpenType/CFF fonts. It is limited to 256 character */
687 /* codes. */
688 /* */
689 /* FT_ENCODING_ADOBE_CUSTOM :: */
690 /* Corresponds to a custom encoding, as found in Type~1, CFF, and */
691 /* OpenType/CFF fonts. It is limited to 256 character codes. */
692 /* */
693 /* FT_ENCODING_APPLE_ROMAN :: */
694 /* Corresponds to the 8-bit Apple roman encoding. Many TrueType */
695 /* and OpenType fonts contain a charmap for this encoding, since */
696 /* older versions of Mac OS are able to use it. */
697 /* */
698 /* FT_ENCODING_OLD_LATIN_2 :: */
699 /* This value is deprecated and was never used nor reported by */
700 /* FreeType. Don't use or test for it. */
701 /* */
702 /* FT_ENCODING_MS_SJIS :: */
703 /* Same as FT_ENCODING_SJIS. Deprecated. */
704 /* */
705 /* FT_ENCODING_MS_GB2312 :: */
706 /* Same as FT_ENCODING_GB2312. Deprecated. */
707 /* */
708 /* FT_ENCODING_MS_BIG5 :: */
709 /* Same as FT_ENCODING_BIG5. Deprecated. */
710 /* */
711 /* FT_ENCODING_MS_WANSUNG :: */
712 /* Same as FT_ENCODING_WANSUNG. Deprecated. */
713 /* */
714 /* FT_ENCODING_MS_JOHAB :: */
715 /* Same as FT_ENCODING_JOHAB. Deprecated. */
716 /* */
717 /* <Note> */
718 /* By default, FreeType automatically synthesizes a Unicode charmap */
719 /* for PostScript fonts, using their glyph names dictionaries. */
720 /* However, it also reports the encodings defined explicitly in the */
721 /* font file, for the cases when they are needed, with the Adobe */
722 /* values as well. */
723 /* */
724 /* FT_ENCODING_NONE is set by the BDF and PCF drivers if the charmap */
725 /* is neither Unicode nor ISO-8859-1 (otherwise it is set to */
726 /* FT_ENCODING_UNICODE). Use @FT_Get_BDF_Charset_ID to find out */
727 /* which encoding is really present. If, for example, the */
728 /* `cs_registry' field is `KOI8' and the `cs_encoding' field is `R', */
729 /* the font is encoded in KOI8-R. */
730 /* */
731 /* FT_ENCODING_NONE is always set (with a single exception) by the */
732 /* winfonts driver. Use @FT_Get_WinFNT_Header and examine the */
733 /* `charset' field of the @FT_WinFNT_HeaderRec structure to find out */
734 /* which encoding is really present. For example, */
735 /* @FT_WinFNT_ID_CP1251 (204) means Windows code page 1251 (for */
736 /* Russian). */
737 /* */
738 /* FT_ENCODING_NONE is set if `platform_id' is @TT_PLATFORM_MACINTOSH */
739 /* and `encoding_id' is not @TT_MAC_ID_ROMAN (otherwise it is set to */
740 /* FT_ENCODING_APPLE_ROMAN). */
741 /* */
742 /* If `platform_id' is @TT_PLATFORM_MACINTOSH, use the function */
743 /* @FT_Get_CMap_Language_ID to query the Mac language ID that may */
744 /* be needed to be able to distinguish Apple encoding variants. See */
745 /* */
746 /* http://www.unicode.org/Public/MAPPINGS/VENDORS/APPLE/Readme.txt */
747 /* */
748 /* to get an idea how to do that. Basically, if the language ID */
749 /* is~0, don't use it, otherwise subtract 1 from the language ID. */
750 /* Then examine `encoding_id'. If, for example, `encoding_id' is */
751 /* @TT_MAC_ID_ROMAN and the language ID (minus~1) is */
752 /* `TT_MAC_LANGID_GREEK', it is the Greek encoding, not Roman. */
753 /* @TT_MAC_ID_ARABIC with `TT_MAC_LANGID_FARSI' means the Farsi */
754 /* variant the Arabic encoding. */
755 /* */
756 typedef enum FT_Encoding_
757 {
758 FT_ENC_TAG( FT_ENCODING_NONE, 0, 0, 0, 0 ),
759
760 FT_ENC_TAG( FT_ENCODING_MS_SYMBOL, 's', 'y', 'm', 'b' ),
761 FT_ENC_TAG( FT_ENCODING_UNICODE, 'u', 'n', 'i', 'c' ),
762
763 FT_ENC_TAG( FT_ENCODING_SJIS, 's', 'j', 'i', 's' ),
764 FT_ENC_TAG( FT_ENCODING_GB2312, 'g', 'b', ' ', ' ' ),
765 FT_ENC_TAG( FT_ENCODING_BIG5, 'b', 'i', 'g', '5' ),
766 FT_ENC_TAG( FT_ENCODING_WANSUNG, 'w', 'a', 'n', 's' ),
767 FT_ENC_TAG( FT_ENCODING_JOHAB, 'j', 'o', 'h', 'a' ),
768
769 /* for backwards compatibility */
770 FT_ENCODING_MS_SJIS = FT_ENCODING_SJIS,
771 FT_ENCODING_MS_GB2312 = FT_ENCODING_GB2312,
772 FT_ENCODING_MS_BIG5 = FT_ENCODING_BIG5,
773 FT_ENCODING_MS_WANSUNG = FT_ENCODING_WANSUNG,
774 FT_ENCODING_MS_JOHAB = FT_ENCODING_JOHAB,
775
776 FT_ENC_TAG( FT_ENCODING_ADOBE_STANDARD, 'A', 'D', 'O', 'B' ),
777 FT_ENC_TAG( FT_ENCODING_ADOBE_EXPERT, 'A', 'D', 'B', 'E' ),
778 FT_ENC_TAG( FT_ENCODING_ADOBE_CUSTOM, 'A', 'D', 'B', 'C' ),
779 FT_ENC_TAG( FT_ENCODING_ADOBE_LATIN_1, 'l', 'a', 't', '1' ),
780
781 FT_ENC_TAG( FT_ENCODING_OLD_LATIN_2, 'l', 'a', 't', '2' ),
782
783 FT_ENC_TAG( FT_ENCODING_APPLE_ROMAN, 'a', 'r', 'm', 'n' )
784
785 } FT_Encoding;
786
787
788 /* these constants are deprecated; use the corresponding `FT_Encoding' */
789 /* values instead */
790#define ft_encoding_none FT_ENCODING_NONE
791#define ft_encoding_unicode FT_ENCODING_UNICODE
792#define ft_encoding_symbol FT_ENCODING_MS_SYMBOL
793#define ft_encoding_latin_1 FT_ENCODING_ADOBE_LATIN_1
794#define ft_encoding_latin_2 FT_ENCODING_OLD_LATIN_2
795#define ft_encoding_sjis FT_ENCODING_SJIS
796#define ft_encoding_gb2312 FT_ENCODING_GB2312
797#define ft_encoding_big5 FT_ENCODING_BIG5
798#define ft_encoding_wansung FT_ENCODING_WANSUNG
799#define ft_encoding_johab FT_ENCODING_JOHAB
800
801#define ft_encoding_adobe_standard FT_ENCODING_ADOBE_STANDARD
802#define ft_encoding_adobe_expert FT_ENCODING_ADOBE_EXPERT
803#define ft_encoding_adobe_custom FT_ENCODING_ADOBE_CUSTOM
804#define ft_encoding_apple_roman FT_ENCODING_APPLE_ROMAN
805
806
807 /*************************************************************************/
808 /* */
809 /* <Struct> */
810 /* FT_CharMapRec */
811 /* */
812 /* <Description> */
813 /* The base charmap structure. */
814 /* */
815 /* <Fields> */
816 /* face :: A handle to the parent face object. */
817 /* */
818 /* encoding :: An @FT_Encoding tag identifying the charmap. Use */
819 /* this with @FT_Select_Charmap. */
820 /* */
821 /* platform_id :: An ID number describing the platform for the */
822 /* following encoding ID. This comes directly from */
823 /* the TrueType specification and should be emulated */
824 /* for other formats. */
825 /* */
826 /* encoding_id :: A platform specific encoding number. This also */
827 /* comes from the TrueType specification and should be */
828 /* emulated similarly. */
829 /* */
830 typedef struct FT_CharMapRec_
831 {
832 FT_Face face;
833 FT_Encoding encoding;
834 FT_UShort platform_id;
835 FT_UShort encoding_id;
836
837 } FT_CharMapRec;
838
839
840 /*************************************************************************/
841 /*************************************************************************/
842 /* */
843 /* B A S E O B J E C T C L A S S E S */
844 /* */
845 /*************************************************************************/
846 /*************************************************************************/
847
848
849 /*************************************************************************/
850 /* */
851 /* <Type> */
852 /* FT_Face_Internal */
853 /* */
854 /* <Description> */
855 /* An opaque handle to an `FT_Face_InternalRec' structure, used to */
856 /* model private data of a given @FT_Face object. */
857 /* */
858 /* This structure might change between releases of FreeType~2 and is */
859 /* not generally available to client applications. */
860 /* */
861 typedef struct FT_Face_InternalRec_* FT_Face_Internal;
862
863
864 /*************************************************************************/
865 /* */
866 /* <Struct> */
867 /* FT_FaceRec */
868 /* */
869 /* <Description> */
870 /* FreeType root face class structure. A face object models a */
871 /* typeface in a font file. */
872 /* */
873 /* <Fields> */
874 /* num_faces :: The number of faces in the font file. Some */
875 /* font formats can have multiple faces in */
876 /* a font file. */
877 /* */
878 /* face_index :: This field holds two different values. */
879 /* Bits 0-15 are the index of the face in the */
880 /* font file (starting with value~0). They */
881 /* are set to~0 if there is only one face in */
882 /* the font file. */
883 /* */
884 /* Bits 16-30 are relevant to GX variation */
885 /* fonts only, holding the named instance */
886 /* index for the current face index (starting */
887 /* with value~1; value~0 indicates font access */
888 /* without GX variation data). For non-GX */
889 /* fonts, bits 16-30 are ignored. If we have */
890 /* the third named instance of face~4, say, */
891 /* `face_index' is set to 0x00030004. */
892 /* */
893 /* Bit 31 is always zero (this is, */
894 /* `face_index' is always a positive value). */
895 /* */
896 /* face_flags :: A set of bit flags that give important */
897 /* information about the face; see */
898 /* @FT_FACE_FLAG_XXX for the details. */
899 /* */
900 /* style_flags :: The lower 16~bits contain a set of bit */
901 /* flags indicating the style of the face; see */
902 /* @FT_STYLE_FLAG_XXX for the details. Bits */
903 /* 16-30 hold the number of named instances */
904 /* available for the current face if we have a */
905 /* GX variation (sub)font. Bit 31 is always */
906 /* zero (this is, `style_flags' is always a */
907 /* positive value). */
908 /* */
909 /* num_glyphs :: The number of glyphs in the face. If the */
910 /* face is scalable and has sbits (see */
911 /* `num_fixed_sizes'), it is set to the number */
912 /* of outline glyphs. */
913 /* */
914 /* For CID-keyed fonts, this value gives the */
915 /* highest CID used in the font. */
916 /* */
917 /* family_name :: The face's family name. This is an ASCII */
918 /* string, usually in English, that describes */
919 /* the typeface's family (like `Times New */
920 /* Roman', `Bodoni', `Garamond', etc). This */
921 /* is a least common denominator used to list */
922 /* fonts. Some formats (TrueType & OpenType) */
923 /* provide localized and Unicode versions of */
924 /* this string. Applications should use the */
925 /* format specific interface to access them. */
926 /* Can be NULL (e.g., in fonts embedded in a */
927 /* PDF file). */
928 /* */
929 /* In case the font doesn't provide a specific */
930 /* family name entry, FreeType tries to */
931 /* synthesize one, deriving it from other name */
932 /* entries. */
933 /* */
934 /* style_name :: The face's style name. This is an ASCII */
935 /* string, usually in English, that describes */
936 /* the typeface's style (like `Italic', */
937 /* `Bold', `Condensed', etc). Not all font */
938 /* formats provide a style name, so this field */
939 /* is optional, and can be set to NULL. As */
940 /* for `family_name', some formats provide */
941 /* localized and Unicode versions of this */
942 /* string. Applications should use the format */
943 /* specific interface to access them. */
944 /* */
945 /* num_fixed_sizes :: The number of bitmap strikes in the face. */
946 /* Even if the face is scalable, there might */
947 /* still be bitmap strikes, which are called */
948 /* `sbits' in that case. */
949 /* */
950 /* available_sizes :: An array of @FT_Bitmap_Size for all bitmap */
951 /* strikes in the face. It is set to NULL if */
952 /* there is no bitmap strike. */
953 /* */
954 /* num_charmaps :: The number of charmaps in the face. */
955 /* */
956 /* charmaps :: An array of the charmaps of the face. */
957 /* */
958 /* generic :: A field reserved for client uses. See the */
959 /* @FT_Generic type description. */
960 /* */
961 /* bbox :: The font bounding box. Coordinates are */
962 /* expressed in font units (see */
963 /* `units_per_EM'). The box is large enough */
964 /* to contain any glyph from the font. Thus, */
965 /* `bbox.yMax' can be seen as the `maximum */
966 /* ascender', and `bbox.yMin' as the `minimum */
967 /* descender'. Only relevant for scalable */
968 /* formats. */
969 /* */
970 /* Note that the bounding box might be off by */
971 /* (at least) one pixel for hinted fonts. See */
972 /* @FT_Size_Metrics for further discussion. */
973 /* */
974 /* units_per_EM :: The number of font units per EM square for */
975 /* this face. This is typically 2048 for */
976 /* TrueType fonts, and 1000 for Type~1 fonts. */
977 /* Only relevant for scalable formats. */
978 /* */
979 /* ascender :: The typographic ascender of the face, */
980 /* expressed in font units. For font formats */
981 /* not having this information, it is set to */
982 /* `bbox.yMax'. Only relevant for scalable */
983 /* formats. */
984 /* */
985 /* descender :: The typographic descender of the face, */
986 /* expressed in font units. For font formats */
987 /* not having this information, it is set to */
988 /* `bbox.yMin'. Note that this field is */
989 /* usually negative. Only relevant for */
990 /* scalable formats. */
991 /* */
992 /* height :: This value is the vertical distance */
993 /* between two consecutive baselines, */
994 /* expressed in font units. It is always */
995 /* positive. Only relevant for scalable */
996 /* formats. */
997 /* */
998 /* If you want the global glyph height, use */
999 /* `ascender - descender'. */
1000 /* */
1001 /* max_advance_width :: The maximum advance width, in font units, */
1002 /* for all glyphs in this face. This can be */
1003 /* used to make word wrapping computations */
1004 /* faster. Only relevant for scalable */
1005 /* formats. */
1006 /* */
1007 /* max_advance_height :: The maximum advance height, in font units, */
1008 /* for all glyphs in this face. This is only */
1009 /* relevant for vertical layouts, and is set */
1010 /* to `height' for fonts that do not provide */
1011 /* vertical metrics. Only relevant for */
1012 /* scalable formats. */
1013 /* */
1014 /* underline_position :: The position, in font units, of the */
1015 /* underline line for this face. It is the */
1016 /* center of the underlining stem. Only */
1017 /* relevant for scalable formats. */
1018 /* */
1019 /* underline_thickness :: The thickness, in font units, of the */
1020 /* underline for this face. Only relevant for */
1021 /* scalable formats. */
1022 /* */
1023 /* glyph :: The face's associated glyph slot(s). */
1024 /* */
1025 /* size :: The current active size for this face. */
1026 /* */
1027 /* charmap :: The current active charmap for this face. */
1028 /* */
1029 /* <Note> */
1030 /* Fields may be changed after a call to @FT_Attach_File or */
1031 /* @FT_Attach_Stream. */
1032 /* */
1033 typedef struct FT_FaceRec_
1034 {
1035 FT_Long num_faces;
1036 FT_Long face_index;
1037
1038 FT_Long face_flags;
1039 FT_Long style_flags;
1040
1041 FT_Long num_glyphs;
1042
1043 FT_String* family_name;
1044 FT_String* style_name;
1045
1046 FT_Int num_fixed_sizes;
1047 FT_Bitmap_Size* available_sizes;
1048
1049 FT_Int num_charmaps;
1050 FT_CharMap* charmaps;
1051
1052 FT_Generic generic;
1053
1054 /*# The following member variables (down to `underline_thickness') */
1055 /*# are only relevant to scalable outlines; cf. @FT_Bitmap_Size */
1056 /*# for bitmap fonts. */
1057 FT_BBox bbox;
1058
1059 FT_UShort units_per_EM;
1060 FT_Short ascender;
1061 FT_Short descender;
1062 FT_Short height;
1063
1064 FT_Short max_advance_width;
1065 FT_Short max_advance_height;
1066
1067 FT_Short underline_position;
1068 FT_Short underline_thickness;
1069
1070 FT_GlyphSlot glyph;
1071 FT_Size size;
1072 FT_CharMap charmap;
1073
1074 /*@private begin */
1075
1076 FT_Driver driver;
1077 FT_Memory memory;
1078 FT_Stream stream;
1079
1080 FT_ListRec sizes_list;
1081
1082 FT_Generic autohint; /* face-specific auto-hinter data */
1083 void* extensions; /* unused */
1084
1085 FT_Face_Internal internal;
1086
1087 /*@private end */
1088
1089 } FT_FaceRec;
1090
1091
1092 /*************************************************************************/
1093 /* */
1094 /* <Enum> */
1095 /* FT_FACE_FLAG_XXX */
1096 /* */
1097 /* <Description> */
1098 /* A list of bit flags used in the `face_flags' field of the */
1099 /* @FT_FaceRec structure. They inform client applications of */
1100 /* properties of the corresponding face. */
1101 /* */
1102 /* <Values> */
1103 /* FT_FACE_FLAG_SCALABLE :: */
1104 /* Indicates that the face contains outline glyphs. This doesn't */
1105 /* prevent bitmap strikes, i.e., a face can have both this and */
1106 /* and @FT_FACE_FLAG_FIXED_SIZES set. */
1107 /* */
1108 /* FT_FACE_FLAG_FIXED_SIZES :: */
1109 /* Indicates that the face contains bitmap strikes. See also the */
1110 /* `num_fixed_sizes' and `available_sizes' fields of @FT_FaceRec. */
1111 /* */
1112 /* FT_FACE_FLAG_FIXED_WIDTH :: */
1113 /* Indicates that the face contains fixed-width characters (like */
1114 /* Courier, Lucido, MonoType, etc.). */
1115 /* */
1116 /* FT_FACE_FLAG_SFNT :: */
1117 /* Indicates that the face uses the `sfnt' storage scheme. For */
1118 /* now, this means TrueType and OpenType. */
1119 /* */
1120 /* FT_FACE_FLAG_HORIZONTAL :: */
1121 /* Indicates that the face contains horizontal glyph metrics. This */
1122 /* should be set for all common formats. */
1123 /* */
1124 /* FT_FACE_FLAG_VERTICAL :: */
1125 /* Indicates that the face contains vertical glyph metrics. This */
1126 /* is only available in some formats, not all of them. */
1127 /* */
1128 /* FT_FACE_FLAG_KERNING :: */
1129 /* Indicates that the face contains kerning information. If set, */
1130 /* the kerning distance can be retrieved through the function */
1131 /* @FT_Get_Kerning. Otherwise the function always return the */
1132 /* vector (0,0). Note that FreeType doesn't handle kerning data */
1133 /* from the `GPOS' table (as present in some OpenType fonts). */
1134 /* */
1135 /* FT_FACE_FLAG_FAST_GLYPHS :: */
1136 /* THIS FLAG IS DEPRECATED. DO NOT USE OR TEST IT. */
1137 /* */
1138 /* FT_FACE_FLAG_MULTIPLE_MASTERS :: */
1139 /* Indicates that the font contains multiple masters and is capable */
1140 /* of interpolating between them. See the multiple-masters */
1141 /* specific API for details. */
1142 /* */
1143 /* FT_FACE_FLAG_GLYPH_NAMES :: */
1144 /* Indicates that the font contains glyph names that can be */
1145 /* retrieved through @FT_Get_Glyph_Name. Note that some TrueType */
1146 /* fonts contain broken glyph name tables. Use the function */
1147 /* @FT_Has_PS_Glyph_Names when needed. */
1148 /* */
1149 /* FT_FACE_FLAG_EXTERNAL_STREAM :: */
1150 /* Used internally by FreeType to indicate that a face's stream was */
1151 /* provided by the client application and should not be destroyed */
1152 /* when @FT_Done_Face is called. Don't read or test this flag. */
1153 /* */
1154 /* FT_FACE_FLAG_HINTER :: */
1155 /* Set if the font driver has a hinting machine of its own. For */
1156 /* example, with TrueType fonts, it makes sense to use data from */
1157 /* the SFNT `gasp' table only if the native TrueType hinting engine */
1158 /* (with the bytecode interpreter) is available and active. */
1159 /* */
1160 /* FT_FACE_FLAG_CID_KEYED :: */
1161 /* Set if the font is CID-keyed. In that case, the font is not */
1162 /* accessed by glyph indices but by CID values. For subsetted */
1163 /* CID-keyed fonts this has the consequence that not all index */
1164 /* values are a valid argument to FT_Load_Glyph. Only the CID */
1165 /* values for which corresponding glyphs in the subsetted font */
1166 /* exist make FT_Load_Glyph return successfully; in all other cases */
1167 /* you get an `FT_Err_Invalid_Argument' error. */
1168 /* */
1169 /* Note that CID-keyed fonts that are in an SFNT wrapper don't */
1170 /* have this flag set since the glyphs are accessed in the normal */
1171 /* way (using contiguous indices); the `CID-ness' isn't visible to */
1172 /* the application. */
1173 /* */
1174 /* FT_FACE_FLAG_TRICKY :: */
1175 /* Set if the font is `tricky', this is, it always needs the */
1176 /* font format's native hinting engine to get a reasonable result. */
1177 /* A typical example is the Chinese font `mingli.ttf' that uses */
1178 /* TrueType bytecode instructions to move and scale all of its */
1179 /* subglyphs. */
1180 /* */
1181 /* It is not possible to auto-hint such fonts using */
1182 /* @FT_LOAD_FORCE_AUTOHINT; it will also ignore */
1183 /* @FT_LOAD_NO_HINTING. You have to set both @FT_LOAD_NO_HINTING */
1184 /* and @FT_LOAD_NO_AUTOHINT to really disable hinting; however, you */
1185 /* probably never want this except for demonstration purposes. */
1186 /* */
1187 /* Currently, there are about a dozen TrueType fonts in the list of */
1188 /* tricky fonts; they are hard-coded in file `ttobjs.c'. */
1189 /* */
1190 /* FT_FACE_FLAG_COLOR :: */
1191 /* Set if the font has color glyph tables. To access color glyphs */
1192 /* use @FT_LOAD_COLOR. */
1193 /* */
1194#define FT_FACE_FLAG_SCALABLE ( 1L << 0 )
1195#define FT_FACE_FLAG_FIXED_SIZES ( 1L << 1 )
1196#define FT_FACE_FLAG_FIXED_WIDTH ( 1L << 2 )
1197#define FT_FACE_FLAG_SFNT ( 1L << 3 )
1198#define FT_FACE_FLAG_HORIZONTAL ( 1L << 4 )
1199#define FT_FACE_FLAG_VERTICAL ( 1L << 5 )
1200#define FT_FACE_FLAG_KERNING ( 1L << 6 )
1201#define FT_FACE_FLAG_FAST_GLYPHS ( 1L << 7 )
1202#define FT_FACE_FLAG_MULTIPLE_MASTERS ( 1L << 8 )
1203#define FT_FACE_FLAG_GLYPH_NAMES ( 1L << 9 )
1204#define FT_FACE_FLAG_EXTERNAL_STREAM ( 1L << 10 )
1205#define FT_FACE_FLAG_HINTER ( 1L << 11 )
1206#define FT_FACE_FLAG_CID_KEYED ( 1L << 12 )
1207#define FT_FACE_FLAG_TRICKY ( 1L << 13 )
1208#define FT_FACE_FLAG_COLOR ( 1L << 14 )
1209
1210
1211 /*************************************************************************
1212 *
1213 * @macro:
1214 * FT_HAS_HORIZONTAL( face )
1215 *
1216 * @description:
1217 * A macro that returns true whenever a face object contains
1218 * horizontal metrics (this is true for all font formats though).
1219 *
1220 * @also:
1221 * @FT_HAS_VERTICAL can be used to check for vertical metrics.
1222 *
1223 */
1224#define FT_HAS_HORIZONTAL( face ) \
1225 ( face->face_flags & FT_FACE_FLAG_HORIZONTAL )
1226
1227
1228 /*************************************************************************
1229 *
1230 * @macro:
1231 * FT_HAS_VERTICAL( face )
1232 *
1233 * @description:
1234 * A macro that returns true whenever a face object contains real
1235 * vertical metrics (and not only synthesized ones).
1236 *
1237 */
1238#define FT_HAS_VERTICAL( face ) \
1239 ( face->face_flags & FT_FACE_FLAG_VERTICAL )
1240
1241
1242 /*************************************************************************
1243 *
1244 * @macro:
1245 * FT_HAS_KERNING( face )
1246 *
1247 * @description:
1248 * A macro that returns true whenever a face object contains kerning
1249 * data that can be accessed with @FT_Get_Kerning.
1250 *
1251 */
1252#define FT_HAS_KERNING( face ) \
1253 ( face->face_flags & FT_FACE_FLAG_KERNING )
1254
1255
1256 /*************************************************************************
1257 *
1258 * @macro:
1259 * FT_IS_SCALABLE( face )
1260 *
1261 * @description:
1262 * A macro that returns true whenever a face object contains a scalable
1263 * font face (true for TrueType, Type~1, Type~42, CID, OpenType/CFF,
1264 * and PFR font formats.
1265 *
1266 */
1267#define FT_IS_SCALABLE( face ) \
1268 ( face->face_flags & FT_FACE_FLAG_SCALABLE )
1269
1270
1271 /*************************************************************************
1272 *
1273 * @macro:
1274 * FT_IS_SFNT( face )
1275 *
1276 * @description:
1277 * A macro that returns true whenever a face object contains a font
1278 * whose format is based on the SFNT storage scheme. This usually
1279 * means: TrueType fonts, OpenType fonts, as well as SFNT-based embedded
1280 * bitmap fonts.
1281 *
1282 * If this macro is true, all functions defined in @FT_SFNT_NAMES_H and
1283 * @FT_TRUETYPE_TABLES_H are available.
1284 *
1285 */
1286#define FT_IS_SFNT( face ) \
1287 ( face->face_flags & FT_FACE_FLAG_SFNT )
1288
1289
1290 /*************************************************************************
1291 *
1292 * @macro:
1293 * FT_IS_FIXED_WIDTH( face )
1294 *
1295 * @description:
1296 * A macro that returns true whenever a face object contains a font face
1297 * that contains fixed-width (or `monospace', `fixed-pitch', etc.)
1298 * glyphs.
1299 *
1300 */
1301#define FT_IS_FIXED_WIDTH( face ) \
1302 ( face->face_flags & FT_FACE_FLAG_FIXED_WIDTH )
1303
1304
1305 /*************************************************************************
1306 *
1307 * @macro:
1308 * FT_HAS_FIXED_SIZES( face )
1309 *
1310 * @description:
1311 * A macro that returns true whenever a face object contains some
1312 * embedded bitmaps. See the `available_sizes' field of the
1313 * @FT_FaceRec structure.
1314 *
1315 */
1316#define FT_HAS_FIXED_SIZES( face ) \
1317 ( face->face_flags & FT_FACE_FLAG_FIXED_SIZES )
1318
1319
1320 /*************************************************************************
1321 *
1322 * @macro:
1323 * FT_HAS_FAST_GLYPHS( face )
1324 *
1325 * @description:
1326 * Deprecated.
1327 *
1328 */
1329#define FT_HAS_FAST_GLYPHS( face ) 0
1330
1331
1332 /*************************************************************************
1333 *
1334 * @macro:
1335 * FT_HAS_GLYPH_NAMES( face )
1336 *
1337 * @description:
1338 * A macro that returns true whenever a face object contains some glyph
1339 * names that can be accessed through @FT_Get_Glyph_Name.
1340 *
1341 */
1342#define FT_HAS_GLYPH_NAMES( face ) \
1343 ( face->face_flags & FT_FACE_FLAG_GLYPH_NAMES )
1344
1345
1346 /*************************************************************************
1347 *
1348 * @macro:
1349 * FT_HAS_MULTIPLE_MASTERS( face )
1350 *
1351 * @description:
1352 * A macro that returns true whenever a face object contains some
1353 * multiple masters. The functions provided by @FT_MULTIPLE_MASTERS_H
1354 * are then available to choose the exact design you want.
1355 *
1356 */
1357#define FT_HAS_MULTIPLE_MASTERS( face ) \
1358 ( face->face_flags & FT_FACE_FLAG_MULTIPLE_MASTERS )
1359
1360
1361 /*************************************************************************
1362 *
1363 * @macro:
1364 * FT_IS_CID_KEYED( face )
1365 *
1366 * @description:
1367 * A macro that returns true whenever a face object contains a CID-keyed
1368 * font. See the discussion of @FT_FACE_FLAG_CID_KEYED for more
1369 * details.
1370 *
1371 * If this macro is true, all functions defined in @FT_CID_H are
1372 * available.
1373 *
1374 */
1375#define FT_IS_CID_KEYED( face ) \
1376 ( face->face_flags & FT_FACE_FLAG_CID_KEYED )
1377
1378
1379 /*************************************************************************
1380 *
1381 * @macro:
1382 * FT_IS_TRICKY( face )
1383 *
1384 * @description:
1385 * A macro that returns true whenever a face represents a `tricky' font.
1386 * See the discussion of @FT_FACE_FLAG_TRICKY for more details.
1387 *
1388 */
1389#define FT_IS_TRICKY( face ) \
1390 ( face->face_flags & FT_FACE_FLAG_TRICKY )
1391
1392
1393 /*************************************************************************
1394 *
1395 * @macro:
1396 * FT_HAS_COLOR( face )
1397 *
1398 * @description:
1399 * A macro that returns true whenever a face object contains
1400 * tables for color glyphs.
1401 *
1402 */
1403#define FT_HAS_COLOR( face ) \
1404 ( face->face_flags & FT_FACE_FLAG_COLOR )
1405
1406
1407 /*************************************************************************/
1408 /* */
1409 /* <Const> */
1410 /* FT_STYLE_FLAG_XXX */
1411 /* */
1412 /* <Description> */
1413 /* A list of bit flags used to indicate the style of a given face. */
1414 /* These are used in the `style_flags' field of @FT_FaceRec. */
1415 /* */
1416 /* <Values> */
1417 /* FT_STYLE_FLAG_ITALIC :: */
1418 /* Indicates that a given face style is italic or oblique. */
1419 /* */
1420 /* FT_STYLE_FLAG_BOLD :: */
1421 /* Indicates that a given face is bold. */
1422 /* */
1423 /* <Note> */
1424 /* The style information as provided by FreeType is very basic. More */
1425 /* details are beyond the scope and should be done on a higher level */
1426 /* (for example, by analyzing various fields of the `OS/2' table in */
1427 /* SFNT based fonts). */
1428 /* */
1429#define FT_STYLE_FLAG_ITALIC ( 1 << 0 )
1430#define FT_STYLE_FLAG_BOLD ( 1 << 1 )
1431
1432
1433 /*************************************************************************/
1434 /* */
1435 /* <Type> */
1436 /* FT_Size_Internal */
1437 /* */
1438 /* <Description> */
1439 /* An opaque handle to an `FT_Size_InternalRec' structure, used to */
1440 /* model private data of a given @FT_Size object. */
1441 /* */
1442 typedef struct FT_Size_InternalRec_* FT_Size_Internal;
1443
1444
1445 /*************************************************************************/
1446 /* */
1447 /* <Struct> */
1448 /* FT_Size_Metrics */
1449 /* */
1450 /* <Description> */
1451 /* The size metrics structure gives the metrics of a size object. */
1452 /* */
1453 /* <Fields> */
1454 /* x_ppem :: The width of the scaled EM square in pixels, hence */
1455 /* the term `ppem' (pixels per EM). It is also */
1456 /* referred to as `nominal width'. */
1457 /* */
1458 /* y_ppem :: The height of the scaled EM square in pixels, */
1459 /* hence the term `ppem' (pixels per EM). It is also */
1460 /* referred to as `nominal height'. */
1461 /* */
1462 /* x_scale :: A 16.16 fractional scaling value used to convert */
1463 /* horizontal metrics from font units to 26.6 */
1464 /* fractional pixels. Only relevant for scalable */
1465 /* font formats. */
1466 /* */
1467 /* y_scale :: A 16.16 fractional scaling value used to convert */
1468 /* vertical metrics from font units to 26.6 */
1469 /* fractional pixels. Only relevant for scalable */
1470 /* font formats. */
1471 /* */
1472 /* ascender :: The ascender in 26.6 fractional pixels. See */
1473 /* @FT_FaceRec for the details. */
1474 /* */
1475 /* descender :: The descender in 26.6 fractional pixels. See */
1476 /* @FT_FaceRec for the details. */
1477 /* */
1478 /* height :: The height in 26.6 fractional pixels. See */
1479 /* @FT_FaceRec for the details. */
1480 /* */
1481 /* max_advance :: The maximum advance width in 26.6 fractional */
1482 /* pixels. See @FT_FaceRec for the details. */
1483 /* */
1484 /* <Note> */
1485 /* The scaling values, if relevant, are determined first during a */
1486 /* size changing operation. The remaining fields are then set by the */
1487 /* driver. For scalable formats, they are usually set to scaled */
1488 /* values of the corresponding fields in @FT_FaceRec. */
1489 /* */
1490 /* Note that due to glyph hinting, these values might not be exact */
1491 /* for certain fonts. Thus they must be treated as unreliable */
1492 /* with an error margin of at least one pixel! */
1493 /* */
1494 /* Indeed, the only way to get the exact metrics is to render _all_ */
1495 /* glyphs. As this would be a definite performance hit, it is up to */
1496 /* client applications to perform such computations. */
1497 /* */
1498 /* The FT_Size_Metrics structure is valid for bitmap fonts also. */
1499 /* */
1500 typedef struct FT_Size_Metrics_
1501 {
1502 FT_UShort x_ppem; /* horizontal pixels per EM */
1503 FT_UShort y_ppem; /* vertical pixels per EM */
1504
1505 FT_Fixed x_scale; /* scaling values used to convert font */
1506 FT_Fixed y_scale; /* units to 26.6 fractional pixels */
1507
1508 FT_Pos ascender; /* ascender in 26.6 frac. pixels */
1509 FT_Pos descender; /* descender in 26.6 frac. pixels */
1510 FT_Pos height; /* text height in 26.6 frac. pixels */
1511 FT_Pos max_advance; /* max horizontal advance, in 26.6 pixels */
1512
1513 } FT_Size_Metrics;
1514
1515
1516 /*************************************************************************/
1517 /* */
1518 /* <Struct> */
1519 /* FT_SizeRec */
1520 /* */
1521 /* <Description> */
1522 /* FreeType root size class structure. A size object models a face */
1523 /* object at a given size. */
1524 /* */
1525 /* <Fields> */
1526 /* face :: Handle to the parent face object. */
1527 /* */
1528 /* generic :: A typeless pointer, unused by the FreeType library or */
1529 /* any of its drivers. It can be used by client */
1530 /* applications to link their own data to each size */
1531 /* object. */
1532 /* */
1533 /* metrics :: Metrics for this size object. This field is read-only. */
1534 /* */
1535 typedef struct FT_SizeRec_
1536 {
1537 FT_Face face; /* parent face object */
1538 FT_Generic generic; /* generic pointer for client uses */
1539 FT_Size_Metrics metrics; /* size metrics */
1540 FT_Size_Internal internal;
1541
1542 } FT_SizeRec;
1543
1544
1545 /*************************************************************************/
1546 /* */
1547 /* <Struct> */
1548 /* FT_SubGlyph */
1549 /* */
1550 /* <Description> */
1551 /* The subglyph structure is an internal object used to describe */
1552 /* subglyphs (for example, in the case of composites). */
1553 /* */
1554 /* <Note> */
1555 /* The subglyph implementation is not part of the high-level API, */
1556 /* hence the forward structure declaration. */
1557 /* */
1558 /* You can however retrieve subglyph information with */
1559 /* @FT_Get_SubGlyph_Info. */
1560 /* */
1561 typedef struct FT_SubGlyphRec_* FT_SubGlyph;
1562
1563
1564 /*************************************************************************/
1565 /* */
1566 /* <Type> */
1567 /* FT_Slot_Internal */
1568 /* */
1569 /* <Description> */
1570 /* An opaque handle to an `FT_Slot_InternalRec' structure, used to */
1571 /* model private data of a given @FT_GlyphSlot object. */
1572 /* */
1573 typedef struct FT_Slot_InternalRec_* FT_Slot_Internal;
1574
1575
1576 /*************************************************************************/
1577 /* */
1578 /* <Struct> */
1579 /* FT_GlyphSlotRec */
1580 /* */
1581 /* <Description> */
1582 /* FreeType root glyph slot class structure. A glyph slot is a */
1583 /* container where individual glyphs can be loaded, be they in */
1584 /* outline or bitmap format. */
1585 /* */
1586 /* <Fields> */
1587 /* library :: A handle to the FreeType library instance */
1588 /* this slot belongs to. */
1589 /* */
1590 /* face :: A handle to the parent face object. */
1591 /* */
1592 /* next :: In some cases (like some font tools), several */
1593 /* glyph slots per face object can be a good */
1594 /* thing. As this is rare, the glyph slots are */
1595 /* listed through a direct, single-linked list */
1596 /* using its `next' field. */
1597 /* */
1598 /* generic :: A typeless pointer unused by the FreeType */
1599 /* library or any of its drivers. It can be */
1600 /* used by client applications to link their own */
1601 /* data to each glyph slot object. */
1602 /* */
1603 /* metrics :: The metrics of the last loaded glyph in the */
1604 /* slot. The returned values depend on the last */
1605 /* load flags (see the @FT_Load_Glyph API */
1606 /* function) and can be expressed either in 26.6 */
1607 /* fractional pixels or font units. */
1608 /* */
1609 /* Note that even when the glyph image is */
1610 /* transformed, the metrics are not. */
1611 /* */
1612 /* linearHoriAdvance :: The advance width of the unhinted glyph. */
1613 /* Its value is expressed in 16.16 fractional */
1614 /* pixels, unless @FT_LOAD_LINEAR_DESIGN is set */
1615 /* when loading the glyph. This field can be */
1616 /* important to perform correct WYSIWYG layout. */
1617 /* Only relevant for outline glyphs. */
1618 /* */
1619 /* linearVertAdvance :: The advance height of the unhinted glyph. */
1620 /* Its value is expressed in 16.16 fractional */
1621 /* pixels, unless @FT_LOAD_LINEAR_DESIGN is set */
1622 /* when loading the glyph. This field can be */
1623 /* important to perform correct WYSIWYG layout. */
1624 /* Only relevant for outline glyphs. */
1625 /* */
1626 /* advance :: This shorthand is, depending on */
1627 /* @FT_LOAD_IGNORE_TRANSFORM, the transformed */
1628 /* (hinted) advance width for the glyph, in 26.6 */
1629 /* fractional pixel format. As specified with */
1630 /* @FT_LOAD_VERTICAL_LAYOUT, it uses either the */
1631 /* `horiAdvance' or the `vertAdvance' value of */
1632 /* `metrics' field. */
1633 /* */
1634 /* format :: This field indicates the format of the image */
1635 /* contained in the glyph slot. Typically */
1636 /* @FT_GLYPH_FORMAT_BITMAP, */
1637 /* @FT_GLYPH_FORMAT_OUTLINE, or */
1638 /* @FT_GLYPH_FORMAT_COMPOSITE, but others are */
1639 /* possible. */
1640 /* */
1641 /* bitmap :: This field is used as a bitmap descriptor */
1642 /* when the slot format is */
1643 /* @FT_GLYPH_FORMAT_BITMAP. Note that the */
1644 /* address and content of the bitmap buffer can */
1645 /* change between calls of @FT_Load_Glyph and a */
1646 /* few other functions. */
1647 /* */
1648 /* bitmap_left :: The bitmap's left bearing expressed in */
1649 /* integer pixels. Only valid if the format is */
1650 /* @FT_GLYPH_FORMAT_BITMAP, this is, if the */
1651 /* glyph slot contains a bitmap. */
1652 /* */
1653 /* bitmap_top :: The bitmap's top bearing expressed in integer */
1654 /* pixels. Remember that this is the distance */
1655 /* from the baseline to the top-most glyph */
1656 /* scanline, upwards y~coordinates being */
1657 /* *positive*. */
1658 /* */
1659 /* outline :: The outline descriptor for the current glyph */
1660 /* image if its format is */
1661 /* @FT_GLYPH_FORMAT_OUTLINE. Once a glyph is */
1662 /* loaded, `outline' can be transformed, */
1663 /* distorted, embolded, etc. However, it must */
1664 /* not be freed. */
1665 /* */
1666 /* num_subglyphs :: The number of subglyphs in a composite glyph. */
1667 /* This field is only valid for the composite */
1668 /* glyph format that should normally only be */
1669 /* loaded with the @FT_LOAD_NO_RECURSE flag. */
1670 /* */
1671 /* subglyphs :: An array of subglyph descriptors for */
1672 /* composite glyphs. There are `num_subglyphs' */
1673 /* elements in there. Currently internal to */
1674 /* FreeType. */
1675 /* */
1676 /* control_data :: Certain font drivers can also return the */
1677 /* control data for a given glyph image (e.g. */
1678 /* TrueType bytecode, Type~1 charstrings, etc.). */
1679 /* This field is a pointer to such data. */
1680 /* */
1681 /* control_len :: This is the length in bytes of the control */
1682 /* data. */
1683 /* */
1684 /* other :: Really wicked formats can use this pointer to */
1685 /* present their own glyph image to client */
1686 /* applications. Note that the application */
1687 /* needs to know about the image format. */
1688 /* */
1689 /* lsb_delta :: The difference between hinted and unhinted */
1690 /* left side bearing while auto-hinting is */
1691 /* active. Zero otherwise. */
1692 /* */
1693 /* rsb_delta :: The difference between hinted and unhinted */
1694 /* right side bearing while auto-hinting is */
1695 /* active. Zero otherwise. */
1696 /* */
1697 /* <Note> */
1698 /* If @FT_Load_Glyph is called with default flags (see */
1699 /* @FT_LOAD_DEFAULT) the glyph image is loaded in the glyph slot in */
1700 /* its native format (e.g., an outline glyph for TrueType and Type~1 */
1701 /* formats). */
1702 /* */
1703 /* This image can later be converted into a bitmap by calling */
1704 /* @FT_Render_Glyph. This function finds the current renderer for */
1705 /* the native image's format, then invokes it. */
1706 /* */
1707 /* The renderer is in charge of transforming the native image through */
1708 /* the slot's face transformation fields, then converting it into a */
1709 /* bitmap that is returned in `slot->bitmap'. */
1710 /* */
1711 /* Note that `slot->bitmap_left' and `slot->bitmap_top' are also used */
1712 /* to specify the position of the bitmap relative to the current pen */
1713 /* position (e.g., coordinates (0,0) on the baseline). Of course, */
1714 /* `slot->format' is also changed to @FT_GLYPH_FORMAT_BITMAP. */
1715 /* */
1716 /* <Note> */
1717 /* Here is a small pseudo code fragment that shows how to use */
1718 /* `lsb_delta' and `rsb_delta': */
1719 /* */
1720 /* { */
1721 /* FT_Pos origin_x = 0; */
1722 /* FT_Pos prev_rsb_delta = 0; */
1723 /* */
1724 /* */
1725 /* for all glyphs do */
1726 /* <compute kern between current and previous glyph and add it to */
1727 /* `origin_x'> */
1728 /* */
1729 /* <load glyph with `FT_Load_Glyph'> */
1730 /* */
1731 /* if ( prev_rsb_delta - face->glyph->lsb_delta >= 32 ) */
1732 /* origin_x -= 64; */
1733 /* else if ( prev_rsb_delta - face->glyph->lsb_delta < -32 ) */
1734 /* origin_x += 64; */
1735 /* */
1736 /* prev_rsb_delta = face->glyph->rsb_delta; */
1737 /* */
1738 /* <save glyph image, or render glyph, or ...> */
1739 /* */
1740 /* origin_x += face->glyph->advance.x; */
1741 /* endfor */
1742 /* } */
1743 /* */
1744 typedef struct FT_GlyphSlotRec_
1745 {
1746 FT_Library library;
1747 FT_Face face;
1748 FT_GlyphSlot next;
1749 FT_UInt reserved; /* retained for binary compatibility */
1750 FT_Generic generic;
1751
1752 FT_Glyph_Metrics metrics;
1753 FT_Fixed linearHoriAdvance;
1754 FT_Fixed linearVertAdvance;
1755 FT_Vector advance;
1756
1757 FT_Glyph_Format format;
1758
1759 FT_Bitmap bitmap;
1760 FT_Int bitmap_left;
1761 FT_Int bitmap_top;
1762
1763 FT_Outline outline;
1764
1765 FT_UInt num_subglyphs;
1766 FT_SubGlyph subglyphs;
1767
1768 void* control_data;
1769 long control_len;
1770
1771 FT_Pos lsb_delta;
1772 FT_Pos rsb_delta;
1773
1774 void* other;
1775
1776 FT_Slot_Internal internal;
1777
1778 } FT_GlyphSlotRec;
1779
1780
1781 /*************************************************************************/
1782 /*************************************************************************/
1783 /* */
1784 /* F U N C T I O N S */
1785 /* */
1786 /*************************************************************************/
1787 /*************************************************************************/
1788
1789
1790 /*************************************************************************/
1791 /* */
1792 /* <Function> */
1793 /* FT_Init_FreeType */
1794 /* */
1795 /* <Description> */
1796 /* Initialize a new FreeType library object. The set of modules */
1797 /* that are registered by this function is determined at build time. */
1798 /* */
1799 /* <Output> */
1800 /* alibrary :: A handle to a new library object. */
1801 /* */
1802 /* <Return> */
1803 /* FreeType error code. 0~means success. */
1804 /* */
1805 /* <Note> */
1806 /* In case you want to provide your own memory allocating routines, */
1807 /* use @FT_New_Library instead, followed by a call to */
1808 /* @FT_Add_Default_Modules (or a series of calls to @FT_Add_Module). */
1809 /* */
1810 /* See the documentation of @FT_Library and @FT_Face for */
1811 /* multi-threading issues. */
1812 /* */
1813 /* If you need reference-counting (cf. @FT_Reference_Library), use */
1814 /* @FT_New_Library and @FT_Done_Library. */
1815 /* */
1816 FT_EXPORT( FT_Error )
1817 FT_Init_FreeType( FT_Library *alibrary );
1818
1819
1820 /*************************************************************************/
1821 /* */
1822 /* <Function> */
1823 /* FT_Done_FreeType */
1824 /* */
1825 /* <Description> */
1826 /* Destroy a given FreeType library object and all of its children, */
1827 /* including resources, drivers, faces, sizes, etc. */
1828 /* */
1829 /* <Input> */
1830 /* library :: A handle to the target library object. */
1831 /* */
1832 /* <Return> */
1833 /* FreeType error code. 0~means success. */
1834 /* */
1835 FT_EXPORT( FT_Error )
1836 FT_Done_FreeType( FT_Library library );
1837
1838
1839 /*************************************************************************/
1840 /* */
1841 /* <Enum> */
1842 /* FT_OPEN_XXX */
1843 /* */
1844 /* <Description> */
1845 /* A list of bit field constants used within the `flags' field of the */
1846 /* @FT_Open_Args structure. */
1847 /* */
1848 /* <Values> */
1849 /* FT_OPEN_MEMORY :: This is a memory-based stream. */
1850 /* */
1851 /* FT_OPEN_STREAM :: Copy the stream from the `stream' field. */
1852 /* */
1853 /* FT_OPEN_PATHNAME :: Create a new input stream from a C~path */
1854 /* name. */
1855 /* */
1856 /* FT_OPEN_DRIVER :: Use the `driver' field. */
1857 /* */
1858 /* FT_OPEN_PARAMS :: Use the `num_params' and `params' fields. */
1859 /* */
1860 /* <Note> */
1861 /* The `FT_OPEN_MEMORY', `FT_OPEN_STREAM', and `FT_OPEN_PATHNAME' */
1862 /* flags are mutually exclusive. */
1863 /* */
1864#define FT_OPEN_MEMORY 0x1
1865#define FT_OPEN_STREAM 0x2
1866#define FT_OPEN_PATHNAME 0x4
1867#define FT_OPEN_DRIVER 0x8
1868#define FT_OPEN_PARAMS 0x10
1869
1870
1871 /* these constants are deprecated; use the corresponding `FT_OPEN_XXX' */
1872 /* values instead */
1873#define ft_open_memory FT_OPEN_MEMORY
1874#define ft_open_stream FT_OPEN_STREAM
1875#define ft_open_pathname FT_OPEN_PATHNAME
1876#define ft_open_driver FT_OPEN_DRIVER
1877#define ft_open_params FT_OPEN_PARAMS
1878
1879
1880 /*************************************************************************/
1881 /* */
1882 /* <Struct> */
1883 /* FT_Parameter */
1884 /* */
1885 /* <Description> */
1886 /* A simple structure used to pass more or less generic parameters to */
1887 /* @FT_Open_Face. */
1888 /* */
1889 /* <Fields> */
1890 /* tag :: A four-byte identification tag. */
1891 /* */
1892 /* data :: A pointer to the parameter data. */
1893 /* */
1894 /* <Note> */
1895 /* The ID and function of parameters are driver-specific. See the */
1896 /* various FT_PARAM_TAG_XXX flags for more information. */
1897 /* */
1898 typedef struct FT_Parameter_
1899 {
1900 FT_ULong tag;
1901 FT_Pointer data;
1902
1903 } FT_Parameter;
1904
1905
1906 /*************************************************************************/
1907 /* */
1908 /* <Struct> */
1909 /* FT_Open_Args */
1910 /* */
1911 /* <Description> */
1912 /* A structure used to indicate how to open a new font file or */
1913 /* stream. A pointer to such a structure can be used as a parameter */
1914 /* for the functions @FT_Open_Face and @FT_Attach_Stream. */
1915 /* */
1916 /* <Fields> */
1917 /* flags :: A set of bit flags indicating how to use the */
1918 /* structure. */
1919 /* */
1920 /* memory_base :: The first byte of the file in memory. */
1921 /* */
1922 /* memory_size :: The size in bytes of the file in memory. */
1923 /* */
1924 /* pathname :: A pointer to an 8-bit file pathname. */
1925 /* */
1926 /* stream :: A handle to a source stream object. */
1927 /* */
1928 /* driver :: This field is exclusively used by @FT_Open_Face; */
1929 /* it simply specifies the font driver to use to open */
1930 /* the face. If set to~0, FreeType tries to load the */
1931 /* face with each one of the drivers in its list. */
1932 /* */
1933 /* num_params :: The number of extra parameters. */
1934 /* */
1935 /* params :: Extra parameters passed to the font driver when */
1936 /* opening a new face. */
1937 /* */
1938 /* <Note> */
1939 /* The stream type is determined by the contents of `flags' that */
1940 /* are tested in the following order by @FT_Open_Face: */
1941 /* */
1942 /* If the @FT_OPEN_MEMORY bit is set, assume that this is a */
1943 /* memory file of `memory_size' bytes, located at `memory_address'. */
1944 /* The data are are not copied, and the client is responsible for */
1945 /* releasing and destroying them _after_ the corresponding call to */
1946 /* @FT_Done_Face. */
1947 /* */
1948 /* Otherwise, if the @FT_OPEN_STREAM bit is set, assume that a */
1949 /* custom input stream `stream' is used. */
1950 /* */
1951 /* Otherwise, if the @FT_OPEN_PATHNAME bit is set, assume that this */
1952 /* is a normal file and use `pathname' to open it. */
1953 /* */
1954 /* If the @FT_OPEN_DRIVER bit is set, @FT_Open_Face only tries to */
1955 /* open the file with the driver whose handler is in `driver'. */
1956 /* */
1957 /* If the @FT_OPEN_PARAMS bit is set, the parameters given by */
1958 /* `num_params' and `params' is used. They are ignored otherwise. */
1959 /* */
1960 /* Ideally, both the `pathname' and `params' fields should be tagged */
1961 /* as `const'; this is missing for API backwards compatibility. In */
1962 /* other words, applications should treat them as read-only. */
1963 /* */
1964 typedef struct FT_Open_Args_
1965 {
1966 FT_UInt flags;
1967 const FT_Byte* memory_base;
1968 FT_Long memory_size;
1969 FT_String* pathname;
1970 FT_Stream stream;
1971 FT_Module driver;
1972 FT_Int num_params;
1973 FT_Parameter* params;
1974
1975 } FT_Open_Args;
1976
1977
1978 /*************************************************************************/
1979 /* */
1980 /* <Function> */
1981 /* FT_New_Face */
1982 /* */
1983 /* <Description> */
1984 /* This function calls @FT_Open_Face to open a font by its pathname. */
1985 /* */
1986 /* <InOut> */
1987 /* library :: A handle to the library resource. */
1988 /* */
1989 /* <Input> */
1990 /* pathname :: A path to the font file. */
1991 /* */
1992 /* face_index :: See @FT_Open_Face for a detailed description of this */
1993 /* parameter. */
1994 /* */
1995 /* <Output> */
1996 /* aface :: A handle to a new face object. If `face_index' is */
1997 /* greater than or equal to zero, it must be non-NULL. */
1998 /* */
1999 /* <Return> */
2000 /* FreeType error code. 0~means success. */
2001 /* */
2002 /* <Note> */
2003 /* Use @FT_Done_Face to destroy the created @FT_Face object (along */
2004 /* with its slot and sizes). */
2005 /* */
2006 FT_EXPORT( FT_Error )
2007 FT_New_Face( FT_Library library,
2008 const char* filepathname,
2009 FT_Long face_index,
2010 FT_Face *aface );
2011
2012
2013 /*************************************************************************/
2014 /* */
2015 /* <Function> */
2016 /* FT_New_Memory_Face */
2017 /* */
2018 /* <Description> */
2019 /* This function calls @FT_Open_Face to open a font that has been */
2020 /* loaded into memory. */
2021 /* */
2022 /* <InOut> */
2023 /* library :: A handle to the library resource. */
2024 /* */
2025 /* <Input> */
2026 /* file_base :: A pointer to the beginning of the font data. */
2027 /* */
2028 /* file_size :: The size of the memory chunk used by the font data. */
2029 /* */
2030 /* face_index :: See @FT_Open_Face for a detailed description of this */
2031 /* parameter. */
2032 /* */
2033 /* <Output> */
2034 /* aface :: A handle to a new face object. If `face_index' is */
2035 /* greater than or equal to zero, it must be non-NULL. */
2036 /* */
2037 /* <Return> */
2038 /* FreeType error code. 0~means success. */
2039 /* */
2040 /* <Note> */
2041 /* You must not deallocate the memory before calling @FT_Done_Face. */
2042 /* */
2043 FT_EXPORT( FT_Error )
2044 FT_New_Memory_Face( FT_Library library,
2045 const FT_Byte* file_base,
2046 FT_Long file_size,
2047 FT_Long face_index,
2048 FT_Face *aface );
2049
2050
2051 /*************************************************************************/
2052 /* */
2053 /* <Function> */
2054 /* FT_Open_Face */
2055 /* */
2056 /* <Description> */
2057 /* Create a face object from a given resource described by */
2058 /* @FT_Open_Args. */
2059 /* */
2060 /* <InOut> */
2061 /* library :: A handle to the library resource. */
2062 /* */
2063 /* <Input> */
2064 /* args :: A pointer to an `FT_Open_Args' structure that must */
2065 /* be filled by the caller. */
2066 /* */
2067 /* face_index :: This field holds two different values. Bits 0-15 */
2068 /* are the index of the face in the font file (starting */
2069 /* with value~0). Set it to~0 if there is only one */
2070 /* face in the font file. */
2071 /* */
2072 /* Bits 16-30 are relevant to GX variation fonts only, */
2073 /* specifying the named instance index for the current */
2074 /* face index (starting with value~1; value~0 makes */
2075 /* FreeType ignore named instances). For non-GX fonts, */
2076 /* bits 16-30 are ignored. Assuming that you want to */
2077 /* access the third named instance in face~4, */
2078 /* `face_index' should be set to 0x00030004. If you */
2079 /* want to access face~4 without GX variation handling, */
2080 /* simply set `face_index' to value~4. */
2081 /* */
2082 /* FT_Open_Face and its siblings can be used to quickly */
2083 /* check whether the font format of a given font */
2084 /* resource is supported by FreeType. In general, if */
2085 /* the `face_index' argument is negative, the */
2086 /* function's return value is~0 if the font format is */
2087 /* recognized, or non-zero otherwise. The function */
2088 /* allocates a more or less empty face handle in */
2089 /* `*aface' (if `aface' isn't NULL); the only two */
2090 /* useful fields in this special case are */
2091 /* `face->num_faces' and `face->style_flags'. For any */
2092 /* negative value of `face_index', `face->num_faces' */
2093 /* gives the number of faces within the font file. For */
2094 /* the negative value `-(N+1)' (with `N' a 16-bit */
2095 /* value), bits 16-30 in `face->style_flags' give the */
2096 /* number of named instances in face `N' if we have a */
2097 /* GX variation font (or zero otherwise). After */
2098 /* examination, the returned @FT_Face structure should */
2099 /* be deallocated with a call to @FT_Done_Face. */
2100 /* */
2101 /* <Output> */
2102 /* aface :: A handle to a new face object. If `face_index' is */
2103 /* greater than or equal to zero, it must be non-NULL. */
2104 /* */
2105 /* <Return> */
2106 /* FreeType error code. 0~means success. */
2107 /* */
2108 /* <Note> */
2109 /* Unlike FreeType 1.x, this function automatically creates a glyph */
2110 /* slot for the face object that can be accessed directly through */
2111 /* `face->glyph'. */
2112 /* */
2113 /* Each new face object created with this function also owns a */
2114 /* default @FT_Size object, accessible as `face->size'. */
2115 /* */
2116 /* One @FT_Library instance can have multiple face objects, this is, */
2117 /* @FT_Open_Face and its siblings can be called multiple times using */
2118 /* the same `library' argument. */
2119 /* */
2120 /* See the discussion of reference counters in the description of */
2121 /* @FT_Reference_Face. */
2122 /* */
2123 /* To loop over all faces, use code similar to the following snippet */
2124 /* (omitting the error handling). */
2125 /* */
2126 /* { */
2127 /* ... */
2128 /* FT_Face face; */
2129 /* FT_Long i, num_faces; */
2130 /* */
2131 /* */
2132 /* error = FT_Open_Face( library, args, -1, &face ); */
2133 /* if ( error ) { ... } */
2134 /* */
2135 /* num_faces = face->num_faces; */
2136 /* FT_Done_Face( face ); */
2137 /* */
2138 /* for ( i = 0; i < num_faces; i++ ) */
2139 /* { */
2140 /* ... */
2141 /* error = FT_Open_Face( library, args, i, &face ); */
2142 /* ... */
2143 /* FT_Done_Face( face ); */
2144 /* ... */
2145 /* } */
2146 /* } */
2147 /* */
2148 /* To loop over all valid values for `face_index', use something */
2149 /* similar to the following snippet, again without error handling. */
2150 /* The code accesses all faces immediately (thus only a single call */
2151 /* of `FT_Open_Face' within the do-loop), with and without named */
2152 /* instances. */
2153 /* */
2154 /* { */
2155 /* ... */
2156 /* FT_Face face; */
2157 /* */
2158 /* FT_Long num_faces = 0; */
2159 /* FT_Long num_instances = 0; */
2160 /* */
2161 /* FT_Long face_idx = 0; */
2162 /* FT_Long instance_idx = 0; */
2163 /* */
2164 /* */
2165 /* do */
2166 /* { */
2167 /* FT_Long id = ( instance_idx << 16 ) + face_idx; */
2168 /* */
2169 /* */
2170 /* error = FT_Open_Face( library, args, id, &face ); */
2171 /* if ( error ) { ... } */
2172 /* */
2173 /* num_faces = face->num_faces; */
2174 /* num_instances = face->style_flags >> 16; */
2175 /* */
2176 /* ... */
2177 /* */
2178 /* FT_Done_Face( face ); */
2179 /* */
2180 /* if ( instance_idx < num_instances ) */
2181 /* instance_idx++; */
2182 /* else */
2183 /* { */
2184 /* face_idx++; */
2185 /* instance_idx = 0; */
2186 /* } */
2187 /* */
2188 /* } while ( face_idx < num_faces ) */
2189 /* } */
2190 /* */
2191 FT_EXPORT( FT_Error )
2192 FT_Open_Face( FT_Library library,
2193 const FT_Open_Args* args,
2194 FT_Long face_index,
2195 FT_Face *aface );
2196
2197
2198 /*************************************************************************/
2199 /* */
2200 /* <Function> */
2201 /* FT_Attach_File */
2202 /* */
2203 /* <Description> */
2204 /* This function calls @FT_Attach_Stream to attach a file. */
2205 /* */
2206 /* <InOut> */
2207 /* face :: The target face object. */
2208 /* */
2209 /* <Input> */
2210 /* filepathname :: The pathname. */
2211 /* */
2212 /* <Return> */
2213 /* FreeType error code. 0~means success. */
2214 /* */
2215 FT_EXPORT( FT_Error )
2216 FT_Attach_File( FT_Face face,
2217 const char* filepathname );
2218
2219
2220 /*************************************************************************/
2221 /* */
2222 /* <Function> */
2223 /* FT_Attach_Stream */
2224 /* */
2225 /* <Description> */
2226 /* `Attach' data to a face object. Normally, this is used to read */
2227 /* additional information for the face object. For example, you can */
2228 /* attach an AFM file that comes with a Type~1 font to get the */
2229 /* kerning values and other metrics. */
2230 /* */
2231 /* <InOut> */
2232 /* face :: The target face object. */
2233 /* */
2234 /* <Input> */
2235 /* parameters :: A pointer to @FT_Open_Args that must be filled by */
2236 /* the caller. */
2237 /* */
2238 /* <Return> */
2239 /* FreeType error code. 0~means success. */
2240 /* */
2241 /* <Note> */
2242 /* The meaning of the `attach' (i.e., what really happens when the */
2243 /* new file is read) is not fixed by FreeType itself. It really */
2244 /* depends on the font format (and thus the font driver). */
2245 /* */
2246 /* Client applications are expected to know what they are doing */
2247 /* when invoking this function. Most drivers simply do not implement */
2248 /* file attachments. */
2249 /* */
2250 FT_EXPORT( FT_Error )
2251 FT_Attach_Stream( FT_Face face,
2252 FT_Open_Args* parameters );
2253
2254
2255 /*************************************************************************/
2256 /* */
2257 /* <Function> */
2258 /* FT_Reference_Face */
2259 /* */
2260 /* <Description> */
2261 /* A counter gets initialized to~1 at the time an @FT_Face structure */
2262 /* is created. This function increments the counter. @FT_Done_Face */
2263 /* then only destroys a face if the counter is~1, otherwise it simply */
2264 /* decrements the counter. */
2265 /* */
2266 /* This function helps in managing life-cycles of structures that */
2267 /* reference @FT_Face objects. */
2268 /* */
2269 /* <Input> */
2270 /* face :: A handle to a target face object. */
2271 /* */
2272 /* <Return> */
2273 /* FreeType error code. 0~means success. */
2274 /* */
2275 /* <Since> */
2276 /* 2.4.2 */
2277 /* */
2278 FT_EXPORT( FT_Error )
2279 FT_Reference_Face( FT_Face face );
2280
2281
2282 /*************************************************************************/
2283 /* */
2284 /* <Function> */
2285 /* FT_Done_Face */
2286 /* */
2287 /* <Description> */
2288 /* Discard a given face object, as well as all of its child slots and */
2289 /* sizes. */
2290 /* */
2291 /* <Input> */
2292 /* face :: A handle to a target face object. */
2293 /* */
2294 /* <Return> */
2295 /* FreeType error code. 0~means success. */
2296 /* */
2297 /* <Note> */
2298 /* See the discussion of reference counters in the description of */
2299 /* @FT_Reference_Face. */
2300 /* */
2301 FT_EXPORT( FT_Error )
2302 FT_Done_Face( FT_Face face );
2303
2304
2305 /*************************************************************************/
2306 /* */
2307 /* <Function> */
2308 /* FT_Select_Size */
2309 /* */
2310 /* <Description> */
2311 /* Select a bitmap strike. */
2312 /* */
2313 /* <InOut> */
2314 /* face :: A handle to a target face object. */
2315 /* */
2316 /* <Input> */
2317 /* strike_index :: The index of the bitmap strike in the */
2318 /* `available_sizes' field of @FT_FaceRec structure. */
2319 /* */
2320 /* <Return> */
2321 /* FreeType error code. 0~means success. */
2322 /* */
2323 FT_EXPORT( FT_Error )
2324 FT_Select_Size( FT_Face face,
2325 FT_Int strike_index );
2326
2327
2328 /*************************************************************************/
2329 /* */
2330 /* <Enum> */
2331 /* FT_Size_Request_Type */
2332 /* */
2333 /* <Description> */
2334 /* An enumeration type that lists the supported size request types. */
2335 /* */
2336 /* <Values> */
2337 /* FT_SIZE_REQUEST_TYPE_NOMINAL :: */
2338 /* The nominal size. The `units_per_EM' field of @FT_FaceRec is */
2339 /* used to determine both scaling values. */
2340 /* */
2341 /* FT_SIZE_REQUEST_TYPE_REAL_DIM :: */
2342 /* The real dimension. The sum of the the `ascender' and (minus */
2343 /* of) the `descender' fields of @FT_FaceRec are used to determine */
2344 /* both scaling values. */
2345 /* */
2346 /* FT_SIZE_REQUEST_TYPE_BBOX :: */
2347 /* The font bounding box. The width and height of the `bbox' field */
2348 /* of @FT_FaceRec are used to determine the horizontal and vertical */
2349 /* scaling value, respectively. */
2350 /* */
2351 /* FT_SIZE_REQUEST_TYPE_CELL :: */
2352 /* The `max_advance_width' field of @FT_FaceRec is used to */
2353 /* determine the horizontal scaling value; the vertical scaling */
2354 /* value is determined the same way as */
2355 /* @FT_SIZE_REQUEST_TYPE_REAL_DIM does. Finally, both scaling */
2356 /* values are set to the smaller one. This type is useful if you */
2357 /* want to specify the font size for, say, a window of a given */
2358 /* dimension and 80x24 cells. */
2359 /* */
2360 /* FT_SIZE_REQUEST_TYPE_SCALES :: */
2361 /* Specify the scaling values directly. */
2362 /* */
2363 /* <Note> */
2364 /* The above descriptions only apply to scalable formats. For bitmap */
2365 /* formats, the behaviour is up to the driver. */
2366 /* */
2367 /* See the note section of @FT_Size_Metrics if you wonder how size */
2368 /* requesting relates to scaling values. */
2369 /* */
2370 typedef enum FT_Size_Request_Type_
2371 {
2372 FT_SIZE_REQUEST_TYPE_NOMINAL,
2373 FT_SIZE_REQUEST_TYPE_REAL_DIM,
2374 FT_SIZE_REQUEST_TYPE_BBOX,
2375 FT_SIZE_REQUEST_TYPE_CELL,
2376 FT_SIZE_REQUEST_TYPE_SCALES,
2377
2378 FT_SIZE_REQUEST_TYPE_MAX
2379
2380 } FT_Size_Request_Type;
2381
2382
2383 /*************************************************************************/
2384 /* */
2385 /* <Struct> */
2386 /* FT_Size_RequestRec */
2387 /* */
2388 /* <Description> */
2389 /* A structure used to model a size request. */
2390 /* */
2391 /* <Fields> */
2392 /* type :: See @FT_Size_Request_Type. */
2393 /* */
2394 /* width :: The desired width. */
2395 /* */
2396 /* height :: The desired height. */
2397 /* */
2398 /* horiResolution :: The horizontal resolution. If set to zero, */
2399 /* `width' is treated as a 26.6 fractional pixel */
2400 /* value. */
2401 /* */
2402 /* vertResolution :: The vertical resolution. If set to zero, */
2403 /* `height' is treated as a 26.6 fractional pixel */
2404 /* value. */
2405 /* */
2406 /* <Note> */
2407 /* If `width' is zero, then the horizontal scaling value is set equal */
2408 /* to the vertical scaling value, and vice versa. */
2409 /* */
2410 typedef struct FT_Size_RequestRec_
2411 {
2412 FT_Size_Request_Type type;
2413 FT_Long width;
2414 FT_Long height;
2415 FT_UInt horiResolution;
2416 FT_UInt vertResolution;
2417
2418 } FT_Size_RequestRec;
2419
2420
2421 /*************************************************************************/
2422 /* */
2423 /* <Struct> */
2424 /* FT_Size_Request */
2425 /* */
2426 /* <Description> */
2427 /* A handle to a size request structure. */
2428 /* */
2429 typedef struct FT_Size_RequestRec_ *FT_Size_Request;
2430
2431
2432 /*************************************************************************/
2433 /* */
2434 /* <Function> */
2435 /* FT_Request_Size */
2436 /* */
2437 /* <Description> */
2438 /* Resize the scale of the active @FT_Size object in a face. */
2439 /* */
2440 /* <InOut> */
2441 /* face :: A handle to a target face object. */
2442 /* */
2443 /* <Input> */
2444 /* req :: A pointer to a @FT_Size_RequestRec. */
2445 /* */
2446 /* <Return> */
2447 /* FreeType error code. 0~means success. */
2448 /* */
2449 /* <Note> */
2450 /* Although drivers may select the bitmap strike matching the */
2451 /* request, you should not rely on this if you intend to select a */
2452 /* particular bitmap strike. Use @FT_Select_Size instead in that */
2453 /* case. */
2454 /* */
2455 /* The relation between the requested size and the resulting glyph */
2456 /* size is dependent entirely on how the size is defined in the */
2457 /* source face. The font designer chooses the final size of each */
2458 /* glyph relative to this size. For more information refer to */
2459 /* `http://www.freetype.org/freetype2/docs/glyphs/glyphs-2.html' */
2460 /* */
2461 /* Don't use this function if you are using the FreeType cache API. */
2462 /* */
2463 FT_EXPORT( FT_Error )
2464 FT_Request_Size( FT_Face face,
2465 FT_Size_Request req );
2466
2467
2468 /*************************************************************************/
2469 /* */
2470 /* <Function> */
2471 /* FT_Set_Char_Size */
2472 /* */
2473 /* <Description> */
2474 /* This function calls @FT_Request_Size to request the nominal size */
2475 /* (in points). */
2476 /* */
2477 /* <InOut> */
2478 /* face :: A handle to a target face object. */
2479 /* */
2480 /* <Input> */
2481 /* char_width :: The nominal width, in 26.6 fractional points. */
2482 /* */
2483 /* char_height :: The nominal height, in 26.6 fractional points. */
2484 /* */
2485 /* horz_resolution :: The horizontal resolution in dpi. */
2486 /* */
2487 /* vert_resolution :: The vertical resolution in dpi. */
2488 /* */
2489 /* <Return> */
2490 /* FreeType error code. 0~means success. */
2491 /* */
2492 /* <Note> */
2493 /* If either the character width or height is zero, it is set equal */
2494 /* to the other value. */
2495 /* */
2496 /* If either the horizontal or vertical resolution is zero, it is set */
2497 /* equal to the other value. */
2498 /* */
2499 /* A character width or height smaller than 1pt is set to 1pt; if */
2500 /* both resolution values are zero, they are set to 72dpi. */
2501 /* */
2502 /* Don't use this function if you are using the FreeType cache API. */
2503 /* */
2504 FT_EXPORT( FT_Error )
2505 FT_Set_Char_Size( FT_Face face,
2506 FT_F26Dot6 char_width,
2507 FT_F26Dot6 char_height,
2508 FT_UInt horz_resolution,
2509 FT_UInt vert_resolution );
2510
2511
2512 /*************************************************************************/
2513 /* */
2514 /* <Function> */
2515 /* FT_Set_Pixel_Sizes */
2516 /* */
2517 /* <Description> */
2518 /* This function calls @FT_Request_Size to request the nominal size */
2519 /* (in pixels). */
2520 /* */
2521 /* <InOut> */
2522 /* face :: A handle to the target face object. */
2523 /* */
2524 /* <Input> */
2525 /* pixel_width :: The nominal width, in pixels. */
2526 /* */
2527 /* pixel_height :: The nominal height, in pixels. */
2528 /* */
2529 /* <Return> */
2530 /* FreeType error code. 0~means success. */
2531 /* */
2532 /* <Note> */
2533 /* You should not rely on the resulting glyphs matching, or being */
2534 /* constrained, to this pixel size. Refer to @FT_Request_Size to */
2535 /* understand how requested sizes relate to actual sizes. */
2536 /* */
2537 /* Don't use this function if you are using the FreeType cache API. */
2538 /* */
2539 FT_EXPORT( FT_Error )
2540 FT_Set_Pixel_Sizes( FT_Face face,
2541 FT_UInt pixel_width,
2542 FT_UInt pixel_height );
2543
2544
2545 /*************************************************************************/
2546 /* */
2547 /* <Function> */
2548 /* FT_Load_Glyph */
2549 /* */
2550 /* <Description> */
2551 /* A function used to load a single glyph into the glyph slot of a */
2552 /* face object. */
2553 /* */
2554 /* <InOut> */
2555 /* face :: A handle to the target face object where the glyph */
2556 /* is loaded. */
2557 /* */
2558 /* <Input> */
2559 /* glyph_index :: The index of the glyph in the font file. For */
2560 /* CID-keyed fonts (either in PS or in CFF format) */
2561 /* this argument specifies the CID value. */
2562 /* */
2563 /* load_flags :: A flag indicating what to load for this glyph. The */
2564 /* @FT_LOAD_XXX constants can be used to control the */
2565 /* glyph loading process (e.g., whether the outline */
2566 /* should be scaled, whether to load bitmaps or not, */
2567 /* whether to hint the outline, etc). */
2568 /* */
2569 /* <Return> */
2570 /* FreeType error code. 0~means success. */
2571 /* */
2572 /* <Note> */
2573 /* The loaded glyph may be transformed. See @FT_Set_Transform for */
2574 /* the details. */
2575 /* */
2576 /* For subsetted CID-keyed fonts, `FT_Err_Invalid_Argument' is */
2577 /* returned for invalid CID values (this is, for CID values that */
2578 /* don't have a corresponding glyph in the font). See the discussion */
2579 /* of the @FT_FACE_FLAG_CID_KEYED flag for more details. */
2580 /* */
2581 FT_EXPORT( FT_Error )
2582 FT_Load_Glyph( FT_Face face,
2583 FT_UInt glyph_index,
2584 FT_Int32 load_flags );
2585
2586
2587 /*************************************************************************/
2588 /* */
2589 /* <Function> */
2590 /* FT_Load_Char */
2591 /* */
2592 /* <Description> */
2593 /* A function used to load a single glyph into the glyph slot of a */
2594 /* face object, according to its character code. */
2595 /* */
2596 /* <InOut> */
2597 /* face :: A handle to a target face object where the glyph */
2598 /* is loaded. */
2599 /* */
2600 /* <Input> */
2601 /* char_code :: The glyph's character code, according to the */
2602 /* current charmap used in the face. */
2603 /* */
2604 /* load_flags :: A flag indicating what to load for this glyph. The */
2605 /* @FT_LOAD_XXX constants can be used to control the */
2606 /* glyph loading process (e.g., whether the outline */
2607 /* should be scaled, whether to load bitmaps or not, */
2608 /* whether to hint the outline, etc). */
2609 /* */
2610 /* <Return> */
2611 /* FreeType error code. 0~means success. */
2612 /* */
2613 /* <Note> */
2614 /* This function simply calls @FT_Get_Char_Index and @FT_Load_Glyph. */
2615 /* */
2616 FT_EXPORT( FT_Error )
2617 FT_Load_Char( FT_Face face,
2618 FT_ULong char_code,
2619 FT_Int32 load_flags );
2620
2621
2622 /*************************************************************************
2623 *
2624 * @enum:
2625 * FT_LOAD_XXX
2626 *
2627 * @description:
2628 * A list of bit field constants used with @FT_Load_Glyph to indicate
2629 * what kind of operations to perform during glyph loading.
2630 *
2631 * @values:
2632 * FT_LOAD_DEFAULT ::
2633 * Corresponding to~0, this value is used as the default glyph load
2634 * operation. In this case, the following happens:
2635 *
2636 * 1. FreeType looks for a bitmap for the glyph corresponding to the
2637 * face's current size. If one is found, the function returns.
2638 * The bitmap data can be accessed from the glyph slot (see note
2639 * below).
2640 *
2641 * 2. If no embedded bitmap is searched or found, FreeType looks for a
2642 * scalable outline. If one is found, it is loaded from the font
2643 * file, scaled to device pixels, then `hinted' to the pixel grid
2644 * in order to optimize it. The outline data can be accessed from
2645 * the glyph slot (see note below).
2646 *
2647 * Note that by default, the glyph loader doesn't render outlines into
2648 * bitmaps. The following flags are used to modify this default
2649 * behaviour to more specific and useful cases.
2650 *
2651 * FT_LOAD_NO_SCALE ::
2652 * Don't scale the loaded outline glyph but keep it in font units.
2653 *
2654 * This flag implies @FT_LOAD_NO_HINTING and @FT_LOAD_NO_BITMAP, and
2655 * unsets @FT_LOAD_RENDER.
2656 *
2657 * If the font is `tricky' (see @FT_FACE_FLAG_TRICKY for more), using
2658 * FT_LOAD_NO_SCALE usually yields meaningless outlines because the
2659 * subglyphs must be scaled and positioned with hinting instructions.
2660 * This can be solved by loading the font without FT_LOAD_NO_SCALE and
2661 * setting the character size to `font->units_per_EM'.
2662 *
2663 * FT_LOAD_NO_HINTING ::
2664 * Disable hinting. This generally generates `blurrier' bitmap glyphs
2665 * when the glyph are rendered in any of the anti-aliased modes. See
2666 * also the note below.
2667 *
2668 * This flag is implied by @FT_LOAD_NO_SCALE.
2669 *
2670 * FT_LOAD_RENDER ::
2671 * Call @FT_Render_Glyph after the glyph is loaded. By default, the
2672 * glyph is rendered in @FT_RENDER_MODE_NORMAL mode. This can be
2673 * overridden by @FT_LOAD_TARGET_XXX or @FT_LOAD_MONOCHROME.
2674 *
2675 * This flag is unset by @FT_LOAD_NO_SCALE.
2676 *
2677 * FT_LOAD_NO_BITMAP ::
2678 * Ignore bitmap strikes when loading. Bitmap-only fonts ignore this
2679 * flag.
2680 *
2681 * @FT_LOAD_NO_SCALE always sets this flag.
2682 *
2683 * FT_LOAD_VERTICAL_LAYOUT ::
2684 * Load the glyph for vertical text layout. In particular, the
2685 * `advance' value in the @FT_GlyphSlotRec structure is set to the
2686 * `vertAdvance' value of the `metrics' field.
2687 *
2688 * In case @FT_HAS_VERTICAL doesn't return true, you shouldn't use
2689 * this flag currently. Reason is that in this case vertical metrics
2690 * get synthesized, and those values are not always consistent across
2691 * various font formats.
2692 *
2693 * FT_LOAD_FORCE_AUTOHINT ::
2694 * Indicates that the auto-hinter is preferred over the font's native
2695 * hinter. See also the note below.
2696 *
2697 * FT_LOAD_PEDANTIC ::
2698 * Indicates that the font driver should perform pedantic verifications
2699 * during glyph loading. This is mostly used to detect broken glyphs
2700 * in fonts. By default, FreeType tries to handle broken fonts also.
2701 *
2702 * In particular, errors from the TrueType bytecode engine are not
2703 * passed to the application if this flag is not set; this might
2704 * result in partially hinted or distorted glyphs in case a glyph's
2705 * bytecode is buggy.
2706 *
2707 * FT_LOAD_NO_RECURSE ::
2708 * Indicate that the font driver should not load composite glyphs
2709 * recursively. Instead, it should set the `num_subglyph' and
2710 * `subglyphs' values of the glyph slot accordingly, and set
2711 * `glyph->format' to @FT_GLYPH_FORMAT_COMPOSITE. The description of
2712 * subglyphs can then be accessed with @FT_Get_SubGlyph_Info.
2713 *
2714 * This flag implies @FT_LOAD_NO_SCALE and @FT_LOAD_IGNORE_TRANSFORM.
2715 *
2716 * FT_LOAD_IGNORE_TRANSFORM ::
2717 * Indicates that the transform matrix set by @FT_Set_Transform should
2718 * be ignored.
2719 *
2720 * FT_LOAD_MONOCHROME ::
2721 * This flag is used with @FT_LOAD_RENDER to indicate that you want to
2722 * render an outline glyph to a 1-bit monochrome bitmap glyph, with
2723 * 8~pixels packed into each byte of the bitmap data.
2724 *
2725 * Note that this has no effect on the hinting algorithm used. You
2726 * should rather use @FT_LOAD_TARGET_MONO so that the
2727 * monochrome-optimized hinting algorithm is used.
2728 *
2729 * FT_LOAD_LINEAR_DESIGN ::
2730 * Indicates that the `linearHoriAdvance' and `linearVertAdvance'
2731 * fields of @FT_GlyphSlotRec should be kept in font units. See
2732 * @FT_GlyphSlotRec for details.
2733 *
2734 * FT_LOAD_NO_AUTOHINT ::
2735 * Disable auto-hinter. See also the note below.
2736 *
2737 * FT_LOAD_COLOR ::
2738 * This flag is used to request loading of color embedded-bitmap
2739 * images. The resulting color bitmaps, if available, will have the
2740 * @FT_PIXEL_MODE_BGRA format. When the flag is not used and color
2741 * bitmaps are found, they will be converted to 256-level gray
2742 * bitmaps transparently. Those bitmaps will be in the
2743 * @FT_PIXEL_MODE_GRAY format.
2744 *
2745 * FT_LOAD_COMPUTE_METRICS ::
2746 * This flag sets computing glyph metrics without the use of bundled
2747 * metrics tables (for example, the `hdmx' table in TrueType fonts).
2748 * Well-behaving fonts have optimized bundled metrics and these should
2749 * be used. This flag is mainly used by font validating or font
2750 * editing applications, which need to ignore, verify, or edit those
2751 * tables.
2752 *
2753 * Currently, this flag is only implemented for TrueType fonts.
2754 *
2755 * FT_LOAD_CROP_BITMAP ::
2756 * Ignored. Deprecated.
2757 *
2758 * FT_LOAD_IGNORE_GLOBAL_ADVANCE_WIDTH ::
2759 * Ignored. Deprecated.
2760 *
2761 * @note:
2762 * By default, hinting is enabled and the font's native hinter (see
2763 * @FT_FACE_FLAG_HINTER) is preferred over the auto-hinter. You can
2764 * disable hinting by setting @FT_LOAD_NO_HINTING or change the
2765 * precedence by setting @FT_LOAD_FORCE_AUTOHINT. You can also set
2766 * @FT_LOAD_NO_AUTOHINT in case you don't want the auto-hinter to be
2767 * used at all.
2768 *
2769 * See the description of @FT_FACE_FLAG_TRICKY for a special exception
2770 * (affecting only a handful of Asian fonts).
2771 *
2772 * Besides deciding which hinter to use, you can also decide which
2773 * hinting algorithm to use. See @FT_LOAD_TARGET_XXX for details.
2774 *
2775 * Note that the auto-hinter needs a valid Unicode cmap (either a native
2776 * one or synthesized by FreeType) for producing correct results. If a
2777 * font provides an incorrect mapping (for example, assigning the
2778 * character code U+005A, LATIN CAPITAL LETTER Z, to a glyph depicting a
2779 * mathematical integral sign), the auto-hinter might produce useless
2780 * results.
2781 *
2782 */
2783#define FT_LOAD_DEFAULT 0x0
2784#define FT_LOAD_NO_SCALE ( 1L << 0 )
2785#define FT_LOAD_NO_HINTING ( 1L << 1 )
2786#define FT_LOAD_RENDER ( 1L << 2 )
2787#define FT_LOAD_NO_BITMAP ( 1L << 3 )
2788#define FT_LOAD_VERTICAL_LAYOUT ( 1L << 4 )
2789#define FT_LOAD_FORCE_AUTOHINT ( 1L << 5 )
2790#define FT_LOAD_CROP_BITMAP ( 1L << 6 )
2791#define FT_LOAD_PEDANTIC ( 1L << 7 )
2792#define FT_LOAD_IGNORE_GLOBAL_ADVANCE_WIDTH ( 1L << 9 )
2793#define FT_LOAD_NO_RECURSE ( 1L << 10 )
2794#define FT_LOAD_IGNORE_TRANSFORM ( 1L << 11 )
2795#define FT_LOAD_MONOCHROME ( 1L << 12 )
2796#define FT_LOAD_LINEAR_DESIGN ( 1L << 13 )
2797#define FT_LOAD_NO_AUTOHINT ( 1L << 15 )
2798 /* Bits 16..19 are used by `FT_LOAD_TARGET_' */
2799#define FT_LOAD_COLOR ( 1L << 20 )
2800#define FT_LOAD_COMPUTE_METRICS ( 1L << 21 )
2801
2802 /* */
2803
2804 /* used internally only by certain font drivers! */
2805#define FT_LOAD_ADVANCE_ONLY ( 1L << 8 )
2806#define FT_LOAD_SBITS_ONLY ( 1L << 14 )
2807
2808
2809 /**************************************************************************
2810 *
2811 * @enum:
2812 * FT_LOAD_TARGET_XXX
2813 *
2814 * @description:
2815 * A list of values that are used to select a specific hinting algorithm
2816 * to use by the hinter. You should OR one of these values to your
2817 * `load_flags' when calling @FT_Load_Glyph.
2818 *
2819 * Note that font's native hinters may ignore the hinting algorithm you
2820 * have specified (e.g., the TrueType bytecode interpreter). You can set
2821 * @FT_LOAD_FORCE_AUTOHINT to ensure that the auto-hinter is used.
2822 *
2823 * @values:
2824 * FT_LOAD_TARGET_NORMAL ::
2825 * This corresponds to the default hinting algorithm, optimized for
2826 * standard gray-level rendering. For monochrome output, use
2827 * @FT_LOAD_TARGET_MONO instead.
2828 *
2829 * FT_LOAD_TARGET_LIGHT ::
2830 * A lighter hinting algorithm for gray-level modes. Many generated
2831 * glyphs are fuzzier but better resemble their original shape. This
2832 * is achieved by snapping glyphs to the pixel grid only vertically
2833 * (Y-axis), as is done by Microsoft's ClearType and Adobe's
2834 * proprietary font renderer. This preserves inter-glyph spacing in
2835 * horizontal text. The snapping is done either by the native font
2836 * driver if the driver itself and the font support it or by the
2837 * auto-hinter.
2838 *
2839 * FT_LOAD_TARGET_MONO ::
2840 * Strong hinting algorithm that should only be used for monochrome
2841 * output. The result is probably unpleasant if the glyph is rendered
2842 * in non-monochrome modes.
2843 *
2844 * FT_LOAD_TARGET_LCD ::
2845 * A variant of @FT_LOAD_TARGET_NORMAL optimized for horizontally
2846 * decimated LCD displays.
2847 *
2848 * FT_LOAD_TARGET_LCD_V ::
2849 * A variant of @FT_LOAD_TARGET_NORMAL optimized for vertically
2850 * decimated LCD displays.
2851 *
2852 * @note:
2853 * You should use only _one_ of the FT_LOAD_TARGET_XXX values in your
2854 * `load_flags'. They can't be ORed.
2855 *
2856 * If @FT_LOAD_RENDER is also set, the glyph is rendered in the
2857 * corresponding mode (i.e., the mode that matches the used algorithm
2858 * best). An exeption is FT_LOAD_TARGET_MONO since it implies
2859 * @FT_LOAD_MONOCHROME.
2860 *
2861 * You can use a hinting algorithm that doesn't correspond to the same
2862 * rendering mode. As an example, it is possible to use the `light'
2863 * hinting algorithm and have the results rendered in horizontal LCD
2864 * pixel mode, with code like
2865 *
2866 * {
2867 * FT_Load_Glyph( face, glyph_index,
2868 * load_flags | FT_LOAD_TARGET_LIGHT );
2869 *
2870 * FT_Render_Glyph( face->glyph, FT_RENDER_MODE_LCD );
2871 * }
2872 *
2873 */
2874#define FT_LOAD_TARGET_( x ) ( (FT_Int32)( (x) & 15 ) << 16 )
2875
2876#define FT_LOAD_TARGET_NORMAL FT_LOAD_TARGET_( FT_RENDER_MODE_NORMAL )
2877#define FT_LOAD_TARGET_LIGHT FT_LOAD_TARGET_( FT_RENDER_MODE_LIGHT )
2878#define FT_LOAD_TARGET_MONO FT_LOAD_TARGET_( FT_RENDER_MODE_MONO )
2879#define FT_LOAD_TARGET_LCD FT_LOAD_TARGET_( FT_RENDER_MODE_LCD )
2880#define FT_LOAD_TARGET_LCD_V FT_LOAD_TARGET_( FT_RENDER_MODE_LCD_V )
2881
2882
2883 /**************************************************************************
2884 *
2885 * @macro:
2886 * FT_LOAD_TARGET_MODE
2887 *
2888 * @description:
2889 * Return the @FT_Render_Mode corresponding to a given
2890 * @FT_LOAD_TARGET_XXX value.
2891 *
2892 */
2893#define FT_LOAD_TARGET_MODE( x ) ( (FT_Render_Mode)( ( (x) >> 16 ) & 15 ) )
2894
2895
2896 /*************************************************************************/
2897 /* */
2898 /* <Function> */
2899 /* FT_Set_Transform */
2900 /* */
2901 /* <Description> */
2902 /* A function used to set the transformation that is applied to glyph */
2903 /* images when they are loaded into a glyph slot through */
2904 /* @FT_Load_Glyph. */
2905 /* */
2906 /* <InOut> */
2907 /* face :: A handle to the source face object. */
2908 /* */
2909 /* <Input> */
2910 /* matrix :: A pointer to the transformation's 2x2 matrix. Use~0 for */
2911 /* the identity matrix. */
2912 /* delta :: A pointer to the translation vector. Use~0 for the null */
2913 /* vector. */
2914 /* */
2915 /* <Note> */
2916 /* The transformation is only applied to scalable image formats after */
2917 /* the glyph has been loaded. It means that hinting is unaltered by */
2918 /* the transformation and is performed on the character size given in */
2919 /* the last call to @FT_Set_Char_Size or @FT_Set_Pixel_Sizes. */
2920 /* */
2921 /* Note that this also transforms the `face.glyph.advance' field, but */
2922 /* *not* the values in `face.glyph.metrics'. */
2923 /* */
2924 FT_EXPORT( void )
2925 FT_Set_Transform( FT_Face face,
2926 FT_Matrix* matrix,
2927 FT_Vector* delta );
2928
2929
2930 /*************************************************************************/
2931 /* */
2932 /* <Enum> */
2933 /* FT_Render_Mode */
2934 /* */
2935 /* <Description> */
2936 /* An enumeration type that lists the render modes supported by */
2937 /* FreeType~2. Each mode corresponds to a specific type of scanline */
2938 /* conversion performed on the outline. */
2939 /* */
2940 /* For bitmap fonts and embedded bitmaps the `bitmap->pixel_mode' */
2941 /* field in the @FT_GlyphSlotRec structure gives the format of the */
2942 /* returned bitmap. */
2943 /* */
2944 /* All modes except @FT_RENDER_MODE_MONO use 256 levels of opacity, */
2945 /* indicating pixel coverage. Use linear alpha blending and gamma */
2946 /* correction to correctly render non-monochrome glyph bitmaps onto a */
2947 /* surface; see @FT_Render_Glyph. */
2948 /* */
2949 /* <Values> */
2950 /* FT_RENDER_MODE_NORMAL :: */
2951 /* This is the default render mode; it corresponds to 8-bit */
2952 /* anti-aliased bitmaps. */
2953 /* */
2954 /* FT_RENDER_MODE_LIGHT :: */
2955 /* This is equivalent to @FT_RENDER_MODE_NORMAL. It is only */
2956 /* defined as a separate value because render modes are also used */
2957 /* indirectly to define hinting algorithm selectors. See */
2958 /* @FT_LOAD_TARGET_XXX for details. */
2959 /* */
2960 /* FT_RENDER_MODE_MONO :: */
2961 /* This mode corresponds to 1-bit bitmaps (with 2~levels of */
2962 /* opacity). */
2963 /* */
2964 /* FT_RENDER_MODE_LCD :: */
2965 /* This mode corresponds to horizontal RGB and BGR sub-pixel */
2966 /* displays like LCD screens. It produces 8-bit bitmaps that are */
2967 /* 3~times the width of the original glyph outline in pixels, and */
2968 /* which use the @FT_PIXEL_MODE_LCD mode. */
2969 /* */
2970 /* FT_RENDER_MODE_LCD_V :: */
2971 /* This mode corresponds to vertical RGB and BGR sub-pixel displays */
2972 /* (like PDA screens, rotated LCD displays, etc.). It produces */
2973 /* 8-bit bitmaps that are 3~times the height of the original */
2974 /* glyph outline in pixels and use the @FT_PIXEL_MODE_LCD_V mode. */
2975 /* */
2976 /* <Note> */
2977 /* The LCD-optimized glyph bitmaps produced by FT_Render_Glyph can be */
2978 /* filtered to reduce color-fringes by using @FT_Library_SetLcdFilter */
2979 /* (not active in the default builds). It is up to the caller to */
2980 /* either call @FT_Library_SetLcdFilter (if available) or do the */
2981 /* filtering itself. */
2982 /* */
2983 /* The selected render mode only affects vector glyphs of a font. */
2984 /* Embedded bitmaps often have a different pixel mode like */
2985 /* @FT_PIXEL_MODE_MONO. You can use @FT_Bitmap_Convert to transform */
2986 /* them into 8-bit pixmaps. */
2987 /* */
2988 typedef enum FT_Render_Mode_
2989 {
2990 FT_RENDER_MODE_NORMAL = 0,
2991 FT_RENDER_MODE_LIGHT,
2992 FT_RENDER_MODE_MONO,
2993 FT_RENDER_MODE_LCD,
2994 FT_RENDER_MODE_LCD_V,
2995
2996 FT_RENDER_MODE_MAX
2997
2998 } FT_Render_Mode;
2999
3000
3001 /* these constants are deprecated; use the corresponding */
3002 /* `FT_Render_Mode' values instead */
3003#define ft_render_mode_normal FT_RENDER_MODE_NORMAL
3004#define ft_render_mode_mono FT_RENDER_MODE_MONO
3005
3006
3007 /*************************************************************************/
3008 /* */
3009 /* <Function> */
3010 /* FT_Render_Glyph */
3011 /* */
3012 /* <Description> */
3013 /* Convert a given glyph image to a bitmap. It does so by inspecting */
3014 /* the glyph image format, finding the relevant renderer, and */
3015 /* invoking it. */
3016 /* */
3017 /* <InOut> */
3018 /* slot :: A handle to the glyph slot containing the image to */
3019 /* convert. */
3020 /* */
3021 /* <Input> */
3022 /* render_mode :: This is the render mode used to render the glyph */
3023 /* image into a bitmap. See @FT_Render_Mode for a */
3024 /* list of possible values. */
3025 /* */
3026 /* <Return> */
3027 /* FreeType error code. 0~means success. */
3028 /* */
3029 /* <Note> */
3030 /* To get meaningful results, font scaling values must be set with */
3031 /* functions like @FT_Set_Char_Size before calling FT_Render_Glyph. */
3032 /* */
3033 /* When FreeType outputs a bitmap of a glyph, it really outputs an */
3034 /* alpha coverage map. If a pixel is completely covered by a */
3035 /* filled-in outline, the bitmap contains 0xFF at that pixel, meaning */
3036 /* that 0xFF/0xFF fraction of that pixel is covered, meaning the */
3037 /* pixel is 100% black (or 0% bright). If a pixel is only 50% */
3038 /* covered (value 0x80), the pixel is made 50% black (50% bright or a */
3039 /* middle shade of grey). 0% covered means 0% black (100% bright or */
3040 /* white). */
3041 /* */
3042 /* On high-DPI screens like on smartphones and tablets, the pixels */
3043 /* are so small that their chance of being completely covered and */
3044 /* therefore completely black are fairly good. On the low-DPI */
3045 /* screens, however, the situation is different. The pixels are too */
3046 /* large for most of the details of a glyph and shades of gray are */
3047 /* the norm rather than the exception. */
3048 /* */
3049 /* This is relevant because all our screens have a second problem: */
3050 /* they are not linear. 1~+~1 is not~2. Twice the value does not */
3051 /* result in twice the brightness. When a pixel is only 50% covered, */
3052 /* the coverage map says 50% black, and this translates to a pixel */
3053 /* value of 128 when you use 8~bits per channel (0-255). However, */
3054 /* this does not translate to 50% brightness for that pixel on our */
3055 /* sRGB and gamma~2.2 screens. Due to their non-linearity, they */
3056 /* dwell longer in the darks and only a pixel value of about 186 */
3057 /* results in 50% brightness – 128 ends up too dark on both bright */
3058 /* and dark backgrounds. The net result is that dark text looks */
3059 /* burnt-out, pixely and blotchy on bright background, bright text */
3060 /* too frail on dark backgrounds, and colored text on colored */
3061 /* background (for example, red on green) seems to have dark halos or */
3062 /* `dirt' around it. The situation is especially ugly for diagonal */
3063 /* stems like in `w' glyph shapes where the quality of FreeType's */
3064 /* anti-aliasing depends on the correct display of grays. On */
3065 /* high-DPI screens where smaller, fully black pixels reign supreme, */
3066 /* this doesn't matter, but on our low-DPI screens with all the gray */
3067 /* shades, it does. 0% and 100% brightness are the same things in */
3068 /* linear and non-linear space, just all the shades in-between */
3069 /* aren't. */
3070 /* */
3071 /* The blending function for placing text over a background is */
3072 /* */
3073 /* { */
3074 /* dst = alpha * src + (1 - alpha) * dst , */
3075 /* } */
3076 /* */
3077 /* which is known as the OVER operator. */
3078 /* */
3079 /* To correctly composite an antialiased pixel of a glyph onto a */
3080 /* surface, */
3081 /* */
3082 /* 1. take the foreground and background colors (e.g., in sRGB space) */
3083 /* and apply gamma to get them in a linear space, */
3084 /* */
3085 /* 2. use OVER to blend the two linear colors using the glyph pixel */
3086 /* as the alpha value (remember, the glyph bitmap is an alpha */
3087 /* coverage bitmap), and */
3088 /* */
3089 /* 3. apply inverse gamma to the blended pixel and write it back to */
3090 /* the image. */
3091 /* */
3092 /* Internal testing at Adobe found that a target inverse gamma of~1.8 */
3093 /* for step~3 gives good results across a wide range of displays with */
3094 /* an sRGB gamma curve or a similar one. */
3095 /* */
3096 /* This process can cost performance. There is an approximation that */
3097 /* does not need to know about the background color; see */
3098 /* https://bel.fi/alankila/lcd/ and */
3099 /* https://bel.fi/alankila/lcd/alpcor.html for details. */
3100 /* */
3101 /* *ATTENTION*: Linear blending is even more important when dealing */
3102 /* with subpixel-rendered glyphs to prevent color-fringing! A */
3103 /* subpixel-rendered glyph must first be filtered with a filter that */
3104 /* gives equal weight to the three color primaries and does not */
3105 /* exceed a sum of 0x100, see section @lcd_filtering. Then the */
3106 /* only difference to gray linear blending is that subpixel-rendered */
3107 /* linear blending is done 3~times per pixel: red foreground subpixel */
3108 /* to red background subpixel and so on for green and blue. */
3109 /* */
3110 FT_EXPORT( FT_Error )
3111 FT_Render_Glyph( FT_GlyphSlot slot,
3112 FT_Render_Mode render_mode );
3113
3114
3115 /*************************************************************************/
3116 /* */
3117 /* <Enum> */
3118 /* FT_Kerning_Mode */
3119 /* */
3120 /* <Description> */
3121 /* An enumeration used to specify which kerning values to return in */
3122 /* @FT_Get_Kerning. */
3123 /* */
3124 /* <Values> */
3125 /* FT_KERNING_DEFAULT :: Return grid-fitted kerning distances in */
3126 /* pixels (value is~0). Whether they are */
3127 /* scaled depends on @FT_LOAD_NO_SCALE. */
3128 /* */
3129 /* FT_KERNING_UNFITTED :: Return un-grid-fitted kerning distances in */
3130 /* 26.6 fractional pixels. Whether they are */
3131 /* scaled depends on @FT_LOAD_NO_SCALE. */
3132 /* */
3133 /* FT_KERNING_UNSCALED :: Return the kerning vector in original font */
3134 /* units. */
3135 /* */
3136 /* <Note> */
3137 /* FT_KERNING_DEFAULT returns full pixel values; it also makes */
3138 /* FreeType heuristically scale down kerning distances at small ppem */
3139 /* values so that they don't become too big. */
3140 /* */
3141 typedef enum FT_Kerning_Mode_
3142 {
3143 FT_KERNING_DEFAULT = 0,
3144 FT_KERNING_UNFITTED,
3145 FT_KERNING_UNSCALED
3146
3147 } FT_Kerning_Mode;
3148
3149
3150 /* these constants are deprecated; use the corresponding */
3151 /* `FT_Kerning_Mode' values instead */
3152#define ft_kerning_default FT_KERNING_DEFAULT
3153#define ft_kerning_unfitted FT_KERNING_UNFITTED
3154#define ft_kerning_unscaled FT_KERNING_UNSCALED
3155
3156
3157 /*************************************************************************/
3158 /* */
3159 /* <Function> */
3160 /* FT_Get_Kerning */
3161 /* */
3162 /* <Description> */
3163 /* Return the kerning vector between two glyphs of a same face. */
3164 /* */
3165 /* <Input> */
3166 /* face :: A handle to a source face object. */
3167 /* */
3168 /* left_glyph :: The index of the left glyph in the kern pair. */
3169 /* */
3170 /* right_glyph :: The index of the right glyph in the kern pair. */
3171 /* */
3172 /* kern_mode :: See @FT_Kerning_Mode for more information. */
3173 /* Determines the scale and dimension of the returned */
3174 /* kerning vector. */
3175 /* */
3176 /* <Output> */
3177 /* akerning :: The kerning vector. This is either in font units, */
3178 /* fractional pixels (26.6 format), or pixels for */
3179 /* scalable formats, and in pixels for fixed-sizes */
3180 /* formats. */
3181 /* */
3182 /* <Return> */
3183 /* FreeType error code. 0~means success. */
3184 /* */
3185 /* <Note> */
3186 /* Only horizontal layouts (left-to-right & right-to-left) are */
3187 /* supported by this method. Other layouts, or more sophisticated */
3188 /* kernings, are out of the scope of this API function -- they can be */
3189 /* implemented through format-specific interfaces. */
3190 /* */
3191 FT_EXPORT( FT_Error )
3192 FT_Get_Kerning( FT_Face face,
3193 FT_UInt left_glyph,
3194 FT_UInt right_glyph,
3195 FT_UInt kern_mode,
3196 FT_Vector *akerning );
3197
3198
3199 /*************************************************************************/
3200 /* */
3201 /* <Function> */
3202 /* FT_Get_Track_Kerning */
3203 /* */
3204 /* <Description> */
3205 /* Return the track kerning for a given face object at a given size. */
3206 /* */
3207 /* <Input> */
3208 /* face :: A handle to a source face object. */
3209 /* */
3210 /* point_size :: The point size in 16.16 fractional points. */
3211 /* */
3212 /* degree :: The degree of tightness. Increasingly negative */
3213 /* values represent tighter track kerning, while */
3214 /* increasingly positive values represent looser track */
3215 /* kerning. Value zero means no track kerning. */
3216 /* */
3217 /* <Output> */
3218 /* akerning :: The kerning in 16.16 fractional points, to be */
3219 /* uniformly applied between all glyphs. */
3220 /* */
3221 /* <Return> */
3222 /* FreeType error code. 0~means success. */
3223 /* */
3224 /* <Note> */
3225 /* Currently, only the Type~1 font driver supports track kerning, */
3226 /* using data from AFM files (if attached with @FT_Attach_File or */
3227 /* @FT_Attach_Stream). */
3228 /* */
3229 /* Only very few AFM files come with track kerning data; please refer */
3230 /* to the Adobe's AFM specification for more details. */
3231 /* */
3232 FT_EXPORT( FT_Error )
3233 FT_Get_Track_Kerning( FT_Face face,
3234 FT_Fixed point_size,
3235 FT_Int degree,
3236 FT_Fixed* akerning );
3237
3238
3239 /*************************************************************************/
3240 /* */
3241 /* <Function> */
3242 /* FT_Get_Glyph_Name */
3243 /* */
3244 /* <Description> */
3245 /* Retrieve the ASCII name of a given glyph in a face. This only */
3246 /* works for those faces where @FT_HAS_GLYPH_NAMES(face) returns~1. */
3247 /* */
3248 /* <Input> */
3249 /* face :: A handle to a source face object. */
3250 /* */
3251 /* glyph_index :: The glyph index. */
3252 /* */
3253 /* buffer_max :: The maximum number of bytes available in the */
3254 /* buffer. */
3255 /* */
3256 /* <Output> */
3257 /* buffer :: A pointer to a target buffer where the name is */
3258 /* copied to. */
3259 /* */
3260 /* <Return> */
3261 /* FreeType error code. 0~means success. */
3262 /* */
3263 /* <Note> */
3264 /* An error is returned if the face doesn't provide glyph names or if */
3265 /* the glyph index is invalid. In all cases of failure, the first */
3266 /* byte of `buffer' is set to~0 to indicate an empty name. */
3267 /* */
3268 /* The glyph name is truncated to fit within the buffer if it is too */
3269 /* long. The returned string is always zero-terminated. */
3270 /* */
3271 /* Be aware that FreeType reorders glyph indices internally so that */
3272 /* glyph index~0 always corresponds to the `missing glyph' (called */
3273 /* `.notdef'). */
3274 /* */
3275 /* This function always returns an error if the config macro */
3276 /* `FT_CONFIG_OPTION_NO_GLYPH_NAMES' is not defined in `ftoptions.h'. */
3277 /* */
3278 FT_EXPORT( FT_Error )
3279 FT_Get_Glyph_Name( FT_Face face,
3280 FT_UInt glyph_index,
3281 FT_Pointer buffer,
3282 FT_UInt buffer_max );
3283
3284
3285 /*************************************************************************/
3286 /* */
3287 /* <Function> */
3288 /* FT_Get_Postscript_Name */
3289 /* */
3290 /* <Description> */
3291 /* Retrieve the ASCII PostScript name of a given face, if available. */
3292 /* This only works with PostScript and TrueType fonts. */
3293 /* */
3294 /* <Input> */
3295 /* face :: A handle to the source face object. */
3296 /* */
3297 /* <Return> */
3298 /* A pointer to the face's PostScript name. NULL if unavailable. */
3299 /* */
3300 /* <Note> */
3301 /* The returned pointer is owned by the face and is destroyed with */
3302 /* it. */
3303 /* */
3304 FT_EXPORT( const char* )
3305 FT_Get_Postscript_Name( FT_Face face );
3306
3307
3308 /*************************************************************************/
3309 /* */
3310 /* <Function> */
3311 /* FT_Select_Charmap */
3312 /* */
3313 /* <Description> */
3314 /* Select a given charmap by its encoding tag (as listed in */
3315 /* `freetype.h'). */
3316 /* */
3317 /* <InOut> */
3318 /* face :: A handle to the source face object. */
3319 /* */
3320 /* <Input> */
3321 /* encoding :: A handle to the selected encoding. */
3322 /* */
3323 /* <Return> */
3324 /* FreeType error code. 0~means success. */
3325 /* */
3326 /* <Note> */
3327 /* This function returns an error if no charmap in the face */
3328 /* corresponds to the encoding queried here. */
3329 /* */
3330 /* Because many fonts contain more than a single cmap for Unicode */
3331 /* encoding, this function has some special code to select the one */
3332 /* that covers Unicode best (`best' in the sense that a UCS-4 cmap is */
3333 /* preferred to a UCS-2 cmap). It is thus preferable to */
3334 /* @FT_Set_Charmap in this case. */
3335 /* */
3336 FT_EXPORT( FT_Error )
3337 FT_Select_Charmap( FT_Face face,
3338 FT_Encoding encoding );
3339
3340
3341 /*************************************************************************/
3342 /* */
3343 /* <Function> */
3344 /* FT_Set_Charmap */
3345 /* */
3346 /* <Description> */
3347 /* Select a given charmap for character code to glyph index mapping. */
3348 /* */
3349 /* <InOut> */
3350 /* face :: A handle to the source face object. */
3351 /* */
3352 /* <Input> */
3353 /* charmap :: A handle to the selected charmap. */
3354 /* */
3355 /* <Return> */
3356 /* FreeType error code. 0~means success. */
3357 /* */
3358 /* <Note> */
3359 /* This function returns an error if the charmap is not part of */
3360 /* the face (i.e., if it is not listed in the `face->charmaps' */
3361 /* table). */
3362 /* */
3363 /* It also fails if a type~14 charmap is selected. */
3364 /* */
3365 FT_EXPORT( FT_Error )
3366 FT_Set_Charmap( FT_Face face,
3367 FT_CharMap charmap );
3368
3369
3370 /*************************************************************************
3371 *
3372 * @function:
3373 * FT_Get_Charmap_Index
3374 *
3375 * @description:
3376 * Retrieve index of a given charmap.
3377 *
3378 * @input:
3379 * charmap ::
3380 * A handle to a charmap.
3381 *
3382 * @return:
3383 * The index into the array of character maps within the face to which
3384 * `charmap' belongs. If an error occurs, -1 is returned.
3385 *
3386 */
3387 FT_EXPORT( FT_Int )
3388 FT_Get_Charmap_Index( FT_CharMap charmap );
3389
3390
3391 /*************************************************************************/
3392 /* */
3393 /* <Function> */
3394 /* FT_Get_Char_Index */
3395 /* */
3396 /* <Description> */
3397 /* Return the glyph index of a given character code. This function */
3398 /* uses a charmap object to do the mapping. */
3399 /* */
3400 /* <Input> */
3401 /* face :: A handle to the source face object. */
3402 /* */
3403 /* charcode :: The character code. */
3404 /* */
3405 /* <Return> */
3406 /* The glyph index. 0~means `undefined character code'. */
3407 /* */
3408 /* <Note> */
3409 /* If you use FreeType to manipulate the contents of font files */
3410 /* directly, be aware that the glyph index returned by this function */
3411 /* doesn't always correspond to the internal indices used within the */
3412 /* file. This is done to ensure that value~0 always corresponds to */
3413 /* the `missing glyph'. If the first glyph is not named `.notdef', */
3414 /* then for Type~1 and Type~42 fonts, `.notdef' will be moved into */
3415 /* the glyph ID~0 position, and whatever was there will be moved to */
3416 /* the position `.notdef' had. For Type~1 fonts, if there is no */
3417 /* `.notdef' glyph at all, then one will be created at index~0 and */
3418 /* whatever was there will be moved to the last index -- Type~42 */
3419 /* fonts are considered invalid under this condition. */
3420 /* */
3421 FT_EXPORT( FT_UInt )
3422 FT_Get_Char_Index( FT_Face face,
3423 FT_ULong charcode );
3424
3425
3426 /*************************************************************************/
3427 /* */
3428 /* <Function> */
3429 /* FT_Get_First_Char */
3430 /* */
3431 /* <Description> */
3432 /* This function is used to return the first character code in the */
3433 /* current charmap of a given face. It also returns the */
3434 /* corresponding glyph index. */
3435 /* */
3436 /* <Input> */
3437 /* face :: A handle to the source face object. */
3438 /* */
3439 /* <Output> */
3440 /* agindex :: Glyph index of first character code. 0~if charmap is */
3441 /* empty. */
3442 /* */
3443 /* <Return> */
3444 /* The charmap's first character code. */
3445 /* */
3446 /* <Note> */
3447 /* You should use this function with @FT_Get_Next_Char to be able to */
3448 /* parse all character codes available in a given charmap. The code */
3449 /* should look like this: */
3450 /* */
3451 /* { */
3452 /* FT_ULong charcode; */
3453 /* FT_UInt gindex; */
3454 /* */
3455 /* */
3456 /* charcode = FT_Get_First_Char( face, &gindex ); */
3457 /* while ( gindex != 0 ) */
3458 /* { */
3459 /* ... do something with (charcode,gindex) pair ... */
3460 /* */
3461 /* charcode = FT_Get_Next_Char( face, charcode, &gindex ); */
3462 /* } */
3463 /* } */
3464 /* */
3465 /* Be aware that character codes can have values up to 0xFFFFFFFF; */
3466 /* this might happen for non-Unicode or malformed cmaps. However, */
3467 /* even with regular Unicode encoding, so-called `last resort fonts' */
3468 /* (using SFNT cmap format 13, see function @FT_Get_CMap_Format) */
3469 /* normally have entries for all Unicode characters up to 0x1FFFFF, */
3470 /* which can cause *a lot* of iterations. */
3471 /* */
3472 /* Note that `*agindex' is set to~0 if the charmap is empty. The */
3473 /* result itself can be~0 in two cases: if the charmap is empty or */
3474 /* if the value~0 is the first valid character code. */
3475 /* */
3476 FT_EXPORT( FT_ULong )
3477 FT_Get_First_Char( FT_Face face,
3478 FT_UInt *agindex );
3479
3480
3481 /*************************************************************************/
3482 /* */
3483 /* <Function> */
3484 /* FT_Get_Next_Char */
3485 /* */
3486 /* <Description> */
3487 /* This function is used to return the next character code in the */
3488 /* current charmap of a given face following the value `char_code', */
3489 /* as well as the corresponding glyph index. */
3490 /* */
3491 /* <Input> */
3492 /* face :: A handle to the source face object. */
3493 /* char_code :: The starting character code. */
3494 /* */
3495 /* <Output> */
3496 /* agindex :: Glyph index of next character code. 0~if charmap */
3497 /* is empty. */
3498 /* */
3499 /* <Return> */
3500 /* The charmap's next character code. */
3501 /* */
3502 /* <Note> */
3503 /* You should use this function with @FT_Get_First_Char to walk */
3504 /* over all character codes available in a given charmap. See the */
3505 /* note for this function for a simple code example. */
3506 /* */
3507 /* Note that `*agindex' is set to~0 when there are no more codes in */
3508 /* the charmap. */
3509 /* */
3510 FT_EXPORT( FT_ULong )
3511 FT_Get_Next_Char( FT_Face face,
3512 FT_ULong char_code,
3513 FT_UInt *agindex );
3514
3515
3516 /*************************************************************************/
3517 /* */
3518 /* <Function> */
3519 /* FT_Get_Name_Index */
3520 /* */
3521 /* <Description> */
3522 /* Return the glyph index of a given glyph name. This function uses */
3523 /* driver specific objects to do the translation. */
3524 /* */
3525 /* <Input> */
3526 /* face :: A handle to the source face object. */
3527 /* */
3528 /* glyph_name :: The glyph name. */
3529 /* */
3530 /* <Return> */
3531 /* The glyph index. 0~means `undefined character code'. */
3532 /* */
3533 FT_EXPORT( FT_UInt )
3534 FT_Get_Name_Index( FT_Face face,
3535 FT_String* glyph_name );
3536
3537
3538 /*************************************************************************
3539 *
3540 * @macro:
3541 * FT_SUBGLYPH_FLAG_XXX
3542 *
3543 * @description:
3544 * A list of constants used to describe subglyphs. Please refer to the
3545 * TrueType specification for the meaning of the various flags.
3546 *
3547 * @values:
3548 * FT_SUBGLYPH_FLAG_ARGS_ARE_WORDS ::
3549 * FT_SUBGLYPH_FLAG_ARGS_ARE_XY_VALUES ::
3550 * FT_SUBGLYPH_FLAG_ROUND_XY_TO_GRID ::
3551 * FT_SUBGLYPH_FLAG_SCALE ::
3552 * FT_SUBGLYPH_FLAG_XY_SCALE ::
3553 * FT_SUBGLYPH_FLAG_2X2 ::
3554 * FT_SUBGLYPH_FLAG_USE_MY_METRICS ::
3555 *
3556 */
3557#define FT_SUBGLYPH_FLAG_ARGS_ARE_WORDS 1
3558#define FT_SUBGLYPH_FLAG_ARGS_ARE_XY_VALUES 2
3559#define FT_SUBGLYPH_FLAG_ROUND_XY_TO_GRID 4
3560#define FT_SUBGLYPH_FLAG_SCALE 8
3561#define FT_SUBGLYPH_FLAG_XY_SCALE 0x40
3562#define FT_SUBGLYPH_FLAG_2X2 0x80
3563#define FT_SUBGLYPH_FLAG_USE_MY_METRICS 0x200
3564
3565
3566 /*************************************************************************
3567 *
3568 * @func:
3569 * FT_Get_SubGlyph_Info
3570 *
3571 * @description:
3572 * Retrieve a description of a given subglyph. Only use it if
3573 * `glyph->format' is @FT_GLYPH_FORMAT_COMPOSITE; an error is
3574 * returned otherwise.
3575 *
3576 * @input:
3577 * glyph ::
3578 * The source glyph slot.
3579 *
3580 * sub_index ::
3581 * The index of the subglyph. Must be less than
3582 * `glyph->num_subglyphs'.
3583 *
3584 * @output:
3585 * p_index ::
3586 * The glyph index of the subglyph.
3587 *
3588 * p_flags ::
3589 * The subglyph flags, see @FT_SUBGLYPH_FLAG_XXX.
3590 *
3591 * p_arg1 ::
3592 * The subglyph's first argument (if any).
3593 *
3594 * p_arg2 ::
3595 * The subglyph's second argument (if any).
3596 *
3597 * p_transform ::
3598 * The subglyph transformation (if any).
3599 *
3600 * @return:
3601 * FreeType error code. 0~means success.
3602 *
3603 * @note:
3604 * The values of `*p_arg1', `*p_arg2', and `*p_transform' must be
3605 * interpreted depending on the flags returned in `*p_flags'. See the
3606 * TrueType specification for details.
3607 *
3608 */
3609 FT_EXPORT( FT_Error )
3610 FT_Get_SubGlyph_Info( FT_GlyphSlot glyph,
3611 FT_UInt sub_index,
3612 FT_Int *p_index,
3613 FT_UInt *p_flags,
3614 FT_Int *p_arg1,
3615 FT_Int *p_arg2,
3616 FT_Matrix *p_transform );
3617
3618
3619 /*************************************************************************/
3620 /* */
3621 /* <Enum> */
3622 /* FT_FSTYPE_XXX */
3623 /* */
3624 /* <Description> */
3625 /* A list of bit flags used in the `fsType' field of the OS/2 table */
3626 /* in a TrueType or OpenType font and the `FSType' entry in a */
3627 /* PostScript font. These bit flags are returned by */
3628 /* @FT_Get_FSType_Flags; they inform client applications of embedding */
3629 /* and subsetting restrictions associated with a font. */
3630 /* */
3631 /* See */
3632 /* http://www.adobe.com/content/dam/Adobe/en/devnet/acrobat/pdfs/FontPolicies.pdf */
3633 /* for more details. */
3634 /* */
3635 /* <Values> */
3636 /* FT_FSTYPE_INSTALLABLE_EMBEDDING :: */
3637 /* Fonts with no fsType bit set may be embedded and permanently */
3638 /* installed on the remote system by an application. */
3639 /* */
3640 /* FT_FSTYPE_RESTRICTED_LICENSE_EMBEDDING :: */
3641 /* Fonts that have only this bit set must not be modified, embedded */
3642 /* or exchanged in any manner without first obtaining permission of */
3643 /* the font software copyright owner. */
3644 /* */
3645 /* FT_FSTYPE_PREVIEW_AND_PRINT_EMBEDDING :: */
3646 /* If this bit is set, the font may be embedded and temporarily */
3647 /* loaded on the remote system. Documents containing Preview & */
3648 /* Print fonts must be opened `read-only'; no edits can be applied */
3649 /* to the document. */
3650 /* */
3651 /* FT_FSTYPE_EDITABLE_EMBEDDING :: */
3652 /* If this bit is set, the font may be embedded but must only be */
3653 /* installed temporarily on other systems. In contrast to Preview */
3654 /* & Print fonts, documents containing editable fonts may be opened */
3655 /* for reading, editing is permitted, and changes may be saved. */
3656 /* */
3657 /* FT_FSTYPE_NO_SUBSETTING :: */
3658 /* If this bit is set, the font may not be subsetted prior to */
3659 /* embedding. */
3660 /* */
3661 /* FT_FSTYPE_BITMAP_EMBEDDING_ONLY :: */
3662 /* If this bit is set, only bitmaps contained in the font may be */
3663 /* embedded; no outline data may be embedded. If there are no */
3664 /* bitmaps available in the font, then the font is unembeddable. */
3665 /* */
3666 /* <Note> */
3667 /* The flags are ORed together, thus more than a single value can be */
3668 /* returned. */
3669 /* */
3670 /* While the fsType flags can indicate that a font may be embedded, a */
3671 /* license with the font vendor may be separately required to use the */
3672 /* font in this way. */
3673 /* */
3674#define FT_FSTYPE_INSTALLABLE_EMBEDDING 0x0000
3675#define FT_FSTYPE_RESTRICTED_LICENSE_EMBEDDING 0x0002
3676#define FT_FSTYPE_PREVIEW_AND_PRINT_EMBEDDING 0x0004
3677#define FT_FSTYPE_EDITABLE_EMBEDDING 0x0008
3678#define FT_FSTYPE_NO_SUBSETTING 0x0100
3679#define FT_FSTYPE_BITMAP_EMBEDDING_ONLY 0x0200
3680
3681
3682 /*************************************************************************/
3683 /* */
3684 /* <Function> */
3685 /* FT_Get_FSType_Flags */
3686 /* */
3687 /* <Description> */
3688 /* Return the fsType flags for a font. */
3689 /* */
3690 /* <Input> */
3691 /* face :: A handle to the source face object. */
3692 /* */
3693 /* <Return> */
3694 /* The fsType flags, @FT_FSTYPE_XXX. */
3695 /* */
3696 /* <Note> */
3697 /* Use this function rather than directly reading the `fs_type' field */
3698 /* in the @PS_FontInfoRec structure, which is only guaranteed to */
3699 /* return the correct results for Type~1 fonts. */
3700 /* */
3701 /* <Since> */
3702 /* 2.3.8 */
3703 /* */
3704 FT_EXPORT( FT_UShort )
3705 FT_Get_FSType_Flags( FT_Face face );
3706
3707
3708 /*************************************************************************/
3709 /* */
3710 /* <Section> */
3711 /* glyph_variants */
3712 /* */
3713 /* <Title> */
3714 /* Glyph Variants */
3715 /* */
3716 /* <Abstract> */
3717 /* The FreeType~2 interface to Unicode Ideographic Variation */
3718 /* Sequences (IVS), using the SFNT cmap format~14. */
3719 /* */
3720 /* <Description> */
3721 /* Many CJK characters have variant forms. They are a sort of grey */
3722 /* area somewhere between being totally irrelevant and semantically */
3723 /* distinct; for this reason, the Unicode consortium decided to */
3724 /* introduce Ideographic Variation Sequences (IVS), consisting of a */
3725 /* Unicode base character and one of 240 variant selectors */
3726 /* (U+E0100-U+E01EF), instead of further extending the already huge */
3727 /* code range for CJK characters. */
3728 /* */
3729 /* An IVS is registered and unique; for further details please refer */
3730 /* to Unicode Technical Standard #37, the Ideographic Variation */
3731 /* Database: */
3732 /* */
3733 /* http://www.unicode.org/reports/tr37/ */
3734 /* */
3735 /* To date (November 2014), the character with the most variants is */
3736 /* U+9089, having 32 such IVS. */
3737 /* */
3738 /* Adobe and MS decided to support IVS with a new cmap subtable */
3739 /* (format~14). It is an odd subtable because it is not a mapping of */
3740 /* input code points to glyphs, but contains lists of all variants */
3741 /* supported by the font. */
3742 /* */
3743 /* A variant may be either `default' or `non-default'. A default */
3744 /* variant is the one you will get for that code point if you look it */
3745 /* up in the standard Unicode cmap. A non-default variant is a */
3746 /* different glyph. */
3747 /* */
3748 /*************************************************************************/
3749
3750
3751 /*************************************************************************/
3752 /* */
3753 /* <Function> */
3754 /* FT_Face_GetCharVariantIndex */
3755 /* */
3756 /* <Description> */
3757 /* Return the glyph index of a given character code as modified by */
3758 /* the variation selector. */
3759 /* */
3760 /* <Input> */
3761 /* face :: */
3762 /* A handle to the source face object. */
3763 /* */
3764 /* charcode :: */
3765 /* The character code point in Unicode. */
3766 /* */
3767 /* variantSelector :: */
3768 /* The Unicode code point of the variation selector. */
3769 /* */
3770 /* <Return> */
3771 /* The glyph index. 0~means either `undefined character code', or */
3772 /* `undefined selector code', or `no variation selector cmap */
3773 /* subtable', or `current CharMap is not Unicode'. */
3774 /* */
3775 /* <Note> */
3776 /* If you use FreeType to manipulate the contents of font files */
3777 /* directly, be aware that the glyph index returned by this function */
3778 /* doesn't always correspond to the internal indices used within */
3779 /* the file. This is done to ensure that value~0 always corresponds */
3780 /* to the `missing glyph'. */
3781 /* */
3782 /* This function is only meaningful if */
3783 /* a) the font has a variation selector cmap sub table, */
3784 /* and */
3785 /* b) the current charmap has a Unicode encoding. */
3786 /* */
3787 /* <Since> */
3788 /* 2.3.6 */
3789 /* */
3790 FT_EXPORT( FT_UInt )
3791 FT_Face_GetCharVariantIndex( FT_Face face,
3792 FT_ULong charcode,
3793 FT_ULong variantSelector );
3794
3795
3796 /*************************************************************************/
3797 /* */
3798 /* <Function> */
3799 /* FT_Face_GetCharVariantIsDefault */
3800 /* */
3801 /* <Description> */
3802 /* Check whether this variant of this Unicode character is the one to */
3803 /* be found in the `cmap'. */
3804 /* */
3805 /* <Input> */
3806 /* face :: */
3807 /* A handle to the source face object. */
3808 /* */
3809 /* charcode :: */
3810 /* The character codepoint in Unicode. */
3811 /* */
3812 /* variantSelector :: */
3813 /* The Unicode codepoint of the variation selector. */
3814 /* */
3815 /* <Return> */
3816 /* 1~if found in the standard (Unicode) cmap, 0~if found in the */
3817 /* variation selector cmap, or -1 if it is not a variant. */
3818 /* */
3819 /* <Note> */
3820 /* This function is only meaningful if the font has a variation */
3821 /* selector cmap subtable. */
3822 /* */
3823 /* <Since> */
3824 /* 2.3.6 */
3825 /* */
3826 FT_EXPORT( FT_Int )
3827 FT_Face_GetCharVariantIsDefault( FT_Face face,
3828 FT_ULong charcode,
3829 FT_ULong variantSelector );
3830
3831
3832 /*************************************************************************/
3833 /* */
3834 /* <Function> */
3835 /* FT_Face_GetVariantSelectors */
3836 /* */
3837 /* <Description> */
3838 /* Return a zero-terminated list of Unicode variant selectors found */
3839 /* in the font. */
3840 /* */
3841 /* <Input> */
3842 /* face :: */
3843 /* A handle to the source face object. */
3844 /* */
3845 /* <Return> */
3846 /* A pointer to an array of selector code points, or NULL if there is */
3847 /* no valid variant selector cmap subtable. */
3848 /* */
3849 /* <Note> */
3850 /* The last item in the array is~0; the array is owned by the */
3851 /* @FT_Face object but can be overwritten or released on the next */
3852 /* call to a FreeType function. */
3853 /* */
3854 /* <Since> */
3855 /* 2.3.6 */
3856 /* */
3857 FT_EXPORT( FT_UInt32* )
3858 FT_Face_GetVariantSelectors( FT_Face face );
3859
3860
3861 /*************************************************************************/
3862 /* */
3863 /* <Function> */
3864 /* FT_Face_GetVariantsOfChar */
3865 /* */
3866 /* <Description> */
3867 /* Return a zero-terminated list of Unicode variant selectors found */
3868 /* for the specified character code. */
3869 /* */
3870 /* <Input> */
3871 /* face :: */
3872 /* A handle to the source face object. */
3873 /* */
3874 /* charcode :: */
3875 /* The character codepoint in Unicode. */
3876 /* */
3877 /* <Return> */
3878 /* A pointer to an array of variant selector code points that are */
3879 /* active for the given character, or NULL if the corresponding list */
3880 /* is empty. */
3881 /* */
3882 /* <Note> */
3883 /* The last item in the array is~0; the array is owned by the */
3884 /* @FT_Face object but can be overwritten or released on the next */
3885 /* call to a FreeType function. */
3886 /* */
3887 /* <Since> */
3888 /* 2.3.6 */
3889 /* */
3890 FT_EXPORT( FT_UInt32* )
3891 FT_Face_GetVariantsOfChar( FT_Face face,
3892 FT_ULong charcode );
3893
3894
3895 /*************************************************************************/
3896 /* */
3897 /* <Function> */
3898 /* FT_Face_GetCharsOfVariant */
3899 /* */
3900 /* <Description> */
3901 /* Return a zero-terminated list of Unicode character codes found for */
3902 /* the specified variant selector. */
3903 /* */
3904 /* <Input> */
3905 /* face :: */
3906 /* A handle to the source face object. */
3907 /* */
3908 /* variantSelector :: */
3909 /* The variant selector code point in Unicode. */
3910 /* */
3911 /* <Return> */
3912 /* A list of all the code points that are specified by this selector */
3913 /* (both default and non-default codes are returned) or NULL if there */
3914 /* is no valid cmap or the variant selector is invalid. */
3915 /* */
3916 /* <Note> */
3917 /* The last item in the array is~0; the array is owned by the */
3918 /* @FT_Face object but can be overwritten or released on the next */
3919 /* call to a FreeType function. */
3920 /* */
3921 /* <Since> */
3922 /* 2.3.6 */
3923 /* */
3924 FT_EXPORT( FT_UInt32* )
3925 FT_Face_GetCharsOfVariant( FT_Face face,
3926 FT_ULong variantSelector );
3927
3928
3929 /*************************************************************************/
3930 /* */
3931 /* <Section> */
3932 /* computations */
3933 /* */
3934 /* <Title> */
3935 /* Computations */
3936 /* */
3937 /* <Abstract> */
3938 /* Crunching fixed numbers and vectors. */
3939 /* */
3940 /* <Description> */
3941 /* This section contains various functions used to perform */
3942 /* computations on 16.16 fixed-float numbers or 2d vectors. */
3943 /* */
3944 /* <Order> */
3945 /* FT_MulDiv */
3946 /* FT_MulFix */
3947 /* FT_DivFix */
3948 /* FT_RoundFix */
3949 /* FT_CeilFix */
3950 /* FT_FloorFix */
3951 /* FT_Vector_Transform */
3952 /* FT_Matrix_Multiply */
3953 /* FT_Matrix_Invert */
3954 /* */
3955 /*************************************************************************/
3956
3957
3958 /*************************************************************************/
3959 /* */
3960 /* <Function> */
3961 /* FT_MulDiv */
3962 /* */
3963 /* <Description> */
3964 /* A very simple function used to perform the computation `(a*b)/c' */
3965 /* with maximum accuracy (it uses a 64-bit intermediate integer */
3966 /* whenever necessary). */
3967 /* */
3968 /* This function isn't necessarily as fast as some processor specific */
3969 /* operations, but is at least completely portable. */
3970 /* */
3971 /* <Input> */
3972 /* a :: The first multiplier. */
3973 /* b :: The second multiplier. */
3974 /* c :: The divisor. */
3975 /* */
3976 /* <Return> */
3977 /* The result of `(a*b)/c'. This function never traps when trying to */
3978 /* divide by zero; it simply returns `MaxInt' or `MinInt' depending */
3979 /* on the signs of `a' and `b'. */
3980 /* */
3981 FT_EXPORT( FT_Long )
3982 FT_MulDiv( FT_Long a,
3983 FT_Long b,
3984 FT_Long c );
3985
3986
3987 /*************************************************************************/
3988 /* */
3989 /* <Function> */
3990 /* FT_MulFix */
3991 /* */
3992 /* <Description> */
3993 /* A very simple function used to perform the computation */
3994 /* `(a*b)/0x10000' with maximum accuracy. Most of the time this is */
3995 /* used to multiply a given value by a 16.16 fixed-point factor. */
3996 /* */
3997 /* <Input> */
3998 /* a :: The first multiplier. */
3999 /* b :: The second multiplier. Use a 16.16 factor here whenever */
4000 /* possible (see note below). */
4001 /* */
4002 /* <Return> */
4003 /* The result of `(a*b)/0x10000'. */
4004 /* */
4005 /* <Note> */
4006 /* This function has been optimized for the case where the absolute */
4007 /* value of `a' is less than 2048, and `b' is a 16.16 scaling factor. */
4008 /* As this happens mainly when scaling from notional units to */
4009 /* fractional pixels in FreeType, it resulted in noticeable speed */
4010 /* improvements between versions 2.x and 1.x. */
4011 /* */
4012 /* As a conclusion, always try to place a 16.16 factor as the */
4013 /* _second_ argument of this function; this can make a great */
4014 /* difference. */
4015 /* */
4016 FT_EXPORT( FT_Long )
4017 FT_MulFix( FT_Long a,
4018 FT_Long b );
4019
4020
4021 /*************************************************************************/
4022 /* */
4023 /* <Function> */
4024 /* FT_DivFix */
4025 /* */
4026 /* <Description> */
4027 /* A very simple function used to perform the computation */
4028 /* `(a*0x10000)/b' with maximum accuracy. Most of the time, this is */
4029 /* used to divide a given value by a 16.16 fixed-point factor. */
4030 /* */
4031 /* <Input> */
4032 /* a :: The numerator. */
4033 /* b :: The denominator. Use a 16.16 factor here. */
4034 /* */
4035 /* <Return> */
4036 /* The result of `(a*0x10000)/b'. */
4037 /* */
4038 FT_EXPORT( FT_Long )
4039 FT_DivFix( FT_Long a,
4040 FT_Long b );
4041
4042
4043 /*************************************************************************/
4044 /* */
4045 /* <Function> */
4046 /* FT_RoundFix */
4047 /* */
4048 /* <Description> */
4049 /* A very simple function used to round a 16.16 fixed number. */
4050 /* */
4051 /* <Input> */
4052 /* a :: The number to be rounded. */
4053 /* */
4054 /* <Return> */
4055 /* `a' rounded to nearest 16.16 fixed integer, halfway cases away */
4056 /* from zero. */
4057 /* */
4058 FT_EXPORT( FT_Fixed )
4059 FT_RoundFix( FT_Fixed a );
4060
4061
4062 /*************************************************************************/
4063 /* */
4064 /* <Function> */
4065 /* FT_CeilFix */
4066 /* */
4067 /* <Description> */
4068 /* A very simple function used to compute the ceiling function of a */
4069 /* 16.16 fixed number. */
4070 /* */
4071 /* <Input> */
4072 /* a :: The number for which the ceiling function is to be computed. */
4073 /* */
4074 /* <Return> */
4075 /* `a' rounded towards plus infinity. */
4076 /* */
4077 FT_EXPORT( FT_Fixed )
4078 FT_CeilFix( FT_Fixed a );
4079
4080
4081 /*************************************************************************/
4082 /* */
4083 /* <Function> */
4084 /* FT_FloorFix */
4085 /* */
4086 /* <Description> */
4087 /* A very simple function used to compute the floor function of a */
4088 /* 16.16 fixed number. */
4089 /* */
4090 /* <Input> */
4091 /* a :: The number for which the floor function is to be computed. */
4092 /* */
4093 /* <Return> */
4094 /* `a' rounded towards minus infinity. */
4095 /* */
4096 FT_EXPORT( FT_Fixed )
4097 FT_FloorFix( FT_Fixed a );
4098
4099
4100 /*************************************************************************/
4101 /* */
4102 /* <Function> */
4103 /* FT_Vector_Transform */
4104 /* */
4105 /* <Description> */
4106 /* Transform a single vector through a 2x2 matrix. */
4107 /* */
4108 /* <InOut> */
4109 /* vector :: The target vector to transform. */
4110 /* */
4111 /* <Input> */
4112 /* matrix :: A pointer to the source 2x2 matrix. */
4113 /* */
4114 /* <Note> */
4115 /* The result is undefined if either `vector' or `matrix' is invalid. */
4116 /* */
4117 FT_EXPORT( void )
4118 FT_Vector_Transform( FT_Vector* vec,
4119 const FT_Matrix* matrix );
4120
4121
4122 /*************************************************************************/
4123 /* */
4124 /* <Section> */
4125 /* version */
4126 /* */
4127 /* <Title> */
4128 /* FreeType Version */
4129 /* */
4130 /* <Abstract> */
4131 /* Functions and macros related to FreeType versions. */
4132 /* */
4133 /* <Description> */
4134 /* Note that those functions and macros are of limited use because */
4135 /* even a new release of FreeType with only documentation changes */
4136 /* increases the version number. */
4137 /* */
4138 /* <Order> */
4139 /* FT_Library_Version */
4140 /* */
4141 /* FREETYPE_MAJOR */
4142 /* FREETYPE_MINOR */
4143 /* FREETYPE_PATCH */
4144 /* */
4145 /* FT_Face_CheckTrueTypePatents */
4146 /* FT_Face_SetUnpatentedHinting */
4147 /* */
4148 /* FREETYPE_XXX */
4149 /* */
4150 /*************************************************************************/
4151
4152
4153 /*************************************************************************
4154 *
4155 * @enum:
4156 * FREETYPE_XXX
4157 *
4158 * @description:
4159 * These three macros identify the FreeType source code version.
4160 * Use @FT_Library_Version to access them at runtime.
4161 *
4162 * @values:
4163 * FREETYPE_MAJOR :: The major version number.
4164 * FREETYPE_MINOR :: The minor version number.
4165 * FREETYPE_PATCH :: The patch level.
4166 *
4167 * @note:
4168 * The version number of FreeType if built as a dynamic link library
4169 * with the `libtool' package is _not_ controlled by these three
4170 * macros.
4171 *
4172 */
4173#define FREETYPE_MAJOR 2
4174#define FREETYPE_MINOR 6
4175#define FREETYPE_PATCH 3
4176
4177
4178 /*************************************************************************/
4179 /* */
4180 /* <Function> */
4181 /* FT_Library_Version */
4182 /* */
4183 /* <Description> */
4184 /* Return the version of the FreeType library being used. This is */
4185 /* useful when dynamically linking to the library, since one cannot */
4186 /* use the macros @FREETYPE_MAJOR, @FREETYPE_MINOR, and */
4187 /* @FREETYPE_PATCH. */
4188 /* */
4189 /* <Input> */
4190 /* library :: A source library handle. */
4191 /* */
4192 /* <Output> */
4193 /* amajor :: The major version number. */
4194 /* */
4195 /* aminor :: The minor version number. */
4196 /* */
4197 /* apatch :: The patch version number. */
4198 /* */
4199 /* <Note> */
4200 /* The reason why this function takes a `library' argument is because */
4201 /* certain programs implement library initialization in a custom way */
4202 /* that doesn't use @FT_Init_FreeType. */
4203 /* */
4204 /* In such cases, the library version might not be available before */
4205 /* the library object has been created. */
4206 /* */
4207 FT_EXPORT( void )
4208 FT_Library_Version( FT_Library library,
4209 FT_Int *amajor,
4210 FT_Int *aminor,
4211 FT_Int *apatch );
4212
4213
4214 /*************************************************************************/
4215 /* */
4216 /* <Function> */
4217 /* FT_Face_CheckTrueTypePatents */
4218 /* */
4219 /* <Description> */
4220 /* Deprecated, does nothing. */
4221 /* */
4222 /* <Input> */
4223 /* face :: A face handle. */
4224 /* */
4225 /* <Return> */
4226 /* Always returns false. */
4227 /* */
4228 /* <Note> */
4229 /* Since May 2010, TrueType hinting is no longer patented. */
4230 /* */
4231 /* <Since> */
4232 /* 2.3.5 */
4233 /* */
4234 FT_EXPORT( FT_Bool )
4235 FT_Face_CheckTrueTypePatents( FT_Face face );
4236
4237
4238 /*************************************************************************/
4239 /* */
4240 /* <Function> */
4241 /* FT_Face_SetUnpatentedHinting */
4242 /* */
4243 /* <Description> */
4244 /* Deprecated, does nothing. */
4245 /* */
4246 /* <Input> */
4247 /* face :: A face handle. */
4248 /* */
4249 /* value :: New boolean setting. */
4250 /* */
4251 /* <Return> */
4252 /* Always returns false. */
4253 /* */
4254 /* <Note> */
4255 /* Since May 2010, TrueType hinting is no longer patented. */
4256 /* */
4257 /* <Since> */
4258 /* 2.3.5 */
4259 /* */
4260 FT_EXPORT( FT_Bool )
4261 FT_Face_SetUnpatentedHinting( FT_Face face,
4262 FT_Bool value );
4263
4264 /* */
4265
4266
4267FT_END_HEADER
4268
4269#endif /* FREETYPE_H_ */
4270
4271
4272/* END */
FT_BBox_
Definition ftimage.h:116
FT_Bitmap_
Definition ftimage.h:262
FT_Bitmap_Size_
Definition freetype.h:363
FT_CharMapRec_
Definition freetype.h:831
FT_FaceRec_
Definition freetype.h:1034
FT_Generic_
Definition fttypes.h:460
FT_Glyph_Metrics_
Definition freetype.h:309
FT_GlyphSlotRec_
Definition freetype.h:1745
FT_ListRec_
Definition fttypes.h:568
FT_Matrix_
Definition fttypes.h:386
FT_Open_Args_
Definition freetype.h:1965
FT_Outline_
Definition ftimage.h:335
FT_Parameter_
Definition freetype.h:1899
FT_Size_Metrics_
Definition freetype.h:1501
FT_Size_RequestRec_
Definition freetype.h:2411
FT_SizeRec_
Definition freetype.h:1536
FT_StreamRec_
Definition ftsystem.h:331
FT_Vector_
Definition ftimage.h:75
Generated by doxygen 1.12.0