summaryrefslogtreecommitdiff
path: root/Build/source/libs/t1lib/t1lib-5.1.2/doc/ut1lib.tex
blob: b0fd2b42fe0949921872dbb5901fe88ad210c340 (plain)
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
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
2276
2277
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
2303
2304
2305
2306
2307
2308
2309
2310
2311
2312
2313
2314
2315
2316
2317
2318
2319
2320
2321
2322
2323
2324
2325
2326
2327
2328
2329
2330
2331
2332
2333
2334
2335
2336
2337
2338
2339
2340
2341
2342
2343
2344
2345
2346
2347
2348
2349
2350
2351
2352
2353
2354
2355
2356
2357
2358
2359
2360
2361
2362
2363
2364
2365
2366
2367
2368
2369
2370
2371
2372
2373
2374
2375
2376
2377
2378
2379
2380
2381
2382
2383
2384
2385
2386
2387
2388
2389
2390
2391
2392
2393
2394
2395
2396
2397
2398
2399
2400
2401
2402
2403
2404
2405
2406
2407
2408
2409
2410
2411
2412
2413
2414
2415
2416
2417
2418
2419
2420
2421
2422
2423
2424
2425
2426
2427
2428
2429
2430
2431
2432
2433
2434
2435
2436
2437
2438
2439
2440
2441
2442
2443
2444
2445
2446
2447
2448
2449
2450
2451
2452
2453
2454
2455
2456
2457
2458
2459
2460
2461
2462
2463
2464
2465
2466
2467
2468
2469
2470
2471
2472
2473
2474
2475
2476
2477
2478
2479
2480
2481
2482
2483
2484
2485
2486
2487
2488
2489
2490
2491
2492
2493
2494
2495
2496
2497
2498
2499
2500
2501
2502
2503
2504
2505
2506
2507
2508
2509
2510
2511
2512
2513
2514
2515
2516
2517
2518
2519
2520
2521
2522
2523
2524
2525
2526
2527
2528
2529
2530
2531
2532
2533
2534
2535
2536
2537
2538
2539
2540
2541
2542
2543
2544
2545
2546
2547
2548
2549
2550
2551
2552
2553
2554
2555
2556
2557
2558
2559
2560
2561
2562
2563
2564
2565
2566
2567
2568
2569
2570
2571
2572
2573
2574
2575
2576
2577
2578
2579
2580
2581
2582
2583
2584
2585
2586
2587
2588
2589
2590
2591
2592
2593
2594
2595
2596
2597
2598
2599
2600
2601
2602
2603
2604
2605
2606
2607
2608
2609
2610
2611
2612
2613
2614
2615
2616
2617
2618
2619
2620
2621
2622
2623
2624
2625
2626
2627
2628
2629
2630
2631
2632
2633
2634
2635
2636
2637
2638
2639
2640
2641
2642
2643
2644
2645
2646
2647
2648
2649
2650
2651
2652
2653
2654
2655
2656
2657
2658
2659
2660
2661
2662
2663
2664
2665
2666
2667
2668
2669
2670
2671
2672
2673
2674
2675
2676
2677
2678
2679
2680
2681
2682
2683
2684
2685
2686
2687
2688
2689
2690
2691
2692
2693
2694
2695
2696
2697
2698
2699
2700
2701
2702
2703
2704
2705
2706
2707
2708
2709
2710
2711
2712
2713
2714
2715
2716
2717
2718
2719
2720
2721
2722
2723
2724
2725
2726
2727
2728
2729
2730
2731
2732
2733
2734
2735
2736
2737
2738
2739
2740
2741
2742
2743
2744
2745
2746
2747
2748
2749
2750
2751
2752
2753
2754
2755
2756
2757
2758
2759
2760
2761
2762
2763
2764
2765
2766
2767
2768
2769
2770
2771
2772
2773
2774
2775
2776
2777
2778
2779
2780
2781
2782
2783
2784
2785
2786
2787
2788
2789
2790
2791
2792
2793
2794
2795
2796
2797
2798
2799
2800
2801
2802
2803
2804
2805
2806
2807
2808
2809
2810
2811
2812
2813
2814
2815
2816
2817
2818
2819
2820
2821
2822
2823
2824
2825
2826
2827
2828
2829
2830
2831
2832
2833
2834
2835
2836
2837
2838
2839
2840
2841
2842
2843
2844
2845
2846
2847
2848
2849
2850
2851
2852
2853
2854
2855
2856
2857
2858
2859
2860
2861
2862
2863
2864
2865
2866
2867
2868
2869
2870
2871
2872
2873
2874
2875
2876
2877
2878
2879
2880
2881
2882
2883
2884
2885
2886
2887
2888
2889
2890
2891
2892
2893
2894
2895
2896
2897
2898
2899
2900
2901
2902
2903
2904
2905
2906
2907
2908
2909
2910
2911
2912
2913
2914
2915
2916
2917
2918
2919
2920
2921
2922
2923
2924
2925
2926
2927
2928
2929
2930
2931
2932
2933
2934
2935
2936
2937
2938
2939
2940
2941
2942
2943
2944
2945
2946
2947
2948
2949
2950
2951
2952
2953
2954
2955
2956
2957
2958
2959
2960
2961
2962
2963
2964
2965
2966
2967
2968
2969
2970
2971
2972
2973
2974
2975
2976
2977
2978
2979
2980
2981
2982
2983
2984
2985
2986
2987
2988
2989
2990
2991
2992
2993
2994
2995
2996
2997
2998
2999
3000
3001
3002
3003
3004
3005
3006
3007
3008
3009
3010
3011
3012
3013
3014
3015
3016
3017
3018
3019
3020
3021
3022
3023
3024
3025
3026
3027
3028
3029
3030
3031
3032
3033
3034
3035
3036
3037
3038
3039
3040
3041
3042
3043
3044
3045
3046
3047
3048
3049
3050
3051
3052
3053
3054
3055
3056
3057
3058
3059
3060
3061
3062
3063
3064
3065
3066
3067
3068
3069
3070
3071
3072
3073
3074
3075
3076
3077
3078
3079
3080
3081
3082
3083
3084
3085
3086
3087
3088
3089
3090
3091
3092
3093
3094
3095
3096
3097
3098
3099
3100
3101
3102
3103
3104
3105
3106
3107
3108
3109
3110
3111
3112
3113
3114
3115
3116
3117
3118
3119
3120
3121
3122
3123
3124
3125
3126
3127
3128
3129
3130
3131
3132
3133
3134
3135
3136
3137
3138
3139
3140
3141
3142
3143
3144
3145
3146
3147
3148
3149
3150
3151
3152
3153
3154
3155
3156
3157
3158
3159
3160
3161
3162
3163
3164
3165
3166
3167
3168
3169
3170
3171
3172
3173
3174
3175
3176
3177
3178
3179
3180
3181
3182
3183
3184
3185
3186
3187
3188
3189
3190
3191
3192
3193
3194
3195
3196
3197
3198
3199
3200
3201
3202
3203
3204
3205
3206
3207
3208
3209
3210
3211
3212
3213
3214
3215
3216
3217
3218
3219
3220
3221
3222
3223
3224
3225
3226
3227
3228
3229
3230
3231
3232
3233
3234
3235
3236
3237
3238
3239
3240
3241
3242
3243
3244
3245
3246
3247
3248
3249
3250
3251
3252
3253
3254
3255
3256
3257
3258
3259
3260
3261
3262
3263
3264
3265
3266
3267
3268
3269
3270
3271
3272
3273
3274
3275
3276
3277
3278
3279
3280
3281
3282
3283
3284
3285
3286
3287
3288
3289
3290
3291
3292
3293
3294
3295
3296
3297
3298
3299
3300
3301
3302
3303
3304
3305
3306
3307
3308
3309
3310
3311
3312
3313
3314
3315
3316
3317
3318
3319
3320
3321
3322
3323
3324
3325
3326
3327
3328
3329
3330
3331
3332
3333
3334
3335
3336
3337
3338
3339
3340
3341
3342
3343
3344
3345
3346
3347
3348
3349
3350
3351
3352
3353
3354
3355
3356
3357
3358
3359
3360
3361
3362
3363
3364
3365
3366
3367
3368
3369
3370
3371
3372
3373
3374
3375
3376
3377
3378
3379
3380
3381
3382
3383
3384
3385
3386
3387
3388
3389
3390
3391
3392
3393
3394
3395
3396
3397
3398
3399
3400
3401
3402
3403
3404
3405
3406
3407
3408
3409
3410
3411
3412
3413
3414
3415
3416
3417
3418
3419
3420
3421
3422
3423
3424
3425
3426
3427
3428
3429
3430
3431
3432
3433
3434
3435
3436
3437
3438
3439
3440
3441
3442
3443
3444
3445
3446
3447
3448
3449
3450
3451
3452
3453
3454
3455
3456
3457
3458
3459
3460
3461
3462
3463
3464
3465
3466
3467
3468
3469
3470
3471
3472
3473
3474
3475
3476
3477
3478
3479
3480
3481
3482
3483
3484
3485
3486
3487
3488
3489
3490
3491
3492
3493
3494
3495
3496
3497
3498
3499
3500
3501
3502
3503
3504
3505
3506
3507
3508
3509
3510
3511
3512
3513
3514
3515
3516
3517
3518
3519
3520
3521
3522
3523
3524
3525
3526
3527
3528
3529
3530
3531
3532
3533
3534
3535
3536
3537
3538
3539
3540
3541
3542
3543
3544
3545
3546
3547
3548
3549
3550
3551
3552
3553
3554
3555
3556
3557
3558
3559
3560
3561
3562
3563
3564
3565
3566
3567
3568
3569
3570
3571
3572
3573
3574
3575
3576
3577
3578
3579
3580
3581
3582
3583
3584
3585
3586
3587
3588
3589
3590
3591
3592
3593
3594
3595
3596
3597
3598
3599
3600
3601
3602
3603
3604
3605
3606
3607
3608
3609
3610
3611
3612
3613
3614
3615
3616
3617
3618
3619
3620
3621
3622
3623
3624
3625
3626
3627
3628
3629
3630
3631
3632
3633
3634
3635
3636
3637
3638
3639
3640
3641
3642
3643
3644
3645
3646
3647
3648
3649
3650
3651
3652
3653
3654
3655
3656
3657
3658
3659
3660
3661
3662
3663
3664
3665
3666
3667
3668
3669
3670
3671
3672
3673
3674
3675
3676
3677
3678
3679
3680
3681
3682
3683
3684
3685
3686
3687
3688
3689
3690
3691
3692
3693
3694
3695
3696
3697
3698
3699
3700
3701
3702
3703
3704
3705
3706
3707
3708
3709
3710
3711
3712
3713
3714
3715
3716
3717
3718
3719
3720
3721
3722
3723
3724
3725
3726
3727
3728
3729
3730
3731
3732
3733
3734
3735
3736
3737
3738
3739
3740
3741
3742
3743
3744
3745
3746
3747
3748
3749
3750
3751
3752
3753
3754
3755
3756
3757
3758
3759
3760
3761
3762
3763
3764
3765
3766
3767
3768
3769
3770
3771
3772
3773
3774
3775
3776
3777
3778
3779
3780
3781
3782
3783
3784
3785
3786
3787
3788
3789
3790
3791
3792
3793
3794
3795
3796
3797
3798
3799
3800
3801
3802
3803
3804
3805
3806
3807
3808
3809
3810
3811
3812
3813
3814
3815
3816
3817
3818
3819
3820
3821
3822
3823
3824
3825
3826
3827
3828
3829
3830
3831
3832
3833
3834
3835
3836
3837
3838
3839
3840
3841
3842
3843
3844
3845
3846
3847
3848
3849
3850
3851
3852
3853
3854
3855
3856
3857
3858
3859
3860
3861
3862
3863
3864
3865
3866
3867
3868
3869
3870
3871
3872
3873
3874
3875
3876
3877
3878
3879
3880
3881
3882
3883
3884
3885
3886
3887
3888
3889
3890
3891
3892
3893
3894
3895
3896
3897
3898
3899
3900
3901
3902
3903
3904
3905
3906
3907
3908
3909
3910
3911
3912
3913
3914
3915
3916
3917
3918
3919
3920
3921
3922
3923
3924
3925
3926
3927
3928
3929
3930
3931
3932
3933
3934
3935
3936
3937
3938
3939
3940
3941
3942
3943
3944
3945
3946
3947
3948
3949
3950
3951
3952
3953
3954
3955
3956
3957
3958
3959
3960
3961
3962
3963
3964
3965
3966
3967
3968
3969
3970
3971
3972
3973
3974
3975
3976
3977
3978
3979
3980
3981
3982
3983
3984
3985
3986
3987
3988
3989
3990
3991
3992
3993
3994
3995
3996
3997
3998
3999
4000
4001
4002
4003
4004
4005
4006
4007
4008
4009
4010
4011
4012
4013
4014
4015
4016
4017
4018
4019
4020
4021
4022
4023
4024
4025
4026
4027
4028
4029
4030
4031
4032
4033
4034
4035
4036
4037
4038
4039
4040
4041
4042
4043
4044
4045
4046
4047
4048
4049
4050
4051
4052
4053
4054
4055
4056
4057
4058
4059
4060
4061
4062
4063
4064
4065
4066
4067
4068
4069
4070
4071
4072
4073
4074
4075
4076
4077
4078
4079
4080
4081
4082
4083
%----------------------------------------------------------------------------
% ----- File:        ut1lib.tex 
% ----- Author:      Rainer Menzner (Rainer.Menzner@web.de)
% ----- Date:        2005-05-18
% ----- Description: This file is part of the t1lib-documentation.
% ----- Copyright:   t1lib is copyrighted (c) Rainer Menzner, 1996-2005.
%                    As of version 0.5, t1lib is distributed under the
%                    GNU General Public Library License. The
%                    conditions can be found in the files LICENSE and
%                    LGPL, which should reside in the top level
%                    directory of the distribution.  Please note that 
%                    there are parts of t1lib that are subject to
%                    other licenses:
%                    The parseAFM-package is copyrighted by Adobe Systems
%                    Inc.
%                    The type1 rasterizer is copyrighted by IBM and the
%                    X11-consortium.
% ----- Warranties:  Of course, there's NO WARRANTY OF ANY KIND :-)
% ----- Credits:     I want to thank IBM and the X11-consortium for making
%                    their rasterizer freely available.
%                    Also thanks to Piet Tutelaers for his ps2pk, from
%                    which I took the rasterizer sources in a format
%                    independ from X11.
%                    Thanks to all people who make free software living!
%----------------------------------------------------------------------------

\newpage
\section{Using \tonelib}
This section describes in detail how to use \tonelib. I have tried to
to describe the stuff in the order a new user would learn best and a new user
would need to use the functions. 


\subsection{Compiling and Linking \tonelib-Programs}
\label{compilingprograms}%
A program that wants to use functions from the library must include
the appropriate headers at compile time and then be linked with the
appropriate libraries. Since V. 0.6-beta the X11 interface is separated
from the \tonelib\ pivotal stuff. This yields advantages for programs that
don't use the X11 rastering functions on systems where X11 is
installed. 
The following applies to programs that do not use the X11 rastering
functions: 
\begin{itemize}
\item Include the file \verb+t1lib.h+. All definitions and declarations
  needed at compile time are included in this file.
\item \verb+libt1.a+ or \verb+libt1.so+ respectively must be linked to the
  program. 
\end{itemize}
In contrast, a program that uses the X11 interface must adhere to the
following scheme:
\begin{itemize}
\item \verb+t1lib.h+ and \verb+t1libx.h+ must be included in this
  order. Furthermore, \verb+t1libx.h+ includes \verb+X11/Xlib.h+ if
  it is not already included.
\item The libraries \verb+libt1.a+/\verb+libt1.so+ and
  \verb+libt1x.a+/\verb+libt1x.so+ must be linked to the executable. 
  The correct order is \verb+-lt1x -lt1+ since the X interface uses
  functions from the latter. Also, the X11 library must appear in the
  library list after \verb+-lt1x+.
\end{itemize}
The Makefiles for \verb+xglyph+ and \verb+type1afm+ are typical
examples for both configurations.


\subsection{Querying and Setting Fundamental Configuration Parameters of \tonelib}
\label{queryconfiguration}%
It might be necessary to know whether \tonelib\ is compiled with or without
X11 interface. At compile time a programmer can check for the X11 interface by
stating
\begin{verbatim}
#ifdef T1LIB_X11_SUPPORT
\end{verbatim}
after including \verb+t1libx.h+. If \verb+T1LIB_X11_SUPPORT+ is not defined,
the X11 interface is not configured and compiled.

At runtime, a program can check for the X11 interface by a call to 
\precorr
\begin{verbatim}
 int T1_QueryX11Support( void)
\end{verbatim}\index{\verb+T1_QueryX11Support()+}\postcorr
It returns \verb+1+ if the X11 interface is present and \verb+0+ otherwise.

Notice that querying X11 support at runtime and compile time tends to
be pretty useless starting with V.~0.6-beta. Any decision can be done
by examining the existence of the \verb+t1x+-library and the
\verb+t1libx.h+ header file. The definition and the function described
above are thus only provided for compatibility with pre-0.6 versions
of \tonelib. 

Some remarks on the general data format of bitmaps and should be given
here. \tonelib\ internally always generates bitmaps in the way that appears to
be natural for them: The first pixel corresponds to the least significant bit
in a byte (or word/longword). Bytes are always arranged in memory the way,
that the first byte is at the lowest address and the next byte at the
following address. This convention is called LSBFirst which stands for Least
Significant Bit/Byte First. It is the natural way of data alignment on
machines with {\em Little Endian} data representation. In contrast MSBFirst
stands for Most Significant Bit/Byte First which is the natural kind of data
representation on Big Endian machines. 
A glyph's scanlines are always aligned in LSBFirst-type, no matter on what
machine \tonelib\ is running.  

What has been said above, strictly does only apply to non antialiased glyphs,
i.e., real bitmaps. Antialiased glyphs have their gray values coded in the
representation that is natural for the machine \tonelib\ is running on. For
example, if \tonelib\ runs on a Big Endian machine, the gray values are in Big
Endian. The X11 displaying functions automatically handle this correct.

Scanlines of \tonelib-glyphs may be padded to 8, 16 or 32 bit. Padding to
higher values will consume more memory for the glyphs, but might speed up
concatenating of bitmaps as described in \ref{generatingbitmaps}. This applies
to machines with Little Endian representation as, for example, Intel's 
$x$86 series. On these machines 16 or 32 bits can be placed into the
target bitmap in one step. On machines with Big Endian representation, for
example, Motorola 680$x$0 series, this is currently not possible. However,
using a higher padding value could still yield a better performance since the
application could work on larger units than a byte.

The default padding value in \tonelib\ is 8 bit. The padding value can be
specified at runtime by means of calling  
\precorr
\begin{verbatim}
 int T1_SetBitmapPad( int pad)
\end{verbatim}\index{\verb+T1_SetBitmapPad()+}\postcorr
\verb+pad+ must be one of `8', `16' or `32'. The call will only be successful
if executed before initialization of \tonelib. This a security mechanism which
prevents from having glyphs with distinct padding values. The return value is
0 if successful and -1 if \verb+pad+ was invalid or \tonelib\ had already been
initialized.

There is a further restriction concerning the padding value. Setting it to 32
is only possible if the machine has an ANSI C integer type of 64 bits. This
condition is automatically checked by the \verb+configure+ script of \tonelib.
If such an integer type is not present (or has to be emulated as e.g.\ 
\verb+long long+ in \verb+gcc+) there would not result any performance gain.
If a specified padding value is rejected, \verb+T1_errno+ is set
appropriately. 

An application can query the current padding value by calling 
\precorr
\begin{verbatim}
 int T1_GetBitmapPad( void)
\end{verbatim}\index{\verb+T1_GetBitmapPad()+}\postcorr
The returned value is the padding value. This function can be called before or
after initialization of \tonelib.

Another function usually be called near
initialization is
\precorr
\begin{verbatim}
 int T1_SetDeviceResolutions(float x_res, float y_res) 
\end{verbatim}\index{\verb+T1_SetDeviceResolutions()+}\postcorr
This function allows setting the resolution of
your device (screen). The values must be given in dpi. The default
resolution, 72 dpi, implies that a pixel in device space equals 1
bp. This function may be called before or after initialization. The
only restriction is that no size dependent data must be
available. Changing the resolution when bitmaps are already cached would 
result in inconsistent bitmap-sizes for bitmaps generated before and
after the call to \verb+T1_SetDeviceResolutions()+.
The function checks whether initialization has already been done. If
not, all is OK since no size-dependent data for any font can exist. If
initialization has been done, it checks for every font whether size
dependent data exists. If there's any size dependent data for any
font, \verb+T1_SetDeviceResolutions()+ will return \verb+-1+ without
having set the new resolution. Otherwise the specified resolution will
be set and the function will return \verb+0+.
If you really need to set
another resolution in the middle of a session, all size-specific data
should explicitly be removed from memory beforehand. This can be
achieved using \verb+T1_DeleteAllSizes()+ (see \ref{deletingdata}).

Notice that the device resolution need not be set at all if the default
resolution of 72 dpi in horizontal and vertical direction is OK. This function
is primarily intended to be prepared for applications with a device aspect
ratio different from 1.
 
\subsection{Initialization of \tonelib\ and Related Things}
\label{initialization}%
In this section we should cover the initialization, part of which has already
been described in \ref{runtimesetup} in some more detail. This gives the user
the chance to fine-tune the initialization for specific applications.

Prior to be able to do anything useful with \tonelib, the library has to be
initialized. Generally speaking, the purpose of the initialization is to tell
\tonelib\ which font files are associated with which font ID's. The existence
or accessibility of the font files is also assured at this point. Hence, file
name search paths for Type 1 font files, AFM files and encoding files have
also to be known at this time. 

The configuration file and the font database file play a central  r\^ole
during initialization. While the configuration file contains path
specifications and a font database specification, the font database file
specifies the relation between font ID's and font filenames.
The format of both these files is described in \ref{runtimesetup} and not
repeated here. 

A further purpose of the initialization is to set certain flags that prevent
other quantities from being modified at a later time. For example, the padding
value must be unique to all glyphs and consequently it is not allowed to be
changed after initialization has been performed.

The initialization is started by a call to the function
\precorr
\begin{verbatim}
 void *T1_InitLib( int log)
\end{verbatim}\index{\verb+T1_InitLib()+}\postcorr
The parameter \verb+log+ can be interpreted as a mode specification that
influences certain parts of the initialization.  In fact it should consist of
one or more \verb+#define+s from \verb+t1lib.h+.  At minimum, \verb+log+
should be either \verb+LOGFILE+ or \verb+NO_LOGFILE+. If \verb+LOGFILE+ is
specified, a log file is written while the application runs, and
\verb+NO_LOGFILE+ suppresses the generation of a logfile. For information the
\tonelib-logfile see \ref{logfile}.  In addition to this,
\verb+IGNORE_CONFIGFILE+ and \verb+IGNORE_FONTDATABASE+ can be bitwise OR'ed
(using ``\verb+|+'') to the \verb+log+-value. The purpose of this is described
later in this section. A further flag that might find its way into the value
of \verb+log+ is \verb+T1_AA_CACHING+. A discussion of this topic is given in
\ref{aacaching}.
The \verb+T1_NO_AFM+ completely suppresses usage of AFM data, no matter if an
AFM file could have been found using the current search paths or not. This
saves time for loading a font and is recommended if an application is known to
be restricted on functions that do not access AFM data. The consequences of
using this flag are covered somewhat more detailed in \ref{generatingafminfo}.


\subsubsection{Standard Initialization}
\label{standardinitialization}%
The term ``standard initialization'' means, that none of the path manipulating
and font database manipulating actions described later has been
performed. Also, a standard initialization excludes the use of
\verb+IGNORE_CONFIGFILE+ and \verb+IGNORE_FONTDATABASE+. If these conditions
are met, the following happens at initialization time:
\begin{enumerate}
\item The padding value, either being the default value or a value specified
  by the user before, is assigned.
\item Next, depending on the value of \verb+log+, a logfile is tried to be
  opened. From this point on, depending on the loglevel and the value of
  \verb+log+ the actions are logged.
\item The endianess of the machine \tonelib\ is running on is checked. 
\item A configuration file is searched in the following order:
  \begin{itemize}
  \item The process' environment is checked for the entry \verb+T1LIB_CONFIG+
  and if found, its value is interpreted as the filename of the configuration
  file (see \ref{runtimesetup}).
  \item If no file was found, the user's home directory is searched for a file
    named \verb+.t1librc+. In case it exists, it is used as a
    \tonelib-configuration file. 
  \item If still no configuration file was found, the global configuration
    file will be tried to be opened.
  \item If this also does not succeed, all file search paths are left to be
    ``.'' and the default font database is \verb+FontDataBase+.
  \end{itemize}
  It should be noted that the first match wins when searching the configuration
  file. Only the first one found is examined.
