fontconfig-devel.sgml revision 2c393a42
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 fcfreetype SYSTEM "fcfreetype.sgml"> 12<!ENTITY fcinit SYSTEM "fcinit.sgml"> 13<!ENTITY fclangset SYSTEM "fclangset.sgml"> 14<!ENTITY fcmatrix SYSTEM "fcmatrix.sgml"> 15<!ENTITY fcobjectset SYSTEM "fcobjectset.sgml"> 16<!ENTITY fcobjecttype SYSTEM "fcobjecttype.sgml"> 17<!ENTITY fcpattern SYSTEM "fcpattern.sgml"> 18<!ENTITY fcstring SYSTEM "fcstring.sgml"> 19<!ENTITY fcstrset SYSTEM "fcstrset.sgml"> 20<!ENTITY fcvalue SYSTEM "fcvalue.sgml"> 21<!ENTITY version SYSTEM "version.sgml"> 22]> 23<!-- 24 $Id: fontconfig-devel.sgml,v 1.1.1.1 2008/07/30 01:24:15 mrg Exp $ 25 26 Copyright © 2003 Keith Packard 27 28 Permission to use, copy, modify, distribute, and sell this software and its 29 documentation for any purpose is hereby granted without fee, provided that 30 the above copyright notice appear in all copies and that both that 31 copyright notice and this permission notice appear in supporting 32 documentation, and that the name of Keith Packard not be used in 33 advertising or publicity pertaining to distribution of the software without 34 specific, written prior permission. Keith Packard makes no 35 representations about the suitability of this software for any purpose. It 36 is provided "as is" without express or implied warranty. 37 38 KEITH PACKARD DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, 39 INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO 40 EVENT SHALL KEITH PACKARD BE LIABLE FOR ANY SPECIAL, INDIRECT OR 41 CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, 42 DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER 43 TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 44 PERFORMANCE OF THIS SOFTWARE. 45--> 46<article> 47 <title>Fontconfig Developers Reference, Version &version; </title> 48 <artheader> 49 <author> 50 <firstname>Keith</firstname> 51 <surname>Packard</surname> 52 <affiliation><orgname> 53 HP Cambridge Research Lab 54 </orgname></affiliation> 55 </author> 56 <authorinitials>KRP</authorinitials> 57 <productname>Fontconfig</productname> 58 <productnumber>&version;</productnumber> 59 <LegalNotice> 60 <simpara> 61Copyright © 2002 Keith Packard 62 </simpara><simpara> 63Permission to use, copy, modify, distribute, and sell this software and its 64documentation for any purpose is hereby granted without fee, provided that 65the above copyright notice appear in all copies and that both that 66copyright notice and this permission notice appear in supporting 67documentation, and that the name of Keith Packard not be used in 68advertising or publicity pertaining to distribution of the software without 69specific, written prior permission. Keith Packard makes no 70representations about the suitability of this software for any purpose. It 71is provided "as is" without express or implied warranty. 72 </simpara><simpara> 73KEITH PACKARD DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, 74INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO 75EVENT SHALL KEITH PACKARD BE LIABLE FOR ANY SPECIAL, INDIRECT OR 76CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, 77DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER 78TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 79PERFORMANCE OF THIS SOFTWARE. 80 </simpara> 81 </LegalNotice> 82 </artheader> 83<sect1><title>DESCRIPTION</title> 84 <para> 85Fontconfig is a library designed to provide system-wide font configuration, 86customization and application access. 87 </para> 88</sect1> 89<sect1><title>FUNCTIONAL OVERVIEW</title> 90 <para> 91Fontconfig contains two essential modules, the configuration module which 92builds an internal configuration from XML files and the matching module 93which accepts font patterns and returns the nearest matching font. 94 </para> 95 <sect2><title>FONT CONFIGURATION</title> 96 <para> 97The configuration module consists of the FcConfig datatype, libexpat and 98FcConfigParse which walks over an XML tree and ammends a configuration with 99data found within. From an external perspective, configuration of the 100library consists of generating a valid XML tree and feeding that to 101FcConfigParse. The only other mechanism provided to applications for 102changing the running configuration is to add fonts and directories to the 103list of application-provided font files. 104 </para><para> 105The intent is to make font configurations relatively static, and shared by 106as many applications as possible. It is hoped that this will lead to more 107stable font selection when passing names from one application to another. 108XML was chosen as a configuration file format because it provides a format 109which is easy for external agents to edit while retaining the correct 110structure and syntax. 111 </para><para> 112Font configuration is separate from font matching; applications needing to 113do their own matching can access the available fonts from the library and 114perform private matching. The intent is to permit applications to pick and 115choose appropriate functionality from the library instead of forcing them to 116choose between this library and a private configuration mechanism. The hope 117is that this will ensure that configuration of fonts for all applications 118can be centralized in one place. Centralizing font configuration will 119simplify and regularize font installation and customization. 120 </para> 121 </sect2> 122 <sect2> 123 <title>FONT PROPERTIES</title> 124 <para> 125While font patterns may contain essentially any properties, there are some 126well known properties with associated types. Fontconfig uses some of these 127properties for font matching and font completion. Others are provided as a 128convenience for the applications rendering mechanism. 129 </para> 130 <programlisting> 131 Property Definitions 132 133 Property CPP Symbol Type Description 134 ---------------------------------------------------- 135 family FC_FAMILY String Font family names 136 familylang FC_FAMILYLANG String Language cooresponding to 137 each family name 138 style FC_STYLE String Font style. Overrides weight 139 and slant 140 stylelang FC_STYLELANG String Language cooresponding to 141 each style name 142 fullname FC_FULLNAME String Font face full name where 143 different from family and 144 family + style 145 fullnamelang FC_FULLNAMELANG String Language cooresponding to 146 each fullname 147 slant FC_SLANT Int Italic, oblique or roman 148 weight FC_WEIGHT Int Light, medium, demibold, 149 bold or black 150 size FC_SIZE Double Point size 151 width FC_WIDTH Int Condensed, normal or expanded 152 aspect FC_ASPECT Double Stretches glyphs horizontally 153 before hinting 154 pixelsize FC_PIXEL_SIZE Double Pixel size 155 spacing FC_SPACING Int Proportional, dual-width, 156 monospace or charcell 157 foundry FC_FOUNDRY String Font foundry name 158 antialias FC_ANTIALIAS Bool Whether glyphs can be 159 antialiased 160 hinting FC_HINTING Bool Whether the rasterizer should 161 use hinting 162 hintstyle FC_HINT_STYLE Int Automatic hinting style 163 verticallayout FC_VERTICAL_LAYOUT Bool Use vertical layout 164 autohint FC_AUTOHINT Bool Use autohinter instead of 165 normal hinter 166 globaladvance FC_GLOBAL_ADVANCE Bool Use font global advance data 167 file FC_FILE String The filename holding the font 168 index FC_INDEX Int The index of the font within 169 the file 170 ftface FC_FT_FACE FT_Face Use the specified FreeType 171 face object 172 rasterizer FC_RASTERIZER String Which rasterizer is in use 173 outline FC_OUTLINE Bool Whether the glyphs are outlines 174 scalable FC_SCALABLE Bool Whether glyphs can be scaled 175 scale FC_SCALE Double Scale factor for point->pixel 176 conversions 177 dpi FC_DPI Double Target dots per inch 178 rgba FC_RGBA Int unknown, rgb, bgr, vrgb, 179 vbgr, none - subpixel geometry 180 lcdfilter FC_LCD_FILTER Int Type of LCD filter 181 minspace FC_MINSPACE Bool Eliminate leading from line 182 spacing 183 charset FC_CHARSET CharSet Unicode chars encoded by 184 the font 185 lang FC_LANG LangSet Set of RFC-3066-style 186 languages this font supports 187 fontversion FC_FONTVERSION Int Version number of the font 188 capability FC_CAPABILITY String List of layout capabilities in 189 the font 190 embolden FC_EMBOLDEN Bool Rasterizer should 191 synthetically embolden the font 192 </programlisting> 193 </sect2> 194</sect1> 195<sect1><title>Datatypes</title> 196 <para> 197Fontconfig uses abstract datatypes to hide internal implementation details 198for most data structures. A few structures are exposed where appropriate. 199 </para> 200 <sect2><title>FcChar8, FcChar16, FcChar32, FcBool</title> 201 <para> 202These are primitive datatypes; the FcChar* types hold precisely the number 203of bits stated (if supported by the C implementation). FcBool holds 204one of two CPP symbols: FcFalse or FcTrue. 205 </para> 206 </sect2> 207 <sect2><title>FcMatrix</title> 208 <para> 209An FcMatrix holds an affine transformation, usually used to reshape glyphs. 210A small set of matrix operations are provided to manipulate these. 211 <programlisting> 212 typedef struct _FcMatrix { 213 double xx, xy, yx, yy; 214 } FcMatrix; 215 </programlisting> 216 </para> 217 </sect2> 218 <sect2><title>FcCharSet</title> 219 <para> 220An FcCharSet is an abstract type that holds the set of encoded unicode chars 221in a font. Operations to build and compare these sets are provided. 222 </para> 223 </sect2> 224 <sect2><title>FcLangSet</title> 225 <para> 226An FcLangSet is an abstract type that holds the set of languages supported 227by a font. Operations to build and compare these sets are provided. These 228are computed for a font based on orthographic information built into the 229fontconfig library. Fontconfig has orthographies for all of the ISO 639-1 230languages except for MS, NA, PA, PS, QU, RN, RW, SD, SG, SN, SU and ZA. If 231you have orthographic information for any of these languages, please submit 232them. 233 </para> 234 </sect2> 235 <sect2><title>FcLangResult</title> 236 <para> 237An FcLangResult is an enumeration used to return the results of comparing 238two language strings or FcLangSet objects. FcLangEqual means the 239objects match language and territory. FcLangDifferentTerritory means 240the objects match in language but differ in territory. 241FcLangDifferentLang means the objects differ in language. 242 </para> 243 </sect2> 244 <sect2><title>FcType</title> 245 <para> 246Tags the kind of data stored in an FcValue. 247 </para> 248 </sect2> 249 <sect2><title>FcValue</title> 250 <para> 251An FcValue object holds a single value with one of a number of different 252types. The 'type' tag indicates which member is valid. 253 <programlisting> 254 typedef struct _FcValue { 255 FcType type; 256 union { 257 const FcChar8 *s; 258 int i; 259 FcBool b; 260 double d; 261 const FcMatrix *m; 262 const FcCharSet *c; 263 void *f; 264 const FcLangSet *l; 265 } u; 266 } FcValue; 267 </programlisting> 268 <programlisting> 269 FcValue Members 270 271 Type Union member Datatype 272 -------------------------------- 273 FcTypeVoid (none) (none) 274 FcTypeInteger i int 275 FcTypeDouble d double 276 FcTypeString s FcChar8 * 277 FcTypeBool b b 278 FcTypeMatrix m FcMatrix * 279 FcTypeCharSet c FcCharSet * 280 FcTypeFTFace f void * (FT_Face) 281 FcTypeLangSet l FcLangSet * 282 </programlisting> 283 </para> 284 </sect2> 285 <sect2><title>FcPattern</title> 286 <para> 287holds a set of names with associated value lists; each name refers to a 288property of a font. FcPatterns are used as inputs to the matching code as 289well as holding information about specific fonts. Each property can hold 290one or more values; conventionally all of the same type, although the 291interface doesn't demand that. 292 </para> 293 </sect2> 294 <sect2><title>FcFontSet</title> 295 <para> 296 <programlisting> 297 typedef struct _FcFontSet { 298 int nfont; 299 int sfont; 300 FcPattern **fonts; 301 } FcFontSet; 302 </programlisting> 303An FcFontSet contains a list of FcPatterns. Internally fontconfig uses this 304data structure to hold sets of fonts. Externally, fontconfig returns the 305results of listing fonts in this format. 'nfont' holds the number of 306patterns in the 'fonts' array; 'sfont' is used to indicate the size of that 307array. 308 </para> 309 </sect2> 310 <sect2><title>FcStrSet, FcStrList</title> 311 <para> 312FcStrSet holds a list of strings that can be appended to and enumerated. 313Its unique characteristic is that the enumeration works even while strings 314are appended during enumeration. FcStrList is used during enumeration to 315safely and correctly walk the list of strings even while that list is edited 316in the middle of enumeration. 317 </para> 318 </sect2> 319 <sect2><title>FcObjectSet</title> 320 <para> 321 <programlisting> 322 typedef struct _FcObjectSet { 323 int nobject; 324 int sobject; 325 const char **objects; 326 } FcObjectSet; 327 </programlisting> 328holds a set of names and is used to specify which fields from fonts are 329placed in the the list of returned patterns when listing fonts. 330 </para> 331 </sect2> 332 <sect2><title>FcObjectType</title> 333 <para> 334 <programlisting> 335 typedef struct _FcObjectType { 336 const char *object; 337 FcType type; 338 } FcObjectType; 339 </programlisting> 340marks the type of a pattern element generated when parsing font names. 341Applications can add new object types so that font names may contain the new 342elements. 343 </para> 344 </sect2> 345 <sect2><title>FcConstant</title> 346 <para> 347 <programlisting> 348 typedef struct _FcConstant { 349 const FcChar8 *name; 350 const char *object; 351 int value; 352 } FcConstant; 353 </programlisting> 354Provides for symbolic constants for new pattern elements. When 'name' is 355seen in a font name, an 'object' element is created with value 'value'. 356 </para> 357 </sect2> 358 <sect2><title>FcBlanks</title> 359 <para> 360holds a list of Unicode chars which are expected to be blank; unexpectedly 361blank chars are assumed to be invalid and are elided from the charset 362associated with the font. 363 </para> 364 </sect2> 365 <sect2><title>FcFileCache</title> 366 <para> 367holds the per-user cache information for use while loading the font 368database. This is built automatically for the current configuration when 369that is loaded. Applications must always pass '0' when one is requested. 370 </para> 371 </sect2> 372 <sect2><title>FcConfig</title> 373 <para> 374holds a complete configuration of the library; there is one default 375configuration, other can be constructed from XML data structures. All 376public entry points that need global data can take an optional FcConfig* 377argument; passing 0 uses the default configuration. FcConfig objects hold two 378sets of fonts, the first contains those specified by the configuration, the 379second set holds those added by the application at run-time. Interfaces 380that need to reference a particulat set use one of the FcSetName enumerated 381values. 382 </para> 383 </sect2> 384 <sect2><title>FcSetName</title> 385 <para> 386Specifies one of the two sets of fonts available in a configuration; 387FcSetSystem for those fonts specified in the configuration and 388FcSetApplication which holds fonts provided by the application. 389 </para> 390 </sect2> 391 <sect2><title>FcResult</title> 392 <para> 393Used as a return type for functions manipulating FcPattern objects. 394 <programlisting> 395 FcResult Values 396 Result Code Meaning 397 ----------------------------------------------------------- 398 FcResultMatch Object exists with the specified ID 399 FcResultNoMatch Object doesn't exist at all 400 FcResultTypeMismatch Object exists, but the type doesn't match 401 FcResultNoId Object exists, but has fewer values 402 than specified 403 FcResultOutOfMemory Malloc failed 404 </programlisting> 405 </para> 406 </sect2> 407 <sect2><title>FcAtomic</title> 408 <para> 409Used for locking access to config files. Provides a safe way to update 410configuration files. 411 </para> 412 </sect2> 413 <sect2><title>FcCache</title> 414 <para> 415Holds information about the fonts contained in a single directory. Normal 416applications need not worry about this as caches for font access are 417automatically managed by the library. Applications dealing with cache 418management may want to use some of these objects in their work, however the 419included 'fc-cache' program generally suffices for all of that. 420 </para> 421 </sect2> 422</sect1> 423<sect1><title>FUNCTIONS</title> 424 <para> 425These are grouped by functionality, often using the main datatype being 426manipulated. 427 </para> 428 <sect2><title>Initialization</title> 429 <para> 430These functions provide some control over how the library is initialized. 431 </para> 432 &fcinit; 433 </sect2> 434 <sect2><title>FcPattern</title> 435 <para> 436An FcPattern is an opaque type that holds both patterns to match against the 437available fonts, as well as the information about each font. 438 </para> 439 &fcpattern; 440 </sect2> 441 <sect2><title>FcFontSet</title> 442 <para> 443An FcFontSet simply holds a list of patterns; these are used to return the 444results of listing available fonts. 445 </para> 446 &fcfontset; 447 </sect2> 448 <sect2><title>FcObjectSet</title> 449 <para> 450An FcObjectSet holds a list of pattern property names; it is used to 451indiciate which properties are to be returned in the patterns from 452FcFontList. 453 </para> 454 &fcobjectset; 455 </sect2> 456 <sect2><title>FreeType specific functions</title> 457 <para> 458While the fontconfig library doesn't insist that FreeType be used as the 459rasterization mechanism for fonts, it does provide some convenience 460functions. 461 </para> 462 &fcfreetype; 463 </sect2> 464 <sect2><title>FcValue</title> 465 <para> 466FcValue is a structure containing a type tag and a union of all possible 467datatypes. The tag is an enum of type 468<emphasis>FcType</emphasis> 469and is intended to provide a measure of run-time 470typechecking, although that depends on careful programming. 471 </para> 472 &fcvalue; 473 </sect2> 474 <sect2><title>FcCharSet</title> 475 <para> 476An FcCharSet is a boolean array indicating a set of unicode chars. Those 477associated with a font are marked constant and cannot be edited. 478FcCharSets may be reference counted internally to reduce memory consumption; 479this may be visible to applications as the result of FcCharSetCopy may 480return it's argument, and that CharSet may remain unmodifiable. 481 </para> 482 &fccharset; 483 </sect2> 484 <sect2><title>FcLangSet</title> 485 <para> 486An FcLangSet is a set of language names (each of which include language and 487an optional territory). They are used when selecting fonts to indicate which 488languages the fonts need to support. Each font is marked, using language 489orthography information built into fontconfig, with the set of supported 490languages. 491 </para> 492 &fclangset; 493 </sect2> 494 <sect2><title>FcMatrix</title> 495 <para> 496FcMatrix structures hold an affine transformation in matrix form. 497 </para> 498 &fcmatrix; 499 </sect2> 500 <sect2><title>FcConfig</title> 501 <para> 502An FcConfig object holds the internal representation of a configuration. 503There is a default configuration which applications may use by passing 0 to 504any function using the data within an FcConfig. 505 </para> 506 &fcconfig; 507 </sect2> 508 <sect2><title>FcObjectType</title> 509 <para> 510Provides for applcation-specified font name object types so that new 511pattern elements can be generated from font names. 512 </para> 513 &fcobjecttype; 514 </sect2> 515 <sect2><title>FcConstant</title> 516 <para> 517Provides for application-specified symbolic constants for font names. 518 </para> 519 &fcconstant; 520 </sect2> 521 <sect2><title>FcBlanks</title> 522 <para> 523An FcBlanks object holds a list of Unicode chars which are expected to 524be blank when drawn. When scanning new fonts, any glyphs which are 525empty and not in this list will be assumed to be broken and not placed in 526the FcCharSet associated with the font. This provides a significantly more 527accurate CharSet for applications. 528 </para> 529 &fcblanks; 530 </sect2> 531 <sect2><title>FcAtomic</title> 532 <para> 533These functions provide a safe way to update config files, allowing ongoing 534reading of the old config file while locked for writing and ensuring that a 535consistent and complete version of the config file is always available. 536 </para> 537 &fcatomic; 538 </sect2> 539 <sect2><title>File and Directory routines</title> 540 <para> 541These routines work with font files and directories, including font 542directory cache files. 543 </para> 544 &fcfile; 545 &fcdircache; 546 </sect2> 547 <sect2><title>FcCache routines</title> 548 <para> 549These routines work with font directory caches, accessing their contents in 550limited ways. It is not expected that normal applications will need to use 551these functions. 552 </para> 553 &fccache; 554 </sect2> 555 <sect2><title>FcStrSet and FcStrList</title> 556 <para> 557A data structure for enumerating strings, used to list directories while 558scanning the configuration as directories are added while scanning. 559 </para> 560 &fcstrset; 561 </sect2> 562 <sect2><title>String utilities</title> 563 <para> 564Fontconfig manipulates many UTF-8 strings represented with the FcChar8 type. 565These functions are exposed to help applications deal with these UTF-8 566strings in a locale-insensitive manner. 567 </para> 568 &fcstring; 569 </sect2> 570</sect1> 571</article> 572