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