Welcome to the F R E E T Y P E P R O J E C T http://www.freetype.org Release 1.4.9 The FREE TrueType Font Engine Copyright 1996 David Turner - 2001 Robert Wilhelm Werner Lemberg 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. 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 xtt, 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. - FreeType 1.4 is binary compatible with 1.3.1, 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. - 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-149.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.4.9.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/ 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 [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'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 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 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 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 ---