http://www.freetype.org

#

# The FreeType 2 FAQ

Document index

- General

  - What is FreeType 2 ?
  - What can I do with FreeType 2 ?
  - What can't I do with FreeType 2 ?
  - How portable is FreeType 2 ?
  - What are the differences between FreeType 1.x and FreeType 2 ?
  - What about the TrueType patents ?
  - Is FreeType 2 backwards compatible to FreeType 1.x?
  - Can I use FreeType 2 to edit fonts or create new ones?
- Compilation & Configuration

  - How do I compile the FreeType 2 library?
  - I've tried to compile FreeType 2, but I'm having problems. What can I do ?
  - How do I configure my library build?
  - How do I select the modules I need?
  - How do I compile all FreeType 2 files in a single directory?
- The FreeType 2 autohinter

  - Under which license is the auto-hinter released?
  - How does auto-hinting work in FreeType 2?
  - Why doesn't the auto-hinter work well with CJK fonts?
- Other questions

  - How can I compute the dimensions of glyphs before rendering them ?
  - How can I determine the ascent, descent or "x-height" of glyphs before rendering them ?
  - How can I set the color of text rendered by FreeType?
  - Can I use FreeType to draw text on a pixmap with arbitrary depth?
  - I set the pixel size to 8x8, but the resulting glyphs are larger than that. Why?
  - How can I compute the bounding box of a text string without loading its glyphs?
  - Which anti-aliasing algorithm is used in the FreeType 2 renderer?
  - When will FreeType 2 support OpenType?

## General questions & answers

### I.1 What is FreeType 2 ?

It's a software library that can be used by all kinds of applications to access the content of font files. Most notably, it supports the following "features":

- It provides a uniform interface to access font files. It supports both bitmap and scalable formats, including TrueType, OpenType, Type1, CID, CFF, Windows FON/FNT, X11 PCF.

- It supports high-speed anti-aliased glyph bitmap generation with 256 levels of gray.

- It is extremely modular, each font format being supported by a specific module. A build of the library can be tailored to support only the formats you need, thus reducing code size (a minimal anti-aliasing build of FreeType can be less than 30 Kb)

### I.2 What can I do with FreeType 2 ?

FreeType 2 is already used in countless product. For example:

- in graphics subsystem and libraries to display text
- in text layout and pagination services to measure and eventually render text
- in font inspection and conversion tools

Generally speaking, the library allows you to access and manage the content of font files in a very easy way.

### I.3 What can't I do with FreeType 2 ?

FreeType 2 doesn't try to perform a number of sophisticated things, because it focuses on being an excellent font service.

This means that the following are not supported directly by the library, even though they can be more or less be implemented on top of it, or by using it:

- rendering glyphs to arbitrary surfaces
  FT2 doesn't try to be a graphics library and thus only supports two pixel formats when rendering glyphs: monochrome 1-bit bitmaps, or 8-bit gray-level pixmaps.

  If you need to draw glyphs to other kinds of surfaces (for example, a 24-bit RGB pixmap), you'll need to use your favorite graphics library to do just that.

  Note however that in the case of rendering scalable glyph outlines to anti-aliased pixmaps, an application can also provide its own rendering callback in order to draw or compose directly the anti-aliased glyph on any target surface.

- glyph caching
  Each time you request a glyph image from a font, FT2 does it by parsing the relevant portion of the font file/stream and interpreting it according to its font format. This can be very slow for certain formats, including scalable ones like TrueType or Type 1.

  Any decent text-rendering sub-system must thus be capable of caching glyph data in order to reach appropriate rendering speed

  Note that we provide a beta caching sub-system with FreeType 2 since version 2.0.1. Even though you're free to write your own to suit your needs.

- text layout
  The library doesn't support the text layout operations. Sophisticated operations like glyph substitution, positioning (kerning), justification, bi-directional ordering, etc.. are not part of a font service in itself.

### I.4 How portable is FreeType 2 ?

The FreeType 2 source code is extremely portable for the following reasons:

