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">
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 names
133 familylang FC_FAMILYLANG String Language cooresponding to
135 style FC_STYLE String Font style. Overrides weight
137 stylelang FC_STYLELANG String Language cooresponding to
139 fullname FC_FULLNAME String Font face full name where
140 different from family and
142 fullnamelang FC_FULLNAMELANG String Language cooresponding to
144 slant FC_SLANT Int Italic, oblique or roman
145 weight FC_WEIGHT Int Light, medium, demibold,
147 size FC_SIZE Double Point size
148 width FC_WIDTH Int Condensed, normal or expanded
149 aspect FC_ASPECT Double Stretches glyphs horizontally
151 pixelsize FC_PIXEL_SIZE Double Pixel size
152 spacing FC_SPACING Int Proportional, dual-width,
153 monospace or charcell
154 foundry FC_FOUNDRY String Font foundry name
155 antialias FC_ANTIALIAS Bool Whether glyphs can be
157 hinting FC_HINTING Bool Whether the rasterizer should
159 hintstyle FC_HINT_STYLE Int Automatic hinting style
160 verticallayout FC_VERTICAL_LAYOUT Bool Use vertical layout
161 autohint FC_AUTOHINT Bool Use autohinter instead of
163 globaladvance FC_GLOBAL_ADVANCE Bool Use font global advance data
164 file FC_FILE String The filename holding the font
165 index FC_INDEX Int The index of the font within
167 ftface FC_FT_FACE FT_Face Use the specified FreeType
169 rasterizer FC_RASTERIZER String Which rasterizer is in use
170 outline FC_OUTLINE Bool Whether the glyphs are outlines
171 scalable FC_SCALABLE Bool Whether glyphs can be scaled
172 scale FC_SCALE Double Scale factor for point->pixel
174 dpi FC_DPI Double Target dots per inch
175 rgba FC_RGBA Int unknown, rgb, bgr, vrgb,
176 vbgr, none - subpixel geometry
177 minspace FC_MINSPACE Bool Eliminate leading from line
179 charset FC_CHARSET CharSet Unicode chars encoded by
181 lang FC_LANG String List of RFC-3066-style
182 languages this font supports
183 fontversion FC_FONTVERSION Int Version number of the font
184 capability FC_CAPABILITY String List of layout capabilities in
186 embolden FC_EMBOLDEN Bool Rasterizer should
187 synthetically embolden the font
191 <sect1><title>Datatypes</title>
193 Fontconfig uses abstract datatypes to hide internal implementation details
194 for most data structures. A few structures are exposed where appropriate.
196 <sect2><title>FcChar8, FcChar16, FcChar32, FcBool</title>
198 These are primitive datatypes; the FcChar* types hold precisely the number
199 of bits stated (if supported by the C implementation). FcBool holds
200 one of two CPP symbols: FcFalse or FcTrue.
203 <sect2><title>FcMatrix</title>
205 An FcMatrix holds an affine transformation, usually used to reshape glyphs.
206 A small set of matrix operations are provided to manipulate these.
208 typedef struct _FcMatrix {
209 double xx, xy, yx, yy;
214 <sect2><title>FcCharSet</title>
216 An FcCharSet is an abstract type that holds the set of encoded unicode chars
217 in a font. Operations to build and compare these sets are provided.
220 <sect2><title>FcType</title>
222 Tags the kind of data stored in an FcValue.
225 <sect2><title>FcValue</title>
227 An FcValue object holds a single value with one of a number of different
228 types. The 'type' tag indicates which member is valid.
230 typedef struct _FcValue {
245 Type Union member Datatype
246 --------------------------------
247 FcTypeVoid (none) (none)
249 FcTypeDouble d double
250 FcTypeString s char *
252 FcTypeMatrix m FcMatrix *
253 FcTypeCharSet c FcCharSet *
257 <sect2><title>FcPattern</title>
259 holds a set of names with associated value lists; each name refers to a
260 property of a font. FcPatterns are used as inputs to the matching code as
261 well as holding information about specific fonts. Each property can hold
262 one or more values; conventionally all of the same type, although the
263 interface doesn't demand that.
266 <sect2><title>FcFontSet</title>
269 typedef struct _FcFontSet {
275 An FcFontSet contains a list of FcPatterns. Internally fontconfig uses this
276 data structure to hold sets of fonts. Externally, fontconfig returns the
277 results of listing fonts in this format. 'nfont' holds the number of
278 patterns in the 'fonts' array; 'sfont' is used to indicate the size of that
282 <sect2><title>FcStrSet, FcStrList</title>
284 FcStrSet holds a list of strings that can be appended to and enumerated.
285 Its unique characteristic is that the enumeration works even while strings
286 are appended during enumeration. FcStrList is used during enumeration to
287 safely and correctly walk the list of strings even while that list is edited
288 in the middle of enumeration.
291 <sect2><title>FcObjectSet</title>
294 typedef struct _FcObjectSet {
297 const char **objects;
300 holds a set of names and is used to specify which fields from fonts are
301 placed in the the list of returned patterns when listing fonts.
304 <sect2><title>FcObjectType</title>
307 typedef struct _FcObjectType {
312 marks the type of a pattern element generated when parsing font names.
313 Applications can add new object types so that font names may contain the new
317 <sect2><title>FcConstant</title>
320 typedef struct _FcConstant {
326 Provides for symbolic constants for new pattern elements. When 'name' is
327 seen in a font name, an 'object' element is created with value 'value'.
330 <sect2><title>FcBlanks</title>
332 holds a list of Unicode chars which are expected to be blank; unexpectedly
333 blank chars are assumed to be invalid and are elided from the charset
334 associated with the font.
337 <sect2><title>FcFileCache</title>
339 holds the per-user cache information for use while loading the font
340 database. This is built automatically for the current configuration when
341 that is loaded. Applications must always pass '0' when one is requested.
344 <sect2><title>FcConfig</title>
346 holds a complete configuration of the library; there is one default
347 configuration, other can be constructed from XML data structures. All
348 public entry points that need global data can take an optional FcConfig*
349 argument; passing 0 uses the default configuration. FcConfig objects hold two
350 sets of fonts, the first contains those specified by the configuration, the
351 second set holds those added by the application at run-time. Interfaces
352 that need to reference a particulat set use one of the FcSetName enumerated
356 <sect2><title>FcSetName</title>
358 Specifies one of the two sets of fonts available in a configuration;
359 FcSetSystem for those fonts specified in the configuration and
360 FcSetApplication which holds fonts provided by the application.
363 <sect2><title>FcResult</title>
365 Used as a return type for functions manipulating FcPattern objects.
369 -----------------------------------------------------------
370 FcResultMatch Object exists with the specified ID
371 FcResultNoMatch Object doesn't exist at all
372 FcResultTypeMismatch Object exists, but the type doesn't match
373 FcResultNoId Object exists, but has fewer values
375 FcResultOutOfMemory Malloc failed
379 <sect2><title>FcAtomic</title>
381 Used for locking access to config files. Provides a safe way to update
386 <sect1><title>FUNCTIONS</title>
388 These are grouped by functionality, often using the main datatype being
391 <sect2><title>Initialization</title>
393 These functions provide some control over how the library is initialized.
397 <sect2><title>FcPattern</title>
399 An FcPattern is an opaque type that holds both patterns to match against the
400 available fonts, as well as the information about each font.
404 <sect2><title>FcFontSet</title>
406 An FcFontSet simply holds a list of patterns; these are used to return the
407 results of listing available fonts.
411 <sect2><title>FcObjectSet</title>
413 An FcObjectSet holds a list of pattern property names; it is used to
414 indiciate which properties are to be returned in the patterns from
419 <sect2><title>FreeType specific functions</title>
421 While the fontconfig library doesn't insist that FreeType be used as the
422 rasterization mechanism for fonts, it does provide some convenience
427 <sect2><title>FcValue</title>
429 FcValue is a structure containing a type tag and a union of all possible
430 datatypes. The tag is an enum of type
431 <emphasis>FcType</emphasis>
432 and is intended to provide a measure of run-time
433 typechecking, although that depends on careful programming.
437 <sect2><title>FcCharSet</title>
439 An FcCharSet is a boolean array indicating a set of unicode chars. Those
440 associated with a font are marked constant and cannot be edited.
441 FcCharSets may be reference counted internally to reduce memory consumption;
442 this may be visible to applications as the result of FcCharSetCopy may
443 return it's argument, and that CharSet may remain unmodifiable.
447 <sect2><title>FcMatrix</title>
449 FcMatrix structures hold an affine transformation in matrix form.
453 <sect2><title>FcConfig</title>
455 An FcConfig object holds the internal representation of a configuration.
456 There is a default configuration which applications may use by passing 0 to
457 any function using the data within an FcConfig.
461 <sect2><title>FcObjectType</title>
463 Provides for applcation-specified font name object types so that new
464 pattern elements can be generated from font names.
468 <sect2><title>FcConstant</title>
470 Provides for application-specified symbolic constants for font names.
474 <sect2><title>FcBlanks</title>
476 An FcBlanks object holds a list of Unicode chars which are expected to
477 be blank when drawn. When scanning new fonts, any glyphs which are
478 empty and not in this list will be assumed to be broken and not placed in
479 the FcCharSet associated with the font. This provides a significantly more
480 accurate CharSet for applications.
484 <sect2><title>FcAtomic</title>
486 These functions provide a safe way to update config files, allowing ongoing
487 reading of the old config file while locked for writing and ensuring that a
488 consistent and complete version of the config file is always available.
492 <sect2><title>File and Directory routines</title>
494 These routines work with font files and directories, including font
495 directory cache files.
499 <sect2><title>FcStrSet and FcStrList</title>
501 A data structure for enumerating strings, used to list directories while
502 scanning the configuration as directories are added while scanning.
506 <sect2><title>String utilities</title>
508 Fontconfig manipulates many UTF-8 strings represented with the FcChar8 type.
509 These functions are exposed to help applications deal with these UTF-8
510 strings in a locale-insensitive manner.
git.wh0rd.org / fontconfig.git / blob