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 (deprecated)
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 fontfeatures FC_FONT_FEATURES String List of extra feature tags in
194 OpenType to be enabled
195 namelang FC_NAMELANG String Language name to be used for the
196 default value of familylang,
197 stylelang and fullnamelang
198 prgname FC_PRGNAME String Name of the running program
199 hash FC_HASH String SHA256 hash value of the font data
200 with "sha256:" prefix.
201 postscriptname FC_POSTSCRIPT_NAME String Font name in PostScript
205 <sect1><title>Datatypes</title>
207 Fontconfig uses abstract data types to hide internal implementation details
208 for most data structures. A few structures are exposed where appropriate.
210 <sect2><title>FcChar8, FcChar16, FcChar32, FcBool</title>
212 These are primitive data types; the FcChar* types hold precisely the number
213 of bits stated (if supported by the C implementation). FcBool holds
214 one of two C preprocessor symbols: FcFalse or FcTrue.
217 <sect2><title>FcMatrix</title>
219 An FcMatrix holds an affine transformation, usually used to reshape glyphs.
220 A small set of matrix operations are provided to manipulate these.
222 typedef struct _FcMatrix {
223 double xx, xy, yx, yy;
228 <sect2><title>FcCharSet</title>
230 An FcCharSet is an abstract type that holds the set of encoded Unicode chars
231 in a font. Operations to build and compare these sets are provided.
234 <sect2><title>FcLangSet</title>
236 An FcLangSet is an abstract type that holds the set of languages supported
237 by a font. Operations to build and compare these sets are provided. These
238 are computed for a font based on orthographic information built into the
239 fontconfig library. Fontconfig has orthographies for all of the ISO 639-1
240 languages except for MS, NA, PA, PS, QU, RN, RW, SD, SG, SN, SU and ZA. If
241 you have orthographic information for any of these languages, please submit
245 <sect2><title>FcLangResult</title>
247 An FcLangResult is an enumeration used to return the results of comparing
248 two language strings or FcLangSet objects. FcLangEqual means the
249 objects match language and territory. FcLangDifferentTerritory means
250 the objects match in language but differ in territory.
251 FcLangDifferentLang means the objects differ in language.
254 <sect2><title>FcType</title>
256 Tags the kind of data stored in an FcValue.
259 <sect2><title>FcValue</title>
261 An FcValue object holds a single value with one of a number of different
262 types. The 'type' tag indicates which member is valid.
264 typedef struct _FcValue {
281 Type Union member Datatype
282 --------------------------------
283 FcTypeVoid (none) (none)
285 FcTypeDouble d double
286 FcTypeString s FcChar8 *
288 FcTypeMatrix m FcMatrix *
289 FcTypeCharSet c FcCharSet *
290 FcTypeFTFace f void * (FT_Face)
291 FcTypeLangSet l FcLangSet *
295 <sect2><title>FcPattern</title>
297 holds a set of names with associated value lists; each name refers to a
298 property of a font. FcPatterns are used as inputs to the matching code as
299 well as holding information about specific fonts. Each property can hold
300 one or more values; conventionally all of the same type, although the
301 interface doesn't demand that.
304 <sect2><title>FcFontSet</title>
307 typedef struct _FcFontSet {
313 An FcFontSet contains a list of FcPatterns. Internally fontconfig uses this
314 data structure to hold sets of fonts. Externally, fontconfig returns the
315 results of listing fonts in this format. 'nfont' holds the number of
316 patterns in the 'fonts' array; 'sfont' is used to indicate the size of that
320 <sect2><title>FcStrSet, FcStrList</title>
322 FcStrSet holds a list of strings that can be appended to and enumerated.
323 Its unique characteristic is that the enumeration works even while strings
324 are appended during enumeration. FcStrList is used during enumeration to
325 safely and correctly walk the list of strings even while that list is edited
326 in the middle of enumeration.
329 <sect2><title>FcObjectSet</title>
332 typedef struct _FcObjectSet {
335 const char **objects;
338 holds a set of names and is used to specify which fields from fonts are
339 placed in the the list of returned patterns when listing fonts.
342 <sect2><title>FcObjectType</title>
345 typedef struct _FcObjectType {
350 marks the type of a pattern element generated when parsing font names.
351 Applications can add new object types so that font names may contain the new
355 <sect2><title>FcConstant</title>
358 typedef struct _FcConstant {
364 Provides for symbolic constants for new pattern elements. When 'name' is
365 seen in a font name, an 'object' element is created with value 'value'.
368 <sect2><title>FcBlanks</title>
370 holds a list of Unicode chars which are expected to be blank; unexpectedly
371 blank chars are assumed to be invalid and are elided from the charset
372 associated with the font.
375 <sect2><title>FcFileCache</title>
377 holds the per-user cache information for use while loading the font
378 database. This is built automatically for the current configuration when
379 that is loaded. Applications must always pass '0' when one is requested.
382 <sect2><title>FcConfig</title>
384 holds a complete configuration of the library; there is one default
385 configuration, other can be constructed from XML data structures. All
386 public entry points that need global data can take an optional FcConfig*
387 argument; passing 0 uses the default configuration. FcConfig objects hold two
388 sets of fonts, the first contains those specified by the configuration, the
389 second set holds those added by the application at run-time. Interfaces
390 that need to reference a particular set use one of the FcSetName enumerated
394 <sect2><title>FcSetName</title>
396 Specifies one of the two sets of fonts available in a configuration;
397 FcSetSystem for those fonts specified in the configuration and
398 FcSetApplication which holds fonts provided by the application.
401 <sect2><title>FcResult</title>
403 Used as a return type for functions manipulating FcPattern objects.
407 -----------------------------------------------------------
408 FcResultMatch Object exists with the specified ID
409 FcResultNoMatch Object doesn't exist at all
410 FcResultTypeMismatch Object exists, but the type doesn't match
411 FcResultNoId Object exists, but has fewer values
413 FcResultOutOfMemory malloc failed
417 <sect2><title>FcAtomic</title>
419 Used for locking access to configuration files. Provides a safe way to update
423 <sect2><title>FcCache</title>
425 Holds information about the fonts contained in a single directory. Normal
426 applications need not worry about this as caches for font access are
427 automatically managed by the library. Applications dealing with cache
428 management may want to use some of these objects in their work, however the
429 included 'fc-cache' program generally suffices for all of that.
433 <sect1><title>FUNCTIONS</title>
435 These are grouped by functionality, often using the main data type being
438 <sect2><title>Initialization</title>
440 These functions provide some control over how the library is initialized.
444 <sect2><title>FcPattern</title>
446 An FcPattern is an opaque type that holds both patterns to match against the
447 available fonts, as well as the information about each font.
452 <sect2><title>FcFontSet</title>
454 An FcFontSet simply holds a list of patterns; these are used to return the
455 results of listing available fonts.
459 <sect2><title>FcObjectSet</title>
461 An FcObjectSet holds a list of pattern property names; it is used to
462 indicate which properties are to be returned in the patterns from
467 <sect2><title>FreeType specific functions</title>
469 While the fontconfig library doesn't insist that FreeType be used as the
470 rasterization mechanism for fonts, it does provide some convenience
475 <sect2><title>FcValue</title>
477 FcValue is a structure containing a type tag and a union of all possible
478 datatypes. The tag is an enum of type
479 <emphasis>FcType</emphasis>
480 and is intended to provide a measure of run-time
481 typechecking, although that depends on careful programming.
485 <sect2><title>FcCharSet</title>
487 An FcCharSet is a boolean array indicating a set of Unicode chars. Those
488 associated with a font are marked constant and cannot be edited.
489 FcCharSets may be reference counted internally to reduce memory consumption;
490 this may be visible to applications as the result of FcCharSetCopy may
491 return it's argument, and that CharSet may remain unmodifiable.
495 <sect2><title>FcLangSet</title>
497 An FcLangSet is a set of language names (each of which include language and
498 an optional territory). They are used when selecting fonts to indicate which
499 languages the fonts need to support. Each font is marked, using language
500 orthography information built into fontconfig, with the set of supported
505 <sect2><title>FcMatrix</title>
507 FcMatrix structures hold an affine transformation in matrix form.
511 <sect2><title>FcConfig</title>
513 An FcConfig object holds the internal representation of a configuration.
514 There is a default configuration which applications may use by passing 0 to
515 any function using the data within an FcConfig.
519 <sect2><title>FcObjectType</title>
521 Provides for application-specified font name object types so that new
522 pattern elements can be generated from font names.
526 <sect2><title>FcConstant</title>
528 Provides for application-specified symbolic constants for font names.
532 <sect2><title>FcBlanks</title>
534 An FcBlanks object holds a list of Unicode chars which are expected to
535 be blank when drawn. When scanning new fonts, any glyphs which are
536 empty and not in this list will be assumed to be broken and not placed in
537 the FcCharSet associated with the font. This provides a significantly more
538 accurate CharSet for applications.
542 <sect2><title>FcAtomic</title>
544 These functions provide a safe way to update configuration files, allowing ongoing
545 reading of the old configuration file while locked for writing and ensuring that a
546 consistent and complete version of the configuration file is always available.
550 <sect2><title>File and Directory routines</title>
552 These routines work with font files and directories, including font
553 directory cache files.
558 <sect2><title>FcCache routines</title>
560 These routines work with font directory caches, accessing their contents in
561 limited ways. It is not expected that normal applications will need to use
566 <sect2><title>FcStrSet and FcStrList</title>
568 A data structure for enumerating strings, used to list directories while
569 scanning the configuration as directories are added while scanning.
573 <sect2><title>String utilities</title>
575 Fontconfig manipulates many UTF-8 strings represented with the FcChar8 type.
576 These functions are exposed to help applications deal with these UTF-8
577 strings in a locale-insensitive manner.