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[ 5<!ENTITY % defs SYSTEM "defs.ent"> %defs; 6]> 7<!-- lifted from troff+ms by doclifter --> 8<!-- previous version was in xorg-docs/specs/xfs/design.ms --> 9<!-- encoding notes: 10 - for lack of a better match, the systemitem tag is used for 11 protocol request names 12 --> 13<article id='xfs-design'> 14 <articleinfo> 15 <title>Font server implementation overview</title> 16 <releaseinfo>X Version 11, Release &fullrelvers;</releaseinfo> 17 <author> 18 <firstname>Dave</firstname> 19 <surname>Lemke</surname> 20 <affiliation> 21 <orgname>Network Computing Devices, Inc.</orgname> 22 </affiliation> 23 </author> 24 <copyright> 25 <year>1991</year> 26 <holder>Network Computing Devices, Inc.</holder> 27 </copyright> 28 29 <legalnotice> 30 <para> 31 Permission to use, copy, modify, distribute, and sell this 32 documentation for any purpose is hereby granted without fee, 33 provided that the above copyright notice and this permission 34 notice appear in all copies. Network Computing Devices, Inc. 35 makes no representations about the suitability for any purpose 36 of the information in this document. This documentation is 37 provided "as is" without express or implied warranty. 38 </para> 39 </legalnotice> 40 41 </articleinfo> 42 <sect1 id='introduction'> 43 <title>Introduction</title> 44 <para>The font server uses the same client/server model as X. 45 The basic structure is that of the X Consortium X11R5 X server, 46 and those who know that code should find the 47 <firstterm remap='I'>os</firstterm> and 48 <firstterm remap='I'>difs</firstterm> (device independent font 49 server) layers familiar.</para> 50 <literallayout class='monospaced'> 51 ┌─────────────────┐ 52 ┌─────┤ difs ├──────┐ 53 │ └─────────────────┘ │ 54 │ │ 55 ┌─┴──┐ ┌────────┴───┐ 56 │ os │ │ renderers │ 57 └────┘ └────────────┘ 58 </literallayout> 59 <sect2 id='definitions'> 60 <title>Definitions</title> 61 <glosslist> 62 <glossentry> 63 <glossterm> 64 <firstterm>Renderer</firstterm> 65 <indexterm><primary>renderer</primary></indexterm> 66 </glossterm> 67 <glossdef><para>Code that knows how to take font data in 68 its raw format and convert it to the font server's 69 format.</para></glossdef> 70 </glossentry> 71 <glossentry> 72 <glossterm> 73 <firstterm>Font Path Element (<acronym>FPE</acronym>)</firstterm> 74 <indexterm><primary>Font Path Element</primary></indexterm> 75 <indexterm><primary><acronym>FPE</acronym></primary><see>Font Path Element</see></indexterm> 76 </glossterm> 77 <glossdef><para>An instance of a renderer, associated with a specific 78 font source, (ie a directory of PCF bitmaps).</para></glossdef> 79 </glossentry> 80 </glosslist> 81 82 <para><indexterm><primary>difs layer</primary></indexterm> 83 The <firstterm>difs</firstterm> layer interprets the 84 requests, and handles the renderer independent work. This 85 includes error checking of requests, and the top level 86 font database. It also contains various utility 87 functionality such as caching and byte swapping.</para> 88 89 <para><indexterm><primary>os layer</primary></indexterm> 90 The <firstterm>os</firstterm> layer sets up the 91 communications channel, reads requests and sends the raw 92 data of replies and events. It also handles font server 93 configuration issues, controlled by command line 94 arguments and a configuration file.</para> 95 96 <para><indexterm><primary>renderer layer</primary></indexterm> 97 The <firstterm>renderer</firstterm> layer contains all 98 font-specific code, and is responsible for rendering a font 99 (which may mean just reading a bitmap from disk, or may 100 include scaling of outline data), computing a fonts 101 properties and header information.</para> 102 103 </sect2> 104 </sect1> 105 <sect1 id='startup'> 106 <title>Startup</title> 107 <para>At startup, the font server handles any command line 108 arguments, initializes any OS-specific data, and then sets up 109 the communications. Various internal databases are then 110 initialized (extensions, the font catalogue, etc).</para> 111 112 <para><indexterm><primary>configuration file</primary></indexterm> 113 The config file, an ordered list of font sources, cache 114 size hints, default resolutions, and security information, is 115 then read in. Each of these source names could be a directory 116 name, the name of another font server, or some other string 117 that a particular renderer can recognize.</para> 118 119 <para>The default font catalogue is then built up by taking 120 each of the font source names and comparing it with the 121 names a renderer recognizes. The one that matches this name 122 will become attached to this source. A renderer will 123 “understand” a name if it can parse the data in 124 that directory, or recognize that it is a valid font server 125 address, or recognizes a special string. Thus a collection 126 of valid font path elements is built up. Each 127 <emphasis remap='B'>FPE</emphasis> has a set of functions to 128 support opening a font and accessing its data.</para> 129 130 <para>Font information is accessed via method functions in the 131 <indexterm><primary><structname>Font</structname></primary></indexterm> 132 <structname>Font</structname>. When a font is first 133 loaded, the header information and properties are 134 loaded/computed. The font also initializes its function 135 pointers to do the proper work. When specific metrics or 136 bitmaps are required, they are access via the font's 137 functions. A disk-based bitmap font will probably want to 138 load all data when first accessed. A scaled font or FS font 139 may want to do more selective caching. In both cases, the 140 renderer can use the utility functions to keep track of this 141 data. Changing values of bitmap formats could result in the 142 font having multiple copies of data in different formats, 143 which the renderer may use the utility functions to 144 manage.</para> 145 </sect1> 146 <sect1 id='per_client_processing'> 147 <title>Per client processing</title> 148 <para>Each entity attaching to the server is a client. Each 149 client has its own authorization and resolution information, 150 and its own view of the font database. A font open to one 151 client may not be open to another, though the font server 152 may have it loaded.</para> 153 154 <para>After initialization, new clients can attach to the font 155 server and have their requests processed. For each request that 156 is searching for a font (<systemitem>OpenBitmapFont</systemitem>) or 157 listing font names (<systemitem>ListFonts</systemitem>, 158 <systemitem>ListFontsWithXInfo</systemitem>), the pattern 159 is given to each <emphasis remap='B'>FPE</emphasis>.</para> 160 161 <para><indexterm><primary><systemitem>OpenBitmapFont</systemitem></primary></indexterm> 162 <systemitem>OpenBitmapFont</systemitem> will take the supplied 163 name and pass it to each <emphasis remap='B'>FPE</emphasis>. 164 The <emphasis remap='B'>FPE</emphasis> will return one of 165 three things: <errorname>Success</errorname>, and the font 166 object; <errorname>BadFont</errorname>, because it doesn't 167 know the font; or <errorname>BadFont</errorname> and an 168 alias name, when it has an alias for the font. If 169 <errorname>Success</errorname> is returned, the server goes 170 on to create an ID (or find an existing one) and return a 171 reply. If <errorname>BadFont</errorname> is returned, it 172 goes on to the next <emphasis remap='B'>FPE</emphasis>. If 173 it reaches the end without finding a font, an error is 174 returned to the client. If an alias is returned, the search 175 resets to the first <emphasis remap='B'>FPE</emphasis> and 176 starts again, using the alias as the new font name. This 177 allows aliases to work across different 178 <emphasis remap='B'>FPEs</emphasis>, without any ordering 179 restrictions.</para> 180 181 <para>When each <emphasis remap='B'>FPE</emphasis> receives a font 182 name to open, it searches for the font's existence. If it 183 can't find, or can only find an alias, it returns 184 <errorname>BadFont</errorname> and any alias. If it finds 185 the font, it checks the authorization and license status of 186 the font to that of the client. If it passes, it then 187 creates a new font object, and reads and/or computes at 188 least the font's header information and properties. (It may 189 also want to produce the bitmaps and extents, but that 190 choice is left to the renderer.)</para> 191 192 <para>When a font's information is accessed, the interpreter 193 routine looks up the font ID to find the font object, and 194 then uses the font's access functions to get the data. These 195 functions will return the data in the format expected by the 196 client.</para> 197 </sect1> 198 199 <sect1 id='client_shutdown'> 200 <title>Client shutdown</title> 201 <para>When a client disconnects, all its references to any 202 fonts it still has opened are removed. If no other clients 203 reference these fonts, they may be freed, though the server may 204 choose to cache them.</para> 205 </sect1> 206 207 <sect1 id='server_reset_and_cleanup'> 208 <title>Server reset and cleanup</title> 209 <para>A server may be reset to flush the caches, re-read the 210 configuration file, and a new list of 211 <emphasis remap='B'>FPEs</emphasis> to be built, via an 212 OS-specific outside action. In UNIX, this will be handled via 213 signals; in VMS it could be handled via an async trap or event 214 flag.</para> 215 </sect1> 216 217 <sect1 id='server_offloading'> 218 <title>Server offloading</title> 219 <para>In order to deal with numerous clients without major 220 performance degradation, the server must be able to clone 221 itself, or provide the client with a substitute server via the 222 alternate server mechanism. Since both strategies have their 223 uses, both will be supported. For a server that has plenty of 224 host memory or CPU, but insufficient sockets, cloning may be a 225 good choice. For a host with limited memory, assigning an 226 alternate server on a different host may be a good choice. The 227 server will make this decision based on configuration options.</para> 228 </sect1> 229 230 <sect1 id='font_server_data_structures'> 231 <title>Font server data structures</title> 232 <para>The 233 <indexterm><primary><structname>Client</structname></primary></indexterm> 234 <firstterm id='struct_client'><structname>Client</structname></firstterm> 235 handles per-client information and interpreter status. 236 <synopsis> 237typedef struct _Client { 238 int index; 239 pointer osPrivate; 240 int noClientException; 241 int (**requestVector) (); 242 pointer requestBuffer; 243 int clientGone; 244 int sequence; 245 Bool swapped; 246 long last_request_time; 247 void (*pSwapReplyFunc) (); 248 AuthContextPtr auth; 249 char *catalogues; 250 int num_catalogues; 251 Mask eventmask; 252 fsResolution *resolutions; 253 int num_resolutions; 254} ClientRec, *ClientPtr; 255 </synopsis></para> 256 <para>The 257 <indexterm><primary><structname>Font</structname></primary></indexterm> 258 <firstterm id='struct_font'><structname>Font</structname></firstterm> 259 contains basic font information, including header information and 260 properties. 261 <synopsis> 262typedef struct _font { 263 int refcount; 264 fsHeader header; 265 fsBitmapFormat format; 266 int (*get_glyphs)(); 267 int (*get_metrics)(); 268 int (*get_extents)(); 269 int (*get_bitmaps)(); 270 int (*unload_font)(); 271 FontPathElementPtr fpe; 272 int *client_ids; 273 Bool restricted_font; 274} FontRec *FontPtr; 275 </synopsis></para> 276 <para>The 277 <indexterm><primary><structname>ClientFont</structname></primary></indexterm> 278 <firstterm id='struct_clientfont'><structname>ClientFont</structname></firstterm> 279 is a wrapper on top of <structname>Font</structname>, 280 handling client specific font information. 281 <synopsis> 282typedef struct _clientfont { 283 FontPtr font; 284 int clientindex; 285} ClientFontRec, *ClientFontRec; 286 </synopsis></para> 287 <para>The 288 <indexterm><primary><structname>AuthContext</structname></primary></indexterm> 289 290 <firstterm id='struct_authcontext'><structname>AuthContext</structname></firstterm> 291 contains authorization information. 292 <synopsis> 293typedef struct _authcontext { 294 char *authname; 295 char *authdata; 296 FSID acid; 297} AuthContextRec *AuthContextPtr; 298 </synopsis></para> 299 </sect1> 300 <sect1 id='font_path_element_functions'> 301 <title>Font Path Element functions</title> 302 <indexterm id='fpe_functions' class='startofrange'> 303 <primary>Font Path Element</primary></indexterm> 304 <para>These functions are associated with each renderer, and 305 handle all aspects of font access. Font data access is 306 controlled via another set of functions described later. These 307 functions are intended to support the R5 X server as well as 308 the font server. As a result, some design decisions were made 309 to support both models. When the 310 <emphasis remap='I'>difs</emphasis> layer needs to access a 311 font, it uses these functions.</para> 312 313 314 <synopsis> 315typedef unsigned long Mask; 316typedef unsigned char *pointer; 317 318typedef struct _FontPathElement { 319 int name_length; 320 char *name; 321 int type; 322 int refcount; 323 pointer private; 324} FontPathElementRec, *FontPathElementPtr; 325 </synopsis> 326 327 328 <para>The FPE's reference count is incremented when it is added 329 to the current list of FPEs and when it opens a font. It is 330 decremented when it is no longer in the current list and when 331 it closes a font. All reference changes are handled by the 332 <emphasis remap='I'>difs</emphasis> layer. The count is required 333 to support font catalogue changes that may occur while the 334 fontserver has fonts open, and keeps FPEs from being 335 lost.</para> 336 337 338 <synopsis> 339typedef struct FontNames { 340 int nnames; 341 int size; 342 int *length; 343 char **names; 344} FontNamesRec, *FontNamesPtr; 345 346typedef struct { 347 Bool (*name_check)(); 348 int (*init_fpe)(); 349 int (*reset_fpe)(); 350 int (*free_fpe)(); 351 int (*open_font)(); 352 int (*close_font)(); 353 int (*list_fonts)(); 354 int (*start_list_fonts_with_info)(); 355 int (*list_next_font_with_info)(); 356 int (*wakeup_fpe)(); 357 int (*client_died); 358 FontNamesPtr renderer_names; 359} FPEFunctions; 360 361int init_fpe_type(Bool (name_func)(), 362 int (init_func)(), int (free_func)(), int (reset_func), 363 int (open_func)(), int (close_func)(), 364 int (list_func)(), 365 int (start_lfwi_func)(), int (next_lfwi_func)(), 366 int (wakeup_func)(), 367 int (client_died_func)() 368 ) 369 </synopsis> 370 <para>This is called by the renderer when it is initialized at 371 the beginning of time, and sets up an FPEFunctions entry for 372 the renderer.</para> 373 <para>The 374 <emphasis remap='B'>FPEFunctions</emphasis> have the following 375 parameters:</para> 376 <para> 377 <synopsis> 378Bool name_check(char *<parameter>name</parameter>); 379 </synopsis> 380 381 If <parameter class="function">name</parameter> is something the 382 renderer recognizes as a valid font source name, it returns 383 <constant>True</constant>, otherwise <constant>False</constant>. 384 ie, if <parameter class="function">name</parameter> 385 is a directory name, or is prefixed by the renderer's prefix, 386 and the directory contains font data the renderer can interpret, 387 it would return <constant>True</constant>. 388 </para> 389 <para> 390 <synopsis> 391int init_fpe(FontPathElementPtr <parameter>fpe</parameter>); 392 </synopsis> 393 Does any initialization work for the renderer. The name in 394 <parameter class="function">fpe</parameter> will be one whose prefix 395 matches the list returned when the renderer was initialized. 396 </para> 397 <para> 398 <synopsis> 399int reset_fpe(FontPathElementPtr <parameter>fpe</parameter>); 400 </synopsis> 401 Tells <parameter class="function">fpe</parameter> to reset any 402 internal state about what fonts it has available. This will typically be 403 called because the font server's <emphasis remap='B'>FPE</emphasis> 404 search list has been changed. The 405 <parameter class="function">fpe</parameter> should reset any cached state 406 of available fonts (ie, re-read <filename>fonts.dir</filename>) 407 </para> 408 <para> 409 <synopsis> 410int free_fpe(FontPathElementPtr <parameter>fpe</parameter>); 411 </synopsis> 412 Frees any renderer-specific data and closes any files or sockets. 413 </para> 414 <para> 415 <synopsis> 416int open_font(pointer <parameter>client</parameter>, FontPathElementPtr <parameter>fpe</parameter>, Mask <parameter>flags</parameter>, 417 char *<parameter>fontname</parameter>, int <parameter>namelength</parameter>, 418 fsBitmapFormat <parameter>format_hint</parameter>, fsBitmapFormatMask <parameter>format_mask</parameter>, 419 XID <parameter>fontid</parameter>, FontPtr *<parameter>ppfont</parameter>, char **<parameter>alias</parameter>); 420 </synopsis> 421 422 Opens the font. The bits marked by 423 <parameter class="function">format_mask</parameter> and 424 <parameter class="function">format_hint</parameter> 425 are used where applicable. The resulting FontPtr is returned in 426 <parameter class="function">ppfont</parameter>. The 427 <parameter class="function">client</parameter> is optional state 428 information for use with blocking renderers. If the 429 <parameter class="function">fontname</parameter> resolves to an 430 alias, it is returned in <parameter class="function">alias</parameter> 431 with a <errorcode>FontNameAlias</errorcode> error. This tells 432 the calling code to start searching again, using 433 <parameter class="function">alias</parameter> as the font name. The 434 renderer is expected to fill in any information specified by the 435 <parameter class="function">flags</parameter>. 436 </para> 437 <para>Possible <parameter class="function">flags</parameter> values are: 438 <synopsis> 439#define FontLoadInfo 0x0001 /* font header info */ 440#define FontLoadProps 0x0002 /* font properties */ 441#define FontLoadMetrics 0x0004 /* font extents */ 442#define FontLoadBitmaps 0x0008 /* glyph bitmaps */ 443#define FontLoadAll 0x000f 444#define FontOpenSync 0x0010 /* force synchronous loading */ 445 </synopsis> 446 </para> 447 448 <para>Once a font has been opened, the server may place it and 449 the pattern it matched into a name cache, to avoid lengthy 450 searching if the font is reopened. If the renderer does not wish 451 the font to be in this cache (for licensing reasons), it should 452 set the font's <emphasis remap='I'>restricted_access</emphasis> 453 flag. 454 </para> 455 456 <para> 457 <synopsis> 458int close_font(FontPtr <parameter>pfont</parameter>); 459 </synopsis> 460 461 Frees up all the data associated with the font. 462 </para> 463 464 <para> 465 <synopsis> 466int list_fonts(pointer <parameter>client</parameter>, FontPathElementPtr <parameter>fpe</parameter>, 467 char *<parameter>pattern</parameter>, int <parameter>pattern_length</parameter>, int <parameter>maxnames</parameter>, 468 FontNamesPtr *<parameter>paths</parameter>); 469 </synopsis> 470 471 Returns in <parameter class="function">paths</parameter> up to 472 <parameter class="function">maxnames</parameter> font names the fpe 473 recognizes as matching the given pattern. 474 </para> 475 476 <para> 477 <synopsis> 478int start_list_fonts_with_info(pointer <parameter>client</parameter>, 479 FontPathElementPtr <parameter>fpe</parameter>, char *<parameter>pattern</parameter>, int <parameter>pattern_length</parameter>, 480 int <parameter>maxnames</parameter>, pointer <parameter>fpe_data</parameter>); 481 </synopsis> 482 483 Initiates a <systemitem>ListFontsWithXInfo</systemitem>. 484 Typically, a disk-based renderer will do the equivalent of 485 <systemitem>ListFonts</systemitem> to gather all the font names 486 matching the pattern. A font server renderer will send the 487 request. <parameter class="function">fpe_data</parameter> 488 provides a handle for any FPE-private data that needs to be 489 passed in later via 490 <function>list_next_font_with_info()</function>, eg, the list of 491 font names for a disk-based renderer. 492 </para> 493 494 <para> 495 <synopsis> 496int list_next_font_with_info(pointer <parameter>client</parameter>, FontPathElementPtr <parameter>fpe</parameter>, 497 char **<parameter>name</parameter>, int *<parameter>namelen</parameter>, FontInfoPtr *<parameter>pinfo</parameter>, 498 int *<parameter>num_fonts</parameter>, pointer <parameter>fpe_data</parameter>); 499 </synopsis> 500 501 Returns the next font's information. The renderer should keep any state 502 it requires in the <parameter class="function">fpe_data</parameter> 503 field. <parameter class="function">num_fonts</parameter> contains the 504 number of replies remaining. 505 </para> 506 507 <para>These two routines are split for because of the way both 508 disk-based renderers and font server renderers handle this 509 request. The first function initiates the action, the second is 510 used to gather the results. For a disk-based renderer, a list of 511 font names matching the pattern is first built up when 512 <function>start_list_fonts_with_info()</function>is called, and 513 the results are gathered with each call to 514 <function>list_next_font_with_info()</function>. In a font 515 server renderer, the first function sends the 516 <systemitem>ListFontsWithXInfo</systemitem> request, and the 517 second processes the replies. 518 </para> 519 520 <para> 521 <synopsis> 522int wakeup_fpe(FontPathElementPtr <parameter>fpe</parameter>, unsigned long *<parameter>mask</parameter>) 523 </synopsis> 524 525 Optional function which can be used for blocking 526 renderers. Typical usage is for a font server renderer, where it 527 is called when a reply is received, allowing the data to be read 528 and the client to be signaled and unblocked. 529 </para> 530 531 <para> 532 <synopsis> 533int client_died(pointer <parameter>client</parameter>, FontPathElementPtr <parameter>fpe</parameter>) 534 </synopsis> 535 536 537 This function is called when a client dies in the middle of a 538 blocked request, allowing the renderer to clean up. 539 </para> 540 <indexterm startref='fpe_functions' class='endofrange' /> 541 </sect1> 542 <sect1 id='font_specific_functions'> 543 <title>Font specific functions</title> 544 <indexterm id='font_functions' class='startofrange'> 545 <primary><structname>Font</structname></primary></indexterm> 546 <para>These functions are contained in each 547 <structname>Font</structname>. For many renderers, every 548 font will use the same functions, but some renderers may wish 549 to use different interfaces for different fonts.</para> 550 551 552 <synopsis> 553typedef struct { 554 INT16 left, 555 right; 556 INT16 width; 557 INT16 ascent, 558 descent; 559 CARD16 attributes; 560} fsCharInfo; 561 562typedef struct { 563 CARD8 low, 564 high; 565} fsChar2b; 566 567typedef struct { 568 fsChar2b min_char, 569 max_char; 570} fsRange; 571 572int get_extents(pointer <parameter>client</parameter>, 573 FontPtr <parameter>pfont</parameter>, Mask <parameter>flags</parameter>, int <parameter>num_ranges</parameter>, fsRange *<parameter>ranges</parameter>, 574 int *<parameter>num_extents</parameter>, fsCharInfo **<parameter>extents</parameter>); 575 </synopsis> 576 577 578 <para>Possible flags:</para> 579 580 581 <synopsis> 582LoadAll /* ignore the ranges and get everything */ 583FinishRange /* magic for range completion as specified by protocol */ 584 </synopsis> 585 586 587 <para>Builds up the requested array of extents. The extent data 588 (which the renderer allocates) is returned, as well as the 589 number of extents. 590 <emphasis remap='I'>closure</emphasis> contains any blocking 591 state information.</para> 592 593 <synopsis> 594 595 596int get_bitmaps(pointer <parameter>client</parameter>, 597 FontPtr <parameter>pfont</parameter>, fsBitmapFormat <parameter>format</parameter>, Mask <parameter>flags</parameter>, 598 int <parameter>num_ranges</parameter>, fsRange *<parameter>ranges</parameter>, 599 unsigned long *<parameter>size</parameter>, unsigned long *<parameter>num_glyphs</parameter>, 600 unsigned long **<parameter>offsets</parameter>, pointer *<parameter>glyph_data</parameter>); 601 </synopsis> 602 603 604 <para>Possible flags:</para> 605 606 <synopsis> 607LoadAll 608FinishRange /* magic for range completion as specified by protocol */ 609 </synopsis> 610 611 612 <para>Builds up the requested array of bitmaps. The glyph and 613 offset data (which the renderer allocates) is returned, as well 614 as the number of glyphs. The 615 <emphasis remap='I'>closure</emphasis> contains any blocking 616 state information. This function will build up the bitmap data 617 in the format specified by 618 <parameter class="function">format</parameter> so that the interpreter 619 can return it without any additional modification. This should 620 minimize data massaging, since outline renderers will hopefully 621 be able to produce the bitmaps in the proper format.</para> 622 623 <synopsis> 624void unload_font(FontPtr <parameter>pfont</parameter>) 625 </synopsis> 626 627 628 <para>The render will free any allocated data. Note that the 629 <emphasis remap='B'>FPE</emphasis> function 630 <function>close_font()</function> will also be called, and 631 should handle any 632 <emphasis remap='B'>FPE</emphasis> data allocated for the 633 font.</para> 634 635 <synopsis> 636int get_glyphs() 637int get_metrics() 638 </synopsis> 639 640 641 <para>These two functions are used by the X server for loading 642 glyphs and metrics. They expect the results in a considerably 643 different form. The 644 <function>get_bitmaps()</function> and 645 <function>get_extents()</function> routines both allow for 646 better cache control by the renderer.</para> 647 <indexterm startref='font_functions' class='endofrange' /> 648 </sect1> 649 <sect1 id='font_directories_and_aliases'> 650 <title>Font directories and aliases</title> 651 <para>Existing bitmap renderers already have their own concept 652 of font organization. In the X sample server, the files 653 <filename>fonts.dir</filename> and <filename>fonts.alias</filename> 654 are used to list the known fonts. <filename>fonts.dir</filename> 655 maps file names to font names, while <filename>fonts.alias</filename> 656 maps font names to other font names. 657 </para> 658 <para>These concepts will also be needed by other forms of 659 fonts which the sample X server does not currently use, but the 660 font server will, like Bitstream outlines.</para> 661 </sect1> 662 <sect1 id='handling_scalable_fonts'> 663 <title>Handling scalable fonts</title> 664 <para>For those renderers that support scalable fonts, several 665 issues must be addressed:</para> 666 <variablelist spacing='compact'> 667 <varlistentry> 668 <term><link linkend='name_parsing'>Name Parsing</link>.</term> 669 <listitem> 670 <para>An <acronym>XLFD</acronym> name must be parsed to 671 determine the requested resolutions and/or sizes.</para> 672 </listitem> 673 </varlistentry> 674 <varlistentry> 675 <term><link linkend='property_scaling'>Property scaling</link>.</term> 676 <listitem> 677 <para>Many of the standard font 678 properties have values that depend on scaling (eg, 679 <property>RESOLUTION_X</property>, 680 <property>POINT_SIZE</property>). </para> 681 </listitem> 682 </varlistentry> 683 <varlistentry> 684 <term><link linkend='default_values'>Default values</link>.</term> 685 <listitem> 686 <para>If resolution information is 687 wildcarded, the proper default resolution should be 688 supplied.</para> 689 </listitem> 690 </varlistentry> 691 </variablelist> 692 <sect2 id='name_parsing'> 693 <title>Name Parsing</title> 694 <para>The font name pattern supplied to 695 <systemitem>OpenBitmapFont</systemitem> or 696 <systemitem>ListFonts</systemitem> may require some 697 parsing to be recognized as a scalable font known to the 698 renderer. The 699 <property>PIXEL_SIZE</property>, 700 <property>POINT_SIZE</property>, 701 <property>RESOLUTION_X</property>, 702 <property>RESOLUTION_Y</property>, and 703 <property>AVERAGE_WIDTH</property> all need to 704 determined from the font name pattern. The master font 705 must then be found, and scaled appropriately. Any 706 unspecified values that cannot be determined should be 707 replaced by the proper defaults. For size fields, this is 708 whatever the configuration specifies. For resolution 709 fields, these should be taken from the client's 710 resolution list, if set, or from the server's 711 configuration.</para> 712 </sect2> 713 <sect2 id='property_scaling'> 714 <title>Property scaling</title> 715 <para>Part of scaling a font is scaling its properties. 716 Many scalable fonts will have a very large number of 717 scalable properties. One way to deal with these is for 718 the “master” outline to keep track of the 719 property names, and supply new values for each instance 720 of the font. If the property names are stored as Atoms, 721 memory usage is kept to a minimum.</para> 722 </sect2> 723 <sect2 id='default_values'> 724 <title>Using defaults</title> 725 <para>Using default values as substitutions for missing 726 values was covered above. These defaults will also be 727 useful in handling <systemitem>ListFonts</systemitem> requests. 728 Returning a scalable font with an instance using the 729 default values will provide the most user-friendly 730 environment.</para> 731 </sect2> 732 </sect1> 733 <sect1 id='access_control'> 734 <title>Access control</title> 735 <para>The font server will also support large grain security. 736 It will have both a limit of the number of users, and on the 737 hosts which it will support.</para> 738 <para>Limiting the number of users is as much a server loading 739 issue as a security issue. The limitation will be typically be 740 set via configuration options or OS limitations. To change it, 741 use:</para> 742 743 <synopsis> 744void AccessSetConnectionLimit(int <parameter>limit</parameter>) 745 </synopsis> 746 747 748 <para>A 749 <parameter class="function">limit</parameter> of 0 will set it to a 750 compiled constant based on OS resources (eg, number of file 751 descriptors).</para> 752 753 <para>Client-host based access control can be used to 754 supplement licensing, and support font server load balancing by 755 restricting access. As with licensing, this is OS-specific 756 code. To manipulate these functions, use: 757 758 <synopsis> 759typedef struct _host_address { 760 int type; 761 pointer address; 762 struct _host_address *next; 763} HostAddress; 764 765typedef HostAddress *HostList; 766 767int AddHost(HostList <parameter>list</parameter>, HostAddress *<parameter>address</parameter>) 768int RemoveHost(HostList <parameter>list</parameter>, HostAddress *<parameter>address</parameter>) 769Bool ValidHost(HostList <parameter>list</parameter>, HostAddress *<parameter>address</parameter>) 770 </synopsis> 771 772 773 <function>AddHost()</function> adds a host to the 774 <parameter class="function">list</parameter>. 775 <function>RemoveHost()</function> removes it, and 776 <function>ValidHost()</function> checks to see if its on the 777 <parameter class="function">list</parameter>. In all functions, 778 the <parameter class="function">address</parameter> will ignore 779 any value in the <structfield>next</structfield> field. 780 </para> 781 <para>Network addresses are used here to avoid issues with host 782 name aliases. The caller fills in the desired type, and an 783 address of that form is returned. This is highly OS-specific, 784 but values for the <structfield>type</structfield> and 785 <structfield>address</structfield> fields could include: 786 787 <synopsis> 788#define HOST_AF_INET 1 789struct in_addr *address; 790 791#define HOST_AF_DECnet 2 792struct dn_addr *address; 793 </synopsis> 794 </para> 795 796 <para>The server will use a global host list, but having the 797 list as an argument will allow licensing schemes to have their 798 own host lists.</para> 799 </sect1> 800 <sect1 id='licensing'> 801 <title>Licensing</title> 802 <para>Licensing is a tricky issue, which each renderer will 803 support in a different way. The sample font server will attempt 804 to provide some guidelines, and present a possible 805 implementation of some simple licensing schemes.</para> 806 <sect2> 807 <title>Host Address licensing</title> 808 <para>This is simplistic licensing based on the client's host. 809 With this form of licensing, a font may be accessible to some 810 host but not others. To get the current client's host, the 811 following is used: 812 813 <synopsis> 814void GetHostAddress(HostAddress *<parameter>address</parameter>); 815 </synopsis> 816 817 A renderer can also use the host access functions to keep 818 a list of the licensed hosts, and <function>ValidHost()</function> 819 to check a client.</para> 820 </sect2> 821 <sect2> 822 <title>Simultaneous use license</title> 823 <para>This licensing allows for a limited number of copies of 824 the font to be open at once. Since this should be a simple 825 per-font counter, no support should be required outside of the 826 renderer.</para> 827 </sect2> 828 </sect1> 829 <sect1 id='difs_contents'> 830 <title>DIFS contents</title> 831 <indexterm id='difs_functions' class='startofrange'> 832 <primary>difs layer</primary></indexterm> 833 <para>This contains the protocol dispatcher, interpreter and 834 reply encoding routines.</para> 835 836 <para>The interpreter is table driven off the request code. The 837 dispatcher gets a request from the os layer from 838 <function>WaitForSomething()</function>, and uses the 839 request code to determine which function to call. eg, a 840 <systemitem>CloseFont</systemitem> request would call 841 <function>ProcCloseFont()</function>.</para> 842 843 <para>Each request's routine handles any applicable error 844 checking, and then does as much work as it can. For font 845 related requests, this means converting the request to the 846 proper arguments for the renderers.</para> 847 848 <para>If any replies are generated, the reply data is gathered 849 into the bytestream format, and sent via 850 <emphasis remap='I'>os</emphasis> write functions to the 851 client.</para> 852 853 <para>If the byte order of the client and server differ, the 854 above is modified by having the dispatcher call an intermediate 855 function which re-orders the request to the proper byte order. 856 Replies go through similar swapping.</para> 857 858 <sect2> 859 <title>Client blocking</title> 860 <para>To minimize delay caused by font server request, clients 861 can be blocked while they wait for data to be produced. This is 862 primarily intended for 863 <emphasis remap='B'>FPEs</emphasis> using a remote font server, 864 but can be used anywhere where the font server can pause to 865 handle other client requests while data needed to satisfy 866 another is produced (possibly via multiple processes).</para> 867 868 <para> 869 <synopsis> 870Bool ClientSleep(ClientPtr <parameter>client</parameter>, Bool (*<parameter>function</parameter>)(), pointer <parameter>closure</parameter>) 871 </synopsis> 872 873 Puts a client to 'sleep'. This means the client will no 874 longer be considered while the server is dispatching requests. 875 <parameter class="function">function</parameter> will be called 876 when the client is signaled, with the 877 <parameter class="function">client</parameter> and 878 <parameter class="function">closure</parameter> as its arguments. 879 </para> 880 881 <para> 882 <synopsis> 883 Bool ClientSignal(ClientPtr <parameter>client</parameter>) 884 </synopsis> 885 886 This should be called when the client is ready to do more 887 work. At this point, the function given to 888 <function>ClientSleep()</function> will be called. 889 </para> 890 891 <para> 892 <synopsis> 893 void ClientWakeup(ClientPtr <parameter>client</parameter>) 894 </synopsis> 895 896 Puts the client back to its normal state processing requests. 897 </para> 898 899 <para> 900 <synopsis> 901 Bool ClientIsAsleep(ClientPtr <parameter>client</parameter>) 902 </synopsis> 903 904 905 Can be used to check if a client is asleep. This is 906 useful for handling client termination, so that any requests 907 the client is waiting upon can be properly cleaned up. 908 </para> 909 </sect2> 910 <sect2> 911 <title>Sample Usage</title> 912 913 <para>For handling a font server renderer request for 914 <function>OpenBitmapFont</function> the renderer will 915 send the request to the remote font server, and the call 916 <function>ClientSleep()</function>. The font server 917 will then continue processing requests from other clients, 918 while the one making the request is blocked. When the reply 919 returns, the renderer will notice when its 920 <function>wakeup_fpe()</function> function is called. At this 921 point the font server renderer will read and process the reply, 922 <function>ClientSignal()</function> will be called, 923 and the <parameter>closure</parameter> function will be called. 924 It will request the data from the renderer, completing the 925 request, and call 926 <function>ClientWakeup()</function> to return the 927 client to normal status.</para> 928 929 <para>This layer also contains the resource database, which 930 associates fonts with IDs, extension interface functions and 931 the server initialization and reset control.</para> 932 <indexterm startref='difs_functions' class='endofrange' /> 933 </sect2> 934 </sect1> 935 <sect1 id='os_contents'> 936 <title>OS contents</title> 937 <indexterm id='os_functions' class='startofrange'> 938 <primary>os layer</primary></indexterm> 939 <para>This layer contains OS specific routines for 940 configuration, command line parsing, client/server 941 communications, and various OS-dependent utilities such as 942 memory management and error handling.</para> 943 <para><function>ReadRequestFromClient()</function> 944 returns a full request to the dispatcher. 945 <function>WaitForSomething()</function> is where the 946 server spends its idle time, waiting for any action from a 947 client or processing any work left from a blocked 948 client.</para> 949 950 <para>When a client attempts to connect, the server will 951 call 952 953 <synopsis> 954int CheckClientAuthorization(ClientPtr <parameter>client</parameter>, AuthPtr <parameter>client_auth</parameter>, 955 int *<parameter>accept</parameter>, int *<parameter>index</parameter>, int *<parameter>size</parameter>, char **<parameter>authdata</parameter>) 956 </synopsis> 957 958 to see if the server is set to allow the client to connect. It 959 may use licensing or configuration information to determine if 960 the client can connect. 961 </para> 962 963 <para>When then connection is established, the server will use the 964 965 <synopsis> 966typedef struct _alt_server { 967 char subset; 968 char namelen; 969 char *name; 970} AlternateServerRec, *AlternateServerPtr; 971 972int ListAlternateServers(AlternateServerPtr *<parameter>servers</parameter>) 973 </synopsis> 974 975 976 to return any alternate server information it may have. 977 </para> 978 <para>When the client limit is reached, the font server may 979 attempt to copy itself, by calling 980 981 <synopsis> 982int CloneMyself() 983 </synopsis> 984 985 986 This function will (if the configuration options allow) 987 start a new font server process. This is done in such a way 988 that no pending connections should be lost, and that the 989 original server will accept no new connections. Once the 990 original server has no more clients, it will exit.</para> 991 992 <sect2> 993 <title>Catalogue manipulation</title> 994 995 <para>Catalogues are configuration dependent, and hence sent by 996 OS-dependent methods. In order for the 997 <emphasis remap='I'>difs</emphasis> layer to get them, it 998 uses 999 1000 <synopsis> 1001int ListCatalogues(char *<parameter>pattern</parameter>, int <parameter>pattern_length</parameter>, 1002 int <parameter>maxnames</parameter>, char **<parameter>catalogues</parameter>, int *<parameter>len</parameter>) 1003 </synopsis> 1004 1005 which returns the list of all catalogues it supports which match 1006 the pattern. This function will be used by the catalogue 1007 manipulation requests, as well as by renderers when they give 1008 their <systemitem>ListFonts</systemitem> results. 1009 </para> 1010 1011 <para> 1012 <synopsis> 1013int ValidateCatalogues(int <parameter>number</parameter>, char *<parameter>catalogues</parameter>) 1014 </synopsis> 1015 Can be used to validate a list of catalogues, returning 1016 <constant>True</constant> if the list is acceptable.</para> 1017 <indexterm startref='os_functions' class='endofrange' /> 1018 </sect2> 1019 </sect1> 1020 <sect1 id='utility_functions'> 1021 <title>Utility functions</title> 1022 <sect2> 1023 <title>Client data functions</title> 1024 1025 <para>These provide access to the current client's resolution 1026 and authorization data. This form of interface is supplied 1027 rather than passing it to all renderers in the <emphasis 1028 remap='B'>FPE</emphasis> functions because the data may be 1029 complex and/or uninteresting to all renderers.</para> 1030 1031 <para><synopsis> 1032AuthContextPtr GetClientAuthorization() 1033 </synopsis> 1034 1035 <indexterm><primary><structname>AuthContext</structname></primary></indexterm> 1036 Returns the authorization data for the current client.</para> 1037 1038 <para><synopsis> 1039fsResolution *GetClientResolutions(int *<parameter>num_resolutions</parameter>) 1040 </synopsis> 1041 1042 1043 Returns the list of resolutions that the current client has set.</para> 1044 </sect2> 1045 <sect2> 1046 <title>Byte swapping</title> 1047 1048 <para>Functions for swapping a 4-byte quantity, a 2-byte 1049 quantity and inverting a byte.</para> 1050 1051 <synopsis> 1052void BitOrderInvert(pointer <parameter>buffer</parameter>, unsigned long <parameter>num_bytes</parameter>) 1053void TwoByteSwap(pointer <parameter>buffer</parameter>, unsigned long <parameter>num_shorts</parameter>) 1054void FourByteSwap(pointer <parameter>buffer</parameter>, unsigned long <parameter>num_longs</parameter>) 1055 </synopsis> 1056 1057 1058 </sect2> 1059 <sect2> 1060 <title>Bitmap padding</title> 1061 1062 <para>Functions taking a desired extents and a bitmap that will 1063 return the bitmap properly padded.</para> 1064 1065 <para><synopsis> 1066int RepadBitmap(pointer <parameter>src</parameter>, pointer <parameter>dst</parameter>, fsFormat <parameter>src_format</parameter>, 1067 fsFormat <parameter>dst_format</parameter>, int <parameter>width</parameter>, int <parameter>height</parameter>) 1068 </synopsis> 1069 1070 Takes a bitmap in <parameter class="function">src_format</parameter> 1071 and converts it to one in 1072 <parameter class="function">dst_format</parameter>.</para> 1073 1074 </sect2> 1075 <sect2> 1076 <title>Atoms</title> 1077 1078 <para>Existing bitmap-based renderers use atoms to store strings 1079 for property information. Rather than duplicate this code in 1080 each renderer, it lives in the 1081 <filename class="directory">util</filename> directory.</para> 1082 1083 <para>Atoms will be especially useful for property information, 1084 to prevent many copies of the same strings from being saved. 1085 Using atoms for comparison when modifying properties after 1086 scaling is also more efficient. Since 1087 <emphasis remap='I'>atoms</emphasis> will will exist until the 1088 server is reset, they may want to be used sparingly for property 1089 values to avoid extraneous string data.</para> 1090 1091 <para><synopsis> 1092typedef unsigned long Atom; 1093 1094Atom MakeAtom(char *<parameter>string</parameter>, unsigned int <parameter>length</parameter>, Bool <parameter>create</parameter>) 1095 </synopsis> 1096 1097 1098 Returns the atom associated with 1099 <parameter class='function'>string</parameter>. If 1100 <parameter>create</parameter> is true, a new atom will be 1101 created. 1102 </para> 1103 1104 <para><synopsis> 1105char *NameForAtom(Atom atom) 1106 </synopsis> 1107 1108 Returns the string associated with 1109 <parameter class="function">atom</parameter>. 1110 </para> 1111 </sect2> 1112 </sect1> 1113 <sect1 id='server_request_details'> 1114 <title>Server request details</title> 1115 <para>This section describes in-depth the action of each 1116 protocol request. In all cases, the request is first error 1117 checked for simple length or value errors, with the server 1118 immediately returning an error if one is encountered.</para> 1119 <sect2 id='connection'> 1120 <title>Connection</title> 1121 <para>When a new client attempts to connect, the server first 1122 checks its initial authorization information to see if the 1123 server is willing to talk to it. This will be handled in some 1124 OS-specific form using <function>CheckClientAuthorization()</function>. 1125 If it passes this test, and the server has sufficient to 1126 resources to talk to it, the server sends accepts the 1127 connection and returns its connection block. If the 1128 connection fails, the server returns the proper status and a 1129 list of any alternate servers it may know of (gathered from 1130 <function> 1131 ListAlternateServers().)</function></para> 1132 </sect2> 1133 <sect2 id='listextension'> 1134 <title>ListExtension</title> 1135 <para>Returns the list of extensions the server knows about. 1136 Any extensions will be initialized when the server is first 1137 started.</para> 1138 </sect2> 1139 <sect2 id='queryextension'> 1140 <title>QueryExtension</title> 1141 <para>Returns the information about the requested extension, 1142 which was set when the extension was initialized.</para> 1143 </sect2> 1144 <sect2 id='listcatalogues'> 1145 <title>ListCatalogues</title> 1146 <para>Returns the catalogues the server recognizes (the 1147 results of <function>ListCatalogues()</function>.)</para> 1148 </sect2> 1149 <sect2 id='setcatalogues'> 1150 <title>SetCatalogues</title> 1151 <para>Sets the requesting client's catalogues after verifying 1152 them with the supported catalogues.</para> 1153 </sect2> 1154 <sect2 id='getcatalogues'> 1155 <title>GetCatalogues</title> 1156 <para>Returns the requesting client's catalogues.</para> 1157 </sect2> 1158 <sect2 id='createac'> 1159 <title>CreateAC</title> 1160 <para>Creates a new authorization context and fills it in. 1161 The list of authorization protocols is then checked by the 1162 server with 1163 <function>CheckClientAuthorization()</function>. If 1164 any are accepted, the 1165 <emphasis remap='B'>AC</emphasis> is placed in the resource 1166 database and <constant>Success</constant> is returned with the 1167 name of the accepted protocol. If more than one is accepted, 1168 <constant>Continue</constant> is returned with each 1169 of the accepted protocols, until the last one which has 1170 status <constant>Success</constant>. Otherwise 1171 <constant>Denied</constant> is returned.</para> 1172 </sect2> 1173 <sect2 id='freeac'> 1174 <title>FreeAC</title> 1175 <para>Looks up the 1176 <emphasis remap='B'>AC</emphasis> in the resource database, 1177 and frees it if it finds it. Otherwise an 1178 <errorname>Access</errorname> error is returned.</para> 1179 </sect2> 1180 <sect2 id='setauthorization'> 1181 <title>SetAuthorization</title> 1182 <indexterm><primary><structname>AuthContext</structname></primary></indexterm> 1183 <para>Looks up the 1184 <emphasis remap='B'>AC</emphasis> in the resource database, 1185 and set the client's AuthContextPtr to its value if it is 1186 found. Otherwise it sends an 1187 <errorname>Access</errorname> error.</para> 1188 </sect2> 1189 <sect2 id='setresolution'> 1190 <title>SetResolution</title> 1191 <para>Sets the requesting client's resolution list to the 1192 supplied list.</para> 1193 </sect2> 1194 <sect2 id='getresolution'> 1195 <title>GetResolution</title> 1196 <para>Returns the requesting client's list of resolutions.</para> 1197 </sect2> 1198 <sect2 id='listfonts'> 1199 <title>ListFonts</title> 1200 <para>Iterates over each open FPE, calling the FPE's 1201 <function>list_fonts()</function>routine passing it the 1202 pattern. When all FPE's have been processed, the list that 1203 has been built up is returned. Note that the same 1204 <structname>FontNamesPtr</structname> is sent to each 1205 FPE in turn, so that one list is built up. An FPE may 1206 restrict the fonts it returns based on the client's 1207 catalogue.</para> 1208 </sect2> 1209 <sect2 id='listfontswithxinfo'> 1210 <title>ListFontsWithXInfo</title> 1211 <para>Iterates over each FPE, calling its 1212 <function>start_list_fonts_with_info()</function>function to 1213 prime the FPE's renderer. It then calls the FPE's 1214 <function>list_next_font_with_info()</function>, sending each font's 1215 data to the client until no more fonts remain. When all FPEs 1216 have been processed, the final reply with a zero-length name 1217 is then sent to mark the end of the replies. An FPE may 1218 restrict the fonts it returns based on the client's 1219 catalogue. Note: an issue exists with font aliases which may 1220 require this to change, since an FPE may contain an alias 1221 pointing to another FPE, and cannot therefore return the 1222 font's info.</para> 1223 </sect2> 1224 <sect2 id='openbitmapfont'> 1225 <title>OpenBitmapFont</title> 1226 <para>The pattern is first searched for in the font server's 1227 name cache. If it doesn't find it, the server iterates over 1228 each FPE, calling its 1229 <function>open_font</function> function with the 1230 supplied pattern. This will return one of the following 1231 values:</para> 1232 <itemizedlist remap='IP'> 1233 <listitem> 1234 <para>an <errorname>Access</errorname> error, which means 1235 the renderer has the font but the client does not have 1236 access to it because of some form of licensing 1237 restriction</para> 1238 </listitem> 1239 <listitem> 1240 <para>a <errorname>Font</errorname> error and a NULL 1241 <emphasis remap='I'>alias</emphasis> parameter, which 1242 will cause the next FPE to be tried</para> 1243 </listitem> 1244 <listitem> 1245 <para>a <errorname>Font</errorname> error but a non-NULL 1246 <emphasis remap='I'>alias</emphasis>, which will cause 1247 the search to start over with the first FPE using 1248 <emphasis remap='I'>alias</emphasis> as the new font 1249 pattern</para> 1250 </listitem> 1251 <listitem> 1252 <para><errorname>Success</errorname>, 1253 in which case a valid font has been found.</para> 1254 </listitem> 1255 </itemizedlist> 1256 1257 <para>If the end of the FPE list is reached without having found 1258 the font, an error is returned to the client. If an 1259 <errorname>Access</errorname> error was encountered, it is 1260 returned, otherwise a <errorname>Font</errorname> error is 1261 returned. If a valid font is found, its reference count will 1262 be incremented and it will be checked to see if the client has 1263 already opened it before. If so, the previous ID will be 1264 returned. Otherwise the font will be placed in the resource 1265 database.</para> 1266 1267 <para>The renderer will fill in the font's header and property 1268 information, and may also choose to load or create the font's 1269 metrics or glyphs. If the glyphs are built, they will use any 1270 supplied <emphasis remap='I'>format hint</emphasis>.</para> 1271 1272 <para>Whenever a new font is successfully opened, the font and 1273 its name pattern will be placed in a name cache. This cache 1274 exists to minimize the amount of work spent searching for a 1275 font. It will be flushed when the font catalogue is 1276 modified. Client's with private font catalogues will require 1277 private name caches.</para> 1278 1279 </sect2> 1280 <sect2 id='queryxinfo'> 1281 <title>QueryXInfo</title> 1282 <para>The 1283 <emphasis remap='I'>fontid</emphasis> is looked up in the 1284 resource database, and the font's header and property info is 1285 returned.</para> 1286 </sect2> 1287 <sect2 id='queryxextents8_queryxextents16'> 1288 <title>QueryXExtents8 QueryXExtents16</title> 1289 <para>The 1290 <emphasis remap='I'>fontid</emphasis> is looked up in the 1291 resource database. The supplied list of characters 1292 (interpreted according to request type) is then translated 1293 into a list of ranges. The font's 1294 <function>get_extents()</function>function is then called. It 1295 builds the requested list of extents, and returns them along 1296 with the number of extents. The results are properly swapped 1297 and sent to the client.</para> 1298 </sect2> 1299 <sect2 id='queryxbitmaps8_queryxbitmaps16'> 1300 <title>QueryXBitmaps8 QueryXBitmaps16</title> 1301 <para>The 1302 <emphasis remap='I'>fontid</emphasis> is looked up in the 1303 resource database. The supplied list of characters 1304 (interpreted according to request type) is then translated 1305 into a list of ranges. The font's 1306 <function>get_bitmaps()</function>function is called, and the 1307 renderer will build up the requested bitmaps, using the 1308 specified 1309 <emphasis remap='I'>format</emphasis>, and returns the 1310 bitmaps, the number of glyphs and the offsets. The offsets 1311 are properly swapped and the offsets and bitmaps are sent to 1312 the clients.</para> 1313 </sect2> 1314 <sect2 id='closefont'> 1315 <title>CloseFont</title> 1316 <para>The font's reference count is decremented. If this was 1317 the last reference, the font's 1318 <function>unload_font()</function>function is called to free 1319 the renderer's data, and the font's FPE 1320 <function>close_font()</function>function is called to free 1321 up any FPE specific data.</para> 1322 </sect2> 1323 </sect1> 1324 <sect1 id='configuration'> 1325 <title>Configuration</title> 1326 <indexterm><primary>configuration file</primary></indexterm> 1327 <para>The configuration mechanism is a simple keyword-value 1328 pair, separated by an '<literal>=</literal>'.</para> 1329 <variablelist> 1330 <title>Configuration types:</title> 1331 <varlistentry> 1332 <term><type>cardinal</type></term> 1333 <listitem><para>non-negative number</para></listitem> 1334 </varlistentry> 1335 <varlistentry> 1336 <term><type>boolean</type></term> 1337 <listitem><para>"[Yy]es", "[Yy]" "on", "1", "[Nn]o", "[Nn]", "off", "0"</para></listitem> 1338 </varlistentry> 1339 <varlistentry> 1340 <term><type>resolution</type></term> 1341 <listitem><para><type>cardinal</type><literal>,</literal><type>cardinal</type></para></listitem> 1342 </varlistentry> 1343 <varlistentry> 1344 <term><type>list of foo</type></term> 1345 <listitem><para>1 or more of foo, separated by commas</para></listitem> 1346 </varlistentry> 1347 </variablelist> 1348 <variablelist> 1349 <title>Here is an incomplete list of the supported keywords:</title> 1350 <varlistentry> 1351 <term><literal>#</literal></term> 1352 <listitem><para>in the first column, a comment character</para></listitem> 1353 </varlistentry> 1354<!-- 1355 <varlistentry> 1356 <term><literal>cache-size</literal> <type>(cardinal)</type></term> 1357 <listitem><para>Size in bytes of the FS cache.r</para></listitem> 1358 </varlistentry> 1359 --> 1360 <varlistentry> 1361 <term><literal>catalogue</literal> <type>(list of string)</type></term> 1362 <listitem><para>Ordered list of font path element names.</para></listitem> 1363 </varlistentry> 1364 <varlistentry> 1365 <term><literal>alternate-servers</literal> <type>(list of string)</type></term> 1366 <listitem><para>List of alternate servers for this FS.</para></listitem> 1367 </varlistentry> 1368 <varlistentry> 1369 <term><literal>client-limit</literal> <type>(cardinal)</type></term> 1370 <listitem><para>Number of clients this FS will support before refusing 1371 service.</para></listitem> 1372 </varlistentry> 1373 <varlistentry> 1374 <term><literal>clone-self</literal> <type>(boolean)</type></term> 1375 <listitem><para>Whether this FS should attempt to clone itself or 1376 use delegates when it reaches the client-limit.</para></listitem> 1377 </varlistentry> 1378 <varlistentry> 1379 <term><literal>default-point-size</literal> <type>(cardinal)</type></term> 1380 <listitem><para>The default pointsize (in decipoints) for fonts that 1381 don't specify.</para></listitem> 1382 </varlistentry> 1383 <varlistentry> 1384 <term><literal>default-resolutions</literal> <type>(list of resolutions)</type></term> 1385 <listitem><para>Resolutions the server supports by default. 1386 This information may be used as a hint for pre-rendering.</para></listitem> 1387 </varlistentry> 1388 <varlistentry> 1389 <term><literal>error-file</literal> <type>(string)</type></term> 1390 <listitem><para>Filename of the error file. All warnings and errors 1391 will be logged here. This information may be used as a hint 1392 for pre-rendering.</para></listitem> 1393 </varlistentry> 1394 <varlistentry> 1395 <term><literal>port</literal> <type>(cardinal)</type></term> 1396 <listitem><para> 1397 The TCP port on which the server will listen for connections. 1398 </para></listitem> 1399 </varlistentry> 1400 <varlistentry> 1401 <term><literal>use-syslog</literal> <type>(boolean)</type></term> 1402 <listitem><para> 1403 Whether syslog(3) is to be used for errors. 1404 </para></listitem> 1405 </varlistentry> 1406<!-- 1407 <varlistentry> 1408 <term><literal>trusted-clients</literal> <type>(list of string)</type></term> 1409 <listitem><para> 1410 Those clients the fontserver will talk to. Others 1411 will be refused for the initial connection. An empty 1412 list means the server will talk to any client. 1413 </para></listitem> 1414 </varlistentry> 1415 --> 1416 </variablelist> 1417 <para>Each renderer may also want private configuration 1418 options. The names should be prefixed by the renderer name, ie 1419 <literal>pcf-</literal>, <literal>atm-</literal>.</para> 1420 <example> 1421 <title>Sample Configuration Entries:</title> 1422 <programlisting> 1423# allow a ~a megabyte of memory to be reserved for cache data 1424cache-size = 1000000 1425 1426catalogue = pcf:/usr/lib/X11/fonts/misc,speedo:/usr/lib/fonts/speedo 1427 </programlisting> 1428 </example> 1429 </sect1> 1430 <index/> 1431</article> 1432