fontlib.xml revision 41c30155
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 <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 */ 224typedef struct _FontPathElement { 225 int name_length; 226 char *name; 227 int type; 228 int refcount; 229 pointer private; 230} FontPathElementRec, *FontPathElementPtr; 231 232typedef 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'> 466typedef 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'> 504typedef 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> 622