\item The font database file(s) are tried to be opened and read. This process
  is in detail described in \ref{fontdatabase}. 
  
  If after scanning the complete list of font databases, no font definitions
  have been performed, \verb+T1_InitLib()+ will return with a \verb+NULL+
  pointer indicating the initialization has failed.
\item The number of fonts declared in the database is stored. Note that this
  number of declared fonts must be greater than zero.
\item A flag is set to indicate \tonelib\ is initialized and the pointer to
  the top most area of the global data structures is returned to the
  application. This pointer is guaranteed to be not \verb+NULL+.
\end{enumerate}
For some applications, the described initialization scheme appears to be too
inflexible and overkill. It is well suited for large applications that use
lots of fonts and where it should be possible to add new fonts without
modifying the application itself. For small commandline applications like
\verb+type1afm+ (see \ref{type1afm}), which are designed to read a few font file
names from the commandline, the overhead in configuration file searching and
path reading is much too large. Moreover, to insist on a font database file
might grow to a real disadvantage. In the subsequent paragraphs we should thus
discuss how we can deviate from the initialization scheme described above.

\subsubsection{Fine Control over Font Databases and File Search Paths}
\label{manipulatingpaths}%
First, it is important to mention that it is generally possible to force
\verb+T1_InitLib()+ to skip steps 4 and / or 5 as described above. 

The configuration file is discarded by OR'ing the parameter \verb+log+ of
\verb+T1_InitLib()+ with \verb+IGNORE_CONFIGFILE+.
The default paths or the paths explicitly specified by the application before
are then left untouched during initialization.

Discarding the font database specification from the configuration file is
achieved by bitwise OR'ing \verb+log+ with \verb+IGNORE_FONTDATABASE+. The
result after initialization will be an empty database. This is valid in V.\ 
0.5 and newer since fonts may be added to the database at runtime.

Using the two flags described above, an installed setup can be ignored and an
application may have complete control over its search paths. There are a
number of functions for this purpose and each of these functions allows to
specify exactly {\em one} path element at a given time. Using special
characters like white space or path separators in a path element is thus not
an issue.

The font database may explicitly be specified by the
application using \precorr
\begin{verbatim}
 int T1_SetFontDataBase( char *filename)
\end{verbatim}\index{\verb+T1_SetFontDataBase()+}\postcorr
\verb+filename+ is the pointer to a string containing the name of the font
database file that is to be examined. This function replaces any set of font
databases setup previously and is thus usually to be called before
\verb+T1_InitLib()+. A call to this function after initialization will return
the result -1 and \verb+T1_errno+ will be set to
\verb+T1ERR_OP_NOT_PERMITTED+. For the special case that the font database is
still epmty after initialization this function may also be called after
initialization. But in any case, the database must be empty! For the latter
cases, fonts specified in the new database file are then immediately inserted
into the database. In case of success, the number of available fonts is returned. 

There is also the function \precorr
\begin{verbatim}
 int T1_AddFontDataBase( int mode, char *filename)
\end{verbatim}\index{\verb+T1_AddFontDataBase()+}\postcorr
It can be called at any time and \verb+filename+ is the string of the new font
database's file name. If called before initialization, the parameter
\verb+mode+ can be either \verb+T1_APPEND_PATH+ or \verb+T1_PREPEND_PATH+ and
the name of the new font database simply is either appended or prepended to
the existing list of font databases. Then, the function returns $0$. 

If the function is called after initialization, the parameter \verb+mode+ is
ignored and the new database is appended in any case, because this is the only
meaningful action. Furthermore, the new database is immediately loaded and the
function returns a number indicating the number of available fonts 
(which can also be 0). In the case of an error, \verb+T1_AddFontDataBase()+
returns $-1$.

There is also a pair of functions that act on the list of XLFD font database
files, 
\precorr
\begin{verbatim}
 int T1_SetFontDataBaseXLFD( char *filename)
\end{verbatim}\index{\verb+T1_SetFontDataBaseXLFD()+}\postcorr
\precorr
\begin{verbatim}
 int T1_AddFontDataBaseXLFD( char *filename)
\end{verbatim}\index{\verb+T1_AddFontDataBaseXLFD()+}\postcorr
These functions have exactly the same syntax and semantics as the functions
just described above. Standard font database files and XLFD font database
files are handled in separate lists internally, so that setting the XLFD font
database will not affect explicit standard font database settings.  However,
the default standard font database (\verb+./FontDataBase+) will be cleared
when at least one XLFD font database is specified. This is because the default
font database is meant as a fallback, and the fallback case is no longer given
if a XLFD font database has been specified.

A similar manipulation as just described for font database files, is
possible for the searchpaths. (Re-)Defining a search 
path is done by calling 
\precorr
\begin{verbatim}
 int T1_SetFileSearchPath( int type, char *pathname)
\end{verbatim}\index{\verb+T1_SetFileSearchPath()+}\postcorr
before calling \verb+T1_InitLib()+, or respectively, before the database
contains any fonts. An attempt to set the file searchpaths when the database
is no longer empty is denied. The reason is that it is not wise to override
the searchpaths which had been valid previously during the verification of the
existence of font files. Such paths should thus not be removed.  The parameter
\verb+pathname+ points to the string that contains the pathname that should be
used as searchpath. The parameter \verb+type+ is any OR'ed combination of
\verb+T1_PFAB_PATH+, \verb+T1_AFM_PATH+ and \verb+T1_ENC_PATH+. These tell the
function to set the search paths for Type 1 font files, AFM files and encoding
files, respectively. In case of an error \verb+-1+ is returned and otherwise
\verb+0+.

Extending the file searchpaths before {\em and} after initialization
is possible using 
\precorr
\begin{verbatim}
 int T1_AddToFileSearchPath( int pathtype, int mode, char *pathname)
\end{verbatim}\index{\verb+T1_AddToFileSearchPath()+}\postcorr
This might be useful to locate font files that were of no interest
at the time of initialization. 
\verb+pathname+ is the pointer to the string that should be added to the
searchpaths. Only {\em one} particular path element may be specified in one
call. What searchpaths are affected is determined by the parameter
\verb+pathtype+. Again, similar to described above, any
OR'ed combination of \verb+T1_PFAB_PATH+, \verb+T1_AFM_PATH+ and
\verb+T1_ENC_PATH+ is valid. There are two ways to extend an existing
searchpath which are specified by the \verb+mode+ parameter. It must be either
\verb+T1_APPEND_PATH+ or \verb+T1_PREPEND_PATH+, which causes the new path
element to be appended or prepended to the existent path respectively.
Since an existent path specification is not overwritten by
\verb+T1_AddToFileSearchPath()+, this function may be called at any time
before or after initialization.

It might also be of interest to query the current file search
paths and font databases. \tonelib\ provides 
\precorr
\begin{verbatim}
 char *T1_GetFileSearchPath( int type)
\end{verbatim}\index{\verb+T1_GetFileSearchPath()+}\postcorr 
for querying search paths. Again, the parameter \verb+type+ determines what
search path is returned. Exactly one of \verb+T1_PFAB_PATH+,
\verb+T1_AFM_PATH+, \verb+T1_ENC_PATH+ and \verb+T1_FDB_PATH+ should be
specified. If more than one path is specified, the first match wins and only
one path is returned. The types will be checked in the order
\verb+T1_PFAB_PATH+, \verb+T1_AFM_PATH+, \verb+T1_ENC_PATH+ and
\verb+T1_FDB_PATH+. Here, \verb+T1_FDB_PATH+ indicates an interest in the list
of font databases. The paths are separated using the current path separator. 


\subsubsection{Adding Fonts to the Database} 
\label{addingfonts}%
Extending the font database is possible at any time after initialization. In
addition to using \verb+T1_AddFontDataBase()+ (see above), it is done via a
call to \precorr
\begin{verbatim}
 int T1_AddFont( char *fontfilename)
\end{verbatim}\index{\verb+T1_AddFont()+}\postcorr
\verb+fontfilename+ is the pointer to the filename string. The following
actions take place:
\begin{itemize}
\item The font file is searched using the current search path specifications. 
\item If the file has been located, it is checked whether the font database
  contains enough memory to hose an additional font. 
  If so, the font filename
  is stored and the function returns \verb+new_ID+, which is the font ID that
  will be associated with this font in the future. 
\item If there was no free memory for an additional font, the memory is
  reallocated to a greater size. This involves also resetting the new
  area. Finally the value \verb+new_ID+ is returned.
\end{itemize}
If a negative value is returned the function failed. \verb+-1+ indicates the
font file could not be located. \verb+-2+ or \verb+-3+ are returned if a
memory allocation failure occurs.


\subsubsection{Summary of Search Path Handling}

Since the exact handling of search path specifications at the several stages
may appear somewhat confusing we shall summarize the exact rules now:
\begin{enumerate}
\item {\bfseries Before Initialization}\\
  Default paths are not yet setup. Each call of one of the \verb+T1_Set...()+
  functions described above establishes a completely new respective path. Each
  call of one of the \verb+T1_Add...()+ functions extends the respective path
  in the desired manner, or creates a new respective path if previously no
  path existed.
\item {\bfseries At the Beginning of the Initialization}\\
  Each path type for which a path had not already been explicitly created
  using the\\ \verb+T1_Set...()+ or \verb+T1_Add...()+ functions receives a
  default value. This is ``\verb+.+'' for the file search paths and
  \verb+./FontDataBase+ for the font database.
\item {\bfseries During Initialization}\\
  Each path element read from the configuration file overwrites an existing
  respective default path but preserves an existing respective explicitly
  setup path by appending to the latter. The newly setup search path is used
  to locate files while scanning the font database file(s).
\item {\bfseries After Inititialization but before the Database is being
    filled}\\ 
  At this stage, all \verb+T1_Set...()+ and \verb+T1_Add...()+ functions still
  work as described under~(1). Notice that this phase usually is not
  accessible when using the standard initialization scheme. It only becomes
  accessible if no fonts have been added during initialization.
\item {\bfseries After at least one Font is insterted into the Database}\\
  Once there are fonts in the database, the paths setup up
  to now must be preserved in any case. Hence, the \verb+T1_Set...()+ may not
  be called any longer. The \verb+T1_Add...()+ functions {\em extend} the
  current set of search paths. In particular, possibly existing default search
  path elements, then, are not overwritten any longer because they might have
  been used before to verify the existance of required files. 
\end{enumerate}
A call to \verb+T1_AddFontDataBase()+ will not only append the specified
file name to the existing list of databases, but will also immediately
locate the fonts specified therein and assign additional font IDs.


\subsubsection{Bypassing the \tonelib\ File Search Machinery} 
\label{afmfilenames}%
Usually, \tonelib\ takes care for locating files according to the path
specifications in the configuration file. There might, however, arise the need
to explicitly tell \tonelib\ which particular file to use. Forcing \tonelib\ to
use particular Type 1 font files can be achieved using the function
\verb+T1_AddFont()+, described just above. If a pathname passed to this
function is a complete path, \tonelib\ will use this complete path to locate
the font file, forgetting about its own search path list. A filename path is
assumed to be complete if 
\begin{itemize}
\item it starts with the directory separator character, usually
  ``\verb+/+''. In this case it is an {\em absolute} path specification, meaning
  that the start point is at the root of the filesystem, or
\item if it starts with ``\verb+./+'' or ``\verb+../+'' (where it is assumed
  that ``\verb+/+'' is the directory separator character). Here we have a {\em
    relative} path specification in which ``\verb+.+'' refers to the current
  working directory while ``\verb+..+'' refers to the parent directory of the
  current working directory. Since the notion of the {\em current working
    directory} is fundamental for every process that has access to a
  filesystem, a relative path specification also uniquely identifies one
  particular file in the filesystem.
\end{itemize}
If a font file whose complete path had been specified could not be found by
\tonelib, the paths from the configuration file are searched as a fallback
mechanism. 

What can be done for the Type 1 font files is also possible for AFM files,
which are needed on a per-font basis. The function
\precorr
\begin{verbatim}
 int T1_SetAfmFileName( int FontID, char *afm_name)
\end{verbatim}\index{\verb+T1_SetAfmFileName()+}\postcorr
allows to set the complete path of the AFM file belonging to the font
identified by \verb+FontID+, overriding the internal
search mechanism. This function is to be called after initialization but
before the font \verb+FontID+ is loaded. It returns 0 if all goes right and
$-1$ otherwise. In the latter case \verb+T1_errno+ will also be set
appropriately. Notice that \verb+FontID+ must also be valid with respect to
its upper limit, it is an error condition if the font database has less than
\verb+FontID+ entries. 

There is also the function 
\precorr
\begin{verbatim}
 char *T1_GetAfmFileName( int FontID)
\end{verbatim}\index{\verb+T1_GetAfmFileName()+}\postcorr
which allows to query the AFM filename of a font. It returns a pointer to the
filename if it had explicitly been specified or \verb+NULL+
otherwise. \verb+NULL+ will also be returned if \verb+FontID+ was invalid. In
this case also \verb+T1_errno+ will be set.  

Just for the sake of completeness we should mention that what has been said 
about absolute and relative path specification
also applies to pathnames for encoding files (see \ref{encoding}).




\subsection{The \tonelib-Logfile}
\label{logfile}%
Since version 0.2-beta \tonelib\ supports a runtime logfile.
It implements an uncomplicated way to keep track of errors,
warnings, statistics and debug messages without overloading stdout/stderr. As
seen in \ref{initialization} the user must specify whether or not to use a
logfile when calling \verb+T1_InitLib()+. Specifying \verb+LOGFILE+ as
argument leads to using a logfile and \verb+NO_LOGFILE+ suppresses the use of a
logfile.

The name of this logfile is by default \verb+t1lib.log+. This name is defined
in \verb+t1misc.h+ and can be changed there as the user likes.

Basically \tonelib\ distinguishes 4 types of runtime messages. Each type is
associated a ``loglevel'':
\begin{itemize}
\item {\sl Errormessages/Level1:}\/ They are considered that important that the user is
  in any case informed. Example: During initialization the memory allocation for
  one of the basic data structures of \tonelib\ failed.
\item {\sl Warningmessages/Level2:}\/ They are considered important but it is not
  absolutely necessary to inform the user. Example: An AFM file could not be
  loaded for a given font. This imposes several restrictions on what can be
  done with that font but it is possible to generate bitmaps.
\item {\sl Infomessages/Level3:}\/ They do not indicate a problem. Rather, the user
  is notified about some facts and statistics that might be of
  interest. Example: After loading a font the consumption of virtual memory is
  displayed. 
\item {\sl Debugmessages/Level4:}\/ These can be pointers, numerical data
  etc. Example: Print out the pointers that point to the memory area where the
  PostScript dictionaries for a font just loaded are located.
\end{itemize}
The decision what message to put into the logfile is done by examining the
value of an integer variable whose values can be \verb+T1LOG_ERROR+ (=1),
\verb+T1LOG_WARNING+ (=2), \verb+T1LOG_STATISTIC+ (=3) or \verb+T1LOG_DEBUG+
(=4). All messages whose level is below or equal to this value are put into the
logfile. The user may set this loglevel by calling
\precorr
\begin{verbatim}
 void T1_SetLogLevel( int level)
\end{verbatim}\index{\verb+T1_SetLogLevel()+}\postcorr
The default value is \verb+T1LOG_WARNING+ which means that error and warning
messages are stored in the logfile. 

If the usage of a logfile has been specified, \tonelib\ tries first to open
it in the current directory. If this fails for some reason \tonelib\ tries
to create it in the user's home directory. If this fails too, an error message
is printed to stderr and no logfile is used.

If the application programmer chose not to create a logfile, it would be hardly
possible for a user to track down possible problems, e.g. in file
searching. To overcome this disadvantage, the user may set an environment
variable \verb+T1LIB_LOGMODE+ at runtime. This variable is evaluated by
\tonelib\ when \verb+T1_InitLib()+ is called. If its value is one of the
four strings \verb+logDebug+, \verb+logStatistic+ \verb+logWarning+ and
\verb+logError+, the respective loglevel is set by \tonelib\ and a log file is
created, even if the programmer chose not to do so. However, if the programmer
had altered the log level after calling \verb+T1_InitLib()+, this cannot be
catched by setting the environment variable. A log file is created anyhow so
that at least error messages will be logged.

The user himself may also put some messages into the logfile. This can be
achieved using
\precorr
\begin{verbatim}
 void T1_PrintLog( char *func_ident, char *msg_txt, int level, ...)
\end{verbatim}\index{\verb+T1_PrintLog()+}\postcorr
where \verb+func_ident+ is a pointer to a string identifying the function that
generates the message. \verb+msg_txt+ points to the text string to put
out. The distinction between a function identifier and a message text is only
formal, indicating the user should identify the function that generates the
message. 

The string \verb+msg_txt+ may contain format character sequences, \verb+%..+ ,
as known from the \verb+printf+- or \verb+scanf+ standard \verb+C+
functions. In this case, the ellipses indicate that a variable list of further
arguments may follow. The \verb+level+ specification works as
described above: The message is only put out if the internal loglevel is
equal or greater than \verb+level+. 

Here is a typical example of a log file after a (short)
\verb+xglyph+-session in which the loglevel was set
\verb+T1LOG_STATISTIC+. Among several informative messages of type S, also two
messages of type W have been generated. They stem from trying to
raster the character ``\ss'' which was not in the current encoding. 
\par\noindent
{%
\tiny
\begin{verbatim}
(S) (Mon Jul 14 18:27:34 1997) T1_InitLib(): Initialization started 
(S) (Mon Jul 14 18:27:34 1997) T1_InitLib(): Initialization succesfully finished 
(S) (Mon Jul 14 18:27:44 1997) T1_LoadFont(): VM for Font 0: 35132 bytes 
(S) (Mon Jul 14 18:27:44 1997) CreateNewFontSize(): New Size 100.000000 created for FontID 0 (antialias=0) 
(S) (Mon Jul 14 18:27:53 1997) CreateNewFontSize(): New Size 100.000000 created for FontID 0 (antialias=1) 
(S) (Mon Jul 14 18:27:53 1997) CreateNewFontSize(): New Size 200.000000 created for FontID 0 (antialias=0) 
(W) (Mon Jul 14 18:27:53 1997) T1_SetChar(): No black pixels found for character 223 from font 0, returning NULL 
(W) (Mon Jul 14 18:27:53 1997) T1_SetStringX(): T1_SetChar() returned NULL-pointer! 
(S) (Mon Jul 14 18:27:55 1997) T1_DeleteSize(): Size 200.000000 deleted for FontID 0 (antialias=0) 
(S) (Mon Jul 14 18:27:55 1997) T1_DeleteSize(): Size 100.000000 deleted for FontID 0 (antialias=0) 
(S) (Mon Jul 14 18:27:55 1997) T1_DeleteSize(): Size 100.000000 deleted for FontID 0 (antialias=1) 
\end{verbatim}
}

\subsection{Generating Bitmaps}
\label{generatingbitmaps}%
At this point, you are able to generate a bitmap.
As said before, a character- or string-bitmap is given to the user as
an object of type \verb+GLYPH+. We should briefly explain \verb+GLYPH+
here. The type is defined by
\begin{verbatim}
typedef struct
{
  char *bits; 
  struct          
  {
    int ascent;
    int descent;
    int leftSideBearing;
    int rightSideBearing;
    int advanceX;
    int advanceY;
  } metrics;
  void *pFontCacheInfo;
  unsigned long bpp;
} GLYPH;
\end{verbatim}
\verb+bits+ is a pointer to the bitmap data. The
bitmap is organized in lines, starting with the uppermost line.
Each bitmap pixel is usually represented by one bit. If the width of
the 
bitmap is not an integer multiple of 8, the lines are padded with
zeros, so that each line starts at a byte boundary. Note that the
bitmap has no margins taken into account. The bitmap occupies the
minimum area the character needs to be painted. 

The bitmap pointer may also be
the \verb+NULL+-pointer. In this case, the glyph contains no foreground
pixels. The metrics of the corresponding glyph should be valid,
though. Typically, this appears for the space character as well as in
situations where an undefined or unencoded character had been substituted by
the \verb+.notdef+-character within the rastering functions.

Note that the \verb+pixmap+-entry which has been present in version 0.3-beta,
has been removed with version 0.4-beta. See the discussion on the X11-interface
in \ref{x11interface} for an explanation of this.

The struct \verb+metrics+ contains metric information that is needed
to position the character and to describe the character origin
with respect to the bitmap. The members in detail:
\begin{itemize}
\item \verb+metrics.ascent+: describes how many lines the bitmap
  ranges above the line $y=0$. 
\item \verb+metrics.descent+: describes how many lines the bitmap
  ranges below the line $y=0$. Width below $y=0$ counts negative so that the
  difference \verb+ascent+ $-$ \verb+descent+ is the
  total height of the bitmap, the number of lines.
\item \verb+metrics.leftSideBearing+: The amount of spacing between
  the origin of a character and the x-coordinate of its leftmost
  painted pixel. One could also name it ``left margin'' of the
  character. 
\item \verb+metrics.rightSideBearing+: The horizontal difference between
  the origin of a character and the x-coordinate of its rightmost
  painted pixel. This definition stands in contrast to some other
  interpretations of the right side bearing, where it is assumed as the
  difference between the glyph's width and its right most pixel.
\item \verb+metrics.advanceX+: The amount of position increment in
  horizontal direction after this character
  bitmap (or string bitmap) has been placed. It is almost always
  larger than the bitmap width because most characters contain a
  certain amount of margins. Note that this value is not suitable for internal
  computations of character positions since it contains the horizontal
  escapement rounded to the pixel grid. Using this value for such computations
  leads to accumulating positioning errors.
\item \verb+metrics.advanceY+: The amount of position increment in
  vertical direction after this character
  bitmap (or string bitmap) has been placed. Upper direction counts positive. 
\end{itemize}
As seen, the width of the bitmap is given as the difference between
\verb+rightSideBearing+ and \verb+leftSideBearing+ and the values
\verb+metrics.leftSideBearing+, \verb+metrics.descent+,\\
\verb+metrics.rightSideBearing+ and \verb+metrics.ascent+ effectively describe
the bounding box of the glyph.

The entry \verb+pFontCacheInfo+ is not currently used but will
probably later when font caching is really
implemented. Moreover, there's a certain chance that some other
entry will be added in future releases.

The member \verb+bpp+ is used to store the depth of the bitmap. For
true bitmaps, it is always 1. See \ref{antialiasing} for an
explanation. 

There are three basic functions which produce pointer to glyph objects. In
order to generate the glyph for a single character you would use the
function 
\precorr 
\begin{verbatim}
 GLYPH *T1_SetChar( int FontID, char charcode, 
                    float size, T1_TMATRIX *transform)
\end{verbatim}\index{\verb+T1_SetChar()+}\postcorr
As in most other functions, \verb+FontID+ is a valid identification
number of a font. It can range from 0 to $n-1$, where $n$ is number of
fonts declared in the font database file.

The second argument \verb+charcode+ determines the character that will
be rasterized.
As mentioned earlier, the encoding mechanism is used for
accessing the output character. This means, if \verb+'A'+ is given as
the character code, the machine representation of \verb+'A'+ is used
as an index into the current encoding vector. In this encoding vector,
the characters' name is looked up. Encoding vectors may be changed by
the user (see \ref{encoding}).


The parameter \verb+size+ is interpreted in Postscript's bigpoint-unit
(bp). By default, 
1 bp equals one device pixel. 

\verb+transform+ specifies the transformation that will be applied to the
character before rastering. If this pointer is \verb+NULL+, no transformation
is used. Otherwise it should point to a valid \tonelib-transformation matrix.
Please refer to \ref{transformations} for information on how to easily create
\verb+T1_TMATRIX+ matrices.
Hinting is only performed if the transformation is a pure rotation and if the
the angle is one of 0, 90, 180 or 270 degrees. Otherwise font level and
character level hinting information is ignored.

Bitmaps of transformed characters are never saved in
cache memory since I assume that they are rarely needed. The overhead
to manage transformed characters in cache would be overkill and would
significantly increase memory consuming. Anyhow, this would only work
for some dedicated transformations.

\verb+T1_SetChar()+ in fact does some more things than simply
rastering the specified character:
\begin{itemize}
\item It checks whether the font in question is already loaded. If not,
  it is loaded. 
