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