diff options
Diffstat (limited to 'doc/fontlib.ms')
| -rw-r--r-- | doc/fontlib.ms | 403 |
1 files changed, 0 insertions, 403 deletions
diff --git a/doc/fontlib.ms b/doc/fontlib.ms deleted file mode 100644 index f4f3b07..0000000 --- a/doc/fontlib.ms +++ /dev/null @@ -1,403 +0,0 @@ -.\" 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. |