font(6) [plan9 man page]

FONT(6) 							   Games Manual 							   FONT(6)

NAME

       font, subfont - external format for fonts and subfonts

SYNOPSIS

       #include <libg.h>

DESCRIPTION

       Fonts and subfonts are described in cachechars(2).

       External  fonts	are  described by a plain text file that can be read using rdfontfile.	The format of the file is a header followed by any
       number of subfont range specifications.	The header contains two numbers: the height and the ascent, both in pixels.   The  height  is  the
       inter-line  spacing  and  the ascent is the distance from the top of the line to the baseline.  These numbers are chosen to display consis-
       tently all the subfonts of the font.  A subfont range specification contains two or three numbers and a file name.   The  numbers  are  the
       inclusive  range  of  characters  covered by the subfont, with an optional starting position within the subfont, and the file name names an
       external file suitable for rdsubfontfile.  The minimum number of a covered range is mapped to  the  specified  starting	position  (default
       zero) of the corresponding subfont.  If the subfont file name does not begin with a slash, it is taken relative to the directory containing
       the font file.  Each field must be followed by some white space.  Each numeric field may be C-format decimal, octal, or hexadecimal.

       External subfonts are represented in a more rigid format that can be read and written using rdsubfontfile and  wrsubfontfile  (see  subfal-
       loc(2)).  The format for subfont files is: a bitmap containing character images, followed by a subfont header, followed by character infor-
       mation.	The bitmap has the format for external bitmap files described in bitmap(6).  The subfont header has 3 decimal strings: n,  height,
       and  ascent.   Each  number  is right-justified and blank padded in 11 characters, followed by a blank.	The character info consists of n+1
       6-byte entries, each giving the Fontchar x (2 bytes, low order byte first), top, bottom, left, and width.  The x field of the last Fontchar
       is used to calculate the bitmap width of the previous character; the other fields in the last Fontchar are irrelevant.

       Note  that  the	convention  of	using the character with value zero (NUL) to represent characters of zero width (see bitblt(2)) means that
       fonts should have, as their zeroth character, one with non-zero width.

FILES

       /lib/font/bit/*
	      font directories

SEE ALSO

       graphics(2), bitblt(2), cachechars(2), subfalloc(2)

																	   FONT(6)

SUBFALLOC(2)							System Calls Manual						      SUBFALLOC(2)

NAME

       subfalloc, subffree, rdsubfontfile, wrsubfontfile, mkfont - subfont manipulation

SYNOPSIS

       #include <u.h>
       #include <libc.h>
       #include <libg.h>

       Subfont* subfalloc(int n, int height, int ascent,
		Fontchar *info, Bitmap *b, ulong q0, ulong q1)

       void	subffree(Subfont *f)

       Subfont* rdsubfontfile(int fd, Bitmap *b)

       void	wrsubfontfile(int fd, Subfont *f)

       Font*	mkfont(Subfont *f, Rune min);

DESCRIPTION

       Subfonts are the components of fonts that hold the character images.  A font comprises an array of subfonts; see cachechars(2).	A new Sub-
       font is allocated and initialized with subfalloc.  See cachechars(2) for the meaning of n, height, ascent, and info, and the arrangement of
       characters in bitmap b.	The fields of the returned Subfont structure are set to the passed arguments, and the id field is set to the iden-
       tifying number used by /dev/bitblt (see bit(3)).  After a successful subfalloc, b is attached to the subfont  and  is  unavailable  to  the
       application; it should not be used.  Subfalloc returns 0 on failure.

       The q0 and q1 arguments are used as tags in a cache of subfonts (see below).  If all ones, they disable caching.

       Subffree  frees	a  subfont  and  all  its  associated structure including the associated bitmap.  Since subffree calls free on f->info, if
       f->info was not allocated by malloc(2) it should be zeroed before calling subffree.

       A number of subfonts are kept in external files.  The convention for naming subfont files is:

	      /lib/font/bit/name/class.size.ldepth

       where size is approximately the height in pixels of the lower case letters (without ascenders or descenders).  If there is only one version
       of the subfont, the .ldepth extension is elided.  Class describes the range of runes encoded in the subfont: ascii, latin1, greek, etc.

       The  format of a subfont file is described in font(6)).	Briefly, it contains a bitmap with all the characters in it, followed by a subfont
       header, followed by character information.  Rdsubfontfile reads a subfont from the file descriptor fd.  If b is zero,  rdsubfontfile  reads
       the  bitmap  as	well as the character information from the file and allows the resulting subfont and bitmap to be cached in the server for
       sharing with other applications.  The first thing such an rdsubfontfile call does is check to see if the subfont can be recovered  directly
       from  the  server:  if the qid (see intro(5)) of the file pointed to by fd matches q0 and q1 of a cache entry, the subfont is read from the
       server instead of from fd.  This is the normal use of rdsubfontfile.

       Unusual applications such as font editors may choose to have uncached (hence unshared) subfonts or to associate arbitrary bitmaps with  the
       character  data.  If the b argument to rdsubfontfile is non-null, rdsubfontfile reads only the character information from fd (which must be
       positioned after the bitmap in the file) and the resulting subfont is uncached.	Nonetheless, rdsubfontfile  calls  subfalloc  with  b  and
       hence b is unusable afterwards; make a copy first if necessary.	Rdsubfontfile returns 0 on error.

       Wrsubfontfile  writes  on fd the part of a subfont file that comes after the bitmap.  Because the bitmap of a cached subfont is unavailable
       to the application, without extraordinary measures only uncached subfonts may be written whole to files.

       Mkfont takes as argument a Subfont s and returns a pointer to a Font that maps the character images in s into the Runes min to min+s->n-1.

FILES

       /lib/font/bit
	      bitmap font file tree

SOURCE

       /sys/src/libg

SEE ALSO

       graphics(2), balloc(2), bitblt(2), cachechars(2), bitmap(6), font(6)

DIAGNOSTICS

       All of the functions use the graphics error function (see graphics(2)).

BUGS

       Subfonts can contain no more than about 1300 characters.

																      SUBFALLOC(2)