3 --------------------------------------------------------------------
9 1. How do I compile the test programs?
11 2. What are the test programs?
15 4. How do I only compile the FreeType library?
17 5. The library compiles fine on my system, unfortunately it seems
18 the test programs won't. What can I do?
20 6. What is FreeType, and what is it not?
22 7. Can FreeType be ported to other platforms?
24 8. My TrueType font only works on a Mac/in Windows. Will I be able
25 to use it with FreeType?
27 9. What are the most common character mappings?
29 10. How do I render text with FreeType?
31 11. How do I render rotated/slanted text with FreeType?
33 12. How do I compute a glyph bitmap's dimensions?
35 13. Why is text rendering so slow? Does FreeType cache glyphs?
37 14. Do you always render the same glyphs as Windows or the Mac?
39 15. The program `ftlint' reports errors with one of my fonts, though
40 it works perfectly under Windows. What does this mean?
42 16. What does the `fttimer' test program benchmarks?
44 17. Is it possible to perform styling (like oblique, italic, bold,
45 underline, etc.) with FreeType?
47 18. When does glyph hinting takes place? Is it when the glyph is
48 loaded, or when it is converted to a bitmap/pixmap?
50 19. Which is the best, caching outlines or bitmaps?
52 20. Can I open OpenType and/or TrueType GX fonts with FreeType?
54 21. How can I access additional TrueType tables that FreeType
57 22. When will I be able to use FreeType to display TrueType fonts in
58 X11, Wine, or OS/2, or even other systems?
60 23. What does the `free' in FreeType really means?
62 24. Does FreeType support threads? Is it re-entrant?
64 25. Does FreeType support `foreign languages'?
66 26. I'm using fractional char sizes, but the glyphs stay at the same
69 27. Hinting doesn't work at very small sizes. Why?
71 --------------------------------------------------------------------
73 1. How do I compile the test programs?
75 Detailed compilation steps are given in the `freetype/HOWTO.txt'
76 file, as well as system and compiler specific hints in the
77 `freetype/howto' directory. What follows is a _very_ simple
82 Do the following on the prompt while in the base directory of
89 This will build and install the library (shared, if supported)
90 together with the test programs. Say `./configure --help' to
91 see the available configuring options.
93 This should work with any ANSI C compiler.
97 Go to the `test' directory. Look at one of the makefiles
98 located in the `arch/<system>' directory, and use the
99 appropriate makefile from there.
103 make -f arch/msdos/makefile.gcc (DJGPP or emx)
104 wmake -f=arch\msdos\makefile.wat (Watcom DOS)
105 nmake -f arch\os2\makefile.icc (Visual Age OS/2)
106 make -f arch/amigaos/makefile.gcc (GCC Amiga)
108 This will compile both the library and the test programs.
111 --------------------------------------------------------------------
113 2. What are the test programs?
115 The test programs are simple sources that `show off' the FreeType
116 library. They are located in the `test' directory. They make use
117 of a small graphics sub-system which is able to display bitmaps
118 and pixmaps on a variety of platforms through the use of
119 system-specific `drivers'.
121 The test programs are:
123 ftdump: A simple TTF information dumper. Also prints the
124 memory used by each opened font file with FreeType.
125 Doesn't use the graphics sub-system.
127 ftlint: A simple TrueType bytecode verifier. It simply hints
128 all glyphs of one or more font files at a given size
129 and reports errors. Doesn't use the graphics
132 ftview: A simple font viewer. Displays all glyphs in a font
135 ftstring: Renders a simple string to the screen. Demonstrates
136 how to produce text with FreeType.
138 fttimer: A simple benchmark, used to profile the scan-line
139 conversion routines (and only them). Supports also
142 ftstrpnm: A version of `ftstring' which saves a bit/pixmap to a
143 PNM file rather than to the screen. No graphics
146 ftzoom: A simple glyph viewer, useful to view, zoom and rotate
147 individual glyphs in a font file.
149 fterror: This program demonstrates how to use the ftxerr18
150 extension. Note that internationalized strings will
151 be available on some platforms only (e.g. Linux).
153 ftmetric: A simple metric/glyph dumper. No graphics sub-system
156 ftsbit: Displays data about embedded bitmaps in a TrueType
159 ftstrtto: Renders a string to screen, using TrueType Open
162 NOTE: The file `ftdebug.c' isn't part of the test suite. It is
163 used only by the developers team to debug the engine at a
164 higher level. It won't work with a standard library
168 The tiny graphics subsystem is defined in the following files:
170 gmain.h/gmain.c: The subsystem's main body/interface.
172 gevents.h: The definition of events defined for the
175 gdriver.h: The generic interface of all system-specific
178 System-specific drivers are in the `test/arch/<system>'
181 test/arch/msdos/gfs_dos.c Full-Screen DOS driver
182 test/arch/os2/gpm_os2.c PM (Windowed) OS/2 driver
183 test/arch/unix/gwin_x11.c X11 Windowed driver
188 --------------------------------------------------------------------
190 3. How do I use them?
192 Please read the file freetype/README for a full description.
195 --------------------------------------------------------------------
197 4. How do I only compile the FreeType library?
201 Do a `configure' run as described in section 1. Then change to
202 the lib subdirectory and say `make' and `make install'.
206 Go to the `lib' directory. Look at one of the makefiles located
207 in the `arch/<system>' directory, and use it from `lib'.
211 make -f arch/msdos/makefile.gcc (DJGPP or emx)
212 wmake -f=arch\msdos\makefile.wat (Watcom DOS)
213 nmake -f arch\os2\makefile.icc (Visual Age OS/2)
214 make -f arch/amigaos/makefile.gcc (GCC Amiga)
216 The library is pure ANSI C and doesn't depend on any
217 system-specific package. You need not gcc to compile it.
220 --------------------------------------------------------------------
222 5. The library compiles fine on my system, unfortunately it seems
223 the test programs won't. What can I do?
225 As said before, the test programs rely on a small graphics
226 sub-system to display the bitmaps and pixmaps produced by the
227 library. The following systems are currently supported:
230 Amiga Full-Screen Note that the windowed graphics
231 Amiga Windowed driver are very 'basic', they do
232 OS/2 Full-Screen not provide menus, dialog boxes,
233 OS/2 Windowed etc. Rather, they provide one
234 X11 Windowed windowed bitmap/pixmap and translate
235 Win32 Windowed events to the ones defined in
238 If you want to add support to your system, you should write a new
239 graphics driver. To do that, read the file `test/gdriver.h' which
240 contains the driver generic interface, then browse the drivers
241 that are already provided.
243 The graphics drivers are located in the `test/arch/<system>'
244 directories. They're not part of the library proper.
248 You can also directly link the library to your own application
249 and render glyphs directly into your own bitmaps with very few
253 --------------------------------------------------------------------
255 6. What is FreeType, and what is it not?
257 FreeType is a rather low-level font engine. It has been designed
258 primarily to be the basis of several font servers, for very
259 different systems which all have their own metrics and graphics
260 models. This means that it focuses on the following points:
262 - Opening and loading font files in memory.
264 - Giving access to most important font properties and TrueType
267 - Providing a simple way to translate system-specific character
268 codes into glyph indexes, according to the TrueType `cmap'
271 - Loading and rendering _individual_ glyphs as nicely as possible
272 (either in outlines, bitmaps, or pixmaps), and performing
275 It isn't a high-level text rendering library, and many tasks will
276 have to be performed by higher level layers like:
278 - glyph caching (outlines and/or maps)
280 - justification, kerning
282 - rotated/slanted text
284 However, its API provides many functions that ease these
285 operations considerably:
287 - Glyph outlines can be copied and transformed easily with the API
288 functions, then rendered to bitmaps or pixmaps with FreeType's
289 scan-line converter, which is very fast.
291 - The glyph loader places the outlines in order to ease the
292 process of text rendering. See the documentation file named
293 `glyphs.htm' (resp. `glyphs.txt') or `ftstring's source for more
296 - The engine gives you access to several TrueType tables that can
297 be processed by your application to provide more powerful
298 rendering (e.g. kerning).
300 - It is possible, and rather simple, to write separately
301 compilable extensions to the engine to access other TrueType
302 tables that are not supported by the engine in this release.
303 This can be handy if one wants to access data in TrueType GX or
304 OpenType fonts (as these formats comply to the TrueType `sfnt'
305 file storage format, they can be opened by the FreeType engine
306 as a normal TrueType file).
309 --------------------------------------------------------------------
311 7. Can FreeType be ported to other platforms?
313 FreeType is written in pure ANSI C and should compile well on all
314 16, 32, and 64 bits processors. Note, however, that the 16-bit
315 port requires a large memory model, as some tables found in
316 TrueType programs could exceed 64kByte (this is really true for
317 CJK and Unicode fonts. Nearly all others should work fine with
320 It doesn't support some very exotic platforms though, like a
321 32-bit only processor (where the only word size is 32-bit, even
322 for chars and shorts). However, nothing prevents you to test it
325 The memory management and file access routines have been gathered
326 in two components, namely `ttmemory' and `ttfile', which can be
327 specialized for a specific system. Their standard version, found
328 in the `lib' directory, uses simply the ANSI libc. However,
329 examples are given of alternative file components for OS/2 and
332 lib/arch/os2/ttfile.c
333 (accessing the low-level OS/2 file API directly)
335 lib/arch/unix/ttmmap.c
336 (using memory-mapped files for improved access)
338 You would certainly need to rewrite these components if you intend
339 to use FreeType in an embedded system.
342 --------------------------------------------------------------------
344 8. My TrueType font only works on a Mac/in Windows. Will I be able
345 to use it with FreeType?
347 Short Answer: YES, but be cautious!
349 If you have read section 9 or 25, you know that a font file might
350 have different charMaps entries, used to translate character codes
351 to glyph indexes. The problem of most `system-specific' TrueType
352 fonts (sigh) is that they only contain one single mapping, like
353 Apple Roman, or Windows Glyph List, making it usable only on the
354 platform it was `designed' for.
356 The test program `ftdump' can be used to display the character
357 encodings supported in a font file. Most fonts come with Apple
358 Roman and Windows Unicode.
360 FreeType can use every charmap found in a font file, so it is up
361 to your application to choose the one that fits its task best. If
362 you use a font which only provides an Apple Roman charcode, you'll
363 probably have a hard time rendering Unicode strings without an
364 additional translation.
366 Note that the tool `ttf_edit' can actually add missing cmaps to a
367 TrueType font file. More info on this can be found at:
369 http://www.truetex.com
371 Another possibility is to use Just van Rossum's TTX compiler
372 (still beta) which can convert a TrueType font into an XML
373 description and vice versa; it can be found at
375 http://www.letterror.com/ttx/
377 --------------------------------------------------------------------
379 9. What are the most common character mappings?
381 If you don't want to read the TrueType specification, here is some
382 information about the most used char maps. Each map is designed
383 by a `platform ID', followed by a platform-specific `encoding ID':
389 3, 0 : Windows Symbol
390 3, 1 : Windows Unicode
392 Windows and Apple Unicode charmaps differ only in internal storage
393 layout. Both can be used transparently with FreeType.
395 Many fonts come also with both Apple Roman and Windows Unicode.
398 --------------------------------------------------------------------
400 10. How do I render text with FreeType?
402 This is explained with great detail in the glyphs documentation
403 file available in both text (glyphs.txt) and HTML (glyphs.htm,
404 including schematics).
406 Text rendering isn't difficult. One can also look at the code for
407 `ftstring' or `ftstrtto' to see how it is done.
410 --------------------------------------------------------------------
412 11. How do I render rotated/slanted text with FreeType?
414 It is possible to transform the outlines returned by the glyph
415 loader, hence producing rotated or slanted text. Please read the
416 `glyphs' documentation file, which explains this in great detail,
417 as well as some other important things.
420 --------------------------------------------------------------------
422 12. How do I compute a glyph bitmap's dimensions?
424 You should grid-fit its bounding box, then compute its width and
425 height. This is explained in the `bitmaps.txt' documentation
429 --------------------------------------------------------------------
431 13. Why is text rendering so slow?
432 Does FreeType cache glyphs?
434 The FreeType engine doesn't cache anything, be it outlines or
435 bitmaps. Hence, a program that renders text by calling the glyph
436 loader on each letter is slow.
438 Because caching cannot be performed in both an _easy_ and
439 _portable_ way it is left to the application. Moreover, some
440 graphics systems already provide some sort of caching, and it is
441 better to take advantage of it rather than re-implementing it.
443 The `how's and `when's of caching are explained in the `glyphs'
444 documentation file. The `bitmaps' documentation file is also a
445 good source of information if you intend to render individual
449 --------------------------------------------------------------------
451 14. Do you always render the same glyphs as Windows or the Mac?
453 Short answer: No for rare cases.
455 There are a lot of technical details, too numerous and lengthy to
456 be put here, that prevents the FreeType library from matching 100%
457 the glyphs produced by the Windows or Macintosh rasterizers.
459 This engine is a clean-room implementation, and most of the
460 reasons why its development took so much time is the largely
461 deficient TrueType specification published by Apple and Microsoft.
462 A number of key technical aspects are missing, and we found many
463 `undocumented' features in the TrueType bytecode, after several
464 months of testing and trying. We are now very satisfied with the
465 current quality, though still try to improve it.
467 The glyph metrics (bearings and advances) also match significantly
468 those computed by Windows, or found in the TrueType pre-calc
471 As hinting glyphs also makes use of several rounding operations,
472 we will be unable to provide a perfect clone unless we implement
473 the exact same computations _and_ rounding errors -- this is
477 --------------------------------------------------------------------
479 15. The program `ftlint' reports errors with one of my fonts, though
480 it works perfectly under Windows. What does this mean?
482 Associated to each glyph is a small `program', written in a
483 specific bytecode language, which is in charge of hinting the
484 glyph's outline to make it perfect on screen as on paper. Some of
485 these programs can be broken (e.g., accessing invalid areas of
486 memory, performing a divide by zero, etc.), and these are the
487 errors that are reported by `ftlint'.
489 They can also mean a bug in the TrueType bytecode interpreter (or
490 more likely an `undocumented' feature we haven't discovered yet),
491 but should now be extremely rare.
493 Surprisingly, even largely distributed fonts can contain broken
494 glyph programs. For example:
496 - antqua.ttf, glyph 163 (MS Office 4.2):
498 The program tries to access point number 0x127, which is too
501 - timesbs, arialbs, courbs (MS Office International):
503 The back-slanted versions of the MS core fonts produce stack
504 overflows in many glyphs, and other oddities. It seems their
505 `maximum profile' table is invalid.
507 - a ton of `free' fonts, apparently designed with mediocre tools.
509 It seems the Windows TrueType engine doesn't check its arguments
510 often, and let all overflows run, possibly writing to critical
511 portions of memory. Please, don't ask us what this could do to
514 The FreeType engine performs checks on every opcode. We cannot
515 guarantee that it is bullet proof, of course, but it seems to work
516 well and catch font bugs accordingly.
518 We also have artificially `enlarged' some allocated tables to make
519 the engine work with the back-slanted fonts without compromising
520 security, but it's clearly a hack we would have preferred to
524 --------------------------------------------------------------------
526 16. What does the `fttimer' test program benchmarks?
528 This test program is only dedicated to profiling FreeType's
529 scan-line converter, a component also called `rasterizer', which
530 is in charge of converting a vectorial outline into a bitmap, or a
533 It simply loads all glyphs of a font file (by slices of 512 at
534 once), then converts them. Only the conversion is actually
537 The glyphs are rendered at size 400pt at a resolution of 96dpi
538 (this is about 500 pixels high!). As you'll see by running
539 `fttimer', the rasterizer is very fast.
542 --------------------------------------------------------------------
544 17. Is it possible to perform styling (like oblique, italic, bold,
545 underline, etc.) with FreeType?
547 Actually, these refer to very different things:
549 - Italic and Bold styles usually mean many variations from the
550 `Regular' font. This is why you normally need a proper font
551 file for each of these. For example, the MS core font Times
552 comes in the following TrueType files:
554 TIMES.TTF Times New Roman Regular
555 TIMESI.TTF Times New Roman Italic
556 TIMESB.TTF Times New Roman Bold
557 TIMESBI.TTF Times New Roman Bold Italic
558 (sometimes named TIMESZ.TTF)
560 With FreeType, you simply need the required font file to use it.
562 - Oblique style refers to a transformation that is applied to a
563 regular font in order to make it `slanted', likes italics do.
564 However, an italic font very frequently contains small but
565 important variations that cannot be produced by this method and
566 make the font more appealing.
568 Slanting can easily be done with a transformation under
569 FreeType, with the exact same process as rendering rotated text.
570 Please read the `glyphs' documentation file where it is
571 explained in details.
573 Usually, Windows or the Macintosh produce oblique versions of a
574 regular font if the corresponding italic TrueType file isn't
575 available. They also stretch regular fonts horizontally if the
576 bold one isn't available. All of this can be done with trivial
579 - Underlining and stroking are not really part of the glyphs.
580 They're simply lines that are printed on the glyph after it has
581 been rendered. Each TrueType file provides, in its OS/2 table
582 (which is accessible through the face object properties in
583 FreeType), several values that define the position and width of
584 those lines, in notional font units.
586 If you want to use them, you'll have to scale these values to
587 your current instance/point size, then draw the lines yourself.
590 --------------------------------------------------------------------
592 18. When does glyph hinting takes place? Is it when the glyph is
593 loaded, or when it is converted to a bitmap/pixmap?
595 The glyph loader returns fitted outlines by default (it can be
596 asked to return a non-fitted one, or simply the original outline
597 in notional coordinates too).
599 This is important to have a glyph's correct metrics, even if it is
600 not to be rendered immediately, like when caching outlines for
604 --------------------------------------------------------------------
606 19. Which is the best, caching outlines or bitmaps?
608 It depends on your application, and what it does with text.
610 Usually, if all you need is render some simple text at specific
611 point sizes, then simply cache the bitmaps or pixmaps.
613 However, if you want to do more advanced things, like rotated
614 text, which require sub-pixel placement to look good, you should
615 then only cache the outlines, and transform/place them as needed
616 before sending them to the scan-line converter.
618 It's always possible to produce a bitmap from an outline, and the
619 scan-converter is very fast. It's up to you then...
622 --------------------------------------------------------------------
624 20. Can I open OpenType and/or TrueType GX fonts with FreeType?
626 TrueType GX fonts are normal TrueType fonts with enhanced tables
627 and capabilities. They can always be opened by a normal TrueType
628 engine (like Windows, the Mac, or FreeType), but their improved
629 features won't be available.
631 On the contrary, OpenType fonts may vary. While some may contain
632 legal TrueType glyphs, an `otf' file may only contain glyphs
633 encoded in the Type 2 format. You won't be able to produce any
634 glyphs from such a font file without a dedicated font engine (like
635 the ones promised in NT 5 and Java 2D).
637 FreeType is a TrueType glyph engine and doesn't support Type 2
638 fonts. Supporting them would require a very different philosophy
639 and a different core engine (even though they could share an API).
641 Note that you can write extensions to the engine to access
642 supplemental tables defined in these formats (see next question).
644 Note that FreeType version 2 (which is in alpha stage currently)
645 already includes a PostScript Type 1 interpreter...
648 --------------------------------------------------------------------
650 21. How can I access additional TrueType tables that FreeType
653 You can write an `engine extension'. This is a separately
654 compilable component which can enhance the base library's
655 functionalities, without recompiling it. Some important
656 extensions are provided in the `lib/extend' directory.
658 You'll need of course to know the TrueType specification
659 precisely, as well as some of the conventions used to access
660 tables and to manage memory. Read the documentation files for
661 more details, or contact the developers at:
666 --------------------------------------------------------------------
668 22. When will I be able to use FreeType to display TrueType fonts in
669 X11, Wine or OS/2, or even other systems?
671 Actually, an OS/2 replacement for TRUETYPE.DLL based on FreeType
672 is part of this package (to be found in contrib/ftos2). Thanks go
673 to Michal Mecasek (mike@mendelu.cz) for his excellent work!
675 At least three X11 TrueType font servers are available; two of
676 them (xfsft and xtt) are based on FreeType, whereas the third
677 (xfstt) uses a separately developed TrueType engine.
679 More information about these servers is available at the FreeType
680 homepage (http://www.freetype.org).
682 Don't hesitate to contact us if you plan to use or port the engine
683 to exotic platforms, we're always interested in helping out.
686 --------------------------------------------------------------------
688 23. What does the `free' in FreeType really means?
690 The previous releases of FreeType (alphas and beta) were placed
691 under the LGPL. FreeType 1.0, and later releases, come with an an
692 alternate license, inspired from the BSD, Artistic, and IJG's
693 (Independent JPEG Group) ones. In short:
695 - You are encouraged to use and distribute this program in all
696 kinds of products, including commercial ones.
698 - You don't have to pay us anything for it (royalty-free).
700 - You may not pretend you wrote it, or part of it that you may use
701 in one of your product, and you have to state clearly that you
702 use the FreeType code if you distribute products based on it, or
703 parts of it (credits clause).
705 - This source code is provided AS IS, with no warranty whatsoever,
706 and we cannot promise support for it.
708 The exact and legal terms are in the file `license.txt'.
713 --------------------------------------------------------------------
715 24. Does FreeType support threads? Is it re-entrant?
717 Short answer: Basically yes, but not fully tested.
719 We have changed some code since FreeType 1.0 in order to support
720 multi-threaded environments. However, these have not been tested
721 yet. Apparently, the thread-safe and reentrant builds now work
722 well perfectly once compiled; however, no serious concurrency
723 testing has been performed (of course, a serious lock analysis was
724 done in order to modify the source).
726 Right now, the mutex management functions are all gathered in the
727 component `ttmutex', which has to be specialized for your own
728 system if a thread build will be necessary.
731 --------------------------------------------------------------------
733 25. Does FreeType support `foreign languages'?
735 Short Answer: YES, it does!
737 From a TrueType font file point of view, there are several parts
738 to the file, one of them being the `glyphs', i.e., picture
739 representations of the symbols.
741 Another part is the mapping table, also called `charMap'.
743 For example, glyph #1 could be letter `A', and glyph #2 could be
744 letter `Z'. Glyphs can be stored in any order in a font file.
746 The mapping tables contain at least one char-map entry. For
747 example, you could have an ASCII-map that maps character code 0x41
748 to glyph #1, and code 0x5A to glyph #2, etc. FreeType provides a
749 `charMap' object class to access and use this information easily.
751 There are several character encodings recognized and defined by
752 the TrueType specification, like Latin-1, Unicode, Apple Scripts,
753 WGL, etc., but a font file might only contain one or two of them.
755 When using a more `exotic' character encoding like EBCDIC (this is
756 IBM mainframe stuff!), you would need to translate it to one of
757 the available formats (or to add a charmap table to the font).
761 --------------------------------------------------------------------
763 26. I'm using fractional char sizes, but the glyphs stay at the same
766 Because hinting only works well with integer pixel sizes. There
767 is a flag that can be set in a TrueType font file to force integer
768 pixel size scaling, even if you ask for fractional sizes with an
769 API function like TT_Set_Instance_CharSize(). Needless to say,
770 nearly all fonts have the flag set. So this is normal.
772 Also, notice that when giving a charsize in fractional points,
773 this will be converted to integer pixels with the formula:
775 pixel_size = char_size * y_resolution / 72
777 For example, using a resolution of 96 dpi, we would have:
779 9.5 pts => 12.666 pixels => 13 pixels
780 10.0 pts => 13.333 pixels => 13 pixels, i.e. same size
781 10.5 pts => 14 pixels => 14 pixels
782 11.0 pts => 14.666 pixels => 15 pixels
783 11.5 pts => 15.333 pixels => 15 pixels, i.e. same size
785 If you want to control the exact size in pixels of your glyphs,
786 simply use a resolution of 72dpi, where char_size = pixel_size.
789 --------------------------------------------------------------------
791 27. Hinting doesn't work at very small sizes. Why?
793 This is normal. There are very good technical reasons why hinting
794 doesn't work well at sizes under 7 ppem, usually meaning the
795 appearance of ugly spikes and glyph distortions. This is why the
796 engine disables hinting by default at such low sizes.