| <head> |
| <title>cachechars(3) - Plan 9 from User Space</title> |
| <meta content="text/html; charset=utf-8" http-equiv=Content-Type> |
| </head> |
| <body bgcolor=#ffffff> |
| <table border=0 cellpadding=0 cellspacing=0 width=100%> |
| <tr height=10><td> |
| <tr><td width=20><td> |
| <tr><td width=20><td><b>CACHECHARS(3)</b><td align=right><b>CACHECHARS(3)</b> |
| <tr><td width=20><td colspan=2> |
| <br> |
| <p><font size=+1><b>NAME </b></font><br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| cachechars, agefont, loadchar, Subfont, Fontchar, Font – font utilities<br> |
| |
| </table> |
| <p><font size=+1><b>SYNOPSIS </b></font><br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| <tt><font size=+1>#include <u.h><br> |
| #include <libc.h><br> |
| #include <draw.h> |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| <tt><font size=+1>int cachechars(Font *f, char **s, Rune **r, ushort *c, int max, |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| <tt><font size=+1>int *widp, char **sfname) |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| |
| </table> |
| |
| </table> |
| <tt><font size=+1>int loadchar(Font *f, Rune r, Cacheinfo *c, int h, |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| <tt><font size=+1>int noclr, char **sfname) |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| |
| </table> |
| |
| </table> |
| <tt><font size=+1>void agefont(Font *f)<br> |
| </font></tt> |
| </table> |
| <p><font size=+1><b>DESCRIPTION </b></font><br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| A <i>Font</i> may contain too many characters to hold in memory simultaneously. |
| The graphics library and draw device (see <a href="../man3/draw.html"><i>draw</i>(3)</a>) cooperate to |
| solve this problem by maintaining a cache of recently used character |
| images. The details of this cooperation need not be known by most |
| programs: <i>initdraw</i> and its associated |
| <i>font</i> variable, <i>openfont</i>, <i>stringwidth</i>, <i>string</i>, and <i>freefont</i> are |
| sufficient for most purposes. The routines described below are |
| used internally by the graphics library to maintain the font cache. |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| A <tt><font size=+1>Subfont</font></tt> is a set of images for a contiguous range of characters, |
| stored as a single image with the characters placed side-by-side |
| on a common baseline. It is described by the following data structures.<br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| <tt><font size=+1>typedef<br> |
| struct Fontchar {<br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| int x; /* left edge of bits */<br> |
| uchar top; /* first non−zero scan−line */<br> |
| uchar bottom; /* last non−zero scan−line */<br> |
| char left; /* offset of baseline */<br> |
| uchar width; /* width of baseline */<br> |
| |
| </table> |
| } Fontchar;<br> |
| typedef<br> |
| struct Subfont {<br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| char *name;<br> |
| short n; /* number of chars in subfont */<br> |
| uchar height; /* height of image */<br> |
| char ascent; /* top of image to baseline */<br> |
| Fontchar *info; /* n+1 Fontchars */<br> |
| Image *bits; /* of font */<br> |
| |
| </table> |
| } Subfont;<br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| |
| </table> |
| The image fills the rectangle <tt><font size=+1>(0, 0,</font></tt> <i>w</i><tt><font size=+1>, height)</font></tt>, where <i>w</i> is the |
| sum of the horizontal extents (of non-zero pixels) for all characters. |
| The pixels to be displayed for character <i>c</i> are in the rectangle |
| <tt><font size=+1>(</font></tt><i>i</i><tt><font size=+1>−>x,</font></tt> <i>i</i><tt><font size=+1>−>top, (</font></tt><i>i</i><tt><font size=+1>+1)−>x,</font></tt> <i>i</i><tt><font size=+1>−>bottom)</font></tt> where <i>i</i> is <tt><font size=+1>&subfont−>info[</font></tt><i>c</i><tt><font size=+1>]</font></tt>. When |
| a character is displayed |
| at <tt><font size=+1>Point p</font></tt> in an image, the character rectangle is placed at <tt><font size=+1>(p.x+</font></tt><i>i</i><tt><font size=+1>−>left, |
| p.y)</font></tt> and the next character of the string is displayed at <tt><font size=+1>(p.x+</font></tt><i>i</i><tt><font size=+1>−>width, |
| p.y)</font></tt>. The baseline of the characters is <tt><font size=+1>ascent</font></tt> rows down from |
| the top of the subfont image. The <tt><font size=+1>info</font></tt> array has <tt><font size=+1>n+1</font></tt> elements, |
| one each for characters 0 |
| to <tt><font size=+1>n−1</font></tt> plus an additional entry so the size of the last character |
| can be calculated. Thus the width, <i>w</i>, of the <tt><font size=+1>Image</font></tt> associated |
| with a <tt><font size=+1>Subfont s</font></tt> is <tt><font size=+1>s−>info[s−>n].x</font></tt>. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| A <tt><font size=+1>Font</font></tt> consists of an overall height and ascent and a collection |
| of subfonts together with the ranges of runes (see <a href="../man7/utf.html"><i>utf</i>(7)</a>) they |
| represent. Fonts are described by the following structures.<br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| <tt><font size=+1>typedef<br> |
| struct Cachefont {<br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| Rune min; /* value of 0th char in subfont */<br> |
| Rune max; /* value+1 of last char in subfont */<br> |
| int offset; /* posn in subfont of char at min */<br> |
| char *name; /* stored in font */<br> |
| char *subfontname;/* to access subfont */<br> |
| |
| </table> |
| } Cachefont;<br> |
| typedef<br> |
| struct Cacheinfo {<br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| ushort x; /* left edge of bits */<br> |
| uchar width; /* width of baseline */<br> |
| schar left; /* offset of baseline */<br> |
| Rune value; /* of char at this slot in cache */<br> |
| ushort age;<br> |
| |
| </table> |
| } Cacheinfo;<br> |
| typedef<br> |
| struct Cachesubf {<br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| ulong age; /* for replacement */<br> |
| Cachefont *cf; /* font info that owns us */<br> |
| Subfont *f; /* attached subfont */<br> |
| |
| </table> |
| } Cachesubf;<br> |
| typedef<br> |
| struct Font {<br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| char *name;<br> |
| Display *display;<br> |
| short height; /* max ht of image;interline space*/<br> |
| short ascent; /* top of image to baseline */<br> |
| short width; /* widest so far; used in caching */<br> |
| short nsub; /* number of subfonts */<br> |
| ulong age; /* increasing counter; for LRU */<br> |
| int ncache; /* size of cache */<br> |
| int nsubf; /* size of subfont list */<br> |
| Cacheinfo *cache;<br> |
| Cachesubf *subf;<br> |
| Cachefont **sub; /* as read from file */<br> |
| Image *cacheimage;<br> |
| |
| </table> |
| } Font;<br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| |
| </table> |
| The <tt><font size=+1>height</font></tt> and <tt><font size=+1>ascent</font></tt> fields of Font are described in <a href="../man3/graphics.html"><i>graphics</i>(3)</a>. |
| <tt><font size=+1>Sub</font></tt> contains <tt><font size=+1>nsub</font></tt> pointers to <tt><font size=+1>Cachefonts</font></tt>. A <tt><font size=+1>Cachefont</font></tt> connects |
| runes <tt><font size=+1>min</font></tt> through <tt><font size=+1>max</font></tt>, inclusive, to the subfont with file name |
| <tt><font size=+1>name</font></tt>; it corresponds to a line of the file describing the font. |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| The characters are taken from the subfont starting at character |
| number <tt><font size=+1>offset</font></tt> (usually zero) in the subfont, permitting selection |
| of parts of subfonts. Thus the image for rune <i>r</i> is found in position |
| <i>r</i><tt><font size=+1>−min+offset</font></tt> of the subfont. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| For each font, the library, with support from the graphics server, |
| maintains a cache of subfonts and a cache of recently used character |
| images. The <tt><font size=+1>subf</font></tt> and <tt><font size=+1>cache</font></tt> fields are used by the library to maintain |
| these caches. The <tt><font size=+1>width</font></tt> of a font is the maximum of the horizontal |
| extents of the characters in the cache. |
| <i>String</i> draws a string by loading the cache and emitting a sequence |
| of cache indices to draw. <i>Cachechars</i> guarantees the images for |
| the characters pointed to by <i>*s</i> or <i>*r</i> (one of these must be nil |
| in each call) are in the cache of <i>f</i>. It calls <i>loadchar</i> to put |
| missing characters into the cache. <i>Cachechars</i> translates the |
| character string into a set of cache indices which it loads into |
| the array <i>c</i>, up to a maximum of <i>n</i> indices or the length of the |
| string. <i>Cachechars</i> returns in <i>c</i> the number of cache indices emitted, |
| updates <i>*s</i> to point to the next character to be processed, and |
| sets <i>*widp</i> to the total width of the characters processed. |
| <i>Cachechars</i> may return before the end of the string if it cannot |
| proceed without destroying active data in the caches. If it needs |
| to load a new subfont, it will fill <tt><font size=+1>*sfname</font></tt> with the name of the |
| subfont it needs and return –1. It can return zero if it is unable |
| to make progress because it cannot resize the caches. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| <i>Loadchar</i> loads a character image into the character cache. Then |
| it tells the graphics server to copy the character into position |
| <i>h</i> in the character cache. If the current font <tt><font size=+1>width</font></tt> is smaller |
| than the horizontal extent of the character being loaded, <i>loadfont</i> |
| clears the cache and resets it to accept characters with the |
| bigger width, unless <i>noclr</i> is set, in which case it just returns |
| –1. If the character does not exist in the font at all, <i>loadfont</i> |
| returns 0; if it is unable to load the character without destroying |
| cached information, it returns –1, updating <tt><font size=+1>*sfname</font></tt> as described |
| above. It returns 1 to indicate success. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| The <tt><font size=+1>age</font></tt> fields record when subfonts and characters have been used. |
| The font <tt><font size=+1>age</font></tt> is increased every time the font is used (<i>agefont</i> |
| does this). A character or subfont <tt><font size=+1>age</font></tt> is set to the font age |
| at each use. Thus, characters or subfonts with small ages are |
| the best candidates for replacement when the cache is full. |
| |
| </table> |
| <p><font size=+1><b>SOURCE </b></font><br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| <tt><font size=+1>/usr/local/plan9/src/libdraw<br> |
| </font></tt> |
| </table> |
| <p><font size=+1><b>SEE ALSO </b></font><br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| <a href="../man3/graphics.html"><i>graphics</i>(3)</a>, <a href="../man3/allocimage.html"><i>allocimage</i>(3)</a>, <a href="../man3/draw.html"><i>draw</i>(3)</a>, <a href="../man3/subfont.html"><i>subfont</i>(3)</a>, <a href="../man7/image.html"><i>image</i>(7)</a>, <a href="../man7/font.html"><i>font</i>(7)</a><br> |
| |
| </table> |
| <p><font size=+1><b>DIAGNOSTICS </b></font><br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| All of the functions use the graphics error function (see <a href="../man3/graphics.html"><i>graphics</i>(3)</a>).<br> |
| |
| </table> |
| |
| <td width=20> |
| <tr height=20><td> |
| </table> |
| <!-- TRAILER --> |
| <table border=0 cellpadding=0 cellspacing=0 width=100%> |
| <tr height=15><td width=10><td><td width=10> |
| <tr><td><td> |
| <center> |
| <a href="../../"><img src="../../dist/spaceglenda100.png" alt="Space Glenda" border=1></a> |
| </center> |
| </table> |
| <!-- TRAILER --> |
| </body></html> |
