FreeType User FAQ -------------------------------------------------------------------- Table of contents 1. How do I compile the test programs? 2. What are the test programs? 3. How do I use them? 4. How do I only compile the FreeType library? 5. The library compiles fine on my system, unfortunately it seems the test programs won't. What can I do? 6. What is FreeType, and what is it not? 7. Can FreeType be ported to other platforms? 8. My TrueType font only works on a Mac/in Windows. Will I be able to use it with FreeType? 9. What are the most common character mappings? 10. How do I render text with FreeType? 11. How do I render rotated/slanted text with FreeType? 12. How do I compute a glyph bitmap's dimensions? 13. Why is text rendering so slow? Does FreeType cache glyphs? 14. Do you always render the same glyphs as Windows or the Mac? 15. The program "ftlint" reports errors with one of my fonts, though it works perfectly under Windows. What does this mean? 16. What does the "fttimer" test program benchmarks? 17. Is it possible to perform styling (like oblique, italic, bold, underline, etc.) with FreeType? 18. When does glyph hinting takes place? Is it when the glyph is loaded, or when it is converted to a bitmap/pixmap? 19. Which is the best, caching outlines or bitmaps? 20. Can I open OpenType and/or TrueType GX fonts with FreeType? 21. How can I access additional TrueType tables that FreeType doesn't support? 22. When will I be able to use FreeType to display TrueType fonts in X11, Wine, or OS/2, or even other systems? 23. What does the "free" in FreeType really means? 24. Does FreeType support threads? Is it re-entrant? 25. Does FreeType support "foreign languages"? 26. I'm using fractional char sizes, but the glyphs stay at the same integer size. Why? 27. Hinting doesn't work at very small sizes. Why? -------------------------------------------------------------------- 1. How do I compile the test programs? Detailed compilation steps are given in the "freetype/HOWTO.txt" file, as well as system and compiler specific hints in the "freetype/howto" directory. What follows is a _very_ simple guide: For Unix: Do the following on the prompt while in the base directory of the FreeType package: % ./configure % make % make install This will build and install the library (static and shared, if supported) together with the test programs. Say `./configure --help' to see the available configuring options. This should work with any ANSI C compiler. For other platforms: Go to the 'test' directory. Look at one of the makefiles located in the 'arch/' directory, and use the appropriate makefile from there. For example: make -f arch/msdos/makefile.gcc (DJGPP or emx) wmake -f arch\msdos\makefile.wat (Watcom DOS) nmake -f arch\os2\makefile.icc (Visual Age OS/2) make -f arch/amigaos/makefile.gcc (GCC Amiga) This will compile both the library and the test programs. -------------------------------------------------------------------- 2. What are the test programs? The test programs are simple sources that "show off" the FreeType library. They're located in the 'test' directory. They make use of a small graphics sub-system which is able to display bitmaps and pixmaps on a variety of platforms through the use of system-specific 'drivers'. The test programs are: ftdump: A simple TTF information dumper. Also prints the memory used by each opened font file with FreeType. Doesn't use the graphics sub-system. ftlint: A simple TrueType bytecode verifier. It simply hints all glyphs of one or more font files at a given size and reports errors. Doesn't use the graphics sub-system. ftview: A simple font viewer. Displays all glyphs in a font file in a window. ftstring: Renders a simple string to the screen. Demonstrates how to produce text with FreeType. fttimer: A simple benchmark, used to profile the scan-line conversion routines (and only them). Supports also display. ftstrpnm: A version of 'ftstring' which saves a bit/pixmap to a PNM file rather than to the screen. No graphics sub-system needed. ftzoom: A simple glyph viewer, useful to view, zoom and rotate individual glyphs in a font file. NOTE: The file 'ftdebug.c' isn't part of the test suite. It is used only by the developers team to debug the engine at a higher level. It won't work with a standard library compile. The tiny graphics subsystem is defined in the following files: gmain.h/gmain.c: The subsystem's main body/interface. gevents.h: The definition of events defined for the subsystem gdriver.h: The generic interface of all system-specific drivers. In addition to several files in the 'test/arch/' directories, like: test/arch/msdos/gfs_dos.c Full-Screen DOS driver test/arch/os2/gpm_os2.c PM (Windowed) OS/2 driver test/arch/unix/gwin_x11.c X11 Windowed driver etc. -------------------------------------------------------------------- 3. How do I use them? The following keyboard mapping has been chosen for all test programs. It's not fancy, but at least works on all platforms easily: x : fine counter-clockwise rotation (ftzoom only) c : fine clockwise rotation (ftzoom only) v : fast counter-clockwise rotation (ftzoom only) b : fast clockwise rotation (ftzoom only) h : toggle hinting on/off [default is on] + : 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 9 : go to hundredth next glyph (useful for large fonts) 0 : go to hundredth previous glyph ( : go to 1000th next glyph (useful for Unicode and CJK fonts) ) : go to 1000th previous glyph { : go to 10000th next glyph } : go to 10000th previous glyph ESC : q : exit -------------------------------------------------------------------- 4. How do I only compile the FreeType library? For Unix: Do a `configure' run as described in section 1. Then change to the lib subdirectory and say `make' and `make install'. For other platforms: Go to the 'lib' directory. Look at one of the makefiles located in the 'arch/' directory, and use it from 'lib'. For example: make -f arch/msdos/makefile.gcc (DJGPP or emx) wmake -f=arch\msdos\makefile.wat (Watcom DOS) nmake -f arch\os2\makefile.icc (Visual Age OS/2) make -f arch/amigaos/makefile.gcc (GCC Amiga) The library is pure ANSI C and doesn't depend on any system-specific package. You need not gcc to compile it. -------------------------------------------------------------------- 5. The library compiles fine on my system, unfortunately it seems the test programs won't. What can I do? As said before, the test programs rely on a small graphics sub-system to display the bitmaps and pixmaps produced by the library. The following systems are currently supported: DOS Full-Screen Amiga Full-Screen Note that the windowed graphics Amiga Windowed driver are very 'basic', they do OS/2 Full-Screen not provide menus, dialog boxes, OS/2 Windowed etc. Rather, they provide one X11 Windowed windowed bitmap/pixmap and translate events to the ones defined in "test/gevents". If you want to add support to your system (like Windows), you should write a new graphics driver. To do that, read the file "test/gdriver.h" which contains the driver generic interface, then browse the drivers that are already provided. The graphics drivers are located in the "test/arch/" directories. They're not part of the library proper. IMPORTANT NOTE: You can also directly link the library to your own application and render glyphs directly into your own bitmaps with very few efforts. -------------------------------------------------------------------- 6. What is FreeType, and what is it not? FreeType is a rather low-level font engine. It has been designed primarly to be the basis of several font servers, for very different systems which all have their own metrics and graphics models. This means that it focuses on the following points: - opening and loading font files in memory. - giving access to most important font properties and TrueType tables. - providing a simple way to translate system-specific character codes into glyph indexes, according to the TrueType "cmap" specification. - loading and rendering _individual_ glyphs, as nicely as possible (either in outlines, bitmaps or pixmaps), and performing excellent hinting. It isn't a high-level text rendering library, and many tasks will have to be performed by higher level layers like: - glyph caching (outlines and/or maps) - text rendering - justification, kerning - font mapping - rotated/slanted text However, its API provides many functions that ease these operations considerably: - Glyph outlines can be copied and transformed easily with the API, then rendered to bitmaps or pixmaps with FreeType's scan-line converter, which is very fast. - The glyph loader places the outlines in order to ease the process of text rendering. See the documentation file named "glyphs" or 'ftstring's source for more details. - The engine gives you access to several TrueType tables that can be processed by your application to provide more powerful rendering (i.e. kerning). - It is possible, and rather simple, to write separately compilable extensions to the engine to access other TrueType tables that are not supported by the engine in this release. This can be handy if one wants to access data in TrueType GX or OpenType fonts (as these formats comply to the TrueType "sfnt" file storage format, they can be opened by the FreeType engine as a normal TrueType file). -------------------------------------------------------------------- 7. Can FreeType be ported to other platforms? FreeType is written in pure ANSI C and should compile well on all 16, 32 and 64 bits processors. Note, however, that the 16-bit port requires a large memory model, as some tables found in TrueType programs could exceed 64kByte (this is really true for CJK and Unicode fonts. Nearly all others should work fine with it). It doesn't support some very exotic platforms though, like a 32-bits only processor (where the only word size is 32-bits, even for chars and shorts). However, nothing prevents you to test it by yourself... The memory management and file access routines have been gathered in two components, namely "ttmemory" and "ttfile", which can be specialized for a specific system. Their standard version, found in the "lib" directory, uses simply the ANSI libc. However, examples are given of alternative file components for OS/2 and Unix in: lib/arch/os2/ttfile.c (accessing the low-level OS/2 file API directly) lib/arch/unix/ttmmap.c (using memory-mapped files for improved access) You would certainly need to rewrite these components if you intend to use FreeType in an embedded system. -------------------------------------------------------------------- 8. My TrueType font only works on a Mac/in Windows. Will I be able to use it with FreeType? Short Answer: YES, but be cautious! If you've read section 9 or 25, you know that a font file might have different charMaps entries, used to translate character codes to glyph indexes. The problem of most "system-specific" TrueType fonts (sigh) is that they only contain one single mapping, like Apple Roman, or Windows Glyph List, making it usable only on the platform it was "designed" for. The test program "ftdump" can be used to display the character encodings supported in a font file. Most fonts come with Apple Roman and Windows Unicode. FreeType can use every charmap found in a font file, so it's up to your application to choose the one that fits its task the best. If you use a font which only provides an Apple Roman charcode, you'll probably have a hard time rendering Unicode strings without an additional translation. Note that the tool 'ttf_edit' can actually add missing cmaps to a TrueType font file. More info on this can be found at: http://idt.net/~truetex -------------------------------------------------------------------- 9. What are the most common character mappings? If you don't want to read the TrueType specification, here is some information about the most used char maps. Each map is designed by a "platform ID", followed by a platform-specific "encoding ID": Examples: 0, 0 : Apple Unicode 1, 0 : Apple Roman 3, 0 : Windows Symbol 3, 1 : Windows Unicode Windows and Apple Unicode charmaps differ only in internal storage layout. Both can be used transparently with FreeType. Many fonts come also with both Apple Roman and Windows Unicode. -------------------------------------------------------------------- 10. How do I render text with FreeType? This is explained with great detail in the documentation file called "glyphs", available in both text and HTML (including schematics). Text rendering isn't difficult. One can also look at the code for "ftstring" to see how it is done. -------------------------------------------------------------------- 11. How do I render rotated/slanted text with FreeType? It is possible to transform the outlines returned by the glyph loader, hence producing rotated or slanted text. Please read the "glyphs" documentation file, which explains this in great detail, as well as some other important things. -------------------------------------------------------------------- 12. How do I compute a glyph bitmap's dimensions? You should grid-fit its bounding box, then compute its width and height. This is explained in the "bitmaps.txt" documentation file. -------------------------------------------------------------------- 13. Why is text rendering so slow? Does FreeType cache glyphs? The FreeType engine doesn't cache anything, be it outlines or bitmaps. Hence, a program that renders text by calling the glyph loader on each letter is slow. Because caching cannot be performed in both an _easy_ and _portable_ way it is left to the application. Moreover, some graphics systems already provide some sort of caching, and it's better to take advantage of it rather than re-implementing it. The hows and when of caching are explained in the "glyphs" documentation file. The "bitmaps" doc file is also a good source of information if you intend to render individual glyph bitmaps. -------------------------------------------------------------------- 14. Do you always render the same glyphs as Windows or the Mac? Short answer: No for rare cases. There are a lot of technical details, too numerous and lengthy to be put here, that prevents the FreeType library from matching 100% the glyphs produced by the Windows or Macintosh rasterizers. This engine is a clean-room implementation, and most of the reasons why its development took so much time is the largely deficient TrueType specification published by Apple and Microsoft. A number of key technical aspects are missing, and we found many "undocumented" features in the TrueType bytecode, after several months of testing and trying. We are now very satisfied with the current quality, though still try to improve it. The glyph metrics (bearings and advances) also match significantly those computed by Windows, or found in the TrueType pre-calc tables. As hinting glyphs also makes use of several rounding operations, we'll be unable to provide a perfect clone unless we implement the exact same computations _and_ rounding errors -- this is highly unlikely... -------------------------------------------------------------------- 15. The program "ftlint" reports errors with one of my fonts, though it works perfectly under Windows. What does this mean? Associated to each glyph is a small "program", written in a specific bytecode, which is in charge of hinting the glyph's outline to make it perfect on screen as on paper. Some of these programs can be broken (e.g. access invalid areas of memory, perform a divide by zero, etc.), and these are the errors that are reported by "ftlint". They can also mean a bug in the TrueType bytecode interpreter (or more likely an "undocumented" feature we haven't discovered yet), but should now be extremely rare. Surprisingly, even largely distributed fonts can contain broken glyph programs. For example: - antqua.ttf, glyph 163: (MS Office 4.2) The program tries to access point number 0x127, which is too much. - timesbs, arialbs, courbs: (MS Office International) The back-slanted versions of the MS core fonts produce stack overflows in many glyphs, and other oddities. It seems their "maximum profile" table is invalid. - a ton of "free" fonts, apparently designed with mediocre tools. It seems the Windows TrueType engine doesn't check its arguments often, and let all overflows run, possibly writing to critical portions of memory. Please, don't ask us what this could do to NT 4 :-) The FreeType engine performs checks on every opcode. We cannot guarantee that it's bullet proof, of course, but it seems to work well and catch font bugs accordingly. We also have artificially "enlarged" some allocated tables to make the engine work with the back-slanted fonts without compromising security, but it's clearly a hack we would have preferred to avoid! -------------------------------------------------------------------- 16. What does the "fttimer" test program benchmarks? This test program is only dedicated to profiling FreeType's scan-line converter, the component, also called "rasterizer", in charge of converting a vectorial outline into a bitmap, or a pixmap. It simply loads all glyphs of a font file (by slices of 512 at once), then converts them. Only the conversion is actually benchmarked. The glyphs are rendered at size 400pt at a resolution of 96dpi (this is about 500 pixels high!). As you'll see by running 'fttimer', the rasterizer is very fast. -------------------------------------------------------------------- 17. Is it possible to perform styling (like oblique, italic, bold, underline, etc.) with FreeType? Actually, these refer to very different things: - Italic and Bold styles usually mean many variations from the 'Regular' font. This is why you normally need a proper font file for each of these. For example, the MS core font Times comes in the following TrueType files: TIMES.TTF Times New Roman Regular TIMESI.TTF Times New Roman Italic TIMESB.TTF Times New Roman Bold TIMESBI.TTF Times New Roman Bold Italic (sometimes named TIMESZ.TTF) With FreeType, you simply need the required font file to use it. - Oblique style refers to a transformation that is applied to a regular font in order to make it 'slanted', likes italics do. However, an italic font very frequently contains small but important variations that cannot be produced by this method and make the font more appealing. Slanting can easily be done with a transformation under FreeType, with the exact same process as rendering rotated text. Please read the "glyphs" documentation file where it is explained in details. Usually, Windows or the Macintosh produce oblique versions of a regular font when the corresponding italic TrueType file isn't available. They also stretch horizontally regular fonts when the bold one isn't available. All of this can be done with trivial transformations. - Underlining and stroking, are not really part of the glyphs. They're simply lines that are printed on the glyph after it has been rendered. Each TrueType file provides, in its OS/2 table, which is accessible through the face object properties in FreeType, several values that define the position and width of those lines, in notional font units. If you want to use them, you'll have to scale these values to your current instance/point size, then draw the lines yourself. -------------------------------------------------------------------- 18. When does glyph hinting takes place? Is it when the glyph is loaded, or when it is converted to a bitmap/pixmap? The glyph loader returns fitted outlines by default (it can be asked to return a non-fitted one, or simply the original outline in notional coordinates too). This is important to have a glyph's correct metrics, even if it is not to be rendered immediately, like when caching outlines for rotated text. -------------------------------------------------------------------- 19. Which is the best, caching outlines or bitmaps? It depends on your application, and what it does with text. Usually, if all you need is render some simple text at specific point sizes, then simply cache the bitmaps or pixmaps. However, if you want to do more advanced things, like rotated text, which require sub-pixel placement to look good, you should then only cache the outlines, and transform/place them as needed before sending them to the scan-line converter. It's always possible to produce a bitmap from an outline, and the scan-converter is very fast. It's up to you then... -------------------------------------------------------------------- 20. Can I open OpenType and/or TrueType GX fonts with FreeType? TrueType GX fonts are normal TrueType fonts with enhanced tables and capabilities. They can always be opened by a normal TrueType engine (like Windows, the Mac or FreeType), but their improved features won't be available. On the contrary, OpenType fonts may vary. While some may contain legal TrueType glyphs, an "otf" file may only contain glyphs encoded in the Type 2 format. You won't be able to produce any glyphs from such a font file without a dedicated font engine (like the ones promised in NT 5 and Java 2D). FreeType is a TrueType glyph engine, and doesn't support Type 2 fonts. Supporting them would require a very different philosophy and a different core engine (even though they could share an API). Note that you can write extensions to the engine to access supplemental tables defined in these formats (see next question). -------------------------------------------------------------------- 21. How can I access additional TrueType tables that FreeType doesn't support? You have the ability to write an "engine extension". This is a separately compilable component which can enhance the base library's functionalities, without recompiling it. Some example extensions are provided in the "lib/extend" directory. You'll need of course to know the TrueType specification precisely, as well as some of the conventions used to access tables and manage memory. Read the documentation files for more details, or contact the developers at: devel@freetype.org -------------------------------------------------------------------- 22. When will I be able to use FreeType to display TrueType fonts in X11, Wine or OS/2, or even other systems? Actually, an OS/2 replacement for TRUETYPE.DLL based on FreeType has been released on its second beta concurrently to this package. Thanks go to Michal Mecasek (mike@mendelu.cz) for his excellent work! There is also an X11 beta font server, called xfstt, which seems to work relatively well. All information about these servers is available at the FreeType homepage (www.freetype.org). Note that you can also use the xfstt engine for X11 (available at SunSite). It isn't based on FreeType, but later versions seem to work rather well too. Don't hesitate to contact us if you plan to use or port the engine to exotic platforms, we're always interested in helping out. -------------------------------------------------------------------- 23. What does the "free" in FreeType really means? The previous releases of FreeType (alphas and beta) were placed under the LGPL. FreeType 1.0, and later releases, are placed in an alternate license, inspired from the BSD, Artistic and IJG's (Independent JPEG Group) ones. In short: - You're encouraged to use and distribute this program in all kinds of products, including commercial ones. - You don't have to pay us anything for it (royalty-free). - You may not pretend you wrote it, or part of it that you may use in one of your product, and state clearly that you use the FreeType code if you distribute products based on it, or parts of it (credits clause). - This source code is provided AS IS, with no warranty whatsoever, and we cannot promise support for it. The exact and legal terms are in the file "license.txt". Enjoy ;-) -------------------------------------------------------------------- 24. Does FreeType support threads? Is it re-entrant? Short answer: IN BETA NOW We have changed some code for FreeType 1.1 in order to support multi-threaded environments. However, these have not been tested yet. Apparently, the thread-safe and reentrant builds now work well perfectly once compiled; however, no serious concurrency testing has been performed (of course, a serious lock analysis was done in order to modify the source). Right now, the mutex management functions are all gathered in the component "ttmutex", which shall be specialized for your own system when a thread build will be necessary. -------------------------------------------------------------------- 25. Does FreeType support "foreign languages"? Short Answer: YES, it does! From a TrueType font file point of view, there are several parts to the file, one of them being the 'glyphs', i.e. picture representation of the symbols. Another part is the mapping table, also called "charMap". For example, glyph #1 could be letter "A", and glyph #2 could be letter "Z". Glyphs can be stored in any order in a font file. The mapping tables contains at least one char-map entry. For example, you could have an ASCII-map that maps 0x41 to glyph #1, and 0x5A to glyph #2, etc. FreeType provides a "charMap" object class to access and use this information easily. There are several character encodings recognized and defined by the TrueType specification, like Latin-1, Unicode, Apple Scripts, WGL, etc., but a font file might only contain one or two of them. When using a more 'exotic' character encoding, like EBCDIC (this is IBM mainframe stuff!), you would need to translate it to one of the available formats (or to add a charmap table to the font). Cf. section 8. -------------------------------------------------------------------- 26. I'm using fractional char sizes, but the glyphs stay at the same integer size. Why? Because hinting only works well with integer pixel sizes. There is a flag that can be set in a TrueType font file to force integer pixel size scaling, even if you ask for fractional sizes with an API like TT_Set_Instance_CharSize(). Needless to say, nearly all fonts have the flag set. So this is normal. Also, notice that when giving a charsize in fractional points, this will be converted to integer pixels with the formula: pixel_size = char_size * y_resolution / 72 For example, using a resolution of 96 dpi, we would have: 9.5 pts => 12.666 pixels => 13 pixels 10.0 pts => 13.333 pixels => 13 pixels, i.e. same size 10.5 pts => 14 pixels => 14 pixels 11.0 pts => 14.666 pixels => 15 pixels 11.5 pts => 15.333 pixels => 15 pixels, i.e. same size If you want to control the exact size in pixels of your glyphs, simply use a resolution of 72 dpi, where char_size = pixel_size. -------------------------------------------------------------------- 27. Hinting doesn't work at very small sizes. Why? This is normal. There are very good technical reasons why hinting doesn't work well at sizes under 7 ppem,. usually meaning the appearance of ugly spikes and glyph distorsions. This is why the engine disables hinting by default at so low sizes. --- end of FAQ ---