- Everything is written in standard ANSI C
- We're very pedantic to avoid any kinds of compiler warnings. The current source code has been compiled with many compilers without producing a single warning.
- The library doesn't use any static writable data at all, making it an ideal choice on various embedded systems (e.g. it can be run from ROM directly)

Meanwhile, we've made great efforts to ensure that the library is both efficient, compact and customizable.

### I.5 What are the differences between FreeType 1.x and FreeType 2 ?

The biggest differences are that:

- FT1 only supports the TrueType format, while FT2 does a lot more.

- The FT2 API is simpler as well as more powerful than the FT1 API,

- FT1 includes an extension to support OpenType text layout processing. This support is not part of FT2, but has been moved to a distinct project, called FreeType Layout. ( FT Layout is not currently available though..)

### I.6 Is FreeType 2 backwards compatible with FreeType 1.x?

Not directly, though we had the project to provide an optional binary compatibility layer on top of it in order to easily re-link applications with the new version. However, this idea has been dropped as it is possible to install and use the two versions independently on any system (read: no namespace conflicts).

The FreeType 2 API is a lot simpler than the one in 1.x while being much more powerful. We thus encourage you to adapt your source code to it as this should not involve much work.

### I.6 Can I use FreeType 2 to edit fonts or create new ones?

The answer is a definitive no, because the library was specifically designed to read font files with small code size and very low memory usage.

We thus do not plan to support editing or creation in the font engine in any way, as this would imply a complete rewrite. This doesn't mean that we won't introduce a font editing/creation library in the future, as this really depends on how many people are asking for it (or how much they would be willing to pay for it), as well as the time of the FreeType developers.

Do not expect anything in this direction until we officially announce something though. There are other axes of development for this project (like text-layout capabilities, glyph caching, etc.) that may be more important to us at the moment.

## Compilation & Configuration

### II.1 How do I compile the FreeType 2 library?

The library can be compiled in various ways, and a detailed documentation is available in the file `freetype2/docs/BUILD`. However, we will summarize the process to a few cases:

#### a. Using the command-line 2 build system

The engine comes with a sophisticated build system that is used to configure and compile a build of the library. You will need GNU Make installed on your platform (Note: It will not work with other Make tools).

Basically, you will need to invoke `make` a first time in the top-level FreeType 2 directory in order to set up the build. This will detect your current platform and choose a configuration sub-makefile to drive the build. A specific compiler can be selected on some platforms by providing an additional target. For example, on Win32:

- `make visualc` will select the Visual C++ compiler
- `make lcc` will select the Win32-lcc compiler

Note that on Unix, when the first time make is called, a configure script located in `freetype2/builds/unix` will be run in order to automatically detect the platform & compiler.

A summary will be displayed showing the detected platform and compiler selected. You will then be able to start the build by invoking `make` a second time. In case of problem, consult the `BUILD` document.

#### b. Direct compilation

You can also directly compile the library from the command line by using these simple rules:

- You should place the directories `freetype2/include` and `freetype2/src` in your include path in order to compile any component of the library. You can also add the system-specific build directory (i.e. `builds/system/`) in the case where an alternate implementation of some of the components is available there (e.g. the memory-mapped i/o implementation on some Unix systems).
- The components of the library are located in sub-directories of `src`, for example: `src/base`, `src/truetype`, etc.
- Each component is normally compiled through a single C file that wraps other sources in the component's directory. For example, you should build the TrueType font driver by compiling the file `src/truetype/truetype.c`. The list of C files to compile for a feature-complete build of the library is given in the `BUILD` document.

#### c. Using a graphical IDE

Well, the process is vastly similar to the one described in b., except that you need to set the include paths, source code paths, etc. in dialog boxes before running the compilation.

### II.2 How do I configure my build of the library?

Each build of the library is configured through two header files located in `include/freetype/config`:

- `ftoption.h`
  This file contains various configuration macros whose definition can be toggled on a per-build basis. Each macro is heavily commented in this file's comment, and we invite you to refer to it directly.
- `ftmodule.h`
  This file contains the list of all the modules that are initially registered (added) when the function `FT_Init_FreeType()` is called. See the next answer to know how to change it and why it may be important.

