doc/fontlib.xml

   1 <?xml version="1.0" encoding="UTF-8" ?>
   2 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
   3             "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
   4 [
   5 <!ENTITY % defs SYSTEM "defs.ent"> %defs;
   6 ]>
   7 <!-- lifted from troff+ms by doclifter -->
   8 <!-- previous version was in xorg-docs/specs/Xserver/fontlib.ms -->
   9
  10   <article id='fontlib'>
  11 <!-- .ps 12 -->
  12 <!-- .EF 'Font Library Interface'\- % \-'July 27, 1991' -->
  13 <!-- .OF 'Font Library Interface'\- % \-'July 27, 1991' -->
  14 <!-- .EH '''' -->
  15 <!-- .OH '''' -->
  16 <!-- body begins here -->
  17     <articleinfo>
  18       <title>
  19         The X Font Library
  20       </title>
  21       <authorgroup>
  22         <author>
  23           <firstname>Keith</firstname>
  24           <surname>Packard</surname>
  25           <affiliation>
  26             <orgname>MIT X Consortium</orgname>
  27           </affiliation>
  28         </author>
  29         <author>
  30           <firstname>David</firstname>
  31           <surname>Lemke</surname>
  32           <affiliation>
  33             <orgname>Network Computing Devices</orgname>
  34           </affiliation>
  35         </author>
  36       </authorgroup>
  37       <releaseinfo>X Version 11, Release &fullrelvers;</releaseinfo>
  38       <copyright><year>1993</year><holder>Network Computing Devices</holder></copyright>
  39
  40       <legalnotice>
  41         <para>
  42           Permission to use, copy, modify, distribute, and sell this
  43           software and its documentation for any purpose is hereby
  44           granted without fee, provided that the above copyright
  45           notice appear in all copies and that both that copyright
  46           notice and this permission notice appear in supporting
  47           documentation, and that the name of Network Computing
  48           Devices not be used in advertising or publicity pertaining
  49           to distribution of the software without specific, written
  50           prior permission.  Network Computing Devices makes no
  51           representations about the suitability of this software for
  52           any purpose.  It is provided &ldquo;as is&rdquo; without
  53           express or implied warranty.
  54         </para>
  55         <para role="multiLicensing">
  56           Copyright &copy; 1993, 1994 X Consortium
  57         </para>
  58         <para>
  59           Permission is hereby granted, free of charge, to any person
  60           obtaining a copy of this software and associated
  61           documentation files (the &ldquo;Software&rdquo;), to deal in the
  62           Software without restriction, including without limitation
  63           the rights to use, copy, modify, merge, publish, distribute,
  64           sublicense, and/or sell copies of the Software, and to
  65           permit persons to whom the Software is furnished to do so,
  66           subject to the following conditions:
  67         </para><para>
  68           The above copyright notice and this permission notice shall be
  69           included in all copies or substantial portions of the Software.
  70         </para><para>
  71           THE SOFTWARE IS PROVIDED &ldquo;AS IS&rdquo;, WITHOUT WARRANTY
  72           OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO
  73           THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
  74           PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE X
  75           CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  76           LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
  77           OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
  78           SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  79         </para><para>
  80           Except as contained in this notice, the name of the X
  81           Consortium shall not be used in advertising or otherwise to
  82           promote the sale, use or other dealings in this Software
  83           without prior written authorization from the X Consortium.
  84         </para>
  85         <para>X Window System is a trademark of The Open Group.</para>
  86       </legalnotice>
  87       <pubdate>July 27, 1991</pubdate>
  88     </articleinfo>
  89
  90     <warning>
  91       <para>
  92         This document has not been updated since X11R6, and is likely
  93         to be somewhat out of date for the current libXfont.
  94       </para>
  95     </warning>
  96
  97     <para>
  98       This document describes the data structures and interfaces for
  99       using the X Font library.  It is intended as a reference for
 100       programmers building X and Font servers.  You may want to refer
 101       to the following documents:
 102     </para>
 103
 104     <itemizedlist>
 105       <listitem>
 106         <para>
 107           <citetitle pubwork="article">Definition of the Porting Layer for
 108             the X v11 Sample Server</citetitle> for a discussion on how this
 109           library interacts with the X server
 110         </para>
 111       </listitem>
 112       <listitem>
 113         <para>
 114           <citetitle pubwork="article">Font Server Implementation
 115             Overview</citetitle> which discusses the design of the font
 116           server.
 117         </para>
 118       </listitem>
 119       <listitem>
 120         <para>
 121           <citetitle pubwork="article">Bitmap Distribution Format</citetitle>
 122           which covers the contents of the bitmap font files which this
 123           library reads; although the library is capable of reading other
 124           formats as well, including non-bitmap fonts.
 125         </para>
 126       </listitem>
 127       <listitem>
 128         <para>
 129           <citetitle pubwork="article">The X Font Service Protocol</citetitle>
 130           for a description of the constraints placed  on the design by
 131           including support for this font service mechanism.
 132         </para>
 133       </listitem>
 134     </itemizedlist>
 135
 136     <para>
 137       This document assumes the reader is familiar with the X server design,
 138       the X protocol as it relates to fonts and the C programming language.
 139       As with most MIT produced documentation, this relies heavily on the
 140       source code, so have a listing handy.
 141     </para>
 142
 143     <sect1 id='Requirements_for_the_Font_library'>
 144 <title>Requirements for the Font library</title>
 145
 146       <para>
 147         To avoid miles of duplicate code in the X server, the font server
 148         and the various font manipulation tools, the font library should
 149         provide interfaces appropriate for all of these tasks.  In
 150         particular, the X server and font server should be able to both
 151         use the library to access disk based fonts, and to communicate
 152         with a font server.  By providing a general library, we hoped to
 153         avoid duplicating code between the X server and font server.
 154       </para>
 155
 156       <para>
 157         Another requirement is that the X server (or even a font server)
 158         be able to continue servicing requests from other clients while
 159         awaiting a response from the font server on behalf of one client.
 160         This is the strongest requirement placed on the font library, and
 161         has warped the design in curious ways.  Because both the X server
 162         and font server are single threaded, the font library must not
 163         suspend internally, rather it returns an indication of suspension
 164         to the application which continues processing other things, until
 165         the font data is ready, at which time it restarts the suspended
 166         request.
 167       </para>
 168
 169       <para>
 170         Because the code for reading and manipulating bitmap font data is
 171         used by the font applications <command>mkfontdir</command> and
 172         <command>bdftopcf</command>, the font library includes
 173         bitmap-font specific interfaces which those applications use,
 174         instead of the more general interfaces used by the X and font
 175         servers, which are unaware of the source of the font data.
 176         These routines will be refered to as the bitmap font access
 177         methods.
 178       </para>
 179
 180     </sect1>
 181
 182     <sect1 id='General_Font_Library_Interface_details'>
 183 <title>General Font Library Interface details.</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>Font Path Elements</title>
 214
 215       <para>
 216         At the center of the general font access methods used by X and
 217         <command>xfs</command> is the Font Path Element data structure.
 218         Like most structures in the X server, this contains a collection
 219         of data and some function pointers for manipulating this data:
 220       </para>
 221
 222       <programlisting remap='.nf'>
 223 /* External view of font paths */
 224 typedef struct _FontPathElement {
 225     int         name_length;
 226     char       *name;
 227     int         type;
 228     int         refcount;
 229     pointer     private;
 230 } FontPathElementRec, *FontPathElementPtr;
 231
 232 typedef struct _FPEFunctions {
 233     int         (*name_check) ( /* name */ );
 234     int         (*init_fpe) ( /* fpe */ );
 235     int         (*reset_fpe) ( /* fpe */ );
 236     int         (*free_fpe) ( /* fpe */ );
 237     int         (*open_font) (  /* client, fpe, flags,
 238                         name, namelen, format,
 239                         fid,  ppfont, alias */ );
 240     int         (*close_font) ( /* pfont */ );
 241     int         (*list_fonts) ( /* client, fpe, pattern,
 242                         patlen, maxnames, paths */ );
 243     int         (*start_list_fonts_with_info) (
 244                         /* client, fpe, name, namelen,
 245                            maxnames, data */ );
 246     int         (*list_next_font_with_info) (
 247                         /* client, fpe, name, namelen,
 248                            info, num, data */ );
 249     int         (*wakeup_fpe) ( /* fpe, mask */ );
 250     int         (*client_died) ( /* client, fpe */ );
 251 } FPEFunctionsRec, FPEFunctions;
 252       </programlisting> <!-- .fi -->
 253
 254       <para>
 255         The function pointers are split out from the data structure to
 256         save memory; additionally, this avoids any complications when
 257         initializing the data structure as there would not be any way
 258         to discover the appropriate function to call (a chicken and
 259         egg problem).
 260       </para>
 261
 262       <para>
 263         When a font path type is initialized, it passes the function
 264         pointers to the server which are then stored in an
 265         <structname>FPEFunctionsRec</structname>. Each function is
 266         described below in turn.
 267       </para>
 268
 269       <sect2 id='name_check'>
 270         <title>(*name_check)</title>
 271
 272         <para>
 273           Each new font path member is passed to this function; if
 274           the return value is <errorname>Successful</errorname>, then
 275           the FPE recognises the format of the string.  This does not
 276           guarantee that the FPE will be able to successfully use this
 277           member.  For example, the disk-based font directory file
 278           <filename>fonts.dir</filename> may be corrupted, this will
 279           not be detected until the font path is initialized.  This
 280           routine never returns <errorname>Suspended</errorname>.
 281         </para>
 282       </sect2>
 283
 284       <sect2 id='init_fpe'>
 285         <title>(*init_fpe)</title>
 286
 287         <para>
 288           Initialize a new font path element.  This function prepares
 289           a new font path element for other requests: the disk font
 290           routine reads the <filename>fonts.dir</filename> and
 291           <filename>fonts.alias</filename> files into the internal
 292           format, while the font server routine connects to the
 293           requested font server and prepares for using it.  This
 294           routine returns <errorname>Successful</errorname> if
 295           everything went OK, otherwise the return value indicates the
 296           source of the problem.  This routine never returns
 297           <errorname>Suspended</errorname>.
 298         </para>
 299       </sect2>
 300
 301       <sect2 id='reset_fpe'>
 302         <title>(*reset_fpe)</title>
 303
 304         <para>
 305           When the X font path is reset, and some of the new members
 306           are also in the old font path, this function is called to
 307           reinitialize those FPEs.  This routine returns
 308           <errorname>Successful</errorname> if everything went OK.  It
 309           returns <errorname>FPEResetFailed</errorname> if (for some
 310           reason) the reset failed, and the caller should remove the
 311           old FPE and simply create a new one in its place.  This is
 312           used by the disk-based fonts routine as resetting the
 313           internal directory structures would be more complicated than
 314           simply having destroying the old and creating a new.
 315         </para>
 316       </sect2>
 317
 318       <sect2 id='free_fpe'>
 319         <title>(*free_fpe)</title>
 320
 321         <para>
 322           When the server is finished with an FPE, this function is
 323           called to dispose of any internal state.  It should return
 324           <errorname>Successful</errorname>, unless something terrible
 325           happens.
 326         </para>
 327       </sect2>
 328
 329       <sect2 id='open_font'>
 330         <title>(*open_font)</title>
 331
 332         <para>
 333           This routine requests that a font be opened.  The <parameter
 334           class='function'>client</parameter> argument is used by the
 335           font library only in connection with suspending/restarting
 336           the request.  The <parameter class='function'>flags</parameter>
 337           argument specifies some behaviour for the library and can be
 338           any of:
 339         </para>
 340
 341         <programlisting remap='.nf'>
 342 /* OpenFont flags */
 343 #define FontLoadInfo    0x0001
 344 #define FontLoadProps   0x0002
 345 #define FontLoadMetrics 0x0004
 346 #define FontLoadBitmaps 0x0008
 347 #define FontLoadAll     0x000f
 348 #define FontOpenSync    0x0010
 349         </programlisting> <!-- .fi -->
 350
 351         <para>
 352           The various fields specify which portions of the font should
 353           be loaded at this time.  When <constant>FontOpenSync</constant>
 354           is specified, this routine will not return until all of the
 355           requested portions are loaded.  Otherwise, this routine may
 356           return <errorname>Suspended</errorname>.  When the presented
 357           font name is actually an alias for some other font name,
 358           <errorname>FontNameAlias</errorname> is returned, and the
 359           actual font name is stored in the location pointed to by the
 360           <parameter class='function'>alias</parameter> argument as a
 361           null-terminated string.
 362         </para>
 363       </sect2>
 364
 365       <sect2 id='close_font'>
 366         <title>(*close_font)</title>
 367
 368         <para>
 369           When the server is finished with a font, this routine
 370           disposes of any internal state and frees the font data
 371           structure.
 372         </para>
 373       </sect2>
 374
 375       <sect2 id='list_fonts'>
 376         <title>(*list_fonts)</title>
 377
 378         <para>
 379           The <parameter class='function'>paths</parameter> argument is
 380           a data structure which will be filled with all of the font names
 381           from this directory which match the specified
 382           <parameter class='function'>pattern</parameter>.  At
 383           most <parameter class='function'>maxnames</parameter> will be added.
 384           This routine may return <errorname>Suspended</errorname>.
 385         </para>
 386       </sect2>
 387
 388       <sect2 id='start_list_fonts_with_info'>
 389         <title>(*start_list_fonts_with_info)</title>
 390
 391         <para>
 392           This routine sets any internal state for a verbose listing of
 393           all fonts matching the specified pattern.  This routine may
 394           return <errorname>Suspended</errorname>.
 395         </para>
 396       </sect2>
 397
 398       <sect2 id='list_next_font_with_info'>
 399         <title>(*list_next_font_with_info)</title>
 400
 401         <para>
 402           To avoid storing huge amounts of data, the interface for
 403           ListFontsWithInfo allows the server to get one reply at a time
 404           and forward that to the client.  When the font name returned
 405           is actually an alias for some other font,
 406           <errorname>FontNameAlias</errorname> will be returned.  The
 407           actual font name is return instead, and the font alias which
 408           matched the pattern is returned in the location pointed to by
 409           data as a null-terminated string.  The caller can then get the
 410           information by recursively listing that font name with a
 411           maxnames of 1.  When <errorname>Successful</errorname> is
 412           returned, the matching font name is returned, and a
 413           FontInfoPtr is stored in the location pointed to by
 414           <parameter class='function'>data</parameter>.
 415           <parameter class='function'>Data</parameter> must be initialized
 416           with a pointer to a FontInfoRec allocated by the caller.  When the
 417           pointer pointed to by <parameter class='function'>data</parameter>
 418           is not left pointing at that storage, the caller mustn't free the
 419           associated property data. This routine may return
 420           <errorname>Suspended</errorname>.
 421         </para>
 422       </sect2>
 423
 424       <sect2 id='wakeup_fpe'>
 425         <title>(*wakeup_fpe)</title>
 426
 427         <para>
 428           Whenever an FPE function has returned
 429           <errorname>Suspended</errorname>, this routine is called
 430           whenever the application wakes up from waiting for input
 431           (from <citerefentry><refentrytitle>select</refentrytitle>
 432             <manvolnum>2</manvolnum></citerefentry>).  This
 433             <parameter class='function'>mask</parameter> argument should be
 434             the value returned from <function>select(2)</function>.
 435         </para>
 436       </sect2>
 437
 438       <sect2 id='client_died'>
 439         <title>(*client_died)</title>
 440
 441         <para>
 442           When an FPE function has returned <errorname>Suspended</errorname>
 443           and the associated client is being destroyed, this function
 444           allows the font library to dispose of any state associated
 445           with that client.
 446         </para>
 447       </sect2>
 448     </sect1>
 449
 450     <sect1 id='Fonts'>
 451 <title>Fonts</title>
 452
 453       <para>
 454         The data structure which actually contains the font information has
 455         changed significantly since previous releases; it now attempts to
 456         hide the actual storage format for the data from the application,
 457         providing accessor functions to get at the data.  This allows a
 458         range of internal details for different font sources.  The structure
 459         is split into two pieces, so that ListFontsWithInfo can share
 460         information from the font when it has been loaded.  The
 461         <structname>FontInfo</structname> structure, then, contains only
 462         information germane to LFWI.
 463       </para>
 464
 465       <programlisting remap='.nf'>
 466 typedef struct _FontInfo {
 467     unsigned short firstCol;            /* range of glyphs for this font */
 468     unsigned short lastCol;
 469     unsigned short firstRow;
 470     unsigned short lastRow;
 471     unsigned short defaultCh;           /* default character index */
 472     unsigned int noOverlap:1;           /* no combination of glyphs overlap */
 473     unsigned int terminalFont:1;        /* Character cell font */
 474     unsigned int constantMetrics:1;     /* all metrics are the same */
 475     unsigned int constantWidth:1;       /* all character widths are the same*/
 476     unsigned int inkInside:1;           /* all ink inside character cell */
 477     unsigned int inkMetrics:1;          /* font has ink metrics */
 478     unsigned int allExist:1;            /* no missing chars in range */
 479     unsigned int drawDirection:2;       /* left-to-right/right-to-left*/
 480     unsigned int cachable:1;            /* font needn't be opened each time*/
 481     unsigned int anamorphic:1;          /* font is strangely scaled */
 482     short       maxOverlap;             /* maximum overlap amount */
 483     short       pad;                    /* unused */
 484     xCharInfo   maxbounds;              /* glyph metrics maximums */
 485     xCharInfo   minbounds;              /* glyph metrics minimums */
 486     xCharInfo   ink_maxbounds;          /* ink metrics maximums */
 487     xCharInfo   ink_minbounds;          /* ink metrics minimums */
 488     short       fontAscent;             /* font ascent amount */
 489     short       fontDescent;            /* font descent amount */
 490     int         nprops;                 /* number of font properties */
 491     FontPropPtr props;                  /* font properties */
 492     char       *isStringProp;           /* boolean array */
 493 }           FontInfoRec, *FontInfoPtr;
 494       </programlisting> <!-- .fi -->
 495
 496       <para>
 497         The font structure, then, contains a font info record, the format of
 498         the bits in each bitmap and the functions which access the font
 499         records (which are stored in an opaque format hung off of
 500         <structfield>fontPrivate</structfield>).
 501       </para>
 502
 503       <programlisting remap='.nf'>
 504 typedef struct _Font {
 505     int         refcnt;
 506     FontInfoRec info;
 507     char        bit;                    /* bit order: LSBFirst/MSBFirst */
 508     char        byte;                   /* byte order: LSBFirst/MSBFirst */
 509     char        glyph;                  /* glyph pad: 1, 2, 4 or 8 */
 510     char        scan;                   /* glyph scan unit: 1, 2 or 4 */
 511     fsBitmapFormat format;              /* FS-style format (packed) */
 512     int         (*get_glyphs)  ( /* font, count, chars, encoding, count, glyphs */ );
 513     int         (*get_metrics) ( /* font, count, chars, encoding, count, glyphs */ );
 514     int         (*get_bitmaps) ( /* client, font, flags, format,
 515                                     flags, nranges, ranges, data_sizep,
 516                                     num_glyphsp, offsetsp, glyph_datap,
 517                                     free_datap */ );
 518     int         (*get_extents) ( /* client, font, flags, nranges,
 519                                     ranges, nextentsp, extentsp */);
 520     void        (*unload_font) ( /* font */ );
 521     FontPathElementPtr fpe;             /* FPE associated with this font */
 522     pointer     svrPrivate;             /* X/FS private data */
 523     pointer     fontPrivate;            /* private to font */
 524     pointer     fpePrivate;             /* private to FPE */
 525     int         maxPrivate;             /* devPrivates (see below) */
 526     pointer     *devPrivates;           /*  ... */
 527 }           FontRec, *FontPtr;
 528       </programlisting> <!-- .fi -->
 529
 530       <para>
 531         Yes, there are several different private pointers in the
 532         <structfield>Font</structfield> structure; they were added
 533         haphazardly until the devPrivate pointers were added.  Future
 534         releases may remove some (or all) of the specific pointers,
 535         leaving only the <structfield>devPrivates</structfield>mechanism.
 536       </para>
 537
 538       <para>
 539         There are two similar interfaces implemented -
 540         <structfield>get_glyphs</structfield>/<structfield>get_metrics</structfield>
 541         and
 542         <structfield>get_bitmaps</structfield>/<structfield>get_extents</structfield>.
 543         Too little time caused the font-server specific interfaces to
 544         be placed in the font library (and portions duplicated in each
 545         renderer) instead of having them integrated into the font server
 546         itself.  This may change.  The X server uses only
 547         <structfield>get_glyphs</structfield>/<structfield>get_metrics</structfield>,
 548         and those will not change dramatically.  Each of the routines
 549         is described below.
 550       </para>
 551
 552       <sect2 id='get_glyphs'>
 553         <title>(*get_glyphs)</title>
 554
 555         <para>
 556           This routine returns <structname>CharInfoPtrs</structname>
 557           for each of the requested characters in the font.  If the
 558           character does not exist in the font, the default character
 559           will be returned, unless no default character exists in
 560           which case that character is skipped.  Thus, the number of
 561           glyphs returned will not always be the same as the number of
 562           characters passed in.
 563         </para>
 564       </sect2>
 565
 566       <sect2 id='get_metrics'>
 567         <title>(*get_metrics)</title>
 568
 569         <para>
 570           This is similar to <structfield>(*get_glyphs)</structfield>
 571           except that pointers to <structname>xCharInfo</structname>
 572           structures are returned, and, if the font has ink metrics,
 573           those are returned instead of the bitmap metrics.
 574         </para>
 575       </sect2>
 576
 577       <sect2 id='get_bitmaps'>
 578 <title>(*get_bitmaps)</title>
 579
 580         <para>
 581           This packs the glyph image data in the requested
 582           <parameter class='function'>format</parameter> and returns it.  The
 583           <parameter class='function'>ranges</parameter>/<parameter class='function'>nranges</parameter>
 584           argument specify the set of glyphs from the font to pack together.
 585         </para>
 586       </sect2>
 587
 588       <sect2 id='get_extents'>
 589         <title>(*get_extents)</title>
 590
 591         <para>
 592           This returns the metrics for the specified font from the
 593           specified <parameter class='function'>ranges</parameter>.
 594         </para>
 595
 596       </sect2>
 597
 598       <sect2 id='unload_font'>
 599         <title>(*unload_font)</title>
 600
 601         <para>
 602           This is called from the FPE routine
 603           <function>(*close_font)</function>, and so should not ever be
 604           called from the application.
 605         </para>
 606       </sect2>
 607
 608       <sect2 id='maxPrivate'>
 609 <title>maxPrivate</title>
 610
 611         <para>
 612           When initializing a new font structure,
 613           <structfield>maxPrivate</structfield> should be set to -1 so
 614           that the <function>FontSetPrivate()</function> macro works
 615           properly with an index of 0.  Initializing
 616           <structfield>maxPrivate</structfield> to 0 can cause
 617           problems if the server tries to set something at index 0.
 618         </para>
 619       </sect2>
 620     </sect1>
 621   </article>