diff options
Diffstat (limited to 'man/man3/cachechars.3')
| -rw-r--r-- | man/man3/cachechars.3 | 313 |
1 files changed, 313 insertions, 0 deletions
diff --git a/man/man3/cachechars.3 b/man/man3/cachechars.3 new file mode 100644 index 00000000..8c18046d --- /dev/null +++ b/man/man3/cachechars.3 @@ -0,0 +1,313 @@ +.TH CACHECHARS 3 +.SH NAME +cachechars, agefont, loadchar, Subfont, Fontchar, Font \- font utilities +.SH SYNOPSIS +.B #include <u.h> +.br +.B #include <draw.h> +.br +.B #include <draw.h> +.PP +.ta \w'\fLCacheinfo 'u +.PP +.B +int cachechars(Font *f, char **s, Rune **r, ushort *c, int max, +.PP +.B + int *widp, char **sfname) +.PP +.B +int loadchar(Font *f, Rune r, Cacheinfo *c, int h, +.PP +.B + int noclr, char **sfname) +.PP +.B +void agefont(Font *f) +.SH DESCRIPTION +A +.I Font +may contain too many characters to hold in memory +simultaneously. +The graphics library and draw device (see +.IR draw (3)) +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 +and its associated +.I font +variable, +.IR openfont , +.IR stringwidth , +.IR string , +and +.I freefont +are sufficient for most purposes. +The routines described below are used internally by the graphics library +to maintain the font cache. +.PP +A +.B Subfont +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. +.IP +.EX +.ta 6n +\w'Fontchar 'u +\w'bottom; 'u +typedef +struct 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; + +typedef +struct 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 +.PP +The image fills the rectangle +\fL(0, 0, \fIw\fP, height)\fR, +where +.I w +is the sum of the horizontal extents (of non-zero pixels) +for all characters. +The pixels to be displayed for character +.I c +are in the rectangle +\fL(\fIi\fP->x, \fIi\fP->top, (\fIi\fP+1)->x, \%\fIi\fP->bottom)\fR +where +.I i +is +.B +&subfont->info[\fIc\fP]\fR. +When a character is displayed at +.B Point +.B p +in 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 ascent +rows down from the top of the subfont image. +The +.L info +array has +.B n+1 +elements, one each for characters 0 to +.BR n-1 +plus an additional entry so the size of the last character +can be calculated. +Thus the width, +.IR w , +of the +.B Image +associated with a +.B Subfont +.B s +is +.BR s->info[s->n].x . +.PP +A +.B Font +consists of an overall height and ascent +and 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; 'u +typedef +struct 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; + +typedef +struct 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; + +typedef +struct Cachesubf { + ulong age; /* for replacement */ + Cachefont *cf; /* font info that owns us */ + Subfont *f; /* attached subfont */ +} Cachesubf; + +typedef +struct 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 +.PP +The +.LR height +and +.LR ascent +fields of Font are described in +.IR graphics (2). +.L Sub +contains +.L nsub +pointers to +.BR Cachefonts . +A +.B Cachefont +connects runes +.L min +through +.LR max , +inclusive, to the subfont +with file name +.LR name ; +it corresponds to a line of the file describing the font. +.PP +The characters +are taken from the subfont starting at character number +.L offset +(usually zero) in the subfont, permitting selection of parts of subfonts. +Thus +the image for rune +.I r +is found in position +.IB r -min+offset +of the subfont. +.PP +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 +.B subf +and +.B cache +fields are used by the library to maintain these caches. +The +.L width +of a font is the maximum of the horizontal extents of the characters +in the cache. +.I String +draws a string by loading the cache and emitting a sequence of +cache indices to draw. +.I Cachechars +guarantees the images for the characters pointed to by +.I *s +or +.I *r +(one of these must be nil in each call) +are in the cache of +.IR f . +It calls +.I loadchar +to put missing characters into the cache. +.I Cachechars +translates the character string into a set of cache indices +which it loads into the array +.IR c , +up to a maximum of +.I n +indices or the length of the string. +.I Cachechars +returns in +.I c +the number of cache indices emitted, +updates +.I *s +to point to the next character to be processed, and sets +.I *widp +to the total width of the characters processed. +.I Cachechars +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 +.B *sfname +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. +.PP +.I Loadchar +loads a character image into the character cache. +Then it tells the graphics server to copy the character +into position +.I h +in the character cache. +If the current font +.L width +is smaller than the horizontal extent of the character being loaded, +.I loadfont +clears the cache and resets it to +accept characters with the bigger width, unless +.I noclr +is set, in which case it just returns \-1. +If the character does not exist in the font at all, +.I loadfont +returns 0; if it is unable to load the character +without destroying cached information, it returns \-1, +updating +.B *sfname +as described above. +It returns 1 to indicate success. +.PP +The +.L age +fields record when +subfonts and characters have been used. +The font +.L age +is increased every time the font is used +.RI ( agefont +does this). +A character or subfont +.L age +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. +.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 DIAGNOSTICS +All of the functions use the graphics error function (see +.IR graphics (2)). |