Subversion Repositories planix.SVN

.TH SUBFONT 2

.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)).