1
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
2
<!ENTITY fcatomic SYSTEM "fcatomic.sgml">
3
<!ENTITY fcblanks SYSTEM "fcblanks.sgml">
4
<!ENTITY fccharset SYSTEM "fccharset.sgml">
5
<!ENTITY fcconfig SYSTEM "fcconfig.sgml">
6
<!ENTITY fcconstant SYSTEM "fcconstant.sgml">
7
<!ENTITY fcfile SYSTEM "fcfile.sgml">
8
<!ENTITY fcfontset SYSTEM "fcfontset.sgml">
9
<!ENTITY fcfreetype SYSTEM "fcfreetype.sgml">
10
<!ENTITY fcinit SYSTEM "fcinit.sgml">
11
<!ENTITY fcmatrix SYSTEM "fcmatrix.sgml">
12
<!ENTITY fcobjectset SYSTEM "fcobjectset.sgml">
13
<!ENTITY fcobjecttype SYSTEM "fcobjecttype.sgml">
14
<!ENTITY fcpattern SYSTEM "fcpattern.sgml">
15
<!ENTITY fcstring SYSTEM "fcstring.sgml">
16
<!ENTITY fcstrset SYSTEM "fcstrset.sgml">
17
<!ENTITY fcvalue SYSTEM "fcvalue.sgml">
18
<!ENTITY version SYSTEM "version.sgml">
21
$Id: fontconfig-devel.sgml,v 1.6.2.1 2003/04/23 04:09:56 keithp Exp $
23
Copyright � 2003 Keith Packard
25
Permission to use, copy, modify, distribute, and sell this software and its
26
documentation for any purpose is hereby granted without fee, provided that
27
the above copyright notice appear in all copies and that both that
28
copyright notice and this permission notice appear in supporting
29
documentation, and that the name of Keith Packard not be used in
30
advertising or publicity pertaining to distribution of the software without
31
specific, written prior permission. Keith Packard makes no
32
representations about the suitability of this software for any purpose. It
33
is provided "as is" without express or implied warranty.
35
KEITH PACKARD DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
36
INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
37
EVENT SHALL KEITH PACKARD BE LIABLE FOR ANY SPECIAL, INDIRECT OR
38
CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
39
DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
40
TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
41
PERFORMANCE OF THIS SOFTWARE.
44
<title>Fontconfig Developers Reference, Version &version; </title>
47
<firstname>Keith</firstname>
48
<surname>Packard</surname>
49
<affiliation><orgname>
50
HP Cambridge Research Lab
51
</orgname></affiliation>
53
<authorinitials>KRP</authorinitials>
54
<productname>Fontconfig</productname>
55
<productnumber>&version;</productnumber>
58
Copyright � 2002 Keith Packard
60
Permission to use, copy, modify, distribute, and sell this software and its
61
documentation for any purpose is hereby granted without fee, provided that
62
the above copyright notice appear in all copies and that both that
63
copyright notice and this permission notice appear in supporting
64
documentation, and that the name of Keith Packard not be used in
65
advertising or publicity pertaining to distribution of the software without
66
specific, written prior permission. Keith Packard makes no
67
representations about the suitability of this software for any purpose. It
68
is provided "as is" without express or implied warranty.
70
KEITH PACKARD DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
71
INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
72
EVENT SHALL KEITH PACKARD BE LIABLE FOR ANY SPECIAL, INDIRECT OR
73
CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
74
DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
75
TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
76
PERFORMANCE OF THIS SOFTWARE.
80
<sect1><title>DESCRIPTION</title>
82
Fontconfig is a library designed to provide system-wide font configuration,
83
customization and application access.
86
<sect1><title>FUNCTIONAL OVERVIEW</title>
88
Fontconfig contains two essential modules, the configuration module which
89
builds an internal configuration from XML files and the matching module
90
which accepts font patterns and returns the nearest matching font.
92
<sect2><title>FONT CONFIGURATION</title>
94
The configuration module consists of the FcConfig datatype, libexpat and
95
FcConfigParse which walks over an XML tree and ammends a configuration with
96
data found within. From an external perspective, configuration of the
97
library consists of generating a valid XML tree and feeding that to
98
FcConfigParse. The only other mechanism provided to applications for
99
changing the running configuration is to add fonts and directories to the
100
list of application-provided font files.
102
The intent is to make font configurations relatively static, and shared by
103
as many applications as possible. It is hoped that this will lead to more
104
stable font selection when passing names from one application to another.
105
XML was chosen as a configuration file format because it provides a format
106
which is easy for external agents to edit while retaining the correct
107
structure and syntax.
109
Font configuration is separate from font matching; applications needing to
110
do their own matching can access the available fonts from the library and
111
perform private matching. The intent is to permit applications to pick and
112
choose appropriate functionality from the library instead of forcing them to
113
choose between this library and a private configuration mechanism. The hope
114
is that this will ensure that configuration of fonts for all applications
115
can be centralized in one place. Centralizing font configuration will
116
simplify and regularize font installation and customization.
120
<title>FONT PROPERTIES</title>
122
While font patterns may contain essentially any properties, there are some
123
well known properties with associated types. Fontconfig uses some of these
124
properties for font matching and font completion. Others are provided as a
125
convenience for the applications rendering mechanism.
130
Property CPP Symbol Type Description
131
----------------------------------------------------
132
family FC_FAMILY String Font family name
133
style FC_STYLE String Font style. Overrides weight
135
slant FC_SLANT Int Italic, oblique or roman
136
weight FC_WEIGHT Int Light, medium, demibold,
138
size FC_SIZE Double Point size
139
aspect FC_ASPECT Double Stretches glyphs horizontally
141
pixelsize FC_PIXEL_SIZE Double Pixel size
142
spacing FC_SPACING Int Proportional, monospace or
144
foundry FC_FOUNDRY String Font foundry name
145
antialias FC_ANTIALIAS Bool Whether glyphs can be
147
hinting FC_HINTING Bool Whether the rasterizer should
149
verticallayout FC_VERTICAL_LAYOUT Bool Use vertical layout
150
autohint FC_AUTOHINT Bool Use autohinter instead of
152
globaladvance FC_GLOBAL_ADVANCE Bool Use font global advance data
153
file FC_FILE String The filename holding the font
154
index FC_INDEX Int The index of the font within
156
ftface FC_FT_FACE FT_Face Use the specified FreeType
158
rasterizer FC_RASTERIZER String Which rasterizer is in use
159
outline FC_OUTLINE Bool Whether the glyphs are outlines
160
scalable FC_SCALABLE Bool Whether glyphs can be scaled
161
scale FC_SCALE Double Scale factor for point->pixel
163
dpi FC_DPI Double Target dots per inch
164
rgba FC_RGBA Int unknown, rgb, bgr, vrgb,
165
vbgr, none - subpixel geometry
166
minspace FC_MINSPACE Bool Eliminate leading from line
168
charset FC_CHARSET CharSet Unicode chars encoded by
170
lang FC_LANG String List of RFC-3066-style
171
languages this font supports
175
<sect1><title>Datatypes</title>
177
Fontconfig uses abstract datatypes to hide internal implementation details
178
for most data structures. A few structures are exposed where appropriate.
180
<sect2><title>FcChar8, FcChar16, FcChar32, FcBool</title>
182
These are primitive datatypes; the FcChar* types hold precisely the number
183
of bits stated (if supported by the C implementation). FcBool holds
184
one of two CPP symbols: FcFalse or FcTrue.
187
<sect2><title>FcMatrix</title>
189
An FcMatrix holds an affine transformation, usually used to reshape glyphs.
190
A small set of matrix operations are provided to manipulate these.
192
typedef struct _FcMatrix {
193
double xx, xy, yx, yy;
198
<sect2><title>FcCharSet</title>
200
An FcCharSet is an abstract type that holds the set of encoded unicode chars
201
in a font. Operations to build and compare these sets are provided.
204
<sect2><title>FcType</title>
206
Tags the kind of data stored in an FcValue.
209
<sect2><title>FcValue</title>
211
An FcValue object holds a single value with one of a number of different
212
types. The 'type' tag indicates which member is valid.
214
typedef struct _FcValue {
229
Type Union member Datatype
230
--------------------------------
231
FcTypeVoid (none) (none)
233
FcTypeDouble d double
234
FcTypeString s char *
236
FcTypeMatrix m FcMatrix *
237
FcTypeCharSet c FcCharSet *
241
<sect2><title>FcPattern</title>
243
holds a set of names with associated value lists; each name refers to a
244
property of a font. FcPatterns are used as inputs to the matching code as
245
well as holding information about specific fonts. Each property can hold
246
one or more values; conventionally all of the same type, although the
247
interface doesn't demand that.
250
<sect2><title>FcFontSet</title>
253
typedef struct _FcFontSet {
259
An FcFontSet contains a list of FcPatterns. Internally fontconfig uses this
260
data structure to hold sets of fonts. Externally, fontconfig returns the
261
results of listing fonts in this format. 'nfont' holds the number of
262
patterns in the 'fonts' array; 'sfont' is used to indicate the size of that
266
<sect2><title>FcStrSet, FcStrList</title>
268
FcStrSet holds a list of strings that can be appended to and enumerated.
269
Its unique characteristic is that the enumeration works even while strings
270
are appended during enumeration. FcStrList is used during enumeration to
271
safely and correctly walk the list of strings even while that list is edited
272
in the middle of enumeration.
275
<sect2><title>FcObjectSet</title>
278
typedef struct _FcObjectSet {
281
const char **objects;
284
holds a set of names and is used to specify which fields from fonts are
285
placed in the the list of returned patterns when listing fonts.
288
<sect2><title>FcObjectType</title>
291
typedef struct _FcObjectType {
296
marks the type of a pattern element generated when parsing font names.
297
Applications can add new object types so that font names may contain the new
301
<sect2><title>FcConstant</title>
304
typedef struct _FcConstant {
310
Provides for symbolic constants for new pattern elements. When 'name' is
311
seen in a font name, an 'object' element is created with value 'value'.
314
<sect2><title>FcBlanks</title>
316
holds a list of Unicode chars which are expected to be blank; unexpectedly
317
blank chars are assumed to be invalid and are elided from the charset
318
associated with the font.
321
<sect2><title>FcFileCache</title>
323
holds the per-user cache information for use while loading the font
324
database. This is built automatically for the current configuration when
325
that is loaded. Applications must always pass '0' when one is requested.
328
<sect2><title>FcConfig</title>
330
holds a complete configuration of the library; there is one default
331
configuration, other can be constructed from XML data structures. All
332
public entry points that need global data can take an optional FcConfig*
333
argument; passing 0 uses the default configuration. FcConfig objects hold two
334
sets of fonts, the first contains those specified by the configuration, the
335
second set holds those added by the application at run-time. Interfaces
336
that need to reference a particulat set use one of the FcSetName enumerated
340
<sect2><title>FcSetName</title>
342
Specifies one of the two sets of fonts available in a configuration;
343
FcSetSystem for those fonts specified in the configuration and
344
FcSetApplication which holds fonts provided by the application.
347
<sect2><title>FcResult</title>
349
Used as a return type for functions manipulating FcPattern objects.
353
-----------------------------------------------------------
354
FcResultMatch Object exists with the specified ID
355
FcResultNoMatch Object doesn't exist at all
356
FcResultTypeMismatch Object exists, but the type doesn't match
357
FcResultNoId Object exists, but has fewer values
362
<sect2><title>FcAtomic</title>
364
Used for locking access to config files. Provides a safe way to update
369
<sect1><title>FUNCTIONS</title>
371
These are grouped by functionality, often using the main datatype being
374
<sect2><title>Initialization</title>
376
These functions provide some control over how the library is initialized.
380
<sect2><title>FcPattern</title>
382
An FcPattern is an opaque type that holds both patterns to match against the
383
available fonts, as well as the information about each font.
387
<sect2><title>FcFontSet</title>
389
An FcFontSet simply holds a list of patterns; these are used to return the
390
results of listing available fonts.
394
<sect2><title>FcObjectSet</title>
396
An FcObjectSet holds a list of pattern property names; it is used to
397
indiciate which properties are to be returned in the patterns from
402
<sect2><title>FreeType specific functions</title>
404
While the fontconfig library doesn't insist that FreeType be used as the
405
rasterization mechanism for fonts, it does provide some convenience
410
<sect2><title>FcValue</title>
412
FcValue is a structure containing a type tag and a union of all possible
413
datatypes. The tag is an enum of type
414
<emphasis>FcType</emphasis>
415
and is intended to provide a measure of run-time
416
typechecking, although that depends on careful programming.
420
<sect2><title>FcCharSet</title>
422
An FcCharSet is a boolean array indicating a set of unicode chars. Those
423
associated with a font are marked constant and cannot be edited.
424
FcCharSets may be reference counted internally to reduce memory consumption;
425
this may be visible to applications as the result of FcCharSetCopy may
426
return it's argument, and that CharSet may remain unmodifiable.
430
<sect2><title>FcMatrix</title>
432
FcMatrix structures hold an affine transformation in matrix form.
436
<sect2><title>FcConfig</title>
438
An FcConfig object holds the internal representation of a configuration.
439
There is a default configuration which applications may use by passing 0 to
440
any function using the data within an FcConfig.
444
<sect2><title>FcObjectType</title>
446
Provides for applcation-specified font name object types so that new
447
pattern elements can be generated from font names.
451
<sect2><title>FcConstant</title>
453
Provides for application-specified symbolic constants for font names.
457
<sect2><title>FcBlanks</title>
459
An FcBlanks object holds a list of Unicode chars which are expected to
460
be blank when drawn. When scanning new fonts, any glyphs which are
461
empty and not in this list will be assumed to be broken and not placed in
462
the FcCharSet associated with the font. This provides a significantly more
463
accurate CharSet for applications.
467
<sect2><title>FcAtomic</title>
469
These functions provide a safe way to update config files, allowing ongoing
470
reading of the old config file while locked for writing and ensuring that a
471
consistent and complete version of the config file is always available.
475
<sect2><title>File and Directory routines</title>
477
These routines work with font files and directories, including font
478
directory cache files.
482
<sect2><title>FcStrSet and FcStrList</title>
484
A data structure for enumerating strings, used to list directories while
485
scanning the configuration as directories are added while scanning.
489
<sect2><title>String utilities</title>
491
Fontconfig manipulates many UTF-8 strings represented with the FcChar8 type.
492
These functions are exposed to help applications deal with these UTF-8
493
strings in a locale-insensitive manner.
added
removed
doc/fontconfig-devel.sgml
