Welcome to the
F R E E T Y P E P R O J E C T
http://www.freetype.org
Release 1.3.1
The FREE TrueType Font Engine
Copyright 1996 David Turner <david.turner@freetype.org>
- 1999 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 55kByte 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 and Pascal.
The C source code 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.
The Pascal code has been successfully compiled and run on DOS
(Borland's BP7) and OS/2 (fPrint's Virtual Pascal). A Delphi
port is in beta (the code in freetype/pascal compiles).
Unfortunately, it is not up to date compared to the C version.
- 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 New in 1.3: Support for embedded bitmaps.
This feature is already used in xtt, a TrueType font server
for X Window System.
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, and X11.
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.
- FreeType 1.3 is binary compatible with 1.2, which means that you
won't need to recompile your programs if they used the engine as
a shared library (libttf.so on Linux, or FreeType.dll on
Windows). See the file `freetype/docs/changes.txt' for more
information about (minimal) API changes.
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-13.zip'
which should be available at:
Hobbes: ftp://ftp.cdrom.com/pub/os2/fonts
SimTel: ftp://oak.oakland.edu/pub/simtel.net/msdos/graphics
* for UNIX and Amiga: `freetype-1.3.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/pub/freetype
Our home page is at:
http://www.freetype.org
Screen shots are available!
There are also three mailing lists:
o freetype-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 subscription commands to:
majordomo@freetype.org
To report bugs please use send an email to the address
bugs@freetype.org -- if you want help fixing bugs, contact
robert.wilhelm@freetype.org to be manually subscribed to this
closed list.
------------------------------------------------------------------
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.
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're really stuck, mail your question to:
freetype@freetype.org
We'll 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're welcome to volunteer for other platforms, like:
Amiga, RISC OS, BeOS, and others
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're 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
G : toggle GSUB 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 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 French, Dutch, Spanish, German, and Czech
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
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 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 ---
