Move fontlib.ms from xorg-docs

Signed-off-by: Alan Coopersmith <alan.coopersmith@sun.com>

1 files changed, 403 insertions, 0 deletions

diff --git a/doc/fontlib.ms b/doc/fontlib.ms
new file mode 100644
index 0000000..f4f3b07
--- /dev/null
+++ b/doc/fontlib.ms
@@ -0,0 +1,403 @@
+.\" Copyright 1993 Network Computing Devices
+.\" 
+.\" 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.
+.\"
+.\" Copyright 1993, 1994 X Consortium
+.\"
+.\" 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:
+.\" 
+.\" The above copyright notice and this permission notice shall be
+.\" included in all copies or substantial portions of the Software.
+.\" 
+.\" 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.
+.\" 
+.\" 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.
+.ps 12
+.nr PS 12
+.de Cs
+.IP
+.nf
+.ft C
+..
+.de Ce
+.ft P
+.fi
+..
+.\" $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 ''''
+.TL
+The X Font Library
+.AU
+Keith Packard
+.AI
+MIT X Consortium
+.AU
+David Lemke
+.AI
+Network Computing Devices
+.LP
+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:
+.IP \(bu 5
+"Definition of the Porting Layer for the X v11 Sample Server" for a
+discussion on how this library interacts with the X server
+.IP \(bu 5
+"Font Server Implementation Overview" which discusses the design of the font
+server.
+.IP \(bu 5
+"Bitmap Distribution Format" 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.
+.IP \(bu 5
+"The X Font Service Protocol" for a description of the constraints placed on
+the design by including support for this font service mechanism.
+.LP
+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.
+.NH 1
+Requirements for the Font library
+.LP
+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.
+.LP
+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.
+.LP
+Because the code for reading and manipulating bitmap font data is used by
+the font applications "mkfontdir" and "bdftopcf", 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.
+.NH 1
+General Font Library Interface details.
+.LP
+To avoid collision between the #define name space for errors, the Font
+library defines a new set of return values:
+.Cs
+#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
+.Ce
+.LP
+Whenever a routine returns \fBSuspended\fP, 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.
+.NH 1
+Font Path Elements
+.LP
+At the center of the general font access methods used by X and fs 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:
+.Cs
+/* 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;
+.Ce
+.LP
+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).
+.LP
+When a font path type is initialized, it passes the function pointers to the
+server which are then stored in an FPEFunctionsRec.  Each function is
+described below in turn.
+.NH 2
+(*name_check)
+.LP
+Each new font path member is passed to this function; if the return value
+is Successful, 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 "fonts.dir" may be
+corrupted, this will not be detected until the font path is initialized.
+This routine never returns \fBSuspended\fP.
+.NH 2
+(*init_fpe)
+.LP
+Initialize a new font path element.  This function prepares a new font path
+element for other requests:  the disk font routine reads the "fonts.dir" and
+"fonts.alias" files into the internal format, while the font server routine
+connects to the requested font server and prepares for using it.  This
+routine returns Successful if everything went OK, otherwise the return value
+indicates the source of the problem.  This routine never returns \fBSuspended\fP.
+.NH 2
+(*reset_fpe)
+.LP
+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 Successful if everything went OK.  It returns FPEResetFailed
+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.
+.NH 2
+(*free_fpe)
+.LP
+When the server is finished with an FPE, this function is called to dispose
+of any internal state.  It should return Successful, unless something
+terrible happens.
+.NH 2
+(*open_font)
+.LP
+This routine requests that a font be opened.  The client argument is used
+by the font library only in connection with suspending/restarting the
+request.  The flags argument specifies some behaviour for the library and can
+be any of:
+.Cs
+/* OpenFont flags */
+#define FontLoadInfo    0x0001
+#define FontLoadProps   0x0002
+#define FontLoadMetrics 0x0004
+#define FontLoadBitmaps 0x0008
+#define FontLoadAll     0x000f
+#define FontOpenSync    0x0010
+.Ce
+.LP
+The various fields specify which portions of the font should be loaded at
+this time.  When FontOpenSync is specified, this routine will not return
+until all of the requested portions are loaded.  Otherwise, this routine may
+return \fBSuspended\fP.  When the presented font name is actually an alias
+for some other font name, FontName Alias is returned, and the actual font
+name is stored in the location pointed to by the \fIalias\fP argument as a
+null-terminated string.
+.NH 2
+(*close_font)
+.LP
+When the server is finished with a font, this routine disposes of any
+internal state and frees the font data structure.
+.NH 2
+(*list_fonts)
+.LP
+The \fIpaths\fP argument is a data structure which will be filled with all
+of the font names from this directory which match the specified pattern.  At
+most \fImaxnames\fP will be added.  This routine may return \fBSuspended\fP.
+.NH 2
+(*start_list_fonts_with_info)
+.LP
+This routine sets any internal state for a verbose listing of all fonts
+matching the specified pattern.  This routine may return \fBSuspended\fP.
+.NH 2
+(*list_next_font_with_info)
+.LP
+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, \fBFontNameAlias\fP 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 \fBSuccessful\fP is returned, the matching font name is
+returned, and a FontInfoPtr is stored in the location pointed to by
+\fIdata\fP.  \fIData\fP must be initialized with a pointer to a FontInfoRec
+allocated by the caller.  When the pointer pointed to by \fIdata\fP is not
+left pointing at that storage, the caller mustn't free the associated
+property data.  This routine may return \fBSuspended\fP.
+.NH 2
+(*wakeup_fpe)
+.LP
+Whenever an FPE function has returned Suspended, this routine is called
+whenever the application wakes up from waiting for input (from select(2)).
+This mask argument should be the value returned from select(2).
+.NH 2
+(*client_died)
+.LP
+When an FPE function has returned \fBSuspended\fP and the associated client
+is being destroyed, this function allows the font library to dispose of any
+state associated with that client.
+.NH 1
+Fonts
+.LP
+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 FontInfo structure, then, contains only information germane to
+LFWI.
+.Cs
+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;
+.Ce
+.LP
+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 fontPrivate).
+.Cs
+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;
+.Ce
+.LP
+Yes, there are several different private pointers in the Font 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
+devPrivates mechanism.
+.LP
+There are two similar interfaces implemented - get_glyphs/get_metrics and
+get_bitmaps/get_extents.  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 get_glyphs/get_metrics, and those
+will not change dramatically.  Each of the routines is described below
+.NH 2
+(*get_glyphs)
+.LP
+This routine returns CharInfoPtrs 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.
+.NH 2
+(*get_metrics)
+.LP
+This is similar to (*get_glyphs) except that pointers to xCharInfo
+structures are returned, and, if the font has ink metrics, those are
+returned instead of the bitmap metrics.
+.NH 2
+(*get-bitmaps)
+.LP
+This packs the glyph image data in the requested format and returns it.  The
+ranges/nranges argument specify the set of glyphs from the font to pack
+together.
+.NH 2
+(*get_extents)
+.LP
+This returns the metrics for the specified font from the specified ranges.
+.LP
+.NH 2
+(*unload_font)
+.LP
+This is called from the FPE routine (*close_font), and so should not ever be
+called from the application.
+.NH 2
+maxPrivate
+.LP
+When initializing a new font structure, maxPrivate should be set to -1
+so that the FontSetPrivate() macro works properly with an index of 0.
+Initializing maxPrivate to 0 can cause problems if the server tries to set 
+something at index 0.