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