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 cce83e9bd..3b0829d30 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>
|