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