diff options
| author | rsc <devnull@localhost> | 2005-01-14 03:45:44 +0000 |
|---|---|---|
| committer | rsc <devnull@localhost> | 2005-01-14 03:45:44 +0000 |
| commit | 78e51a8c6678b6e3dff3d619aa786669f531f4bc (patch) | |
| tree | 015e00fde4fc837fd31b705e18d17dc913829388 /man/man3/cachechars.html | |
| parent | 2634795b5f0053bc0ff08e5d7bbc0eda8efea061 (diff) | |
| download | plan9port-78e51a8c6678b6e3dff3d619aa786669f531f4bc.tar.gz plan9port-78e51a8c6678b6e3dff3d619aa786669f531f4bc.tar.bz2 plan9port-78e51a8c6678b6e3dff3d619aa786669f531f4bc.zip | |
checkpoint
Diffstat (limited to 'man/man3/cachechars.html')
| -rw-r--r-- | man/man3/cachechars.html | 292 |
1 files changed, 292 insertions, 0 deletions
diff --git a/man/man3/cachechars.html b/man/man3/cachechars.html new file mode 100644 index 00000000..382b5e7e --- /dev/null +++ b/man/man3/cachechars.html @@ -0,0 +1,292 @@ +<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> |