<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 &ndash; 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 &lt;u.h&gt;<br>
    #include &lt;libc.h&gt;<br>
    #include &lt;draw.h&gt; 
    <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 &nbsp;&nbsp;&nbsp;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 &nbsp;&nbsp;&nbsp;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 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;x; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* left edge of bits */<br>
            uchar &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;top; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* first non&#8722;zero scan&#8722;line */<br>
            uchar &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;bottom; &nbsp;&nbsp;&nbsp;&nbsp;/* last non&#8722;zero scan&#8722;line */<br>
            char &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;left; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* offset of baseline */<br>
            uchar &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;width; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* 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 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*name;<br>
            short &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;n; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* number of chars in subfont */<br>
            uchar &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;height; &nbsp;&nbsp;&nbsp;&nbsp;/* height of image */<br>
            char &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;ascent; &nbsp;&nbsp;&nbsp;&nbsp;/* top of image to baseline */<br>
            Fontchar *info; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* n+1 Fontchars */<br>
            Image &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*bits; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* 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>&#8722;&gt;x,</font></tt> <i>i</i><tt><font size=+1>&#8722;&gt;top, (</font></tt><i>i</i><tt><font size=+1>+1)&#8722;&gt;x,</font></tt> <i>i</i><tt><font size=+1>&#8722;&gt;bottom)</font></tt> where <i>i</i> is <tt><font size=+1>&amp;subfont&#8722;&gt;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>&#8722;&gt;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>&#8722;&gt;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&#8722;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&#8722;&gt;info[s&#8722;&gt;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 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;min; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* value of 0th char in subfont */<br>
            Rune &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;max; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* value+1 of last char in subfont */<br>
            int &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;offset; &nbsp;&nbsp;&nbsp;&nbsp;/* posn in subfont of char at min */<br>
            char &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*name; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* stored in font */<br>
            char &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*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 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;x; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* left edge of bits */<br>
            uchar &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;width; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* width of baseline */<br>
            schar &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;left; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* offset of baseline */<br>
            Rune &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;value; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* of char at this slot in cache */<br>
            ushort &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;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 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;age; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* for replacement */<br>
            Cachefont *cf; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* font info that owns us */<br>
            Subfont &nbsp;&nbsp;&nbsp;&nbsp;*f; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* 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 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*name;<br>
            Display &nbsp;&nbsp;&nbsp;&nbsp;*display;<br>
            short &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;height; &nbsp;&nbsp;&nbsp;&nbsp;/* max ht of image;interline space*/<br>
            short &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;ascent; &nbsp;&nbsp;&nbsp;&nbsp;/* top of image to baseline */<br>
            short &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;width; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* widest so far; used in caching */<br>
            short &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;nsub; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* number of subfonts */<br>
            ulong &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;age; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* increasing counter; for LRU */<br>
            int &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;ncache; &nbsp;&nbsp;&nbsp;&nbsp;/* size of cache */<br>
            int &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;nsubf; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* size of subfont list */<br>
            Cacheinfo *cache;<br>
            Cachesubf *subf;<br>
            Cachefont **sub; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* as read from file */<br>
            Image &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*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>&#8722;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 &ndash;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
    &ndash;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 &ndash;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>