\item If the size dependent data structures for the size in question
  do not exist, it creates them and inserts them in the linked list of
  size dependent data structures.
\item It checks if the character is already existent in cache. If so,
  it returns the data from cache.
\end{itemize}

Some words concerning memory management: The memory used by
the \verb+GLYPH+-structure is static in this function. The memory
required for the bitmap is also allocated by the function itself.
This means, the user doesn't need to free any memory by
himself. Every time \verb+T1_SetChar()+ is called, it starts by giving the
memory needed for the last generated glyph free or respectively
setting metric values to 0. Thus, do not free the
returned glyph pointer since later \verb+T1_SetChar()+ will free
memory that is no more allocated and probably used for some other purpose.
If you really like to free the memory, set the pointer to \verb+NULL+
afterwards. 

If an error occurs at some point, \verb+T1_SetChar()+ returns a
NULL-pointer to the user.

Frequently it is advantageous to raster a series of
characters at once. This has the advantage that internal accuracy may
be used and the overhead for the user is minimal. For such cases, the
function 
\precorr
\begin{verbatim}
 GLYPH *T1_SetString( int FontID, char *string, int len, 
                      long spaceoff, int modflag, 
                      float size, T1_TMATRIX *transform)
\end{verbatim}\index{\verb+T1_SetString()+}\postcorr
is provided.
It can be considered an extended version of \verb+T1_SetChar()+. The
same as said above applies to the arguments \verb+FontID+,
\verb+size+ and \verb+transform+. But a few additional arguments are
needed here. 

\verb+string+ is a series of bytes representing the indices into the current
encoding vector. 
The \verb+len+-parameter is needed because we cannot imply that string
is always an object like a string in C. For example, the Computer
Modern Roman fonts contain the uppercase Greek Gamma (\char0) at
position 0 in their internal encoding. In a string to be typeset the
value 0 is thus a valid value and deserves no special
treatment. Hence, we cannot not use the C-function \verb+strlen()+ to
compute the length of the string. However, since in most usual encodings
the special value 0 is not encoded (``\verb+.notdef+''), it makes
sense to switch between 
standard situations and non-standard situations:
\begin{itemize}
\item If \verb+string+ is a string conforming with C-semantics,
  \verb+len+ can be set to 0. Then, the length of the string is
  internally computed.
\item If \verb+string+ contains one or more control characters which make
  processing impossible, the \verb+len+-value must be specified
  explicitly. 
\end{itemize}

The \verb+spaceoff+ parameter is important for word processing
purposes. The value specified here is interpreted as an offset to the
space width used during rastering. It is interpreted in charspace
units, i.e., $1/1000$ bp. Every time a space character is requested,
this amount of horizontal escapement is added to the natural
spacewidth of the current font. Note that the space character itself
is actually not rastered. All requests to the character with the
charactername ``\verb+space+'' are caught by \tonelib\ and converted
to a simple horizontal escapement. For computation of the resulting
spacewidth, the width of the space-character is taken from the
AFM data and merged with the specified offset, which may also be
negative.\footnote{One consequence of this handling is, that---with a
  little tricking---fonts that do not define a space character
  themselves may be used for typesetting. This applies to the
  dc-fonts, which only define a visible space, but no real space (see
  \ref{fonts}).}

The \verb+modflag+ argument may be used to specify some option to the
rastering function. It is generally 0 or an OR'ed combination of the following
names:
\begin{itemize}
\item \verb+T1_KERNING+: As the name implies, this argument
  determines that pairwise kerning information from the AFM file is to be taken
  into account during string rastering. Not specifying \verb+T1_KERNING+ 
  means: ``omit kerning''. It is generally
  recommended to use kerning information since this improves the optical
  appearance. However, many lower quality fonts do not have kerning
  information.  With \tonelib\ V.\ 0.4-beta, kerning information is accessible
  much faster than before because it is based on char codes rather than on
  characternames.
\item \verb+T1_RIGHT_TO_LEFT+: Setting this flag will invert the writing
  direction. In {\em Right-To-Left} mode the escapement in writing direction
  (left) is inserted before placing the character with the result that the
  character laps over to the left side. This principle is kept for all
  characters in the string. Note that metrics of fonts that are intended for
  {\em Right-To-Left} typesetting have the same meaning as for fonts intended
  for standard ({\em Left-To-Right}) typesetting.
\item \verb+T1_UNDERLINE+: The string to be rastered is to be underlined
  according to the line specifications of the current font. 
\item \verb+T1_OVERLINE+: The string to be rastered is to be over lined.
\item \verb+T1_OVERSTRIKE+: Same here for overstriking. 
\end{itemize}
For a description of underlining and such, see \ref{underlining}. Notice also
that the \verb+modflag+ argument is a replacement of the \verb+kerning+
argument from pre-0.7 versions of \tonelib.

Concerning glyph-memory considerations, the same applies as said under
the description of \verb+T1_SetChar()+: Never free a pointer to memory
which was returned by \verb+T1_SetString()+. Or, alternatively, if freeing
the pointer cannot be avoided set it to NULL after freeing it.\footnote{For
  example, {\tt XDestroyImage()} gives the pixel memory for the image
  data free although it might not have been allocated by any X11-function.} 

There are two generic ways how a string-glyph can be produced. The first is to
take the paths of all characters needed, concatenate them, insert space and
kerning amounts as needed and raster the resulting whole path. This will yield
the best results since the average position accuracy of the pixels will be
optimal. This applies especially for rotated strings. The drawback is, that
every character must be rastered every time it is needed. There is no way to
access the bitmap data of a character inside a rastered string separate from
others. And the caching of string-glyphs at this programming level doesn't
make any sense. So this principle takes significantly longer than
concatenating bitmaps from a cache area. However, it is done when the
specified rotation angle is not equal to $0^\circ$ or when even further
transformation are to be applied.  This condition should limit the total
number of situations when this happens to an amount we can easily bear.

If the \verb+transform+-argument is \verb+NULL+ we know transformations or
rotation should not be applied and another approach is used. We are then able
to construct the resulting bitmap by adjusting already existent bitmaps into
proper positions.  If a character does not already exist in the cache, it is
generated just the way \verb+T1_SetChar()+ works. The calculation of the
character-bitmap positions in the output bitmap is done with
char space-precision.  Nonetheless, there may be differences in the output
compared with output of the above method. These are caused by the fact that
rounding to pixel accuracy has already been achieved when generating the
character bitmap. Thus, the output of the above principle should always be
better since the positions of the black pixels are rounded with respect to the
whole string, and not with respect to a single character glyph. On the other
hand, concatenating character glyphs takes significantly less time than
rastering a complete string.  Theoretically, differences of up to two pixels
horizontal shift may appear in the output of the two principles. You can
check the effect by running the program \verb+xglyph+. Specify a string of
enough length and raster it at angle $0^\circ$. Then specify a very small
angle from 0 different, say, $0.001^\circ$, and raster the string again with
the new setting. You might find that the representation of the string is a
little different now.

The third function that creates a glyph object is 
\precorr 
\begin{verbatim}
 GLYPH* T1_SetRect( int FontID, float size,
                    float width, float height,
                    T1_TMATRIX *transform)
\end{verbatim}\index{\verb+T1_SetRect()+}\postcorr
Calling this function yields a filled rectangle. It is intended for situations
where a \TeX-style \verb+\vrule+ would be appropriate, or, for equations in
mathematical typesetting. 

First, the argument \verb+FontID+ identifies a valid font. At this time, it is
not obvious why a valid font is required in order to create a rectangular
glyph. The reason is, that some of the parameters that are associated to a
particular font are also relevant for creating rectangles in the context of
that font. Hence, specifying a font identifier in this case is a means of
stating ``{\em draw a rectangle that visually fits to the style of the font
  \verb+FontID+}''. Aside from this, I assume that each application that uses
\tonelib\ deals with at least {\em one} font so that the \verb+FontID+
parameter actually does not hurt.

The size of the rectangle is to be specified in charspace units by means of
the parameters \verb+width+ and \verb+height+, and is moreover subject to
scaling through the parameter \verb+size+. By definition, the typographical
fundamental area of a font, known as the {\em em-square}, is just as high and
as wide as the design size of the font. In charspace units, this rectangle
exactly maps to a $1000 \times 1000$ grid. Or alternatively spoken, one
charspace unit is 0.001bp (Big Point). For example, in order to draw an
em-square for some font at 13 points, the correct parameters are
\hbox{\verb+size+ $= 13$}, \hbox{\verb+width+ $= 1000$} and
\hbox{\verb+height+ $= 1000$}. If absolute physical dimensions are desired,
the scaling explicitly must be calculated by the user. For instance, in order to
produce a $ 1 \mathrm{cm} \times 1 \mathrm{cm}$ square we find
\begin{displaymath}
h = w = 1\mathrm{cm} \frac{72\mathrm{bp}/\mathrm{in} \times
  1000\mathrm{cs}/\mathrm{bp}}{2.54\mathrm{cm}/\mathrm{in}} 
\approx 28346\;\mathrm{cs.}
\end{displaymath}
Here ``cs'' designates charspace units and \verb+size+ is assumed to be $1$.
Note that still the device resolution must be properly setup in order to make
the dimensions appear accurately on the device.

The parameter \verb+transform+ is a pointer to a \tonelib\ transformation
matrix. If it is \verb+NULL+, the current transformation of the font in
question is used. Depending on the kind of actual transformation, the
rectangle might also image as a nonrectangular shape. This happens, if the
current font is slanted, then the rectangle will be skewed.

Glyphs produced by the rectangle function are never cached because there is
no means in doing so. With respect to memory management, the same applies as
for \verb+T1_SetChar()+ and \verb+T1_SetString()+. Since rectangles rarely are
used to produce normal text flow, the glyphs produced by the rectangle
function do not cause any escapement.


If two glyphs with arbitrary orientation exist,
\precorr
\begin{verbatim}
 GLYPH *T1_ConcatGlyphs( GLYPH *glyph1, GLYPH *glyph2,
                         int x_off, int y_off, int modflag)
\end{verbatim}\index{\verb+T1_ConcatGlyphs()+}\postcorr
can be used to concatenate them. First the size of the resulting glyph is
computed and its metric values are filled. Then, the two glyphs are placed at
their appropriate positions in the newly created bitmap. In order to be able
to work, the following conditions must be met:
\begin{enumerate}
\item Either glyph must be different from \verb+NULL+.
\item Both glyphs must have identical \verb+bpp+-values. If antialiased and
  non-antialiased glyphs are to be concatenated, have a look at
\item There must be enough memory for the new glyph (naturally).
\end{enumerate}
The quantities \verb+x_off+ and \verb+y_off+ describe the $x$- and
$y$-component of an optional offset to be inserted between the two
glyphs. This offset is interpreted as device pixels. The \verb+modflag+
argument is used to specify the direction in which the two glyphs are to be
concatenated. That is, only the bit \verb+T1_LEFT_TO_RIGHT+ /
\verb+T1_RIGHT_TO_LEFT+ is respected by this function.

If problems occur, \verb+NULL+ is returned.
It is generally not recommended to produce large glyphs with this function
because the char space precision in placing the character bitmaps is lost. For
example, three times rounding up an advance by 0.3 pixels accumulates to 1
pixel position error. A similar effect shows up when two rotated and underlined
glyphs are concatenated with this function. There might be a slight shift in the
baseline at the point where the two glyphs touch.

A dilemma occurs, if two antialiased bitmaps have distinct background
colors. Then, it is not clear what the transparent color
is. \verb+T1_ConcatGlyphs()+ always assumes the {\em current} background color
to be transparent.


There is one more function that generates pointers to glyphs:
\precorr
\begin{verbatim}
 GLYPH *T1_CopyGlyph(GLYPH *glyph)
\end{verbatim}\index{\verb+T1_CopyGlyph()+}\postcorr
As mentioned earlier, the user doesn't have the possibility of keeping
the  
glyphs longer than to the next call of the respective rastering function. If 
someone wants to keep a bitmap some time longer,  
\verb+T1_CopyGlyph()+ may be used
to copy the glyph to another area which is then completely under user's
control. This function simply does the following:
\begin{itemize}
\item Allocates the memory for the glyph-structure.
\item If bitmap data is present, it allocates memory for the bitmap data,
  taking the member \verb+bpp+ into account (see \ref{antialiasing}).
\item Copies the structure and the bitmap data to the respective locations.
\item Initializes the pointer \verb+glyph.bits+.
\end{itemize}

Return value is the pointer to the allocated glyph-structure. If something
goes wrong, NULL is returned to indicate an error. A glyph pointer,
returned by a call to this function should be freed by a call to
\verb+T1_FreeGlyph()+ (see \ref{deletingdata}).


\subsection{Loading Fonts Explicitly}
\label{loading}%
Usually there is no need for a user to load a font into memory since this is
done automatically as needed by the rastering functions. But there are two
situations where it makes sense to explicitly load a font before generating
any size dependent data:
\begin{itemize}
\item A font is to be reencoded immediately after loading (see \ref{encoding}).
\item A font is to be transformed (see \ref{transformations}).
\end{itemize}
These operations require a font being loaded but not having any size specific
data. Loading a font explicitly is done by the function
\precorr
\begin{verbatim}
 int T1_LoadFont( int FontID)
\end{verbatim}\index{\verb+T1_LoadFont()+}\postcorr
Loading a font involves several actions:
\begin{itemize}
\item Locating and loading the Type 1 font file.
\item Locating and loading the font metrics data from AFM file.
\item Computing and filling the values of the \verb+FONTPRIVATE+ structure as
  described in section \ref{internals}.
\item Setting up some tables for fast access of metrics information.
\end{itemize}
\verb+T1_LoadFont()+ returns \verb+0+ if successful or \verb+-1+ if the font
could not be loaded. A failure may be due to \tonelib\ not having been
initialized or due to problems with file locations and file parsing. If a font
refuses to load, the logfile should be examined first. Furthermore, in case of
a failure \verb+T1_errno+ will be set appropriately.


\subsection{Functions for Encoding Handling}
\label{encoding}%
As mentioned earlier, the encoding mechanism used in the
PostScript-language allows a font to contain more than 256 different
characters, although only 256 are accessible at a given time. The
characters which are accessible are given by the elements of the
current {\em encoding vector}. In order to maximize flexibility,
\tonelib\ allows for changing the current encoding vector. This is
also called ``Reencoding a font''. A new encoding vector is defined
and made known to the library by creating an encoding-file and loading
its contents into memory. 
Before describing the functions needed for this, we should
briefly describe the format of an encoding file. 

An encoding file is an ASCII text file. No
assumptions about filename extensions are made. Here are the rules for
scanning the file:
\begin{itemize}
\item The file contents are completely ignored until a line is encountered
  that starts with the string \verb+Encoding=+. This string may optionally be
  immediately followed by a string that is assumed to be the identifier of the
  {\em encoding scheme} that this file defines. Any further text on this line
  is ignored.
\item Now, 256 lines have to follow, each line describing one
  character's name. The string ranging from the beginning of the line
  to the first white space character is assumed to be a character
  name. The remainder of the lines is ignored and may (should) be used
  for comments, thereby describing the current character code.
\item All further lines of text are ignored.
\end{itemize}
As well known from PostScript, non-existent characters have to be
named \verb+.notdef+.

Here's an example of such an encoding file:
\begin{verbatim}
Sample encoding file for t1lib!
The first two lines are considered to be comments!
Encoding=ISOLatin1Encoding       
.notdef                          /* '000  000  "00 */ 
.notdef                          /* '001  001  "01 */ 
.notdef                          /* '002  002  "02 */ 
  .                                   .
  .                                   .
  .                                   .
greater                          /* '076  062  "3E */
question                         /* '077  063  "3F */
at                               /* '100  064  "40 */
A                                /* '101  065  "41 */
B                                /* '102  066  "42 */
  .                                   .
  .                                   .
  .                                   .
yacute                           /* '375  253  "FD */
thorn                            /* '376  254  "FE */
ydieresis                        /* '377  255  "FF */ 
\end{verbatim}

Since V.~1.2, \tonelib\ is also able to load encoding files in the format used
by \verb+dvips+. This makes a large set of existing encoding files available
to the user. When parsing \verb+dvips+ encoding files, \tonelib\ requires
PostScript syntax. This means white space may be interspersed freely and
line comments are defined by the character \%. The mark-characters, \verb+[+
and\verb+]+, are considered as special tokens and need not be preceded or
followed by white space. Similarly, the literal escape character \verb+/+
delimits a preceding token without interspersed white space. When parsing
\verb+dvips+ encoding files, \tonelib\ tolerates less than 256 character name
definitions. If characters are missing, they are substituted by \verb+.notdef+
until the counter reaches $256$. Aside from comments, no PostScript tokens are
allowed after the encoding definition in a \verb+dvips+ encoding file is
complete.

With the defining terms above, it turns out that a file which has successfully
been scanned as a \verb+dvips+ encoding file, cannot specify a valid \tonelib\
encoding after the PostScript encoding definition is complete (because no
valid character name can start with \% and because at least a line such as
\verb+Encoding=+, would have to follow the PostScript encoding). Hence the
file format are mutually exclusive and it is possible to read both format
using one function. In a first pass \tonelib\ tries to read the file as a
\verb+dvips+ encoding file, and if that fails, it assumes to have a \tonelib\
encoding file. 


Once such an encoding file of either type has been created, it can be loaded
into memory. This is done with the function
\precorr
\begin{verbatim}
 char **T1_LoadEncoding( char *filename)
\end{verbatim}\index{\verb+T1_LoadEncoding()+}\postcorr
The function will use the search path definitions read from
the configuration file during initialization (see
\ref{runtimesetup}, \verb+ENCODING=+). If no
errors occur, an array of pointers to strings is created and
initialized. The start address of this pointer array is returned as a
double pointer to a char. This pointer is intended
to be used to reencode a font via \verb+T1_ReencodeFont()+. If the encoding
data structure could not be created, \verb+NULL+ is returned to indicate the
error. 

The memory allocated by \verb+T1_LoadEncoding()+ is organized in two
continuous blocks. One block is the pointer array of size 257\footnote{This
  number results from 256 charactername pointers plus one pointer to the
  encoding scheme identifier.} and the
other block contains the character name strings plus the encoding scheme
specification, separated by
ASCII-zeros. 
This memory can be returned to the system using the function 
\precorr
\begin{verbatim}
 int T1_DeleteEncoding( char **Encoding)
\end{verbatim}\index{\verb+T1_DeleteEncoding()+}\postcorr
\tonelib\ does not check whether a valid pointer value was passed. So be
careful to pass the correct pointer. An error in this function should almost
always be followed by a segmentation violation.

A newly loaded encoding is applied to an existent font by
calling 
\precorr
\begin{verbatim}
 int T1_ReencodeFont( int FontID, char **Encoding)
\end{verbatim}\index{\verb+T1_ReencodeFont()+}\postcorr
\verb+FontID+ must be a valid font identification and
\verb+Encoding+ a pointer returned from a
successful call to \verb+T1_LoadEncoding()+. 

There are two requirements
in order to reencode a font:
\begin{enumerate}
\item The font must already have been loaded into memory. 
\item No size-dependent data exists for this font. If
  it does, it must be removed explicitly prior to calling
  \verb+T1_ReencodeFont()+. 
\end{enumerate}

It follows that there are two ways to reencode a font. The first is
to load a font explicitly and reencode it before any size dependent
data is created. The second is to use an automatically loaded font
and delete all of its size dependent data before reencoding it.

The user may also specify the special pointer NULL as the
\verb+Encoding+-argument. This would reencode the font to its internal
encoding vector.

In case of success, the function returns 0, otherwise -1 is returned.

