10564b1175
groff 1.23.0 added .MR to its -man macro package. The NEWS file states
that the inclusion of the macro "was prompted by its introduction to
Plan 9 from User Space's troff in August 2020." From d32deab it seems
that the name for Plan 9 from User Space's implementation was suggested
by groff maintainer G. Brandon Robinson.
Not sure if the intention was to make these definitions compatible, but
it would be nice if they were.
Currently, Plan 9 from User Space's .MR expects its second argument to
be parenthesized. groff's .MR does not. This results in extra
parentheses appearing in manual references when viewing Plan 9 from User
Space's manual pages on a system using groff.
236 lines
5.0 KiB
Groff
236 lines
5.0 KiB
Groff
.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
|
|
.MR cachechars 3 .
|
|
A new
|
|
.B Subfont
|
|
is allocated and initialized with
|
|
.IR allocsubfont .
|
|
See
|
|
.MR cachechars 3
|
|
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
|
|
.MR 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
|
|
.MR malloc 3
|
|
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 \*9/font/\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
|
|
.MR font 7 .
|
|
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
|
|
.MR allocimage 3 ).
|
|
.PP
|
|
.I Stringsubfont
|
|
is analogous to
|
|
.B string
|
|
(see
|
|
.MR draw 3 )
|
|
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 \*9/font
|
|
.TP
|
|
.B \*9/font
|
|
bitmap font file tree
|
|
.SH SOURCE
|
|
.B \*9/src/libdraw
|
|
.SH SEE ALSO
|
|
.MR graphics 3 ,
|
|
.MR allocimage 3 ,
|
|
.MR draw 3 ,
|
|
.MR cachechars 3 ,
|
|
.MR image 7 ,
|
|
.MR font 7
|
|
.SH DIAGNOSTICS
|
|
All of the functions use the graphics error function (see
|
|
.MR graphics 3 ).
|