Alternatively, some specific implementations of some FreeType 2 components can be provided in a `builds/system/` directory (e.g. the Unix-specific `ftsystem.c` that uses memory-mapped file for i/o).

### II.3 How do I select the modules I need in my build?

The function `FT_Init_FreeType()` creates a new instance of the FreeType 2 library and registers a set of "default" modules before returning to the calling application. Its default implementation is in the file `src/base/ftinit.c`.

The list of default modules used by `ftinit.c` is located in the configuration file `include/freetype/config/ftmodule.h`. Normally, it is automatically generated by the build system by invoking the "`make modules`" command in the top level FreeType 2 directory (Note: this only works with GNU Make; you can edit the file by hand otherwise). It does so by parsing all sub-directories of `src` that contain a file named `module.mk`.

Note that a specific port or project is free to provide its own implementation of `ftinit.c` in order to ensure a different initialization sequence. For example, one could do something like:

- Compile each module as a shared library (DLL or `.so`) with a common "entry point" to retrieve a pointer to its module class (there is already some code that allows this when compiling each module).
- Place these modules in a directory like `/usr/lib/freetype2/modules/`.
- Provide an implementation of `ftinit.c` that would scan the directory for valid modules.

This example only emphasizes the flexibility that is left to developers when building the library.

### II.4 How do I compile all FreeType 2 files in a single directory?

Some projects may need, for the sake of simplicity or ease of building, to compile the FreeType 2 library with all source files copied to a single directory. This is possible.

To do so, you have to copy all source files located under `src` to your own directory (you must retain the include files in a distinct hierarchy though), then compile each of the FreeType 2 component with the macro `FT_FLAT_COMPILE`. This will change the way `#include` works during the build.

## The FreeType 2 auto-hinter

### III.1 Under which license is the FreeType 2 auto-hinter released?

The auto-hinter was initially designed and implemented under contract for Catharon Productions, Inc which gladly accepted to released it under an open-source license compatible with the FreeType one.

This license can be found in `src/autohint/CatharonLicense.txt` and requires that you cite Catharon Productions in your documentation (just like you do with FreeType) when using the auto-hinting module.

Other than that, you still have the same freedom than with the good old FreeType license. Enjoy!

### III.2 How does the auto-hinter work?

Well, a complete description would be difficult. Have a look at the dedicated auto-hinter pages on the FreeType site, as they describe most of its details with graphics and explanations. You could also look at the source code if you want to :-)

To give a few details, the auto-hinter is used to perform grid-fitting on scalable font formats that use Bézier outlines as their primary glyph image format (this means nearly all scalable font formats today). If a given font driver doesn't provide its own hinter, the auto-hinter is used by default. If a format-specific hinter is provided, it is still possible to use the auto-hinter using the `FT_LOAD_FORCE_AUTOHINT` bit flag when calling `FT_Load_Glyph()`.

The auto-hinter currently doesn't use external hints to do its job, as it automatically computes global metrics (when it "opens" a font for the first time) and glyph "hints" from their outline. Note that we plan the ability to specify external hints, given that it is based on a constraint system. That could be used to support native hints in Type 1/Type 2 fonts, for example.

### III.3 Why does the auto-hinter doesn't work correctly with CJK fonts?

The auto-hinter was first designed to manage and hint Latin-based fonts, as they consist of most of the fonts available today. It doesn't hint Asian fonts, as well as a few other complex scripts, because we didn't put enough research on the topic yet. Hinting CJK isn't really more difficult than Latin, just different, with a set of different constraints (basically, more distortion of glyphs is acceptable as long as certain features like triple-stem positions are respected more strictly).

We thus plan to handle such a case in the near future. Please be patient.

## Other questions

### IV.1 Can I use FreeType to draw text on a pixmap with arbitratry depth?

Not directly, as FreeType is a font library, not a general purpose graphics library or text rendering service. However, note that the anti-aliased renderer allows you to convert a vectorial glyph outline into a list of "spans" (i.e. horizontal pixel segments with same coverage) that can be rendered through user-provided callbacks.