Reencoding a font takes a considerable amount of time since the mapping tables
have to be reorganized. In situations where it is \`a priori foreseeable that the
font will be reencoded using some standard encoding vector, it makes sense to
assign that particular encoding vector as the default encoding vector,
thereby overwriting the internal encoding vector of each font at load time
before the mapping tables are setup. Setting the default encoding can be
achieved using 
\precorr
\begin{verbatim}
 int T1_SetDefaultEncoding( char **Encoding)
\end{verbatim}\index{\verb+T1_SetDefaultEncoding()+}\postcorr
Here \verb+Encoding+ encoding is assumed to be a valid \tonelib\ encoding
vector, e.g., created by a call to \verb+T1_LoadEncoding+.
\verb+T1_SetDefaultEncoding()+ has to be called after initialization. It
returns \verb+0+ if this condition is fulfilled and \verb+-1+
otherwise. In the latter case \verb+T1_errno+ is set appropriately. 
Notice that the internal encoding of the font is still accessible by
reencoding the font using \verb+NULL+ as encoding specification (see above). 
Note further that the default encoding vector is only applied to those font
that have \verb+StandardEncoding+ as internal encoding. This is to prevent
fonts like ZapfDingbats, Symbol or Sonata\footnote{A musical notation font.}
from being reencoded automatically at load time because this would be
surely inappropriate for such fonts.

It is also possible to query the encoding scheme that the font associated with
\verb+FontID+ uses. This is achieved with the function
\precorr
\begin{verbatim}
 char *T1_GetEncodingScheme( int FontID)
\end{verbatim}\index{\verb+T1_GetEncodingScheme()+}\postcorr
The return value is a pointer to a string which describes the encoding scheme
in question. The are 3 possible cases:
\begin{itemize}
\item The font uses Adobe StandardEncoding, which is internally known by the
  rasterizer. Then, \verb+StandardEncoding+ is returned.
\item The font defines its own encoding by \hbox{\verb+dup+ $n$ {\em
      LiteralName} \verb+put+} statements. In this case no particular name is
  associated with the encoding scheme and \verb+FontSpecific+ is returned.
\item The encoding is externally loaded by \verb+T1_LoadEncoding()+. Then the
  encoding scheme entry of this file is returned. If this (optional) entry is
  not specified in the file, \verb+Unspecified+ is returned.
\end{itemize}
Notice that the name of the encoding scheme is also accessible as
\verb+Encoding[256]+ where \verb+Encoding+ is the pointer returned by a
successful call to \verb+T1_LoadEncoding()+.

\subsection{Deleting Data}
\label{deletingdata}%
In frequently appearing cases, it may be wise to return some memory
which was explicitly 
or automatically allocated by the library back to the
system.\footnote{This is especially true, since there is presently no
  caching algorithm which automatically takes care of this.} For
this purpose 
some functions are available. To understand how size dependent
data for a font is organized, see (\ref{internals}).

The memory amount required by the size-dependent data of \verb+size+
and font \verb+FontID+ is freed by calling the function 
\precorr
\begin{verbatim}
 int T1_DeleteSize( int FontID, float size)
\end{verbatim}\index{\verb+T1_DeleteSize()+}\postcorr
The data deleted includes the metric
information for 256 characters, some pointers, associated bitmap data (if
already existent) as well as the font matrix for that size.

As described in section \ref{internals}, the data structures containing
size-dependent information of a particular font are organized as a
linked list. \verb+T1_DeleteSize()+ takes care that a properly linked
list is left after deleting the data.

If the combination of \verb+size+ and \verb+FontID+ does not exist, -1
is returned. If the operation was successful, the return value is 0.

For the purpose of removing all size-dependent data for a particular
font, there is the function
\precorr
\begin{verbatim}
 int T1_DeleteAllSizes( int FontID)
\end{verbatim}\index{\verb+T1_DeleteAllSizes()+}\postcorr
It recursively removes all size-dependent data for the font
\verb+FontID+. This may be appropriate if a user knows some font not
to be needed any longer. This function is also to be used, if one intends to
reencode a font for 
which size dependent data has already been generated. In addition,
 font transformations
such as {\em slanting} and {\em extending} 
require a font having no size-specific data. 
\verb+T1_DeleteAllSizes()+ recursively calls \verb+T1_DeleteSize()+ to
do its job.
It returns the number of sizes removed (including 0 if no sizes were
existent) or -1 if an error occurred.

It is also possible to remove the entire data  associated with a
particular font from memory using
\precorr
\begin{verbatim}
 int T1_DeleteFont( int FontID)
\end{verbatim}\index{\verb+T1_DeleteFont()+}\postcorr
\verb+T1_DeleteFont()+ goes one step beyond the above functions and
removes all the data associated with the font \verb+FontID+. This
includes:
\begin{itemize}
\item All size dependent data.
\item All data from the Type 1 font program, held in memory.
\item All AFM data kept in memory. 
\end{itemize}
The memory reserved for a font in hierarchy-level 1 is not returned to
the system since it is simply one element in the array of structures of
type \verb+FONTPRIVATE+ (see \ref{internals}). But all entries in this
structure are reset to initial values.

Whether it is useful or not, a font that has been removed using
\verb+T1_DeleteFont()+ may also be loaded again, explicitly or
implicitly.

There is a restriction, which has not yet been mentioned: A font may only be
removed if it is a physical font (to be explained later) to which no logical
fonts refer or if it is a logical font.\footnote{See \ref{logicalfonts} for
  explanation of logical fonts.} A reference counter is maintained in each
physical font to check for this. If the font to be removed is a logical font,
the \verb+FONTPRIVATE+ area is reset and the reference counter of the
referenced physical font is decremented. Of course, size dependent data is
removed in every case.

\verb+T1_DeleteFont()+ returns 0 if the font has been removed correctly or if
the font was not loaded. $n$ ($>0$) is returned if
the font was physical and was referenced by $n$ logical fonts. A
return value -1 indicates an invalid \verb+FontID+.

The function 
\precorr
\begin{verbatim}
 int T1_FreeGlyph( GLYPH *glyph)
\end{verbatim}\index{\verb+T1_FreeGlyph()+}\postcorr
returns memory allocated by
\verb+T1_CopyGlyph()+ back to the system. This function should not be
applied to the pointer to a glyph returned by one of the rastering
functions. As said earlier, these functions manage the memory areas by
themselves. 

Similarly, the function
\precorr
\begin{verbatim}
 int T1_FreeCompCharData( T1_COMP_CHAR_INFO *cci)
\end{verbatim}\index{\verb+T1_FreeCompCharData()+}\postcorr
returns memory associated to the composite caracter data structures, as
allocated and returned by \verb+T1_GetCompCharData()+ or
\verb+T1_GetCompCharDataByIndex()+ (see
Section~\ref{subsec:CompositeCharacters}), to the system. In order to avoid
memory leaks, each call of the latter two functions should be followed by a
call to this function.


In order to close the library and return all memory to the system, 
\precorr
\begin{verbatim}
 int T1_CloseLib( void)
\end{verbatim}\index{\verb+T1_CloseLib()+}\postcorr
should be used. If no problems occur, 0 is returned. The value 1 indicates
problems during freeing data. In this case the logfile should be examined. 
After having freed all data the file search paths, if different from the
defaults, are restored. Last, the logfile  is closed.


\subsection{Underlining, Overlining and Overstriking}
\label{underlining}%
\tonelib\ supports underlining, overlining and overstriking for the string
rastering functions. These lines are always drawn on the fly as the bitmaps
are generated. In writing direction, the lines range from the glyph's origin
to the glyph's width. The vertical dimensions are set the following way by
default when a font is loaded:
\begin{itemize}
\item {\bf Underlining}: Underline position and thickness are taken from the
  Fontinfo dictionary of the respective font. The rule is vertically centered
  with respect to the mathematical line given by the position value.
\item {\bf Overlining}: The position is computed to be $y=a+|u|$ where $a$
  corresponds to the typographic ascender and $u$ is the underline position
  from the Fontinfo dictionary. As above, the rule is vertically centered
  around this position value. The thickness is set to underline thickness.
\item {\bf Overstriking}: The position is $y=a/2$ where again $a$ is the
  typographic ascender of the font and vertical alignment of the rule is done
  by centering around the computed position. The thickness is set to underline
  thickness. 
\end{itemize}
As all information in AFM files, thickness and position specifications are
interpreted in charspace units.

Notice that the typographic ascender is not determined by the Type 1 font
program. It has to be guessed by \tonelib. The problem of guessing the
typographic ascender is discussed in more detail in \ref{writingafmfiles}.
When loading a font, this typographic ascender is assumed to be the vertical
coordinate of the upper right corner of the bounding box of the letter ``d''.
This is not as advanced as the procedure described in \ref{writingafmfiles},
but it suffices because the underlining positions can later be overwritten by
the user (see below).

From the mathematical point of view, the line rules are an integral part of
the rastered path. It follows that line rules may appear sheared if a font has
been artificially slanted and the size and/or thickness is sufficiently large.

A look into real Type 1 font files shows that even fonts of the same family
possess incompatible values for underlining. For example, Bitstream Charter
Roman defines underline thickness to be 61 and its bold variant assigns a
value of 90. Underlining text consisting of Roman and bold words will not be
very pleasing using these values. For this reason \tonelib\ provides a way for
explicitly setting and overwriting the default values for line ruling on a
per-font level. The functions 
\precorr
\begin{verbatim}
 int T1_SetLinePosition( int FontID, int linetype, float value)
\end{verbatim}\index{\verb+T1_SetLinePosition()+}\postcorr
and
\precorr
\begin{verbatim}
 int T1_SetLineThickness( int FontID, int linetype, float value)
\end{verbatim}\index{\verb+T1_SetLineThickness()+}\postcorr
set the respective value for font \verb+FontID+ to \verb+value+.
The \verb+linetype+ argument is assumed to be an OR'ed combination of
\verb+T1_UNDERLINE+, \verb+T1_OVERLINE+ and \verb+T1_OVERSTRIKE+. While it
generally does not make sense to specify identical positions for two or three
distinct line rule types, it is meaningful to specify identical thickness
values for two or all rules types. However both functions accept combinations
of linetype specification.
It follows that consistent line ruling for several fonts can be achieved by
setting the line rule parameters of the involved fonts to identical respective
values.

Currently active line rule parameters can be queried using the functions
\precorr
\begin{verbatim}
 float T1_GetLinePosition( int FontID, int linetype)
\end{verbatim}\index{\verb+T1_GetLinePosition()+}\postcorr
and
\precorr
\begin{verbatim}
 float T1_GetLineThickness( int FontID, int linetype)
\end{verbatim}\index{\verb+T1_GetLineThickness()+}\postcorr
In case more than one line rule type is specified for
\verb+linetype+ the first matching value is returned, 
since obviously the functions can only return {\em one} value. The order the
argument is checked is \verb+T1_UNDERLINE+, \verb+T1_OVERLINE+ and
finally \verb+T1_OVERSTRIKE+. 

These functions called with \verb+T1_UNDERLINE+ as line type argument should
not be confused with the functions \verb+T1_GetUnderlinePosition()+ and
\verb+T1_GetUnderlineThickness()+ respectively. The latter functions will
always return the values from the Fontinfo dictionary as opposed to the former
which will return the currently active values. 

Since line ruling is done on the fly, it is possible to change the involved
parameters in the middle of a session without confusing the cache or removing
size dependent data.


\subsection{Common Information on Fonts and Characters}
\label{common}%
This subsection describes some functions making common information
available. This includes Type 1 and AFM data. Thus, these
functions partially depend on the existence of AFM data. In order not
to have to specify this data every time, here are a few conventions:
\begin{enumerate}
\item \verb+FontID+ is the valid ID of a declared font.   
\item All functions that require a character index as argument
  use the currently active encoding vector to determine the
  character's name 
  belonging to this index and use the character's name to search for the
  information required.
\item Some functions do not allow to use the return value for error
  checking. For this reason every function described in this subsection will
  set \verb+T1_errno+ appropriately if something goes wrong. See
  \ref{errorhandling} for the description of the possible values of
  \verb+T1_errno+. 
\item None of the functions described in this subsection will load a font
  automatically. 
\end{enumerate}

\subsubsection{Information from FontInfo-Dictionary}
\label{fontinfodict}%
\precorr
\begin{verbatim}
 char *T1_GetFontName( int FontID)
\end{verbatim}\index{\verb+T1_GetFontName()+}\postcorr
This function returns the string object \verb+FontName+ from the
fontinfo-dictionary of the specified font or a NULL pointer if the font is not
loaded.

The memory for the returned string is static in this function and should thus
not be freed by the user. As another consequence, the returned
string is only constant until the function is called the next time.

\precorr
\begin{verbatim}
 char *T1_GetFullName( int FontID)
\end{verbatim}\index{\verb+T1_GetFullName()+}\postcorr
This function returns the string object \verb+FullName+ from the
fontinfo-dictionary of the specified font or a NULL pointer if the font is not
loaded.

The memory for the returned string is static in this function and should thus
not be freed by the user. As another consequence, the returned
string is only constant until the function is called the next time.

\precorr
\begin{verbatim}
 char *T1_GetFamilyName( int FontID)
\end{verbatim}\index{\verb+T1_GetFamilyName()+}\postcorr
This function returns the string object \verb+FamilyName+ from the
fontinfo-dictionary of the specified font or a NULL pointer if the font is not
loaded.

The memory for the returned string is static in this function and should thus
not be freed by the user. As another consequence, the returned
string is only constant until the function is called the next time.

\precorr
\begin{verbatim}
 char *T1_GetWeight( int FontID)
\end{verbatim}\index{\verb+T1_GetWeight()+}\postcorr
It returns the Weight entry from fontinfo dictionary. It is a string
entry and represents a verbatim classification of the font rather than
a numerical quantity. In case of an error \verb+NULL+ is returned.

\precorr
\begin{verbatim}
 float T1_GetItalicAngle( int FontID)
\end{verbatim}\index{\verb+T1_GetItalicAngle()+}\postcorr
The returned value is the italic angle of the font in degrees as a
float. Notice that the meaning of ItalicAngle is related to the slanting
of fonts, but not in the sense of \tonelib\ (see
\ref{transformations}). 
An italic font may be artificially slanted and an artificially slanted
font in the sense of \tonelib\ may have an italic angle of zero. 

\precorr
\begin{verbatim}
 int T1_GetIsFixedPitch( int FontID)
\end{verbatim}\index{\verb+T1_GetIsFixedPitch()+}\postcorr
This function returns 0 if the font's spacing is proportional and 1 if
it is fixed. 

\precorr
\begin{verbatim}
 BBox T1_GetFontBBox( int FontID)
\end{verbatim}\index{\verb+T1_GetFontBBox()+}\postcorr
This function returns the bounding box of the font identified by
\verb+FontID+. It is the bounding box that 
results if all characters of a font are overlayed with their reference point
falling on the point (0,0). All values are in charspace units. The members
\verb+lly+ and \verb+urx+ represent the fonts overall descent and ascent,
respectively. 

The font's bounding box is part of the AFM information as well as member in
the font's private dictionary. It turns out that the information from
\verb+.afm+- and \verb+.pfa+/\verb+.pfb+-file is not consistent for some
fonts. \tonelib\ returns the information stored in the font-file itself, since
I assume it is more consistent to the font's data.

\precorr
\begin{verbatim}
 float T1_GetUnderlinePosition( int FontID)
\end{verbatim}\index{\verb+T1_GetUnderlinePosition()+}\postcorr
This function returns the underline position of the specified font as given in
the fontinfo-dictionary. The value is to be interpreted in charspace
units. If the font is not loaded, 0 is returned since an
underline position of 0 can be considered impossible for most fonts.

\precorr
\begin{verbatim}
 float T1_GetUnderlineThickness( int FontID)
\end{verbatim}\index{\verb+T1_GetUnderlineThickness()+}\postcorr
This function returns the thickness of the underlining rule for this font or 0
if the font is not loaded. 0 is a safe index for an error since a rule of
height 0 would not be visible anyhow. 

\precorr
\begin{verbatim}
 char *T1_GetVersion( int FontID)
\end{verbatim}\index{\verb+T1_GetVersion()+}\postcorr
The version string from the Type 1 font file is returned. The memory
where the string is located is managed by the function itself.

\precorr
\begin{verbatim}
 char *T1_GetNotice( int FontID)
\end{verbatim}\index{\verb+T1_GetNotice()+}\postcorr
The notice string from the Type 1 font file is returned. Again the
user should not touch the memory where the string is located.

\subsubsection{Metric Information on Glyphs}
\label{metricinformation}%
\precorr
\begin{verbatim}
 int T1_GetCharWidth( int FontID, char char1)
\end{verbatim}\index{\verb+T1_GetCharWidth()+}\postcorr
The character width according to the AFM information is returned in charspace
units. If no AFM information is available, 0 is returned. 

The width of a
character is the amount of horizontal escapement that the next character is
shifted to the right with respect to the current position. This information is
not given in the character's bounding box. Also, the width corresponds to the
entry \verb+characterWidth+ in the \verb+glyph+-structure, as described in
\ref{generatingbitmaps}. But since \verb+T1_GetCharWidth()+, returns its
result in charspace units, the accuracy is much higher than using the value
of the \verb+glyph+-structure which has only pixel-accuracy.

If there is an extension specified for the font in question, the characters
width is corrected correspondingly. 

\precorr
\begin{verbatim}
 BBox T1_GetCharBBox( int FontID, char char1)
\end{verbatim}\index{\verb+T1_GetCharBBox()+}\postcorr
The character's bounding box of \verb+char1+ is returned with the elements to
be interpreted in charspace units. The bounding box of a character is defined
to be smallest rectangle aligned parallel to the $x$- and $y$-axis of
the character 
coordinate system which encloses the painted area of the character
completely. This rectangle is completely specified by specifying its
lower left and its upper 
right corner. From a programmer's point of view, a characters bounding
box is defined by the following struct of type \verb+BBox+:
\begin{verbatim}
typedef struct
{ 
   int llx;     /* lower left x-position  */
   int lly;     /* lower left y-position  */
   int urx;     /* upper right x-position */
   int ury;     /* upper right y-position */
} BBox;
\end{verbatim}
In case the character is not encoded or no AFM data is available, a box
containing only zeros is returned.

The bounding box is corrected if an extension value has been applied
to the font in question.

Since version 0.3-beta, slanted fonts are fully supported, meaning that for
slanted fonts too a correct bounding box will be returned. This is however
quite time expensive since the characters' real outline must be considered.
See the discussion on slanting a font  (\ref{transformations}) for an
explanation of this.


\precorr
\begin{verbatim}
 int T1_GetStringWidth( int FontID, char *string,
                        int len, long spaceoff, int kerning)
\end{verbatim}\index{\verb+T1_GetStringWidth()+}\postcorr
\precorr
\begin{verbatim}
 BBox T1_GetStringBBox( int FontID, char *string,
                        int len, long spaceoff, int kerning)
\end{verbatim}\index{\verb+T1_GetStringBBox()+}\postcorr
These two functions represent the complement to the above functions on the level
of strings. All parameters that take influence on the resulting width and
bounding box must be given in the argument list. Their meaning is identical to
the meaning they have when calling string rastering functions (see
\ref{generatingbitmaps}). 


\precorr
\begin{verbatim}
 METRICSINFO T1_GetMetricsInfo( int FontID, char *string,
                                int len, long spaceoff, int kerning)
\end{verbatim}\index{\verb+T1_GetMetricsInfo()+}\postcorr
In certain situations bounding box and width of a glyph are required both. In
these cases it is more convenient to call \verb+T1_GetMetricsInfo()+ which
returns a structure that contains all information. \verb+METRICSINFO+ is
defined in \verb+t1lib.h+ as:
\begin{verbatim}
typedef struct
{
  int      width;
  BBox     bbox;
  int      numchars;
  int      *charpos;
} METRICSINFO;
\end{verbatim}
All numbers are to be interpreted in character space units --- they are
directly taken from AFM data. \verb+width+ is the glyph's width and
\verb+bbox+ its bounding box which in turn is a struct as defined some
paragraphs above.

\verb+numchars+ is assigned number of characters in string. If the argument
\verb+len+ is different from 0, \verb+numchars+ is assigned that value.

\verb+charpos+ is a pointer to an integer array of size \verb+numchars+
allocated by \verb+T1_GetMetricsInfo()+. During execution this array is filled
step by step with the horizontal escapement in character space units of the
respective character relative to the start point of the string glyph which
corresponds to 0. \verb+charpos+ remains valid until
\verb+T1_GetMetricsInfo()+ is called the next time. The user should not
free this memory because this is handled automatically.

The terms concerning the bounding box of slanted fonts mentioned under the
description of \verb+T1_GetCharBBox()+ apply here as well. The first and the
last character of \verb+string+ have to be observed spending high effort.
But nevertheless the correct bounding box is returned.

\precorr
\begin{verbatim}
 int T1_GetKerning( int FontID, char char1, char char2)
\end{verbatim}\index{\verb+T1_GetKerning()+}\postcorr
This function returns the amount of kerning for the specified character
pair \verb+char1+ and \verb+char2+. If an extension has been specified
for the font (see \ref{transformations}), the amount of
kerning is automatically corrected using the extension factor. The
value returned has to be interpreted in charspace units.

If no AFM information is available for the font in question, simply 0
is returned. The same applies if the font is not loaded.

The implementation of this function requires that the kerning pairs in
the AFM file are sorted in alphabetical order. I am not sure
whether this condition is found in the specification of the AFM file
format. If this function doesn't work although AFM kerning data is
available, this might be the reason.

\precorr
\begin{verbatim}
 int T1_QueryLigs( int FontID, char char1,
                   char **successors, char **ligatures)
\end{verbatim}\index{\verb+T1_QueryLigs()+}\postcorr
This function implements the interface to the ligature information in
the AFM data. Ligatures are special character-symbols which are
substituted if special pairs, 
triples or whatever groups of characters appear in a string. For example,
``f{}i'' is replaced with the ligature ``fi''. In this example, the ``i'' is
called {\em successor} and the ``fi'' is the associated ligature.

\verb+char1+ is the character
which has to be checked for ligatures, i.e., the first character of a possible
ligature group. \verb+successors+ and \verb+ligatures+ should be addresses of
pointers to \verb+char+s. These pointers are modified by the
\verb+T1_QueryLigs()+. 

First, \verb+T1_QueryLigs()+ checks how many ligatures are defined for the
character given by \verb+char1+. Assuming this number is $n$, it then
defines memory for two arrays of type \verb+char+ with size
$n$. These arrays are filled with the indices of the
successor-characters and with 
the indices of the associated ligatures, respectively. The current 
encoding vector is used for this. The addresses of these two arrays
are written to the
addresses of the respective  pointers \verb+successors+ and \verb+ligatures+.
They are thus later available to the user in order to access the memory where
the successor-character and ligatures are specified. The value $n$ is returned
in order to tell the user how many ligatures were found and to give
the user information about the end of the two arrays. 

If the font is not loaded or AFM data is not available, -1 is returned.

Since this may seem to be a little complicated, here is a programming example:
\begin{verbatim}
char *succ, *lig;
int n_lig, i;
char char1='f';

/* Get ligature information of character 'f' in font 0: */
n_lig=T1_QueryLig( 0, char1, &suc, &lig);

/* print out indices of characters and their ligatures */
for ( i=0; i<n_lig; i++;){
  printf("First char: %d, +  next char: %d --> ligatur: %d\n",
         char1,
         succ[i],
         lig[i]);
\end{verbatim}

Notice that the arrays where the successor indices and the respective
ligature indices are stored are static in
\verb+T1_QueryLigs()+. Thus, they may not be freed and moreover they
are only valid until the next time \verb+T1_QueryLigs()+ is called.


\subsubsection{Character-Encoding Relation}
\label{characterencodingrelation}%

\precorr
\begin{verbatim}
 char *T1_GetCharName( int FontID, char char1)
\end{verbatim}\index{\verb+T1_GetCharName()+}\postcorr
This function returns the name of the character indexed by \verb+char1+
according to the current encoding vector. As said above, the memory where the
string 
is stored is static to this function so that the user should not free the
returned pointer. If the font is not loaded, NULL is returned.

\precorr
\begin{verbatim}
 int T1_GetEncodingIndex( int FontID, char *char1)
\end{verbatim}\index{\verb+T1_GetEncodingIndex()+}\postcorr
This function is the complement to the above function. It returns the lowest
index of the character with the specified name in the current encoding vector
as an \verb+int+. If the charactername is not found in the current encoding
vector or if the font is not loaded, the value -1 is returned.

\precorr
\begin{verbatim}
 int *T1_GetEncodingIndices( int FontID, char *char1)
\end{verbatim}\index{\verb+T1_GetEncodingIndices()+}\postcorr
This function is an extension of the above function. It is meant for cases
where all appearences of \verb+char1+ in the encoding vector are requested.
The return value is an integer array whose elements contain the encoding
indices where \verb+char1+ appears in increasing order. The first negative
entry in this array indicates that no more valid indices will follow. In the
most extreme case we can think of (i.e., where the complete encoding vector is
occupied by {\em one} character), \verb+T1_GetEncodingIndices()+ will return
an array of size 257 where the first 256 elements bear their own index and the
257th element is $-1$. If font \verb+FontID+ is not loaded, this function
returns \verb+NULL+ and \verb+T1_errno+ will be set appropriately. If
\verb+char1+ was not found in the encoding vector, a valid array is returned
but the first element will be $-1$.


\precorr
\begin{verbatim}
 char **T1_GetAllCharNames( int FontID)
\end{verbatim}\index{\verb+T1_GetAllCharNames()+}\postcorr
As described in \ref{encoding}, not all characters of a font need to be
encoded. A Type 1 may contain the outlines of an arbitrary number of
characters, but only 256 can be encoded---and thus
accessed---simultaneously. Since the characternames are inside the encrypted
portion of 
the Type 1 font file, there is no easy way to find out which characters a font
defines. 

\tonelib\ provides \verb+T1_GetAllCharNames()+ for situations where a
programmer needs to know what characters are defined in the font file
identified by \verb+FontID+. The value returned is a pointer to an array of
\verb+char+ pointers which in turn point to the characternames.
The array's size is $(n+1)$ where $n$ is the number of defined outlines. The
$(n+1$)th pointer is \verb+NULL+ to indicate the end of the array.
An application programmer may use these characternames to construct a
specialized encoding vector. Here is an example of how to use
\verb+T1_GetAllCharNames()+. It prints a list of all defined characternames in
font 0.
\begin{verbatim}
 char **ptr;
 int i;
 .
 .
 .
 ptr=T1_GetAllCharNames( 0);
 i=0;
 while (ptr[i]!=NULL){
   printf("Charstring %d = %s\n", i, ptr[i]);
   i++;
 }
\end{verbatim}

The memory for storing the pointers and the charactername strings is static in\\
\verb+T1_GetAllCharNames()+. Thus it remains valid until the function is
called the next time. The user should not free this memory or if he does, he
should set the pointer to \verb+NULL+ to indicate the memory has already been
freed. 

\precorr
\begin{verbatim}
 int T1_GetNoKernPairs( int FontID)
\end{verbatim}\index{\verb+T1_GetNoKernPairs()+}\postcorr
This function returns the number of kerning pairs defined for the font
identified by \verb+FontID+. The number -1 is returned if an error occured and
\verb+T1_errno+ will be set. All positive numbers including 0 should be
considered valid return values.


\subsubsection{Administrative Information}
\label{administrativeinformation}%


\precorr
\begin{verbatim}
 int T1_GetNoFonts( void)
\end{verbatim}\index{\verb+T1_GetNoFonts()+}\postcorr
Usually, this function returns the number of fonts declared in the font
database file, i.e., the integer quantity from the first line of the font
database file. However, if some new fonts have been created using
\verb+T1_CopyFont()+ (see \ref{logicalfonts}) or if some fonts have
been added to the database 
after initialization (see \ref{addingfonts}), these are also taken into
account. The number returned by \verb+T1_GetNoFonts()+ minus 1
is thus the largest valid font ID specification.

\precorr
\begin{verbatim}
 int T1_CheckForInit( void)
\end{verbatim}\index{\verb+T1_CheckForInit()+}\postcorr
Use this function in order to check whether \tonelib\ is initialized. It
returns $0$ if initialization has already happened and $-1$ otherwise.

\precorr
\begin{verbatim}
 int T1_CheckForFontID( int FontID)
\end{verbatim}\index{\verb+T1_CheckForFontID()+}\postcorr
This functions gives information on the load status of the font associated to
\verb+FontID+. It returns $0$ if the font \verb+FontID+ has not yet been loaded,
$1$ if it has already been loaded. Finally, a return value of $-1$ indicates
that either \verb+FontID+ is an invalid specification or \tonelib\ is not
initialized. 


\precorr
\begin{verbatim}
 char *T1_GetFontFileName( int FontID)
\end{verbatim}\index{\verb+T1_GetFontFileName()+}\postcorr
This function returns a pointer to the fontfilename identified by
\verb+FontID+. In no case, this pointer may be freed since the memory is
static to this function. The string also is only valid up to the next call of
this function.

\precorr
\begin{verbatim}
 char *T1_GetFontFilePath( int FontID)
\end{verbatim}\index{\verb+T1_GetFontFilePath()+}\postcorr
This function returns a pointer to the fully qualified path of the font file
identified by \verb+FontID+. In no case, this pointer may be freed since the
memory is static to this function. The string also is only valid up to the
next call of this function.

\precorr
\begin{verbatim}
 char *T1_GetAFMFilePath( int FontID)
\end{verbatim}\index{\verb+T1_GetAFMFilePath()+}\postcorr
This function returns a pointer to the fully qualified path of the AFM file of
the font identified by \verb+FontID+, as used by \tonelib. In case of an error
\verb+NULL+ is returned. It may also happen that there exists no AFM file for
the font either because AFM information was generated on the fly at the time
the font was loaded, or because AFM processing had been disabled at
initialization time. For those cases \verb+T1_errno+ is not set.  

In no case, the returned pointer may be freed since the memory is static to
this function.  The string also is only valid up to the next call of this
function.

\precorr
\begin{verbatim}
 char *T1_GetLibIdent( void)
\end{verbatim}\index{\verb+T1_GetLibIdent()+}\postcorr
This function returns the identifier string for the version of \tonelib. For
example, this could be \verb+0.8-beta+. The string is static in this function
and should thus not be freed by the user.


\subsection{Transformation of Fonts}
\label{transformations}%
Transformation of
Type 1 fonts is generally accomplished by means of concatenating 
so-called transformation matrices. For example, rotation is 
equivalent to concatenation of
the standard transformation matrix with a special matrix whose elements are
trigonometric functions evaluated at the rotation angle. In the sense of
\tonelib, we distinguish between {\em fontlevel transformations} and {\em
  characterlevel transformations}.

\subsubsection{Fontlevel Transformations}
\tonelib\ supports three transformations that operate globally on a font's data.
After applying such a transformation to a font all characters generated from
then on will be rendered according to that transformation. Moreover, these
transformed characters are saved in cache for fast future access. This
principle is thus meant for transformed fonts which are semantically used as
ordinary text fonts. Creating a font Times-Oblique by slanting a Times-Roman
would be a typical example.

The first fontlevel transformation is called ``extension'' since it extents a font
horizontally---makes its characters wider. A font is extended by a call to the
function
\precorr
\begin{verbatim}
 int T1_ExtendFont( int FontID, double extend)
\end{verbatim}\index{\verb+T1_ExtendFont()+}\postcorr
A font that is to be extended may not have size dependent data. If size
dependent data exists, it must
explicitly be removed before applying an extension-factor. This is simply a
security mechanism which prevents the user from mixing up extended and
non-extended bitmaps. If the font is not loaded or size-dependent data is
existent, -1 is returned. Otherwise, the function returns 0.

All information on character metrics is automatically adapted to an
extension-factor different from 1 (see \ref{common}).

Applying an extension-factor to a font is implemented by replacing the current
extension-factor---initially 1---with the supplied value. Thus, an extension
can be deleted by specifying a factor 1. Moreover, extending a font two
times, say, with factor 2, does not yield a font extended by 4. Rather the
last specified extension, here 2, is applied.

The second type of fontlevel transformation supported by \tonelib\ is {\em
  slanting}.  It is done by a call to the function \precorr
\begin{verbatim}
 int T1_SlantFont( int FontID, double slant)
\end{verbatim}\index{\verb+T1_SlantFont()+}\postcorr
The slant-factor $s$ tells the rastering algorithm to advance the $x$-coordinate
of a given point by the product of $s$ with the $y$-coordinate of that
point. Such fonts are sometimes called {\em oblique}. Another interpretation
is that we state: $s=\tan(\alpha)$, where $\alpha$ is the well-known
italic-angle of the font. 

Just as above, no size-dependent data may be existent and the font must be
loaded. In that case 0 is returned, otherwise -1.

As above, the slanting operation is implemented by {\em setting} the
slant-factor so that a slant may be reset by means of specifying a
slant-factor of 0.

There is one thing that makes handling of slanted fonts more difficult than
handling of extended fonts. When
typesetting strings by concatenating bitmaps, exact information on character
metrics is necessary. By slanting a character the character's width is not
affected. But the bounding box is. And while extension---which means 
strictly horizontal scaling independent of the respective
y-coordinate---simply leads to an extension of the bounding box, there is no
way to compute the
bounding box of a slanted character from the bounding box of the respective
unslanted character. Here is an example.
\begin{itemize}
\item Let the character be \verb+\+. When slanting this character with a
  value of 1, the resulting character will be similar to a vertical line. The
  bounding box will thus be small in horizontal direction.
\item If character is \verb+/+, the resulting slanted
  character will tend to be more horizontal. Thus the resulting bounding box
  will be much extended in horizontal direction.
\end{itemize}
In conclusion
we can say that the effect of slanting on the bounding box of
a given character depends on the shape of the character itself. 

Since version 0.3-beta the problem with the bounding box of slanted characters
is handled as follows. The character in question is internally rastered at
1000 bp and the bounding box of the resulting ``edgelist'' is examined. But no
bitmap is generated for the character, this limits the computational effort.
However the difference in time performance between getting a bounding box from
a ``simple-shaped'' slanted character like ``i'' and getting a bounding box of
a ``complex-shaped'' character like ``Q'' is clearly noticeable.

The positioning algorithm for string bitmaps has been slightly improved in
\tonelib\ V.\ 0.3-beta so that now exclusively bitmap metrics are used where 
the bounding boxes are needed. The limitation of slanted fonts appears thus
only if a user explicitly requests a bounding box of a character/string in an
artificially slanted font.

The third and most common type of fontlevel transformation allows arbitrary
linear transformations. This is done by a call to the function 
\precorr
\begin{verbatim}
 int T1_TransformFont( int FontID, T1_TMATRIX *matrix)
\end{verbatim}\index{\verb+T1_TransformFont()+}
\postcorr
The transformation is specified by \verb+matrix+ (as described below).
This function acts by setting the font's transformation matrix to the
matrix pointed to by \verb+matrix+.

As a final consequence of what has been described so far in this section it
turns out that \verb+T1_TransformFont()+ overrides whatever slant and extension
values might have been set before. Conversely, if \verb+T1_SlantFont()+ or
\verb+T1_ExtendFont()+ are applied to a font after a call to
\verb+T1_TransformFont()+, the respective values are simply overridden, there
will be no concatenation. In the following description of transformation
matrices and their usage, we will also describe how to concatenate an
arbitrary series of linear transformations.

There are also functions for querying the current values of the quantities
described above for fontlevel transformations.
\precorr
\begin{verbatim}
 double T1_GetExtend( int FontID)
\end{verbatim}\index{\verb+T1_GetExtend()+}\postcorr
and
\precorr
\begin{verbatim}
 double T1_GetSlant( int FontID)
\end{verbatim}\index{\verb+T1_GetExtend()+}\postcorr
return the current extension and slant values. The function 
\precorr
\begin{verbatim}
 T1_TMATRIX T1_GetTransform( int FontID)
\end{verbatim}\index{\verb+T1_GetTransform()+}\postcorr
Returns the current transformation matrix as a structure of type
\verb+T1_TMATRIX+ which will be described in detail in the next subsubsection. 

\subsubsection{Transformation at Rastering Time}
This kind of transformation is the most generic one and allows arbitrary
transformations. A transformation $(x',y')^T$ of a given location $(x,y)^T$ is
given by the following set of linear equations:
\begin{eqnarray*}
x' & = a_{11} x + a_{21} y \\
y' & = a_{12} x + a_{22} y 
\end{eqnarray*}
Here, the matrix 
\begin{displaymath}
\mathbf{A}=
\left( 
\begin{array}{cc}
a_{11} & a_{21} \\
a_{12} & a_{22}
\end{array}
\right)
\end{displaymath}
is referred to as the {\em transformation matrix}. In \tonelib\ the following
type definition is used for such transformation matrices:
\begin{verbatim}
typedef struct
{
  double cxx;  /* corresponds to a11 */
  double cyx;  /* corresponds to a21 */
  double cxy;  /* corresponds to a12 */
  double cyy;  /* corresponds to a22 */
} T1_TMATRIX;
\end{verbatim}
Each of the rastering functions expects to get a pointer to an object of type
\verb+T1_MATRIX+, or \verb+NULL+ if no transformation is to be applied. 
If any transformation has been specified, the resulting glyph is never kept in
cache memory. Thus, if for some reason caching should be disabled for
non-transformed characters, simply a pointer to the
unity matrix 
%$\left( 
%\begin{array}{cc}
%1.0 & 0 \\
%0 & 1.0
%\end{array}
%\right)$ 
could be specified to the rastering function to achieve this.

The user has the possibility of either allocating and creating the
transformation matrices by himself or to use predefined functions of
\tonelib. There are 8 different functions for generating transformed
characters. Figure \ref{figure:transformations} gives an example of each
function using the character ``g''. 

\begin{figure}[t]
\hfill
\includegraphics[scale=0.5]{mirrorh}
\hfill
\includegraphics[scale=0.5]{mirrorv}
\hfill
\includegraphics[scale=0.5]{shearh}
\hfill\break
\noindent\vrule width 0pt\hfill\verb+T1_MirrorHMatrix()+\hfill
\verb+T1_MirrorVMatrix()+\hfill
\verb+T1_ShearHMatrix()+\hfill\break
% line 2
\vskip0.5cm
\hfill
\includegraphics[scale=0.5]{shearv}
\hfill
\includegraphics[scale=0.5]{extenth}
\hfill
\includegraphics[scale=0.5]{extentv}
\hfill\break
\noindent\vrule width 0pt\hfill\verb+T1_ShearVMatrix()+\hfill
\verb+T1_ExtendHMatrix()+\hfill
\verb+T1_ExtendVMatrix()+\hfill\break
% line 3
\vskip0.5cm
\hfill
\includegraphics[scale=0.5]{rotate}
\hfill
\includegraphics[scale=0.5]{arbitrary}
\hfill\break
\noindent\vrule width 0pt\hfill\verb+T1_RotateMatrix()+\hfill
\verb+T1_TransformMatrix()+\hfill\break
\vskip3mm
\hrule\vskip3mm\small
\caption{\label{figure:transformations}Typical examples for the predefined
  functions for generating transformation matrices in \tonelib, applied to the
  character ``g''.} 
\end{figure}

Before describing each particular function we should discuss the first
argument because this is common to all matrix transformation functions. This
first argument, in case it is not \verb+NULL+, is expected to be a pointer to
an already existent valid \verb+T1_TMATRIX+ object. The transformation to be
applied is then done by multiplying the existent matrix with the new
matrix. In other words, the existent matrix is replaced by the concatenation of
the two matrices. If a \verb+NULL+ is specified as argument, the new matrix is
allocated by the respective function and then set to the concatenation of the
unity matrix with the desired transformation. Thus, to remove a matrix from
memory, the pointer simply has to be given to \verb+free()+, no matter how
many transformations have been applied to this matrix before.

We should now describe the functions for generating transformation matrices:
\precorr
\begin{verbatim}
 T1_TMATRIX *T1_MirrorHMatrix( T1_TMATRIX *matrix)
\end{verbatim}\index{\verb+T1_MirrorHMatrix()+}\postcorr
and
\precorr
\begin{verbatim}
 T1_TMATRIX *T1_MirrorVMatrix( T1_TMATRIX *matrix)
\end{verbatim}\index{\verb+T1_MirrorVMatrix()+}\postcorr
simply change the sign of the matrix coefficients $a_{11}$ and $a_{22}$
respectively. This has the optical effect of mirroring the character at the
horizontal line $y=0$ or at the vertical line $x=0$, respectively. These
functions represent a specialized form of 
\precorr
\begin{verbatim}
 T1_TMATRIX *T1_ExtendHMatrix( T1_TMATRIX *matrix, float extent)
\end{verbatim}\index{\verb+T1_ExtendHMatrix()+}\postcorr
and
\precorr
\begin{verbatim}
 T1_TMATRIX *T1_ExtendVMatrix( T1_TMATRIX *matrix, float extent)
\end{verbatim}\index{\verb+T1_ExtendVMatrix()+}\postcorr
These functions allow arbitrary scaling in the respective coordinate
direction. Specifying \\
\verb+extent=-1+ exactly yields mirroring at the
corresponding axis. 

Furthermore, there are two transformations where one coordinate depends on
itself and on the other coordinate.  This is called shearing, slanting or also
obliqueing. It is possible in both directions using the functions 
\precorr
\begin{verbatim}
 T1_TMATRIX *T1_ShearHMatrix( T1_TMATRIX *matrix, float shear)
\end{verbatim}\index{\verb+T1_ShearHMatrix()+}\postcorr
and
\precorr
\begin{verbatim}
 T1_TMATRIX *T1_ShearVMatrix( T1_TMATRIX *matrix, float shear)
\end{verbatim}\index{\verb+T1_ShearVMatrix()+}\postcorr
In case of horizontal shearing, the factor \verb+shear+ is equal to
$\tan(\alpha)$, where $\alpha$ may be interpreted as the italic angle. It is
measured from the positive vertical axis in mathematical negative direction. 
Correspondingly, for vertical shearing \verb+shear+ equals $\tan(\beta)$,
where $\beta$ is the angle measured from the horizontal axis in mathematically
positive direction.

Rotation of glyphs is achieved using 
\precorr
\begin{verbatim}
 T1_TMATRIX *T1_RotateMatrix( T1_TMATRIX *matrix, float angle)
\end{verbatim}\index{\verb+T1_RotateMatrix()+}\postcorr
This function evaluates the trigonometric functions at the value of
\verb+angle+ and concatenates the transformation matrix with 
\begin{displaymath}
\left( 
\begin{array}{cc}
\cos(\alpha)  & -\sin(\alpha) \\
\sin(\alpha) & \cos(\alpha)
\end{array}
\right)
\end{displaymath}
$\alpha$ is expected to be specified in degrees. It is measured according
standard mathematical conventions.

There is one more function which allows to set all matrix coefficients
explicitly. It gives thus complete control over the transformation. This might
be necessary to typeset text in a circle, for example. The syntax of this
function is
\precorr
\begin{verbatim}
 T1_TMATRIX *T1_TransformMatrix( T1_TMATRIX *matrix, 
                                 float cxx, float cyx,
                                 float cxy, float cyy)
\end{verbatim}\index{\verb+T1_TransformMatrix()+}\postcorr

\subsubsection{{\tt t1lib} and PostScript: Notes on Transformation Matrices}
In order to avoid confusion about transformation matrices, we should briefly
discuss the differences between \tonelib- and PostScript transformation
matrices. In \tonelib-nomenclature a coordinate description is assumed to be
represented by a column vector $(x,y)^T$. In contrast, PostScript assumes a
coordinate to be represented by a row vector $(x,y)$. This leads to an
exchanged meaning of the second and third matrix element between \tonelib\ and
PostScript. From the mathematical point of view this is caused by matrix
transposition. To make this clear, let me quote the matrix 
\begin{displaymath}
\mathbf{A}_{\mbox{\footnotesize PostScript}}=
\left( 
\begin{array}{ccc}
a & b & 0\\
c & d & 0\\
t_x & t_y & 1
\end{array}
\right)
\end{displaymath}
from the PostScript Language Reference Manual (Adobe, Red Book). If we forget
about translation which in this sense is not implemented by \tonelib, we only
have to consider the top left submatrix consisting of $a$, $b$, $c$ and $d$.
The \tonelib-equivalent to this matrix would be written as
\begin{displaymath}
\mathbf{A}_{\mbox{\tt\footnotesize t1lib}}=
\left( 
\begin{array}{cc}
a & c \\
b & d \\
\end{array}
\right)
\end{displaymath}
I.e., the meaning of $b$ and $c$ is exchanged. Notice that font matrices as
found in Type 1 font files have to be interpreted according to the PostScript
notation. But a user should never come close to something other than the
\tonelib\ transformation matrices


\subsection{Stroking of Character Outlines}
\label{stroking}%
Most available Type 1 fonts internally specify the numeric value
\verb+PaintType+ as $0$. This indicates that the mathematical outline
definitions of the characters consist of paths that represent the left and
right---or inner and outer---borders of the character area to be filled with
ink. In particular, this means that every subpath of a character definition
must be closed. When filling characters, the curves that describe the outline
are infinitely thin and the area between paths is of interest. 

By contrast, there are fonts that specify \verb+PaintType+ as $1$. These are
also known as {\em stroked fonts}. Basically, their characters' shapes are
generated by travelling along the mathematically thin defining curves using a
pen with some finite width. The penwidth used here usually is specified in the
font itself by means of the quantity \verb+StrokeWidth+. 

Using a somewhat unusual implementation, \tonelib\ can
\begin{itemize}
\item image stroked fonts with \verb+PaintType+ 1,
\item stroke fonts that have \verb+PaintType+ 0,
\item deal with variable strokewidths for both paint types.
\end{itemize}
In particular at low resolutions and when using large penwidths, the results
of stroking may fall short of the quality of other general graphics tools like
e.g.~native PostScript interpreters. Also hinting generally is disabled when
creating stroked character outlines. For the interested reader, the
implementation of stroking is outlined in \ref{strokingimplementation}
(page~\pageref{strokingimplementation}). 

The process of stroking in \tonelib\ is treated similar to the process of
transformation. Therefore, firstly, a font can be generally switched to be a
stroked font. This is achieved using 
\precorr
\begin{verbatim}
 int T1_StrokeFont( int FontID, int dostroke)
\end{verbatim}\index{\verb+T1_StrokeFont()+}\postcorr
Here, \verb+FontID+ identifies the font to be switched. The parameter
\verb+dostroke+ determines the future rastering behavior. If it equals 0, the
font's characters will be filled and for any other value the characters will
be stroked. The function returns 0 in case of success.
\verb+T1_StrokeFont()+ requires the font \verb+FontID+ to be loaded. If the
font is not loaded \verb+T1_errno+ will be set appropriately and the function
returns -1. After switching a font to {\em stroked}, its characters are cached
as usual. It is therefore important that, at the time where
\verb+T1_StrokeFont()+ is called, no size-dependent data does exist. If this
condition is violated, the function will fail too and set \verb+T1_errno+ to 
\verb+T1ERR_OP_NOT_PERMITTED+.  

The second method to control the rasterizer mode for the font \verb+FontID+ is
to use the function pair
\precorr
\begin{verbatim}
 int T1_SetStrokeFlag( int FontID)
\end{verbatim}\index{\verb+T1_SetStrokeFlag()+}\postcorr
and
\precorr
\begin{verbatim}
 int T1_ClearStrokeFlag( int FontID)
\end{verbatim}\index{\verb+T1_ClearStrokeFlag()+}\postcorr
for enabling and disabling stroking, respectively.  These two functions return
0 on successful completion and -1 in case of a failure. They can only fail if
\verb+FontID+ is not valid, in which case \verb+T1_errno+ is set to
\verb+T1ERR_INVALID_FONTID+. Using these functions, switching the stroking is
hence possible at any time. The netto effect is that caching will be disabled
if the actually selected rasterizer mode does not match the one of the cached
characters. The performance then will degrade for the rasterizer mode that is
not the base mode of the font in question.

If stroked characters and filled characters are required for one particular
font while preserving good performance, using logical fonts is the tool of
choice (see Sec.~\ref{logicalfonts}, page~\pageref{logicalfonts}).

The currently active rasterizer mode for the font \verb+FontID+ can also be
queried. This is done using  
\precorr
\begin{verbatim}
 int T1_GetStrokeMode( int FontID)
\end{verbatim}\index{\verb+T1_GetStrokeMode()+}\postcorr
If \verb+FontID+ is not valid, $-1$ is returned and \verb+T1_errno+ is set to
\verb+T1ERR_INVALID_FONTID+. In any other case, the following values may be
returned: 
\begin{itemize}
\item \verb+0+: The rasterizer mode is {\em Fill} and filled characters are
  cached. For stroked fonts with a \verb+PaintType+ of $1$, of course, the
  characters are stroked and these stroked characters are cached anyhow.
\item \verb+1+: Stroking is enabled, while filled characters are cached. Each
  rasterization request is performed on the fly, as for nontrivial
  transformations.
\item \verb+2+: Filling is enabled but stroked characters are
  cached. Rasterization again is performed on the fly.
\item \verb+3+: Stroking is enabled and stroked characters are cached.
\end{itemize}

The width of the virtual pen used to trace the character outlines can also be
adjusted. The function
\precorr
\begin{verbatim}
 int T1_SetStrokeWidth( int FontID, float strokewidth)
\end{verbatim}\index{\verb+T1_SetStrokeWidth()+}\postcorr
sets up \verb+strokewidth+ as the pen width used to stroke characters from
font \verb+FontID+. It is interpreted in charspace units and hence directly
comparable to the \verb+StrokeWidth+ parameter of stroked fonts.
If this function succeeds, $0$ is returned. The function call might
also be unsuccessful, in which case $-1$ is returned. The value of
\verb+T1_errno+ then gives a hint to the reason of the failure. If set to
\verb+T1ERR_INVALID_FONTID+, the font was not loaded. The value
\verb+T1ERR_INVALID_PARAMETER+ indicates that a negative strokewidths has
been specified. Finally, \verb+T1ERR_OP_NOT_PERMITTED+ may appear if stroked
characters are cached for the font in question, size dependent data exists,
and the requested strokewidth did not equal the one used at the time where
the cache data initially has been built. Allowing to setup an arbitrary
strokewidth under the latter circumstances might fillup the cache for one font
with characters rasterized using inconsistent strokewidths, which has to be
avoided. From this discussion it becomes suggesting not to cache stroked
character at all, if stroking should be done using variable strokewidths.

The pen width for a given font \verb+FontID+ may be queried at any time using  
\precorr
\begin{verbatim}
 float T1_GetStrokeWidth( int FontID)
\end{verbatim}\index{\verb+T1_GetStrokeWidth()+}\postcorr
If the value $0.0$ is returned, this either indicates that the characters are
filled or that the font in question is not loaded. Then, \verb+T1_errno+ is
also set to \verb+T1ERR_INVALID_FONTID+.
 

\subsection{Antialiasing}
\label{antialiasing}%
\subsubsection{General Description} 
When fonts are displayed on screen at low sizes, the shapes of characters often
get damaged because of rounding errors---a pixel can generally present two
states: painted or non-painted. But the human eye can be fooled in a
way that it 
``thinks'' sub-pixel accuracy is given on the screen. This is done by
considering which pixels are filled with ink to what degree and
giving the 
physical pixel an appropriate  shade of gray. For example, a pixel whose area
would be covered 50\% would get a 50\% gray shade. This technique is called
{\em antialiasing}.

There are several ways to implement antialiasing. \tonelib\ implements
antialiasing by internally generating a bitmap larger than needed
and then subsampling. Depending on the subsampling factor which may be 2 or 4,
this principle yields glyphs with
5 or 17 shades of gray including black and white. 

There are three functions for generating antialiased glyphs:
\precorr
\begin{verbatim}
 GLYPH *T1_AASetChar( int FontID, char charcode, 
                      float size, T1_TMATRIX *transform)
\end{verbatim}\index{\verb+T1_AASetChar()+}\postcorr
\precorr
\begin{verbatim}
 GLYPH *T1_AASetString( int FontID, char *string, int len, 
                        long spaceoff, int modflag, 
                        float size, T1_TMATRIX *transform)
\end{verbatim}\index{\verb+T1_AASetString()+}\postcorr
\precorr 
\begin{verbatim}
 GLYPH* T1_AASetRect( int FontID, float size,
                      float width, float height,
                      T1_TMATRIX *transform)
\end{verbatim}\index{\verb+T1_AASetRect()+}\postcorr
Note the ``\verb+AA+'' in the functions names which stand for
\underline{A}nti\underline{A}liasing. The usage is identical to the usage of
the functions \verb+T1_SetChar()+, \verb+T1_SetString()+ and
\verb+T1_SetRect()+. So see \ref{generatingbitmaps} for an explanation of the
arguments and their interpretation.

When an antialiased glyph is requested, the supplied \verb+size+-value is
multiplied by the current subsampling factor. For now, let us assume it is 2.
Then the respective function for generating non-antialiased glyphs
is called with all other arguments unchanged. The result is a bitmap twice as
high and twice as wide as the user requested. Now, a $2\times2$ mask is moved
over this bitmap and the number of painted pixels in this mask is considered
at each place. According to the number of painted pixels one of 5 different
gray shades is assigned to the resulting pixel. Since the mask is moved with
an increment of 2 pixels in horizontal and vertical direction, the bitmap is
at the same time subsampled by 2. Thus, the resulting bitmap is just of the
size the user requested and its pixels each contain one of 5 gray shades. 

Conceptually, the same applies for subsampling with 4. In this case the mask is
of size $4\times4$ and there will be 17 distinct gray shades including black
and white. The computational effort is considerably larger so that 4 $\times$
subsampling should only be used for very small sizes. 

When moving the mask over double-sized bitmap it is aligned properly with
respect to the characters' baseline (zero height) rather than with the
characters' top or bottom line. This principle ensures, that the most important
visual guideline in running text, the baseline, is represented in a consistent
manor. This is especially important if one is using a serif-font.
Thanks to Raph Levien, the algorithm described above in a verbose manor has
been replaced by a much 
faster lookup-algorithm in \tonelib\ V.\ 0.4-beta.

\subsubsection{Setting Operating Parameters}
Applications can use both $2\times$ and $4\times$ antialiasing arbitrary
mixed. Switching between the two modes is achieved using
\precorr
\begin{verbatim}
 int T1_AASetLevel( int level)
\end{verbatim}\index{\verb+T1_AASetLevel()+}\postcorr
The argument \verb+level+ should be either \verb+T1_AA_LOW+ ($=2$) or
\verb+T1_AA_HIGH+ ($=4$). Any other values are ignored and \verb+T1_errno+ is
set appropriately. This function is to be called after initialization. The
default value after initialization is \verb+T1_AA_LOW+. The current value can
also be queried by issuing a call to 
\precorr
\begin{verbatim}
 int T1_AAGetLevel( void)
\end{verbatim}\index{\verb+T1_AASetLevel()+}\postcorr
The returned value is current level. Switching between the two antialiasing
modes should be quite fast since apart from a little error checking
essentially only one simple variable is set.

There is one more value that may be specified for \verb+level+, namely
\verb+T1_AA_NONE+. \verb+T1_AA_NONE+ is identical to 1 which means that no
subsampling at all is done. But the resulting glyph, having only fore- and
background colors is returned as a bytemap instead of as a bitmap. This is
intended for situtations where an antialiased glyph should be concatenated
with a (possibly large) non-antialiased glyph using the function
\verb+T1_ConcatGlyphs()+. In that case, the depths of the two glyphs have to
be identical. There is probably not much more sense in setting \verb+level+ to
\verb+T1_AA_NONE+.

As described before, the result of the \verb+T1_AASet..()+ functions is 
strictly spoken no longer a
bitmap since more than one bit is used to
represent one pixel. The function
\precorr
\begin{verbatim}
 int T1_AASetBitsPerPixel( int bpp)
\end{verbatim}\index{\verb+T1_AASetBitsPerPixel()+}\postcorr
allows the user to specify how many bits should be used to represent one
pixel. Allowed values for \verb+bpp+ are 8, 16, 24 and 32. However, if 24 is
specified, internally 32 will be used since the pixel are then addressed as
objects of type \verb+long+. Antialiased glyphs may grow quite large,
especially when 
using \verb+bpp+ = 32. The value of \verb+bpp+ is written into the member
\verb+bpp+ of the \verb+glyph+-structure (see \ref{generatingbitmaps} on page
\pageref{generatingbitmaps}).  That way a user can check whether a
glyph is antialiased or not. It is possible to work with antialiased
and non-antialiased glyphs at the same time.
It is also possible to directly query the value of bits per pixel by using
\precorr
\begin{verbatim}
 int T1_AAGetBitsPerPixel( void)
\end{verbatim}\index{\verb+T1_AAGetBitsPerPixel()+}\postcorr
The value returned is the number of bits per pixel used.

In order to make the handling of antialiased glyphs as flexible as possible,
the values to be written into the pixels for different gray values
may (and must) be explicitly specified. For low level antialiasing this is
done by calling the function
\precorr
\begin{verbatim}
 int T1_AASetGrayValues( unsigned long white,
                         unsigned long gray75,
                         unsigned long gray50,
                         unsigned long gray25,
                         unsigned long black)
\end{verbatim}\index{\verb+T1_AASetGrayValues()+}\postcorr
For lower \verb+bpp+ values only the lower bits are used. For high level
antialiasing this kind of graylevel specification is not economical since 17
arguments 
would have to be specified. Instead, another function is used which expects a
pointer an array of \verb+unsigned long+'s:
\precorr
\begin{verbatim}
 int T1_AAHSetGrayValues( unsigned long *grayvals)
\end{verbatim}\index{\verb+T1_AAHSetGrayValues()+}\postcorr
The array \verb+grayvals+ points to must contain 17 entries. Element 0 is
expected to specify the background color's pixel value and element 16
represents the foreground color. Calling one of these two functions involves
also a new setup of the lookup tables. It should thus only be done if some
color value really has changed. 

In case the antialiasing level is set to \verb+T1_AA_NONE+ as described 
above, the function
\precorr
\begin{verbatim}
 int T1_AANSetGrayValues( unsigned long bg, unsigned long fg)
\end{verbatim}\index{\verb+T1_AANSetGrayValues()+}\postcorr
must be used to set foreground and background color. In conclusion, it turns
out that each antialiasing level has its own lookup tables which have to be
initialized as soon as either foreground color, background color or both have
changed. 
 
Each of the three graylevel sets described above can also be queried by the
user. This is done using one of the functions
\precorr
\begin{verbatim}
 int T1_AAGetGrayValues( long *pgrayvals)
\end{verbatim}\index{\verb+T1_AAGetGrayValues()+}\postcorr
\precorr
\begin{verbatim}
 int T1_AAHGetGrayValues( long *pgrayvals)
\end{verbatim}\index{\verb+T1_AAHGetGrayValues()+}\postcorr
\precorr
\begin{verbatim}
 int T1_AANGetGrayValues( long *pgrayvals)
\end{verbatim}\index{\verb+T1_AANGetGrayValues()+}\postcorr
Here, \verb+pgrayvals+ is the start address of an array of \verb+long+-values
to which the respective grayvalues are written. This memory must thus be
supplied by the user. These functions will write 5
(\verb+T1_AAGetGrayValues+), 17 (\verb+T1_AAHGetGrayValues+) and 2
(\verb+T1_AANGetGrayValues+) respectively to the location given by
\verb+pgrayvals+. These functions are to be called after initialization. If
something goes wrong -1 is returned and \verb+T1_errno+ will be set
accordingly. Otherwise 0 is returned. 


\subsubsection{Smart Antialiasing} 
\label{smartantialiasing}%
Antialiasing improves legibility for small sizes but is not that much useful
for large sizes. To make a compromise between computation time, system
resources and optical appearance it might be advantageous to use
\verb+T1_AA_HIGH+ for small sizes, \verb+T1_AA_LOW+ for medium sizes and
\verb+T1_AA_NONE+ for large sizes. Of course, for large sizes the
non-antialiasing functions could be used which still need less resources. 

In order to free the user from having to switch the antialiasing level explicitly,
\tonelib\ can be told to do this switching
automatically, depending on the size requested. This is called {\em Smart
  Antialiasing}. It is disabled by default and can be toggled by a call to 
\precorr
\begin{verbatim}
 int T1_AASetSmartMode( int smart)
\end{verbatim}\index{\verb+T1_AASetSmartMode()+}\postcorr
The quantity \verb+smart+ should be either be \verb+T1_YES+ (which corresponds
to 1) or \verb+T1_NO+ (which corresponds to 0. Notice that the current
antialiasing level as set by \verb+T1_AASetLevel()+ is not affected by
this. After having switched off smart antialiasing the former antialiasing
level is restored. When smart antialiasing is active still has to take care
for setting the lookup tables after a color change has happened.

The numerical limits of the requested size at which \tonelib\ will switch
between the different antialiasing levels may be specified using 
\precorr
\begin{verbatim}
 int T1_AASetSmartLimits( float limit1, float limit2)
\end{verbatim}\index{\verb+T1_AASetSmartLimits()+}\postcorr
Here, \verb+limit1+ is the value of size at which \tonelib\ switches from
\verb+T1_AA_HIGH+ to \verb+T1_AA_LOW+ and \verb+limit2+ is the value of size
at which \tonelib\ switches from \verb+T1_AA_LOW+ to \verb+T1_AA_NONE+. The
default values are 20.0 for \verb+limit1+ and 60.0 for \verb+limit2+. This
means for sizes smaller than 20.0 \verb+T1_AA_HIGH+ will be used and for sizes
equal to or greater than 60.0 \verb+T1_AA_NONE+ will be used. The intermediate
range is covered by \verb+T1_AA_LOW+. These values are suitable for
applications that display on screen when the device resolution has been left
at the default value of 72 dpi.


\subsubsection{Caching of Antialiased Character Glyphs} 
\label{aacaching}%
Generally, antialiased glyphs are not cached in \tonelib\ because this
involves several problems which are hardly to solve. One main problem is shown
in figure \ref{figure:subpixelpositioning}.
\begin{figure}
\centerline{\includegraphics[scale=10]{Tee}}\relax
\vskip3mm
\hrule\vskip3mm\small
\caption{\label{figure:subpixelpositioning} The string ``Tee'' (which is the
  German word for ``tea'') rastered at 13~bp, using $4\times$ antialiasing.
  Notice the different representations of the character ``e''.} 
\end{figure}
Obviously the character ``e'' appears twice in different representations. This
is intentional and is referred to as sub pixel positioning. In the left ``e''
the letter is perceived somewhat more to the left with respect to the pixels
that represent the character. Conversely, the second ``e'' seems to lie
somewhat more to the right within the pixels. The advantage of this technique 
is that characters can be shifted by some fractional amount of a pixel at low
sizes.\footnote{The opinions whether this and antialiasing in general is of
  advantage for readability vary, so please consider this the opinion of the
  author. } On the other hand the problem is introduced that each character
can have more than one representation in graylevels, depending on how much
subpixel shift is needed. 

One further problem caused by subsampling is that certain information is
irreversibly lost in the graylevel representation. For example, if you have a
graylevel pixel of intensity 50\% (whatever the real color is), then, in case
of $2\times$ antialiasing, you will know that in the $2\times 2$ input bitmap
two pixels had been set to foreground, but you would not know {\em which} two
these had been. But this information is important for concatenating and
blitting of antialiased bitmaps: it may well happen that two pixels with 50\%
gray that lie over each other had to produce an output pixel of 50\%, 75\%
or 100\% gray (where 100\% gray means full foreground intensity).

To avoid these problems, \tonelib\ generally does not cache antialiased
glyphs. Instead, it works on true bitmaps which are then subsampled at the
last possible stage to an antialiased glyph. Applications that do not use
anything more than the functions that yield char bitmaps or bytemaps, could
profit from caching of antialiased characters. Such applications could specify
\verb+T1_AA_CACHING+ as an additional ingredient to the \verb+log+ argument of
the function \verb+T1_InitLib()+ which initializes \tonelib. This is done by
OR'ing the value of \verb+log+ with \verb+T1_AA_CACHING+ as described in
\ref{initialization}. If this flag had been specified at initialization time,
\verb+T1_AASetChar()+ will cache the bytemaps it has generated and will take
them from cache in future requests. 

When caching antialiased glyphs, each size gets up to four distinct cache
areas, one for bitmaps and one for $1\times$, $2\times$ and $4\times$ subsampled
bytemaps each. As soon as a string-generating function is called these cached
antialiased glyphs cannot be used for the reasons discussed before. The
developer of an application should thus carefully think about whether 
a possibly marginal performance gain is really worth this much higher
effort. If in doubt, simply check it out. Applications like \verb+xdvi+ which
place isolated character glyphs on a sheet could use this feature, however, and
profit from it.


\subsection{Interface to Outlines}
\label{outlines}%
Although \tonelib\ is meant for generating bitmaps from Type 1 outline fonts,
there is a set of functions for accessing outline data. 
There are several reasons for this. Firstly, outline
descriptions are, within the given arithmetic constraints, mathematically exact.
Secondly and related to the previous point, in certain cases where exact
subpixel positioning is needed, the functionality of grid-fitting before
rasterization is needed. This can only be done accurately based on
outlines. To illustrate this, consider figure \ref{figure:whyoutlines}.
% -parameters for this figure: size     50.0
%                              angle    35
%                              arg:     --checkConcat[Glyphs|Outlines]
%
\begin{figure}[t]
\hfill
a) \includegraphics[scale=1.0]{concatglyphs}
\hfill
b) \includegraphics[scale=1.0]{concatoutlines}
\hfill\break
\vskip3mm
\hrule\vskip3mm\small
\caption{\label{figure:whyoutlines}Two concatenated bitmaps, a) concatenation
  done based on bitmaps by blitting and b) based on outlines and then filled.} 
\end{figure}
When looking at the concatenated glyph a), it appears that the underline rule
has a small step where the two words touch.\footnote{Depending on the
  resolution and quality of the hardcopy you are reading, the effect might be
  hardly or not all noticeable.} The reason is, that the second part of the
glyph had been rastered with respect to a pixel coordinate of exactly $(0,0)$.
Since the start of the second word in the resulting glyph does not exactly
fall on an integer pixel location, bitmap blitting causes an artifact in the
visual line of the underlining rule. Strings rotated at angles that are not
multiples of $90^\circ$ are prone to produce such effects. In contrast the
concatenated glyph b) does not show such effects because both partial glyphs
are placed mathematically exact and then filled. Thirdly, if the outline of a
character is available, it can be used for whatever. For example, the outline
can be filled by another rasterizer, it can by altered, it can be stroked and
so on. \tonelib\ makes outlines as they are internally used by the rasterizer
available. We will discuss how to interprete and access outlines in the
remainder of this section.
\subsubsection{Outline Format}
\label{outlineformat}%
Before going into implementation details the general structure of a Type 1
outline is described. We will consider the simple fictive character whose
outline is shown in figure \ref{figure:generaloutline}. 
\begin{figure}[t]
\hfill
\includegraphics[scale=1.0]{outlines}
\hfill\break
\vskip3mm
\hrule\vskip3mm\small
\caption{\label{figure:generaloutline}The outline of a fictive character.} 
\end{figure}
We assume that scaling, grid fitting and hinting has already been carried out.
Then, the outline is given by set of points $P_i$ and segments connecting those
points. There are:
\begin{itemize}
\item Move-segments (type = \verb+T1_PATHTYPE_MOVE+): These are straight
  segments which cause the current position to be displaced by some offset.
  Since the starting point of a segment is always implicitly the current
  point, only one argument is needed, $P_{dest}$, the destination point. In
  the figure, $P_1$--$P_2$ and $P_{2}$--$P_{12}$ are Move-segments. In this
  simple case they displace from the characters origin to some starting point
  of the outline and from the ending point of the outline to the point where
  the next character would have to be placed (the horizontal escapement). 
\item Line-segments (type = \verb+T1_PATHTYPE_LINE+): These are part of the
  path to be filled later. In analogy to the Move-segment, one argument,
  $P_{dest}$, is required for Line-segments. In the figure, $P_{11}$--$P_2$ is
  a Line-segment.
\item Bezier-segments (type = \verb+T1_PATHTYPE_BEZIER+): These are curve
  segments. Their shape is defined by a starting point (always the current
  point here), an ending point $P_{dest}$ and two control points $P_B$,
  $P_C$. These four points are the parameters of what is called a third order
  Bezier spline.\footnote{The mathematical defining equation represents a
    special case of a Bernstein polynom which was exploited by {\sc Bezier} in
    the context of solid modeling. The curve especially has the property that
    it may be approximated efficiently by straight line segments in a few
    iterations.} The resulting curve has the following 
  properties:
  \begin{itemize}
  \item It starts at the first point $P_{current}$.
  \item It ends at the fourth point $P_{dest}$.
  \item The line that goes through the points $P_{current}$ and $P_{B}$ is the
    tangent to the curve from the right side at the starting point $P_{current}$.
  \item In analogy, the line that goes through the points $P_{C}$ and
    $P_{dest}$ is the tangent to the curve from the left side at the ending
    point $P_{dest}$.
  \item The resulting curve will be enclosed completely by the convex area
    that is defined by connecting the definition points with straight line
    segments.
  \end{itemize}
  Our fictive character outline in figure \ref{figure:generaloutline}
  has three Bezier-segments, $P_{2}$--$P_{3}$--$P_{4}$--$P_{5}$,
  $P_{5}$--$P_{6}$--$P_{7}$--$P_{8}$ and
  $P_{8}$--$P_{9}$--$P_{10}$--$P_{11}$. Notice that it is easily possible to
  achieve a smooth tangent transition from one curve-segment to the next by
  choosing the involved points from a straight line.
\end{itemize}
For Type 1 fonts in general, the following rules for interpreting coordinate
specifications hold:
\begin{itemize}
\item All point specifications are relative to the {\em current
    point}. 
\item For Bezier-segments, $P_{B}$, $P_{C}$ and $P_{dest}$ all are relative to
  $P_{current}$.
\item Initially, i.e. when a character outline is started, the current point
  is at the origin $(0,0)$ of the character.
\end{itemize}
Additionally, for this special rasterizer implementation, the following terms
apply: 
\begin{itemize}
\item The vertical coordinate is---in contrast to PostScript---inverted, i.e.,
  the $y$-axis points down. 
\item Once hinted and gridfitted, the outline point coordinates are described
  in {\em fractional pixels}. A ``fractpel'' is of type \verb+long+ and
  describes the location in $2^{16}$th fractions of a pixel. To convert from
  pixel to fractional pixel and vice versa, the macros
  \verb+T1_TOPATHPOINT(p)+\index{\verb+T1_TOPATHPOINT()+} and
  \verb+T1_NEARESTPOINT(fp)+\index{\verb+T1_NEARESTPOINT()+} are provided. 
\end{itemize}

Before describing the functions for retrieving outlines the format in which
outlines are presented in C will be described. A point specification is done
in the following structure:  
\begin{verbatim}
typedef struct {
  T1_int32 x;
  T1_int32 y;
} T1_PATHPOINT;
\end{verbatim}
\verb+x+ and \verb+y+ are fractional pixels as described above.

An outline is represented by a linked list of structures which describe path
segments of the type described above.
Line- and Move-segments are described by the following structure:
\begin{verbatim}
typedef struct pathsegment {  
  char type;                
  unsigned char flag;       
  short references;         
  unsigned char size;       
  unsigned char context;    
  struct pathsegment *link; 
  struct pathsegment *last; 
  T1_PATHPOINT    dest;     
} T1_PATHSEGMENT;
\end{verbatim}
\verb+type+ is either \verb+T1_PATHTYPE_MOVE+ or
\verb+T1_PATHTYPE_LINE+. \verb+flag+, \verb+references+, \verb+size+ and
\verb+context+ are internally used by the rasterizer. \verb+link+ is a pointer
to the next segment structure or \verb+NULL+ in case it is the last structure
in the list. Finally, the \verb+last+-entry is a pointer to
the last structure in the linked list. \verb+last+ is only set in the first
segment and is reset to \verb+NULL+ in the remaining segment structures. 
A Bezier-segment is described by the following structure:
\begin{verbatim}
typedef struct bezierpathsegment {
  char type;              
  unsigned char flag;     
  short references;       
  unsigned char size;     
  unsigned char context;  
  T1_PATHSEGMENT *link;   
  T1_PATHSEGMENT *last;   
  T1_PATHPOINT    dest;   
  T1_PATHPOINT    B;      
  T1_PATHPOINT    C;      
} T1_BEZIERSEGMENT;
\end{verbatim}
Obviously, the format is identical to that for straight path segments, extended
by the entries \verb+B+ and \verb+C+ which specify the control points as
described earlier in this subsection.
The common return type for the outline retrieving functions is a pointer to 
\verb+T1_OUTLINE+, which is in fact identical to \verb+T1_PATHSEGMENT+. This
purely for convention. Although it is quite unlikely, an outline might start
with a Bezier-segment. To access Bezier-segment elements, a cast must be used.


\subsubsection{Using Outlines}
\label{usingoutlines}%
\tonelib\ provides three functions for retrieving outlines. The first is  
\precorr
\begin{verbatim}
 T1_OUTLINE *T1_GetCharOutline( int FontID, char charcode,
                                float size, T1_TMATRIX *transform)
\end{verbatim}\index{\verb+T1_GetCharOutline()+}\postcorr
The meaning of the arguments is as in the \verb+T1_SetChar()+-function. 
Notice that the size specification is also required here. Outlines are, by
their nature in Type~1, generally defined in a $1000\times 1000$ grid and then
scaled down by the fontmatrix to 1 bp. The space is known as the
charspace. The reason for specifying a size at this place, instead of scaling
the outline later, is, that hinting is performed according to the scaled
outline. The returned outline is then hinted for the given size. If necessary,
it may still be scaled later.

The outline for a complete string can be retrieved by
\precorr
\begin{verbatim}
 T1_OUTLINE *T1_GetStringOutline( int FontID, char *string, int len, 
                                  long spaceoff, int modflag,
                                  float size, T1_TMATRIX *transform)
\end{verbatim}\index{\verb+T1_GetStringOutline()+}\postcorr
The meaning of the arguments is as in \verb+T1_SetString()+.

Finally the ``outline'' for a displacement is available by the function
\precorr
\begin{verbatim}
 T1_OUTLINE *T1_GetMoveOutline( int FontID, int deltax, int deltay, int modflag,
                                float size, T1_TMATRIX *transform)
\end{verbatim}\index{\verb+T1_GetMoveOutline()+}\postcorr
This function is intended to be used for concatenation of outlines. It needs
all the arguments because some quantities which are given on the font level
are required for constructing the outline. \verb+deltax+ and \verb+deltay+ are
the horizontal and vertical displacement measured in charspace units. From the
\verb+modflag+-argument, especially the underlining parameters are
evaluated. Although $x$- and $y$-displacement may be specified, the resulting
outline is still subject to scaling with \verb+size+ and transformation
according to \verb+transform+. 

Arbitrary outlines may be concatenated by using the function
\precorr
\begin{verbatim}
 T1_OUTLINE *T1_ConcatOutlines( T1_OUTLINE *path1,
                                T1_OUTLINE *path2)
\end{verbatim}\index{\verb+T1_ConcatOutlines()+}\postcorr
Notice that this concatenation is done with high precision so that we can
expect that visual artefacts are reduced to a minimum (remember figure
\ref{figure:whyoutlines}). 

Scaling of outlines is done by the function
\precorr
\begin{verbatim}
 T1_OUTLINE *T1_ScaleOutline( T1_OUTLINE *path, float scale)
\end{verbatim}\index{\verb+T1_ScaleOutline()+}\postcorr
\verb+T1_ScaleOutline+ does nothing more than linearly scaling the coordinate
data with \verb+scale+ and storing the result in fractional pixels. No care is
taken for hinting (see above).

An outline may be duplicated using the function
\precorr
\begin{verbatim}
 T1_OUTLINE *T1_CopyOutline( T1_OUTLINE *path)
\end{verbatim}\index{\verb+T1_CopyOutline()+}\postcorr
This is a direct entrypoint into the rasterizer. It works by allocating and
duplicating each segment of \verb+path+. This function may be useful if one
wants to do several things with one outline because the process of filling an
outline also consumes that outline.

An outline that that a user decides not to fill can be destroyed by the
function 
\precorr
\begin{verbatim}
 void T1_FreeOutline( T1_OUTLINE *path)
\end{verbatim}\index{\verb+T1_FreeOutline()+}\postcorr
It iterates through the segment list and frees each segment.
This must not be done after filling an outline because the filling process
consumes the outline!

Finally, there are two functions that produce glyphs from outlines, namely
\precorr
\begin{verbatim}
 GLYPH *T1_FillOutline( T1_OUTLINE *path, int modflag)
\end{verbatim}\index{\verb+T1_FillOutline()+}\postcorr
and
\precorr
\begin{verbatim}
 GLYPH *T1_AAFillOutline( T1_OUTLINE *path, int modflag)
\end{verbatim}\index{\verb+T1_AAFillOutline()+}\postcorr
Their usage does not need any explanation. The value of \verb+modflag+ is
required for {\em Right-To-Left} typesetting. If the bit
\verb+T1_RIGHT_TO_LEFT+ is set, the dimension of the glyph are recomputed
accordingly. All other bits from \verb+modflag+ are ignored such that in the
usual case of {\em Left-To-Right} typesetting simply 0 can be specified.
While \verb+T1_FillOutline()+ produces bitmaps of depth 1,
\verb+T1_AAFillOutline()+ produces antialiased bytemaps of the current
graphics depth. It should be mentioned that Smart Antialiasing (see
\ref{smartantialiasing}) does not work with this function. The reason is that
\tonelib\ has no notion of the quantity ``size'' when it gets the outline to
process. Hence, Smart Antialiasing can't work in this case. As noted above,
the outline is consumed by the filling functions so that there is no need to
free it explicitly.

 
\subsubsection{Manipulation of Outlines}
\label{outlinemanipulation}%
\tonelib\ provides some limited further functionality to process
outlines. First of all, a user would expect a character to be defined in a
coordinate system in which $x$ points to the right and $y$ points up. Further,
a representation of the glyph where all points are specified in absolute
coordinates would be advantageous for manipulating outline-points. This is
because most transformations, linear or nonlinear, need to have an absolute
$x$-value to compute an $y$-value or vice versa. The function
\precorr
\begin{verbatim}
 void T1_AbsolutePath( T1_OUTLINE *rpath)
\end{verbatim}\index{\verb+T1_AbsolutePath()+}\postcorr
does exactly what has been described just before, (a) conversion of relative
coordinates into absolute coordinates and (b) inverting the
$y$-direction. 

Once a path has been converted into an absolute path, it is
suitable for possibly nonlinear manipulation.\footnote{A linear manipulation
  of path points would rather be realized using the transformation matrices as
  described in \ref{transformations}.}
As an example of what can be done, have a look at figure \ref{figure:manipulation}. 
\begin{figure}[t]
\hfill
\includegraphics[scale=1.0]{manipulate}
\hfill\break
\vskip3mm
\hrule\vskip3mm\small
\caption{\label{figure:manipulation}A string with nonlinearly scaled coordinates.} 
\end{figure}
The string displayed has been generated by essentially applying the
transformation $y'= y(1+cx^2)$, with appropriate $c$. To allow such
transformations by the user, \tonelib\ provides the function
\precorr
\begin{verbatim}
 void T1_ManipulatePath( T1_OUTLINE *path,
                         void (*manipulate)(long *x,long *y, int type))
\end{verbatim}\index{\verb+T1_ManipulatePath()+}\postcorr
Here, \verb+path+ should be an absolute path as described above. Notice that
\tonelib\ has no way to check whether the path is relative or absolute, this
is in the responsibility of the user. The second argument is a pointer to a
function that has a return type of \verb+void+ and that expects three
arguments: two pointers to \verb+long+-values one integer \verb+type+.
\verb+T1_ManipulatePath()+ works by iterating through all outline points of
\verb+path+ and calling the function \verb+*manipulate()+ for each outline
point. When the function \verb+*manipulate()+ is called, \verb+x+ and \verb+y+
are pointers to the $x$- and $y$-coordinates respectively of the outline point
to be processed. That way, \verb+*manipulate()+ can alter the outline
points arbitrarily. The \verb+type+-argument will be set to the segment type
by \verb+T1_ManipulatePath()+. As described earlier, the segment type can be
one of \verb+T1_PATHTYPE_MOVE+, \verb+T1_PATHTYPE_LINE+ and
\verb+T1_PATHTYPE_BEZIER+. Of course, the function \verb+manipulate()+ has to
be written by the user. To make it clear, we consider a function which
stretches an outline horizontally by 1.5. The code fragment for this could be:
\begin{verbatim}
     .
     .
     .
void h_stretch( long *x, long *y, int type)
{
  double dx;

  dx=(double)*x;
  dx *=1.5;       /* scale x coordinate by 1.5 */
  *x=(long)dx;
}
     .
     .
     .
T1_OUTLINE *path=NULL;
path=T1_GetStringOutline(FontID,(char *)SomeString,
                         0,0,T1_KERNING,20.0,NULL);
T1_AbsolutePath( path);
T1_ManipulatePath( path, &h_stretch);
T1_RelativePath( path);
glyph=T1_FillOutline( path, Modflag);
     .
     .
     .
\end{verbatim}

As the example above already has shown, an absolute path, manipulated or not,
must converted back to a relative path before it finally can be interpreted by
the rasterizer. This conversion is done using
\precorr
\begin{verbatim}
 void T1_RelativePath( T1_OUTLINE *apath)
\end{verbatim}\index{\verb+T1_RelativePath()+}\postcorr
As already mentioned with respect to \verb+T1_AbsolutePath()+, \tonelib\ cannot
check whether the \verb+path+ specified is really absolute. The user has to 
take care for this.

A few general comments about manipulating paths are appropriate. Although the
mechanism implemented by \verb+T1_ManipulatePath()+ allows arbitrary
manipulation of path points, one must be very careful in doing so. Figure
\ref{figure:outlineproblems} exhibits some of the problems that may arise. A text
string aligned to a sine function is displayed.
%- parameters of figure: string:   Text aligned along a sine wave function
%                        size:     50
%                        kerning   on
\begin{figure}[t]
\hfill
a) \includegraphics[scale=0.5]{outlineproblems1} % period=500, 
\hfill\break

\hfill
b) \includegraphics[scale=0.5]{outlineproblems2} % period=200
\hfill\break

\hfill
c) \includegraphics[scale=0.5]{outlineproblems3} % period=100
\hfill\break

\hfill
d) \includegraphics[scale=0.5]{outlineproblems4} % period=50
\hfill\break

\hfill
e) \includegraphics[scale=0.5]{outlineproblems5} % period=500
\hfill\break
\hrule\vskip3mm\small
\caption{\label{figure:outlineproblems}The string ``Text aligned along a sine wave
  function'' using a period of (a) 500, (b) 200, (c) 100, (d) 50 pixels and
  (e) again 500 pixels with underlining. The sine amplitude was 30 pixels 
  (in screen resolution).} 
\end{figure}
In part (a), a pleasing smooth text flow is shown and this also applies for
(b) where the period of the sine has been reduced to 200 pixels. In (c), where
the period has been reduced to 100 pixels, some artefacts already show up. For
example, the top bar of the uppercase ``T'' has noticeable variance in
thickness. In (d), where the period has been reduced again, the result is
hardly readable. Another artefact appears in figure
\ref{figure:outlineproblems} (e): since the underlining rule is defined by
four points only, these points and nothing else is transformed with the result
that the out coming line is still straight and not curved as we would
like. From this discussion we conclude, that such transformations can only be done
with reasonable results if the maximum distance between the outline points of
a shape is small compared to the variance of the outline points that the
transformation results in. This rule, although being very fuzzy and
non-mathematical, should give a good estimation of which transformations are valid. 

Another completely independent topic is that, at the level where \tonelib\ 
provides outlines, their representation is strictly descriptive with respect
to points and their connections. There are no such things like 
\verb+closepath+-segments which would take care that a path is really closed,
no matter what the transformation had been. This means, that identical points
$P_1 = P_2$ have to be transformed to identical points $P_1'=P_2'$, no matter
where they appear in the outline. However,
if the transformation is done by by a function $(x',y')=f(x,y)$ as suggested,
this should never be a problem.

Finally, one should remember that all computations in the user function
\verb+manipulate()+ have to be done in units of fractional pixels, rather than in
pixels. When designing a sine wave as in figure \ref{figure:outlineproblems},
this must be taken into account with respect to periodicity.

\subsection{Logical Fonts}
\label{logicalfonts}%
It sometimes may be necessary to have a font and an extended or slanted
variant simultaneously. To enable such configurations without needing to
declare the fonts two or even more times in the font database file, 
\tonelib\  provides the function 
\precorr
\begin{verbatim}
 int T1_CopyFont( int FontID)
\end{verbatim}\index{\verb+T1_CopyFont()+}\postcorr
It copies the top level data structure of the font given by \verb+FontID+ to
another location. The newly created font refers in fact to the same 
physical memory as the font \verb+FontID+ as far as Type 1 and AFM data are
concerned. However, no size specific data is copied from font \verb+FontID+,
you can thus do with the new font whatever you want to. It will get its own
size-specific memory area when the first bitmap is generated using its ID.

It is also possible to reencode a copied font without affecting the
original font. This is possible because a logical font gets its own
mapping tables. This allows configurations with one font at different
encodings simultaneously.

In order to keep track that another font is referring to data from
font \verb+FontID+, a reference counter is managed for every font. The
reference counter for font \verb+FontID+ is incremented after a call to
\verb+T1_CopyFont()+. 

If the font \verb+FontID+ is not loaded into memory, the function returns $-1$.

Only {\em physical} fonts---those fonts defined in the font database
file or added via \verb+T1_AddFont()+---may be copied to another
font. If a user tries to copy a font 
which is already logical, the function returns $-2$.

If no memory is available for the new font the function return $-3$. But
this should not happen. 

If all goes the right way, \verb+T1_CopyFont()+ returns an integer---lets call
it \verb+new_ID+---which is from now on a valid font identification number.

\subsection{Missing or Invalid AFM Files}
\label{missingafmfiles}%
\tonelib\ heavily relies on AFM information every time the relative position
of bitmaps is of importance. Because AFM information is of high resolution,
accumulating positioning errors are avoided in contrast to what the X11 text
drawing functions do. On the other hand, there are many freely available
Type~1 font programs that come without AFM files. This problem has been
addressed in \tonelib\ 0.5. \tonelib\ is now able to generate AFM information
on the fly and it even can generate AFM files from Type 1 font files.

\subsubsection{Remarks on AFM Files}
\label{remarksonafmfiles}%
Information in AFM files is only relevant for placing character glyphs but not
for rasterizing. The metric values are based on the same coordinate system as
used in Type 1 font files, the so called {\em charspace coordinate system}. 
One unit is $1/1000 \mbox{bp}$ when a font is not scaled or scaled to 1~bp,
respectively. 

Information in AFM files can divided into several groups:
\begin{enumerate}
\item {\em Global Font Information:} This information is generally not needed
  to place characters. Furthermore, most of this information is also
  contained in a Type 1 font file itself. This area is thus of marginal
  importance for \tonelib. 
\item {\em Character Width's and Bounding Boxes:} These both are crucial for
  accurately placing the character glyphs. Fortunately, these are dimensions
  are exactly defined by the character outlines themselves. It is thus
  possible to compute them spending some computational effort.
\item {\em Ligature Information:} For \ae sthetic reasons, certain character
  groups are often replaced by ligatures and a font file may define several
  ligatures. It is however not intuitively clear what character groups should
  be replaced by what ligatures.\footnote{Well, at least not without some
    expert knowledge like ``I know this ligature's name is `f{}i', so I
  replace  every series of `f' and `i' with it.''}
  Fortunately, ligatures are not crucially needed for quality typesetting.
