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