Fontconfig Developers Reference, Version 2.8.0
Keith Packard
HP Cambridge Research Lab
Table of Contents
DESCRIPTION .....................................................................................................................3
FUNCTIONAL OVERVIEW...............................................................................................3
Datatypes................................................................................................................................4
FUNCTIONS .........................................................................................................................8
DESCRIPTION
Fontconfig is a library designed to provide system-wide font configuration,
customization and application access.
FUNCTIONAL OVERVIEW
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.
FONT CONFIGURATION
The configuration module consists of the FcConfig datatype, libexpat and FcConfig-
Parse which walks over an XML tree and ammends a configuration with data found
within. From an external perspective, configuration of the library consists of gener-
ating 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 configurations relatively static, and shared by as many ap-
plications 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 func-
tionality 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 configu-
ration of fonts for all applications can be centralized in one place. Centralizing font
configuration will simplify and regularize font installation and customization.
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.
Property Definitions
Property CPP Symbol Type Description
----------------------------------------------------
family FC_FAMILY String Font family names
familylang FC_FAMILYLANG String Language cooresponding to
each family name
style FC_STYLE String Font style. Overrides weight
and slant
stylelang FC_STYLELANG String Language cooresponding to
each style name
fullname FC_FULLNAME String Font face full name where
different from family and
family + style
fullnamelang FC_FULLNAMELANG String Language cooresponding to
each fullname
slant FC_SLANT Int Italic, oblique or roman
weight FC_WEIGHT Int Light, medium, demibold,
bold or black
3
Fontconfig Developers Reference, Version 2.8.0
size FC_SIZE Double Point size
width FC_WIDTH Int Condensed, normal or expanded
aspect FC_ASPECT Double Stretches glyphs horizontally
before hinting
pixelsize FC_PIXEL_SIZE Double Pixel size
spacing FC_SPACING Int Proportional, dual-width,
monospace or charcell
foundry FC_FOUNDRY String Font foundry name
antialias FC_ANTIALIAS Bool Whether glyphs can be
antialiased
hinting FC_HINTING Bool Whether the rasterizer should
use hinting
hintstyle FC_HINT_STYLE Int Automatic hinting style
verticallayout FC_VERTICAL_LAYOUT Bool Use vertical layout
autohint FC_AUTOHINT Bool Use autohinter instead of
normal hinter
globaladvance FC_GLOBAL_ADVANCE Bool Use font global advance data
file FC_FILE String The filename holding the font
index FC_INDEX Int The index of the font within
the file
ftface FC_FT_FACE FT_Face Use the specified FreeType
face object
rasterizer FC_RASTERIZER String Which rasterizer is in use
outline FC_OUTLINE Bool Whether the glyphs are outlines
scalable FC_SCALABLE Bool Whether glyphs can be scaled
scale FC_SCALE Double Scale factor for point->pixel
conversions
dpi FC_DPI Double Target dots per inch
rgba FC_RGBA Int unknown, rgb, bgr, vrgb,
vbgr, none - subpixel geometry
lcdfilter FC_LCD_FILTER Int Type of LCD filter
minspace FC_MINSPACE Bool Eliminate leading from line
spacing
charset FC_CHARSET CharSet Unicode chars encoded by
the font
lang FC_LANG LangSet Set of RFC-3066-style
languages this font supports
fontversion FC_FONTVERSION Int Version number of the font
capability FC_CAPABILITY String List of layout capabilities in
the font
embolden FC_EMBOLDEN Bool Rasterizer should
synthetically embolden the font
Datatypes
Fontconfig uses abstract datatypes to hide internal implementation details for most
data structures. A few structures are exposed where appropriate.
FcChar8, FcChar16, FcChar32, FcBool
These are primitive datatypes; the FcChar* types hold precisely the number of bits
stated (if supported by the C implementation). FcBool holds one of two CPP symbols:
FcFalse or FcTrue.
4
Fontconfig Developers Reference, Version 2.8.0
FcMatrix
An FcMatrix holds an affine transformation, usually used to reshape glyphs. A small
set of matrix operations are provided to manipulate these.
typedef struct _FcMatrix {
double xx, xy, yx, yy;
} FcMatrix;
FcCharSet
An FcCharSet is an abstract type that holds the set of encoded unicode chars in a font.
Operations to build and compare these sets are provided.
FcLangSet
An FcLangSet is an abstract type that holds the set of languages supported by a font.
Operations to build and compare these sets are provided. These are computed for a
font based on orthographic information built into the fontconfig library. Fontconfig
has orthographies for all of the ISO 639-1 languages except for MS, NA, PA, PS, QU,
RN, RW, SD, SG, SN, SU and ZA. If you have orthographic information for any of
these languages, please submit them.
FcLangResult
An FcLangResult is an enumeration used to return the results of comparing two lan-
guage strings or FcLangSet objects. FcLangEqual means the objects match language
and territory. FcLangDifferentTerritory means the objects match in language but dif-
fer in territory. FcLangDifferentLang means the objects differ in language.
FcType
Tags the kind of data stored in an FcValue.
FcValue
An FcValue object holds a single value with one of a number of different types. The
’type’ tag indicates which member is valid.
typedef struct _FcValue {
FcType type;
union {
const FcChar8
*
s;
int i;
FcBool b;
double d;
const FcMatrix
*
m;
const FcCharSet
*
c;
void
*
f;
const FcLangSet
*
l;
} u;
} FcValue;
5