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
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
|
The FreeType Engine
Core Library Reference
-----------------------------------
Table of Contents:
Introduction
I. Types
II. Functions
III. Error codes
--------------------
Introduction
============
This reference presents the types, functions, and error codes
defined in the high-level API header file `freetype.h'. Note that
all symbols defined in this file are prefixed by `TT_' to avoid
conflict of names with other packages at link time.
The reference for extensions of the FreeType library can be found
in the file `apirefx.txt'.
--------------------------------------------------------------------
--------------------------------------------------------------------
I. Types
========
Here is the list of all types defined in the core FreeType API.
Their exact definition can be found in the file `freetype.h' which
should be included in every client application.
TT_Bool
Can be either non-zero (true) or zero (false).
..................................................................
TT_Fixed
A signed 16.16 fixed float integer type used to specify
transform coefficients and other important data.
..................................................................
TT_FWord
A signed 16-bit type used to express a distance measured in the
font's original EM units. These are also called `FUnits' in the
TrueType specification.
..................................................................
TT_UFWord
An unsigned 16-bit type.
..................................................................
TT_String
TT_Char
TT_Byte
These types represent various 8-bit integer values (for strings,
signed, and unsigned values, respectively).
..................................................................
TT_Short
TT_UShort
TT_Long
TT_ULong
These four types are aliases for 16-bit integer (signed and
unsigned) and 32-bit integer types (signed and unsigned).
..................................................................
TT_Int
A signed type, either 16-bit or 32-bit, whichever is the most
efficient for the target platform.
..................................................................
TT_F2Dot14
A 2.14 fixed float integer type used for unary vectors and some
scaling coefficients. Its layout is:
s : 1 -- sign bit
m : 1 -- mantissa bit
f : 14 -- unsigned fractional value
where `s:m' denotes a 2-bit signed integer value to which the
positive fractional part `f' should always be added.
..................................................................
TT_F26Dot6
A 26.6 fixed float integer format used to define fractional
pixel coordinates. Here, 1 unit = 1/64 pixel.
..................................................................
TT_Pos
This type is used to store point coordinates, either in
fractional pixels (26.6 fixed floats) or in EM units (simple
integers).
The interpretation of the value depends on the context. For
example, all distances relative to a scaled glyph are expressed
in fractional pixels (including bearings, advances, etc).
However, the same distances are measured in notional font units
when the glyph has been loaded unscaled.
..................................................................
TT_UnitVector
A simple structure used to store a unit vector. The vector's
coordinates are expressed in fixed float format (2.14).
struct
{
TT_F2Dot14 x;
TT_F2Dot14 y;
}
..................................................................
TT_Vector
A simple structure used to store a single vector. Its
coordinates are expressed in fixed float format (26.6).
struct
{
TT_F26Dot6 x;
TT_F26Dot6 y;
}
..................................................................
TT_Matrix
A simple structure used to store a single 2x2 matrix. Its
coefficients are expressed in 16.16 fixed float format. This
matrix is used to perform linear transformations on the glyph
outline, such as slanting or rotation.
struct
{
TT_Fixed xx, xy;
TT_Fixed yx, yy;
};
The computation performed is:
x' = xx * x + xy * y
y' = yx * x + yy * y
..................................................................
TT_BBox
A simple type to hold a glyph's bounding box. Used by the
TT_Get_Outline_BBox() API.
struct
{
TT_Pos xMin, yMin;
TT_Pos xMax, yMax;
}
..................................................................
TT_Outline
Outlines are represented from now on as a class in itself, with
their own API.
This structure is used to describe a vectorial glyph
representation to the rasterizer. It consists of several fields
as described below. Note however that:
***** THIS STRUCTURE MAY CHANGE IN THE FUTURE. We thus
***** encourage you to use the outlines APIs described below to
***** process your outlines i.e., create/copy/translate/
***** transform them, as well as rendering bitmaps and pixmaps.
***** THE STRUCTURE CHANGED BETWEEN 1.0 and 1.1!
Now that you have been warned, the fields are:
- An array of points:
The `n_points' field gives the number of points in the
outline, while their coordinates are found in the single
vector array called `points'. The `flags' array holds a flag
for each point indicating its type.
Currently, only the first bit (bit 0, the least significant
bit) of each byte is meaningful to the rasterizer. If set, it
indicates that the point is _on_ the curve. If not set, the
point is said to be _off_ the curve. It is then a Bezier
control point.
For more information about point states, read the TrueType
specification or the scan-line documentation `raster.txt'.
- An array of contours end-point indices:
The `n_contours' field gives the number of contours, while the
`contours' array holds the indices of each contour's last
point. Note that the first contour always begins at point 0.
Hence, `contours[0]' holds the index of the last point of the
first contour. The second contour starts at point number
`contours[0]+1', and ends at point number `contours[1]'.
** IMPORTANT NOTE: **
*********************
The last table entry _must_ always give the total number of
points used to draw the contours, i.e.:
contours[n_contours - 1] == n_points
If this value is greater than `n_points' when calling the
scan-line converter, the component will immediately return
an error (TT_Err_Too_Many_Points). If the value is smaller,
only the points contained in the described contours will be
used in the conversion process.
- An owner field:
This flag should **NEVER** be changed by the user. It
indicates whether the pointer fields own the arrays they refer
to (when the flag is set), or if they simply alias them (flag
unset).
- A high precision flag:
If this boolean is set (i.e. not zero), the scan-line
converter uses a higher precision to compute segment and
Bezier coordinates (more precisely, it uses 1/1024 precision,
instead of the normal 1/64). This is of course slower but can
be important for glyphs rendered at small sizes.
- A second pass flag:
If this boolean is set, the scan-line converter performs a
second sweep on the bitmap/pixmap to detect vertical drop-out.
Only horizontal drop-outs are detected in the first pass.
This is slower, but important for glyphs rendered at small
sizes.
- A dropout mode:
Used to specify which method applies for drop-out control
(also called `continuity testing' in other environments). The
mode value must be one of the values defined by the TrueType
specification.
The more recent modes 4 and 5 introduced in the newest
TrueType specification (Version 1.66) are fully supported.
An invalid value (i.e., not 0, 1, 2, 4, or 5) is taken as no
dropout control (equivalent to mode 0).
NOTE 1:
The outline returned by TT_Get_Glyph_Outline() only alias the
data that is part of a glyph container (see below). However,
it is possible to create and process your own outlines with
the new API functions TT_New_Outline(), TT_Done_Outline(),
TT_Copy_Outline(), TT_Translate_Outline(), etc.
TT_Done_Outline() will only discard an outline's array if it
owns them.
NOTE 2:
The outlines created by TT_New_Outline() are _not_ released by
the engine while executing TT_Done_FreeType(), they must be
explicitly discarded by the user who has created them!
NOTE 3:
The glyph loader sets the fields `high_precision',
`dropout_mode', and `second_pass' automatically.
NOTE 4:
This structure was called TT_Glyph_Outline in beta versions of
FreeType.
..................................................................
TT_Glyph_Metrics
A structure used to return simple glyph metrics, applicable for
either horizontal or vertical layout. The values are expressed
in fractional pixels (26.6 format) if scaling was active,
otherwise in FUnits.
The main idea was to accomodate vertical text layouts by
eradicating the two explicit `leftSideBearing' and
`advanceWidth' names.
The interpretation of the fields varies with the text layout:
bearingX: Also known as the `left side bearing'. In
horizontal metrics, this value gives the horizontal
distance from the pen position to the glyph's bbox
xmin, otherwise it specifies the vertical distance.
bearingY: Also known as the `top side bearing', this is the
vertical distance from the baseline to the glyph's
bbox ymax in horizontal metrics, otherwise the
horizontal distance.
struct
{
TT_BBox bbox; /* the glyph's bbox */
TT_Pos bearingX; /* left-side bearing */
TT_Pos bearingY; /* top-side bearing */
TT_Pos advance; /* advance width or height */
};
** IMPORTANT NOTE **
Because of the conventions inherent to the TrueType engine,
the outlines generated at glyph-load time are all placed so
that the pen is at position (0,0). This means that it is not
necessary to increase the pen position by `bearingX' and/or
`bearingY' before writing a glyph. Text output can be
performed with simple lines such as:
for (glyphs in text)
{
TT_Load_Glyph( ... );
TT_Get_Glyph_Outline( glyph, &outline );
TT_Translate_Outline( outline,
cur_pos_x * 64, cur_pos_y * 64 );
TT_Get_Outline_Bitmap( outline, bitmap );
/* blit bitmap to surface */
cur_pos_x += (metrics.advance + 32) / 64
}
For an example see the file `test/ftstring.c'.
NOTE 2:
This structure has changed from the beta version of FreeType.
NOTE 3:
FreeType only implements TT_Get_Glyph_Metrics() to return
horizontal metrics. For extracting vertical metrics you
should use TT_Get_Glyph_Big_Metrics().
..................................................................
TT_Big_Glyph_Metrics
This structure is used to return the metrics of a glyph for both
horizontal and vertical layout.
The `linearXXX' fields represent unhinted scaled metrics values.
They can be useful for applications which need to compute device
independent placement of glyphs. Applying these metrics to
hinted glyphs will in most cases ruin the grid fitting performed
by the bytecode interpreter.
struct
{
TT_BBox bbox; /* the glyph's bounding box */
TT_Pos horiBearingX; /* horizontal left-side bearing */
TT_Pos horiBearingY; /* horizontal top-side bearing */
TT_Pos vertBearingX; /* vertical left-side bearing */
TT_Pos vertBearingY; /* vertical top-side bearing */
TT_Pos horiAdvance; /* horizontal advance */
TT_Pos vertAdvance; /* vertical advance */
TT_Pos linearHoriBearingX; /* lin. scaled hor. lsb. */
TT_Pos linearHoriAdvance; /* lin. scaled hor. adv. */
TT_Pos linearVertBearingY; /* lin. scaled vert. tsb. */
TT_Pos linearVertAdvance; /* lin. scaled vert. adv. */
}
..................................................................
TT_Instance_Metrics
A structure used to return instance (point size) metrics.
struct
{
int pointSize;
/* point size in points (1 point = 1/72 inch) */
TT_UShort x_ppem; /* horizontal pixels per EM square */
TT_UShort y_ppem; /* vertical pixels per EM square */
TT_Fixed x_scale; /* 16.16 scale for EM -> frac pixels */
TT_Fixed y_scale; /* 16.16 scale for EM -> frac pixels */
TT_UShort x_resolution; /* device hor. res. in dpi */
TT_UShort y_resolution; /* device vert. res. in dpi */
};
The fields `x_scale' and `y_scale' can be used by clients to
convert notional units (in funits) in fractional pixels (in 26.6
fixed float format), e.g.:
TT_FUnit em_distance;
TT_F26Dot6 frac_distance;
TT_Fixed x_scale;
frac_distance = (em_distance * x_scale) / 0x10000;
..................................................................
TT_Raster_Map
This structure is used to specify a target bitmap (or pixmap)
for the scan-line converter. It _must_ be set up by the client
application.
- The `rows' field contains the total number of rows in the
bitmap.
- The `width' field gives the number of pixels per row (a bit or
a byte, depending on the map's nature).
- The `cols' field gives the number of columns, i.e. bytes,
taken by each row in the map buffer.
** IMPORTANT: ** The `cols' field must be a multiple of 4 for
pixmaps!
Usually, its value should be `(width+7)/8' for bitmaps, and
`(width+3) & -4' for pixmaps.
- The `flow' field gives the map's vertical orientation.
If the first bytes of the bitmap buffer pertain to its upper
row, the flow is said to be going `down' and the field should
take the value `TT_Flow_Down', otherwise the flow is going
`up', and the value is `TT_Flow_Up'.
To cite an example, the PC video modes use a `down' flow,
where the first VRAM byte corresponds to the upper and
leftmost corner of the screen.
- The `bitmap' field is a typeless pointer to the map's buffer.
- The `size' field contains the buffer's size in bytes. It is
usually computed as follows:
size = rows * cols;
NOTE 1:
For bitmaps, the leftmost-pixel is related to the highest
(i.e. most significant) bit of its byte. There is currently
no support for the opposite convention found in some systems.
(It can be easily added if you really need it, just ask the
development team.)
struct
{
int rows; /* number of rows */
int cols; /* number of columns (bytes) per row */
int width; /* number of pixels per line */
int flow; /* bitmap orientation */
void* bitmap; /* bit/pixmap buffer */
long size; /* bit/pixmap size in bytes */
} TT_Raster_Map;
NOTE 2:
TT_Get_Outline_Bitmap() resp. TT_Get_Glyph_Bitmap() are used
to render bitmaps into a TT_Raster_Map. The convention used
is 0 for the background, and 1 for the foreground. The glyph
is simply `or-ed' to the bitmap buffer.
NOTE 3:
TT_Get_Outline_Pixmap() and TT_Get_Glyph_Pixmap() are used to
render pixmaps into a TT_Raster_Map. Note that pixels are
drawn in spans of 4 successive bytes, only if needed. This
means that you must ALWAYS pass a clean pixmap buffer to these
functions. Otherwise, garbage could accumulate!
..................................................................
TT_Header
This structure is used to hold the font's header. Its layout
and meaning are defined in the TrueType specification, in the
`head' section.
..................................................................
TT_Horizontal_Header
This structure is used to hold the font's horizontal header.
Its layout and meaning are defined in the TrueType
specification, in the `hhead' section.
..................................................................
TT_OS2
This structure is used to hold the font's OS/2 table. Its
layout and meaning are defined in the TrueType specification, in
the `OS/2' section.
Note that since FreeType 1.3, we support fonts without an OS/2
table (mainly old but popular Mac fonts). In this case, the
table's `version' field will be set to 0xFFFF by the loader, and
all other fields will be zeroed.
..................................................................
TT_Postscript
This structure is used to hold the font's PostScript table. Its
layout and meaning are defined in the TrueType specification, in
the `post' section.
..................................................................
TT_Hdmx
This structure is used to hold the font's horizontal device
metrics. Its layout and meaning are defined in the in the
`hdmx' section of the TrueType specification.
..................................................................
TT_Face_Properties
This structure is used to return an opened face's properties.
These are:
- The total number of glyphs in the font, given by the field
`num_Glyphs'.
- The maximum number of points for the font's glyphs. This
value is used to allocate the points tables of a glyph
container's outline. It can be fairly large (like 256 points
for Roman fonts).
- The maximum number of contours for the font's glyphs. This
value is used to allocate the contours tables of a glyph
container's outline. It can be fairly large (over 16, even in
Roman fonts).
- The number of character mappings and name records within the
font. These values can still be retrieved through the APIs
TT_Get_CharMapCount() and TT_Get_Num_Names(), though these
have been _seriously_ deprecated.
- The number of associated faces. This number is always 1 for a
normal TrueType font file. However, when the face object was
opened from a TrueType collection, it contains the total
number of embedded fonts.
- Pointers to the face's header and horizontal header, the OS/2
and PostScript tables, and the horizontal device metrics.
struct
{
TT_UShort num_Glyphs; /* number of glyphs in face */
TT_UShort max_Points; /* max. numb. of points in a glyph */
TT_Short max_Contours;
/* maximum number of contours in a glyph */
TT_ULong num_Faces;
/* 1 for normal TrueType files resp. */
/* the number of embedded faces for TT */
/* collections */
TT_Header* header; /* TrueType header table */
TT_Horizontal_Header* horizontal;
/* TrueType horizontal header */
TT_Vertical_Header* vertical;
/* TrueType vertical header */
TT_OS2* os2; /* TrueType OS/2 table */
TT_Postscript* postscript;
/* TrueType PostScript table */
TT_Hdmx* hdmx; /* TrueType hdmx table */
} TT_Face_Properties;
- Note that the `vertical' field is set to NULL if the font file
does not contain any vertical metrics.
- Note also that since version 1.3 we support font files without
an OS/2 table. See the definition of TT_OS2 for more details.
..................................................................
TT_Stream
This handle type defines a stream used to access a font file's
data. A client application should never deal with streams
directly, but some engine extensions need it to support more
advanced features like sbit support.
..................................................................
TT_Face
This type defines a handle used to reference a face object. The
objects are never accessed directly by a client application; it
can only obtain handles to new objects, and use them to query
specific information or processes.
See also:
TT_Open_Face(), TT_Open_Collection(), TT_Close_Face(),
TT_Get_Face_Properties(), etc.
..................................................................
TT_Instance
This type defines a handle used to reference an instance object
(also called a `pointsize' in other type engines). An instance
is always created from a valid face object, and is destroyed
with it by the engine.
See also:
TT_New_Instance(), TT_Done_Instance(),
TT_Set_Instance_CharSizes(), TT_Set_Instance_Resolutions(),
etc.
..................................................................
TT_Glyph
This type defines a handle used to reference a glyph container
object. A glyph container is an object owning tables sized to
the font's maximum profile to hold any glyph of a given font
file.
It contains an outline, some metrics, as well as some data
related to the way it should be processed by the scan-line
converter.
Note that a glyph container doesn't contain any bitmap or
pixmap!
See also:
TT_New_Glyph(), TT_Done_Glyph(), TT_Load_Glyph(),
TT_Get_Glyph_Metrics(), TT_Get_Glyph_Big_Metrics(),
TT_Get_Glyph_Outline(), TT_Get_Glyph_Bitmap(),
TT_Get_Glyph_Pixmap()
..................................................................
TT_CharMap
This type defines a handle used to reference a charMap object.
A charMap is an object owning the tables needed to perform the
mapping from characters code to glyphs numbers. A charMap is
always created from a valid face object, and is destroyed with
it by the engine.
See also:
TT_Get_CharMap(), TT_Char_Index().
..................................................................
TT_Error
This is the type of all error codes returned by the API. Nearly
all functions return an error code, set to 0 in case of success.
A list of all error codes is given in section III.
..................................................................
TT_Engine
For the sake of re-entrancy it is possible to distinguish
`engines' to separate several running instances of the library.
For example, it could be used as a DLL shared by several client
applications.
Each client program must begin by creating its own engine,
through a call to TT_Init_FreeType(). The engine must also be
passed as the first argument of the following functions:
TT_Open_Face()
TT_Open_Collection()
TT_Set_Raster_Gray_Palette()
TT_Get_Outline_Bitmap()
TT_Get_Outline_Pixmap()
TT_Done_FreeType()
Note that any FreeType object pertains to one single engine
(there is no sharing). Closing an engine with
TT_Done_FreeType() will delete all the objects that have been
allocated within its instance.
--------------------------------------------------------------------
--------------------------------------------------------------------
II. Functions
=============
Here is a list of the core library's API.
NOTE:
A function's default result is an error code of type TT_Error; a
list of error codes is given in section III below.
Some functions return other types, in which case the result type
is documented with its description.
..................................................................
TT_FreeType_Version( int* major, int* minor );
Queries the major and minor version of the library.
..................................................................
TT_Init_FreeType( TT_Engine* engine );
Creates and initializes a new engine. Returns a handle to the
engine in the `*engine' variable.
This call must be performed before any other function of
FreeType is invoked. The engine handle must be passed to the
following functions:
TT_Open_Face()
TT_Open_Collection()
TT_Set_Raster_Gray_Palette()
TT_Done_FreeType()
..................................................................
TT_Done_FreeType( TT_Engine engine );
Finalizes and destroys an engine. This call destroys _all_
objects that were previously created and used with the engine.
..................................................................
TT_Open_Face( TT_Engine engine,
TT_Text* fontPathName,
TT_Face* face );
This call opens a font file, located by `fontPathName', and
returns a handle to the newly corresponding face object in the
handle `*face'. The object is part of the `engine' instance.
Example:
error = TT_Open_Face( engine, "c:\ttf\wingding.ttf", &face );
if ( error )
fprintf( stderr, "Could not open face.\n" );
NOTE 1:
The font file can be a TrueType collection; in this case, the
engine will always open the first embedded font found in the
file.
NOTE 2:
`TT_Text' is usually defined as `char' by a typedef
declaration. It may be a 16-bit quantity (or even wider) for
some operating systems; see ttconfig.h for details.
..................................................................
TT_Open_Collection( TT_Engine engine,
TT_Text* collectionPathName,
TT_ULong fontIndex,
TT_Face* face );
This call opens one of the fonts found in a TrueType collection.
The font is selected through the `fontIndex' argument. The
first font has index 0.
Note that to know a collection's number of embedded fonts,
you will have to:
1 - open the first collection font with TT_Open_Face().
2 - query the face's properties through
TT_Get_Face_Properties().
The number of embedded faces is then `properties->num_Faces'.
Example:
TT_Face face;
TT_Face_Properties properties;
/* Open first embedded collection font */
error = TT_Open_Face( engine, "c:\ttf\sample.ttc", &face );
if ( error ) { ...error... }
/* Get face properties */
error = TT_Get_Face_Properties( face, &properties );
if ( error ) { ...error... }
printf( "There are %d fonts in this collection.\n",
properties->num_Faces );
TT_Close_Face( face );
/* Open second font in collection */
error = TT_Open_Collection( engine, "c:\ttf\sample.ttc", 1,
&face );
if ( error ) { ...error... }
NOTE 1:
If the file isn't a collection, `fontIndex' must be zero.
Otherwise, an error will be returned.
NOTE 2:
`TT_Text' is usually defined as `char' by a typedef
declaration. It may be a 16-bit quantity (or even wider) for
some operating systems; see ttconfig.h for details.
..................................................................
TT_Set_Raster_Gray_Palette( TT_Engine engine,
TT_Byte* palette );
Sets the gray-level palette for an engine. The palette is used
to create pixmaps through the TT_Get_Glyph_Pixmap() function.
It is an array of five bytes, following the convention:
palette[0] = background (white)
palette[1] = light
palette[2] = medium
palette[3] = dark
palette[4] = foreground (black)
..................................................................
TT_Get_Face_Properties( TT_Face face,
TT_Face_Properties* properties );
Returns the `face' object's `*properties'. This structure
contains various data like the total number of glyphs and
pointers to some mandatory TrueType tables.
See the definition of TT_Face_Properties in section I for more
details.
Note that since version 1.3, FreeType supports fonts with no
OS/2 table, like many old Mac fonts. See the definition of
TT_OS2 for more details.
..................................................................
TT_Get_Face_Metrics( TT_Face face,
TT_UShort firstGlyph,
TT_UShort lastGlyph,
TT_Short* leftBearings,
TT_UShort* widths,
TT_Short* topBearings,
TT_UShort* heights );
This function returns the original horizontal AND vertical
metrics for a given face `face' and a given glyph range specified
by `firstGlyph' and `lastGlyph' as found in the `hmtx' and `vmtx'
tables. These are the glyphs' left-side bearings (in
`leftBearings') and horizontal advance widths (in `widths'), as
well as top-side bearings (in `topBearings') and vertical advance
heights (in `heights'). If you aren't interested in any of the
metrics fields, simply set its value to NULL.
All are expressed in font units, a.k.a. EM units.
The metrics arrays must be allocated by the client program.
IMPORTANT NOTE:
As vertical metrics are optional in a TrueType font, this
function will return an error (TT_Err_No_Vertical_Data) if this
function is called on such a face with non-NULL `topBearings'
or `heights' arguments.
If a font has no vertical data, the `vertical' field in its
properties structure is set to NULL.
..................................................................
TT_Set_Face_Pointer( TT_Face face,
void* data );
For convenience purposes, each face object has a `generic'
pointer which value is unused by the engine, but that can be set
freely by client applications through this function.
Do what you want with it; it is here to give you a chance to
link a face object to your own structures and data.
..................................................................
void* TT_Get_Face_Pointer( TT_Face face );
^^^^
Returns a face object's generic pointer. See
TT_Set_Face_Pointer() above.
..................................................................
TT_Flush_Face( TT_Face face );
Closes a given face object's file handler or descriptor. This
is useful to save system resources if your application opens
dozens or even hundreds of fonts. The face object is still
valid, and its file will be re-opened automatically on the next
request which requires disk access.
..................................................................
TT_Close_Face( TT_Face face );
Closes a given `face' object. This function will also destroy
all the face's child instances. The face's glyphs will not be
destroyed, however.
..................................................................
TT_New_Instance( TT_Face face,
TT_Instance* instance );
Creates a new instance object related to the `face' object. A
handle to the newly created instance is returned in `instance'.
The default instance resolution is 96dpi in both vertical and
horizontal direction; the default point size is 10pt.
..................................................................
TT_Set_Instance_Resolutions( TT_Instance instance,
TT_UShort xResolution,
TT_UShort yResolution );
Sets the target device resolutions for a given instance. The
values are expressed in dots per inch (dpi). A value of 96dpi
is typical for an SVGA display, 72dpi for a Macintosh one, and
300 to 6000dpi for printers. Default value (before a call to
this function) is 96dpi.
..................................................................
TT_Set_Instance_CharSize( TT_Instance instance,
TT_F26Dot6 charsize );
Sets the point size for a given instance. The size is expressed
in fractional (26.6) `points', where 1 point = 1/72 inch. The
default value is 10pt (before a call to this function).
For example, to use a char size of 12pt, call the function with:
TT_Set_Instance_CharSize( instance, 12 * 64 );
Fractional point sizes are thus possible.
Call this function after TT_Set_Instance_Resolutions().
..................................................................
TT_Set_Instance_CharSizes( TT_Instance instance,
TT_F26Dot6 charWidth,
TT_F26Dot6 charHeight );
Sets an instance's glyph width and height independently in
fractional (26.6) points. Similar to Set_Instance_CharSize()
with the exception that the horizontal and vertical glyph
dimensions can differ.
Call this function after TT_Set_Instance_Resolutions().
..................................................................
TT_Set_Instance_PixelSizes( TT_Instance instance,
TT_UShort pixelWidth,
TT_UShort pixelHeight,
TT_F26Dot6 pointSize );
This function can be used to specify directly the pixel sizes
and point size of a given instance, independently of device
resolutions. This is not the recommended way to do it, but can
be used for debugging or simplicity in some special cases.
Note that you _must_ provide a point size!
Call this function after TT_Set_Instance_Resolutions().
..................................................................
TT_Set_Instance_Transform_Flags( TT_Instance instance,
TT_Bool rotated,
TT_Bool stretched );
Sets the transform flags for a given instance. These flags are
passed to the interpreter each time a glyph is loaded within the
instance. Their role is to notify the glyph hinting mechanism
that the resulting glyph will be transformed in a special way.
Setting one of these flags to true usually disables hinting,
though this behaviour varies with each font file.
NOTE:
The glyph loader doesn't perform the rotation or the
stretching automatically; this must be done explicitly by the
client application. Use the function TT_Transform_Outline()
for that purpose.
..................................................................
TT_Get_Instance_Metrics( TT_Instance instance,
TT_Instance_Metrics* imetrics );
This call returns a given instance's current metrics. They are
returned in the `imetrics' structure, which contains, among
other things, the current point size, ppem, and device
resolution (horizontal and vertical).
..................................................................
TT_Set_Instance_Pointer( TT_Instance instance,
void* data );
For convenience purposes, each instance object has a `generic'
pointer which value is unused by the engine, but that can be set
freely by client applications through this function.
Do what you want with it, it is here to give you a chance to
link a face object to your own structures and data.
..................................................................
void* TT_Get_Instance_Pointer( TT_Instance instance )
^^^^
This function returns an instance object's generic pointer set
through TT_Set_Instance_Pointer().
..................................................................
TT_Done_Instance( TT_Instance instance );
Closes a given instance object, destroying its associated data.
Note that this is performed automatically when a face is closed
on all its child instances. However, explicit deallocation can
help in freeing the memory used by the application earlier.
..................................................................
TT_New_Glyph( TT_Face face,
TT_Glyph* glyph );
Creates a new glyph container for the glyphs of the font
described by the `face' handle. A pointer to the container is
returned in `glyph'. The face is said to be the glyph's parent.
NOTE:
A glyph is destroyed with its parent face object. However, it
is possible to delete it explicitly with TT_Done_Glyph().
..................................................................
TT_Done_Glyph( TT_Glyph glyph );
Discards a glyph container. This is also done automatically for
all glyphs when closing its parent face object.
..................................................................
TT_Load_Glyph( TT_Instance instance,
TT_Glyph glyph,
TT_UShort glyphIndex,
TT_UShort loadFlags );
Loads and processes (scales and/or hints) a glyph at a given
`instance' into the `glyph' container.
Note that `glyph' and `instance' must have the _same_ parent
face object, otherwise an error message will be returned.
`glyph_index' is the glyph's index as found in the TrueType
font. It is _not_ a character code (see the charmap functions
below).
`load_flags' is an integer that specifies which operations are
to be performed on the loaded glyph. The following values/bits
are used:
TTLOAD_SCALE_GLYPH
Indicates that the glyph must be scaled to the instance's
resolution. The pixel coordinates returned in the glyph
outline structure (see below) are then expressed in
fractional pixels represented in the 26.6 fixed point
floating format (F26Dot6).
If scaling is disabled, the coordinates returned in the
outline structure are integer font units, also called
`FUnits' by the TrueType specification.
TTLOAD_HINT_GLYPH
This flag is only valid when scaling is on. It informs the
loader that the glyph must be hinted (i.e., grid-fitted for
optimal display). Note that hinting will occur only if the
instance's transformations and metrics allow it (for
example, most font programs disable hinting automatically in
case of rotation or stretching).
When loading a hinted glyph, the metrics computed by the
loader, including the bounding box, will also be
grid-fitted.
TTLOAD_PEDANTIC
Starting with FreeType version 1.3, the bytecode interpreter
can ignore even more errors (like out-of-bound array
accesses). Using this flag it is possible to force TrueType
compliant interpretation of font programs.
TTLOAD_IGNORE_GLOBAL_ADVANCE_WIDTH
A flag to handle monospaced fonts with an incorrect global
advance width in the `hhea' table. If set, the actual
advance width value of a particular glyph will be used; if
unset, the advance widths for all glyphs are forced to be
equal to the global value.
NOTE:
You can also use the constant TTLOAD_DEFAULT, which is simply
the union of TTLOAD_SCALE_GLYPH and TTLOAD_HINT_GLYPH for most
`typical' loads.
..................................................................
TT_Get_Glyph_Outline( TT_Glyph glyph,
TT_Outline* outline );
This call returns the glyph's `outline'. This is a simple
structure which contains pointers to the data used to describe
an outline to the rasterizer. See the definition of
TT_Outline in section I.
..................................................................
TT_Get_Glyph_Metrics( TT_Glyph glyph,
TT_Glyph_Metrics* metrics );
Extracts the glyph's metrics and copies them to the `*metrics'
structure. Its format is described in section I.
If the glyph has been loaded without scaling, the values are
expressed in FUnits (integers relative to the original font grid
called the EM Square).
If the glyph has been loaded _with_ scaling, which is the
default, the values are expressed in fractional pixels in 26.6
fixed point float format (F26Dot6; 1 unit = 1/64th of a pixel).
If the glyph has been loaded with hinting, the metrics are also
grid-fitted, including the bounding box. To get the un-fitted
bbox, call TT_Get_Outline_BBox() on the glyph's outline.
NOTE:
BBox fitting occurs according to the following scheme:
#define FLOOR( x ) ( (x) & -64 )
#define CEILING( x ) ( ( (x) + 63 ) & -64 )
xMin = FLOOR( xMin );
yMin = FLOOR( yMin );
xMax = CEILING( xMax );
yMax = CEILING( yMax );
This means that the outline's width and height in pixels can be
computed simply from the fitted bbox, namely
(xMax-xMin)/64 and (yMax-yMin)/64
..................................................................
TT_Get_Glyph_Big_Metrics( TT_Glyph glyph,
TT_Big_Glyph_Metrics* metrics );
Extracts the glyph's big metrics and copies them to the
`*metrics' structure. Its format is described in section I.
If the glyph has been loaded without scaling, the values are
expressed in FUnits (integers relative to the original font grid
called the EM Square).
If the glyph has been loaded _with_ scaling, which is the
default, the values are expressed in fractional pixels in 26.6
fixed point float format (F26Dot6; 1 unit = 1/64th of a pixel).
If the glyph has been loaded with hinting, the metrics are also
grid-fitted, including the bounding box. To get the un-fitted
bbox, just call TT_Get_Outline_BBox() on the glyph's outline.
NOTE 1:
BBox fitting occurs according to the following scheme:
#define FLOOR( x ) ( (x) & -64 )
#define CEILING( x ) ( ( (x) + 63 ) & -64 )
xMin = FLOOR( xMin );
yMin = FLOOR( yMin );
xMax = CEILING( xMax );
yMax = CEILING( yMax );
This means that the outline's width and height in pixels can be
computed simply from the fitted bounding box, namely
(xMax-xMin)/64 and (yMax-yMin)/64
NOTE 2:
The vertBearingX value in `metrics' cannot be extracted for
outline glyphs -- it is defined for embedded bitmaps only.
Instead, it is set to (xMin-xMax)/2; this will center the
bounding box on the vertical `baseline'.
..................................................................
TT_Get_Glyph_Bitmap( TT_Glyph glyph,
TT_Raster_Map* bitmap,
TT_F26Dot6 xOffset,
TT_F26Dot6 yOffset );
This call converts the vectorial glyph representation contained
in the object handled by `glyph' into a bitmap.
The target bitmap is described by the `bitmap' pointer.
Clipping will be done if necessary. You can also specify an
offset to be applied before the scan-line conversion; `xOffset'
and `yOffset' must be expressed in fractional pixels (where
1 unit = 1/64th pixel).
NOTE 1:
Choosing non integer pixel offsets, i.e., values of `xOffset'
and `yOffset' that are not multiples of 64, will ruin the
hinting performed by the interpreter, and result in bad
rendering at small sizes.
NOTE 2:
The glyph's point coordinates must be scaled before calling
this function. Never call this function with a glyph that
were loaded with no scaling!
NOTE 3:
FreeType always shifts the glyph horizontally so that the left
side bearing is equal to the left side of the bounding box.
..................................................................
TT_Get_Glyph_Pixmap( TT_Glyph glyph,
TT_Raster_Map* pixmap,
TT_F26Dot6 xOffset,
TT_F26Dot6 yOffset );
This call converts the vectorial glyph representation contained
in the object handled by `glyph' into a pixmap (i.e., an
8-bit/pixel map). The result is an anti-aliased version of the
glyph (`anti-aliasing' is also known as `font-smoothing').
The target pixmap is described by the `pixmap' pointer. Note
that its width _must_ be a multiple of 4. For the definition
and description of a pixmap see Section I.
As with TT_Get_Glyph_Bitmap(), you can specify offsets to be
applied before the rendering (`xOffset' and `yOffset' must be
expressed in fractional pixel coordinates).
NOTE 1:
You don't need to supply a temporary bitmap for the
anti-aliaser. The rasterizer uses its own scheme to optimize
memory usage.
NOTE 2:
The glyph's point coordinates must be scaled before calling
this function. This means that you should never call it with
a glyph which has been loaded without scaling!
NOTE 3:
The pixmap passed to this function should always be EMPTY
(i.e., filled with zero bytes) before the call. If not,
garbage will accumulate!
NOTE 4:
FreeType always shifts the glyph horizontally so that the left
side bearing is equal to the left side of the bounding box.
..................................................................
TT_New_Outline( TT_UShort numPoints,
TT_UShort numContours,
TT_Outline* outline );
Creates a new outline object. This function creates the arrays
necessary to hold `numPoints' points and `numContours' contours,
and set `outline's pointers to them.
The new outline owns the arrays, and they will be destroyed with
it through TT_Done_Outline().
NOTE 1:
Outlines created with this function are called `user'
outlines, in contrast with the outlines returned by
TT_Get_Glyph_Outline(), which fields refer to the data
contained within a glyph object (i.e., these outlines do not
own the arrays they refer to).
NOTE 2:
User outlines aren't tracked by the engine, which means they
are not destroyed by a TT_Done_FreeType(). You have to
explicitly discard them through TT_Done_Outline() to avoid
memory leaks.
..................................................................
TT_Done_Outline( TT_Outline* outline );
Deletes an outline's data. Note that you need not destroy the
outlines returned by TT_Get_Glyph_Outline(), only those created
by TT_New_Outline().
..................................................................
TT_Copy_Outline( TT_Outline* source,
TT_Outline* target );
Copies the content of the `source' outline into the content of
the `target' outline. The two outlines must have been created
with the same dimensions (num_points and num_contours),
otherwise this function will return an error code.
..................................................................
void TT_Transform_Outline( TT_Glyph_Outline* outline,
^^^^ TT_Matrix* matrix );
Applies a simple transformation matrix on a given outline. This
will multiply each point coordinate vector by a 2x2 matrix,
which coefficients are given in the 16.16 fixed float format.
Rotation can be performed with this function.
NOTE:
This function takes an outline, and not a glyph handle, as a
parameter. This `feature' lets you apply transformations on
your own copies of glyphs.
..................................................................
void TT_Translate_Outline( TT_Glyph_Outline* outline,
^^^^ TT_Pos xOffset,
TT_Pos yOffset );
Applies a simple translation on a given outline.
NOTE:
This function takes an outline, and not a glyph handle, as a
parameter. This `feature' lets you apply translation to your
own copies of glyphs.
..................................................................
TT_Get_Outline_Bitmap( TT_Engine engine,
TT_Outline* outline,
TT_Raster_Map* bitmap );
Renders an outline into a bitmap. The latter must be setup by
the user before the call (i.e., it is not created by this
function, instead it must be provided by the user).
..................................................................
TT_Get_Outline_Pixmap( TT_Engine engine,
TT_Outline* outline,
TT_Raster_Map* pixmap );
Renders an outline into a pixmap. The latter must be setup by
the user before the call (i.e., it is not created by this
function, instead it must be provided by the user).
NOTE:
The pixmap passed to this function must always be EMPTY (i.e.,
filled with zero bytes) before the call. Otherwise, garbage may
accumulate!
..................................................................
TT_Get_Outline_BBox( TT_Outline* outline,
TT_BBox* bbox );
Returns an outline's bounding box in the `bbox' structure. Note
that the returned coordinates are not grid fitted!
NOTE:
The current release of FreeType (1.x) does compute the bounding
box for the outline's control points, and not the `exact' box
based on Bezier arcs extrema. Hence, the bbox returned by this
function may be slightly larger than necessary if the glyph
doesn't have control points at its extrema, or if it has been
rotated.
..................................................................
void TT_Transform_Vector( TT_Pos* x,
^^^^ TT_Pos* y,
TT_Matrix* matrix );
Applies a 2x2 matrix to a vector.
..................................................................
int TT_Get_CharMapCount( TT_Face face );
^^^
Gets the number of character mappings present in the TrueType
file described by the `face' handle. Returns -1 if the handle
is invalid.
IMPORTANT NOTE: ********
This function is deprecated. Get the number of character maps
from the `num_CharMaps' field in the structure returned by
TT_Get_Face_Property() instead.
..................................................................
TT_Get_CharMap_ID( TT_Face face,
TT_UShort charmapIndex,
TT_UShort* platformID,
TT_UShort* encodingID );
Returns the platform ID and platform-specific encoding ID for
the charmap numbered `charmapIndex' in the `face' object. The
total number of character mapping tables can be found in the
`num_CharMaps' field in the structure returned by
TT_Get_Face_Property().
..................................................................
TT_Get_CharMap( TT_Face face,
TT_UShort charmapIndex,
TT_CharMap* charMap );
Returns a handle for the character map number `charmapIndex' of
`face'. The handle is placed in `*charMap' and can be used
later for fast lookup with the TT_Char_Index() API function.
Charmap objects are automatically destroyed when their face
object is destroyed.
..................................................................
TT_UShort TT_Char_Index( TT_CharMap charMap,
^^^^^^^^^ TT_ULong charCode );
Applies a charMap to translate `charCode' into a glyph index
that can be used to load and address a glyph in the TrueType
file. In case of error, the undefined glyph (index 0) is
returned.
Note: Since FT 1.5, the `charCode' is an unsigned long instead
of an unsigned short.
The charmap handle can be obtained with TT_Get_CharMap().
..................................................................
int TT_Get_Name_Count( TT_Face face );
^^^
Gets the number of name strings found in a face's name table.
This function will return -1 if the face handle is invalid.
IMPORTANT NOTE: ********
This function is deprecated. Get the number of name strings
from the `num_Names' field in the structure returned by
TT_Get_Face_Property() instead.
..................................................................
TT_Get_Name_ID( TT_Face face,
TT_UShort nameIndex,
TT_UShort* platformID,
TT_UShort* encodingID,
TT_UShort* languageID,
TT_UShort* nameID );
Returns the ID of a given name string, indexed by the number
`nameIndex' in a given face. The name index ranges from 0 to
`num_names' minus one; this value can be found in the structure
returned by TT_Get_Face_Property().
Each string has a `platformID', `encodingID', `languageID' and
`nameID', as defined by the TrueType specification.
The platformID is typically in the range [0,3]. Some font files
have unusual name table entries; these can be detected from
their platformID which is larger than 3.
..................................................................
TT_Get_Name_String( TT_Face face,
TT_UShort nameIndex,
TT_String** stringPtr,
TT_UShort* length );
Returns a name string's address and length. Note that an
invalid name table entry always returns NULL for `stringPtr' and
zero for `length'.
NOTE 1:
The string belongs to the face object and should not be
written to or freed by the client application.
NOTE 2:
The library does not care about endianess here! If you are
using a little-endian machine and you have to interpret the
string bytes as 16-bit-wide characters (e.g. Unicode encoded),
you must byte-swap the data because 16-bit data is stored as
big-endian in TrueType fonts, and FreeType reads in the whole
name table bytewise.
..................................................................
TT_Get_Font_Data( TT_face face,
TT_Long tag,
TT_Long offset,
void* buffer,
TT_Long* length );
Gets font or table data. Similar to the GetFontData() API of
the Windows world. You can use the macro MAKE_TT_TAG() to
generate TrueType table tags from character descriptions, like
MAKE_TT_TAG( 'e', 'b', 'l', 'c' )
Use the value 0 instead for `tag' if you want to access the
whole font file. `offset' specifies the starting offset in the
table (or the offset in the file if tag == 0), `buffer' the
address of target buffer.
Depending on the value of length, various actions are performed.
If `length' is NULL, the whole table will be loaded. An error
will be returned if `offset' is not 0. If `*length' is zero,
TT_Get_Font_Data() exits immediately, returning only the length
of the given table (in the variable `length'), or of the font
file, depending on the value of `tag'. Finally, if `*length' is
not zero, the next `length' bytes of the table (resp. the font)
are loaded into an array pointed to by `buffer', starting at
offset `offset'. Note that the `buffer' array must be large
enough to hold `length' bytes.
--------------------------------------------------------------------
--------------------------------------------------------------------
III. Error Messages
===================
Most functions return an error code, typed to TT_Error. A return
value of zero indicates no error. The error values are defined in
the file `freetype.h'. In the following table, the prefix
`TT_Err_' is omitted, e.g. `Ok' -> `TT_Err_Ok'.
Error Unprefixed Error
Code Macro Name Description
------------------------------------------------------------------
0x0000 Ok Successful function call.
Always 0!
----------------- high-level API error codes ---------------------
The following error codes are returned by the high-level API to
indicate an invalid client request.
0x0001 Invalid_Face_Handle An invalid face object handle was
passed to an API function.
0x0002 Invalid_Instance_Handle An invalid instance object handle
was passed to an API function.
0x0003 Invalid_Glyph_Handle An invalid glyph container handle
was passed to an API function.
0x0004 Invalid_CharMap_Handle An invalid charmap handle was
passed to an API function.
0x0005 Invalid_Result_Address An output parameter (a result)
was given a NULL address in an
API call.
0x0006 Invalid_Glyph_Index An invalid glyph index was passed
to an API function.
0x0007 Invalid_Argument An invalid argument was passed to
an API function. Usually, this
means a simple out-of-bounds
error.
0x0008 Could_Not_Open_File The pathname passed doesn't point
to an existing or accessible
file.
0x0009 File_Is_Not_Collection Returned by TT_Open_Collection
while trying to open a file which
isn't a collection.
0x000A Table_Missing The requested TrueType table is
missing in the font file.
0x000B Invalid_Horiz_Metrics The font's HMTX table is invalid.
Denotes a broken font.
0x000C Invalid_CharMap_Format A font's charmap entry has an
invalid format. Some other
entries may be valid though.
0x000D Invalid_PPem Invalid PPem values specified,
i.e., you are accessing a scaled
glyph without having called
TT_Set_Instance_CharSize() or
TT_Set_Instance_PixelSizes().
0x0010 Invalid_File_Format The file isn't a TrueType font or
collection.
0x0011 Invalid_Vert_Metrics The font's VMTX table is invalid.
Denotes a broken font.
0x0020 Invalid_Engine An invalid engine handle was
passed to one of the API
functions.
0x0021 Too_Many_Extensions The client application is trying
to initialize too many
extensions. The default max
extensions number is 8 (this
value can be changed at compile
time).
0x0022 Extensions_Unsupported This build of the engine doesn't
support extensions.
0x0023 Invalid_Extension_Id This error indicates that the
client application is trying to
use an extension that has not
been initialized yet.
0x0030 No_Vertical_Data There is no vertical data, but
you are requesting it. Instead,
call TT_Get_Face_Metrics() with
NULL pointers for `topBearings'
and `heights'.
0x0080 Max_Profile_Missing The max profile table is missing.
=> broken font file
0x0081 Header_Table_Missing The font header table is missing.
=> broken font file
0x0082 Horiz_Header_Missing The horizontal header is missing.
=> broken font file
0x0083 Locations_Missing The locations table is missing.
=> broken font file
0x0084 Name_Table_Missing The name table is missing.
=> broken font file
0x0085 CMap_Table_Missing The character encoding tables are
missing.
=> broken font file
0x0086 Hmtx_Table_Missing The hmtx table is missing.
=> broken font file
0x0087 OS2_Table_Missing The OS/2 table is missing.
Some Mac fonts don't have it.
0x0088 Post_Table_Missing The PostScript table is missing.
=> broken font file
0x0089 Glyf_Table_Missing The glyph table is missing.
=> broken font file
----------------- memory component error codes -------------------
0x0100 Out_Of_Memory An operation couldn't be
performed due to memory
exhaustion.
----------------- file component error codes ---------------------
0x0200 Invalid_File_Offset Trying to seek to an invalid
portion of the font file.
Denotes a broken file.
0x0201 Invalid_File_Read Trying to read an invalid portion
of the font file. Denotes a
broken file.
0x0202 Invalid_Frame_Access Trying to frame an invalid
portion of the font file.
Denotes a broken file.
----------------- glyph loader error codes -----------------------
These errors are produced by the glyph loader. They denote an
invalid glyph record within the font file.
0x0300 Too_Many_Points The glyph has too many points to
be valid for its font file.
0x0301 Too_Many_Contours The glyph has too many contours
to be valid for its font file.
0x0302 Invalid_Composite_Glyph A composite glyph's description
is broken.
0x0303 Too_Many_Ins The glyph has too many
instructions to be valid for its
font file.
----------------- byte-code interpreter error codes --------------
These error codes are produced by the TrueType byte-code
interpreter. They usually indicate a broken font file or a broken
glyph within a font.
0x0400 Invalid_Opcode Found an invalid opcode in a
TrueType byte-code stream.
0x0401 Too_Few_Arguments An opcode was invoked with too
few arguments on the stack.
0x0402 Stack_Overflow The interpreter's stack has been
filled up and operations can't
continue.
0x0403 Code_Overflow The byte-code stream runs out of
its valid bounds.
0x0404 Bad_Argument A function received an invalid
argument.
0x0405 Divide_By_Zero A division by 0 operation was
queried by the interpreter
program.
0x0406 Storage_Overflow The program tried to access data
outside of its storage area.
0x0407 Cvt_Overflow The program tried to access data
outside of its control value
table.
0x0408 Invalid_Reference The program tried to reference an
invalid point, zone, or contour.
0x0409 Invalid_Distance The program tried to use an
invalid distance.
0x040A Interpolate_Twilight The program tried to interpolate
twilight points.
0x040B Debug_Opcode The now invalid `debug' opcode
was found in the byte-code
stream.
0x040C ENDF_In_Exec_Stream A misplaced ENDF was encountered
in the byte-code stream.
0x040D Out_Of_CodeRanges The program tried to allocate too
much code ranges (this is really
an engine internal error that
should never happen).
0x040E Nested_DEFS Nested function definitions
encountered.
0x040F Invalid_CodeRange The program tried to access an
invalid code range.
0x0410 Invalid_Displacement The program tried to use an
invalid displacement.
0x0411 Execution_Too_Long In order to get rid of `poison'
fonts, the interpreter produces
this error if more than one
million opcodes have been
interpreted in a single glyph
program. This detects infinite
loops softly.
----------------- internal failure error codes -------------------
These error codes are produced if an incoherent library state has
been detected. All of these reflect a severe bug in the engine
(or a severe memory corruption due to massive overwrites by your
application into the library's data)!
If you do encounter a font that makes one of the test programs
produce such an error, please report it!
0x0500 Nested_Frame_Access
0x0501 Invalid_Cache_List
0x0502 Could_Not_Find_Context
0x0503 Unlisted_Object
----------------- scan-line converter error codes ----------------
These error codes are produced by the raster component. They
indicate that an outline structure was incoherently set up, or
that you are trying to render a horribly complex glyph.
They should be _extremely_ rare, however.
0x0600 Raster_Pool_Overflow Render pool overflow. This should
never happen in this release.
0x0601 Raster_Negative_Height A negative height was produced.
0x0602 Raster_Invalid_Value The outline data wasn't set
properly. Check that:
points >= endContours[contours]
0x0603 Raster_Not_Initialized You did not call
TT_Init_FreeType()!
--- end of apiref.txt ---
|