svn merge ^/branches/released .

1 files changed, 659 insertions, 660 deletions

diff --git a/libXfont/doc/fontlib.xml b/libXfont/doc/fontlib.xml
index 8b7245ef1..e6755c928 100644
--- a/libXfont/doc/fontlib.xml
+++ b/libXfont/doc/fontlib.xml
@@ -1,660 +1,659 @@
-<?xml version="1.0" encoding="UTF-8" ?>
-<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
-            "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" >
-<!-- lifted from troff+ms by doclifter -->
-<!-- previous version was in xorg-docs/specs/Xserver/fontlib.ms -->
-
-  <article id='fontlibms'>
-<!-- .ps 12 -->
-<!--  $Xorg: fontlib.ms,v 1.3 2000/08/17 19:42:42 cpqbld Exp $ -->
-<!-- .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 &ldquo;as is&rdquo; 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 &ldquo;Software&rdquo;), 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 &ldquo;AS IS&rdquo;, 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.4//EN"

+            "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" >

+<!-- lifted from troff+ms by doclifter -->

+<!-- previous version was in xorg-docs/specs/Xserver/fontlib.ms -->

+

+  <article id='fontlibms'>

+<!-- .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 &ldquo;as is&rdquo; 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 &ldquo;Software&rdquo;), 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 &ldquo;AS IS&rdquo;, 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>