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
|
Welcome to the
F R E E T Y P E P R O J E C T
http://www.freetype.org
Release 1.5
The FREE TrueType Font Engine
Copyright 1996 David Turner <david.turner@freetype.org>
- 2001 Robert Wilhelm <robert.wilhelm@freetype.org>
Werner Lemberg <werner.lemberg@freetype.org>
Table of Contents
-----------------
I. Introduction
II. The FreeType mini-FAQ
III. How to use the test programs
1. ftzoom
2. ftlint
3. ftview
4. fttimer
5. ftdump
6. ftstring
7. ftstrpnm
8. fterror
9. ftsbit
10. ftmetric
11. ftstrtto
IV. How to use the programs in the `contrib' directory
V. Final remarks
I. Introduction
===============
Please read the file `INSTALL' for installation instructions!
The FreeType engine is a free and portable TrueType font rendering
engine. It has been developed to provide TrueType support to a
great variety of platforms and environments.
Notice that FreeType is a *library*. It is *not* a font server
for your preferred environment, even though it has been written to
allow the design of many font servers.
To our knowledge, this is the only royalty-free complete TrueType
engine available. Moreover, its quality fully matches these of
Windows or the Macintosh, a thing that cannot be said for most
other commercial engines available.
FreeType is a clean-room implementation that is not derived from
the original TrueType engine developed by Apple and Microsoft. It
has been created with the sole help of the published TrueType
specifications, which, to our great surprise and pain, turned out
to be extremely poor or misleading in critical areas. Much hard
work has been undertaken to solve numerous ambiguities;
nevertheless, its end result is a portable, fast quality renderer!
The library itself takes about 53 kByte of Intel code, complete
with a TrueType byte-code interpreter and a high-performance
scan-line converter.
You will find in this release:
- A TrueType engine, with source code in ANSI C. It has been
successfully compiled and run on various platforms, including
MS-DOS, OS/2, Amiga, Linux, and several other variants of Unix.
It should be portable to many other platforms too.
- An API to be used by client applications and font servers,
providing several low level abstractions that can be used to
open font files and collections, create point sizes and load,
process and render glyph outlines and bitmaps.
- Support for the following features:
o Font smoothing, a.k.a. gray-level rendering.
Just like Windows 95, the renderer uses a `fine' algorithm
that only smoothes diagonals and curves, while keeping the
horizontal and vertical stems intact.
This results in glyphs that are much more legible than the
`fuzzy' ones generated by programs like Acrobat.
o Support for all character mapping formats.
o A full-featured TrueType byte-code interpreter.
The engine is able to hint the glyphs to produce excellent
output at small sizes. It was extremely difficult to get this
component right, due to the ambiguous and misleading TrueType
specifications. However, we now *match* Windows and Macintosh
qualities.
o TrueType collection support, when several fonts are embedded
in the same file.
o Support for extensions.
It is now possible to extend the library in parts to support
additional features, like optional tables that are not
considered by the current core engine.
o Kerning support.
Provided as a sample extension with this release, kerning
tables can be accessed from a TrueType font for applications
that need it.
o Support for vertical metrics.
It is possible to load vertical metrics when they are present
in a font file. Metrics can be retrieved glyph by glyph,
using the loader, or in arrays with a new API.
o Support for thread-safety and re-entrancy.
You will only need to specialize the file `ttmutex.c' for your
platform to include system-specific synchronization calls.
o Support for embedded bitmaps.
This feature is already used in x-tt, a TrueType font server
for X Window System.
o Support for OpenType. With this release, GSUB and GPOS have
been completely implemented.
Note also that:
- Though development of the library is mainly performed on OS/2
and Linux, the library does not contain system-specific code.
- The package contains some graphics drivers used by the test
programs for display purposes on MS-DOS, OS/2, Amiga, X11, and
Windows. These drivers are absolutely not mandatory for running
the FreeType engine. Some console-mode test programs like
`ftlint' or `ftdump' don't use graphics at all.
- There was a Pascal version that was distributed along with the C
version. Unfortunately, it is not up to date when compared to
the C version, so we decided to split the two projects. If you
are interested, you can find the Pascal version in packages
named like `ftpascal-1.x.tar.gz' or `ftpas1x.zip'.
II. The FreeType mini-FAQ
=========================
Summary
0. Where to find the latest FreeType release?
1. Did the API change?
2. What does the `Free' in FreeType means? Can you use it in a
commercial product? (YES!)
3. I have made a small program based on the test programs but I
would like to know how to do xxx?
4. When will I be able to use FreeType to display TrueType fonts
under X11, OS/2 or Wine? (NOW!)
5. Trying to compile the FreeType sources gives me lots of
warnings with my ANSI C compliant compiler!
------------------------------------------------------------------
0. Where to find the latest FreeType release?
The latest package is usually uploaded to various source
repositories, like SunSite, SimTel, or Hobbes. There are two
archive formats (zip and tar.gz), which also differ by their
CR/LF conventions.
* for DOS and OS/2: `ft-15.zip'
which should be available at:
Hobbes: ftp://ftp.cdrom.com/pub/os2/misc
SimTel: ftp://ftp.simtel.net/pub/msdos/graphics
* for UNIX and Amiga: `freetype-1.5.tar.gz'
look at:
SunSite: ftp://sunsite.unc.edu/pub/Linux/X11/fonts
As uploading can take several days before the package becomes
available to the public, we advise you to download it from our
own ftp site if you read this message few days after the
announcement at:
ftp://ftp.freetype.org/freetype/
Our home page is at:
http://www.freetype.org
Screen shots are available!
There are also three mailing lists:
o announce@freetype.org
Announcements only about new versions of FreeType and
related packages. This list is moderated and expected to
have very low traffic.
o freetype@freetype.org
Discusses general use of FreeType, future, and needed
additions, as well as many other font-related discussions
which do not always relate directly to the FreeType code
itself...
o devel@freetype.org
Discusses development, design choices, portability issues,
internals, specific licenses, etc.
To subscribe, send the usual "subscribe" command to:
announce-request@freetype.org
freetype-request@freetype.org
devel-request@freetype.org
To report bugs please use send an e-mail to devel@freetype.org.
------------------------------------------------------------------
1. Did the API change since the version 1.2?
Only very marginally. Please refer to `changes.txt'.
------------------------------------------------------------------
2. What does the `Free' in FreeType means? Can you use it in a
commercial product? (YES!)
We have placed this release under our special FreeType license.
It was inspired by the BSD, Artistic, and IJG (Independent JPEG
group) licences, which specifically encourage the use of this
software in commercial products!
The reason we did this is that we believe that TrueType is a
very useful technology, and want to make it available on all
machines and platforms. The license is there to ensure that
the engine can be spread as widely as possible.
Since version 1.5, you can also optionally choose to use the
GNU Public Licence (GPL) instead. The GPL is used only to allow
GPL-ed applications to use FreeType (since the "disclaimer
clause" is considered an unacceptable "restriction" in GNU
speak); for a commercial product, you should avoid the GPL, and
then elect the FreeType licence.
However, free does not mean public domain. This engine is
copyrighted by its authors, and they will fiercely defend their
rights.
------------------------------------------------------------------
3. I have made a small program based on the test programs but I
would like to know how to do xxx?
(Where xxx is a feature lacking from the current
implementation).
First of all, read the documentation. The user guide gives
some basic hints and concepts. You can also read the source
code of the test programs that you didn't consider yet. If
you are really stuck, mail your question to:
freetype@freetype.org
We shall try to help you.
------------------------------------------------------------------
4. When will I be able to use FreeType to display TrueType fonts
under X11, OS/2, or Wine?
You can already do that under X11 and OS/2 :-) Go to the
FreeType web page (http://www.freetype.org) for up-to-date
information.
And yes, it looks terrific!
For X11, you could also take a look at `xfstt', an independent
TrueType font server for Unix which doesn't rely on the
FreeType code.
You are welcome to volunteer for other platforms, like:
Amiga, RISC OS, BeOS, and others
[Note that the FreeType library is already available with Amiga
and BeOS.]
Please contact devel@freetype.org for more information.
------------------------------------------------------------------
5. Trying to compile the FreeType sources gives me lots of
warnings with my ANSI C compliant compiler!
We use gcc as our reference compiler for warnings. This means
that we use the `-ansi -pedantic -Wall' flags and try to get
rid of warnings in this situation.
If you are compiling with another compiler, you may encounter
warnings, not errors.
We have spent much efforts to reduce seriously the number of
warnings produced by major compilers, including Visual Age,
Visual C++ and Borland C++.
Note that the Borland compilers seem to produce lots of
irrelevant warnings (like `potential loss of precision').
III. How to use the test programs
=================================
All test programs having a graphic interface use the same key
convention:
x : fine counter_clockwise rotation
c : fine clockwise rotation
v : fast counter_clockwise rotation
b : fast clockwise rotation
h : toggle hinting on/off
K : toggle kerning on/off
B : toggle display of embedded bitmaps on/off
S : toggle GSUB on/off
P : toggle GPOS on/off
+ : fast scale up
- : fast scale down
u : fine scale up
j : fine scale down
l : go to next glyph
k : go to previous glyph
o : go to tenth next glyph
i : go to tenth previous glyph
0 : go to hundredth next glyph (useful for CJK fonts)
9 : go to hundredth previous glyph
) : go to thousandth next glyph
( : go to thousandth previous glyph
} : go to tenthousandth next glyph
{ : go to tenthousandth previous glyph
q :
ESC : exit
These keys were chosen because they are available on all
platforms. Note also that each program uses only a subset of this
key map.
1. FTZOOM
---------
`ftzoom' is a very simple glyph viewer that supports font
smoothing. Its usage is:
ftzoom [-g] [-p platformID -e encodingID]
[-r resolution] [-z magnification] [-n] fontfilename
With -g you can select gray-scaling; with -n you can suppress
usage of the `post' table in the TrueType font.
For example:
ftzoom arial.ttf to show the glyphs found
in the Arial font
ftzoom -g times.ttf to show smoothed version of
Times's glyphs.
ftzoom -p 3 -e 1 uwjmg3.ttf use cmap for platform ID 3,
encoding ID 1 for this Japanese
font.
2. FTLINT
---------
`ftlint' is used to execute all glyphs instructions found in a
font file at a given char size size. Its usage is:
ftlint pointsize fontfilename [fontfilename] ...
For example:
ftlint 12 arial.ttf
ftlint 15 times.ttf
It reports error codes and faulty glyph numbers. This is a
console tool that doesn't need the graphics subsystem.
NOTE: Trying to hint at sizes smaller than 7 is irrelevant.
3. FTVIEW
---------
A font viewer that supports hinting and font smoothing. Its
usage:
ftview [-g] -[r resolution] [-B] pointsize fontfilename
like in:
ftview 12 arial.ttf show the hinted Arial at size 12pt.
ftview -g 15 timesi.ttf show the hinted and font-smoothed
Times at size 15pt.
`-r' selects the resolution; `-B' forces the use of embedded
bitmaps.
Note that it is possible to change the point size during display
with the keys `u', `j', `+', and `-'. It is also possible to
browse the whole glyph set with the `k', `l', `i', `o', `0',
`9', `(', `)', `{', and `}' keys (see key map above).
The OS/2 PM driver comes with an additional magnifying window.
The magnified zone is set with the mouse, while the scale is
changed with the help of `PageUp' and `PageDown'.
Note 1: The engine uses the font's CVT program to determine at
which size to enable or disable glyph hinting. Don't be
surprised to see unhinted glyphs at sizes < 7pt.
Note 2: Vertical drop-out control has been added to the gray
scaling renderer. As a consequence, the library doesn't
produce unpleasant results at small ppems with badly
hinted glyphs.
4. FTTIMER
----------
This program is used to benchmark FreeType's scan-converter (the
component in charge of translating a vectorial shape description
into a bitmap). It does so in preloading all glyphs from a font
file, then rendering them as fast as possible in a 640x450
buffer. The glyphs are rendered at size 400pt / 96dpi, which is
_quite_ big.
Its usage is:
fttimer [-g] [-v] fontfilename
where
-g : Asks for gray-level rendering at size 200pt instead
(a.k.a. font-smoothing).
-v : Asks for the display of the produced bitmap. Beware
that display slows things down (display on X11 is
_terrible_, especially with gray-levels, but this is
not a problem for us :-).
Note that the returned numbers are not a benchmark of FreeType's
overall performance! Only of the scan-line renderer (which
seems quite fast, apparently :-).
When comparing measured performances across machines, please
only consider the undisplayed ones. We're interested in all
kinds of results (please provide the following information:
font file
number of rendered glyphs
render time
total time
glyphs / s
processor type
CPU clock
and which compiler used (with optimization involved)! This
can make a great difference!
etc.)
5. FTDUMP
---------
This program is a very simple font dumper. In its current
incarnation, it will only output a font's name table, character
encoding maps IDs and total memory consumption. For TrueType
Open files, the available GSUB and GPOS tables are also shown.
The `total memory used' reported is the amount that is used by
the engine to load one face, with one instance (a point size).
Each additional instance takes only a fraction of that amount,
and is labeled by `instance object'. As you can see, FreeType
isn't really greedy.
Usage: ftdump fontpathname[.ttf|.ttc]
6. FTSTRING
-----------
This program demonstrates string text generation. It only
displays a given message on the screen, and lets you resize it
with the classic key bindings `u', `j', `+', and `-'.
Usage:
ftstring ptsize fontname[.ttf|.ttc] [message_string]
If the message is omitted, it will revert to the classic
typographic test sentence:
The quick brown fox jumps over the lazy dog
which is made of all letters of the English alphabet.
`ftstring' only works with font files that contain a Unicode
character mapping table (either Windows Unicode or Apple
Unicode). For the moment, the message can however only be
written in ASCII, as accents aren't supported yet.
7. FTSTRPNM
-----------
Usage:
ftstrpnm [options] filename [string]
Options:
-g gray-level rendering (default: off)
-h hinting off (default: on)
-r X resolution X dpi (default: 96)
-p X pointsize X pt (default: 12)
-b X border X pixels wide (default: 0)
This program is quite similar to ftstring but converts the
rendered image of the specified string into a bitmap in PBM or
PGM format written to stdout; PBM (Portable BitMap) and PGM
(Portable GrayMap) formats can be further converted to popular
graphics formats like GIF or PNG with the netpbm tool suite
available via Internet.
8. FTERROR
----------
This program tests the gettext() functionality on UNIX platforms
(usually provided in the GNU gettext package). It will return
language specific error and warning messages depending on your
locale. Currently Czech, Dutch, French, German, and Spanish
translations of the FreeType messages are included -- we invite
you to contribute more translations.
Typically, you have to set the LANG environment variable to your
locale to get localized messages. Example:
LANG=de fterror
fterror also gives you a textual interpretation of a particular
(numerical) error code, as returned by the Freetype library.
Example:
LANG=fr fterror 0x40E
Note that providing message strings for FreeType's error and
warning messages is an extension and not part of the FreeType
library itself. Please refer to `docs/i18n.txt' for further
details.
9. FTSBIT
---------
Usage:
ftsbit ppem fontname[.ttf|.ttc] glyph_index [glyph_index2..]
This tool dumps the information in the tables for embedded
bitmaps. Additionally, it prints (to the console) a selected
glyph bitmap.
10. FTMETRIC
------------
Usage:
ftmetric [options below] point fontname[.ttf|.ttc] ...
-B show sbit's metrics (default: none)
-c C use C'th font index of TrueType collection
(default: 0)
-i index glyph index (default: 0)
-r R use resolution R dpi (default: 72dpi)
With this small program you can inspect the metric data of a
given glyph; additionally, it dumps the particular glyph to the
console.
11. FTSTRTTO
------------
Usage:
ftstrtto [options below] ppem fontname[.ttf|.ttc] [string|-]
-c C use font with index C in TrueType collection
(default: 0)
-f F use feature F (can be specified more than once)
-g gray-level rendering
-l L use language L
-r R use resolution R dpi (default: 96dpi)
-s S use script S
-u interpret input data as UTF8-encoded
-v display string vertically
-x display string from right to left
F, L, and S must be specified as 4-character tags.
Specifying only F and S selects default language system of S.
Specifying only L and S selects the req. feature of L only
(if any).
If `-' is specified as input string, stdin is read instead.
This program uses almost all features of FreeType to display a
string on screen. Its usage is similar to `ftstring', but you
can additionally select GSUB and GPOS features, the collection
in a font, toggle kerning and embedded bitmaps interactively,
and input the optional string in UTF8 encoding.
For a list of available script, language, and feature tags
please refer to the TrueType Open (resp. OpenType)
specification.
Example:
ftstrtto -s "latn" -l "DEU " -f "liga" -f "frac" \
40 pala.ttf "fi ff ffi ffl 1/2"
Note that you can inspect the available tags in a font with
`ftdump'.
The features `init', `medi', and `fina', and `isol' are treated
specially. Internally, ftstrtto assigns initial, medial,
isolated, and final properties to Arabic characters in the input
string. If one of the features is switched on, all glyphs with
the corresponding property are modified (if covered).
Example:
ftstrtto -s arab -f init -f medi -f fina -f isol \
-f liga -f mset -x -u 20 trado.ttf - < arab.utf8
`mset' is another, Arabic specific feature to position combining
marks.
If you select the swash feature `swsh', the displayed
alternative in the string is always the first available one.
IV. HOW TO USE THE PROGRAMS IN THE `CONTRIB' DIRECTORY
======================================================
These programs are contributions to FreeType and not really part
of it. Please read the documentation files in the respective
subdirectories how to compile and install them.
V. FINAL REMARKS
================
Of course, all source code is provided `as is'. Please read the
file `license.txt' for more information.
We hope you will find this engine useful, and look forward to file.
your feed-back. We're of course very interested in bug reports, as
well as FreeType success stories :-)
Thanks for your time and consideration,
David Turner, Robert Wilhelm, Werner Lemberg,
and all the FreeType enthusiasts...
--- end of README ---
|