doc/fontlib.xml

   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 -->
   6
   7   <article id='fontlibms'>
   8 <!-- .ps 12 -->
   9 <!-- .EF 'Font Library Interface'\- % \-'July 27, 1991' -->
  10 <!-- .OF 'Font Library Interface'\- % \-'July 27, 1991' -->
  11 <!-- .EH '''' -->
  12 <!-- .OH '''' -->
  13 <!-- body begins here -->
  14     <articleinfo>
  15       <title>
  16         The X Font Library
  17       </title>
  18       <pubdate>July 27, 1991</pubdate>
  19       <authorgroup>
  20         <author>
  21           <firstname>Keith</firstname>
  22           <surname>Packard</surname>
  23           <affiliation>
  24             <orgname>MIT X Consortium</orgname>
  25           </affiliation>
  26         </author>
  27         <author>
  28           <firstname>David</firstname>
  29           <surname>Lemke</surname>
  30           <affiliation>
  31             <orgname>Network Computing Devices</orgname>
  32           </affiliation>
  33         </author>
  34       </authorgroup>
  35       <legalnotice>
  36         <para>
  37           Copyright 1993 <orgname>Network Computing Devices</orgname>
  38         </para>
  39         <para>
  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 &ldquo;as is&rdquo; without
  51           express or implied warranty.
  52         </para>
  53         <para>
  54           Copyright 1993, 1994 <orgname>X Consortium</orgname>
  55         </para>
  56         <para>
  57           Permission is hereby granted, free of charge, to any person
  58           obtaining a copy of this software and associated
  59           documentation files (the &ldquo;Software&rdquo;), 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:
  65         </para><para>
  66           The above copyright notice and this permission notice shall be
  67           included in all copies or substantial portions of the Software.
  68         </para><para>
  69           THE SOFTWARE IS PROVIDED &ldquo;AS IS&rdquo;, 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.
  77         </para><para>
  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.
  82         </para>
  83       </legalnotice>
  84     </articleinfo>
  85
  86     <warning>
  87       <para>
  88         This document has not been updated since X11R6, and is likely
  89         to be somewhat out of date for the current libXfont.
  90       </para>
  91     </warning>
  92
  93     <para>
  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:
  98     </para>
  99
 100     <itemizedlist>
 101       <listitem>
 102         <para>
 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
 106         </para>
 107       </listitem>
 108       <listitem>
 109         <para>
 110           <citetitle pubwork="article">Font Server Implementation
 111             Overview</citetitle> which discusses the design of the font
 112           server.
 113         </para>
 114       </listitem>
 115       <listitem>
 116         <para>
 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.
 121         </para>
 122       </listitem>
 123       <listitem>
 124         <para>
 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.
 128         </para>
 129       </listitem>
 130     </itemizedlist>
 131
 132     <para>
 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.
 137     </para>
 138
 139     <sect1 id='requirements_for_the_font_library'>
 140       <title>
 141         Requirements for the Font library
 142       </title>
 143
 144       <para>
 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.
 152       </para>
 153
 154       <para>
 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
 164         request.
 165       </para>
 166
 167       <para>
 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
 175         methods.
 176       </para>
 177
 178     </sect1>
 179
 180     <sect1 id='general_font_library_interface_details'>
 181       <title>
 182         General Font Library Interface details.
 183       </title>
 184
 185       <para>
 186         To avoid collision between the #define name space for errors, the Font
 187         library defines a new set of return values:
 188       </para>
 189
 190       <programlisting remap='.nf'>
 191 #define AllocError      80
 192 #define StillWorking    81
 193 #define FontNameAlias   82
 194 #define BadFontName     83
 195 #define Suspended       84
 196 #define Successful      85
 197 #define BadFontPath     86
 198 #define BadCharRange    87
 199 #define BadFontFormat   88
 200 #define FPEResetFailed  89
 201       </programlisting> <!-- .fi -->
 202
 203       <para>
 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.
 208       </para>
 209
 210     </sect1>
 211
 212     <sect1 id='font_path_elements'>
 213       <title>
 214         Font Path Elements
 215       </title>
 216
 217       <para>
 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:
 222       </para>
 223
 224       <programlisting remap='.nf'>
 225 /* External view of font paths */
 226 typedef struct _FontPathElement {
 227     int         name_length;
 228     char       *name;
 229     int         type;
 230     int         refcount;
 231     pointer     private;
 232 } FontPathElementRec, *FontPathElementPtr;
 233
 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,
 247                            maxnames, data */ );
 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 -->
 255
 256       <para>
 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
 261         egg problem).
 262       </para>
 263
 264       <para>
 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.
 269       </para>
 270
 271       <sect2 id='name_check'>
 272         <title>
 273           (*name_check)
 274         </title>
 275
 276         <para>
 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>.
 285         </para>
 286       </sect2>
 287
 288       <sect2 id='init_fpe'>
 289         <title>
 290           (*init_fpe)
 291         </title>
 292
 293         <para>
 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>.
 304         </para>
 305       </sect2>
 306
 307       <sect2 id='reset_fpe'>
 308         <title>
 309           (*reset_fpe)
 310         </title>
 311
 312         <para>
 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.
 323         </para>
 324       </sect2>
 325
 326       <sect2 id='free_fpe'>
 327         <title>
 328           (*free_fpe)
 329         </title>
 330
 331         <para>
 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
 335           happens.
 336         </para>
 337       </sect2>
 338
 339       <sect2 id='open_font'>
 340         <title>
 341           (*open_font)
 342         </title>
 343
 344         <para>
 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
 350           any of:
 351         </para>
 352
 353         <programlisting remap='.nf'>
 354 /* OpenFont flags */
 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 -->
 362
 363         <para>
 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.
 374         </para>
 375       </sect2>
 376
 377       <sect2 id='close_font'>
 378         <title>
 379           (*close_font)
 380         </title>
 381
 382         <para>
 383           When the server is finished with a font, this routine
 384           disposes of any internal state and frees the font data
 385           structure.
 386         </para>
 387       </sect2>
 388
 389       <sect2 id='list_fonts'>
 390         <title>
 391           (*list_fonts)
 392         </title>
 393
 394         <para>
 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>.
 401         </para>
 402       </sect2>
 403
 404       <sect2 id='start_list_fonts_with_info'>
 405         <title>
 406           (*start_list_fonts_with_info)
 407         </title>
 408
 409         <para>
 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>.
 413         </para>
 414       </sect2>
 415
 416       <sect2 id='list_next_font_with_info'>
 417         <title>
 418           (*list_next_font_with_info)
 419         </title>
 420
 421         <para>
 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>.
 441         </para>
 442       </sect2>
 443
 444       <sect2 id='wakeup_fpe'>
 445         <title>
 446           (*wakeup_fpe)
 447         </title>
 448
 449         <para>
 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>.
 457         </para>
 458       </sect2>
 459
 460       <sect2 id='client_died'>
 461         <title>
 462           (*client_died)
 463         </title>
 464
 465         <para>
 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
 469           with that client.
 470         </para>
 471       </sect2>
 472     </sect1>
 473
 474     <sect1 id='fonts'>
 475       <title>
 476         Fonts
 477       </title>
 478
 479       <para>
 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.
 489       </para>
 490
 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 -->
 521
 522       <para>
 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>).
 527       </para>
 528
 529       <programlisting remap='.nf'>
 530 typedef struct _Font {
 531     int         refcnt;
 532     FontInfoRec info;
 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,
 543                                     free_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;           /*  ... */
 553 }           FontRec, *FontPtr;
 554       </programlisting> <!-- .fi -->
 555
 556       <para>
 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.
 562       </para>
 563
 564       <para>
 565         There are two similar interfaces implemented -
 566         <structfield>get_glyphs</structfield>/<structfield>get_metrics</structfield>
 567         and
 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
 575         is described below.
 576       </para>
 577
 578       <sect2 id='get_glyphs'>
 579         <title>
 580           (*get_glyphs)
 581         </title>
 582
 583         <para>
 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.
 591         </para>
 592       </sect2>
 593
 594       <sect2 id='get_metrics'>
 595         <title>
 596           (*get_metrics)
 597         </title>
 598
 599         <para>
 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.
 604         </para>
 605       </sect2>
 606
 607       <sect2 id='getbitmaps'>
 608         <title>
 609           (*get_bitmaps)
 610         </title>
 611
 612         <para>
 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.
 617         </para>
 618       </sect2>
 619
 620       <sect2 id='get_extents'>
 621         <title>
 622           (*get_extents)
 623         </title>
 624
 625         <para>
 626           This returns the metrics for the specified font from the
 627           specified <parameter class='function'>ranges</parameter>.
 628         </para>
 629
 630       </sect2>
 631
 632       <sect2 id='unload_font'>
 633         <title>
 634           (*unload_font)
 635         </title>
 636
 637         <para>
 638           This is called from the FPE routine
 639           <function>(*close_font)</function>, and so should not ever be
 640           called from the application.
 641         </para>
 642       </sect2>
 643
 644       <sect2 id='maxprivate'>
 645         <title>
 646           maxPrivate
 647         </title>
 648
 649         <para>
 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.
 656         </para>
 657       </sect2>
 658     </sect1>
 659   </article>