1 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
2 <!ENTITY fcatomic SYSTEM "fcatomic.sgml">
3 <!ENTITY fcblanks SYSTEM "fcblanks.sgml">
4 <!ENTITY fccache SYSTEM "fccache.sgml">
5 <!ENTITY fccharset SYSTEM "fccharset.sgml">
6 <!ENTITY fcconfig SYSTEM "fcconfig.sgml">
7 <!ENTITY fcconstant SYSTEM "fcconstant.sgml">
8 <!ENTITY fcdircache SYSTEM "fcdircache.sgml">
9 <!ENTITY fcfile SYSTEM "fcfile.sgml">
10 <!ENTITY fcfontset SYSTEM "fcfontset.sgml">
11 <!ENTITY fcformat SYSTEM "fcformat.sgml">
12 <!ENTITY fcfreetype SYSTEM "fcfreetype.sgml">
13 <!ENTITY fcinit SYSTEM "fcinit.sgml">
14 <!ENTITY fclangset SYSTEM "fclangset.sgml">
15 <!ENTITY fcmatrix SYSTEM "fcmatrix.sgml">
16 <!ENTITY fcobjectset SYSTEM "fcobjectset.sgml">
17 <!ENTITY fcobjecttype SYSTEM "fcobjecttype.sgml">
18 <!ENTITY fcpattern SYSTEM "fcpattern.sgml">
19 <!ENTITY fcstring SYSTEM "fcstring.sgml">
20 <!ENTITY fcstrset SYSTEM "fcstrset.sgml">
21 <!ENTITY fcvalue SYSTEM "fcvalue.sgml">
22 <!ENTITY version SYSTEM "version.sgml">
25 fontconfig/doc/local-fontconfig-devel.sgml
27 Copyright © 2003 Keith Packard
29 Permission to use, copy, modify, distribute, and sell this software and its
30 documentation for any purpose is hereby granted without fee, provided that
31 the above copyright notice appear in all copies and that both that
32 copyright notice and this permission notice appear in supporting
33 documentation, and that the name of the author(s) not be used in
34 advertising or publicity pertaining to distribution of the software without
35 specific, written prior permission. The authors make no
36 representations about the suitability of this software for any purpose. It
37 is provided "as is" without express or implied warranty.
39 THE AUTHOR(S) DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
40 INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
41 EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY SPECIAL, INDIRECT OR
42 CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
43 DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
44 TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
45 PERFORMANCE OF THIS SOFTWARE.
48 <title>Fontconfig Developers Reference, Version &version; </title>
51 <firstname>Keith</firstname>
52 <surname>Packard</surname>
53 <affiliation><orgname>
54 HP Cambridge Research Lab
55 </orgname></affiliation>
57 <authorinitials>KRP</authorinitials>
58 <productname>Fontconfig</productname>
59 <productnumber>&version;</productnumber>
62 Copyright © 2002 Keith Packard
64 Permission to use, copy, modify, distribute, and sell this software and its
65 documentation for any purpose is hereby granted without fee, provided that
66 the above copyright notice appear in all copies and that both that
67 copyright notice and this permission notice appear in supporting
68 documentation, and that the name of the author(s) not be used in
69 advertising or publicity pertaining to distribution of the software without
70 specific, written prior permission. The authors make no
71 representations about the suitability of this software for any purpose. It
72 is provided "as is" without express or implied warranty.
74 THE AUTHOR(S) DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
75 INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
76 EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY SPECIAL, INDIRECT OR
77 CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
78 DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
79 TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
80 PERFORMANCE OF THIS SOFTWARE.
84 <sect1><title>DESCRIPTION</title>
86 Fontconfig is a library designed to provide system-wide font configuration,
87 customization and application access.
90 <sect1><title>FUNCTIONAL OVERVIEW</title>
92 Fontconfig contains two essential modules, the configuration module which
93 builds an internal configuration from XML files and the matching module
94 which accepts font patterns and returns the nearest matching font.
96 <sect2><title>FONT CONFIGURATION</title>
98 The configuration module consists of the FcConfig datatype, libexpat and
99 FcConfigParse which walks over an XML tree and amends a configuration with
100 data found within. From an external perspective, configuration of the
101 library consists of generating a valid XML tree and feeding that to
102 FcConfigParse. The only other mechanism provided to applications for
103 changing the running configuration is to add fonts and directories to the
104 list of application-provided font files.
106 The intent is to make font configurations relatively static, and shared by
107 as many applications as possible. It is hoped that this will lead to more
108 stable font selection when passing names from one application to another.
109 XML was chosen as a configuration file format because it provides a format
110 which is easy for external agents to edit while retaining the correct
111 structure and syntax.
113 Font configuration is separate from font matching; applications needing to
114 do their own matching can access the available fonts from the library and
115 perform private matching. The intent is to permit applications to pick and
116 choose appropriate functionality from the library instead of forcing them to
117 choose between this library and a private configuration mechanism. The hope
118 is that this will ensure that configuration of fonts for all applications
119 can be centralized in one place. Centralizing font configuration will
120 simplify and regularize font installation and customization.
124 <title>FONT PROPERTIES</title>
126 While font patterns may contain essentially any properties, there are some
127 well known properties with associated types. Fontconfig uses some of these
128 properties for font matching and font completion. Others are provided as a
129 convenience for the application's rendering mechanism.
134 Property C Preprocessor Symbol Type Description
135 ----------------------------------------------------
136 family FC_FAMILY String Font family names
137 familylang FC_FAMILYLANG String Language corresponding to
139 style FC_STYLE String Font style. Overrides weight
141 stylelang FC_STYLELANG String Language corresponding to
143 fullname FC_FULLNAME String Font face full name where
144 different from family and
146 fullnamelang FC_FULLNAMELANG String Language corresponding to
148 slant FC_SLANT Int Italic, oblique or roman
149 weight FC_WEIGHT Int Light, medium, demibold,
151 size FC_SIZE Double Point size
152 width FC_WIDTH Int Condensed, normal or expanded
153 aspect FC_ASPECT Double Stretches glyphs horizontally
155 pixelsize FC_PIXEL_SIZE Double Pixel size
156 spacing FC_SPACING Int Proportional, dual-width,
157 monospace or charcell
158 foundry FC_FOUNDRY String Font foundry name
159 antialias FC_ANTIALIAS Bool Whether glyphs can be
161 hinting FC_HINTING Bool Whether the rasterizer should
163 hintstyle FC_HINT_STYLE Int Automatic hinting style
164 verticallayout FC_VERTICAL_LAYOUT Bool Use vertical layout
165 autohint FC_AUTOHINT Bool Use autohinter instead of
167 globaladvance FC_GLOBAL_ADVANCE Bool Use font global advance data (deprecated)
168 file FC_FILE String The filename holding the font
169 index FC_INDEX Int The index of the font within
171 ftface FC_FT_FACE FT_Face Use the specified FreeType
173 rasterizer FC_RASTERIZER String Which rasterizer is in use
174 outline FC_OUTLINE Bool Whether the glyphs are outlines
175 scalable FC_SCALABLE Bool Whether glyphs can be scaled
176 scale FC_SCALE Double Scale factor for point->pixel
178 dpi FC_DPI Double Target dots per inch
179 rgba FC_RGBA Int unknown, rgb, bgr, vrgb,
180 vbgr, none - subpixel geometry
181 lcdfilter FC_LCD_FILTER Int Type of LCD filter
182 minspace FC_MINSPACE Bool Eliminate leading from line
184 charset FC_CHARSET CharSet Unicode chars encoded by
186 lang FC_LANG LangSet Set of RFC-3066-style
187 languages this font supports
188 fontversion FC_FONTVERSION Int Version number of the font
189 capability FC_CAPABILITY String List of layout capabilities in
191 embolden FC_EMBOLDEN Bool Rasterizer should
192 synthetically embolden the font
193 namelang FC_NAMELANG String Language name to be used for the
194 default value of familylang,
195 stylelang and fullnamelang
199 <sect1><title>Datatypes</title>
201 Fontconfig uses abstract data types to hide internal implementation details
202 for most data structures. A few structures are exposed where appropriate.
204 <sect2><title>FcChar8, FcChar16, FcChar32, FcBool</title>
206 These are primitive data types; the FcChar* types hold precisely the number
207 of bits stated (if supported by the C implementation). FcBool holds
208 one of two C preprocessor symbols: FcFalse or FcTrue.
211 <sect2><title>FcMatrix</title>
213 An FcMatrix holds an affine transformation, usually used to reshape glyphs.
214 A small set of matrix operations are provided to manipulate these.
216 typedef struct _FcMatrix {
217 double xx, xy, yx, yy;
222 <sect2><title>FcCharSet</title>
224 An FcCharSet is an abstract type that holds the set of encoded Unicode chars
225 in a font. Operations to build and compare these sets are provided.
228 <sect2><title>FcLangSet</title>
230 An FcLangSet is an abstract type that holds the set of languages supported
231 by a font. Operations to build and compare these sets are provided. These
232 are computed for a font based on orthographic information built into the
233 fontconfig library. Fontconfig has orthographies for all of the ISO 639-1
234 languages except for MS, NA, PA, PS, QU, RN, RW, SD, SG, SN, SU and ZA. If
235 you have orthographic information for any of these languages, please submit
239 <sect2><title>FcLangResult</title>
241 An FcLangResult is an enumeration used to return the results of comparing
242 two language strings or FcLangSet objects. FcLangEqual means the
243 objects match language and territory. FcLangDifferentTerritory means
244 the objects match in language but differ in territory.
245 FcLangDifferentLang means the objects differ in language.
248 <sect2><title>FcType</title>
250 Tags the kind of data stored in an FcValue.
253 <sect2><title>FcValue</title>
255 An FcValue object holds a single value with one of a number of different
256 types. The 'type' tag indicates which member is valid.
258 typedef struct _FcValue {
275 Type Union member Datatype
276 --------------------------------
277 FcTypeVoid (none) (none)
279 FcTypeDouble d double
280 FcTypeString s FcChar8 *
282 FcTypeMatrix m FcMatrix *
283 FcTypeCharSet c FcCharSet *
284 FcTypeFTFace f void * (FT_Face)
285 FcTypeLangSet l FcLangSet *
289 <sect2><title>FcPattern</title>
291 holds a set of names with associated value lists; each name refers to a
292 property of a font. FcPatterns are used as inputs to the matching code as
293 well as holding information about specific fonts. Each property can hold
294 one or more values; conventionally all of the same type, although the
295 interface doesn't demand that.
298 <sect2><title>FcFontSet</title>
301 typedef struct _FcFontSet {
307 An FcFontSet contains a list of FcPatterns. Internally fontconfig uses this
308 data structure to hold sets of fonts. Externally, fontconfig returns the
309 results of listing fonts in this format. 'nfont' holds the number of
310 patterns in the 'fonts' array; 'sfont' is used to indicate the size of that
314 <sect2><title>FcStrSet, FcStrList</title>
316 FcStrSet holds a list of strings that can be appended to and enumerated.
317 Its unique characteristic is that the enumeration works even while strings
318 are appended during enumeration. FcStrList is used during enumeration to
319 safely and correctly walk the list of strings even while that list is edited
320 in the middle of enumeration.
323 <sect2><title>FcObjectSet</title>
326 typedef struct _FcObjectSet {
329 const char **objects;
332 holds a set of names and is used to specify which fields from fonts are
333 placed in the the list of returned patterns when listing fonts.
336 <sect2><title>FcObjectType</title>
339 typedef struct _FcObjectType {
344 marks the type of a pattern element generated when parsing font names.
345 Applications can add new object types so that font names may contain the new
349 <sect2><title>FcConstant</title>
352 typedef struct _FcConstant {
358 Provides for symbolic constants for new pattern elements. When 'name' is
359 seen in a font name, an 'object' element is created with value 'value'.
362 <sect2><title>FcBlanks</title>
364 holds a list of Unicode chars which are expected to be blank; unexpectedly
365 blank chars are assumed to be invalid and are elided from the charset
366 associated with the font.
369 <sect2><title>FcFileCache</title>
371 holds the per-user cache information for use while loading the font
372 database. This is built automatically for the current configuration when
373 that is loaded. Applications must always pass '0' when one is requested.
376 <sect2><title>FcConfig</title>
378 holds a complete configuration of the library; there is one default
379 configuration, other can be constructed from XML data structures. All
380 public entry points that need global data can take an optional FcConfig*
381 argument; passing 0 uses the default configuration. FcConfig objects hold two
382 sets of fonts, the first contains those specified by the configuration, the
383 second set holds those added by the application at run-time. Interfaces
384 that need to reference a particular set use one of the FcSetName enumerated
388 <sect2><title>FcSetName</title>
390 Specifies one of the two sets of fonts available in a configuration;
391 FcSetSystem for those fonts specified in the configuration and
392 FcSetApplication which holds fonts provided by the application.
395 <sect2><title>FcResult</title>
397 Used as a return type for functions manipulating FcPattern objects.
401 -----------------------------------------------------------
402 FcResultMatch Object exists with the specified ID
403 FcResultNoMatch Object doesn't exist at all
404 FcResultTypeMismatch Object exists, but the type doesn't match
405 FcResultNoId Object exists, but has fewer values
407 FcResultOutOfMemory malloc failed
411 <sect2><title>FcAtomic</title>
413 Used for locking access to configuration files. Provides a safe way to update
417 <sect2><title>FcCache</title>
419 Holds information about the fonts contained in a single directory. Normal
420 applications need not worry about this as caches for font access are
421 automatically managed by the library. Applications dealing with cache
422 management may want to use some of these objects in their work, however the
423 included 'fc-cache' program generally suffices for all of that.
427 <sect1><title>FUNCTIONS</title>
429 These are grouped by functionality, often using the main data type being
432 <sect2><title>Initialization</title>
434 These functions provide some control over how the library is initialized.
438 <sect2><title>FcPattern</title>
440 An FcPattern is an opaque type that holds both patterns to match against the
441 available fonts, as well as the information about each font.
446 <sect2><title>FcFontSet</title>
448 An FcFontSet simply holds a list of patterns; these are used to return the
449 results of listing available fonts.
453 <sect2><title>FcObjectSet</title>
455 An FcObjectSet holds a list of pattern property names; it is used to
456 indicate which properties are to be returned in the patterns from
461 <sect2><title>FreeType specific functions</title>
463 While the fontconfig library doesn't insist that FreeType be used as the
464 rasterization mechanism for fonts, it does provide some convenience
469 <sect2><title>FcValue</title>
471 FcValue is a structure containing a type tag and a union of all possible
472 datatypes. The tag is an enum of type
473 <emphasis>FcType</emphasis>
474 and is intended to provide a measure of run-time
475 typechecking, although that depends on careful programming.
479 <sect2><title>FcCharSet</title>
481 An FcCharSet is a boolean array indicating a set of Unicode chars. Those
482 associated with a font are marked constant and cannot be edited.
483 FcCharSets may be reference counted internally to reduce memory consumption;
484 this may be visible to applications as the result of FcCharSetCopy may
485 return it's argument, and that CharSet may remain unmodifiable.
489 <sect2><title>FcLangSet</title>
491 An FcLangSet is a set of language names (each of which include language and
492 an optional territory). They are used when selecting fonts to indicate which
493 languages the fonts need to support. Each font is marked, using language
494 orthography information built into fontconfig, with the set of supported
499 <sect2><title>FcMatrix</title>
501 FcMatrix structures hold an affine transformation in matrix form.
505 <sect2><title>FcConfig</title>
507 An FcConfig object holds the internal representation of a configuration.
508 There is a default configuration which applications may use by passing 0 to
509 any function using the data within an FcConfig.
513 <sect2><title>FcObjectType</title>
515 Provides for application-specified font name object types so that new
516 pattern elements can be generated from font names.
520 <sect2><title>FcConstant</title>
522 Provides for application-specified symbolic constants for font names.
526 <sect2><title>FcBlanks</title>
528 An FcBlanks object holds a list of Unicode chars which are expected to
529 be blank when drawn. When scanning new fonts, any glyphs which are
530 empty and not in this list will be assumed to be broken and not placed in
531 the FcCharSet associated with the font. This provides a significantly more
532 accurate CharSet for applications.
536 <sect2><title>FcAtomic</title>
538 These functions provide a safe way to update configuration files, allowing ongoing
539 reading of the old configuration file while locked for writing and ensuring that a
540 consistent and complete version of the configuration file is always available.
544 <sect2><title>File and Directory routines</title>
546 These routines work with font files and directories, including font
547 directory cache files.
552 <sect2><title>FcCache routines</title>
554 These routines work with font directory caches, accessing their contents in
555 limited ways. It is not expected that normal applications will need to use
560 <sect2><title>FcStrSet and FcStrList</title>
562 A data structure for enumerating strings, used to list directories while
563 scanning the configuration as directories are added while scanning.
567 <sect2><title>String utilities</title>
569 Fontconfig manipulates many UTF-8 strings represented with the FcChar8 type.
570 These functions are exposed to help applications deal with these UTF-8
571 strings in a locale-insensitive manner.