1 <?xml version="1.0" encoding="UTF-8" ?>
2 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
3 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" >
4 <!-- lifted from troff+ms by doclifter -->
5 <!-- previous version was in xorg-docs/specs/Xserver/fontlib.ms -->
7 <article id='fontlibms'>
9 <!-- .EF 'Font Library Interface'\- % \-'July 27, 1991' -->
10 <!-- .OF 'Font Library Interface'\- % \-'July 27, 1991' -->
13 <!-- body begins here -->
18 <pubdate>July 27, 1991</pubdate>
21 <firstname>Keith</firstname>
22 <surname>Packard</surname>
24 <orgname>MIT X Consortium</orgname>
28 <firstname>David</firstname>
29 <surname>Lemke</surname>
31 <orgname>Network Computing Devices</orgname>
37 Copyright 1993 <orgname>Network Computing Devices</orgname>
40 Permission to use, copy, modify, distribute, and sell this
41 software and its documentation for any purpose is hereby
42 granted without fee, provided that the above copyright
43 notice appear in all copies and that both that copyright
44 notice and this permission notice appear in supporting
45 documentation, and that the name of Network Computing
46 Devices not be used in advertising or publicity pertaining
47 to distribution of the software without specific, written
48 prior permission. Network Computing Devices makes no
49 representations about the suitability of this software for
50 any purpose. It is provided “as is” without
51 express or implied warranty.
54 Copyright 1993, 1994 <orgname>X Consortium</orgname>
57 Permission is hereby granted, free of charge, to any person
58 obtaining a copy of this software and associated
59 documentation files (the “Software”), to deal in the
60 Software without restriction, including without limitation
61 the rights to use, copy, modify, merge, publish, distribute,
62 sublicense, and/or sell copies of the Software, and to
63 permit persons to whom the Software is furnished to do so,
64 subject to the following conditions:
66 The above copyright notice and this permission notice shall be
67 included in all copies or substantial portions of the Software.
69 THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY
70 OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO
71 THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
72 PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE X
73 CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
74 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
75 OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
76 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
78 Except as contained in this notice, the name of the X
79 Consortium shall not be used in advertising or otherwise to
80 promote the sale, use or other dealings in this Software
81 without prior written authorization from the X Consortium.
88 This document has not been updated since X11R6, and is likely
89 to be somewhat out of date for the current libXfont.
94 This document describes the data structures and interfaces for
95 using the X Font library. It is intended as a reference for
96 programmers building X and Font servers. You may want to refer
97 to the following documents:
103 <citetitle pubwork="article">Definition of the Porting Layer for
104 the X v11 Sample Server</citetitle> for a discussion on how this
105 library interacts with the X server
110 <citetitle pubwork="article">Font Server Implementation
111 Overview</citetitle> which discusses the design of the font
117 <citetitle pubwork="article">Bitmap Distribution Format</citetitle>
118 which covers the contents of the bitmap font files which this
119 library reads; although the library is capable of reading other
120 formats as well, including non-bitmap fonts.
125 <citetitle pubwork="article">The X Font Service Protocol</citetitle>
126 for a description of the constraints placed on the design by
127 including support for this font service mechanism.
133 This document assumes the reader is familiar with the X server design,
134 the X protocol as it relates to fonts and the C programming language.
135 As with most MIT produced documentation, this relies heavily on the
136 source code, so have a listing handy.
139 <sect1 id='requirements_for_the_font_library'>
141 Requirements for the Font library
145 To avoid miles of duplicate code in the X server, the font server
146 and the various font manipulation tools, the font library should
147 provide interfaces appropriate for all of these tasks. In
148 particular, the X server and font server should be able to both
149 use the library to access disk based fonts, and to communicate
150 with a font server. By providing a general library, we hoped to
151 avoid duplicating code between the X server and font server.
155 Another requirement is that the X server (or even a font server)
156 be able to continue servicing requests from other clients while
157 awaiting a response from the font server on behalf of one client.
158 This is the strongest requirement placed on the font library, and
159 has warped the design in curious ways. Because both the X server
160 and font server are single threaded, the font library must not
161 suspend internally, rather it returns an indication of suspension
162 to the application which continues processing other things, until
163 the font data is ready, at which time it restarts the suspended
168 Because the code for reading and manipulating bitmap font data is
169 used by the font applications <command>mkfontdir</command> and
170 <command>bdftopcf</command>, the font library includes
171 bitmap-font specific interfaces which those applications use,
172 instead of the more general interfaces used by the X and font
173 servers, which are unaware of the source of the font data.
174 These routines will be refered to as the bitmap font access
180 <sect1 id='general_font_library_interface_details'>
182 General Font Library Interface details.
186 To avoid collision between the #define name space for errors, the Font
187 library defines a new set of return values:
190 <programlisting remap='.nf'>
191 #define AllocError 80
192 #define StillWorking 81
193 #define FontNameAlias 82
194 #define BadFontName 83
196 #define Successful 85
197 #define BadFontPath 86
198 #define BadCharRange 87
199 #define BadFontFormat 88
200 #define FPEResetFailed 89
201 </programlisting> <!-- .fi -->
204 Whenever a routine returns <errorname>Suspended</errorname>,
205 the font library will notify the caller (via the ClientSignal
206 interface described below) who should then reinvoke the same routine
207 again with the same arguments.
212 <sect1 id='font_path_elements'>
218 At the center of the general font access methods used by X and
219 <command>xfs</command> is the Font Path Element data structure.
220 Like most structures in the X server, this contains a collection
221 of data and some function pointers for manipulating this data:
224 <programlisting remap='.nf'>
225 /* External view of font paths */
226 typedef struct _FontPathElement {
232 } FontPathElementRec, *FontPathElementPtr;
234 typedef struct _FPEFunctions {
235 int (*name_check) ( /* name */ );
236 int (*init_fpe) ( /* fpe */ );
237 int (*reset_fpe) ( /* fpe */ );
238 int (*free_fpe) ( /* fpe */ );
239 int (*open_font) ( /* client, fpe, flags,
240 name, namelen, format,
241 fid, ppfont, alias */ );
242 int (*close_font) ( /* pfont */ );
243 int (*list_fonts) ( /* client, fpe, pattern,
244 patlen, maxnames, paths */ );
245 int (*start_list_fonts_with_info) (
246 /* client, fpe, name, namelen,
248 int (*list_next_font_with_info) (
249 /* client, fpe, name, namelen,
250 info, num, data */ );
251 int (*wakeup_fpe) ( /* fpe, mask */ );
252 int (*client_died) ( /* client, fpe */ );
253 } FPEFunctionsRec, FPEFunctions;
254 </programlisting> <!-- .fi -->
257 The function pointers are split out from the data structure to
258 save memory; additionally, this avoids any complications when
259 initializing the data structure as there would not be any way
260 to discover the appropriate function to call (a chicken and
265 When a font path type is initialized, it passes the function
266 pointers to the server which are then stored in an
267 <structname>FPEFunctionsRec</structname>. Each function is
268 described below in turn.
271 <sect2 id='name_check'>
277 Each new font path member is passed to this function; if
278 the return value is <errorname>Successful</errorname>, then
279 the FPE recognises the format of the string. This does not
280 guarantee that the FPE will be able to successfully use this
281 member. For example, the disk-based font directory file
282 <filename>fonts.dir</filename> may be corrupted, this will
283 not be detected until the font path is initialized. This
284 routine never returns <errorname>Suspended</errorname>.
288 <sect2 id='init_fpe'>
294 Initialize a new font path element. This function prepares
295 a new font path element for other requests: the disk font
296 routine reads the <filename>fonts.dir</filename> and
297 <filename>fonts.alias</filename> files into the internal
298 format, while the font server routine connects to the
299 requested font server and prepares for using it. This
300 routine returns <errorname>Successful</errorname> if
301 everything went OK, otherwise the return value indicates the
302 source of the problem. This routine never returns
303 <errorname>Suspended</errorname>.
307 <sect2 id='reset_fpe'>
313 When the X font path is reset, and some of the new members
314 are also in the old font path, this function is called to
315 reinitialize those FPEs. This routine returns
316 <errorname>Successful</errorname> if everything went OK. It
317 returns <errorname>FPEResetFailed</errorname> if (for some
318 reason) the reset failed, and the caller should remove the
319 old FPE and simply create a new one in its place. This is
320 used by the disk-based fonts routine as resetting the
321 internal directory structures would be more complicated than
322 simply having destroying the old and creating a new.
326 <sect2 id='free_fpe'>
332 When the server is finished with an FPE, this function is
333 called to dispose of any internal state. It should return
334 <errorname>Successful</errorname>, unless something terrible
339 <sect2 id='open_font'>
345 This routine requests that a font be opened. The <parameter
346 class='function'>client</parameter> argument is used by the
347 font library only in connection with suspending/restarting
348 the request. The <parameter class='function'>flags</parameter>
349 argument specifies some behaviour for the library and can be
353 <programlisting remap='.nf'>
355 #define FontLoadInfo 0x0001
356 #define FontLoadProps 0x0002
357 #define FontLoadMetrics 0x0004
358 #define FontLoadBitmaps 0x0008
359 #define FontLoadAll 0x000f
360 #define FontOpenSync 0x0010
361 </programlisting> <!-- .fi -->
364 The various fields specify which portions of the font should
365 be loaded at this time. When <constant>FontOpenSync</constant>
366 is specified, this routine will not return until all of the
367 requested portions are loaded. Otherwise, this routine may
368 return <errorname>Suspended</errorname>. When the presented
369 font name is actually an alias for some other font name,
370 <errorname>FontNameAlias</errorname> is returned, and the
371 actual font name is stored in the location pointed to by the
372 <parameter class='function'>alias</parameter> argument as a
373 null-terminated string.
377 <sect2 id='close_font'>
383 When the server is finished with a font, this routine
384 disposes of any internal state and frees the font data
389 <sect2 id='list_fonts'>
395 The <parameter class='function'>paths</parameter> argument is
396 a data structure which will be filled with all of the font names
397 from this directory which match the specified
398 <parameter class='function'>pattern</parameter>. At
399 most <parameter class='function'>maxnames</parameter> will be added.
400 This routine may return <errorname>Suspended</errorname>.
404 <sect2 id='start_list_fonts_with_info'>
406 (*start_list_fonts_with_info)
410 This routine sets any internal state for a verbose listing of
411 all fonts matching the specified pattern. This routine may
412 return <errorname>Suspended</errorname>.
416 <sect2 id='list_next_font_with_info'>
418 (*list_next_font_with_info)
422 To avoid storing huge amounts of data, the interface for
423 ListFontsWithInfo allows the server to get one reply at a time
424 and forward that to the client. When the font name returned
425 is actually an alias for some other font,
426 <errorname>FontNameAlias</errorname> will be returned. The
427 actual font name is return instead, and the font alias which
428 matched the pattern is returned in the location pointed to by
429 data as a null-terminated string. The caller can then get the
430 information by recursively listing that font name with a
431 maxnames of 1. When <errorname>Successful</errorname> is
432 returned, the matching font name is returned, and a
433 FontInfoPtr is stored in the location pointed to by
434 <parameter class='function'>data</parameter>.
435 <parameter class='function'>Data</parameter> must be initialized
436 with a pointer to a FontInfoRec allocated by the caller. When the
437 pointer pointed to by <parameter class='function'>data</parameter>
438 is not left pointing at that storage, the caller mustn't free the
439 associated property data. This routine may return
440 <errorname>Suspended</errorname>.
444 <sect2 id='wakeup_fpe'>
450 Whenever an FPE function has returned
451 <errorname>Suspended</errorname>, this routine is called
452 whenever the application wakes up from waiting for input
453 (from <citerefentry><refentrytitle>select</refentrytitle>
454 <manvolnum>2</manvolnum></citerefentry>). This
455 <parameter class='function'>mask</parameter> argument should be
456 the value returned from <function>select(2)</function>.
460 <sect2 id='client_died'>
466 When an FPE function has returned <errorname>Suspended</errorname>
467 and the associated client is being destroyed, this function
468 allows the font library to dispose of any state associated
480 The data structure which actually contains the font information has
481 changed significantly since previous releases; it now attempts to
482 hide the actual storage format for the data from the application,
483 providing accessor functions to get at the data. This allows a
484 range of internal details for different font sources. The structure
485 is split into two pieces, so that ListFontsWithInfo can share
486 information from the font when it has been loaded. The
487 <structname>FontInfo</structname> structure, then, contains only
488 information germane to LFWI.
491 <programlisting remap='.nf'>
492 typedef struct _FontInfo {
493 unsigned short firstCol; /* range of glyphs for this font */
494 unsigned short lastCol;
495 unsigned short firstRow;
496 unsigned short lastRow;
497 unsigned short defaultCh; /* default character index */
498 unsigned int noOverlap:1; /* no combination of glyphs overlap */
499 unsigned int terminalFont:1; /* Character cell font */
500 unsigned int constantMetrics:1; /* all metrics are the same */
501 unsigned int constantWidth:1; /* all character widths are the same*/
502 unsigned int inkInside:1; /* all ink inside character cell */
503 unsigned int inkMetrics:1; /* font has ink metrics */
504 unsigned int allExist:1; /* no missing chars in range */
505 unsigned int drawDirection:2; /* left-to-right/right-to-left*/
506 unsigned int cachable:1; /* font needn't be opened each time*/
507 unsigned int anamorphic:1; /* font is strangely scaled */
508 short maxOverlap; /* maximum overlap amount */
509 short pad; /* unused */
510 xCharInfo maxbounds; /* glyph metrics maximums */
511 xCharInfo minbounds; /* glyph metrics minimums */
512 xCharInfo ink_maxbounds; /* ink metrics maximums */
513 xCharInfo ink_minbounds; /* ink metrics minimums */
514 short fontAscent; /* font ascent amount */
515 short fontDescent; /* font descent amount */
516 int nprops; /* number of font properties */
517 FontPropPtr props; /* font properties */
518 char *isStringProp; /* boolean array */
519 } FontInfoRec, *FontInfoPtr;
520 </programlisting> <!-- .fi -->
523 The font structure, then, contains a font info record, the format of
524 the bits in each bitmap and the functions which access the font
525 records (which are stored in an opaque format hung off of
526 <structfield>fontPrivate</structfield>).
529 <programlisting remap='.nf'>
530 typedef struct _Font {
533 char bit; /* bit order: LSBFirst/MSBFirst */
534 char byte; /* byte order: LSBFirst/MSBFirst */
535 char glyph; /* glyph pad: 1, 2, 4 or 8 */
536 char scan; /* glyph scan unit: 1, 2 or 4 */
537 fsBitmapFormat format; /* FS-style format (packed) */
538 int (*get_glyphs) ( /* font, count, chars, encoding, count, glyphs */ );
539 int (*get_metrics) ( /* font, count, chars, encoding, count, glyphs */ );
540 int (*get_bitmaps) ( /* client, font, flags, format,
541 flags, nranges, ranges, data_sizep,
542 num_glyphsp, offsetsp, glyph_datap,
544 int (*get_extents) ( /* client, font, flags, nranges,
545 ranges, nextentsp, extentsp */);
546 void (*unload_font) ( /* font */ );
547 FontPathElementPtr fpe; /* FPE associated with this font */
548 pointer svrPrivate; /* X/FS private data */
549 pointer fontPrivate; /* private to font */
550 pointer fpePrivate; /* private to FPE */
551 int maxPrivate; /* devPrivates (see below) */
552 pointer *devPrivates; /* ... */
554 </programlisting> <!-- .fi -->
557 Yes, there are several different private pointers in the
558 <structfield>Font</structfield> structure; they were added
559 haphazardly until the devPrivate pointers were added. Future
560 releases may remove some (or all) of the specific pointers,
561 leaving only the <structfield>devPrivates</structfield>mechanism.
565 There are two similar interfaces implemented -
566 <structfield>get_glyphs</structfield>/<structfield>get_metrics</structfield>
568 <structfield>get_bitmaps</structfield>/<structfield>get_extents</structfield>.
569 Too little time caused the font-server specific interfaces to
570 be placed in the font library (and portions duplicated in each
571 renderer) instead of having them integrated into the font server
572 itself. This may change. The X server uses only
573 <structfield>get_glyphs</structfield>/<structfield>get_metrics</structfield>,
574 and those will not change dramatically. Each of the routines
578 <sect2 id='get_glyphs'>
584 This routine returns <structname>CharInfoPtrs</structname>
585 for each of the requested characters in the font. If the
586 character does not exist in the font, the default character
587 will be returned, unless no default character exists in
588 which case that character is skipped. Thus, the number of
589 glyphs returned will not always be the same as the number of
590 characters passed in.
594 <sect2 id='get_metrics'>
600 This is similar to <structfield>(*get_glyphs)</structfield>
601 except that pointers to <structname>xCharInfo</structname>
602 structures are returned, and, if the font has ink metrics,
603 those are returned instead of the bitmap metrics.
607 <sect2 id='getbitmaps'>
613 This packs the glyph image data in the requested
614 <parameter class='function'>format</parameter> and returns it. The
615 <parameter class='function'>ranges</parameter>/<parameter class='function'>nranges</parameter>
616 argument specify the set of glyphs from the font to pack together.
620 <sect2 id='get_extents'>
626 This returns the metrics for the specified font from the
627 specified <parameter class='function'>ranges</parameter>.
632 <sect2 id='unload_font'>
638 This is called from the FPE routine
639 <function>(*close_font)</function>, and so should not ever be
640 called from the application.
644 <sect2 id='maxprivate'>
650 When initializing a new font structure,
651 <structfield>maxPrivate</structfield> should be set to -1 so
652 that the <function>FontSetPrivate()</function> macro works
653 properly with an index of 0. Initializing
654 <structfield>maxPrivate</structfield> to 0 can cause
655 problems if the server tries to set something at index 0.