\item {\em Pair Kerning Information:} This information is quite important for
  \ae sthetic reasons but it is entirely independent from the outline
  descriptions and can thus not be extracted from a font file.
\item {\em Track Kerning Information:} This information gives hints of how to
  typeset text generally closer or wider at varying point sizes. 
  \tonelib\ does not use track kerning
  information and I personally do not consider using track kerning a good
  typographical style. 
\item {\em Composite Character Data:} This is needed to construct characters
  from two single characters. Typical examples are accented
  characters. \tonelib\ currently does not deal with composite
  characters. Most of the composite characters needed are already existent
  internally. 
\end{enumerate}
To come to a conclusion, for our purposes it is sufficient to generate the
characters' widths and their bounding boxes and we have all information we
need to construct string glyphs.

\subsubsection{Generation of AFM Information}
\label{generatingafminfo}%
Next lets consider how to generate the AFM information. It is a series of
entirely independent steps:
\begin{itemize}
\item When we generate AFM information, we want to do this once and forever
  when the font is loaded. Consequently all characters, have to be examined,
  not only those that are currently encoded. 
  We start by fetching all character names the font defines. This done with
  \verb+T1_GetAllCharNames()+ (see \ref{characterencodingrelation}). This
  yields a list of possibly more than 256 character names.
