diff options
Diffstat (limited to 'man/man3/subfont.3')
| -rw-r--r-- | man/man3/subfont.3 | 235 |
1 files changed, 235 insertions, 0 deletions
diff --git a/man/man3/subfont.3 b/man/man3/subfont.3 new file mode 100644 index 00000000..3802333b --- /dev/null +++ b/man/man3/subfont.3 @@ -0,0 +1,235 @@ +.TH SUBFONT 3 +.SH NAME +allocsubfont, freesubfont, installsubfont, lookupsubfont, uninstallsubfont, subfontname, readsubfont, readsubfonti, writesubfont, stringsubfont, strsubfontwidth, mkfont \- subfont manipulation +.SH SYNOPSIS +.B #include <u.h> +.br +.B #include <libc.h> +.br +.B #include <draw.h> +.PP +.ta \w'\fLSubfont* 'u +.B +Subfont* allocsubfont(char *name, int n, int height, int ascent, +.br +.B + Fontchar *info, Image *i) +.PP +.B +void freesubfont(Subfont *f) +.PP +.B +void installsubfont(char *name, Subfont *f) +.PP +.B +Subfont* lookupsubfont(Subfont *f) +.PP +.B +void uninstallsubfont(Subfont *f) +.PP +.B +Subfont* readsubfont(Display *d, char *name, int fd, int dolock) +.PP +.B +Subfont* readsubfonti(Display *d, char *name, int fd, Image *im, +.br +.B + int dolock) +.PP +.B +int writesubfont(int fd, Subfont *f) +.PP +.B +Point stringsubfont(Image *dst, Point p, Image *src, +.br +.B + Subfont *f, char *str) +.PP +.B +Point strsubfontwidth(Subfont *f, char *s) +.PP +.B +Font* mkfont(Subfont *f, Rune min) +.SH DESCRIPTION +Subfonts are the components of fonts that hold the character images. +A font comprises an array of subfonts; see +.IR cachechars (2). +A new +.B Subfont +is allocated and initialized with +.IR allocsubfont . +See +.IR cachechars (2) +for the meaning of +.IR n , +.IR height , +.IR ascent , +and +.IR info , +and the arrangement of characters in +image +.IR i . +The +.I name +is used to identify the subfont in the subfont cache; see the descriptions +.I lookupsubfont +and +.IR installsubfont +.RI ( q.v. ). +The appropriate fields of the returned +.B Subfont +structure are set to +the passed arguments, and the image is registered as a subfont +with the graphics device +.IR draw (3). +.I Allocsubfont +returns 0 on failure. +.PP +.I Freesubfont +frees a subfont and all its associated structure including the +associated image. +Since +.I freesbufont +calls +.I free +on +.BR f->info , +if +.B f->info +was not allocated by +.IR malloc (2) +it should be zeroed before calling +.IR subffree . +.PP +A number of subfonts are kept in external files. +The convention for naming subfont files is: +.IP +.B /lib/font/bit/\fIname\fP/\fIclass\fP.\fIsize\fP.\fIdepth +.PD +.PP +where +.I 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 +.BI \&. depth +extension is elided. +.I Class +describes the range of runes encoded in the subfont: +.BR ascii , +.BR latin1 , +.BR greek , +etc. +.PP +Subfonts are cached within the program, so a subfont shared between fonts will be loaded only once. +.I Installsubfont +stores subfont +.I f +under the given +.IR name , +typically the file name from which it was read. +.I Uninstallsubfont +removes the subfont from the cache. +Finally, +.I lookupsubfont +searches for a subfont with the given +.I name +in the cache and returns it, or nil if no such subfont exists. +.PP +.I Subfontname +is used to locate subfonts given their names within the fonts. +The default version constructs a name given the +.IR cfname , +its name within the font, +.IR fname , +the name of the font, and the maximum depth suitable for this subfont. +This interface allows a partially specified name within a font to be resolved +at run-time to the name of a file holding a suitable subfont. +Although it is principally a routine internal to the library, +.I subfontname +may be substituted by the application to provide a less file-oriented subfont naming scheme. +.PP +The format of a subfont file is described in +.IR font (6). +Briefly, it contains a image with all the characters in it, +followed by a subfont header, followed by character information. +.I Readsubfont +reads a subfont from the file descriptor +.IR fd . +The +.I name +is used to identify the font in the cache. +The +.I dolock +argument specifies whether the routine should synchronize +use of the +.I Display +with other processes; for single-threaded applications it may +always be zero. +.I Readsubfonti +does the same for a subfont whose associated image is already in memory; it is passed as the +argument +.IR im . +In other words, +.I readsubfonti +reads only the header and character information from the file descriptor. +.PP +.I Writesubfont +writes on +.I fd +the part of a subfont file that comes after the image. It should be preceded by +a call to +.IR writeimage +(see +.IR allocimage (2)). +.PP +.I Stringsubfont +is analogous to +.B string +(see +.IR draw (2)) +for subfonts. Rather than use the underlying font caching primitives, +it calls +.B draw +for each character. +It is intended for stand-alone environments such as operating system kernels. +.I Strsubfontwidth +returns the width of the string +.I s +in +as it would appear if drawn with +.I stringsubfont +in +.B Subfont +.BR f . +.PP +.I Mkfont +takes as argument a +.B Subfont +.I s +and returns a pointer to a +.B Font +that maps the character images in +.I s +into the +.B Runes +.I min +to +.IB min + s ->n-1\f1. +.SH FILES +.TF /lib/font/bit +.TP +.B /lib/font/bit +bitmap font file tree +.SH SOURCE +.B /sys/src/libdraw +.SH SEE ALSO +.IR graphics (2), +.IR allocimage (2), +.IR draw (2), +.IR cachechars (2), +.IR image (6), +.IR font (6) +.SH DIAGNOSTICS +All of the functions use the graphics error function (see +.IR graphics (2)). |