diff options
Diffstat (limited to 'libXfont/doc/fontlib.xml')
| -rw-r--r-- | libXfont/doc/fontlib.xml | 1318 |
1 files changed, 659 insertions, 659 deletions
diff --git a/libXfont/doc/fontlib.xml b/libXfont/doc/fontlib.xml index 3b0829d30..cce83e9bd 100644 --- a/libXfont/doc/fontlib.xml +++ b/libXfont/doc/fontlib.xml @@ -1,659 +1,659 @@ -<?xml version="1.0" encoding="UTF-8" ?>
-<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
- "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" >
-<!-- lifted from troff+ms by doclifter -->
-<!-- previous version was in xorg-docs/specs/Xserver/fontlib.ms -->
-
- <article id='fontlib'>
-<!-- .ps 12 -->
-<!-- .EF 'Font Library Interface'\- % \-'July 27, 1991' -->
-<!-- .OF 'Font Library Interface'\- % \-'July 27, 1991' -->
-<!-- .EH '''' -->
-<!-- .OH '''' -->
-<!-- body begins here -->
- <articleinfo>
- <title>
- The X Font Library
- </title>
- <pubdate>July 27, 1991</pubdate>
- <authorgroup>
- <author>
- <firstname>Keith</firstname>
- <surname>Packard</surname>
- <affiliation>
- <orgname>MIT X Consortium</orgname>
- </affiliation>
- </author>
- <author>
- <firstname>David</firstname>
- <surname>Lemke</surname>
- <affiliation>
- <orgname>Network Computing Devices</orgname>
- </affiliation>
- </author>
- </authorgroup>
- <legalnotice>
- <para>
- Copyright 1993 <orgname>Network Computing Devices</orgname>
- </para>
- <para>
- 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 Network Computing
- Devices not be used in advertising or publicity pertaining
- to distribution of the software without specific, written
- prior permission. Network Computing Devices makes no
- representations about the suitability of this software for
- any purpose. It is provided “as is” without
- express or implied warranty.
- </para>
- <para>
- Copyright 1993, 1994 <orgname>X Consortium</orgname>
- </para>
- <para>
- Permission is hereby granted, free of charge, to any person
- obtaining a copy of this software and associated
- documentation files (the “Software”), to deal in the
- Software without restriction, including without limitation
- the rights to use, copy, modify, merge, publish, distribute,
- sublicense, and/or sell copies of the Software, and to
- permit persons to whom the Software is furnished to do so,
- subject to the following conditions:
- </para><para>
- The above copyright notice and this permission notice shall be
- included in all copies or substantial portions of the Software.
- </para><para>
- THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY
- OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO
- THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
- PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE X
- CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
- OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
- SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
- </para><para>
- Except as contained in this notice, the name of the X
- Consortium shall not be used in advertising or otherwise to
- promote the sale, use or other dealings in this Software
- without prior written authorization from the X Consortium.
- </para>
- </legalnotice>
- </articleinfo>
-
- <warning>
- <para>
- This document has not been updated since X11R6, and is likely
- to be somewhat out of date for the current libXfont.
- </para>
- </warning>
-
- <para>
- This document describes the data structures and interfaces for
- using the X Font library. It is intended as a reference for
- programmers building X and Font servers. You may want to refer
- to the following documents:
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- <citetitle pubwork="article">Definition of the Porting Layer for
- the X v11 Sample Server</citetitle> for a discussion on how this
- library interacts with the X server
- </para>
- </listitem>
- <listitem>
- <para>
- <citetitle pubwork="article">Font Server Implementation
- Overview</citetitle> which discusses the design of the font
- server.
- </para>
- </listitem>
- <listitem>
- <para>
- <citetitle pubwork="article">Bitmap Distribution Format</citetitle>
- which covers the contents of the bitmap font files which this
- library reads; although the library is capable of reading other
- formats as well, including non-bitmap fonts.
- </para>
- </listitem>
- <listitem>
- <para>
- <citetitle pubwork="article">The X Font Service Protocol</citetitle>
- for a description of the constraints placed on the design by
- including support for this font service mechanism.
- </para>
- </listitem>
- </itemizedlist>
-
- <para>
- This document assumes the reader is familiar with the X server design,
- the X protocol as it relates to fonts and the C programming language.
- As with most MIT produced documentation, this relies heavily on the
- source code, so have a listing handy.
- </para>
-
- <sect1 id='requirements_for_the_font_library'>
- <title>
- Requirements for the Font library
- </title>
-
- <para>
- To avoid miles of duplicate code in the X server, the font server
- and the various font manipulation tools, the font library should
- provide interfaces appropriate for all of these tasks. In
- particular, the X server and font server should be able to both
- use the library to access disk based fonts, and to communicate
- with a font server. By providing a general library, we hoped to
- avoid duplicating code between the X server and font server.
- </para>
-
- <para>
- Another requirement is that the X server (or even a font server)
- be able to continue servicing requests from other clients while
- awaiting a response from the font server on behalf of one client.
- This is the strongest requirement placed on the font library, and
- has warped the design in curious ways. Because both the X server
- and font server are single threaded, the font library must not
- suspend internally, rather it returns an indication of suspension
- to the application which continues processing other things, until
- the font data is ready, at which time it restarts the suspended
- request.
- </para>
-
- <para>
- Because the code for reading and manipulating bitmap font data is
- used by the font applications <command>mkfontdir</command> and
- <command>bdftopcf</command>, the font library includes
- bitmap-font specific interfaces which those applications use,
- instead of the more general interfaces used by the X and font
- servers, which are unaware of the source of the font data.
- These routines will be refered to as the bitmap font access
- methods.
- </para>
-
- </sect1>
-
- <sect1 id='general_font_library_interface_details'>
- <title>
- General Font Library Interface details.
- </title>
-
- <para>
- To avoid collision between the #define name space for errors, the Font
- library defines a new set of return values:
- </para>
-
- <programlisting remap='.nf'>
-#define AllocError 80
-#define StillWorking 81
-#define FontNameAlias 82
-#define BadFontName 83
-#define Suspended 84
-#define Successful 85
-#define BadFontPath 86
-#define BadCharRange 87
-#define BadFontFormat 88
-#define FPEResetFailed 89
- </programlisting> <!-- .fi -->
-
- <para>
- Whenever a routine returns <errorname>Suspended</errorname>,
- the font library will notify the caller (via the ClientSignal
- interface described below) who should then reinvoke the same routine
- again with the same arguments.
- </para>
-
- </sect1>
-
- <sect1 id='font_path_elements'>
- <title>
- Font Path Elements
- </title>
-
- <para>
- At the center of the general font access methods used by X and
- <command>xfs</command> is the Font Path Element data structure.
- Like most structures in the X server, this contains a collection
- of data and some function pointers for manipulating this data:
- </para>
-
- <programlisting remap='.nf'>
-/* External view of font paths */
-typedef struct _FontPathElement {
- int name_length;
- char *name;
- int type;
- int refcount;
- pointer private;
-} FontPathElementRec, *FontPathElementPtr;
-
-typedef struct _FPEFunctions {
- int (*name_check) ( /* name */ );
- int (*init_fpe) ( /* fpe */ );
- int (*reset_fpe) ( /* fpe */ );
- int (*free_fpe) ( /* fpe */ );
- int (*open_font) ( /* client, fpe, flags,
- name, namelen, format,
- fid, ppfont, alias */ );
- int (*close_font) ( /* pfont */ );
- int (*list_fonts) ( /* client, fpe, pattern,
- patlen, maxnames, paths */ );
- int (*start_list_fonts_with_info) (
- /* client, fpe, name, namelen,
- maxnames, data */ );
- int (*list_next_font_with_info) (
- /* client, fpe, name, namelen,
- info, num, data */ );
- int (*wakeup_fpe) ( /* fpe, mask */ );
- int (*client_died) ( /* client, fpe */ );
-} FPEFunctionsRec, FPEFunctions;
- </programlisting> <!-- .fi -->
-
- <para>
- The function pointers are split out from the data structure to
- save memory; additionally, this avoids any complications when
- initializing the data structure as there would not be any way
- to discover the appropriate function to call (a chicken and
- egg problem).
- </para>
-
- <para>
- When a font path type is initialized, it passes the function
- pointers to the server which are then stored in an
- <structname>FPEFunctionsRec</structname>. Each function is
- described below in turn.
- </para>
-
- <sect2 id='name_check'>
- <title>
- (*name_check)
- </title>
-
- <para>
- Each new font path member is passed to this function; if
- the return value is <errorname>Successful</errorname>, then
- the FPE recognises the format of the string. This does not
- guarantee that the FPE will be able to successfully use this
- member. For example, the disk-based font directory file
- <filename>fonts.dir</filename> may be corrupted, this will
- not be detected until the font path is initialized. This
- routine never returns <errorname>Suspended</errorname>.
- </para>
- </sect2>
-
- <sect2 id='init_fpe'>
- <title>
- (*init_fpe)
- </title>
-
- <para>
- Initialize a new font path element. This function prepares
- a new font path element for other requests: the disk font
- routine reads the <filename>fonts.dir</filename> and
- <filename>fonts.alias</filename> files into the internal
- format, while the font server routine connects to the
- requested font server and prepares for using it. This
- routine returns <errorname>Successful</errorname> if
- everything went OK, otherwise the return value indicates the
- source of the problem. This routine never returns
- <errorname>Suspended</errorname>.
- </para>
- </sect2>
-
- <sect2 id='reset_fpe'>
- <title>
- (*reset_fpe)
- </title>
-
- <para>
- When the X font path is reset, and some of the new members
- are also in the old font path, this function is called to
- reinitialize those FPEs. This routine returns
- <errorname>Successful</errorname> if everything went OK. It
- returns <errorname>FPEResetFailed</errorname> if (for some
- reason) the reset failed, and the caller should remove the
- old FPE and simply create a new one in its place. This is
- used by the disk-based fonts routine as resetting the
- internal directory structures would be more complicated than
- simply having destroying the old and creating a new.
- </para>
- </sect2>
-
- <sect2 id='free_fpe'>
- <title>
- (*free_fpe)
- </title>
-
- <para>
- When the server is finished with an FPE, this function is
- called to dispose of any internal state. It should return
- <errorname>Successful</errorname>, unless something terrible
- happens.
- </para>
- </sect2>
-
- <sect2 id='open_font'>
- <title>
- (*open_font)
- </title>
-
- <para>
- This routine requests that a font be opened. The <parameter
- class='function'>client</parameter> argument is used by the
- font library only in connection with suspending/restarting
- the request. The <parameter class='function'>flags</parameter>
- argument specifies some behaviour for the library and can be
- any of:
- </para>
-
- <programlisting remap='.nf'>
-/* OpenFont flags */
-#define FontLoadInfo 0x0001
-#define FontLoadProps 0x0002
-#define FontLoadMetrics 0x0004
-#define FontLoadBitmaps 0x0008
-#define FontLoadAll 0x000f
-#define FontOpenSync 0x0010
- </programlisting> <!-- .fi -->
-
- <para>
- The various fields specify which portions of the font should
- be loaded at this time. When <constant>FontOpenSync</constant>
- is specified, this routine will not return until all of the
- requested portions are loaded. Otherwise, this routine may
- return <errorname>Suspended</errorname>. When the presented
- font name is actually an alias for some other font name,
- <errorname>FontNameAlias</errorname> is returned, and the
- actual font name is stored in the location pointed to by the
- <parameter class='function'>alias</parameter> argument as a
- null-terminated string.
- </para>
- </sect2>
-
- <sect2 id='close_font'>
- <title>
- (*close_font)
- </title>
-
- <para>
- When the server is finished with a font, this routine
- disposes of any internal state and frees the font data
- structure.
- </para>
- </sect2>
-
- <sect2 id='list_fonts'>
- <title>
- (*list_fonts)
- </title>
-
- <para>
- The <parameter class='function'>paths</parameter> argument is
- a data structure which will be filled with all of the font names
- from this directory which match the specified
- <parameter class='function'>pattern</parameter>. At
- most <parameter class='function'>maxnames</parameter> will be added.
- This routine may return <errorname>Suspended</errorname>.
- </para>
- </sect2>
-
- <sect2 id='start_list_fonts_with_info'>
- <title>
- (*start_list_fonts_with_info)
- </title>
-
- <para>
- This routine sets any internal state for a verbose listing of
- all fonts matching the specified pattern. This routine may
- return <errorname>Suspended</errorname>.
- </para>
- </sect2>
-
- <sect2 id='list_next_font_with_info'>
- <title>
- (*list_next_font_with_info)
- </title>
-
- <para>
- To avoid storing huge amounts of data, the interface for
- ListFontsWithInfo allows the server to get one reply at a time
- and forward that to the client. When the font name returned
- is actually an alias for some other font,
- <errorname>FontNameAlias</errorname> will be returned. The
- actual font name is return instead, and the font alias which
- matched the pattern is returned in the location pointed to by
- data as a null-terminated string. The caller can then get the
- information by recursively listing that font name with a
- maxnames of 1. When <errorname>Successful</errorname> is
- returned, the matching font name is returned, and a
- FontInfoPtr is stored in the location pointed to by
- <parameter class='function'>data</parameter>.
- <parameter class='function'>Data</parameter> must be initialized
- with a pointer to a FontInfoRec allocated by the caller. When the
- pointer pointed to by <parameter class='function'>data</parameter>
- is not left pointing at that storage, the caller mustn't free the
- associated property data. This routine may return
- <errorname>Suspended</errorname>.
- </para>
- </sect2>
-
- <sect2 id='wakeup_fpe'>
- <title>
- (*wakeup_fpe)
- </title>
-
- <para>
- Whenever an FPE function has returned
- <errorname>Suspended</errorname>, this routine is called
- whenever the application wakes up from waiting for input
- (from <citerefentry><refentrytitle>select</refentrytitle>
- <manvolnum>2</manvolnum></citerefentry>). This
- <parameter class='function'>mask</parameter> argument should be
- the value returned from <function>select(2)</function>.
- </para>
- </sect2>
-
- <sect2 id='client_died'>
- <title>
- (*client_died)
- </title>
-
- <para>
- When an FPE function has returned <errorname>Suspended</errorname>
- and the associated client is being destroyed, this function
- allows the font library to dispose of any state associated
- with that client.
- </para>
- </sect2>
- </sect1>
-
- <sect1 id='fonts'>
- <title>
- Fonts
- </title>
-
- <para>
- The data structure which actually contains the font information has
- changed significantly since previous releases; it now attempts to
- hide the actual storage format for the data from the application,
- providing accessor functions to get at the data. This allows a
- range of internal details for different font sources. The structure
- is split into two pieces, so that ListFontsWithInfo can share
- information from the font when it has been loaded. The
- <structname>FontInfo</structname> structure, then, contains only
- information germane to LFWI.
- </para>
-
- <programlisting remap='.nf'>
-typedef struct _FontInfo {
- unsigned short firstCol; /* range of glyphs for this font */
- unsigned short lastCol;
- unsigned short firstRow;
- unsigned short lastRow;
- unsigned short defaultCh; /* default character index */
- unsigned int noOverlap:1; /* no combination of glyphs overlap */
- unsigned int terminalFont:1; /* Character cell font */
- unsigned int constantMetrics:1; /* all metrics are the same */
- unsigned int constantWidth:1; /* all character widths are the same*/
- unsigned int inkInside:1; /* all ink inside character cell */
- unsigned int inkMetrics:1; /* font has ink metrics */
- unsigned int allExist:1; /* no missing chars in range */
- unsigned int drawDirection:2; /* left-to-right/right-to-left*/
- unsigned int cachable:1; /* font needn't be opened each time*/
- unsigned int anamorphic:1; /* font is strangely scaled */
- short maxOverlap; /* maximum overlap amount */
- short pad; /* unused */
- xCharInfo maxbounds; /* glyph metrics maximums */
- xCharInfo minbounds; /* glyph metrics minimums */
- xCharInfo ink_maxbounds; /* ink metrics maximums */
- xCharInfo ink_minbounds; /* ink metrics minimums */
- short fontAscent; /* font ascent amount */
- short fontDescent; /* font descent amount */
- int nprops; /* number of font properties */
- FontPropPtr props; /* font properties */
- char *isStringProp; /* boolean array */
-} FontInfoRec, *FontInfoPtr;
- </programlisting> <!-- .fi -->
-
- <para>
- The font structure, then, contains a font info record, the format of
- the bits in each bitmap and the functions which access the font
- records (which are stored in an opaque format hung off of
- <structfield>fontPrivate</structfield>).
- </para>
-
- <programlisting remap='.nf'>
-typedef struct _Font {
- int refcnt;
- FontInfoRec info;
- char bit; /* bit order: LSBFirst/MSBFirst */
- char byte; /* byte order: LSBFirst/MSBFirst */
- char glyph; /* glyph pad: 1, 2, 4 or 8 */
- char scan; /* glyph scan unit: 1, 2 or 4 */
- fsBitmapFormat format; /* FS-style format (packed) */
- int (*get_glyphs) ( /* font, count, chars, encoding, count, glyphs */ );
- int (*get_metrics) ( /* font, count, chars, encoding, count, glyphs */ );
- int (*get_bitmaps) ( /* client, font, flags, format,
- flags, nranges, ranges, data_sizep,
- num_glyphsp, offsetsp, glyph_datap,
- free_datap */ );
- int (*get_extents) ( /* client, font, flags, nranges,
- ranges, nextentsp, extentsp */);
- void (*unload_font) ( /* font */ );
- FontPathElementPtr fpe; /* FPE associated with this font */
- pointer svrPrivate; /* X/FS private data */
- pointer fontPrivate; /* private to font */
- pointer fpePrivate; /* private to FPE */
- int maxPrivate; /* devPrivates (see below) */
- pointer *devPrivates; /* ... */
-} FontRec, *FontPtr;
- </programlisting> <!-- .fi -->
-
- <para>
- Yes, there are several different private pointers in the
- <structfield>Font</structfield> structure; they were added
- haphazardly until the devPrivate pointers were added. Future
- releases may remove some (or all) of the specific pointers,
- leaving only the <structfield>devPrivates</structfield>mechanism.
- </para>
-
- <para>
- There are two similar interfaces implemented -
- <structfield>get_glyphs</structfield>/<structfield>get_metrics</structfield>
- and
- <structfield>get_bitmaps</structfield>/<structfield>get_extents</structfield>.
- Too little time caused the font-server specific interfaces to
- be placed in the font library (and portions duplicated in each
- renderer) instead of having them integrated into the font server
- itself. This may change. The X server uses only
- <structfield>get_glyphs</structfield>/<structfield>get_metrics</structfield>,
- and those will not change dramatically. Each of the routines
- is described below.
- </para>
-
- <sect2 id='get_glyphs'>
- <title>
- (*get_glyphs)
- </title>
-
- <para>
- This routine returns <structname>CharInfoPtrs</structname>
- for each of the requested characters in the font. If the
- character does not exist in the font, the default character
- will be returned, unless no default character exists in
- which case that character is skipped. Thus, the number of
- glyphs returned will not always be the same as the number of
- characters passed in.
- </para>
- </sect2>
-
- <sect2 id='get_metrics'>
- <title>
- (*get_metrics)
- </title>
-
- <para>
- This is similar to <structfield>(*get_glyphs)</structfield>
- except that pointers to <structname>xCharInfo</structname>
- structures are returned, and, if the font has ink metrics,
- those are returned instead of the bitmap metrics.
- </para>
- </sect2>
-
- <sect2 id='getbitmaps'>
- <title>
- (*get_bitmaps)
- </title>
-
- <para>
- This packs the glyph image data in the requested
- <parameter class='function'>format</parameter> and returns it. The
- <parameter class='function'>ranges</parameter>/<parameter class='function'>nranges</parameter>
- argument specify the set of glyphs from the font to pack together.
- </para>
- </sect2>
-
- <sect2 id='get_extents'>
- <title>
- (*get_extents)
- </title>
-
- <para>
- This returns the metrics for the specified font from the
- specified <parameter class='function'>ranges</parameter>.
- </para>
-
- </sect2>
-
- <sect2 id='unload_font'>
- <title>
- (*unload_font)
- </title>
-
- <para>
- This is called from the FPE routine
- <function>(*close_font)</function>, and so should not ever be
- called from the application.
- </para>
- </sect2>
-
- <sect2 id='maxprivate'>
- <title>
- maxPrivate
- </title>
-
- <para>
- When initializing a new font structure,
- <structfield>maxPrivate</structfield> should be set to -1 so
- that the <function>FontSetPrivate()</function> macro works
- properly with an index of 0. Initializing
- <structfield>maxPrivate</structfield> to 0 can cause
- problems if the server tries to set something at index 0.
- </para>
- </sect2>
- </sect1>
- </article>
+<?xml version="1.0" encoding="UTF-8" ?> +<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" + "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" > +<!-- lifted from troff+ms by doclifter --> +<!-- previous version was in xorg-docs/specs/Xserver/fontlib.ms --> + + <article id='fontlib'> +<!-- .ps 12 --> +<!-- .EF 'Font Library Interface'\- % \-'July 27, 1991' --> +<!-- .OF 'Font Library Interface'\- % \-'July 27, 1991' --> +<!-- .EH '''' --> +<!-- .OH '''' --> +<!-- body begins here --> + <articleinfo> + <title> + The X Font Library + </title> + <pubdate>July 27, 1991</pubdate> + <authorgroup> + <author> + <firstname>Keith</firstname> + <surname>Packard</surname> + <affiliation> + <orgname>MIT X Consortium</orgname> + </affiliation> + </author> + <author> + <firstname>David</firstname> + <surname>Lemke</surname> + <affiliation> + <orgname>Network Computing Devices</orgname> + </affiliation> + </author> + </authorgroup> + <legalnotice> + <para> + Copyright 1993 <orgname>Network Computing Devices</orgname> + </para> + <para> + 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 Network Computing + Devices not be used in advertising or publicity pertaining + to distribution of the software without specific, written + prior permission. Network Computing Devices makes no + representations about the suitability of this software for + any purpose. It is provided “as is” without + express or implied warranty. + </para> + <para> + Copyright 1993, 1994 <orgname>X Consortium</orgname> + </para> + <para> + Permission is hereby granted, free of charge, to any person + obtaining a copy of this software and associated + documentation files (the “Software”), to deal in the + Software without restriction, including without limitation + the rights to use, copy, modify, merge, publish, distribute, + sublicense, and/or sell copies of the Software, and to + permit persons to whom the Software is furnished to do so, + subject to the following conditions: + </para><para> + The above copyright notice and this permission notice shall be + included in all copies or substantial portions of the Software. + </para><para> + THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY + OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO + THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR + PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE X + CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR + OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE + SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + </para><para> + Except as contained in this notice, the name of the X + Consortium shall not be used in advertising or otherwise to + promote the sale, use or other dealings in this Software + without prior written authorization from the X Consortium. + </para> + </legalnotice> + </articleinfo> + + <warning> + <para> + This document has not been updated since X11R6, and is likely + to be somewhat out of date for the current libXfont. + </para> + </warning> + + <para> + This document describes the data structures and interfaces for + using the X Font library. It is intended as a reference for + programmers building X and Font servers. You may want to refer + to the following documents: + </para> + + <itemizedlist> + <listitem> + <para> + <citetitle pubwork="article">Definition of the Porting Layer for + the X v11 Sample Server</citetitle> for a discussion on how this + library interacts with the X server + </para> + </listitem> + <listitem> + <para> + <citetitle pubwork="article">Font Server Implementation + Overview</citetitle> which discusses the design of the font + server. + </para> + </listitem> + <listitem> + <para> + <citetitle pubwork="article">Bitmap Distribution Format</citetitle> + which covers the contents of the bitmap font files which this + library reads; although the library is capable of reading other + formats as well, including non-bitmap fonts. + </para> + </listitem> + <listitem> + <para> + <citetitle pubwork="article">The X Font Service Protocol</citetitle> + for a description of the constraints placed on the design by + including support for this font service mechanism. + </para> + </listitem> + </itemizedlist> + + <para> + This document assumes the reader is familiar with the X server design, + the X protocol as it relates to fonts and the C programming language. + As with most MIT produced documentation, this relies heavily on the + source code, so have a listing handy. + </para> + + <sect1 id='requirements_for_the_font_library'> + <title> + Requirements for the Font library + </title> + + <para> + To avoid miles of duplicate code in the X server, the font server + and the various font manipulation tools, the font library should + provide interfaces appropriate for all of these tasks. In + particular, the X server and font server should be able to both + use the library to access disk based fonts, and to communicate + with a font server. By providing a general library, we hoped to + avoid duplicating code between the X server and font server. + </para> + + <para> + Another requirement is that the X server (or even a font server) + be able to continue servicing requests from other clients while + awaiting a response from the font server on behalf of one client. + This is the strongest requirement placed on the font library, and + has warped the design in curious ways. Because both the X server + and font server are single threaded, the font library must not + suspend internally, rather it returns an indication of suspension + to the application which continues processing other things, until + the font data is ready, at which time it restarts the suspended + request. + </para> + + <para> + Because the code for reading and manipulating bitmap font data is + used by the font applications <command>mkfontdir</command> and + <command>bdftopcf</command>, the font library includes + bitmap-font specific interfaces which those applications use, + instead of the more general interfaces used by the X and font + servers, which are unaware of the source of the font data. + These routines will be refered to as the bitmap font access + methods. + </para> + + </sect1> + + <sect1 id='general_font_library_interface_details'> + <title> + General Font Library Interface details. + </title> + + <para> + To avoid collision between the #define name space for errors, the Font + library defines a new set of return values: + </para> + + <programlisting remap='.nf'> +#define AllocError 80 +#define StillWorking 81 +#define FontNameAlias 82 +#define BadFontName 83 +#define Suspended 84 +#define Successful 85 +#define BadFontPath 86 +#define BadCharRange 87 +#define BadFontFormat 88 +#define FPEResetFailed 89 + </programlisting> <!-- .fi --> + + <para> + Whenever a routine returns <errorname>Suspended</errorname>, + the font library will notify the caller (via the ClientSignal + interface described below) who should then reinvoke the same routine + again with the same arguments. + </para> + + </sect1> + + <sect1 id='font_path_elements'> + <title> + Font Path Elements + </title> + + <para> + At the center of the general font access methods used by X and + <command>xfs</command> is the Font Path Element data structure. + Like most structures in the X server, this contains a collection + of data and some function pointers for manipulating this data: + </para> + + <programlisting remap='.nf'> +/* External view of font paths */ +typedef struct _FontPathElement { + int name_length; + char *name; + int type; + int refcount; + pointer private; +} FontPathElementRec, *FontPathElementPtr; + +typedef struct _FPEFunctions { + int (*name_check) ( /* name */ ); + int (*init_fpe) ( /* fpe */ ); + int (*reset_fpe) ( /* fpe */ ); + int (*free_fpe) ( /* fpe */ ); + int (*open_font) ( /* client, fpe, flags, + name, namelen, format, + fid, ppfont, alias */ ); + int (*close_font) ( /* pfont */ ); + int (*list_fonts) ( /* client, fpe, pattern, + patlen, maxnames, paths */ ); + int (*start_list_fonts_with_info) ( + /* client, fpe, name, namelen, + maxnames, data */ ); + int (*list_next_font_with_info) ( + /* client, fpe, name, namelen, + info, num, data */ ); + int (*wakeup_fpe) ( /* fpe, mask */ ); + int (*client_died) ( /* client, fpe */ ); +} FPEFunctionsRec, FPEFunctions; + </programlisting> <!-- .fi --> + + <para> + The function pointers are split out from the data structure to + save memory; additionally, this avoids any complications when + initializing the data structure as there would not be any way + to discover the appropriate function to call (a chicken and + egg problem). + </para> + + <para> + When a font path type is initialized, it passes the function + pointers to the server which are then stored in an + <structname>FPEFunctionsRec</structname>. Each function is + described below in turn. + </para> + + <sect2 id='name_check'> + <title> + (*name_check) + </title> + + <para> + Each new font path member is passed to this function; if + the return value is <errorname>Successful</errorname>, then + the FPE recognises the format of the string. This does not + guarantee that the FPE will be able to successfully use this + member. For example, the disk-based font directory file + <filename>fonts.dir</filename> may be corrupted, this will + not be detected until the font path is initialized. This + routine never returns <errorname>Suspended</errorname>. + </para> + </sect2> + + <sect2 id='init_fpe'> + <title> + (*init_fpe) + </title> + + <para> + Initialize a new font path element. This function prepares + a new font path element for other requests: the disk font + routine reads the <filename>fonts.dir</filename> and + <filename>fonts.alias</filename> files into the internal + format, while the font server routine connects to the + requested font server and prepares for using it. This + routine returns <errorname>Successful</errorname> if + everything went OK, otherwise the return value indicates the + source of the problem. This routine never returns + <errorname>Suspended</errorname>. + </para> + </sect2> + + <sect2 id='reset_fpe'> + <title> + (*reset_fpe) + </title> + + <para> + When the X font path is reset, and some of the new members + are also in the old font path, this function is called to + reinitialize those FPEs. This routine returns + <errorname>Successful</errorname> if everything went OK. It + returns <errorname>FPEResetFailed</errorname> if (for some + reason) the reset failed, and the caller should remove the + old FPE and simply create a new one in its place. This is + used by the disk-based fonts routine as resetting the + internal directory structures would be more complicated than + simply having destroying the old and creating a new. + </para> + </sect2> + + <sect2 id='free_fpe'> + <title> + (*free_fpe) + </title> + + <para> + When the server is finished with an FPE, this function is + called to dispose of any internal state. It should return + <errorname>Successful</errorname>, unless something terrible + happens. + </para> + </sect2> + + <sect2 id='open_font'> + <title> + (*open_font) + </title> + + <para> + This routine requests that a font be opened. The <parameter + class='function'>client</parameter> argument is used by the + font library only in connection with suspending/restarting + the request. The <parameter class='function'>flags</parameter> + argument specifies some behaviour for the library and can be + any of: + </para> + + <programlisting remap='.nf'> +/* OpenFont flags */ +#define FontLoadInfo 0x0001 +#define FontLoadProps 0x0002 +#define FontLoadMetrics 0x0004 +#define FontLoadBitmaps 0x0008 +#define FontLoadAll 0x000f +#define FontOpenSync 0x0010 + </programlisting> <!-- .fi --> + + <para> + The various fields specify which portions of the font should + be loaded at this time. When <constant>FontOpenSync</constant> + is specified, this routine will not return until all of the + requested portions are loaded. Otherwise, this routine may + return <errorname>Suspended</errorname>. When the presented + font name is actually an alias for some other font name, + <errorname>FontNameAlias</errorname> is returned, and the + actual font name is stored in the location pointed to by the + <parameter class='function'>alias</parameter> argument as a + null-terminated string. + </para> + </sect2> + + <sect2 id='close_font'> + <title> + (*close_font) + </title> + + <para> + When the server is finished with a font, this routine + disposes of any internal state and frees the font data + structure. + </para> + </sect2> + + <sect2 id='list_fonts'> + <title> + (*list_fonts) + </title> + + <para> + The <parameter class='function'>paths</parameter> argument is + a data structure which will be filled with all of the font names + from this directory which match the specified + <parameter class='function'>pattern</parameter>. At + most <parameter class='function'>maxnames</parameter> will be added. + This routine may return <errorname>Suspended</errorname>. + </para> + </sect2> + + <sect2 id='start_list_fonts_with_info'> + <title> + (*start_list_fonts_with_info) + </title> + + <para> + This routine sets any internal state for a verbose listing of + all fonts matching the specified pattern. This routine may + return <errorname>Suspended</errorname>. + </para> + </sect2> + + <sect2 id='list_next_font_with_info'> + <title> + (*list_next_font_with_info) + </title> + + <para> + To avoid storing huge amounts of data, the interface for + ListFontsWithInfo allows the server to get one reply at a time + and forward that to the client. When the font name returned + is actually an alias for some other font, + <errorname>FontNameAlias</errorname> will be returned. The + actual font name is return instead, and the font alias which + matched the pattern is returned in the location pointed to by + data as a null-terminated string. The caller can then get the + information by recursively listing that font name with a + maxnames of 1. When <errorname>Successful</errorname> is + returned, the matching font name is returned, and a + FontInfoPtr is stored in the location pointed to by + <parameter class='function'>data</parameter>. + <parameter class='function'>Data</parameter> must be initialized + with a pointer to a FontInfoRec allocated by the caller. When the + pointer pointed to by <parameter class='function'>data</parameter> + is not left pointing at that storage, the caller mustn't free the + associated property data. This routine may return + <errorname>Suspended</errorname>. + </para> + </sect2> + + <sect2 id='wakeup_fpe'> + <title> + (*wakeup_fpe) + </title> + + <para> + Whenever an FPE function has returned + <errorname>Suspended</errorname>, this routine is called + whenever the application wakes up from waiting for input + (from <citerefentry><refentrytitle>select</refentrytitle> + <manvolnum>2</manvolnum></citerefentry>). This + <parameter class='function'>mask</parameter> argument should be + the value returned from <function>select(2)</function>. + </para> + </sect2> + + <sect2 id='client_died'> + <title> + (*client_died) + </title> + + <para> + When an FPE function has returned <errorname>Suspended</errorname> + and the associated client is being destroyed, this function + allows the font library to dispose of any state associated + with that client. + </para> + </sect2> + </sect1> + + <sect1 id='fonts'> + <title> + Fonts + </title> + + <para> + The data structure which actually contains the font information has + changed significantly since previous releases; it now attempts to + hide the actual storage format for the data from the application, + providing accessor functions to get at the data. This allows a + range of internal details for different font sources. The structure + is split into two pieces, so that ListFontsWithInfo can share + information from the font when it has been loaded. The + <structname>FontInfo</structname> structure, then, contains only + information germane to LFWI. + </para> + + <programlisting remap='.nf'> +typedef struct _FontInfo { + unsigned short firstCol; /* range of glyphs for this font */ + unsigned short lastCol; + unsigned short firstRow; + unsigned short lastRow; + unsigned short defaultCh; /* default character index */ + unsigned int noOverlap:1; /* no combination of glyphs overlap */ + unsigned int terminalFont:1; /* Character cell font */ + unsigned int constantMetrics:1; /* all metrics are the same */ + unsigned int constantWidth:1; /* all character widths are the same*/ + unsigned int inkInside:1; /* all ink inside character cell */ + unsigned int inkMetrics:1; /* font has ink metrics */ + unsigned int allExist:1; /* no missing chars in range */ + unsigned int drawDirection:2; /* left-to-right/right-to-left*/ + unsigned int cachable:1; /* font needn't be opened each time*/ + unsigned int anamorphic:1; /* font is strangely scaled */ + short maxOverlap; /* maximum overlap amount */ + short pad; /* unused */ + xCharInfo maxbounds; /* glyph metrics maximums */ + xCharInfo minbounds; /* glyph metrics minimums */ + xCharInfo ink_maxbounds; /* ink metrics maximums */ + xCharInfo ink_minbounds; /* ink metrics minimums */ + short fontAscent; /* font ascent amount */ + short fontDescent; /* font descent amount */ + int nprops; /* number of font properties */ + FontPropPtr props; /* font properties */ + char *isStringProp; /* boolean array */ +} FontInfoRec, *FontInfoPtr; + </programlisting> <!-- .fi --> + + <para> + The font structure, then, contains a font info record, the format of + the bits in each bitmap and the functions which access the font + records (which are stored in an opaque format hung off of + <structfield>fontPrivate</structfield>). + </para> + + <programlisting remap='.nf'> +typedef struct _Font { + int refcnt; + FontInfoRec info; + char bit; /* bit order: LSBFirst/MSBFirst */ + char byte; /* byte order: LSBFirst/MSBFirst */ + char glyph; /* glyph pad: 1, 2, 4 or 8 */ + char scan; /* glyph scan unit: 1, 2 or 4 */ + fsBitmapFormat format; /* FS-style format (packed) */ + int (*get_glyphs) ( /* font, count, chars, encoding, count, glyphs */ ); + int (*get_metrics) ( /* font, count, chars, encoding, count, glyphs */ ); + int (*get_bitmaps) ( /* client, font, flags, format, + flags, nranges, ranges, data_sizep, + num_glyphsp, offsetsp, glyph_datap, + free_datap */ ); + int (*get_extents) ( /* client, font, flags, nranges, + ranges, nextentsp, extentsp */); + void (*unload_font) ( /* font */ ); + FontPathElementPtr fpe; /* FPE associated with this font */ + pointer svrPrivate; /* X/FS private data */ + pointer fontPrivate; /* private to font */ + pointer fpePrivate; /* private to FPE */ + int maxPrivate; /* devPrivates (see below) */ + pointer *devPrivates; /* ... */ +} FontRec, *FontPtr; + </programlisting> <!-- .fi --> + + <para> + Yes, there are several different private pointers in the + <structfield>Font</structfield> structure; they were added + haphazardly until the devPrivate pointers were added. Future + releases may remove some (or all) of the specific pointers, + leaving only the <structfield>devPrivates</structfield>mechanism. + </para> + + <para> + There are two similar interfaces implemented - + <structfield>get_glyphs</structfield>/<structfield>get_metrics</structfield> + and + <structfield>get_bitmaps</structfield>/<structfield>get_extents</structfield>. + Too little time caused the font-server specific interfaces to + be placed in the font library (and portions duplicated in each + renderer) instead of having them integrated into the font server + itself. This may change. The X server uses only + <structfield>get_glyphs</structfield>/<structfield>get_metrics</structfield>, + and those will not change dramatically. Each of the routines + is described below. + </para> + + <sect2 id='get_glyphs'> + <title> + (*get_glyphs) + </title> + + <para> + This routine returns <structname>CharInfoPtrs</structname> + for each of the requested characters in the font. If the + character does not exist in the font, the default character + will be returned, unless no default character exists in + which case that character is skipped. Thus, the number of + glyphs returned will not always be the same as the number of + characters passed in. + </para> + </sect2> + + <sect2 id='get_metrics'> + <title> + (*get_metrics) + </title> + + <para> + This is similar to <structfield>(*get_glyphs)</structfield> + except that pointers to <structname>xCharInfo</structname> + structures are returned, and, if the font has ink metrics, + those are returned instead of the bitmap metrics. + </para> + </sect2> + + <sect2 id='getbitmaps'> + <title> + (*get_bitmaps) + </title> + + <para> + This packs the glyph image data in the requested + <parameter class='function'>format</parameter> and returns it. The + <parameter class='function'>ranges</parameter>/<parameter class='function'>nranges</parameter> + argument specify the set of glyphs from the font to pack together. + </para> + </sect2> + + <sect2 id='get_extents'> + <title> + (*get_extents) + </title> + + <para> + This returns the metrics for the specified font from the + specified <parameter class='function'>ranges</parameter>. + </para> + + </sect2> + + <sect2 id='unload_font'> + <title> + (*unload_font) + </title> + + <para> + This is called from the FPE routine + <function>(*close_font)</function>, and so should not ever be + called from the application. + </para> + </sect2> + + <sect2 id='maxprivate'> + <title> + maxPrivate + </title> + + <para> + When initializing a new font structure, + <structfield>maxPrivate</structfield> should be set to -1 so + that the <function>FontSetPrivate()</function> macro works + properly with an index of 0. Initializing + <structfield>maxPrivate</structfield> to 0 can cause + problems if the server tries to set something at index 0. + </para> + </sect2> + </sect1> + </article> |