\item Each of the character addressed by the names above is now rastered at
  size 1000~bp. By rastering at 1000~bp we match exactly the charspace
  coordinate system which the character outline descriptions are
  based on. Width and bounding box are easily examined and saved at
  appropriate places. 
\item The kerning pair area and ligatures are explicitly set to zero.
\end{itemize}
At the end of this procedure, there is a data area identical to what would
have been built when reading an AFM file without kerning-section and ligature
specifications.  

The decision of building AFM data is done on the fly without any user
interaction. Here is what happens on the metrics-area when loading a font:
\begin{itemize}
\item \tonelib\ tries to open an AFM file reading metrics and kerning pair
  information. 
\item If this does not succeed, it tries to rescan the AFM file in a {\em
    sloppy} way, only requesting metrics information.
\item If this fails too, metrics information is generated on the fly as
  described above.
\end{itemize}
It should be noted that generating metric information the way described above
takes significant amount of time since every character has to be rastered at
1000~bp.

%~derekn
If the \verb+T1_NO_AFM+ flag is passed to \verb+T1_InitLib()+,
\tonelib\ will neither attempt to open AFM files nor generate AFM
information.  This is useful to speed up applications which do not
need the metrics data. However, this slows down access to certain features,
mostly related to the string processing functions, and completely disables the
features that only are contained in AFM files (like kerning and ligatures).

