doc/fontconfig-devel.sgml

   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     fontconfig/doc/local-fontconfig-devel.sgml
  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     THE AUTHOR(S) DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
  39     INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
  40     EVENT SHALL THE AUTHOR(S) 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>
  61 Copyright © 2002 Keith Packard
  62                         </simpara><simpara>
  63 Permission to use, copy, modify, distribute, and sell this software and its
  64 documentation for any purpose is hereby granted without fee, provided that
  65 the above copyright notice appear in all copies and that both that
  66 copyright notice and this permission notice appear in supporting
  67 documentation, and that the name of Keith Packard not be used in
  68 advertising or publicity pertaining to distribution of the software without
  69 specific, written prior permission.  Keith Packard makes no
  70 representations about the suitability of this software for any purpose.  It
  71 is provided "as is" without express or implied warranty.
  72                         </simpara><simpara>
  73 THE AUTHOR(S) DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
  74 INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
  75 EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY SPECIAL, INDIRECT OR
  76 CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
  77 DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
  78 TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  79 PERFORMANCE OF THIS SOFTWARE.
  80                         </simpara>
  81                 </LegalNotice>
  82         </artheader>
  83 <sect1><title>DESCRIPTION</title>
  84   <para>
  85 Fontconfig is a library designed to provide system-wide font configuration,
  86 customization and application access.
  87   </para>
  88 </sect1>
  89 <sect1><title>FUNCTIONAL OVERVIEW</title>
  90   <para>
  91 Fontconfig contains two essential modules, the configuration module which
  92 builds an internal configuration from XML files and the matching module
  93 which accepts font patterns and returns the nearest matching font.
  94   </para>
  95   <sect2><title>FONT CONFIGURATION</title>
  96     <para>
  97 The configuration module consists of the FcConfig datatype, libexpat and
  98 FcConfigParse which walks over an XML tree and ammends a configuration with
  99 data found within.  From an external perspective, configuration of the
 100 library consists of generating a valid XML tree and feeding that to
 101 FcConfigParse.  The only other mechanism provided to applications for
 102 changing the running configuration is to add fonts and directories to the
 103 list of application-provided font files.
 104     </para><para>
 105 The intent is to make font configurations relatively static, and shared by
 106 as many applications as possible.  It is hoped that this will lead to more
 107 stable font selection when passing names from one application to another.
 108 XML was chosen as a configuration file format because it provides a format
 109 which is easy for external agents to edit while retaining the correct
 110 structure and syntax.
 111     </para><para>
 112 Font configuration is separate from font matching; applications needing to
 113 do their own matching can access the available fonts from the library and
 114 perform private matching.  The intent is to permit applications to pick and
 115 choose appropriate functionality from the library instead of forcing them to
 116 choose between this library and a private configuration mechanism.  The hope
 117 is that this will ensure that configuration of fonts for all applications
 118 can be centralized in one place.  Centralizing font configuration will
 119 simplify and regularize font installation and customization.
 120     </para>
 121   </sect2>
 122   <sect2>
 123     <title>FONT PROPERTIES</title>
 124     <para>
 125 While font patterns may contain essentially any properties, there are some
 126 well known properties with associated types.  Fontconfig uses some of these
 127 properties for font matching and font completion.  Others are provided as a
 128 convenience 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>
 197 Fontconfig uses abstract datatypes to hide internal implementation details
 198 for most data structures.  A few structures are exposed where appropriate.
 199   </para>
 200   <sect2><title>FcChar8, FcChar16, FcChar32, FcBool</title>
 201     <para>
 202 These are primitive datatypes; the FcChar* types hold precisely the number
 203 of bits stated (if supported by the C implementation).  FcBool holds
 204 one of two CPP symbols: FcFalse or FcTrue.
 205     </para>
 206   </sect2>
 207   <sect2><title>FcMatrix</title>
 208     <para>
 209 An FcMatrix holds an affine transformation, usually used to reshape glyphs.
 210 A 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>
 220 An FcCharSet is an abstract type that holds the set of encoded unicode chars
 221 in a font.  Operations to build and compare these sets are provided.
 222     </para>
 223   </sect2>
 224   <sect2><title>FcLangSet</title>
 225     <para>
 226 An FcLangSet is an abstract type that holds the set of languages supported
 227 by a font.  Operations to build and compare these sets are provided. These
 228 are computed for a font based on orthographic information built into the
 229 fontconfig library. Fontconfig has orthographies for all of the ISO 639-1
 230 languages except for MS, NA, PA, PS, QU, RN, RW, SD, SG, SN, SU and ZA. If
 231 you have orthographic information for any of these languages, please submit
 232 them.
 233     </para>
 234   </sect2>
 235   <sect2><title>FcLangResult</title>
 236     <para>
 237 An FcLangResult is an enumeration used to return the results of comparing
 238 two language strings or FcLangSet objects. FcLangEqual means the
 239 objects match language and territory. FcLangDifferentTerritory means
 240 the objects match in language but differ in territory.
 241 FcLangDifferentLang means the objects differ in language.
 242     </para>
 243   </sect2>
 244   <sect2><title>FcType</title>
 245     <para>
 246 Tags the kind of data stored in an FcValue.
 247     </para>
 248   </sect2>
 249   <sect2><title>FcValue</title>
 250     <para>
 251 An FcValue object holds a single value with one of a number of different
 252 types.  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>
 287 holds a set of names with associated value lists; each name refers to a
 288 property of a font.  FcPatterns are used as inputs to the matching code as
 289 well as holding information about specific fonts.  Each property can hold
 290 one or more values; conventionally all of the same type, although the
 291 interface 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>
 303 An FcFontSet contains a list of FcPatterns.  Internally fontconfig uses this
 304 data structure to hold sets of fonts.  Externally, fontconfig returns the
 305 results of listing fonts in this format.  'nfont' holds the number of
 306 patterns in the 'fonts' array; 'sfont' is used to indicate the size of that
 307 array.
 308     </para>
 309   </sect2>
 310   <sect2><title>FcStrSet, FcStrList</title>
 311     <para>
 312 FcStrSet holds a list of strings that can be appended to and enumerated.
 313 Its unique characteristic is that the enumeration works even while strings
 314 are appended during enumeration.  FcStrList is used during enumeration to
 315 safely and correctly walk the list of strings even while that list is edited
 316 in 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>
 328 holds a set of names and is used to specify which fields from fonts are
 329 placed 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>
 340 marks the type of a pattern element generated when parsing font names.
 341 Applications can add new object types so that font names may contain the new
 342 elements.
 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>
 354 Provides for symbolic constants for new pattern elements.  When 'name' is
 355 seen in a font name, an 'object' element is created with value 'value'.
 356     </para>
 357   </sect2>
 358   <sect2><title>FcBlanks</title>
 359     <para>
 360 holds a list of Unicode chars which are expected to be blank; unexpectedly
 361 blank chars are assumed to be invalid and are elided from the charset
 362 associated with the font.
 363     </para>
 364   </sect2>
 365   <sect2><title>FcFileCache</title>
 366     <para>
 367 holds the per-user cache information for use while loading the font
 368 database. This is built automatically for the current configuration when
 369 that is loaded.  Applications must always pass '0' when one is requested.
 370     </para>
 371   </sect2>
 372   <sect2><title>FcConfig</title>
 373     <para>
 374 holds a complete configuration of the library; there is one default
 375 configuration, other can be constructed from XML data structures.  All
 376 public entry points that need global data can take an optional FcConfig*
 377 argument; passing 0 uses the default configuration.  FcConfig objects hold two
 378 sets of fonts, the first contains those specified by the configuration, the
 379 second set holds those added by the application at run-time.  Interfaces
 380 that need to reference a particulat set use one of the FcSetName enumerated
 381 values.
 382     </para>
 383   </sect2>
 384   <sect2><title>FcSetName</title>
 385     <para>
 386 Specifies one of the two sets of fonts available in a configuration;
 387 FcSetSystem for those fonts specified in the configuration and
 388 FcSetApplication which holds fonts provided by the application.
 389     </para>
 390   </sect2>
 391   <sect2><title>FcResult</title>
 392     <para>
 393 Used 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>
 409 Used for locking access to config files.  Provides a safe way to update
 410 configuration files.
 411     </para>
 412   </sect2>
 413   <sect2><title>FcCache</title>
 414     <para>
 415 Holds information about the fonts contained in a single directory. Normal
 416 applications need not worry about this as caches for font access are
 417 automatically managed by the library. Applications dealing with cache
 418 management may want to use some of these objects in their work, however the
 419 included 'fc-cache' program generally suffices for all of that.
 420     </para>
 421   </sect2>
 422 </sect1>
 423 <sect1><title>FUNCTIONS</title>
 424   <para>
 425 These are grouped by functionality, often using the main datatype being
 426 manipulated.
 427   </para>
 428   <sect2><title>Initialization</title>
 429     <para>
 430 These functions provide some control over how the library is initialized.
 431     </para>
 432     &fcinit;
 433   </sect2>
 434   <sect2><title>FcPattern</title>
 435     <para>
 436 An FcPattern is an opaque type that holds both patterns to match against the
 437 available fonts, as well as the information about each font.
 438     </para>
 439     &fcpattern;
 440   </sect2>
 441   <sect2><title>FcFontSet</title>
 442     <para>
 443 An FcFontSet simply holds a list of patterns; these are used to return the
 444 results of listing available fonts.
 445     </para>
 446     &fcfontset;
 447   </sect2>
 448   <sect2><title>FcObjectSet</title>
 449     <para>
 450 An FcObjectSet holds a list of pattern property names; it is used to
 451 indiciate which properties are to be returned in the patterns from
 452 FcFontList.
 453     </para>
 454     &fcobjectset;
 455   </sect2>
 456   <sect2><title>FreeType specific functions</title>
 457     <para>
 458 While the fontconfig library doesn't insist that FreeType be used as the
 459 rasterization mechanism for fonts, it does provide some convenience
 460 functions.
 461     </para>
 462     &fcfreetype;
 463   </sect2>
 464   <sect2><title>FcValue</title>
 465     <para>
 466 FcValue is a structure containing a type tag and a union of all possible
 467 datatypes.  The tag is an enum of type
 468 <emphasis>FcType</emphasis>
 469 and is intended to provide a measure of run-time
 470 typechecking, although that depends on careful programming.
 471     </para>
 472     &fcvalue;
 473   </sect2>
 474   <sect2><title>FcCharSet</title>
 475     <para>
 476 An FcCharSet is a boolean array indicating a set of unicode chars.  Those
 477 associated with a font are marked constant and cannot be edited.
 478 FcCharSets may be reference counted internally to reduce memory consumption;
 479 this may be visible to applications as the result of FcCharSetCopy may
 480 return it's argument, and that CharSet may remain unmodifiable.
 481     </para>
 482     &fccharset;
 483   </sect2>
 484   <sect2><title>FcLangSet</title>
 485     <para>
 486 An FcLangSet is a set of language names (each of which include language and
 487 an optional territory). They are used when selecting fonts to indicate which
 488 languages the fonts need to support. Each font is marked, using language
 489 orthography information built into fontconfig, with the set of supported
 490 languages.
 491     </para>
 492     &fclangset;
 493   </sect2>
 494   <sect2><title>FcMatrix</title>
 495     <para>
 496 FcMatrix structures hold an affine transformation in matrix form.
 497     </para>
 498     &fcmatrix;
 499   </sect2>
 500   <sect2><title>FcConfig</title>
 501     <para>
 502 An FcConfig object holds the internal representation of a configuration.
 503 There is a default configuration which applications may use by passing 0 to
 504 any function using the data within an FcConfig.
 505     </para>
 506     &fcconfig;
 507   </sect2>
 508   <sect2><title>FcObjectType</title>
 509     <para>
 510 Provides for applcation-specified font name object types so that new
 511 pattern elements can be generated from font names.
 512     </para>
 513     &fcobjecttype;
 514   </sect2>
 515   <sect2><title>FcConstant</title>
 516     <para>
 517 Provides for application-specified symbolic constants for font names.
 518     </para>
 519     &fcconstant;
 520   </sect2>
 521   <sect2><title>FcBlanks</title>
 522     <para>
 523 An FcBlanks object holds a list of Unicode chars which are expected to
 524 be blank when drawn.  When scanning new fonts, any glyphs which are
 525 empty and not in this list will be assumed to be broken and not placed in
 526 the FcCharSet associated with the font.  This provides a significantly more
 527 accurate CharSet for applications.
 528     </para>
 529     &fcblanks;
 530   </sect2>
 531   <sect2><title>FcAtomic</title>
 532     <para>
 533 These functions provide a safe way to update config files, allowing ongoing
 534 reading of the old config file while locked for writing and ensuring that a
 535 consistent 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>
 541 These routines work with font files and directories, including font
 542 directory cache files.
 543     </para>
 544     &fcfile;
 545     &fcdircache;
 546   </sect2>
 547   <sect2><title>FcCache routines</title>
 548     <para>
 549 These routines work with font directory caches, accessing their contents in
 550 limited ways. It is not expected that normal applications will need to use
 551 these functions.
 552     </para>
 553     &fccache;
 554   </sect2>
 555   <sect2><title>FcStrSet and FcStrList</title>
 556     <para>
 557 A data structure for enumerating strings, used to list directories while
 558 scanning the configuration as directories are added while scanning.
 559     </para>
 560     &fcstrset;
 561   </sect2>
 562   <sect2><title>String utilities</title>
 563     <para>
 564 Fontconfig manipulates many UTF-8 strings represented with the FcChar8 type.
 565 These functions are exposed to help applications deal with these UTF-8
 566 strings in a locale-insensitive manner.
 567     </para>
 568     &fcstring;
 569   </sect2>
 570 </sect1>
 571 </article>