--- name: "cachechars" section: "3g" platform: "linux" package: "libxg-dev" version: "4.3-14" release: "Debian 3.0 (Woody)" platforms: ["linux"] url: "https://new.carta.tech/cachechars" --- # cachechars(3g) font utilities ## NAME cachechars, Subfont, Cachesubf, Fontchar, Font - font utilities ## SYNOPSIS ``` #include #include ``` **int cachechars(Font \*f, char \*\*s, XChar2b \*c, int n, int \*widp, ushort \*fp)** ## DESCRIPTION A *Font* may contain too many characters to hold in memory simultaneously. The graphics library and X server 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: *xtbinit* and its associated *\*p9font* X resource, *rdfontfile,* *charwidth,* *string,* and *ffree* are sufficient for most purposes. The routines described below are used internally by the graphics library to maintain the font cache. A **Subfont** may be considered to be a set of images for a contiguous range of characters, stored as a single bitmap with the characters placed side-by-side on a common baseline. It is described by the following data structures. - ``` typedef struct Fontchar { ushort cwidth; /* width of glyph */ uchar top; /* first non-zero scan-line */ uchar bottom; /* last non-zero scan-line */ char left; /* offset of baseline */ uchar width; /* advance to next char's origin */ } Fontchar; typedef struct Subfont { short minrow; /* first character row in font (for X subfonts) */ short mincol; /* first character col in font (for X subfonts) */ short minchar; /* first char code in font (for X subfonts) */ short maxchar; /* last char code in font (for X subfonts) */ short width; /* number of chars in row (for X subfonts) */ short n; /* number of chars in subfont */ unsigned char height; /* height of bitmap */ char ascent; /* top of bitmap to baseline */ Fontchar *info; /* n+1 character descriptors */ int id; /* of font */ } Subfont; ``` The actual bitmap for each character is stored on the server but the metrics associated with character *c* are cached locally in **subfont-\>info\[*c*\].** When a character is displayed at **Point** **p** in a bitmap, the character rectangle is placed at **(p.x+***i***-\>left,** **p.y)** and the next character of the string is displayed at **(p.x+***i***-\>width+(***i***+1)-\>left,** **p.y)**. The baseline of the characters is rows down from the top of the subfont bitmap. Each **Fontchar** has two widths associated with it: *width* is the width of the rectangular bitmap to contain the character; *cwidth* is the true width of the character, that is, the number of pixels between the leftmost and rightmost pixels of the character glyph. A **Font** consists of an overall height and ascent and a collection of subfonts together with the ranges of runes (see [*utf*(5g)](/utf/5g.md)) they represent. Fonts are described by the following structures. - ``` typedef struct Cachesubf { Rune min; /* rune value of 0th char in subfont */ Rune max; /* rune value+1 of last char in subfont */ char *name; Subfont *f; /* attached subfont */ } Cachefont; typedef struct Font { char *name; uchar height; /* max height of bitmap, interline spacing */ char ascent; /* top of bitmap to baseline */ char width; /* widest so far; used in caching only */ char ldepth; /* of images */ short id; /* of font */ short nsubf; /* number of subfonts */ Cachesubf *subf; /* as read from file */ } Font; ``` The and fields of Font are described in [*graphics*(3g)](/graphics/3g.md). contains pointers to **Cachesubfs**. A **Cachesubf** connects runes through inclusive, to the subfont it corresponds to a line of the file describing the font. The image for rune *r* is found in position *r*−min+minchar of the subfont. For each font, the library, with support from the graphics server, maintains a list of subfonts. The of a font is the maximum of the horizontal extents of the characters in the cache. \[ is unused in the X implementation of libg.\] *String* draws a string by calling *cachechars* and emitting a sequence of X font indices to draw. *Cachechars* calculates the subfont/index pairs for the characters pointed to by *\*s*. It calls *getsubfont* to fetch subfonts which are not yet in the subfont list of *f*. *Cachechars* translates the character string into a set of subfont/index pairs. It loads the character indices into the array *c*, up to a maximum of *n* indices or the length of the string. It also loads the corresponding element of *fp* with the subfont index for each character. *Cachechars* returns in *c* the number of subfont indices emitted, updates *\*s* to point to the next character to be processed, and sets *\*widp* to the total width of the characters processed. *Cachechars* may return before the end of the string if it cannot proceed. It can return zero if it is unable to make progress because a character code does not covered by any subfont range. ## SEE ALSO [*graphics*(3g)](/graphics/3g.md), [*balloc*(3g)](/balloc/3g.md), [*bitblt*(3g)](/bitblt/3g.md), [*font*(5g)](/font/5g.md). ## DIAGNOSTICS All of the functions use the graphics error function (see [*graphics*(3g)](/graphics/3g.md)).