Obivously, the \tonelib\ functions that use
the AFM data will not work correctly in this case and should not be
used.
%~derekn

\subsubsection{Writing AFM Files}
\label{writingafmfiles}%
In order to reduce the situations where AFM data has to be generated on the
fly, \tonelib\ provides the following function:
\precorr
\begin{verbatim}
 int T1_WriteAFMFallbackFile( int FontID)
\end{verbatim}\index{\verb+T1_WriteAFMFallbackFile()+}\postcorr
It writes an AFM file for the font identified by \verb+FontID+. This is done
executing the following steps:
\begin{enumerate}
\item The AFM filename is constructed by taking the fontfilename, cutting off
  the extension and appending \verb+.afm+.
\item A pointer array of size $256 + n$, where $n=\mbox{number of
  characters}$, is
  allocated and set to NULL. The leading 256 entries are reserved to point to 
  encoded
  characters' metrics. The remaining entries are intended to point to metrics
  of unencoded characters. We see that this is a worst case speculation: The
  pointer array is large enough for the extremely unusual case that no
  characters are encoded. 
\item Next the function steps through all character names and gets their
  encoding index $i$. If $i\geq0$, the character is encoded and the $i$th
  pointer element in the array is set to point to the metrics of this
  character. If $i=-1$, the character is not encoded and the lowest unused
  pointer in the second area is set to point to the metrics of this character.
\item Next the AFM file is opened and the header information as well as a
  comment by \tonelib\ are written. There are 5 entries that are not trivially
  to extract from the font file: \verb+Ascender+, \verb+Descender+,
  \verb+XHeight+, \verb+CapHeight+ and \verb+EncodingScheme+. Their
  discussion is deferred to later in this section.
\item After the header, the metrics information is written in the format
  required for AFM files. This is done by stepping through the pointer array
  until the first NULL pointer in the unencoded characters' area is
  reached. 
\end{enumerate}
The result is a list of char-dimensions entries which is leaded by the encoded
characters in ascending order of their encoding index, followed by a list of
unencoded characters in alphabetical order. 

As seen above, the current encoding takes influence on the order the
characters appear in the AFM file. One should thus not produce AFM files from
reencoded fonts, although this is possible. This yields non-standard AFM files
and gives no performance gain, even not when used with \tonelib.

The entry \verb+EncodingScheme+ is not always contained in the fontfile
itself. It is generated by comparison between encodings. \tonelib\ has only one
builtin encoding, \verb+AdobeStandardEncoding+, which
is recognized. Every further encoding, defined
by the font itself or applied by a user, is always marked as
\verb+FontSpecific+. 

The entries \verb+CapHeight+, \verb+XHeight+ \verb+Ascender+ and
\verb+Descender+ are not fully determined by a Type 1 font file
although they are existent with high probability. As rough definitions
can be considered:
\begin{itemize}
\item \verb+CapHeight+: The height a capital `H' reaches to.
\item \verb+XHeight+: The height a lower case `x' reaches to.
\item \verb+Ascender+: The height a lower case `d' reaches to.
\item \verb+Descender+: The depth a lower case `p' reaches down.
\end{itemize}
It is obvious that these definitions make only sense in certain font
definitions. For example, a musical notation font might not necessarily
define an ascender since no capital letters are provided. 

In the Type 1 notion these dimensions are referred to as top alignment
and bottom alignment values respectively. The corresponding alignment
``zone'', i.e., an interval, is defined by the alignment height and a
corresponding overshoot position. The alignment zones are specified in
the BlueValues array for top alignment zones and the OtherBlues
array for bottom alignment zones. A Type 1 font may define up to 7 top
alignment zones and 5 bottom alignment zones. It is unfortunately not
defined which of these alignment zones refer to \verb+CapHeight+,
\verb+XHeight+, \verb+Ascender+ and \verb+Descender+. 

\tonelib\ tries to get out of this dilemma by making a best guess:
\begin{enumerate}
\item For each of the characters `H', `x' and `d' it fetches the
  largest y-value and compares the result with each alignment zone in
  the BlueValues array. The alignment zone closest to the observed
  character dimension is assumed a candidate for the respective
  quantity. 
\item It checks whether the difference between the alignment zone just
  selected and the character dimension is within a certain tolerance
  area. This tolerance width is $\pm 30$ charspace units. If the
  result is positive, the quantity in question is assigned the
  numerical value of the standard height (not the overshoot) of this
  alignment zone. Since we are currently considering top
  alignment zone, this will always be the lower value. 
\item If the value is out of tolerance or the font even does not
  define the character, the corresponding entry in the AFM file is left
  out.
\item A comparable procedure is then done for \verb+Descender+, this
  time examining the OtherBlues array.
\end{enumerate}
Note that if the values do not seem to be correct, the corresponding
lines can be removed from the AFM file without doing any harm. These
entries are optional only.

\verb+T1_WriteAFMFallBackFile()+ can indicate  a number of error
conditions by returning appropriate values. These are:
\begin{itemize}
\item \verb+0+: No error occurred, AFM file was successfully written.
\item \verb+-1+: The AFM data for the font in question has been
  generated by reading an AFM file, there is no need to generate a new
  one. If you really want to force an AFM file to be written, take
  care that \tonelib\ does not find an AFM file when loading the
  font. 
\item \verb+-2+: The font in question is not loaded.
\item \verb+-3+: The font in question is loaded but AFM data has not
  been generated. This definitely is an error condition because it
  indicates not all characters of the font could be rastered, either
  because the font file is damaged or because there were 
  insufficient system resources. In any case the application should
  generate a logfile and this file should be examined.
\item \verb+-4+: The AFM file could not be opened. This could be a
  permission problem or something else. The file is always opened in
  the current working directory.
\item \verb+-5+: The file has successfully been opened but there was
  an error writing to the file.
\item \verb+-6+: A memory allocation error occurred. This should not
  happen because it indicates there are no system resources. 
\end{itemize}



\subsection{Font Subsetting}
\label{Font Subsetting}%
When applications have to setup Postscript files for printing, the problem is
that these files often grow large. Each font which is not known to the
Postscript interpeter, i.e., usually each font that is not part of the set of
35 standard fonts, has to be downloaded as part of the file. The size of a
particular font file often can be reduced by font subsetting, because usually
only a small subset of the available character descriptions is actually
needed. 



\subsubsection{Font File Organization and Subsetting}
\label{Font File Organization and Subsetting}%

Each Type~1 font file is a special Postscript program defining three
Postscript-dictionaries:
\begin{itemize}
\item \verb+FontInfo+\\
  Global font information like font and family name and encoding scheme is
  stored here. This data is required even for a subsetted font. However, as
  will be described later, the encoding scheme may be reduced to those
  characters that are in the desired subset. 
\item \verb+Private+\\
  This dictionary is in the encrypted part of the file and stores global font
  data too. This data includes quantities parameterizing hinting and
  subroutines that might be called by the character descriptions. This data is
  required also.
\item \verb+Charstrings+\\
  For each character defined in the font a binary and encrypted byte string
  (charstring) coding the character outline is stored in this dictionary. The
  number of charstrings may be considerably larger than the size of the
  encoding vector. This dictionary usually constitutes the largest part of the
  font file and, consequently, it is the place to reduce storage requirements.
\end{itemize}
The main principle in subsetting is to decrypt the font and reorganize it,
leaving out charstrings that are not required in the current context. For
example, if a document uses only the character 'A' from the font Garamond,
then this font may be subsetted preserving the character outline for 'A'
only. The resulting file, which will be much smaller than the original file,
can then be included verbatim into the Postscript file containing the
document. At the same time, optionally, the encoding vector could be redefined
to contain only the entry for 'A' at the appropriate location and
\verb+.notdef+ otherwise. 

A still more consequent subsetting would involve leaving out those subroutines
from the \verb+Private+-dictionary that are not needed by the preserved
charstrings. Leaving out some subroutines on the other hand would require to
interprete and check all charstrings for the subroutines they require and all
preserved charstrings would have to be adapted to the reorganized index. Since
the subroutines usually do not consume that much memory this is not considered
worth the effort.

\subsubsection{Functions for Subsetting}
\label{Functions for Subsetting}%

There are two ways to obtain a subsetted font from an existing file. The user
can (1)~do it step by step which requires reading, decrypting, reorganizing
and encrypting of the font file, and (2)~use a high level function to do it
without having to know anything about the details. For font subsetting,
\tonelib\ provides the function 
\precorr
\begin{verbatim}
 char *T1_SubsetFont( int FontID, char *mask,
                      unsigned int flags, int linewidth,
                      unsigned long maxblocksize,
                      unsigned long *bufsize)
\end{verbatim}\index{\verb+T1_SubsetFont()+}\postcorr
It returns a pointer to a memory block containing the subset data. The memory
is allocated in the function and it is the responsability of the user to
free this memory. The parameter \verb+FontID+ as usual is used to tell
\tonelib\ which file or font is to be used for the operation. 

\verb+mask+ points to an array of characters which has to be setup by the
user. This array must comprise exactly 256 characters and for the index of
each non-zero entry the charstring resulting from the current encoding is
preserved in the subsetted font. To give an instance, if the subset should
consist in the character 'A' only and we assume the current font specifies
\verb+StandardEncoding+, then the \verb+mask+-array should be initialized to
zeroes and \verb+mask['A']=1+ or some other non-zero value.

The \verb+flags+ parameter allows to control the subsetting operation.  It
usually should be set to \verb+T1_SUBSET_DEFAULT+. In this case, the subset is
ASCII-hex encrypted, that is, as in a \verb+.pfa+-file. It is thus well-suited
for the verbatim insertion into a Postscript file. If the source font file in
question defines the encoding to be \verb+StandardEncoding+, the encoding is
not adjusted to the subset specified by \verb+mask+. By contrast, if the font
defines a \verb+FontSpecific+ encoding, this encoding will be adjusted
according to the subset. This default behavior---which mimics what
e.g.~\verb+dvips+ seems to do---may be overwritten by OR'ing \verb+flags+ with
\verb+T1_SUBSET_FORCE_REENCODE+, which leads to adjusting the encoding vector
in any case. Conversely, reencoding can be suppressed unconditionally by OR'ing
\verb+flags+ with \verb+T1_SUBSET_SKIP_REENCODE+. If \verb+flags+ is OR'ed
with \verb+T1_SUBSET_ENCRYPT_BINARY+, a buffer of mixed ASCII, binary and EOF
segment types is created and encryption is performed in binary mode. The
buffer's contents in this case represents a valid compact binary format file
(\verb+.pfb+). It is considerably smaller than a comparable \verb+.pfa+-file
but it is not suitable to be inserted into Postscript files.

The parameter \verb+linewidth+ is used to specify the line length if ASCII-hex
encryption is used. Since---according to the Adobe speification---the first 8
encrypted bytes have to be stored one after the other without interspersed
white space, the allowed range of \verb+linwidth+ is limited to 8 at the lower
bound. It is also limited at the upper bound by 1024, because writing that
long lines does not preserve the readability of the produced file.

The parameter \verb+maxblocksize+ is important if binary encryption is
used. Then, this value specifies the maximum allowed segment size. For similar
reasons as discussed above, this value must be equal to or larger
than~4. There is no limit at the upper bound, because the maximum segment size
can be derived automatically follows from the target font file.

\verb+bufsize+ must be a valid pointer to an \verb+unsigned long int+ in the
context of the calling function. The size of the memory area to which the
function returns a pointer, is written to \verb+bufsize+. The calling function
needs this number to process to buffers contents, e.g., to write it to a file. 

If errors occur in this function, \verb+NULL+ is returned and \verb+T1_errno+
is set to an appropriate value. If the font corresponding to \verb+FontID+ is
not loaded, \verb+T1_errno+ is set to \verb+T1ERR_INVALID_FONTID+.
\verb+T1ERR_INVALID_PARAMETER+ is used to indicate that one of the further
arguments is out of range. \verb+T1ERR_ALLOC_MEM+ and
\verb+T1ERR_FILE_OPEN_ERR+ may also be set in this function. Finally,
\verb+T1ERR_UNSPECIFIED+ may also be set if the charstring definition for
\verb+.notdef+ could not be located. This is considered to be a fatal error.

An example of how to use the function described above is given in the file
\verb+subset.c+ in the \verb+examples/+ subdirectory of the distribution.  

