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