path: root/doc
diff options
authorAlan Coopersmith <>2009-10-07 08:31:54 -0700
committerAlan Coopersmith <>2009-10-07 08:31:54 -0700
commit96a4daad7097ce94d4340a4e9ce779e378f9b83c (patch)
tree328a340bb268f637d570e704bb75eb848e49873f /doc
parentb7be4a976a59f3149590cf62a2ea8144aa729c2a (diff)
Move from xorg-docs
Signed-off-by: Alan Coopersmith <>
Diffstat (limited to 'doc')
1 files changed, 403 insertions, 0 deletions
diff --git a/doc/ b/doc/
new file mode 100644
index 0000000..f4f3b07
--- /dev/null
+++ b/doc/
@@ -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.
+.\" 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. 12 PS 12 Cs
+.ft C
+.. Ce
+.ft P
+.\" $Xorg:,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 ''''
+The X Font Library
+Keith Packard
+MIT X Consortium
+David Lemke
+Network Computing Devices
+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
+.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.
+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
+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.
+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.
+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.
+To avoid collision between the #define name space for errors, the Font
+library defines a new set of return values:
+#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
+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
+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:
+/* 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;
+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).
+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
+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
+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
+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
+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
+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:
+/* OpenFont flags */
+#define FontLoadInfo 0x0001
+#define FontLoadProps 0x0002
+#define FontLoadMetrics 0x0004
+#define FontLoadBitmaps 0x0008
+#define FontLoadAll 0x000f
+#define FontOpenSync 0x0010
+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
+When the server is finished with a font, this routine disposes of any
+internal state and frees the font data structure.
+.NH 2
+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
+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
+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
+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
+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
+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
+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;
+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).
+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;
+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.
+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
+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
+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
+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
+.NH 2
+This returns the metrics for the specified font from the specified ranges.
+.NH 2
+This is called from the FPE routine (*close_font), and so should not ever be
+called from the application.
+.NH 2
+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.