2. Overview

Fontconfig is a library designed to provide system-wide font configuration, customization and application access.

This manual describes fontconfig version 1.0.2.

Fontconfig contains two essential modules, the configuration module which builds an internal configuration from XML files and the matching module which accepts font patterns and returns the nearest matching font.

2.1 Font Configuration

The configuration module consists of the FcConfig datatype, libexpat and FcConfigParse which walks over an XML tree and amends a configuration with data found within. From an external perspective, configuration of the library consists of generating a valid XML tree and feeding that to FcConfigParse. The only other mechanism provided to applications for changing the running configuration is to add fonts and directories to the list of application-provided font files.

The intent is to make font configuration relatively static, and shared by as many applications as possible. It is hoped that this will lead to more stable font selection when passing names from one application to another. XML was chosen as a configuration file format because it provides a format which is easy for external agents to edit while retaining the correct structure and syntax.

Font configuration is separate from font matching; applications needing to do their own matching can access the available fonts from the library and perform private matching. The intent is to permit applications to pick and choose appropriate functionality from the library instead of forcing them to choose between this library and a private configuration mechanism. The hope is that this will ensure that configuration of fonts for all applications can be centralized in one place. Centralizing font configuration will simplify and regularize font installation and customization.

2.2 Font Properties

While font patterns may contain essentially any properties, there are some well known properties with associated types. Fontconfig uses some of these properties for font matching and font completion. Others are provided as a convenience for the applications rendering mechanism. Some symbolic constants are provided for common values or enumerated types. @xref{Constants}, for the list of standard properties and values.

2.3 Font Matching

Fontconfig performs matching by measuring the distance from a provided pattern to all of the available fonts in the system. The closest matching font is selected. This ensures that a font will always be returned, but doesn't ensure that it is anything like the requested pattern.

Font matching starts with an application constructed pattern. The desired attributes of the resulting font are collected together in an FcPattern object. Each property of the pattern can contain one or more values; these are listed in priority order; matches earlier in the list are considered "closer" than matches later in the list.

The initial pattern is modified by applying the list of editing instructions specific to patterns found in the configuration; each consists of a match predicate and a set of editing operations. They are executed in the order they appeared in the configuration. Each match causes the associated sequence of editing operations to be applied.

After the pattern has been edited, a sequence of default substitutions are performed to canonicalize the set of available properties; this avoids the need for the lower layers to constantly provide default values for various font properties during rendering.

The canonical font pattern is finally matched against all available fonts. The distance from the pattern to the font is measured for each of several properties: foundry, charset, family, lang, spacing, pixelsize, style, slant, weight, antialias, rasterizer and outline. This list is in priority order--results of comparing earlier elements of this list weigh more heavily than later elements.

There is one special case to this rule; family names are split into two bindings; strong and weak. Strong family names are given greater precedence in the match than lang elements while weak family names are given lower precedence than lang elements. This permits the document language to drive font selection when any document specified font is unavailable.

The pattern representing that font is augmented to include any properties found in the pattern but not found in the font itself; this permits the application to pass rendering instructions or any other data through the matching system. Finally, the list of editing instructions specific to fonts found in the configuration are applied to the pattern. This modified pattern is returned to the application.

The return value contains sufficient information to locate and rasterize the font, including the file name, pixel size and other rendering data. As none of the information involved pertains to the FreeType library, applications are free to use any rasterization engine or even to take the identified font file and access it directly.

The match/edit sequences in the configuration are performed in two passes because there are essentially two different operations necessary -- the first is to modify how fonts are selected; aliasing families and adding suitable defaults. The second is to modify how the selected fonts are rasterized. Those must apply to the selected font, not the original pattern as false matches will often occur.

2.4 Font List Matching

While many applications want to locate a single font best matching their search criteria, other applications need to build a set of fonts which can be used to present any Unicode data. Fontconfig provides an API to generate a list sorted by the nearness of each font to the pattern. Every font in the system is considered, the best matching fonts are placed first. The application then can select whether the remaining fonts are unconditionally included in the list, or whether they are included only if they cover portions of Unicode not covered by any of the preceeding fonts.

The list resulting from this match is represented by references to the original font patterns and so consumes very little memory. Using a list entry involves creating a pattern which combines the information from the font with the information from the original pattern and executing the font substitutions.

2.5 Font Names

Fontconfig provides a textual representation for patterns that the library can both accept and generate. The representation is in three parts, first a list of family names, second a list of point sizes and finally a list of additional properties:

	<families>-<point sizes>:<name1>=<values1>:<name2>=<values2>...

Values in a list are separated with commas. A hyphen or comma in a family name must be escaped with a backslash. The name needn't include either families or point sizes; they can be elided. If the family name only is given, the hyphen may be omitted. If there are no additional properties, no trailing colon should be used. In addition, there are symbolic constants that simultaneously indicate both a name and a value. Here are some examples:

Times-12                    12 point Times Roman
Times-12:bold               12 point Times Bold
Courier:italic              Courier Italic in the default size
Monospace:matrix=1 .1 0 1   The users preferred monospace font
                            with artificial obliquing
Mikachan\-PB-16             12 point Mikachan-PB

2.6 LANG Tags

Each font in the database contains a list of languages it supports. This is computed by comparing the Unicode coverage of the font with the orthography of each language. Languages are tagged using an RFC-3066 compatible naming and occur in two parts -- the ISO639 language tag followed a hyphen and then by the ISO 3166 country code. The hyphen and country code may be elided.

Fontconfig has orthographies for several languages built into the library. No provision has been made for adding new ones aside from rebuilding the library. It currently supports 122 of the 139 languages named in ISO 639-1, 141 of the languages with two-letter codes from ISO 639-2 and another 30 languages with only three-letter codes.

This document was generated by XEmacs shared group account on December, 19 2009 using texi2html 1.65.