home *** CD-ROM | disk | FTP | other *** search
/ Chip 2001 August - Disc 2 / chip_20018102_hu.iso / linux / X-4.1.0 / doc / fontlib.txt < prev    next >
Text File  |  2001-06-27  |  16KB  |  529 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.              The X Font Library
  11.  
  12.                Keith Packard
  13.               MIT X Consortium
  14.  
  15.             David Lemke
  16.          Network Computing Devices
  17.  
  18.  
  19. This document describes the data structures and interfaces
  20. for using the X Font library.  It is intended as a reference
  21. for programmers building X and Font servers.  You may want
  22. to refer to the following documents:
  23.  
  24. o    "Definition of the Porting Layer for the X v11 Sample
  25.      Server" for a discussion on how this library interacts
  26.      with the X server
  27.  
  28. o    "Font Server Implementation Overview" which discusses
  29.      the design of the font server.
  30.  
  31. o    "Bitmap Distribution Format" which covers the contents
  32.      of the bitmap font files which this library reads;
  33.      although the library is capable of reading other for-
  34.      mats as well, including non-bitmap fonts.
  35.  
  36. o    "The X Font Service Protocol" for a description of the
  37.      constraints placed on the design by including support
  38.      for this font service mechanism.
  39.  
  40. This document assumes the reader is familiar with the X
  41. server design, the X protocol as it relates to fonts and the
  42. C programming language.  As with most MIT produced documen-
  43. tation, this relies heavily on the source code, so have a
  44. listing handy.
  45.  
  46. 1.  Requirements for the Font library
  47.  
  48. To avoid miles of duplicate code in the X server, the font
  49. server and the various font manipulation tools, the font
  50. library should provide interfaces appropriate for all of
  51. these tasks.  In particular, the X server and font server
  52. should be able to both use the library to access disk based
  53. fonts, and to communicate with a font server.  By providing
  54. a general library, we hoped to avoid duplicating code
  55. between the X server and font server.
  56.  
  57. Another requirement is that the X server (or even a font
  58. server) be able to continue servicing requests from other
  59. clients while awaiting a response from the font server on
  60. behalf of one client.  This is the strongest requirement
  61.  
  62.  
  63.  
  64. Font Library Interface        - 1 -           July 27, 1991
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72.  
  73. placed on the font library, and has warped the design in
  74. curious ways.  Because both the X server and font server are
  75. single threaded, the font library must not suspend inter-
  76. nally, rather it returns an indication of suspension to the
  77. application which continues processing other things, until
  78. the font data is ready, at which time it restarts the sus-
  79. pended request.
  80.  
  81. Because the code for reading and manipulating bitmap font
  82. data is used by the font applications "mkfontdir" and
  83. "bdftopcf", the font library includes bitmap-font specific
  84. interfaces which those applications use, instead of the more
  85. general interfaces used by the X and font servers, which are
  86. unaware of the source of the font data.  These routines will
  87. be refered to as the bitmap font access methods.
  88.  
  89. 2.  General Font Library Interface details.
  90.  
  91. To avoid collision between the #define name space for
  92. errors, the Font library defines a new set of return values:
  93.  
  94.      #define AllocError      80
  95.      #define StillWorking    81
  96.      #define FontNameAlias   82
  97.      #define BadFontName     83
  98.      #define Suspended         84
  99.      #define Successful      85
  100.      #define BadFontPath     86
  101.      #define BadCharRange    87
  102.      #define BadFontFormat   88
  103.      #define FPEResetFailed  89
  104.  
  105. Whenever a routine returns Suspended, the font library will
  106. notify the caller (via the ClientSignal interface described
  107. below) who should then reinvoke the same routine again with
  108. the same arguments.
  109.  
  110. 3.  Font Path Elements
  111.  
  112. At the center of the general font access methods used by X
  113. and fs is the Font Path Element data structure.  Like most
  114. structures in the X server, this contains a collection of
  115. data and some function pointers for manipulating this data:
  116.  
  117.      /* External view of font paths */
  118.      typedef struct _FontPathElement {
  119.      int         name_length;
  120.      char        *name;
  121.      int         type;
  122.      int         refcount;
  123.      pointer     private;
  124.      } FontPathElementRec, *FontPathElementPtr;
  125.  
  126.      typedef struct _FPEFunctions {
  127.  
  128.  
  129.  
  130. Font Library Interface        - 2 -           July 27, 1991
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138.  
  139.      int         (*name_check) ( /* name */ );
  140.      int         (*init_fpe) ( /* fpe */ );
  141.      int         (*reset_fpe) ( /* fpe */ );
  142.      int         (*free_fpe) ( /* fpe */ );
  143.      int         (*open_font) (  /* client, fpe, flags,
  144.                  name, namelen, format,
  145.                  fid,  ppfont, alias */ );
  146.      int         (*close_font) ( /* pfont */ );
  147.      int         (*list_fonts) ( /* client, fpe, pattern,
  148.                  patlen, maxnames, paths */ );
  149.      int         (*start_list_fonts_with_info) (
  150.                  /* client, fpe, name, namelen,
  151.                 maxnames, data */ );
  152.      int         (*list_next_font_with_info) (
  153.                  /* client, fpe, name, namelen,
  154.                 info, num, data */ );
  155.      int         (*wakeup_fpe) ( /* fpe, mask */ );
  156.      int         (*client_died) ( /* client, fpe */ );
  157.      } FPEFunctionsRec, FPEFunctions;
  158.  
  159. The function pointers are split out from the data structure
  160. to save memory; additionally, this avoids any complications
  161. when initializing the data structure as there would not be
  162. any way to discover the appropriate function to call (a
  163. chicken and egg problem).
  164.  
  165. When a font path type is initialized, it passes the function
  166. pointers to the server which are then stored in an FPEFunc-
  167. tionsRec.  Each function is described below in turn.
  168.  
  169. 3.1.  (*name_check)
  170.  
  171. Each new font path member is passed to this function; if the
  172. return value is Successful, then the FPE recognises the for-
  173. mat of the string.  This does not guarantee that the FPE
  174. will be able to successfully use this member.  For example,
  175. the disk-based font directory file "fonts.dir" may be cor-
  176. rupted, this will not be detected until the font path is
  177. initialized.  This routine never returns Suspended.
  178.  
  179. 3.2.  (*init_fpe)
  180.  
  181. Initialize a new font path element.  This function prepares
  182. a new font path element for other requests:  the disk font
  183. routine reads the "fonts.dir" and "fonts.alias" files into
  184. the internal format, while the font server routine connects
  185. to the requested font server and prepares for using it.
  186. This routine returns Successful if everything went OK, oth-
  187. erwise the return value indicates the source of the problem.
  188. This routine never returns Suspended.
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.  
  196. Font Library Interface        - 3 -           July 27, 1991
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  
  203.  
  204.  
  205. 3.3.  (*reset_fpe)
  206.  
  207. When the X font path is reset, and some of the new members
  208. are also in the old font path, this function is called to
  209. reinitialize those FPEs.  This routine returns Successful if
  210. everything went OK.  It returns FPEResetFailed if (for some
  211. reason) the reset failed, and the caller should remove the
  212. old FPE and simply create a new one in its place.  This is
  213. used by the disk-based fonts routine as resetting the inter-
  214. nal directory structures would be more complicated than sim-
  215. ply having destroying the old and creating a new.
  216.  
  217. 3.4.  (*free_fpe)
  218.  
  219. When the server is finished with an FPE, this function is
  220. called to dispose of any internal state.  It should return
  221. Successful, unless something terrible happens.
  222.  
  223. 3.5.  (*open_font)
  224.  
  225. This routine requests that a font be opened.  The client
  226. argument is used by the font library only in connection with
  227. suspending/restarting the request.  The flags argument spec-
  228. ifies some behaviour for the library and can be any of:
  229.  
  230.      /* OpenFont flags */
  231.      #define FontLoadInfo    0x0001
  232.      #define FontLoadProps   0x0002
  233.      #define FontLoadMetrics 0x0004
  234.      #define FontLoadBitmaps 0x0008
  235.      #define FontLoadAll     0x000f
  236.      #define FontOpenSync    0x0010
  237.  
  238. The various fields specify which portions of the font should
  239. be loaded at this time.  When FontOpenSync is specified,
  240. this routine will not return until all of the requested por-
  241. tions are loaded.  Otherwise, this routine may return Sus-
  242. pended.  When the presented font name is actually an alias
  243. for some other font name, FontName Alias is returned, and
  244. the actual font name is stored in the location pointed to by
  245. the alias argument as a null-terminated string.
  246.  
  247. 3.6.  (*close_font)
  248.  
  249. When the server is finished with a font, this routine dis-
  250. poses of any internal state and frees the font data struc-
  251. ture.
  252.  
  253. 3.7.  (*list_fonts)
  254.  
  255. The paths argument is a data structure which will be filled
  256. with all of the font names from this directory which match
  257. the specified pattern.    At most maxnames will be added.
  258. This routine may return Suspended.
  259.  
  260.  
  261.  
  262. Font Library Interface        - 4 -           July 27, 1991
  263.  
  264.  
  265.  
  266.  
  267.  
  268.  
  269.  
  270.  
  271. 3.8.  (*start_list_fonts_with_info)
  272.  
  273. This routine sets any internal state for a verbose listing
  274. of all fonts matching the specified pattern.  This routine
  275. may return Suspended.
  276.  
  277. 3.9.  (*list_next_font_with_info)
  278.  
  279. To avoid storing huge amounts of data, the interface for
  280. ListFontsWithInfo allows the server to get one reply at a
  281. time and forward that to the client.  When the font name
  282. returned is actually an alias for some other font, Font-
  283. NameAlias will be returned.  The actual font name is return
  284. instead, and the font alias which matched the pattern is
  285. returned in the location pointed to by data as a null-termi-
  286. nated string.  The caller can then get the information by
  287. recursively listing that font name with a maxnames of 1.
  288. When Successful is returned, the matching font name is
  289. returned, and a FontInfoPtr is stored in the location
  290. pointed to by data.  Data must be initialized with a pointer
  291. to a FontInfoRec allocated by the caller.  When the pointer
  292. pointed to by data is not left pointing at that storage, the
  293. caller mustn't free the associated property data.  This rou-
  294. tine may return Suspended.
  295.  
  296. 3.10.  (*wakeup_fpe)
  297.  
  298. Whenever an FPE function has returned Suspended, this rou-
  299. tine is called whenever the application wakes up from wait-
  300. ing for input (from select(2)).  This mask argument should
  301. be the value returned from select(2).
  302.  
  303. 3.11.  (*client_died)
  304.  
  305. When an FPE function has returned Suspended and the associ-
  306. ated client is being destroyed, this function allows the
  307. font library to dispose of any state associated with that
  308. client.
  309.  
  310. 4.  Fonts
  311.  
  312. The data structure which actually contains the font informa-
  313. tion has changed significantly since previous releases; it
  314. now attempts to hide the actual storage format for the data
  315. from the application, providing accessor functions to get at
  316. the data.  This allows a range of internal details for dif-
  317. ferent font sources.  The structure is split into two
  318. pieces, so that ListFontsWithInfo can share information from
  319. the font when it has been loaded.  The FontInfo structure,
  320. then, contains only information germane to LFWI.
  321.  
  322.      typedef struct _FontInfo {
  323.      unsigned short firstCol;         /* range of glyphs for this font */
  324.      unsigned short lastCol;
  325.  
  326.  
  327.  
  328. Font Library Interface        - 5 -           July 27, 1991
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  
  335.  
  336.  
  337.      unsigned short firstRow;
  338.      unsigned short lastRow;
  339.      unsigned short defaultCh;         /* default character index */
  340.      unsigned int noOverlap:1;         /* no combination of glyphs overlap */
  341.      unsigned int terminalFont:1;         /* Character cell font */
  342.      unsigned int constantMetrics:1;     /* all metrics are the same */
  343.      unsigned int constantWidth:1;         /* all character widths are the same*/
  344.      unsigned int inkInside:1;         /* all ink inside character cell */
  345.      unsigned int inkMetrics:1;         /* font has ink metrics */
  346.      unsigned int allExist:1;         /* no missing chars in range */
  347.      unsigned int drawDirection:2;         /* left-to-right/right-to-left*/
  348.      unsigned int cachable:1;         /* font needn't be opened each time*/
  349.      unsigned int anamorphic:1;         /* font is strangely scaled */
  350.      short         maxOverlap;         /* maximum overlap amount */
  351.      short         pad;             /* unused */
  352.      xCharInfo   maxbounds;          /* glyph metrics maximums */
  353.      xCharInfo   minbounds;          /* glyph metrics minimums */
  354.      xCharInfo   ink_maxbounds;         /* ink metrics maximums */
  355.      xCharInfo   ink_minbounds;         /* ink metrics minimums */
  356.      short         fontAscent;         /* font ascent amount */
  357.      short         fontDescent;         /* font descent amount */
  358.      int         nprops;             /* number of font properties */
  359.      FontPropPtr props;             /* font properties */
  360.      char        *isStringProp;         /* boolean array */
  361.      }         FontInfoRec, *FontInfoPtr;
  362.  
  363. The font structure, then, contains a font info record, the
  364. format of the bits in each bitmap and the functions which
  365. access the font records (which are stored in an opaque for-
  366. mat hung off of fontPrivate).
  367.  
  368.      typedef struct _Font {
  369.      int         refcnt;
  370.      FontInfoRec info;
  371.      char         bit;             /* bit order: LSBFirst/MSBFirst */
  372.      char         byte;             /* byte order: LSBFirst/MSBFirst */
  373.      char         glyph;             /* glyph pad: 1, 2, 4 or 8 */
  374.      char         scan;             /* glyph scan unit: 1, 2 or 4 */
  375.      fsBitmapFormat format;          /* FS-style format (packed) */
  376.      int         (*get_glyphs) ( /* font, count, chars, encoding, count, glyphs */ );
  377.      int         (*get_metrics) ( /* font, count, chars, encoding, count, glyphs */ );
  378.      int         (*get_bitmaps) (/* client, font, flags, format,
  379.                     flags, nranges, ranges, data_sizep,
  380.                     num_glyphsp, offsetsp, glyph_datap,
  381.                     free_datap */ );
  382.      int         (*get_extents) (/* client, font, flags, nranges,
  383.                      ranges, nextentsp, extentsp */);
  384.      void         (*unload_font) ( /* font */ );
  385.      FontPathElementPtr fpe;         /* FPE associated with this font */
  386.      pointer     svrPrivate;         /* X/FS private data */
  387.      pointer     fontPrivate;         /* private to font */
  388.      pointer     fpePrivate;         /* private to FPE */
  389.      int         maxPrivate;         /* devPrivates (see below) */
  390.      pointer     *devPrivates;         /*  ... */
  391.  
  392.  
  393.  
  394. Font Library Interface        - 6 -           July 27, 1991
  395.  
  396.  
  397.  
  398.  
  399.  
  400.  
  401.  
  402.  
  403.      }         FontRec, *FontPtr;
  404.  
  405. Yes, there are several different private pointers in the
  406. Font structure; they were added haphazardly until the
  407. devPrivate pointers were added.  Future releases may remove
  408. some (or all) of the specific pointers, leaving only the
  409. devPrivates mechanism.
  410.  
  411. There are two similar interfaces implemented -
  412. get_glyphs/get_metrics and get_bitmaps/get_extents.  Too
  413. little time caused the font-server specific interfaces to be
  414. placed in the font library (and portions duplicated in each
  415. renderer) instead of having them integrated into the font
  416. server itself.    This may change.  The X server uses only
  417. get_glyphs/get_metrics, and those will not change dramati-
  418. cally.    Each of the routines is described below
  419.  
  420. 4.1.  (*get_glyphs)
  421.  
  422. This routine returns CharInfoPtrs for each of the requested
  423. characters in the font.  If the character does not exist in
  424. the font, the default character will be returned, unless no
  425. default character exists in which case that character is
  426. skipped.  Thus, the number of glyphs returned will not
  427. always be the same as the number of characters passed in.
  428.  
  429. 4.2.  (*get_metrics)
  430.  
  431. This is similar to (*get_glyphs) except that pointers to
  432. xCharInfo structures are returned, and, if the font has ink
  433. metrics, those are returned instead of the bitmap metrics.
  434.  
  435. 4.3.  (*get-bitmaps)
  436.  
  437. This packs the glyph image data in the requested format and
  438. returns it.  The ranges/nranges argument specify the set of
  439. glyphs from the font to pack together.
  440.  
  441. 4.4.  (*get_extents)
  442.  
  443. This returns the metrics for the specified font from the
  444. specified ranges.
  445.  
  446.  
  447. 4.5.  (*unload_font)
  448.  
  449. This is called from the FPE routine (*close_font), and so
  450. should not ever be called from the application.
  451.  
  452. 4.6.  maxPrivate
  453.  
  454. When initializing a new font structure, maxPrivate should be
  455. set to -1 so that the FontSetPrivate() macro works properly
  456. with an index of 0.  Initializing maxPrivate to 0 can cause
  457.  
  458.  
  459.  
  460. Font Library Interface        - 7 -           July 27, 1991
  461.  
  462.  
  463.  
  464.  
  465.  
  466.  
  467.  
  468.  
  469. problems if the server tries to set something at index 0.
  470.  
  471.  
  472.  
  473.  
  474.  
  475.  
  476.  
  477.  
  478.  
  479.  
  480.  
  481.  
  482.  
  483.  
  484.  
  485.  
  486.  
  487.  
  488.  
  489.  
  490.  
  491.  
  492.  
  493.  
  494.  
  495.  
  496.  
  497.  
  498.  
  499.  
  500.  
  501.  
  502.  
  503.  
  504.  
  505.  
  506.  
  507.  
  508.  
  509.  
  510.  
  511.  
  512.  
  513.  
  514.  
  515.  
  516.  
  517.  
  518.  
  519.  
  520.  
  521.  
  522.  
  523.  
  524.  
  525.  
  526. Font Library Interface        - 8 -           July 27, 1991
  527.  
  528.  
  529.