5 F R E E T Y P E P R O J E C T
7 http://www.freetype.org
11 The FREE TrueType Font Engine
13 Copyright 1996 David Turner <david.turner@freetype.org>
14 - 1999 Robert Wilhelm <robert.wilhelm@freetype.org>
15 Werner Lemberg <werner.lemberg@freetype.org>
23 II. The FreeType mini-FAQ
25 III. How to use the test programs
39 IV. How to use the programs in the `contrib' directory
47 Please read the file `INSTALL' for installation instructions!
49 The FreeType engine is a free and portable TrueType font rendering
50 engine. It has been developed to provide TrueType support to a
51 great variety of platforms and environments.
53 Notice that FreeType is a *library*. It is *not* a font server
54 for your preferred environment, even though it has been written to
55 allow the design of many font servers.
57 To our knowledge, this is the only royalty-free complete TrueType
58 engine available. Moreover, its quality fully matches these of
59 Windows or the Macintosh, a thing that cannot be said for most
60 other commercial engines available.
62 FreeType is a clean-room implementation that is not derived from
63 the original TrueType engine developed by Apple and Microsoft. It
64 has been created with the sole help of the published TrueType
65 specifications, which, to our great surprise and pain, turned out
66 to be extremely poor or misleading in critical areas. Much hard
67 work has been undertaken to solve numerous ambiguities;
68 nevertheless, its end result is a portable, fast quality renderer!
70 The library itself takes about 55kByte of Intel code, complete
71 with a TrueType byte-code interpreter and a high-performance
74 You will find in this release:
76 - A TrueType engine, with source code in ANSI C and Pascal.
78 The C source code has been successfully compiled and run on
79 various platforms, including MS-DOS, OS/2, Amiga, Linux, and
80 several other variants of Unix. It should be portable to many
83 The Pascal code has been successfully compiled and run on DOS
84 (Borland's BP7) and OS/2 (fPrint's Virtual Pascal). A Delphi
85 port is in beta (the code in freetype/pascal compiles).
86 Unfortunately, it is not up to date compared to the C version.
88 - An API to be used by client applications and font servers,
89 providing several low level abstractions that can be used to
90 open font files and collections, create point sizes and load,
91 process and render glyph outlines and bitmaps.
93 - Support for the following features:
95 o Font smoothing, a.k.a. gray-level rendering.
97 Just like Windows 95, the renderer uses a `fine' algorithm
98 that only smoothes diagonals and curves, while keeping the
99 horizontal and vertical stems intact.
101 This results in glyphs that are much more legible than the
102 `fuzzy' ones generated by programs like Acrobat.
104 o Support for all character mapping formats.
106 o A full-featured TrueType byte-code interpreter.
108 The engine is able to hint the glyphs to produce excellent
109 output at small sizes. It was extremely difficult to get this
110 component right, due to the ambiguous and misleading TrueType
111 specifications. However, we now *match* Windows and Macintosh
114 o TrueType collection support, when several fonts are embedded
117 o Support for extensions.
119 It is now possible to extend the library in parts to support
120 additional features, like optional tables that are not
121 considered by the current core engine.
125 Provided as a sample extension with this release, kerning
126 tables can be accessed from a TrueType font for applications
129 o Support for vertical metrics.
131 It is possible to load vertical metrics when they are present
132 in a font file. Metrics can be retrieved glyph by glyph,
133 using the loader, or in arrays with a new API.
135 o Support for thread-safety and re-entrancy.
137 You will only need to specialize the file `ttmutex.c' for your
138 platform to include system-specific synchronization calls.
140 o New in 1.3: Support for embedded bitmaps.
142 This feature is already used in xtt, a TrueType font server
147 - Though development of the library is mainly performed on OS/2
148 and Linux, the library does not contain system-specific code.
150 - The package contains some graphics drivers used by the test
151 programs for display purposes on MS-DOS, OS/2, Amiga, and X11.
152 These drivers are absolutely not mandatory for running the
153 FreeType engine. Some console-mode test programs like `ftlint'
154 or `ftdump' don't use graphics at all.
156 - FreeType 1.3 is binary compatible with 1.2, which means that you
157 won't need to recompile your programs if they used the engine as
158 a shared library (libttf.so on Linux, or FreeType.dll on
159 Windows). See the file `freetype/docs/changes.txt' for more
160 information about (minimal) API changes.
163 II. The FreeType mini-FAQ
164 =========================
168 0. Where to find the latest FreeType release?
170 1. Did the API change?
172 2. What does the `Free' in FreeType means? Can you use it in a
173 commercial product? (YES!)
175 3. I have made a small program based on the test programs but I
176 would like to know how to do xxx?
178 4. When will I be able to use FreeType to display TrueType fonts
179 under X11, OS/2 or Wine? (NOW!)
181 5. Trying to compile the FreeType sources gives me lots of
182 warnings with my ANSI C compliant compiler!
184 ------------------------------------------------------------------
186 0. Where to find the latest FreeType release?
188 The latest package is usually uploaded to various source
189 repositories, like SunSite, SimTel, or Hobbes. There are two
190 archive formats (zip and tar.gz), which also differ by their
193 * for DOS and OS/2: `ft-13.zip'
195 which should be available at:
197 Hobbes: ftp://ftp.cdrom.com/pub/os2/fonts
198 SimTel: ftp://oak.oakland.edu/pub/simtel.net/msdos/graphics
200 * for UNIX and Amiga: `freetype-1.3.tar.gz'
204 SunSite: ftp://sunsite.unc.edu/pub/Linux/X11/fonts
206 * As uploading can take several days before the package becomes
207 available to the public, we advise you to download it from
208 our own ftp site if you read this message few days after the
211 ftp://ftp.freetype.org/pub/freetype
215 http://www.freetype.org
217 Screen shots are available!
219 There are also three mailing lists:
221 o freetype-announce@freetype.org
223 Announcements only about new versions of FreeType and
224 related packages. This list is moderated and expected to
225 have very low traffic.
227 o freetype@freetype.org
229 Discusses general use of FreeType, future, and needed
230 additions, as well as many other font-related discussions
231 which do not always relate directly to the FreeType code
236 Discusses development, design choices, portability issues,
237 internals, specific licenses, etc.
239 To subscribe, send the usual subscription commands to:
241 majordomo@freetype.org
243 To report bugs please use send an email to the address
244 bugs@freetype.org -- if you want help fixing bugs, contact
245 robert.wilhelm@freetype.org to be manually subscribed to this
248 ------------------------------------------------------------------
250 1. Did the API change since the version 1.2?
252 Only very marginally. Please refer to `changes.txt'.
254 ------------------------------------------------------------------
256 2. What does the `Free' in FreeType means? Can you use it in a
257 commercial product? (YES!)
259 We have placed this release under our special FreeType license.
261 It was inspired by the BSD, Artistic, and IJG (Independent JPEG
262 group) licences, which specifically encourage the use of this
263 software in commercial products!
265 The reason we did this is that we believe that TrueType is a
266 very useful technology, and want to make it available on all
267 machines and platforms. The license is there to ensure that
268 the engine can be spread as widely as possible.
270 However, free does not mean public domain. This engine is
271 copyrighted by its authors, and they will fiercely defend their
274 ------------------------------------------------------------------
276 3. I have made a small program based on the test programs but I
277 would like to know how to do xxx?
279 (Where xxx is a feature lacking from the current
282 First of all, read the documentation. The user guide gives
283 some basic hints and concepts. You can also read the source
284 code of the test programs that you didn't consider yet. If
285 you're really stuck, mail your question to:
287 freetype@freetype.org
289 We'll try to help you.
291 ------------------------------------------------------------------
293 4. When will I be able to use FreeType to display TrueType fonts
294 under X11, OS/2, or Wine?
296 You can already do that under X11 and OS/2 :-) Go to the
297 FreeType web page (http://www.freetype.org) for up-to-date
300 And yes, it looks terrific!
302 For X11, you could also take a look at `xfstt', an independent
303 TrueType font server for Unix which doesn't rely on the
306 You're welcome to volunteer for other platforms, like:
308 Amiga, RISC OS, BeOS, and others
310 Please contact devel@freetype.org for more information.
312 ------------------------------------------------------------------
314 5. Trying to compile the FreeType sources gives me lots of
315 warnings with my ANSI C compliant compiler!
317 We use gcc as our reference compiler for warnings. This means
318 that we use the `-ansi -pedantic -Wall' flags and try to get
319 rid of warnings in this situation.
321 If you're compiling with another compiler, you may encounter
322 warnings, not errors.
324 We have spent much efforts to reduce seriously the number of
325 warnings produced by major compilers, including Visual Age,
326 Visual C++ and Borland C++.
328 Note that the Borland compilers seem to produce lots of
329 irrelevant warnings (like `potential loss of precision').
332 III. How to use the test programs
333 =================================
335 All test programs having a graphic interface use the same key
338 x : fine counter_clockwise rotation
339 c : fine clockwise rotation
341 v : fast counter_clockwise rotation
342 b : fast clockwise rotation
344 h : toggle hinting on/off
345 K : toggle kerning on/off
346 B : toggle display of embedded bitmaps on/off
347 G : toggle GSUB on/off
355 k : go to previous glyph
357 o : go to tenth next glyph
358 i : go to tenth previous glyph
360 0 : go to hundredth next glyph (useful for CJK fonts)
361 9 : go to hundredth previous glyph
363 ) : go to thousandth next glyph
364 ( : go to thousandth previous glyph
366 } : go to tenthousandth next glyph
367 { : go to tenthousandth previous glyph
372 These keys were chosen because they are available on all
373 platforms. Note also that each program uses only a subset of this
379 `ftzoom' is a very simple glyph viewer that supports font
380 smoothing. Its usage is:
382 ftzoom [-g] [-p platformID -e encodingID]
383 [-r resolution] [-z magnification] [-n] fontfilename
385 With -g you can select gray-scaling; with -n you can suppress
386 usage of the `post' table in the TrueType font.
390 ftzoom arial.ttf to show the glyphs found
392 ftzoom -g times.ttf to show smoothed version of
394 ftzoom -p 3 -e 1 uwjmg3.ttf use cmap for platform ID 3,
395 encoding ID 1 for this Japanese
401 `ftlint' is used to execute all glyphs instructions found in a
402 font file at a given char size size. Its usage is:
404 ftlint pointsize fontfilename [fontfilename] ...
411 It reports error codes and faulty glyph numbers. This is a
412 console tool that doesn't need the graphics subsystem.
414 NOTE: Trying to hint at sizes smaller than 7 is irrelevant.
419 A font viewer that supports hinting and font smoothing. Its
422 ftview [-g] -[r resolution] [-B] pointsize fontfilename
426 ftview 12 arial.ttf show the hinted Arial at size 12pt.
428 ftview -g 15 timesi.ttf show the hinted and font-smoothed
431 `-r' selects the resolution; `-B' forces the use of embedded
434 Note that it is possible to change the point size during display
435 with the keys `u', `j', `+', and `-'. It is also possible to
436 browse the whole glyph set with the `k', `l', `i', `o', `0',
437 `9', `(', `)', `{', and `}' keys (see key map above).
439 The OS/2 PM driver comes with an additional magnifying window.
440 The magnified zone is set with the mouse, while the scale is
441 changed with the help of `PageUp' and `PageDown'.
443 Note 1: The engine uses the font's CVT program to determine at
444 which size to enable or disable glyph hinting. Don't be
445 surprised to see unhinted glyphs at sizes < 7pt.
447 Note 2: Vertical drop-out control has been added to the gray
448 scaling renderer. As a consequence, the library doesn't
449 produce unpleasant results at small ppems with badly
455 This program is used to benchmark FreeType's scan-converter (the
456 component in charge of translating a vectorial shape description
457 into a bitmap). It does so in preloading all glyphs from a font
458 file, then rendering them as fast as possible in a 640x450
459 buffer. The glyphs are rendered at size 400pt / 96dpi, which is
464 fttimer [-g] [-v] fontfilename
468 -g : Asks for gray-level rendering at size 200pt instead
469 (a.k.a. font-smoothing).
471 -v : Asks for the display of the produced bitmap. Beware
472 that display slows things down (display on X11 is
473 _terrible_, especially with gray-levels, but this is
474 not a problem for us :-).
476 Note that the returned numbers are not a benchmark of FreeType's
477 overall performance! Only of the scan-line renderer (which
478 seems quite fast, apparently :-).
480 When comparing measured performances across machines, please
481 only consider the undisplayed ones. We're interested in all
482 kinds of results (please provide the following information:
485 number of rendered glyphs
492 and which compiler used (with optimization involved)! This
493 can make a great difference!
500 This program is a very simple font dumper. In its current
501 incarnation, it will only output a font's name table, character
502 encoding maps IDs and total memory consumption. For TrueType
503 Open files, the available GSUB tables are also shown.
505 The `total memory used' reported is the amount that is used by
506 the engine to load one face, with one instance (a point size).
508 Each additional instance takes only a fraction of that amount,
509 and is labeled by `instance object'. As you can see, FreeType
512 Usage: ftdump fontpathname[.ttf|.ttc]
517 This program demonstrates string text generation. It only
518 displays a given message on the screen, and lets you resize it
519 with the classic key bindings `u', `j', `+', and `-'.
523 ftstring ptsize fontname[.ttf|.ttc] [message_string]
525 If the message is omitted, it will revert to the classic
526 typographic test sentence:
528 The quick brown fox jumps over the lazy dog
530 which is made of all letters of the English alphabet.
532 `ftstring' only works with font files that contain a Unicode
533 character mapping table (either Windows Unicode or Apple
534 Unicode). For the moment, the message can however only be
535 written in ASCII, as accents aren't supported yet.
542 ftstrpnm [options] filename [string]
546 -g gray-level rendering (default: off)
547 -h hinting off (default: on)
548 -r X resolution X dpi (default: 96)
549 -p X pointsize X pt (default: 12)
550 -b X border X pixels wide (default: 0)
552 This program is quite similar to ftstring but converts the
553 rendered image of the specified string into a bitmap in PBM or
554 PGM format written to stdout; PBM (Portable BitMap) and PGM
555 (Portable GrayMap) formats can be further converted to popular
556 graphics formats like GIF or PNG with the netpbm tool suite
557 available via Internet.
562 This program tests the gettext() functionality on UNIX platforms
563 (usually provided in the GNU gettext package). It will return
564 language specific error and warning messages depending on your
565 locale. Currently French, Dutch, Spanish, German, and Czech
566 translations of the FreeType messages are included -- we invite
567 you to contribute more translations.
569 Typically, you have to set the LANG environment variable to your
570 locale to get localized messages. Example:
574 Note that providing message strings for FreeType's error and
575 warning messages is an extension and not part of the FreeType
576 library itself. Please refer to `docs/i18n.txt' for further
584 ftsbit ppem fontname[.ttf|.ttc] glyph_index [glyph_index2..]
586 This tool dumps the information in the tables for embedded
587 bitmaps. Additionally, it prints (to the console) a selected
595 ftmetric [options below] point fontname[.ttf|.ttc] ...
597 -B show sbit's metrics (default: none)
598 -c C use C'th font index of TrueType collection
600 -i index glyph index (default: 0)
601 -r R use resolution R dpi (default: 72dpi)
603 With this small program you can inspect the metric data of a
604 given glyph; additionally, it dumps the particular glyph to the
612 ftstrtto [options below] ppem fontname[.ttf|.ttc] [string|-]
614 -c C use font with index C in TrueType collection
616 -f F use feature F (can be specified more than once)
617 -g gray-level rendering
619 -r R use resolution R dpi (default: 96dpi)
621 -u interpret input data as UTF8-encoded
622 -v display string vertically
623 -x display string from right to left
625 F, L, and S must be specified as 4-character tags.
626 Specifying only F and S selects default language system of S.
627 Specifying only L and S selects the req. feature of L only
630 If `-' is specified as input string, stdin is read instead.
632 This program uses almost all features of FreeType to display a
633 string on screen. Its usage is similar to `ftstring', but you
634 can additionally select GSUB features, the collection in a font,
635 toggle kerning and embedded bitmaps interactively, and input the
636 optional string in UTF8 encoding.
638 For a list of available script, language, and feature tags
639 please refer to the TrueType Open (resp. OpenType)
644 ftstrtto -s "latn" -l "DEU " -f "liga" -f "frac" \
645 40 pala.ttf "fi ff ffi ffl 1/2"
647 Note that you can inspect the available tags in a font with
650 The features `init', `medi', and `fina', and `isol' are treated
651 specially. Internally, ftstrtto assigns initial, medial,
652 isolated, and final properties to Arabic characters in the input
653 string. If one of the features is switched on, all glyphs with
654 the corresponding property are modified (if covered).
658 ftstrtto -s arab -f init -f medi -f fina -f isol \
659 -f liga -f mset -x -u 20 trado.ttf - < arab.utf8
661 `mset' is another, Arabic specific feature to position combining
664 If you select the swash feature `swsh', the displayed
665 alternative in the string is always the first available one.
669 IV. HOW TO USE THE PROGRAMS IN THE `CONTRIB' DIRECTORY
670 ======================================================
672 These programs are contributions to FreeType and not really part
673 of it. Please read the documentation files in the respective
674 subdirectories how to compile and install them.
680 Of course, all source code is provided `as is'. Please read the
681 file `license.txt' for more information.
683 We hope you will find this engine useful, and look forward to file.
684 your feed-back. We're of course very interested in bug reports, as
685 well as FreeType success stories :-)
688 Thanks for your time and consideration,
691 David Turner, Robert Wilhelm, Werner Lemberg,
692 and all the FreeType enthusiasts...
695 --- end of README ---