/
freetype.h
5050 lines (4739 loc) · 168 KB
/
freetype.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
/****************************************************************************
*
* freetype.h
*
* FreeType high-level API and common types (specification only).
*
* Copyright (C) 1996-2022 by
* David Turner, Robert Wilhelm, and Werner Lemberg.
*
* This file is part of the FreeType project, and may only be used,
* modified, and distributed under the terms of the FreeType project
* license, LICENSE.TXT. By continuing to use, modify, or distribute
* this file you indicate that you have read the license and
* understand and accept it fully.
*
*/
#ifndef FREETYPE_H_
#define FREETYPE_H_
#include <ft2build.h>
#include FT_CONFIG_CONFIG_H
#include <freetype/fttypes.h>
#include <freetype/fterrors.h>
FT_BEGIN_HEADER
/**************************************************************************
*
* @section:
* preamble
*
* @title:
* Preamble
*
* @abstract:
* What FreeType is and isn't
*
* @description:
* FreeType is a library that provides access to glyphs in font files. It
* scales the glyph images and their metrics to a requested size, and it
* rasterizes the glyph images to produce pixel or subpixel alpha coverage
* bitmaps.
*
* Note that FreeType is _not_ a text layout engine. You have to use
* higher-level libraries like HarfBuzz, Pango, or ICU for that.
*
* Note also that FreeType does _not_ perform alpha blending or
* compositing the resulting bitmaps or pixmaps by itself. Use your
* favourite graphics library (for example, Cairo or Skia) to further
* process FreeType's output.
*
*/
/**************************************************************************
*
* @section:
* header_inclusion
*
* @title:
* FreeType's header inclusion scheme
*
* @abstract:
* How client applications should include FreeType header files.
*
* @description:
* To be as flexible as possible (and for historical reasons), you must
* load file `ft2build.h` first before other header files, for example
*
* ```
* #include <ft2build.h>
*
* #include <freetype/freetype.h>
* #include <freetype/ftoutln.h>
* ```
*/
/**************************************************************************
*
* @section:
* user_allocation
*
* @title:
* User allocation
*
* @abstract:
* How client applications should allocate FreeType data structures.
*
* @description:
* FreeType assumes that structures allocated by the user and passed as
* arguments are zeroed out except for the actual data. In other words,
* it is recommended to use `calloc` (or variants of it) instead of
* `malloc` for allocation.
*
*/
/*************************************************************************/
/*************************************************************************/
/* */
/* B A S I C T Y P E S */
/* */
/*************************************************************************/
/*************************************************************************/
/**************************************************************************
*
* @section:
* base_interface
*
* @title:
* Base Interface
*
* @abstract:
* The FreeType~2 base font interface.
*
* @description:
* This section describes the most important public high-level API
* functions of FreeType~2.
*
* @order:
* FT_Library
* FT_Face
* FT_Size
* FT_GlyphSlot
* FT_CharMap
* FT_Encoding
* FT_ENC_TAG
*
* FT_FaceRec
*
* FT_FACE_FLAG_SCALABLE
* FT_FACE_FLAG_FIXED_SIZES
* FT_FACE_FLAG_FIXED_WIDTH
* FT_FACE_FLAG_HORIZONTAL
* FT_FACE_FLAG_VERTICAL
* FT_FACE_FLAG_COLOR
* FT_FACE_FLAG_SFNT
* FT_FACE_FLAG_CID_KEYED
* FT_FACE_FLAG_TRICKY
* FT_FACE_FLAG_KERNING
* FT_FACE_FLAG_MULTIPLE_MASTERS
* FT_FACE_FLAG_VARIATION
* FT_FACE_FLAG_GLYPH_NAMES
* FT_FACE_FLAG_EXTERNAL_STREAM
* FT_FACE_FLAG_HINTER
* FT_FACE_FLAG_SVG
* FT_FACE_FLAG_SBIX
* FT_FACE_FLAG_SBIX_OVERLAY
*
* FT_HAS_HORIZONTAL
* FT_HAS_VERTICAL
* FT_HAS_KERNING
* FT_HAS_FIXED_SIZES
* FT_HAS_GLYPH_NAMES
* FT_HAS_COLOR
* FT_HAS_MULTIPLE_MASTERS
* FT_HAS_SVG
* FT_HAS_SBIX
* FT_HAS_SBIX_OVERLAY
*
* FT_IS_SFNT
* FT_IS_SCALABLE
* FT_IS_FIXED_WIDTH
* FT_IS_CID_KEYED
* FT_IS_TRICKY
* FT_IS_NAMED_INSTANCE
* FT_IS_VARIATION
*
* FT_STYLE_FLAG_BOLD
* FT_STYLE_FLAG_ITALIC
*
* FT_SizeRec
* FT_Size_Metrics
*
* FT_GlyphSlotRec
* FT_Glyph_Metrics
* FT_SubGlyph
*
* FT_Bitmap_Size
*
* FT_Init_FreeType
* FT_Done_FreeType
*
* FT_New_Face
* FT_Done_Face
* FT_Reference_Face
* FT_New_Memory_Face
* FT_Face_Properties
* FT_Open_Face
* FT_Open_Args
* FT_Parameter
* FT_Attach_File
* FT_Attach_Stream
*
* FT_Set_Char_Size
* FT_Set_Pixel_Sizes
* FT_Request_Size
* FT_Select_Size
* FT_Size_Request_Type
* FT_Size_RequestRec
* FT_Size_Request
* FT_Set_Transform
* FT_Get_Transform
* FT_Load_Glyph
* FT_Get_Char_Index
* FT_Get_First_Char
* FT_Get_Next_Char
* FT_Get_Name_Index
* FT_Load_Char
*
* FT_OPEN_MEMORY
* FT_OPEN_STREAM
* FT_OPEN_PATHNAME
* FT_OPEN_DRIVER
* FT_OPEN_PARAMS
*
* FT_LOAD_DEFAULT
* FT_LOAD_RENDER
* FT_LOAD_MONOCHROME
* FT_LOAD_LINEAR_DESIGN
* FT_LOAD_NO_SCALE
* FT_LOAD_NO_HINTING
* FT_LOAD_NO_BITMAP
* FT_LOAD_SBITS_ONLY
* FT_LOAD_NO_AUTOHINT
* FT_LOAD_COLOR
*
* FT_LOAD_VERTICAL_LAYOUT
* FT_LOAD_IGNORE_TRANSFORM
* FT_LOAD_FORCE_AUTOHINT
* FT_LOAD_NO_RECURSE
* FT_LOAD_PEDANTIC
*
* FT_LOAD_TARGET_NORMAL
* FT_LOAD_TARGET_LIGHT
* FT_LOAD_TARGET_MONO
* FT_LOAD_TARGET_LCD
* FT_LOAD_TARGET_LCD_V
*
* FT_LOAD_TARGET_MODE
*
* FT_Render_Glyph
* FT_Render_Mode
* FT_Get_Kerning
* FT_Kerning_Mode
* FT_Get_Track_Kerning
* FT_Get_Glyph_Name
* FT_Get_Postscript_Name
*
* FT_CharMapRec
* FT_Select_Charmap
* FT_Set_Charmap
* FT_Get_Charmap_Index
*
* FT_Get_FSType_Flags
* FT_Get_SubGlyph_Info
*
* FT_Face_Internal
* FT_Size_Internal
* FT_Slot_Internal
*
* FT_FACE_FLAG_XXX
* FT_STYLE_FLAG_XXX
* FT_OPEN_XXX
* FT_LOAD_XXX
* FT_LOAD_TARGET_XXX
* FT_SUBGLYPH_FLAG_XXX
* FT_FSTYPE_XXX
*
* FT_HAS_FAST_GLYPHS
*
*/
/**************************************************************************
*
* @struct:
* FT_Glyph_Metrics
*
* @description:
* A structure to model the metrics of a single glyph. The values are
* expressed in 26.6 fractional pixel format; if the flag
* @FT_LOAD_NO_SCALE has been used while loading the glyph, values are
* expressed in font units instead.
*
* @fields:
* width ::
* The glyph's width.
*
* height ::
* The glyph's height.
*
* horiBearingX ::
* Left side bearing for horizontal layout.
*
* horiBearingY ::
* Top side bearing for horizontal layout.
*
* horiAdvance ::
* Advance width for horizontal layout.
*
* vertBearingX ::
* Left side bearing for vertical layout.
*
* vertBearingY ::
* Top side bearing for vertical layout. Larger positive values mean
* further below the vertical glyph origin.
*
* vertAdvance ::
* Advance height for vertical layout. Positive values mean the glyph
* has a positive advance downward.
*
* @note:
* If not disabled with @FT_LOAD_NO_HINTING, the values represent
* dimensions of the hinted glyph (in case hinting is applicable).
*
* Stroking a glyph with an outside border does not increase
* `horiAdvance` or `vertAdvance`; you have to manually adjust these
* values to account for the added width and height.
*
* FreeType doesn't use the 'VORG' table data for CFF fonts because it
* doesn't have an interface to quickly retrieve the glyph height. The
* y~coordinate of the vertical origin can be simply computed as
* `vertBearingY + height` after loading a glyph.
*/
typedef struct FT_Glyph_Metrics_
{
FT_Pos width;
FT_Pos height;
FT_Pos horiBearingX;
FT_Pos horiBearingY;
FT_Pos horiAdvance;
FT_Pos vertBearingX;
FT_Pos vertBearingY;
FT_Pos vertAdvance;
} FT_Glyph_Metrics;
/**************************************************************************
*
* @struct:
* FT_Bitmap_Size
*
* @description:
* This structure models the metrics of a bitmap strike (i.e., a set of
* glyphs for a given point size and resolution) in a bitmap font. It is
* used for the `available_sizes` field of @FT_Face.
*
* @fields:
* height ::
* The vertical distance, in pixels, between two consecutive baselines.
* It is always positive.
*
* width ::
* The average width, in pixels, of all glyphs in the strike.
*
* size ::
* The nominal size of the strike in 26.6 fractional points. This
* field is not very useful.
*
* x_ppem ::
* The horizontal ppem (nominal width) in 26.6 fractional pixels.
*
* y_ppem ::
* The vertical ppem (nominal height) in 26.6 fractional pixels.
*
* @note:
* Windows FNT:
* The nominal size given in a FNT font is not reliable. If the driver
* finds it incorrect, it sets `size` to some calculated values, and
* `x_ppem` and `y_ppem` to the pixel width and height given in the
* font, respectively.
*
* TrueType embedded bitmaps:
* `size`, `width`, and `height` values are not contained in the bitmap
* strike itself. They are computed from the global font parameters.
*/
typedef struct FT_Bitmap_Size_
{
FT_Short height;
FT_Short width;
FT_Pos size;
FT_Pos x_ppem;
FT_Pos y_ppem;
} FT_Bitmap_Size;
/*************************************************************************/
/*************************************************************************/
/* */
/* O B J E C T C L A S S E S */
/* */
/*************************************************************************/
/*************************************************************************/
/**************************************************************************
*
* @type:
* FT_Library
*
* @description:
* A handle to a FreeType library instance. Each 'library' is completely
* independent from the others; it is the 'root' of a set of objects like
* fonts, faces, sizes, etc.
*
* It also embeds a memory manager (see @FT_Memory), as well as a
* scan-line converter object (see @FT_Raster).
*
* [Since 2.5.6] In multi-threaded applications it is easiest to use one
* `FT_Library` object per thread. In case this is too cumbersome, a
* single `FT_Library` object across threads is possible also, as long as
* a mutex lock is used around @FT_New_Face and @FT_Done_Face.
*
* @note:
* Library objects are normally created by @FT_Init_FreeType, and
* destroyed with @FT_Done_FreeType. If you need reference-counting
* (cf. @FT_Reference_Library), use @FT_New_Library and @FT_Done_Library.
*/
typedef struct FT_LibraryRec_ *FT_Library;
/**************************************************************************
*
* @section:
* module_management
*
*/
/**************************************************************************
*
* @type:
* FT_Module
*
* @description:
* A handle to a given FreeType module object. A module can be a font
* driver, a renderer, or anything else that provides services to the
* former.
*/
typedef struct FT_ModuleRec_* FT_Module;
/**************************************************************************
*
* @type:
* FT_Driver
*
* @description:
* A handle to a given FreeType font driver object. A font driver is a
* module capable of creating faces from font files.
*/
typedef struct FT_DriverRec_* FT_Driver;
/**************************************************************************
*
* @type:
* FT_Renderer
*
* @description:
* A handle to a given FreeType renderer. A renderer is a module in
* charge of converting a glyph's outline image to a bitmap. It supports
* a single glyph image format, and one or more target surface depths.
*/
typedef struct FT_RendererRec_* FT_Renderer;
/**************************************************************************
*
* @section:
* base_interface
*
*/
/**************************************************************************
*
* @type:
* FT_Face
*
* @description:
* A handle to a typographic face object. A face object models a given
* typeface, in a given style.
*
* @note:
* A face object also owns a single @FT_GlyphSlot object, as well as one
* or more @FT_Size objects.
*
* Use @FT_New_Face or @FT_Open_Face to create a new face object from a
* given filepath or a custom input stream.
*
* Use @FT_Done_Face to destroy it (along with its slot and sizes).
*
* An `FT_Face` object can only be safely used from one thread at a time.
* Similarly, creation and destruction of `FT_Face` with the same
* @FT_Library object can only be done from one thread at a time. On the
* other hand, functions like @FT_Load_Glyph and its siblings are
* thread-safe and do not need the lock to be held as long as the same
* `FT_Face` object is not used from multiple threads at the same time.
*
* @also:
* See @FT_FaceRec for the publicly accessible fields of a given face
* object.
*/
typedef struct FT_FaceRec_* FT_Face;
/**************************************************************************
*
* @type:
* FT_Size
*
* @description:
* A handle to an object that models a face scaled to a given character
* size.
*
* @note:
* An @FT_Face has one _active_ `FT_Size` object that is used by
* functions like @FT_Load_Glyph to determine the scaling transformation
* that in turn is used to load and hint glyphs and metrics.
*
* A newly created `FT_Size` object contains only meaningless zero values.
* You must use @FT_Set_Char_Size, @FT_Set_Pixel_Sizes, @FT_Request_Size
* or even @FT_Select_Size to change the content (i.e., the scaling
* values) of the active `FT_Size`. Otherwise, the scaling and hinting
* will not be performed.
*
* You can use @FT_New_Size to create additional size objects for a given
* @FT_Face, but they won't be used by other functions until you activate
* it through @FT_Activate_Size. Only one size can be activated at any
* given time per face.
*
* @also:
* See @FT_SizeRec for the publicly accessible fields of a given size
* object.
*/
typedef struct FT_SizeRec_* FT_Size;
/**************************************************************************
*
* @type:
* FT_GlyphSlot
*
* @description:
* A handle to a given 'glyph slot'. A slot is a container that can hold
* any of the glyphs contained in its parent face.
*
* In other words, each time you call @FT_Load_Glyph or @FT_Load_Char,
* the slot's content is erased by the new glyph data, i.e., the glyph's
* metrics, its image (bitmap or outline), and other control information.
*
* @also:
* See @FT_GlyphSlotRec for the publicly accessible glyph fields.
*/
typedef struct FT_GlyphSlotRec_* FT_GlyphSlot;
/**************************************************************************
*
* @type:
* FT_CharMap
*
* @description:
* A handle to a character map (usually abbreviated to 'charmap'). A
* charmap is used to translate character codes in a given encoding into
* glyph indexes for its parent's face. Some font formats may provide
* several charmaps per font.
*
* Each face object owns zero or more charmaps, but only one of them can
* be 'active', providing the data used by @FT_Get_Char_Index or
* @FT_Load_Char.
*
* The list of available charmaps in a face is available through the
* `face->num_charmaps` and `face->charmaps` fields of @FT_FaceRec.
*
* The currently active charmap is available as `face->charmap`. You
* should call @FT_Set_Charmap to change it.
*
* @note:
* When a new face is created (either through @FT_New_Face or
* @FT_Open_Face), the library looks for a Unicode charmap within the
* list and automatically activates it. If there is no Unicode charmap,
* FreeType doesn't set an 'active' charmap.
*
* @also:
* See @FT_CharMapRec for the publicly accessible fields of a given
* character map.
*/
typedef struct FT_CharMapRec_* FT_CharMap;
/**************************************************************************
*
* @macro:
* FT_ENC_TAG
*
* @description:
* This macro converts four-letter tags into an unsigned long. It is
* used to define 'encoding' identifiers (see @FT_Encoding).
*
* @note:
* Since many 16-bit compilers don't like 32-bit enumerations, you should
* redefine this macro in case of problems to something like this:
*
* ```
* #define FT_ENC_TAG( value, a, b, c, d ) value
* ```
*
* to get a simple enumeration without assigning special numbers.
*/
#ifndef FT_ENC_TAG
#define FT_ENC_TAG( value, a, b, c, d ) \
value = ( ( FT_STATIC_BYTE_CAST( FT_UInt32, a ) << 24 ) | \
( FT_STATIC_BYTE_CAST( FT_UInt32, b ) << 16 ) | \
( FT_STATIC_BYTE_CAST( FT_UInt32, c ) << 8 ) | \
FT_STATIC_BYTE_CAST( FT_UInt32, d ) )
#endif /* FT_ENC_TAG */
/**************************************************************************
*
* @enum:
* FT_Encoding
*
* @description:
* An enumeration to specify character sets supported by charmaps. Used
* in the @FT_Select_Charmap API function.
*
* @note:
* Despite the name, this enumeration lists specific character
* repertories (i.e., charsets), and not text encoding methods (e.g.,
* UTF-8, UTF-16, etc.).
*
* Other encodings might be defined in the future.
*
* @values:
* FT_ENCODING_NONE ::
* The encoding value~0 is reserved for all formats except BDF, PCF,
* and Windows FNT; see below for more information.
*
* FT_ENCODING_UNICODE ::
* The Unicode character set. This value covers all versions of the
* Unicode repertoire, including ASCII and Latin-1. Most fonts include
* a Unicode charmap, but not all of them.
*
* For example, if you want to access Unicode value U+1F028 (and the
* font contains it), use value 0x1F028 as the input value for
* @FT_Get_Char_Index.
*
* FT_ENCODING_MS_SYMBOL ::
* Microsoft Symbol encoding, used to encode mathematical symbols and
* wingdings. For more information, see
* 'https://www.microsoft.com/typography/otspec/recom.htm#non-standard-symbol-fonts',
* 'http://www.kostis.net/charsets/symbol.htm', and
* 'http://www.kostis.net/charsets/wingding.htm'.
*
* This encoding uses character codes from the PUA (Private Unicode
* Area) in the range U+F020-U+F0FF.
*
* FT_ENCODING_SJIS ::
* Shift JIS encoding for Japanese. More info at
* 'https://en.wikipedia.org/wiki/Shift_JIS'. See note on multi-byte
* encodings below.
*
* FT_ENCODING_PRC ::
* Corresponds to encoding systems mainly for Simplified Chinese as
* used in People's Republic of China (PRC). The encoding layout is
* based on GB~2312 and its supersets GBK and GB~18030.
*
* FT_ENCODING_BIG5 ::
* Corresponds to an encoding system for Traditional Chinese as used in
* Taiwan and Hong Kong.
*
* FT_ENCODING_WANSUNG ::
* Corresponds to the Korean encoding system known as Extended Wansung
* (MS Windows code page 949). For more information see
* 'https://www.unicode.org/Public/MAPPINGS/VENDORS/MICSFT/WindowsBestFit/bestfit949.txt'.
*
* FT_ENCODING_JOHAB ::
* The Korean standard character set (KS~C 5601-1992), which
* corresponds to MS Windows code page 1361. This character set
* includes all possible Hangul character combinations.
*
* FT_ENCODING_ADOBE_LATIN_1 ::
* Corresponds to a Latin-1 encoding as defined in a Type~1 PostScript
* font. It is limited to 256 character codes.
*
* FT_ENCODING_ADOBE_STANDARD ::
* Adobe Standard encoding, as found in Type~1, CFF, and OpenType/CFF
* fonts. It is limited to 256 character codes.
*
* FT_ENCODING_ADOBE_EXPERT ::
* Adobe Expert encoding, as found in Type~1, CFF, and OpenType/CFF
* fonts. It is limited to 256 character codes.
*
* FT_ENCODING_ADOBE_CUSTOM ::
* Corresponds to a custom encoding, as found in Type~1, CFF, and
* OpenType/CFF fonts. It is limited to 256 character codes.
*
* FT_ENCODING_APPLE_ROMAN ::
* Apple roman encoding. Many TrueType and OpenType fonts contain a
* charmap for this 8-bit encoding, since older versions of Mac OS are
* able to use it.
*
* FT_ENCODING_OLD_LATIN_2 ::
* This value is deprecated and was neither used nor reported by
* FreeType. Don't use or test for it.
*
* FT_ENCODING_MS_SJIS ::
* Same as FT_ENCODING_SJIS. Deprecated.
*
* FT_ENCODING_MS_GB2312 ::
* Same as FT_ENCODING_PRC. Deprecated.
*
* FT_ENCODING_MS_BIG5 ::
* Same as FT_ENCODING_BIG5. Deprecated.
*
* FT_ENCODING_MS_WANSUNG ::
* Same as FT_ENCODING_WANSUNG. Deprecated.
*
* FT_ENCODING_MS_JOHAB ::
* Same as FT_ENCODING_JOHAB. Deprecated.
*
* @note:
* When loading a font, FreeType makes a Unicode charmap active if
* possible (either if the font provides such a charmap, or if FreeType
* can synthesize one from PostScript glyph name dictionaries; in either
* case, the charmap is tagged with `FT_ENCODING_UNICODE`). If such a
* charmap is synthesized, it is placed at the first position of the
* charmap array.
*
* All other encodings are considered legacy and tagged only if
* explicitly defined in the font file. Otherwise, `FT_ENCODING_NONE` is
* used.
*
* `FT_ENCODING_NONE` is set by the BDF and PCF drivers if the charmap is
* neither Unicode nor ISO-8859-1 (otherwise it is set to
* `FT_ENCODING_UNICODE`). Use @FT_Get_BDF_Charset_ID to find out which
* encoding is really present. If, for example, the `cs_registry` field
* is 'KOI8' and the `cs_encoding` field is 'R', the font is encoded in
* KOI8-R.
*
* `FT_ENCODING_NONE` is always set (with a single exception) by the
* winfonts driver. Use @FT_Get_WinFNT_Header and examine the `charset`
* field of the @FT_WinFNT_HeaderRec structure to find out which encoding
* is really present. For example, @FT_WinFNT_ID_CP1251 (204) means
* Windows code page 1251 (for Russian).
*
* `FT_ENCODING_NONE` is set if `platform_id` is @TT_PLATFORM_MACINTOSH
* and `encoding_id` is not `TT_MAC_ID_ROMAN` (otherwise it is set to
* `FT_ENCODING_APPLE_ROMAN`).
*
* If `platform_id` is @TT_PLATFORM_MACINTOSH, use the function
* @FT_Get_CMap_Language_ID to query the Mac language ID that may be
* needed to be able to distinguish Apple encoding variants. See
*
* https://www.unicode.org/Public/MAPPINGS/VENDORS/APPLE/Readme.txt
*
* to get an idea how to do that. Basically, if the language ID is~0,
* don't use it, otherwise subtract 1 from the language ID. Then examine
* `encoding_id`. If, for example, `encoding_id` is `TT_MAC_ID_ROMAN`
* and the language ID (minus~1) is `TT_MAC_LANGID_GREEK`, it is the
* Greek encoding, not Roman. `TT_MAC_ID_ARABIC` with
* `TT_MAC_LANGID_FARSI` means the Farsi variant the Arabic encoding.
*/
typedef enum FT_Encoding_
{
FT_ENC_TAG( FT_ENCODING_NONE, 0, 0, 0, 0 ),
FT_ENC_TAG( FT_ENCODING_MS_SYMBOL, 's', 'y', 'm', 'b' ),
FT_ENC_TAG( FT_ENCODING_UNICODE, 'u', 'n', 'i', 'c' ),
FT_ENC_TAG( FT_ENCODING_SJIS, 's', 'j', 'i', 's' ),
FT_ENC_TAG( FT_ENCODING_PRC, 'g', 'b', ' ', ' ' ),
FT_ENC_TAG( FT_ENCODING_BIG5, 'b', 'i', 'g', '5' ),
FT_ENC_TAG( FT_ENCODING_WANSUNG, 'w', 'a', 'n', 's' ),
FT_ENC_TAG( FT_ENCODING_JOHAB, 'j', 'o', 'h', 'a' ),
/* for backward compatibility */
FT_ENCODING_GB2312 = FT_ENCODING_PRC,
FT_ENCODING_MS_SJIS = FT_ENCODING_SJIS,
FT_ENCODING_MS_GB2312 = FT_ENCODING_PRC,
FT_ENCODING_MS_BIG5 = FT_ENCODING_BIG5,
FT_ENCODING_MS_WANSUNG = FT_ENCODING_WANSUNG,
FT_ENCODING_MS_JOHAB = FT_ENCODING_JOHAB,
FT_ENC_TAG( FT_ENCODING_ADOBE_STANDARD, 'A', 'D', 'O', 'B' ),
FT_ENC_TAG( FT_ENCODING_ADOBE_EXPERT, 'A', 'D', 'B', 'E' ),
FT_ENC_TAG( FT_ENCODING_ADOBE_CUSTOM, 'A', 'D', 'B', 'C' ),
FT_ENC_TAG( FT_ENCODING_ADOBE_LATIN_1, 'l', 'a', 't', '1' ),
FT_ENC_TAG( FT_ENCODING_OLD_LATIN_2, 'l', 'a', 't', '2' ),
FT_ENC_TAG( FT_ENCODING_APPLE_ROMAN, 'a', 'r', 'm', 'n' )
} FT_Encoding;
/* these constants are deprecated; use the corresponding `FT_Encoding` */
/* values instead */
#define ft_encoding_none FT_ENCODING_NONE
#define ft_encoding_unicode FT_ENCODING_UNICODE
#define ft_encoding_symbol FT_ENCODING_MS_SYMBOL
#define ft_encoding_latin_1 FT_ENCODING_ADOBE_LATIN_1
#define ft_encoding_latin_2 FT_ENCODING_OLD_LATIN_2
#define ft_encoding_sjis FT_ENCODING_SJIS
#define ft_encoding_gb2312 FT_ENCODING_PRC
#define ft_encoding_big5 FT_ENCODING_BIG5
#define ft_encoding_wansung FT_ENCODING_WANSUNG
#define ft_encoding_johab FT_ENCODING_JOHAB
#define ft_encoding_adobe_standard FT_ENCODING_ADOBE_STANDARD
#define ft_encoding_adobe_expert FT_ENCODING_ADOBE_EXPERT
#define ft_encoding_adobe_custom FT_ENCODING_ADOBE_CUSTOM
#define ft_encoding_apple_roman FT_ENCODING_APPLE_ROMAN
/**************************************************************************
*
* @struct:
* FT_CharMapRec
*
* @description:
* The base charmap structure.
*
* @fields:
* face ::
* A handle to the parent face object.
*
* encoding ::
* An @FT_Encoding tag identifying the charmap. Use this with
* @FT_Select_Charmap.
*
* platform_id ::
* An ID number describing the platform for the following encoding ID.
* This comes directly from the TrueType specification and gets
* emulated for other formats.
*
* encoding_id ::
* A platform-specific encoding number. This also comes from the
* TrueType specification and gets emulated similarly.
*/
typedef struct FT_CharMapRec_
{
FT_Face face;
FT_Encoding encoding;
FT_UShort platform_id;
FT_UShort encoding_id;
} FT_CharMapRec;
/*************************************************************************/
/*************************************************************************/
/* */
/* B A S E O B J E C T C L A S S E S */
/* */
/*************************************************************************/
/*************************************************************************/
/**************************************************************************
*
* @type:
* FT_Face_Internal
*
* @description:
* An opaque handle to an `FT_Face_InternalRec` structure that models the
* private data of a given @FT_Face object.
*
* This structure might change between releases of FreeType~2 and is not
* generally available to client applications.
*/
typedef struct FT_Face_InternalRec_* FT_Face_Internal;
/**************************************************************************
*
* @struct:
* FT_FaceRec
*
* @description:
* FreeType root face class structure. A face object models a typeface
* in a font file.
*
* @fields:
* num_faces ::
* The number of faces in the font file. Some font formats can have
* multiple faces in a single font file.
*
* face_index ::
* This field holds two different values. Bits 0-15 are the index of
* the face in the font file (starting with value~0). They are set
* to~0 if there is only one face in the font file.
*
* [Since 2.6.1] Bits 16-30 are relevant to GX and OpenType variation
* fonts only, holding the named instance index for the current face
* index (starting with value~1; value~0 indicates font access without
* a named instance). For non-variation fonts, bits 16-30 are ignored.
* If we have the third named instance of face~4, say, `face_index` is
* set to 0x00030004.
*
* Bit 31 is always zero (this is, `face_index` is always a positive
* value).
*
* [Since 2.9] Changing the design coordinates with
* @FT_Set_Var_Design_Coordinates or @FT_Set_Var_Blend_Coordinates does
* not influence the named instance index value (only
* @FT_Set_Named_Instance does that).
*
* face_flags ::
* A set of bit flags that give important information about the face;
* see @FT_FACE_FLAG_XXX for the details.
*
* style_flags ::
* The lower 16~bits contain a set of bit flags indicating the style of
* the face; see @FT_STYLE_FLAG_XXX for the details.
*
* [Since 2.6.1] Bits 16-30 hold the number of named instances
* available for the current face if we have a GX or OpenType variation
* (sub)font. Bit 31 is always zero (this is, `style_flags` is always
* a positive value). Note that a variation font has always at least
* one named instance, namely the default instance.
*
* num_glyphs ::
* The number of glyphs in the face. If the face is scalable and has
* sbits (see `num_fixed_sizes`), it is set to the number of outline
* glyphs.
*
* For CID-keyed fonts (not in an SFNT wrapper) this value gives the
* highest CID used in the font.
*
* family_name ::
* The face's family name. This is an ASCII string, usually in
* English, that describes the typeface's family (like 'Times New
* Roman', 'Bodoni', 'Garamond', etc). This is a least common
* denominator used to list fonts. Some formats (TrueType & OpenType)
* provide localized and Unicode versions of this string. Applications
* should use the format-specific interface to access them. Can be
* `NULL` (e.g., in fonts embedded in a PDF file).
*
* In case the font doesn't provide a specific family name entry,
* FreeType tries to synthesize one, deriving it from other name
* entries.
*
* style_name ::
* The face's style name. This is an ASCII string, usually in English,
* that describes the typeface's style (like 'Italic', 'Bold',
* 'Condensed', etc). Not all font formats provide a style name, so
* this field is optional, and can be set to `NULL`. As for
* `family_name`, some formats provide localized and Unicode versions
* of this string. Applications should use the format-specific
* interface to access them.
*
* num_fixed_sizes ::
* The number of bitmap strikes in the face. Even if the face is
* scalable, there might still be bitmap strikes, which are called
* 'sbits' in that case.
*
* available_sizes ::
* An array of @FT_Bitmap_Size for all bitmap strikes in the face. It
* is set to `NULL` if there is no bitmap strike.
*
* Note that FreeType tries to sanitize the strike data since they are
* sometimes sloppy or incorrect, but this can easily fail.
*
* num_charmaps ::
* The number of charmaps in the face.
*
* charmaps ::
* An array of the charmaps of the face.
*
* generic ::
* A field reserved for client uses. See the @FT_Generic type
* description.
*
* bbox ::
* The font bounding box. Coordinates are expressed in font units (see
* `units_per_EM`). The box is large enough to contain any glyph from
* the font. Thus, `bbox.yMax` can be seen as the 'maximum ascender',
* and `bbox.yMin` as the 'minimum descender'. Only relevant for
* scalable formats.