.TH CACHECHARS 2.SH NAMEcachechars, agefont, loadchar, Subfont, Fontchar, Font  \- font utilities.SH SYNOPSIS.B #include <u.h>.br.B #include <libc.h>.br.B #include <draw.h>.PP.ta \w'\fLCacheinfo 'u.PP.Bint  cachechars(Font *f, char **s, Rune **r, ushort *c, int max,.PP.B	   int *widp, char **sfname).PP.Bint  loadchar(Font *f, Rune r, Cacheinfo *c, int h,.PP.B	   int noclr, char **sfname).PP.Bvoid agefont(Font *f).SH DESCRIPTIONA.I Fontmay contain too many characters to hold in memorysimultaneously.The graphics library and draw device (see.IR draw (3))cooperate to solve this problem by maintaining a cache of recently usedcharacter images.The details of this cooperation need not be known by most programs:.I initdrawand its associated.I fontvariable,.IR openfont ,.IR stringwidth ,.IR string ,and.I freefontare sufficient for most purposes.The routines described below are used internally by the graphics libraryto maintain the font cache..PPA.B Subfontis a set of images for a contiguous range of characters, stored as a singleimagewith the charactersplaced side-by-side on a common baseline.It is described by the following data structures..IP.EX.ta 6n +\w'Fontchar 'u +\w'bottom;   'utypedefstruct Fontchar {	int	x;	/* left edge of bits */	uchar	top;	/* first non-zero scan-line */	uchar	bottom;	/* last non-zero scan-line */	char	left;	/* offset of baseline */	uchar	width;	/* width of baseline */} Fontchar; typedefstruct Subfont {	char	*name;	short	n;	/* number of chars in subfont */	uchar	height;	/* height of image */	char	ascent;	/* top of image to baseline */	Fontchar	*info;	/* n+1 Fontchars */	Image	*bits;	/* of font */} Subfont;.EE.PPThe image fills the rectangle\fL(0, 0, \fIw\fP, height)\fR,where.I wis the sum of the horizontal extents (of non-zero pixels)for all characters.The pixels to be displayed for character.I care in the rectangle\fL(\fIi\fP->x, \fIi\fP->top, (\fIi\fP+1)->x, \%\fIi\fP->bottom)\fRwhere.I iis.B&subfont->info[\fIc\fP]\fR.When a character is displayed at.B Point.B pin an image,the character rectangle is placed at.BI (p.x+ i ->left,.B p.y)and the next character of the string is displayed at.BI (p.x+ i ->width,.BR p.y) .The baseline of the characters is.L ascentrows down from the top of the subfont image.The.L infoarray has.B n+1elements, one each for characters 0 to.BR n-1plus an additional entry so the size of the last charactercan be calculated.Thus the width,.IR w ,of the.B Imageassociated with a.B Subfont.B sis.BR s->info[s->n].x ..PPA.B Fontconsists of an overall height and ascentand a collection of subfonts together with the ranges of runes (see.IR utf (6))they represent.Fonts are described by the following structures..IP.EX.ta 6n +\w'Cacheinfo 'u +\w'height;   'utypedefstruct Cachefont {	Rune	min;	/* value of 0th char in subfont */	Rune	max;	/* value+1 of last char in subfont */	int	offset;	/* posn in subfont of char at min */	char	*name;	/* stored in font */	char	*subfontname;	/* to access subfont */} Cachefont; typedefstruct Cacheinfo {	ushort	x;	/* left edge of bits */	uchar	width;	/* width of baseline */	schar	left;	/* offset of baseline */	Rune	value;	/* of char at this slot in cache */	ushort	age;} Cacheinfo; typedefstruct Cachesubf {	ulong	age;	/* for replacement */	Cachefont	*cf;	/* font info that owns us */	Subfont	*f;	/* attached subfont */} Cachesubf; typedefstruct Font {	char	*name;	Display	*display;	short	height;	/* max ht of image;interline space*/	short	ascent;	/* top of image to baseline */	short	width;	/* widest so far; used in caching */	short	nsub;	/* number of subfonts */	ulong	age;	/* increasing counter; for LRU */	int	ncache;	/* size of cache */	int	nsubf;	/* size of subfont list */	Cacheinfo	*cache;	Cachesubf	*subf;	Cachefont	**sub;	/* as read from file */	Image	*cacheimage;} Font;.EE.PPThe.LR heightand.LR ascentfields of Font are described in.IR graphics (2)..L Subcontains.L nsubpointers to.BR Cachefonts .A.B Cachefontconnects runes.L minthrough.LR max ,inclusive, to the subfontwith file name.LR name ;it corresponds to a line of the file describing the font..PPThe charactersare taken from the subfont starting at character number.L offset(usually zero) in the subfont, permitting selection of parts of subfonts.Thusthe image for rune.I ris found in position.IB r -min+offsetof the subfont..PPFor each font, the library, with support from thegraphics server,maintains a cache ofsubfonts and a cache of recently usedcharacter images.The.B subfand.B cachefields are used by the library to maintain these caches.The.L widthof a font is the maximum of the horizontal extents of the charactersin the cache..I Stringdraws a string by loading the cache and emitting a sequence ofcache indices to draw..I Cachecharsguarantees the images for the characters pointed to by.I *sor.I *r(one of these must be nil in each call)are in the cache of.IR f .It calls.I loadcharto put missing characters into the cache..I Cachecharstranslates the character string into a set of cache indiceswhich it loads into the array.IR c ,up to a maximum of.I nindices or the length of the string..I Cachecharsreturns in.I cthe number of cache indices emitted,updates.I *sto point to the next character to be processed, and sets.I *widpto the total width of the characters processed..I Cachecharsmay return before the end of the string if it cannotproceed without destroying active data in the caches.If it needs to load a new subfont, it will fill.B *sfnamewith the name of the subfont it needs and return \-1.It can return zero if it is unable to make progress becauseit cannot resize the caches..PP.I Loadcharloads a character image into the character cache.Then it tells the graphics server to copy the character into position.I hin the character cache.If the current font.L widthis smaller than the horizontal extent of the character being loaded,.I loadfontclears the cache and resets it toaccept characters with the bigger width, unless.I noclris set, in which case it just returns \-1.If the character does not exist in the font at all,.I loadfontreturns 0; if it is unable to load the characterwithout destroying cached information, it returns \-1,updating.B *sfnameas described above.It returns 1 to indicate success..PPThe.L agefields record whensubfonts and characters have been used.The font.L ageis increased every time the font is used.RI ( agefontdoes this).A character or subfont.L ageis set to the font age at each use.Thus, characters or subfonts with small ages are the best candidatesfor replacement when the cache is full..SH SOURCE.B /sys/src/libdraw.SH SEE ALSO.IR graphics (2),.IR allocimage (2),.IR draw (2),.IR subfont (2),.IR image (6),.IR font (6).SH DIAGNOSTICSAll of the functions use the graphics error function (see.IR graphics (2)).