aboutsummaryrefslogtreecommitdiff
path: root/fontconfig/doc/fontconfig-devel.sgml
diff options
context:
space:
mode:
Diffstat (limited to 'fontconfig/doc/fontconfig-devel.sgml')
-rw-r--r--fontconfig/doc/fontconfig-devel.sgml1146
1 files changed, 573 insertions, 573 deletions
diff --git a/fontconfig/doc/fontconfig-devel.sgml b/fontconfig/doc/fontconfig-devel.sgml
index 87339511c..52675e267 100644
--- a/fontconfig/doc/fontconfig-devel.sgml
+++ b/fontconfig/doc/fontconfig-devel.sgml
@@ -1,573 +1,573 @@
-<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
-<!ENTITY fcatomic SYSTEM "fcatomic.sgml">
-<!ENTITY fcblanks SYSTEM "fcblanks.sgml">
-<!ENTITY fccache SYSTEM "fccache.sgml">
-<!ENTITY fccharset SYSTEM "fccharset.sgml">
-<!ENTITY fcconfig SYSTEM "fcconfig.sgml">
-<!ENTITY fcconstant SYSTEM "fcconstant.sgml">
-<!ENTITY fcdircache SYSTEM "fcdircache.sgml">
-<!ENTITY fcfile SYSTEM "fcfile.sgml">
-<!ENTITY fcfontset SYSTEM "fcfontset.sgml">
-<!ENTITY fcformat SYSTEM "fcformat.sgml">
-<!ENTITY fcfreetype SYSTEM "fcfreetype.sgml">
-<!ENTITY fcinit SYSTEM "fcinit.sgml">
-<!ENTITY fclangset SYSTEM "fclangset.sgml">
-<!ENTITY fcmatrix SYSTEM "fcmatrix.sgml">
-<!ENTITY fcobjectset SYSTEM "fcobjectset.sgml">
-<!ENTITY fcobjecttype SYSTEM "fcobjecttype.sgml">
-<!ENTITY fcpattern SYSTEM "fcpattern.sgml">
-<!ENTITY fcstring SYSTEM "fcstring.sgml">
-<!ENTITY fcstrset SYSTEM "fcstrset.sgml">
-<!ENTITY fcvalue SYSTEM "fcvalue.sgml">
-<!ENTITY version SYSTEM "version.sgml">
-]>
-<!--
- fontconfig/doc/local-fontconfig-devel.sgml
-
- Copyright © 2003 Keith Packard
-
- Permission to use, copy, modify, distribute, and sell this software and its
- documentation for any purpose is hereby granted without fee, provided that
- the above copyright notice appear in all copies and that both that
- copyright notice and this permission notice appear in supporting
- documentation, and that the name of the author(s) not be used in
- advertising or publicity pertaining to distribution of the software without
- specific, written prior permission. The authors make no
- representations about the suitability of this software for any purpose. It
- is provided "as is" without express or implied warranty.
-
- THE AUTHOR(S) DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
- INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
- EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY SPECIAL, INDIRECT OR
- CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
- DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
- TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
- PERFORMANCE OF THIS SOFTWARE.
--->
-<article>
- <title>Fontconfig Developers Reference, Version &version; </title>
- <artheader>
- <author>
- <firstname>Keith</firstname>
- <surname>Packard</surname>
- <affiliation><orgname>
- HP Cambridge Research Lab
- </orgname></affiliation>
- </author>
- <authorinitials>KRP</authorinitials>
- <productname>Fontconfig</productname>
- <productnumber>&version;</productnumber>
- <LegalNotice>
- <simpara>
-Copyright © 2002 Keith Packard
- </simpara><simpara>
-Permission to use, copy, modify, distribute, and sell this software and its
-documentation for any purpose is hereby granted without fee, provided that
-the above copyright notice appear in all copies and that both that
-copyright notice and this permission notice appear in supporting
-documentation, and that the name of the author(s) not be used in
-advertising or publicity pertaining to distribution of the software without
-specific, written prior permission. The authors make no
-representations about the suitability of this software for any purpose. It
-is provided "as is" without express or implied warranty.
- </simpara><simpara>
-THE AUTHOR(S) DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
-INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
-EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY SPECIAL, INDIRECT OR
-CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
-DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
-TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
-PERFORMANCE OF THIS SOFTWARE.
- </simpara>
- </LegalNotice>
- </artheader>
-<sect1><title>DESCRIPTION</title>
- <para>
-Fontconfig is a library designed to provide system-wide font configuration,
-customization and application access.
- </para>
-</sect1>
-<sect1><title>FUNCTIONAL OVERVIEW</title>
- <para>
-Fontconfig contains two essential modules, the configuration module which
-builds an internal configuration from XML files and the matching module
-which accepts font patterns and returns the nearest matching font.
- </para>
- <sect2><title>FONT CONFIGURATION</title>
- <para>
-The configuration module consists of the FcConfig datatype, libexpat and
-FcConfigParse which walks over an XML tree and amends a configuration with
-data found within. From an external perspective, configuration of the
-library consists of generating a valid XML tree and feeding that to
-FcConfigParse. The only other mechanism provided to applications for
-changing the running configuration is to add fonts and directories to the
-list of application-provided font files.
- </para><para>
-The intent is to make font configurations relatively static, and shared by
-as many applications as possible. It is hoped that this will lead to more
-stable font selection when passing names from one application to another.
-XML was chosen as a configuration file format because it provides a format
-which is easy for external agents to edit while retaining the correct
-structure and syntax.
- </para><para>
-Font configuration is separate from font matching; applications needing to
-do their own matching can access the available fonts from the library and
-perform private matching. The intent is to permit applications to pick and
-choose appropriate functionality from the library instead of forcing them to
-choose between this library and a private configuration mechanism. The hope
-is that this will ensure that configuration of fonts for all applications
-can be centralized in one place. Centralizing font configuration will
-simplify and regularize font installation and customization.
- </para>
- </sect2>
- <sect2>
- <title>FONT PROPERTIES</title>
- <para>
-While font patterns may contain essentially any properties, there are some
-well known properties with associated types. Fontconfig uses some of these
-properties for font matching and font completion. Others are provided as a
-convenience for the application's rendering mechanism.
- </para>
- <programlisting>
- Property Definitions
-
- Property C Preprocessor Symbol Type Description
- ----------------------------------------------------
- family FC_FAMILY String Font family names
- familylang FC_FAMILYLANG String Language corresponding to
- each family name
- style FC_STYLE String Font style. Overrides weight
- and slant
- stylelang FC_STYLELANG String Language corresponding to
- each style name
- fullname FC_FULLNAME String Font face full name where
- different from family and
- family + style
- fullnamelang FC_FULLNAMELANG String Language corresponding to
- each fullname
- slant FC_SLANT Int Italic, oblique or roman
- weight FC_WEIGHT Int Light, medium, demibold,
- bold or black
- size FC_SIZE Double Point size
- width FC_WIDTH Int Condensed, normal or expanded
- aspect FC_ASPECT Double Stretches glyphs horizontally
- before hinting
- pixelsize FC_PIXEL_SIZE Double Pixel size
- spacing FC_SPACING Int Proportional, dual-width,
- monospace or charcell
- foundry FC_FOUNDRY String Font foundry name
- antialias FC_ANTIALIAS Bool Whether glyphs can be
- antialiased
- hinting FC_HINTING Bool Whether the rasterizer should
- use hinting
- hintstyle FC_HINT_STYLE Int Automatic hinting style
- verticallayout FC_VERTICAL_LAYOUT Bool Use vertical layout
- autohint FC_AUTOHINT Bool Use autohinter instead of
- normal hinter
- globaladvance FC_GLOBAL_ADVANCE Bool Use font global advance data
- file FC_FILE String The filename holding the font
- index FC_INDEX Int The index of the font within
- the file
- ftface FC_FT_FACE FT_Face Use the specified FreeType
- face object
- rasterizer FC_RASTERIZER String Which rasterizer is in use
- outline FC_OUTLINE Bool Whether the glyphs are outlines
- scalable FC_SCALABLE Bool Whether glyphs can be scaled
- scale FC_SCALE Double Scale factor for point->pixel
- conversions
- dpi FC_DPI Double Target dots per inch
- rgba FC_RGBA Int unknown, rgb, bgr, vrgb,
- vbgr, none - subpixel geometry
- lcdfilter FC_LCD_FILTER Int Type of LCD filter
- minspace FC_MINSPACE Bool Eliminate leading from line
- spacing
- charset FC_CHARSET CharSet Unicode chars encoded by
- the font
- lang FC_LANG LangSet Set of RFC-3066-style
- languages this font supports
- fontversion FC_FONTVERSION Int Version number of the font
- capability FC_CAPABILITY String List of layout capabilities in
- the font
- embolden FC_EMBOLDEN Bool Rasterizer should
- synthetically embolden the font
- </programlisting>
- </sect2>
-</sect1>
-<sect1><title>Datatypes</title>
- <para>
-Fontconfig uses abstract data types to hide internal implementation details
-for most data structures. A few structures are exposed where appropriate.
- </para>
- <sect2><title>FcChar8, FcChar16, FcChar32, FcBool</title>
- <para>
-These are primitive data types; the FcChar* types hold precisely the number
-of bits stated (if supported by the C implementation). FcBool holds
-one of two C preprocessor symbols: FcFalse or FcTrue.
- </para>
- </sect2>
- <sect2><title>FcMatrix</title>
- <para>
-An FcMatrix holds an affine transformation, usually used to reshape glyphs.
-A small set of matrix operations are provided to manipulate these.
- <programlisting>
- typedef struct _FcMatrix {
- double xx, xy, yx, yy;
- } FcMatrix;
- </programlisting>
- </para>
- </sect2>
- <sect2><title>FcCharSet</title>
- <para>
-An FcCharSet is an abstract type that holds the set of encoded Unicode chars
-in a font. Operations to build and compare these sets are provided.
- </para>
- </sect2>
- <sect2><title>FcLangSet</title>
- <para>
-An FcLangSet is an abstract type that holds the set of languages supported
-by a font. Operations to build and compare these sets are provided. These
-are computed for a font based on orthographic information built into the
-fontconfig library. Fontconfig has orthographies for all of the ISO 639-1
-languages except for MS, NA, PA, PS, QU, RN, RW, SD, SG, SN, SU and ZA. If
-you have orthographic information for any of these languages, please submit
-them.
- </para>
- </sect2>
- <sect2><title>FcLangResult</title>
- <para>
-An FcLangResult is an enumeration used to return the results of comparing
-two language strings or FcLangSet objects. FcLangEqual means the
-objects match language and territory. FcLangDifferentTerritory means
-the objects match in language but differ in territory.
-FcLangDifferentLang means the objects differ in language.
- </para>
- </sect2>
- <sect2><title>FcType</title>
- <para>
-Tags the kind of data stored in an FcValue.
- </para>
- </sect2>
- <sect2><title>FcValue</title>
- <para>
-An FcValue object holds a single value with one of a number of different
-types. The 'type' tag indicates which member is valid.
- <programlisting>
- typedef struct _FcValue {
- FcType type;
- union {
- const FcChar8 *s;
- int i;
- FcBool b;
- double d;
- const FcMatrix *m;
- const FcCharSet *c;
- void *f;
- const FcLangSet *l;
- } u;
- } FcValue;
- </programlisting>
- <programlisting>
- FcValue Members
-
- Type Union member Datatype
- --------------------------------
- FcTypeVoid (none) (none)
- FcTypeInteger i int
- FcTypeDouble d double
- FcTypeString s FcChar8 *
- FcTypeBool b b
- FcTypeMatrix m FcMatrix *
- FcTypeCharSet c FcCharSet *
- FcTypeFTFace f void * (FT_Face)
- FcTypeLangSet l FcLangSet *
- </programlisting>
- </para>
- </sect2>
- <sect2><title>FcPattern</title>
- <para>
-holds a set of names with associated value lists; each name refers to a
-property of a font. FcPatterns are used as inputs to the matching code as
-well as holding information about specific fonts. Each property can hold
-one or more values; conventionally all of the same type, although the
-interface doesn't demand that.
- </para>
- </sect2>
- <sect2><title>FcFontSet</title>
- <para>
- <programlisting>
- typedef struct _FcFontSet {
- int nfont;
- int sfont;
- FcPattern **fonts;
- } FcFontSet;
- </programlisting>
-An FcFontSet contains a list of FcPatterns. Internally fontconfig uses this
-data structure to hold sets of fonts. Externally, fontconfig returns the
-results of listing fonts in this format. 'nfont' holds the number of
-patterns in the 'fonts' array; 'sfont' is used to indicate the size of that
-array.
- </para>
- </sect2>
- <sect2><title>FcStrSet, FcStrList</title>
- <para>
-FcStrSet holds a list of strings that can be appended to and enumerated.
-Its unique characteristic is that the enumeration works even while strings
-are appended during enumeration. FcStrList is used during enumeration to
-safely and correctly walk the list of strings even while that list is edited
-in the middle of enumeration.
- </para>
- </sect2>
- <sect2><title>FcObjectSet</title>
- <para>
- <programlisting>
- typedef struct _FcObjectSet {
- int nobject;
- int sobject;
- const char **objects;
- } FcObjectSet;
- </programlisting>
-holds a set of names and is used to specify which fields from fonts are
-placed in the the list of returned patterns when listing fonts.
- </para>
- </sect2>
- <sect2><title>FcObjectType</title>
- <para>
- <programlisting>
- typedef struct _FcObjectType {
- const char *object;
- FcType type;
- } FcObjectType;
- </programlisting>
-marks the type of a pattern element generated when parsing font names.
-Applications can add new object types so that font names may contain the new
-elements.
- </para>
- </sect2>
- <sect2><title>FcConstant</title>
- <para>
- <programlisting>
- typedef struct _FcConstant {
- const FcChar8 *name;
- const char *object;
- int value;
- } FcConstant;
- </programlisting>
-Provides for symbolic constants for new pattern elements. When 'name' is
-seen in a font name, an 'object' element is created with value 'value'.
- </para>
- </sect2>
- <sect2><title>FcBlanks</title>
- <para>
-holds a list of Unicode chars which are expected to be blank; unexpectedly
-blank chars are assumed to be invalid and are elided from the charset
-associated with the font.
- </para>
- </sect2>
- <sect2><title>FcFileCache</title>
- <para>
-holds the per-user cache information for use while loading the font
-database. This is built automatically for the current configuration when
-that is loaded. Applications must always pass '0' when one is requested.
- </para>
- </sect2>
- <sect2><title>FcConfig</title>
- <para>
-holds a complete configuration of the library; there is one default
-configuration, other can be constructed from XML data structures. All
-public entry points that need global data can take an optional FcConfig*
-argument; passing 0 uses the default configuration. FcConfig objects hold two
-sets of fonts, the first contains those specified by the configuration, the
-second set holds those added by the application at run-time. Interfaces
-that need to reference a particular set use one of the FcSetName enumerated
-values.
- </para>
- </sect2>
- <sect2><title>FcSetName</title>
- <para>
-Specifies one of the two sets of fonts available in a configuration;
-FcSetSystem for those fonts specified in the configuration and
-FcSetApplication which holds fonts provided by the application.
- </para>
- </sect2>
- <sect2><title>FcResult</title>
- <para>
-Used as a return type for functions manipulating FcPattern objects.
- <programlisting>
- FcResult Values
- Result Code Meaning
- -----------------------------------------------------------
- FcResultMatch Object exists with the specified ID
- FcResultNoMatch Object doesn't exist at all
- FcResultTypeMismatch Object exists, but the type doesn't match
- FcResultNoId Object exists, but has fewer values
- than specified
- FcResultOutOfMemory malloc failed
- </programlisting>
- </para>
- </sect2>
- <sect2><title>FcAtomic</title>
- <para>
-Used for locking access to configuration files. Provides a safe way to update
-configuration files.
- </para>
- </sect2>
- <sect2><title>FcCache</title>
- <para>
-Holds information about the fonts contained in a single directory. Normal
-applications need not worry about this as caches for font access are
-automatically managed by the library. Applications dealing with cache
-management may want to use some of these objects in their work, however the
-included 'fc-cache' program generally suffices for all of that.
- </para>
- </sect2>
-</sect1>
-<sect1><title>FUNCTIONS</title>
- <para>
-These are grouped by functionality, often using the main data type being
-manipulated.
- </para>
- <sect2><title>Initialization</title>
- <para>
-These functions provide some control over how the library is initialized.
- </para>
- &fcinit;
- </sect2>
- <sect2><title>FcPattern</title>
- <para>
-An FcPattern is an opaque type that holds both patterns to match against the
-available fonts, as well as the information about each font.
- </para>
- &fcpattern;
- &fcformat;
- </sect2>
- <sect2><title>FcFontSet</title>
- <para>
-An FcFontSet simply holds a list of patterns; these are used to return the
-results of listing available fonts.
- </para>
- &fcfontset;
- </sect2>
- <sect2><title>FcObjectSet</title>
- <para>
-An FcObjectSet holds a list of pattern property names; it is used to
-indicate which properties are to be returned in the patterns from
-FcFontList.
- </para>
- &fcobjectset;
- </sect2>
- <sect2><title>FreeType specific functions</title>
- <para>
-While the fontconfig library doesn't insist that FreeType be used as the
-rasterization mechanism for fonts, it does provide some convenience
-functions.
- </para>
- &fcfreetype;
- </sect2>
- <sect2><title>FcValue</title>
- <para>
-FcValue is a structure containing a type tag and a union of all possible
-datatypes. The tag is an enum of type
-<emphasis>FcType</emphasis>
-and is intended to provide a measure of run-time
-typechecking, although that depends on careful programming.
- </para>
- &fcvalue;
- </sect2>
- <sect2><title>FcCharSet</title>
- <para>
-An FcCharSet is a boolean array indicating a set of Unicode chars. Those
-associated with a font are marked constant and cannot be edited.
-FcCharSets may be reference counted internally to reduce memory consumption;
-this may be visible to applications as the result of FcCharSetCopy may
-return it's argument, and that CharSet may remain unmodifiable.
- </para>
- &fccharset;
- </sect2>
- <sect2><title>FcLangSet</title>
- <para>
-An FcLangSet is a set of language names (each of which include language and
-an optional territory). They are used when selecting fonts to indicate which
-languages the fonts need to support. Each font is marked, using language
-orthography information built into fontconfig, with the set of supported
-languages.
- </para>
- &fclangset;
- </sect2>
- <sect2><title>FcMatrix</title>
- <para>
-FcMatrix structures hold an affine transformation in matrix form.
- </para>
- &fcmatrix;
- </sect2>
- <sect2><title>FcConfig</title>
- <para>
-An FcConfig object holds the internal representation of a configuration.
-There is a default configuration which applications may use by passing 0 to
-any function using the data within an FcConfig.
- </para>
- &fcconfig;
- </sect2>
- <sect2><title>FcObjectType</title>
- <para>
-Provides for application-specified font name object types so that new
-pattern elements can be generated from font names.
- </para>
- &fcobjecttype;
- </sect2>
- <sect2><title>FcConstant</title>
- <para>
-Provides for application-specified symbolic constants for font names.
- </para>
- &fcconstant;
- </sect2>
- <sect2><title>FcBlanks</title>
- <para>
-An FcBlanks object holds a list of Unicode chars which are expected to
-be blank when drawn. When scanning new fonts, any glyphs which are
-empty and not in this list will be assumed to be broken and not placed in
-the FcCharSet associated with the font. This provides a significantly more
-accurate CharSet for applications.
- </para>
- &fcblanks;
- </sect2>
- <sect2><title>FcAtomic</title>
- <para>
-These functions provide a safe way to update configuration files, allowing ongoing
-reading of the old configuration file while locked for writing and ensuring that a
-consistent and complete version of the configuration file is always available.
- </para>
- &fcatomic;
- </sect2>
- <sect2><title>File and Directory routines</title>
- <para>
-These routines work with font files and directories, including font
-directory cache files.
- </para>
- &fcfile;
- &fcdircache;
- </sect2>
- <sect2><title>FcCache routines</title>
- <para>
-These routines work with font directory caches, accessing their contents in
-limited ways. It is not expected that normal applications will need to use
-these functions.
- </para>
- &fccache;
- </sect2>
- <sect2><title>FcStrSet and FcStrList</title>
- <para>
-A data structure for enumerating strings, used to list directories while
-scanning the configuration as directories are added while scanning.
- </para>
- &fcstrset;
- </sect2>
- <sect2><title>String utilities</title>
- <para>
-Fontconfig manipulates many UTF-8 strings represented with the FcChar8 type.
-These functions are exposed to help applications deal with these UTF-8
-strings in a locale-insensitive manner.
- </para>
- &fcstring;
- </sect2>
-</sect1>
-</article>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
+<!ENTITY fcatomic SYSTEM "fcatomic.sgml">
+<!ENTITY fcblanks SYSTEM "fcblanks.sgml">
+<!ENTITY fccache SYSTEM "fccache.sgml">
+<!ENTITY fccharset SYSTEM "fccharset.sgml">
+<!ENTITY fcconfig SYSTEM "fcconfig.sgml">
+<!ENTITY fcconstant SYSTEM "fcconstant.sgml">
+<!ENTITY fcdircache SYSTEM "fcdircache.sgml">
+<!ENTITY fcfile SYSTEM "fcfile.sgml">
+<!ENTITY fcfontset SYSTEM "fcfontset.sgml">
+<!ENTITY fcformat SYSTEM "fcformat.sgml">
+<!ENTITY fcfreetype SYSTEM "fcfreetype.sgml">
+<!ENTITY fcinit SYSTEM "fcinit.sgml">
+<!ENTITY fclangset SYSTEM "fclangset.sgml">
+<!ENTITY fcmatrix SYSTEM "fcmatrix.sgml">
+<!ENTITY fcobjectset SYSTEM "fcobjectset.sgml">
+<!ENTITY fcobjecttype SYSTEM "fcobjecttype.sgml">
+<!ENTITY fcpattern SYSTEM "fcpattern.sgml">
+<!ENTITY fcstring SYSTEM "fcstring.sgml">
+<!ENTITY fcstrset SYSTEM "fcstrset.sgml">
+<!ENTITY fcvalue SYSTEM "fcvalue.sgml">
+<!ENTITY version SYSTEM "version.sgml">
+]>
+<!--
+ fontconfig/doc/local-fontconfig-devel.sgml
+
+ Copyright © 2003 Keith Packard
+
+ Permission to use, copy, modify, distribute, and sell this software and its
+ documentation for any purpose is hereby granted without fee, provided that
+ the above copyright notice appear in all copies and that both that
+ copyright notice and this permission notice appear in supporting
+ documentation, and that the name of the author(s) not be used in
+ advertising or publicity pertaining to distribution of the software without
+ specific, written prior permission. The authors make no
+ representations about the suitability of this software for any purpose. It
+ is provided "as is" without express or implied warranty.
+
+ THE AUTHOR(S) DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
+ INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
+ EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY SPECIAL, INDIRECT OR
+ CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
+ DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
+ TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+ PERFORMANCE OF THIS SOFTWARE.
+-->
+<article>
+ <title>Fontconfig Developers Reference, Version &version; </title>
+ <artheader>
+ <author>
+ <firstname>Keith</firstname>
+ <surname>Packard</surname>
+ <affiliation><orgname>
+ HP Cambridge Research Lab
+ </orgname></affiliation>
+ </author>
+ <authorinitials>KRP</authorinitials>
+ <productname>Fontconfig</productname>
+ <productnumber>&version;</productnumber>
+ <LegalNotice>
+ <simpara>
+Copyright © 2002 Keith Packard
+ </simpara><simpara>
+Permission to use, copy, modify, distribute, and sell this software and its
+documentation for any purpose is hereby granted without fee, provided that
+the above copyright notice appear in all copies and that both that
+copyright notice and this permission notice appear in supporting
+documentation, and that the name of the author(s) not be used in
+advertising or publicity pertaining to distribution of the software without
+specific, written prior permission. The authors make no
+representations about the suitability of this software for any purpose. It
+is provided "as is" without express or implied warranty.
+ </simpara><simpara>
+THE AUTHOR(S) DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
+INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
+EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY SPECIAL, INDIRECT OR
+CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
+DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
+TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.
+ </simpara>
+ </LegalNotice>
+ </artheader>
+<sect1><title>DESCRIPTION</title>
+ <para>
+Fontconfig is a library designed to provide system-wide font configuration,
+customization and application access.
+ </para>
+</sect1>
+<sect1><title>FUNCTIONAL OVERVIEW</title>
+ <para>
+Fontconfig contains two essential modules, the configuration module which
+builds an internal configuration from XML files and the matching module
+which accepts font patterns and returns the nearest matching font.
+ </para>
+ <sect2><title>FONT CONFIGURATION</title>
+ <para>
+The configuration module consists of the FcConfig datatype, libexpat and
+FcConfigParse which walks over an XML tree and amends a configuration with
+data found within. From an external perspective, configuration of the
+library consists of generating a valid XML tree and feeding that to
+FcConfigParse. The only other mechanism provided to applications for
+changing the running configuration is to add fonts and directories to the
+list of application-provided font files.
+ </para><para>
+The intent is to make font configurations relatively static, and shared by
+as many applications as possible. It is hoped that this will lead to more
+stable font selection when passing names from one application to another.
+XML was chosen as a configuration file format because it provides a format
+which is easy for external agents to edit while retaining the correct
+structure and syntax.
+ </para><para>
+Font configuration is separate from font matching; applications needing to
+do their own matching can access the available fonts from the library and
+perform private matching. The intent is to permit applications to pick and
+choose appropriate functionality from the library instead of forcing them to
+choose between this library and a private configuration mechanism. The hope
+is that this will ensure that configuration of fonts for all applications
+can be centralized in one place. Centralizing font configuration will
+simplify and regularize font installation and customization.
+ </para>
+ </sect2>
+ <sect2>
+ <title>FONT PROPERTIES</title>
+ <para>
+While font patterns may contain essentially any properties, there are some
+well known properties with associated types. Fontconfig uses some of these
+properties for font matching and font completion. Others are provided as a
+convenience for the application's rendering mechanism.
+ </para>
+ <programlisting>
+ Property Definitions
+
+ Property C Preprocessor Symbol Type Description
+ ----------------------------------------------------
+ family FC_FAMILY String Font family names
+ familylang FC_FAMILYLANG String Language corresponding to
+ each family name
+ style FC_STYLE String Font style. Overrides weight
+ and slant
+ stylelang FC_STYLELANG String Language corresponding to
+ each style name
+ fullname FC_FULLNAME String Font face full name where
+ different from family and
+ family + style
+ fullnamelang FC_FULLNAMELANG String Language corresponding to
+ each fullname
+ slant FC_SLANT Int Italic, oblique or roman
+ weight FC_WEIGHT Int Light, medium, demibold,
+ bold or black
+ size FC_SIZE Double Point size
+ width FC_WIDTH Int Condensed, normal or expanded
+ aspect FC_ASPECT Double Stretches glyphs horizontally
+ before hinting
+ pixelsize FC_PIXEL_SIZE Double Pixel size
+ spacing FC_SPACING Int Proportional, dual-width,
+ monospace or charcell
+ foundry FC_FOUNDRY String Font foundry name
+ antialias FC_ANTIALIAS Bool Whether glyphs can be
+ antialiased
+ hinting FC_HINTING Bool Whether the rasterizer should
+ use hinting
+ hintstyle FC_HINT_STYLE Int Automatic hinting style
+ verticallayout FC_VERTICAL_LAYOUT Bool Use vertical layout
+ autohint FC_AUTOHINT Bool Use autohinter instead of
+ normal hinter
+ globaladvance FC_GLOBAL_ADVANCE Bool Use font global advance data
+ file FC_FILE String The filename holding the font
+ index FC_INDEX Int The index of the font within
+ the file
+ ftface FC_FT_FACE FT_Face Use the specified FreeType
+ face object
+ rasterizer FC_RASTERIZER String Which rasterizer is in use
+ outline FC_OUTLINE Bool Whether the glyphs are outlines
+ scalable FC_SCALABLE Bool Whether glyphs can be scaled
+ scale FC_SCALE Double Scale factor for point->pixel
+ conversions
+ dpi FC_DPI Double Target dots per inch
+ rgba FC_RGBA Int unknown, rgb, bgr, vrgb,
+ vbgr, none - subpixel geometry
+ lcdfilter FC_LCD_FILTER Int Type of LCD filter
+ minspace FC_MINSPACE Bool Eliminate leading from line
+ spacing
+ charset FC_CHARSET CharSet Unicode chars encoded by
+ the font
+ lang FC_LANG LangSet Set of RFC-3066-style
+ languages this font supports
+ fontversion FC_FONTVERSION Int Version number of the font
+ capability FC_CAPABILITY String List of layout capabilities in
+ the font
+ embolden FC_EMBOLDEN Bool Rasterizer should
+ synthetically embolden the font
+ </programlisting>
+ </sect2>
+</sect1>
+<sect1><title>Datatypes</title>
+ <para>
+Fontconfig uses abstract data types to hide internal implementation details
+for most data structures. A few structures are exposed where appropriate.
+ </para>
+ <sect2><title>FcChar8, FcChar16, FcChar32, FcBool</title>
+ <para>
+These are primitive data types; the FcChar* types hold precisely the number
+of bits stated (if supported by the C implementation). FcBool holds
+one of two C preprocessor symbols: FcFalse or FcTrue.
+ </para>
+ </sect2>
+ <sect2><title>FcMatrix</title>
+ <para>
+An FcMatrix holds an affine transformation, usually used to reshape glyphs.
+A small set of matrix operations are provided to manipulate these.
+ <programlisting>
+ typedef struct _FcMatrix {
+ double xx, xy, yx, yy;
+ } FcMatrix;
+ </programlisting>
+ </para>
+ </sect2>
+ <sect2><title>FcCharSet</title>
+ <para>
+An FcCharSet is an abstract type that holds the set of encoded Unicode chars
+in a font. Operations to build and compare these sets are provided.
+ </para>
+ </sect2>
+ <sect2><title>FcLangSet</title>
+ <para>
+An FcLangSet is an abstract type that holds the set of languages supported
+by a font. Operations to build and compare these sets are provided. These
+are computed for a font based on orthographic information built into the
+fontconfig library. Fontconfig has orthographies for all of the ISO 639-1
+languages except for MS, NA, PA, PS, QU, RN, RW, SD, SG, SN, SU and ZA. If
+you have orthographic information for any of these languages, please submit
+them.
+ </para>
+ </sect2>
+ <sect2><title>FcLangResult</title>
+ <para>
+An FcLangResult is an enumeration used to return the results of comparing
+two language strings or FcLangSet objects. FcLangEqual means the
+objects match language and territory. FcLangDifferentTerritory means
+the objects match in language but differ in territory.
+FcLangDifferentLang means the objects differ in language.
+ </para>
+ </sect2>
+ <sect2><title>FcType</title>
+ <para>
+Tags the kind of data stored in an FcValue.
+ </para>
+ </sect2>
+ <sect2><title>FcValue</title>
+ <para>
+An FcValue object holds a single value with one of a number of different
+types. The 'type' tag indicates which member is valid.
+ <programlisting>
+ typedef struct _FcValue {
+ FcType type;
+ union {
+ const FcChar8 *s;
+ int i;
+ FcBool b;
+ double d;
+ const FcMatrix *m;
+ const FcCharSet *c;
+ void *f;
+ const FcLangSet *l;
+ } u;
+ } FcValue;
+ </programlisting>
+ <programlisting>
+ FcValue Members
+
+ Type Union member Datatype
+ --------------------------------
+ FcTypeVoid (none) (none)
+ FcTypeInteger i int
+ FcTypeDouble d double
+ FcTypeString s FcChar8 *
+ FcTypeBool b b
+ FcTypeMatrix m FcMatrix *
+ FcTypeCharSet c FcCharSet *
+ FcTypeFTFace f void * (FT_Face)
+ FcTypeLangSet l FcLangSet *
+ </programlisting>
+ </para>
+ </sect2>
+ <sect2><title>FcPattern</title>
+ <para>
+holds a set of names with associated value lists; each name refers to a
+property of a font. FcPatterns are used as inputs to the matching code as
+well as holding information about specific fonts. Each property can hold
+one or more values; conventionally all of the same type, although the
+interface doesn't demand that.
+ </para>
+ </sect2>
+ <sect2><title>FcFontSet</title>
+ <para>
+ <programlisting>
+ typedef struct _FcFontSet {
+ int nfont;
+ int sfont;
+ FcPattern **fonts;
+ } FcFontSet;
+ </programlisting>
+An FcFontSet contains a list of FcPatterns. Internally fontconfig uses this
+data structure to hold sets of fonts. Externally, fontconfig returns the
+results of listing fonts in this format. 'nfont' holds the number of
+patterns in the 'fonts' array; 'sfont' is used to indicate the size of that
+array.
+ </para>
+ </sect2>
+ <sect2><title>FcStrSet, FcStrList</title>
+ <para>
+FcStrSet holds a list of strings that can be appended to and enumerated.
+Its unique characteristic is that the enumeration works even while strings
+are appended during enumeration. FcStrList is used during enumeration to
+safely and correctly walk the list of strings even while that list is edited
+in the middle of enumeration.
+ </para>
+ </sect2>
+ <sect2><title>FcObjectSet</title>
+ <para>
+ <programlisting>
+ typedef struct _FcObjectSet {
+ int nobject;
+ int sobject;
+ const char **objects;
+ } FcObjectSet;
+ </programlisting>
+holds a set of names and is used to specify which fields from fonts are
+placed in the the list of returned patterns when listing fonts.
+ </para>
+ </sect2>
+ <sect2><title>FcObjectType</title>
+ <para>
+ <programlisting>
+ typedef struct _FcObjectType {
+ const char *object;
+ FcType type;
+ } FcObjectType;
+ </programlisting>
+marks the type of a pattern element generated when parsing font names.
+Applications can add new object types so that font names may contain the new
+elements.
+ </para>
+ </sect2>
+ <sect2><title>FcConstant</title>
+ <para>
+ <programlisting>
+ typedef struct _FcConstant {
+ const FcChar8 *name;
+ const char *object;
+ int value;
+ } FcConstant;
+ </programlisting>
+Provides for symbolic constants for new pattern elements. When 'name' is
+seen in a font name, an 'object' element is created with value 'value'.
+ </para>
+ </sect2>
+ <sect2><title>FcBlanks</title>
+ <para>
+holds a list of Unicode chars which are expected to be blank; unexpectedly
+blank chars are assumed to be invalid and are elided from the charset
+associated with the font.
+ </para>
+ </sect2>
+ <sect2><title>FcFileCache</title>
+ <para>
+holds the per-user cache information for use while loading the font
+database. This is built automatically for the current configuration when
+that is loaded. Applications must always pass '0' when one is requested.
+ </para>
+ </sect2>
+ <sect2><title>FcConfig</title>
+ <para>
+holds a complete configuration of the library; there is one default
+configuration, other can be constructed from XML data structures. All
+public entry points that need global data can take an optional FcConfig*
+argument; passing 0 uses the default configuration. FcConfig objects hold two
+sets of fonts, the first contains those specified by the configuration, the
+second set holds those added by the application at run-time. Interfaces
+that need to reference a particular set use one of the FcSetName enumerated
+values.
+ </para>
+ </sect2>
+ <sect2><title>FcSetName</title>
+ <para>
+Specifies one of the two sets of fonts available in a configuration;
+FcSetSystem for those fonts specified in the configuration and
+FcSetApplication which holds fonts provided by the application.
+ </para>
+ </sect2>
+ <sect2><title>FcResult</title>
+ <para>
+Used as a return type for functions manipulating FcPattern objects.
+ <programlisting>
+ FcResult Values
+ Result Code Meaning
+ -----------------------------------------------------------
+ FcResultMatch Object exists with the specified ID
+ FcResultNoMatch Object doesn't exist at all
+ FcResultTypeMismatch Object exists, but the type doesn't match
+ FcResultNoId Object exists, but has fewer values
+ than specified
+ FcResultOutOfMemory malloc failed
+ </programlisting>
+ </para>
+ </sect2>
+ <sect2><title>FcAtomic</title>
+ <para>
+Used for locking access to configuration files. Provides a safe way to update
+configuration files.
+ </para>
+ </sect2>
+ <sect2><title>FcCache</title>
+ <para>
+Holds information about the fonts contained in a single directory. Normal
+applications need not worry about this as caches for font access are
+automatically managed by the library. Applications dealing with cache
+management may want to use some of these objects in their work, however the
+included 'fc-cache' program generally suffices for all of that.
+ </para>
+ </sect2>
+</sect1>
+<sect1><title>FUNCTIONS</title>
+ <para>
+These are grouped by functionality, often using the main data type being
+manipulated.
+ </para>
+ <sect2><title>Initialization</title>
+ <para>
+These functions provide some control over how the library is initialized.
+ </para>
+ &fcinit;
+ </sect2>
+ <sect2><title>FcPattern</title>
+ <para>
+An FcPattern is an opaque type that holds both patterns to match against the
+available fonts, as well as the information about each font.
+ </para>
+ &fcpattern;
+ &fcformat;
+ </sect2>
+ <sect2><title>FcFontSet</title>
+ <para>
+An FcFontSet simply holds a list of patterns; these are used to return the
+results of listing available fonts.
+ </para>
+ &fcfontset;
+ </sect2>
+ <sect2><title>FcObjectSet</title>
+ <para>
+An FcObjectSet holds a list of pattern property names; it is used to
+indicate which properties are to be returned in the patterns from
+FcFontList.
+ </para>
+ &fcobjectset;
+ </sect2>
+ <sect2><title>FreeType specific functions</title>
+ <para>
+While the fontconfig library doesn't insist that FreeType be used as the
+rasterization mechanism for fonts, it does provide some convenience
+functions.
+ </para>
+ &fcfreetype;
+ </sect2>
+ <sect2><title>FcValue</title>
+ <para>
+FcValue is a structure containing a type tag and a union of all possible
+datatypes. The tag is an enum of type
+<emphasis>FcType</emphasis>
+and is intended to provide a measure of run-time
+typechecking, although that depends on careful programming.
+ </para>
+ &fcvalue;
+ </sect2>
+ <sect2><title>FcCharSet</title>
+ <para>
+An FcCharSet is a boolean array indicating a set of Unicode chars. Those
+associated with a font are marked constant and cannot be edited.
+FcCharSets may be reference counted internally to reduce memory consumption;
+this may be visible to applications as the result of FcCharSetCopy may
+return it's argument, and that CharSet may remain unmodifiable.
+ </para>
+ &fccharset;
+ </sect2>
+ <sect2><title>FcLangSet</title>
+ <para>
+An FcLangSet is a set of language names (each of which include language and
+an optional territory). They are used when selecting fonts to indicate which
+languages the fonts need to support. Each font is marked, using language
+orthography information built into fontconfig, with the set of supported
+languages.
+ </para>
+ &fclangset;
+ </sect2>
+ <sect2><title>FcMatrix</title>
+ <para>
+FcMatrix structures hold an affine transformation in matrix form.
+ </para>
+ &fcmatrix;
+ </sect2>
+ <sect2><title>FcConfig</title>
+ <para>
+An FcConfig object holds the internal representation of a configuration.
+There is a default configuration which applications may use by passing 0 to
+any function using the data within an FcConfig.
+ </para>
+ &fcconfig;
+ </sect2>
+ <sect2><title>FcObjectType</title>
+ <para>
+Provides for application-specified font name object types so that new
+pattern elements can be generated from font names.
+ </para>
+ &fcobjecttype;
+ </sect2>
+ <sect2><title>FcConstant</title>
+ <para>
+Provides for application-specified symbolic constants for font names.
+ </para>
+ &fcconstant;
+ </sect2>
+ <sect2><title>FcBlanks</title>
+ <para>
+An FcBlanks object holds a list of Unicode chars which are expected to
+be blank when drawn. When scanning new fonts, any glyphs which are
+empty and not in this list will be assumed to be broken and not placed in
+the FcCharSet associated with the font. This provides a significantly more
+accurate CharSet for applications.
+ </para>
+ &fcblanks;
+ </sect2>
+ <sect2><title>FcAtomic</title>
+ <para>
+These functions provide a safe way to update configuration files, allowing ongoing
+reading of the old configuration file while locked for writing and ensuring that a
+consistent and complete version of the configuration file is always available.
+ </para>
+ &fcatomic;
+ </sect2>
+ <sect2><title>File and Directory routines</title>
+ <para>
+These routines work with font files and directories, including font
+directory cache files.
+ </para>
+ &fcfile;
+ &fcdircache;
+ </sect2>
+ <sect2><title>FcCache routines</title>
+ <para>
+These routines work with font directory caches, accessing their contents in
+limited ways. It is not expected that normal applications will need to use
+these functions.
+ </para>
+ &fccache;
+ </sect2>
+ <sect2><title>FcStrSet and FcStrList</title>
+ <para>
+A data structure for enumerating strings, used to list directories while
+scanning the configuration as directories are added while scanning.
+ </para>
+ &fcstrset;
+ </sect2>
+ <sect2><title>String utilities</title>
+ <para>
+Fontconfig manipulates many UTF-8 strings represented with the FcChar8 type.
+These functions are exposed to help applications deal with these UTF-8
+strings in a locale-insensitive manner.
+ </para>
+ &fcstring;
+ </sect2>
+</sect1>
+</article>