\subsubsection{Further Functions for Subsetting}
\label{Further Functions for Subsetting}%

For the sake of completeness, there are a few further functions in the
subsetting module. The function
\precorr
\begin{verbatim}
 char *T1_GetCharString( int FontID, char *charname, int *len)
\end{verbatim}\index{\verb+T1_GetCharString()+}\postcorr
returns a pointer to the charstring of the character with name \verb+charname+
of the font identified by \verb+FontID+. In case of an error, \verb+NULL+ is
returned and \verb+T1_errno+ is set to \verb+T1ERR_ALLOC_ERR+ if there was not
enough memory for storing the charstring, \verb+T1ERR_UNSPECIFIED+ if the
charstring was not found in the dictionary, \verb+T1ERR_INVALID_FONTID+ if the
font in question is not loaded or \verb+T1ERR_INVALID_PARAMETER+ if
\verb+charname+ or \verb+len+ is \verb+NULL+. The memory pointer which is
returned is managed static in this function. Thus, it should not be free'd by
the user, or, in case the memory block is free'd, the pointer must be set to
\verb+NULL+.

In order to decrypt a charstring, the \verb+lenIV+-value of the font in
question must be known. It can be obtained using the function
\precorr
\begin{verbatim}
 int T1_GetlenIV( int FontID)
\end{verbatim}\index{\verb+T1_GetLenIV()+}\postcorr
The returned value indicates how many leading random bytes are used for
charstring encryption in the font \verb+FontID+. According to an undocumented
Adobe convention, the value $-1$ is also valid and indicates that the
charstring is not encrypted at all. Hence the return value $-2$ is used to
indicate an error. In this case, \verb+T1_errno+ is set to
\verb+T1ERR_INVALID_FONTID+, which indicates that the font in question is not
loaded.   


\subsection{Composite Characters}
\label{subsec:CompositeCharacters}%

This section discusses the composite character information that may be present
in AFM files and how this information is represented, accessed and handled in
\tonelib.  

\subsubsection{General remarks}
\label{subsubsec:General Remarks}%

Composite characters are defined by the fact that they are constructed from at
least two independent symbols. In practice there frequently appear two
components, a base character and an accent, e.g., as in ``\"A''. Usually, the
accents (or secondary pieces) of a composite character are typeset first
without causing any horizontal escapement and finally the base character
itself is typeset and causes its escapement to become the escapement of the
whole composite character. Although some people recommend that the character
definition of an accent itself should not cause escapement, this generally is
not respected in real fonts and \tonelib\ does not require this condition to
be fulfilled.

In order to construct a composite character the characters to be put together
have to be known and metric information about how to put these characters
together has to be known too. \tonelib\ defines two structures as new data types
for this purpose. The first is 
\begin{verbatim}
typedef struct 
 {
   int compchar;         
   int numPieces;        
   T1_COMP_PIECE *pieces;
 } T1_COMP_CHAR_INFO;
\end{verbatim}
Here, \verb+compchar+ is the index in the encoding vector of the composite
character. \verb+numPieces+ specifies how many pieces are
required to build the composite character. The third element is a pointer to
an array of type \verb+T1_COMP_PIECE+, whose actual length is given by
\verb+numPieces+: Each piece (or symbol) receives one slot in this
array. \verb+T1_COMP_PIECE+ is defined by
\begin{verbatim}
 typedef struct
 {
   int piece;     
   int deltax;    
   int deltay;    
 } T1_COMP_PIECE;
\end{verbatim}
It contains the encoding index of the symbol in \verb+piece+ and information
where to place this symbol with respect to the composite character's orgin in
\verb+deltax+ and \verb+deltay+. The first slot is filled by what I refer to
as the base character, it is the one that causes spacing. As can be seen in
these data structures, composite character handling in \tonelib\ is based on
encoding indices rather than on character names, which, by contrast, are used
for the definition of composite character data in AFM files.

The presence of composite character information in AFM files does not tell
anything about whether a font has an internal  definition of this character or
not. For example, the font \verb+TimesRoman+ internally defines the CharString
\verb+Adieresis+ and hence this font provides the letter ``\"A'', assuming an
appropriate encoding, without any knowledge about composite
characters. However, the file \verb+TimesRoman.afm+ may still 
provide composite character information for \verb+Adieresis+, just to tell an
application that this glyph consists of more elementary pieces and how to
construct it. On the other hand, if \verb+TimesRoman+ had no
CharString-definition for \verb+Adieresis+, the composite character
information of \verb+Adieresis+ provides an application with enough
information to be able construct \verb+Adiereis+ from the elementary units
\verb+A+ and \verb+dieresis+ that the font provides.


\subsubsection{Accessing Composite Character Data}
\label{subsubsec:Accessing Composite CHaracter Data}%

This section describes a few functions that provide access to composite
character data of a font file. The data they return can be considered a
mapping of the original AFM data with respect to the current encoding.  As
usual, \verb+FontID+ must be the identifier of a font loaded into memory,
otherwise an appropriate error indicator is returned. The functions described
in the following may also return some other error types.

Firstly,
\precorr
\begin{verbatim}
 int T1_GetNoCompositeChars( int FontID)
\end{verbatim}\index{\verb+T1_GetNoCompositeChars()+}\postcorr
tells the user how many composite character definitions are given in the AFM
file. This, of course, does not depend on the current encoding vector and it
is even possible that the current encoding vector does not incorporate any
composite character at all. 

The function 
\precorr
\begin{verbatim}
 int T1_QueryCompositeChar( int FontID, char char1) 
\end{verbatim}\index{\verb+T1_QueryCompositeChar()+}\postcorr
checks whether composite character information exists for the encoding index
\verb+char1+. If so, it returns the index within in the AFM composite
character data array as a number equal to or greater than zero. If the result
is valid but no composite character information has been found for
\verb+char1+, $-1$ is returned. In case of an error, $-2$ is returned and
\verb+T1_errno+ is set to an appropriate value. 

The previous function does not tell anything about whether the font
\verb+FontID+ incorporates a character definition for the composite char or
not. This can be queried using
\precorr
\begin{verbatim}
 int T1_IsInternalChar( int FontID, char char1)
\end{verbatim}\index{\verb+T1_IsInternalChar()+}\postcorr
It returns $1$ if there exists a CharString for \verb+char1+ and $0$ if not.
In the latter case, the application is responsible for the construction of the
composite character (see later). \verb+T1_IsInternalChar()+ also might return
$-1$ and set \verb+T1_errno+, which indicates that the font in question is not
loaded. 

The information required to construct a composite character is retrieved by
calling the function
\precorr
\begin{verbatim}
 T1_COMP_CHAR_INFO *T1_GetCompCharData( int FontID, char char1)
\end{verbatim}\index{\verb+T1_GetCompCharData()+}\postcorr
It returns a pointer to a meaningfully filled struct of type
\verb+T1_COMP_CHAR_INFO+ as described above. The composite character and the
number 
of pieces as well as a pointer to the array of type \verb+T1_COMP_PIECE+ are
stored in this structure. Once this information is obtained the composite
character can be constructed by
\begin{itemize}
\item placing the accent symbols in a loop that ranges from $1$ to
  \verb+numPieces+$-1$. In practice this loop will often be executed only
  once. The initial current point must always be restored. In this loop
  positioning information is accessed by \verb+ptr->pieces[+$i$\verb+].deltax+
  and \verb+ptr->pieces[+$i$\verb+].deltay+, where \verb+ptr+ is the pointer
  returned by the above function.
\item placing the base character (\verb+pieces[0]+), which then also causes
  the horizontal escapement of the composite character. 
\end{itemize}

In cases where \verb+char1+ is not a composite
character, the \verb+compchar+ entry is set to \verb+char1+ itself and
\verb+numPieces+ becomes $1$, as would be expected. The \verb+pieces+ pointer
is then set to \verb+NULL+. In case of errors, this function returns
\verb+NULL+ and \verb+T1_errno+ is setup correspondingly.

The pointer returned by this function should always be free'd  using
\verb+T1_FreeCompCharData()+ in order to avoid memory leaks (see also
Section~\ref{deletingdata}).

A function that provides the same functionality is
\precorr
\begin{verbatim}
 T1_COMP_CHAR_INFO *T1_GetCompCharDataByIndex( int FontID, int index)
\end{verbatim}\index{\verb+T1_GetCompCharDataByIndex()+}\postcorr
In this case, the information is requested by means of an index \verb+index+
in the AFM composite character data array. This function is thus well-suited
for scanning the complete composite character information of a given font in a
given encoding. \verb+index+ may, for example, be obtained by a call to
\verb+T1_QueryCompCharData()+ as described above. The valid range for
\verb+index+ is from $0$ to the value returned by
\verb+T1_GetNoCompositeChars()+ minus one. The range of \verb+index+ is
validated and in case of an error \verb+T1_errno+ is to
\verb+T1ERR_INVALID_PARAMETER+. There may also appear other errors and under any
erroneous condition, \verb+NULL+ is returned.

The parameter \verb+compchar+ of the \verb+T1_COMP_CHAR_INFO+ structure that
is referenced by the returned pointer, bears somewhat more information for
this function than in the case of \\
\verb+T1_GetCompCharData()+. As said it contains the index in the encoding
vector where the composite glyph is encoded. It may also have the vaue $-1$,
which means that the composite character is not encoded. Note that this is not
an error condition.


\subsubsection{Transparent Handling of Composite Characters and User Extensions}
\label{subsubsec:Transparent Handling of Composite Characters and User
  Extensions}%

Aside from the fact that composite character information may be accessed in
\tonelib, \tonelib\ can automatically---and completely transparently with
respect to the user---compose characters if it finds information on how to do
so.  To give an instance, let us examine the font ComputerModern Roman
(cmr10). Because this font is specially encoded for the use with early (7-bit)
\TeX-systems, it does not incorporate a definition for \verb+Adieresis+. The
definition simply was not required because \TeX\ itself constructed the
composite character by means of its \verb+\accent+-primitive.  If a font like
cmr10 is reencoded e.g.~to IsoLatin1 encoding, the character ``\"A'' will show
up as a blank because there is no definition for \verb+Adieresis+. Now, if the
corresponding AFM file is extended with the following lines, it becomes
possible to access an \verb+Adieresis+:
\begin{verbatim}
StartComposites 1
CC Adieresis 2; PCC A 0 0; PCC dieresis 100 200;
EndComposites
\end{verbatim}
This line in an AFM file provides information about how to construct an
\verb+Adieresis+ from the \verb+A+ and  \verb+dieresis+ glyphs, and \tonelib\
can utilize this information to construct the requested glyph without that
this will be be noticed by the user. 

Composite character are treated just the same way as standard characters.
They are cached, they can be scaled, transformed etc. Let us assume that the
cache is still empty and a character, identified by its encoding index, now is
to be rastered. The following happens in the rastering function:
\begin{enumerate}
\item \tonelib\ looks up the character's name in the encoding vector and tries
  to locate the CharString for that character. If this succeeds all works as
  usual, notwithstanding the fact that there might have been composite
  character information for that char. This means, font-internal
  CharString-definitions have highest priority: One cannot, for example,
  re-define an \verb+Adieresis+ by raising the umlaut ``\"{ }'' via a composite
  character definition, if \verb+Adieresis+ is defined internally.
\item However, if the CharString is not found, composite character information
  is examined and if possible, elementary units are used to construct the
  requested composite character by concatenating paths.
\end{enumerate}
In any case, the resulting character is put into the cache and is from then on
available as any other character. If pieces of a composite character are not
found in the CharStrings dictionary, those pieces are substituted by
\verb+.notdef+, so that for extreme cases the whole composite character might
be substituted by a \verb+.notdef+. Then, an appropriate message is put into
the log file with priority \verb+T1LOG_WARNING+ and \verb+T1_errno+ is set to 
\verb+T1ERR_COMPOSITE_CHAR+.

In the same way \tonelib\ composes characters without user intervention, the
functions for character metrics are aware of composite character information
and the returned result are also valid for those functions.


\subsubsection{Caveats}
\label{subsubsec:Caveats}%

Although handling of composite character is widely automated, problems may
arise. Most importantly it is the responsibility of the user to take care that
font file and AFM file provide consistent data. Alas, this is not always true
for existing font and AFM files. If, for example, an AFM file is extended by
composite character definitions and these composite character definitions
reference symbols that are not defined in the CharsStrings dictionary, errors
will result. If composite character information is added to an AFM file, the
following rules have to be respected:
\begin{itemize}
\item The name of the composite character has to be encoded because it could
  not be accessed otherwise. Furthermore, no internal definition in the
  CharStrings dictionary may exist because this would override the composite
  character definition from the AFM file.
\item The user should verify that all components of a composite character
  definition have entries in the CharStrings dictionary. This can be checked
  for example by using\\ \verb+T1_GetAllCharNames()+ or by disassembling the font
  file. 
\item Even being more restrictive, the user should take care that all pieces
  of a composite character are encoded. For \tonelib\, this is really
  irrelevant because, internally, characters may be accessed by the name of
  their CharString. This means \tonelib\ simultaneously has access to all
  characters defined in a font. However, an application that exports PostScript
  files can only access character definitions via their position in the
  encoding vector. Composing a character from pieces of different encodings
  will require two font definitions in a exported PostScript file for
  typesetting one character, which cannot be termed a clean strategy.
\end{itemize}


\subsection{Error Handling}
\label{errorhandling}%
Although every function usually returns meaningful values, there are
situations where indicating an error via the return value is not possible. For
example, requesting a charspace bounding box from a char of a font which is not
loaded will return a bounding box containing all zeroes. This cannot be
considered an error-condition since for characters like ``space'' it is
correct to return a bounding box containing all zeroes. Furthermore, there's no
consistent scheme which value should indicate what type of error. In order to
allow a unified error handling in applications, the global variable
\verb+T1_errno+ has been introduced. 

The functionality of \verb+T1_errno+ is analogous to that of the global
\verb+errno+ in C programs. \verb+T1_errno+ is once set to 0 when the library
is initialized and never reset by any \tonelib-function. It is set to specific
values when specific types of errors appear. An application may then act
appropriately and reset \verb+T1_errno+.
The errors that might appear can be roughly split into three categories as
described below.

\subsubsection{Type 1 Font File Scan-Errors}
These types of errors can only appear at the time a font file is loaded.
These kinds of errors are indicated by negative values:
\begin{itemize}
\item \verb+T1ERR_SCAN_FONT_FORMAT+ (-5): A Multiple Master Font was attempted
  to be loaded. These are not supported by \tonelib.
\item \verb+T1ERR_SCAN_FILE_OPEN_ERR+ (-4): This value indicates that the Type
  1 font file could not be opened by the parser. It usually does not mean that
  the file does not exist because this problem would have shown up at the time
  the font database had been built. It is more likely a permission problem.
  Anyhow, the C library variable \verb+errno+ should be examined for getting
  an idea of what the problem was.
\item \verb+T1ERR_SCAN_OUT_OF_MEMORY+ (-3): A Type 1 font program required
  more than 262144 bytes of VM. This is a limit imposed by \tonelib\ because
  it usually means there goes something wrong. Typical values of VM
  consumption are between 30000 and 60000 bytes depending on the fonts'
  complexity. If this limit really does not suffice the constant
  \verb+MAXTRIAL+ (defined in \verb+lib/type1/fontfcn.c+) may be set to some
  larger value. 
\item \verb+T1ERR_SCAN_ERROR+ (-2): An error occurred during scanning the font
  file. It usually means that the font file is damaged or does not comply to
  the conventions of Type 1 font files. For example, an encountered token might
  have been too long. Another reason could be, a literal name follows a literal
  name where a number was expected. There is no way to recover from this
  error. One last resort could be to disassemble the font (e.g., using
  \verb+t1disasm+ from the \verb+t1utils+ package) and scan the resulting
  human-readable file for possible violations of the Type 1 font format
  specifications. However, some knowledge about the format is in force.
\item \verb+T1ERR_SCAN_FILE_EOF+ (-1): A premature end of file was encountered
  during parsing. The file is damaged.
\end{itemize}


\subsubsection{Path Generation Errors}
Small positive number are reserved for errors that might appear during path
construction and rasterization. 
\begin{itemize}
\item \verb+T1ERR_PATH_ERROR+ (1): An error occurred during path
  construction. The font file is most probably damaged.
\item \verb+T1ERR_PARSE_ERROR+ (2): This kind of error describes a kind of
  ``semantic'' error in the font file. A typical candidate for this is a font
  that does not define a character named \verb+.notdef+, although this is
  required by the format specification. Since under usual conditions the
  \verb+.notdef+ character is never accessed, this error would not show
  up. But if for some reason the \verb+.notdef+ has to be substituted for some
  other character the problem becomes evident.
\item \verb+T1ERR_TYPE1_ABORT+ (3): The \verb+abort()+-function of the
  rasterizer has been called. This may happen at several places during
  hinting, converting to edgelists etc. There is a certain chance that
  unfreed memory has been left. If this error appears and a logfile is used,
  an error string giving some more info is placed into the logfile.
  
  This error should not appear, normally. If it does, either the font file is
  damaged or the font contains invalid outline descriptions such as unclosed
  paths. Especially the latter is quite unlikely. Of course this error can be
  raised, when an outline has been modified manually in an invalid way and is
  then rastered (see.~\ref{outlinemanipulation}).
\end{itemize}

\subsubsection{\tonelib-Errors}
The remaining types of errors are detected by the management of \tonelib. Their
numbering starts with 10 (decimal). The list could be extended in future
releases. 
\begin{itemize}
\item \verb+T1ERR_INVALID_FONTID+ (10): An invalid font ID has been
  specified. The exact meaning of this error depends on the specific
  situation, in any case the operation requested cannot be realized with the
  identified font. Possible reasons are:
  \begin{itemize}
  \item The font ID points to a font which is not loaded and which must be
    loaded in order to perform the operation.
  \item The specified font ID is a number which is generally out of the range
    of the valid font IDs, either because it is $<0$ or because it is $>$ the
    value of \verb+no_fonts+.
  \item The library is not yet initialized so that no font ID at all is valid.
  \end{itemize}
\item \verb+T1ERR_INVALID_PARAMETER+ (11): One or more of the parameters
  specified to a function call were assigned invalid values. For example, a
  size-value specified to a rastering function must always be $>0$. Just the
  same way, \verb+T1_ConcatGlyphs()+ cannot concatenate two glyphs if one of
  them is the \verb+NULL+ pointer.
\item \verb+T1ERR_OP_NOT_PERMITTED+ (12): An operation that was not allowed
  {\em at that time} has been requested. This error could result, for example,
  if an application tries to set a new bitmap padding value after \tonelib\
  has been initialized. 
\item \verb+T1ERR_ALLOC_MEM+ (13): This error indicates that \tonelib\ ran out
  of memory and a memory allocation failed. This error should not appear.
\item \verb+T1ERR_FILE_OPEN_ERR+ (14): A file that was needed could not be
  opened by \tonelib. The file might have been necessary for reading data or
  writing data. For example, \verb+T1_WriteAFMFallbackFile()+ returns this
  value if the AFM file could not be opened for writing and
  \verb+T1_LoadEncoding()+ returns it if the encoding file specified as
  argument could not be opened. Notice that there is no indication of the
  reason why the file opening failed. The C library
  variable \verb+errno+ should be examined to analyze this further.

  It should be mentioned that \verb+T1ERR_FILE_OPEN_ERR+ is only set if a file
  operation failed which was really in force. This means that at the time a
  font is loaded a missing AFM file does not cause \verb+T1_errno+ caused to
  be set to \verb+T1ERR_FILE_OPEN_ERR+. This is because \tonelib\ can
  automatically recover from this by generating AFM information on the fly (at
  the cost of computation time).
\item \verb+T1ERR_UNSPECIFIED+ (15): This value indicates nothing apart from
  that an error occurred and this error was not one the other errors. It can
  be considered a fallback. 
\item \verb+T1ERR_NO_AFM_DATA+ (16): A function has been called which needs
  AFM information and AFM information is not available, either because all
  attempts to generate AFM data failed or because the flag \verb+T1_NO_AFM+
  has been specified as part of the flag for \verb+T1_InitLib()+. 
\item \verb+T1ERR_X11+ (17): An error in an X11 library function occured. This
  could be caused by calling a function of the X11 interface without prior
  initialization of the X11 interface via \verb+T1_SetX11Params()+.
\item \verb+T1ERR_COMPOSITE_CHAR+ (18): A request to compose a composite
  character could not be fulfilled without problems because at least one part
  of the composite character was not found in the \verb+CharStrings+
  dictionary. This is bad because it indicates that font file and AFM file do
  match. Further errors or unsatisfactory rastering results have to be
  expected. 
\item \verb+T1ERR_SCAN_ENCODING+ (19): Scanning an encoding file failed. Since
  \tonelib\ uses a fallback approach---DVIPS-encoding is tried first and
  afterwards \tonelib-encoding---it is not clear at which place exactly a
  failure occured. However, further hints about what \tonelib\ thought about
  the file in question may be found in the log file. 
\end{itemize}
In analogy to the Standard C Library function \verb+strerror()+, \tonelib\
provides the function
\precorr
\begin{verbatim}
 const char *T1_StrError( int t1err)
\end{verbatim}\index{\verb+T1_StrError()+}\postcorr
It returns a pointer to a string describing the error corresponding to
\verb+t1err+. Usually, the argument should be directly specified as
\verb+T1_errno+. The memory where the returned string is stored is static in
\tonelib\ so that it may not be \verb+free()+'d.


\subsection{Other Useful Functions}
\label{otherfunctions}%
This subsection describes a few functions that had not been described up to
now but which however could be useful.

\precorr
\begin{verbatim}
 int T1_CheckEndian( void)
\end{verbatim}\index{\verb+T1_CheckEndian()+}\postcorr
This function may be used to check the endianess of the hardware \tonelib\ is
running on. The return value is \verb+0+ for Little Endian and \verb+1+ for
Big Endian machines.

\precorr
\begin{verbatim}
 void T1_DumpGlyph( GLYPH *glyph)
\end{verbatim}\index{\verb+T1_DumpGlyph()+}\postcorr
This function might be useful for debugging and testing \tonelib. It dumps an
ASCII representation of the glyph pointed to by \verb+glyph+ to the standard
output. A background pixel is represented by \verb+.+ while a foreground pixel
is represented by \verb+X+. After the number of bits that correspond to the
current padding value, an empty column is inserted. See the output of the
programming example in \ref{programmingexample}. In this case the padding
values has been 16.

Note that the size of the glyph should be small enough that its padded width
does not exceed the terminals line width. Otherwise the result might become
illegible. 

\precorr
\begin{verbatim}
 void T1_DumpPath( T1_OUTLINE *path)
\end{verbatim}\index{\verb+T1_DumpPath()+}\postcorr
This function dumps a description of an outline to the standard output. It is
exclusively intended for debugging purposes.


\precorr
\begin{verbatim}
 void T1_SetRasterFlags( int flags)
\end{verbatim}\index{\verb+T1_SetRasterFlags()+}\postcorr
This function allows to enable or disable certain features of the
rasterizer. Let me emphasize that this is exclusively intended for debugging
and error tracking. The default value of \verb+flags+ is 0 which means that no
debugging output is shown and hinting is performed as suggested in the {\em Adobe
Type Font Format}. However there may arise situations where fiddling with the
\verb+flags+ might be helpful in rasterizer and font debugging. 

\verb+flags+ usually is an OR'ed combination of the following definitions:
\begin{itemize}
\item \verb+T1_IGNORE_FORCEBOLD+
\item \verb+T1_IGNORE_FAMILYALIGNMENT+
\item \verb+T1_IGNORE_HINTING+
\item \verb+T1_DEBUG_LINE+
\item \verb+T1_DEBUG_REGION+
\item \verb+T1_DEBUG_PATH+
\item \verb+T1_DEBUG_FONT+
\item \verb+T1_DEBUG_HINT+
\end{itemize}
The \verb+T1_IGNORE_...+ types allow to selectively disable hinting. They
might be useful if parts of a font are not properly rendered. For example,
substituting a font's alignment zones by the family's alignment zones might
result in visual artifacts if the values for \verb+FamilyBlues+ are not
correct. Disabling family alignment might reveal the problem in such cases.

The \verb+T1_DEBUG_...+ types produce debugging output from the intermediate
rasterizing steps. Notice that to understand this output a thorough
understanding of what happens in the rasterizer is in force. Moreover, be
prepared that thousands of lines might be written to the terminal, depending
on the particular option.

%%% Local Variables: 
%%% mode: latex
%%% TeX-master: "t1lib_doc"
%%% End: