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 “as is” without 53 express or implied warranty. 54 </para> 55 <para role="multiLicensing"> 56 Copyright © 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 “Software”), 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 “AS IS”, 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 <olink targetdoc='xfs-design' targetptr='xfs-design'> 115 <citetitle pubwork="article">Font Server Implementation 116 Overview</citetitle></olink> which discusses the design of the font 117 server. 118 </para> 119 </listitem> 120 <listitem> 121 <para> 122 <citetitle pubwork="article">Bitmap Distribution Format</citetitle> 123 which covers the contents of the bitmap font files which this 124 library reads; although the library is capable of reading other 125 formats as well, including non-bitmap fonts. 126 </para> 127 </listitem> 128 <listitem> 129 <para> 130 <olink targetdoc='fsproto' targetptr='fsproto'> 131 <citetitle pubwork="article">The X Font Service Protocol</citetitle> 132 </olink> 133 for a description of the constraints placed on the design by 134 including support for this font service mechanism. 135 </para> 136 </listitem> 137 </itemizedlist> 138 139 <para> 140 This document assumes the reader is familiar with the X server design, 141 the X protocol as it relates to fonts and the C programming language. 142 As with most MIT produced documentation, this relies heavily on the 143 source code, so have a listing handy. 144 </para> 145 146 <sect1 id='Requirements_for_the_Font_library'> 147<title>Requirements for the Font library</title> 148 149 <para> 150 To avoid miles of duplicate code in the X server, the font server 151 and the various font manipulation tools, the font library should 152 provide interfaces appropriate for all of these tasks. In 153 particular, the X server and font server should be able to both 154 use the library to access disk based fonts, and to communicate 155 with a font server. By providing a general library, we hoped to 156 avoid duplicating code between the X server and font server. 157 </para> 158 159 <para> 160 Another requirement is that the X server (or even a font server) 161 be able to continue servicing requests from other clients while 162 awaiting a response from the font server on behalf of one client. 163 This is the strongest requirement placed on the font library, and 164 has warped the design in curious ways. Because both the X server 165 and font server are single threaded, the font library must not 166 suspend internally, rather it returns an indication of suspension 167 to the application which continues processing other things, until 168 the font data is ready, at which time it restarts the suspended 169 request. 170 </para> 171 172 <para> 173 Because the code for reading and manipulating bitmap font data is 174 used by the font applications <command>mkfontdir</command> and 175 <command>bdftopcf</command>, the font library includes 176 bitmap-font specific interfaces which those applications use, 177 instead of the more general interfaces used by the X and font 178 servers, which are unaware of the source of the font data. 179 These routines will be referred to as the bitmap font access 180 methods. 181 </para> 182 183 </sect1> 184 185 <sect1 id='General_Font_Library_Interface_details'> 186<title>General Font Library Interface details.</title> 187 188 <para> 189 To avoid collision between the #define name space for errors, the Font 190 library defines a new set of return values: 191 </para> 192 193 <programlisting remap='.nf'> 194#define AllocError 80 195#define StillWorking 81 196#define FontNameAlias 82 197#define BadFontName 83 198#define Suspended 84 199#define Successful 85 200#define BadFontPath 86 201#define BadCharRange 87 202#define BadFontFormat 88 203#define FPEResetFailed 89 204 </programlisting> <!-- .fi --> 205 206 <para> 207 Whenever a routine returns <errorname>Suspended</errorname>, 208 the font library will notify the caller (via the ClientSignal 209 interface described below) who should then reinvoke the same routine 210 again with the same arguments. 211 </para> 212 213 </sect1> 214 215 <sect1 id='Font_Path_Elements'> 216<title>Font Path Elements</title> 217 218 <para> 219 At the center of the general font access methods used by X and 220 <command>xfs</command> is the Font Path Element data structure. 221 Like most structures in the X server, this contains a collection 222 of data and some function pointers for manipulating this data: 223 </para> 224 225 <programlisting remap='.nf'> 226/* External view of font paths */ 227typedef struct _FontPathElement { 228 int name_length; 229 char *name; 230 int type; 231 int refcount; 232 pointer private; 233} FontPathElementRec, *FontPathElementPtr; 234 235typedef struct _FPEFunctions { 236 int (*name_check) ( /* name */ ); 237 int (*init_fpe) ( /* fpe */ ); 238 int (*reset_fpe) ( /* fpe */ ); 239 int (*free_fpe) ( /* fpe */ ); 240 int (*open_font) ( /* client, fpe, flags, 241 name, namelen, format, 242 fid, ppfont, alias */ ); 243 int (*close_font) ( /* pfont */ ); 244 int (*list_fonts) ( /* client, fpe, pattern, 245 patlen, maxnames, paths */ ); 246 int (*start_list_fonts_with_info) ( 247 /* client, fpe, name, namelen, 248 maxnames, data */ ); 249 int (*list_next_font_with_info) ( 250 /* client, fpe, name, namelen, 251 info, num, data */ ); 252 int (*wakeup_fpe) ( /* fpe, mask */ ); 253 int (*client_died) ( /* client, fpe */ ); 254} FPEFunctionsRec, FPEFunctions; 255 </programlisting> <!-- .fi --> 256 257 <para> 258 The function pointers are split out from the data structure to 259 save memory; additionally, this avoids any complications when 260 initializing the data structure as there would not be any way 261 to discover the appropriate function to call (a chicken and 262 egg problem). 263 </para> 264 265 <para> 266 When a font path type is initialized, it passes the function 267 pointers to the server which are then stored in an 268 <structname>FPEFunctionsRec</structname>. Each function is 269 described below in turn. 270 </para> 271 272 <sect2 id='name_check'> 273 <title>(*name_check)</title> 274 275 <para> 276 Each new font path member is passed to this function; if 277 the return value is <errorname>Successful</errorname>, then 278 the FPE recognises the format of the string. This does not 279 guarantee that the FPE will be able to successfully use this 280 member. For example, the disk-based font directory file 281 <filename>fonts.dir</filename> may be corrupted, this will 282 not be detected until the font path is initialized. This 283 routine never returns <errorname>Suspended</errorname>. 284 </para> 285 </sect2> 286 287 <sect2 id='init_fpe'> 288 <title>(*init_fpe)</title> 289 290 <para> 291 Initialize a new font path element. This function prepares 292 a new font path element for other requests: the disk font 293 routine reads the <filename>fonts.dir</filename> and 294 <filename>fonts.alias</filename> files into the internal 295 format, while the font server routine connects to the 296 requested font server and prepares for using it. This 297 routine returns <errorname>Successful</errorname> if 298 everything went OK, otherwise the return value indicates the 299 source of the problem. This routine never returns 300 <errorname>Suspended</errorname>. 301 </para> 302 </sect2> 303 304 <sect2 id='reset_fpe'> 305 <title>(*reset_fpe)</title> 306 307 <para> 308 When the X font path is reset, and some of the new members 309 are also in the old font path, this function is called to 310 reinitialize those FPEs. This routine returns 311 <errorname>Successful</errorname> if everything went OK. It 312 returns <errorname>FPEResetFailed</errorname> if (for some 313 reason) the reset failed, and the caller should remove the 314 old FPE and simply create a new one in its place. This is 315 used by the disk-based fonts routine as resetting the 316 internal directory structures would be more complicated than 317 simply having destroying the old and creating a new. 318 </para> 319 </sect2> 320 321 <sect2 id='free_fpe'> 322 <title>(*free_fpe)</title> 323 324 <para> 325 When the server is finished with an FPE, this function is 326 called to dispose of any internal state. It should return 327 <errorname>Successful</errorname>, unless something terrible 328 happens. 329 </para> 330 </sect2> 331 332 <sect2 id='open_font'> 333 <title>(*open_font)</title> 334 335 <para> 336 This routine requests that a font be opened. The <parameter 337 class='function'>client</parameter> argument is used by the 338 font library only in connection with suspending/restarting 339 the request. The <parameter class='function'>flags</parameter> 340 argument specifies some behaviour for the library and can be 341 any of: 342 </para> 343 344 <programlisting remap='.nf'> 345/* OpenFont flags */ 346#define FontLoadInfo 0x0001 347#define FontLoadProps 0x0002 348#define FontLoadMetrics 0x0004 349#define FontLoadBitmaps 0x0008 350#define FontLoadAll 0x000f 351#define FontOpenSync 0x0010 352 </programlisting> <!-- .fi --> 353 354 <para> 355 The various fields specify which portions of the font should 356 be loaded at this time. When <constant>FontOpenSync</constant> 357 is specified, this routine will not return until all of the 358 requested portions are loaded. Otherwise, this routine may 359 return <errorname>Suspended</errorname>. When the presented 360 font name is actually an alias for some other font name, 361 <errorname>FontNameAlias</errorname> is returned, and the 362 actual font name is stored in the location pointed to by the 363 <parameter class='function'>alias</parameter> argument as a 364 null-terminated string. 365 </para> 366 </sect2> 367 368 <sect2 id='close_font'> 369 <title>(*close_font)</title> 370 371 <para> 372 When the server is finished with a font, this routine 373 disposes of any internal state and frees the font data 374 structure. 375 </para> 376 </sect2> 377 378 <sect2 id='list_fonts'> 379 <title>(*list_fonts)</title> 380 381 <para> 382 The <parameter class='function'>paths</parameter> argument is 383 a data structure which will be filled with all of the font names 384 from this directory which match the specified 385 <parameter class='function'>pattern</parameter>. At 386 most <parameter class='function'>maxnames</parameter> will be added. 387 This routine may return <errorname>Suspended</errorname>. 388 </para> 389 </sect2> 390 391 <sect2 id='start_list_fonts_with_info'> 392 <title>(*start_list_fonts_with_info)</title> 393 394 <para> 395 This routine sets any internal state for a verbose listing of 396 all fonts matching the specified pattern. This routine may 397 return <errorname>Suspended</errorname>. 398 </para> 399 </sect2> 400 401 <sect2 id='list_next_font_with_info'> 402 <title>(*list_next_font_with_info)</title> 403 404 <para> 405 To avoid storing huge amounts of data, the interface for 406 ListFontsWithInfo allows the server to get one reply at a time 407 and forward that to the client. When the font name returned 408 is actually an alias for some other font, 409 <errorname>FontNameAlias</errorname> will be returned. The 410 actual font name is return instead, and the font alias which 411 matched the pattern is returned in the location pointed to by 412 data as a null-terminated string. The caller can then get the 413 information by recursively listing that font name with a 414 maxnames of 1. When <errorname>Successful</errorname> is 415 returned, the matching font name is returned, and a 416 FontInfoPtr is stored in the location pointed to by 417 <parameter class='function'>data</parameter>. 418 <parameter class='function'>Data</parameter> must be initialized 419 with a pointer to a FontInfoRec allocated by the caller. When the 420 pointer pointed to by <parameter class='function'>data</parameter> 421 is not left pointing at that storage, the caller mustn't free the 422 associated property data. This routine may return 423 <errorname>Suspended</errorname>. 424 </para> 425 </sect2> 426 427 <sect2 id='wakeup_fpe'> 428 <title>(*wakeup_fpe)</title> 429 430 <para> 431 Whenever an FPE function has returned 432 <errorname>Suspended</errorname>, this routine is called 433 whenever the application wakes up from waiting for input 434 (from <citerefentry><refentrytitle>select</refentrytitle> 435 <manvolnum>2</manvolnum></citerefentry>). This 436 <parameter class='function'>mask</parameter> argument should be 437 the value returned from <function>select(2)</function>. 438 </para> 439 </sect2> 440 441 <sect2 id='client_died'> 442 <title>(*client_died)</title> 443 444 <para> 445 When an FPE function has returned <errorname>Suspended</errorname> 446 and the associated client is being destroyed, this function 447 allows the font library to dispose of any state associated 448 with that client. 449 </para> 450 </sect2> 451 </sect1> 452 453 <sect1 id='Fonts'> 454<title>Fonts</title> 455 456 <para> 457 The data structure which actually contains the font information has 458 changed significantly since previous releases; it now attempts to 459 hide the actual storage format for the data from the application, 460 providing accessor functions to get at the data. This allows a 461 range of internal details for different font sources. The structure 462 is split into two pieces, so that ListFontsWithInfo can share 463 information from the font when it has been loaded. The 464 <structname>FontInfo</structname> structure, then, contains only 465 information germane to LFWI. 466 </para> 467 468 <programlisting remap='.nf'> 469typedef struct _FontInfo { 470 unsigned short firstCol; /* range of glyphs for this font */ 471 unsigned short lastCol; 472 unsigned short firstRow; 473 unsigned short lastRow; 474 unsigned short defaultCh; /* default character index */ 475 unsigned int noOverlap:1; /* no combination of glyphs overlap */ 476 unsigned int terminalFont:1; /* Character cell font */ 477 unsigned int constantMetrics:1; /* all metrics are the same */ 478 unsigned int constantWidth:1; /* all character widths are the same*/ 479 unsigned int inkInside:1; /* all ink inside character cell */ 480 unsigned int inkMetrics:1; /* font has ink metrics */ 481 unsigned int allExist:1; /* no missing chars in range */ 482 unsigned int drawDirection:2; /* left-to-right/right-to-left*/ 483 unsigned int cachable:1; /* font needn't be opened each time*/ 484 unsigned int anamorphic:1; /* font is strangely scaled */ 485 short maxOverlap; /* maximum overlap amount */ 486 short pad; /* unused */ 487 xCharInfo maxbounds; /* glyph metrics maximums */ 488 xCharInfo minbounds; /* glyph metrics minimums */ 489 xCharInfo ink_maxbounds; /* ink metrics maximums */ 490 xCharInfo ink_minbounds; /* ink metrics minimums */ 491 short fontAscent; /* font ascent amount */ 492 short fontDescent; /* font descent amount */ 493 int nprops; /* number of font properties */ 494 FontPropPtr props; /* font properties */ 495 char *isStringProp; /* boolean array */ 496} FontInfoRec, *FontInfoPtr; 497 </programlisting> <!-- .fi --> 498 499 <para> 500 The font structure, then, contains a font info record, the format of 501 the bits in each bitmap and the functions which access the font 502 records (which are stored in an opaque format hung off of 503 <structfield>fontPrivate</structfield>). 504 </para> 505 506 <programlisting remap='.nf'> 507typedef struct _Font { 508 int refcnt; 509 FontInfoRec info; 510 char bit; /* bit order: LSBFirst/MSBFirst */ 511 char byte; /* byte order: LSBFirst/MSBFirst */ 512 char glyph; /* glyph pad: 1, 2, 4 or 8 */ 513 char scan; /* glyph scan unit: 1, 2 or 4 */ 514 fsBitmapFormat format; /* FS-style format (packed) */ 515 int (*get_glyphs) ( /* font, count, chars, encoding, count, glyphs */ ); 516 int (*get_metrics) ( /* font, count, chars, encoding, count, glyphs */ ); 517 int (*get_bitmaps) ( /* client, font, flags, format, 518 flags, nranges, ranges, data_sizep, 519 num_glyphsp, offsetsp, glyph_datap, 520 free_datap */ ); 521 int (*get_extents) ( /* client, font, flags, nranges, 522 ranges, nextentsp, extentsp */); 523 void (*unload_font) ( /* font */ ); 524 FontPathElementPtr fpe; /* FPE associated with this font */ 525 pointer svrPrivate; /* X/FS private data */ 526 pointer fontPrivate; /* private to font */ 527 pointer fpePrivate; /* private to FPE */ 528 int maxPrivate; /* devPrivates (see below) */ 529 pointer *devPrivates; /* ... */ 530} FontRec, *FontPtr; 531 </programlisting> <!-- .fi --> 532 533 <para> 534 Yes, there are several different private pointers in the 535 <structfield>Font</structfield> structure; they were added 536 haphazardly until the devPrivate pointers were added. Future 537 releases may remove some (or all) of the specific pointers, 538 leaving only the <structfield>devPrivates</structfield>mechanism. 539 </para> 540 541 <para> 542 There are two similar interfaces implemented - 543 <structfield>get_glyphs</structfield>/<structfield>get_metrics</structfield> 544 and 545 <structfield>get_bitmaps</structfield>/<structfield>get_extents</structfield>. 546 Too little time caused the font-server specific interfaces to 547 be placed in the font library (and portions duplicated in each 548 renderer) instead of having them integrated into the font server 549 itself. This may change. The X server uses only 550 <structfield>get_glyphs</structfield>/<structfield>get_metrics</structfield>, 551 and those will not change dramatically. Each of the routines 552 is described below. 553 </para> 554 555 <sect2 id='get_glyphs'> 556 <title>(*get_glyphs)</title> 557 558 <para> 559 This routine returns <structname>CharInfoPtrs</structname> 560 for each of the requested characters in the font. If the 561 character does not exist in the font, the default character 562 will be returned, unless no default character exists in 563 which case that character is skipped. Thus, the number of 564 glyphs returned will not always be the same as the number of 565 characters passed in. 566 </para> 567 </sect2> 568 569 <sect2 id='get_metrics'> 570 <title>(*get_metrics)</title> 571 572 <para> 573 This is similar to <structfield>(*get_glyphs)</structfield> 574 except that pointers to <structname>xCharInfo</structname> 575 structures are returned, and, if the font has ink metrics, 576 those are returned instead of the bitmap metrics. 577 </para> 578 </sect2> 579 580 <sect2 id='get_bitmaps'> 581<title>(*get_bitmaps)</title> 582 583 <para> 584 This packs the glyph image data in the requested 585 <parameter class='function'>format</parameter> and returns it. The 586 <parameter class='function'>ranges</parameter>/<parameter class='function'>nranges</parameter> 587 argument specify the set of glyphs from the font to pack together. 588 </para> 589 </sect2> 590 591 <sect2 id='get_extents'> 592 <title>(*get_extents)</title> 593 594 <para> 595 This returns the metrics for the specified font from the 596 specified <parameter class='function'>ranges</parameter>. 597 </para> 598 599 </sect2> 600 601 <sect2 id='unload_font'> 602 <title>(*unload_font)</title> 603 604 <para> 605 This is called from the FPE routine 606 <function>(*close_font)</function>, and so should not ever be 607 called from the application. 608 </para> 609 </sect2> 610 611 <sect2 id='maxPrivate'> 612<title>maxPrivate</title> 613 614 <para> 615 When initializing a new font structure, 616 <structfield>maxPrivate</structfield> should be set to -1 so 617 that the <function>FontSetPrivate()</function> macro works 618 properly with an index of 0. Initializing 619 <structfield>maxPrivate</structfield> to 0 can cause 620 problems if the server tries to set something at index 0. 621 </para> 622 </sect2> 623 </sect1> 624 </article> 625