404 lines
18 KiB
Plaintext
404 lines
18 KiB
Plaintext
.\" 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.
|