By providing the appropriate span callback, you can render anti-aliased text to any kind of surface. You can also use any color or fill pattern/image if you want to. This process is called direct rendering. For more information, please read the documentation contained in the following files:

- `<freetype/ftimage.h>` contains the definition of the `FT_Raster_Params` type used with direct rendering.

- `<freetype/ftoutln.h>` contains the definition of the `FT_Outline_Render()` function that can be used to convert vectorial outlines to span lists.

Here's some code that uses them:

        FT_Raster_Params  params;
        FT_Outline        outline;

        ... load vectorial glyph in "outline" ...

        params.flags      = ft_raster_flag_aa | ft_raster_flag_direct;
        params.gray_spans = (FT_Raster_Span_Func)your_own_span_function_here;
        params.user       = your_own_data_pointer;

        error = FT_Outline_Render( library, &outline, &params );

Note that direct rendering is not available with monochrome output, as the current renderer uses a two-pass algorithm to generate glyphs with correct drop-out control.

### IV.2 How can I set the color of text rendered by FreeType?

Basically, you can't do that, because FreeType is simply a font library. In general, you will need to use your favorite graphics library to draw the FreeType glyphs with the appropriate color.

Note that for anti-aliased glyphs, you can "set the color" by using direct rendering as described in this answer.

### IV.3 I set the pixel size to 8x8, but the resulting glyphs are larger (or smaller) than that. Why?

A lot of people have difficulties to understand this topic, because they think of glyphs as fixed-width resp. fixed-height "cells", like those of fonts used in terminals/consoles. This assumption is simply not valid with most "modern" font formats, even bitmapped-based ones like `PCF` or `BDF`.

Be aware that the character size that is set either through `FT_Set_Char_Size()` or `FT_Set_Pixel_Sizes()` isn't directly related to the dimension of the glyph bitmaps generated.

Rather, the character size is indeed the size of an abstract square, called the EM, used by typographers to design fonts. Scaling two distinct fonts to the same character size, be it expressed in points or pixels, will generally result in bitmaps with distinct dimensions!

Note that historically, the EM corresponded to the width of a capital "M" in Latin typefaces. However, later improvements in typography led to designs that greatly detract from this rule. Today, it is not possible to connect the EM size to a specific font "feature" in a reliable way.

### IV.4 How can I compute the bounding box of a given string of text without loading its glyphs before?

A lot of people want to be able to compute the size in pixels of a simple string of text with minimal overhead. For example, that can be useful to draw centered text within a button. (to be continued...)

### IV.5 Which anti-aliasing algorithm is used by FreeType 2?

The algorithm has been specifically designed for FreeType. It is based on ideas that were originally found in the implementation of the libArt graphics library to compute the exact pixel coverage of a vector image with absolutely no sub-sampling/filtering.

However, these two implementations are radically distinct and use vastly different models. The FreeType 2 renderer is optimized specifically for rendering small complex shapes, like glyphs, at very high speed while using very few memory; while libArt shines at general shape/polygon processing, especially large ones.

The FreeType 2 anti-aliasing renderer is indeed faster than the monochrome renderer for small character sizes (typically <20 pixels). The reason is that the monochrome renderer must perform two passes on the outline in order to perform drop-out control according to the TrueType specification (we could drop this requirement later though).

We will try to document its design in a later document, though this is not a priority for now.

### IV.6 When will FreeType 2 support OpenType?

Well, the engine already reads OpenType/CFF files perfectly. What it doesn't do is handle "OpenType Layout" tables yet.

FreeType 1 comes with a set of extensions that are used to load and manage OpenType Layout tables. It even has a demonstration program named `ftstrtto` to show its capabilities.

For FreeType 2, we have decided that the layout operations provided through these tables are better placed in a specific text-layout library, (many people having asked for such a thing). This new engine will not depend on FreeType2 explicitly and will be developed as a separate project. We plan to announce it in a few weeks with all gory details, once the definitive 2.0 release of FreeType has been made.

Back to FreeType homepage