FreeType FAQ

General questions

What is FreeType?

It is a software library that can be used by all kinds of applications to access the contents 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, and others.

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

  • 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 30kByte.

What can I do with FreeType?

FreeType is already used in many products. For example, it serves as a font rendering engine

  • in graphics subsystem and libraries to display text (Android OS, Apple's iOS, and others),
  • 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 contents of font files in a very easy way.

What can I not do with FreeType?

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

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

  • rendering glyphs to arbitrary surfaces
    FreeType doesn't try to be a graphics library and thus only supports a very small number of pixel formats when rendering glyphs, in particular monochrome 1-bit bitmaps and 8-bit gray-level pixmaps.

    If you need to draw glyphs to other kinds of surfaces (for example, a 24-bit RGB pixmap), you 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, FreeType does it by parsing the relevant portion of the font file or font stream and interpreting it according to its font format. This can be very slow for certain formats, including scalable ones like TrueType or CFF.

    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 caching sub-system with FreeType. However, it might not suit your needs.

  • text layout
    The library doesn't support text layout operations. Sophisticated features like glyph substitution, positioning (kerning), justification, bi-directional ordering, etc., are not part of a font service in itself. They must be handled (at least) one level higher.

How portable is FreeType?

FreeType's source code is extremely portable for the following reasons.

  • Everything is written in standard ANSI C.

  • We are 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). It is completely thread-safe too.

We have made great efforts to ensure that the library is efficient, compact, and customizable.

Can I use FreeType to edit fonts or create new ones?

No. The library is specifically designed to read font files with small code size and very low memory usage.

A good, freely available font editor is FontForge.

How do I render a line of text in FreeType?

FreeType is a very low-level rendering engine. All it knows how to do is render individual glyphs and return metrics for them.

Arranging glyphs into words and lines is best left to a 2D graphics rendering library like Cairo. Cairo is able to do some primitive typesetting, including very basic translation of Unicode character codes to glyphs; for a more general solution, it uses Pango for text layout, which in turn relies on HarfBuzz to implement the full OpenType rules for glyph substitution and placement (Cairo still handles the actual text drawing). To deal with right-to-left (Arabic, Hebrew) text layout, you will also need FriBidi, which handles the details of the Unicode bidirectional layout algorithm.

And finally, to cope with additional niceties like dealing with writing-system-specific rules for word breaks and line breaks, you might like to look at ICU, which includes a whole range of internationalization and localization facilities.

Compilation & configuration

How do I compile the FreeType library?

The library can be compiled in various ways, and detailed documentation is available in documentation directory of FreeType's source tree.

For compilation on the command line, GNU make is the standard tool. The source bundle also comes with support files for CMake and meson builds, together with project files for Visual C++ and some other, older graphical IDEs. Note, however, that those files are sometimes not up to date since it is contributed code not used by the core developers.

How do I configure my build of the library?

This is fully described in the file CUSTOMIZE in FreeType's documentation directory. Basically, you have to edit the header file ftoption.h for compile-time options and to select the modules with the file modules.cfg. Finally, it is possible to replace the standard system interface (dealing with memory allocation and stream I/O) with a custom one.

Why does FreeType render differently on different platforms?

Different distributions compile FreeType with different options. The developer version of a distribution's FreeType package, which is needed to compile your program against FreeType, includes the file ftoption.h. Compare each platform's copy of ftoption.h to find the differences.

The FreeType auto-hinter

How does the auto-hinter work?

Please note that the name of auto-hinter module is autofit, which is a reimplementation of the old ‘autohint’ module.

A rather complete description of the hinting algorithm (which is slightly out of date regarding the internal structures) can be found in the TUGboat article Real-Time Grid Fitting of Typographic Outlines.

The auto-hinter performs 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 function FT_Load_Glyph.

Currently, the auto-hinter 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.

Why doesn't the auto-hinter work well with my script?

The auto-hinter was first designed to manage and hint Latin-based fonts, as they consist of most of the fonts available today. It now supports almost all scripts available in Unicode.

Hinting various scripts isn't really more difficult than Latin, just different, with a set of different constraints, which must be hard-coded into the autofit module. If your particular script is still missing and you are an expert for this script, we would be very glad to add the necessary code with your help!

Other questions

Can I use FreeType to draw text on a pixmap with arbitrary depth?

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

By providing an appropriate span callback, you can render anti-aliased text to any kind of surface. You can also use any colour, fill pattern or fill image if you want to. This process is called direct rendering.

A complete example is given in the FreeType tutorial.

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.

How can I set the colour of text rendered by FreeType?

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

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

I set the pixel size to 8×8, 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 or fixed-height ‘cells’, like those of fonts used in terminals or consoles. This assumption is not valid with most ‘modern’ font formats, it even fails for bitmapped-based ones like PCF or BDF.

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

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

Note that historically, the EM Square corresponded to the width of a capital ‘M’ in Latin typefaces (thus the name). However, later improvements in typography led to designs that greatly deviate from this rule. Today, it is not possible to connect the EM size to a specific font ‘feature’ in a reliable way.

How can I compute the bounding box of a text string without loading its glyphs before?

This is not possible in general. Reason is that hinting distorts the glyph shape for optimal rasterization, and this process sometimes creates outlines that have considerably different metrics. The TrueType format provides the (optional) ‘hdmx’ table that contains device horizontal metrics for selected pixel sizes, but even here the vertical metrics are missing.

It is probably best to use both a glyph and a metrics cache to avoid recomputation.

Which anti-aliasing algorithm is used by FreeType?

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 no sub-sampling and filtering.

However, these two implementations are radically distinct and use vastly different models. The FreeType renderer is optimized specifically for rendering small complex shapes, like glyphs, at very high speed while using very few memory. On the other hand, libArt has been designed for general shape and polygon processing, especially large ones.

The FreeType 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.

When will FreeType support OpenType?

Well, the engine already reads OpenType/CFF files perfectly. What it doesn't do is handling ‘OpenType Layout’ tables.

The predecessor of FreeType 2, the now defunct FreeType 1 series, came with a set of extensions that were used to load and manage OpenType Layout tables. It even had a demonstration program named ftstrtto to show its capabilities. However, this code is no longer maintained, and we strongly advise to not use it.

See this answer for more.

How to implement Asian vertical writing text with FreeType?

FreeType 2 no longer supports it. Before the general adoption of OpenType in the font industry, text renderers implemented many hacks to handle vertical typesetting, like detection of the vertical writing mode by relying on modified font names, renderer-side rotation to obtain vertical glyph representation forms, or putting pre-rotated glyphs at non-standard Unicode PUA codepoints in the font. Modern operating systems and font developers switched to TrueType GX and later to OpenType many years ago, and fonts designed for such legacy technologies are no longer widely distributed.

See this answer for more.

Last update: 16-May-2021