diff options
Diffstat (limited to 'fontconfig/doc/fontconfig-devel.sgml')
| -rw-r--r-- | fontconfig/doc/fontconfig-devel.sgml | 1146 |
1 files changed, 573 insertions, 573 deletions
diff --git a/fontconfig/doc/fontconfig-devel.sgml b/fontconfig/doc/fontconfig-devel.sgml index 52675e267..87339511c 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> |