Subversion Repositories planix.SVN

.TH GRAPHICS 2

.SH NAME

Display, Point, Rectangle, Cursor, initdraw, geninitdraw, drawerror, initdisplay, closedisplay, getdefont, getwindow, gengetwindow, flushimage, bufimage, lockdisplay, unlockdisplay, openfont, buildfont, freefont, Pfmt, Rfmt, strtochan, chantostr, chantodepth \- interactive graphics

.SH SYNOPSIS

.nf

.ft L

#include <u.h>

#include <libc.h>

#include <draw.h>

#include <cursor.h>

.ft P

.PP

.ta \w'\fLFont* 'u

.B

int	initdraw(void (*errfun)(Display*, char*), char *font,

.B

	   char *label)

.PP

.B

int	geninitdraw(char *devdir, void(*errfun)(Display*, char*),

.B

	   char *font, char *label, char *windir, int ref)

.PP

.B

int	newwindow(char *str)

.PP

.B

void	drawerror(Display *d, char *msg)

.PP

.B

Display*	initdisplay(char *devdir, char *win, void(*errfun)(Display*, char*))

.PP

.B

void	closedisplay(Display *d)

.PP

.B

Subfont*	getdefont(Display *d)

.PP

.B

int	flushimage(Display *d, int vis)

.PP

.B

uchar*	bufimage(Display *d, int n)

.PP

.B

void	lockdisplay(Display *d)

.PP

.B

void	unlockdisplay(Display *d)

.PP

.B

int	getwindow(Display *d, int ref)

.PP

.B

int	gengetwindow(Display *d, char *winname,

.br

.B

	   Image **ip, Screen **sp, int ref)

.PP

.B

Font*	openfont(Display *d, char *name)

.PP

.B

Font*	buildfont(Display *d, char *desc, char *name)

.PP

.B

void	freefont(Font *f)

.PP

.B

int	Pfmt(Fmt*)

.PP

.B

int	Rfmt(Fmt*)

.PP

.B

ulong	strtochan(char *s)

.PP

.B

char*	chantostr(char *s, ulong chan)

.PP

.B

int	chantodepth(ulong chan)

.PP

.B

extern Display *display

.PP

.B

extern Image   *screen

.PP

.B

extern Screen   *_screen

.PP

.B

extern Font    *font

.fi

.SH DESCRIPTION

A

.B Display

structure represents a connection to the graphics device,

.IR draw (3),

holding all graphics resources associated with the connection,

including in particular raster image data in use by the client program.

The structure is defined (in part) as:

.IP

.EX

.ta 6n +10n

typedef

struct Display

{

	...

	void	(*error)(Display*, char*);

	...

	Image	*black;

	Image	*white;

	Image	*opaque;

	Image	*transparent;

	Image	*image;

	Font		*defaultfont;

	Subfont	*defaultsubfont;

	...

};

.EE

.PP

A

.B Point

is a location in an Image

(see below and

.IR draw (2)),

such as the display, and is defined as:

.IP

.EX

.ta 6n

typedef

struct Point {

	int x;

	int y;

} Point;

.EE

.PP

The coordinate system has

.I x

increasing to the right and

.I y

increasing down.

.PP

A

.B Rectangle

is a rectangular area in an image.

.IP

.EX

.ta 6n

typedef

struct Rectangle {

	Point min;      /* upper left */

	Point max;      /* lower right */

} Rectangle;

.EE

.PP

By definition,

.BR min.x ≤ max.x

and

.BR min.y ≤ max.y .

By convention, the right (maximum

.IR x )

and bottom (maximum

.IR y )

edges are

excluded from the represented rectangle, so abutting rectangles have no

points in common.

Thus,

.B max

contains the coordinates of the first point beyond the rectangle.

.PP

The

.B Image

data structure is defined in

.IR draw (2).

.PP

A

.B Font

is a set of character images, indexed by runes (see

.IR utf (6)).

The images are organized into

.BR Subfonts ,

each containing the images for a small, contiguous set of runes.

The detailed format of these data structures,

which are described in detail in

.IR cachechars (2),

is immaterial for most applications.

.B Font

and

.B Subfont

structures contain two interrelated fields:

.LR ascent ,

the distance from the top of the highest character

(actually the top of the image holding all the characters)

to the baseline,

and

.LR height ,

the distance from the top of the highest character to the bottom of

the lowest character (and hence, the interline spacing).

See

.IR cachechars (2)

for more details.

.PP

.I Buildfont

parses the font description in the buffer

.BR desc ,

returning a 

.B Font*

pointer that can be used by

.B string

(see

.IR draw (2))

to draw characters from the font.

.I Openfont

does the same, but reads the description

from the named file.

.I Freefont

frees a font.

The convention for naming font files is:

.IP

.B /lib/font/bit/\fIname\fP/\fIrange\fP.\fIsize\fP.font

.PD

.PP

where

.I size

is approximately the height in pixels of the lower case letters

(without ascenders or descenders).

.I Range

gives some indication of which characters will be available: for example

.BR ascii ,

.BR latin1 ,

.BR euro ,

or

.BR unicode .

.B Euro

includes most European languages, punctuation marks, the International Phonetic

Alphabet, etc., but no Oriental languages.

.B Unicode

includes every character for which appropriate-sized images exist on the system.

.PP

A

.I Cursor

is defined:

.IP

.EX

.ta 6n +\w'Point 'u

typedef struct

Cursor {

	Point	offset;

	uchar	clr[2*16];

	uchar	set[2*16];

} Cursor;

.EE

.PP

The arrays are arranged in rows, two bytes per row, left to

right in big-endian order to give 16 rows

of 16 bits each.

A cursor is displayed on the screen by adding

.B offset

to the current mouse position, using

.B clr

as a mask to draw white at the pixels where

.B clr

is one, and then drawing black at the pixels where

.B set

is one.

.I Setcursor

and

.I moveto

(see

.IR mouse (2))

and

.I esetcursor

and

.I emoveto

(see

.IR event (2))

change the cursor image and its location on the screen.

.PP

The routine

.I initdraw

connects to the display; it returns \-1 if it fails and sets the error string.

.I Initdraw

sets up the global variables

.B display

(the

.B Display

structure representing the connection),

.B screen

(an

.B Image

representing the display memory itself or, if

.IR rio (1)

is running, the client's window),

and

.B font

(the default font for text).

The arguments to

.I initdraw

include a

.IR label ,

which is written to

.B /dev/label

if non-nil

so that it can be used to identify the window when hidden (see

.IR rio (1)).

The font is created by reading the named

.I font

file.  If

.B font

is null,

.I initdraw

reads the file named in the environment variable

.BR $font ;

if

.B $font

is not set, it imports the default (usually minimal)

font from the operating system.

The global

.I font

will be set to point to the resulting

.B Font

structure.

The

.I errfun

argument is a

.I graphics error function

to call in the event of a fatal error in the library; it must never return.

Its arguments are the

display pointer and an error string.

If

.I errfun

is nil, the library provides a default, called

.IR drawerror .

Another effect of

.I initdraw

is that it installs

.IR print (2)

formats

.I Pfmt

and

.I Rfmt

as

.L %P

and

.L %R

for printing

.B Points

and

.BR Rectangles .

.PP

The

.I geninitdraw

function provides a less automated way to establish a connection, for programs

that wish to connect to multiple displays.

.I Devdir

is the name of the directory containing the device files for the display

(if nil, default

.BR /dev );

.IR errfun ,

.IR font ,

and

.I label

are as in

.IR initdraw ;

.I windir

is the directory holding the

.B winname

files; and

.I ref

specifies the refresh function to be used to create the window, if running under

.IR rio (1)

(see

.IR window (2)).

.PP

The function

.I newwindow

may be called before

.I initdraw

or

.IR geninitdraw

to cause the program to occupy a newly created window rather than take over the one in

which it is running when it starts.

The

.I str

argument, if non-null, is concatenated to the string \f5\&"new\ "\fP

that is used to create the window (see

.IR rio (4)).

For example,

.B newwindow("-hide -dy 100")

will cause the program to run in a newly created, hidden window

100 pixels high.

.PP

.I Initdisplay

is part of

.IR geninitdraw ;

it sets up the display structures but does not allocate any fonts or call

.IR getwindow .

The arguments are similar to those of

.IR initdraw ;

.I win

names the directory, default

.BR /dev ,

in which the files associated with the window reside.

.I Closedisplay

disconnects the display and frees the associated data structures.

.I Getdefont

builds a

.B Subfont

structure from in-core data describing a default subfont.

None of these routines is needed by most programs, since

.I initdraw

calls them as needed.

.PP

The data structures associated with the display must be protected in a multi-process program,

because they assume only one process will be using them at a time.

Multi-process programs should set

.B display->locking

to

.BR 1 ,

to notify the library to use a locking protocol for its own accesses,

and call

.I lockdisplay

and

.I unlockdisplay

around any calls to the graphics library that will cause messages to be sent to the display device.

.I Initdraw

and

.I geninitdraw

initialize the display to the locked state.

.PP

.I Getwindow

returns a pointer to the window associated with the application; it is called

automatically by

.I initdraw

to establish the

.B screen

pointer but must be called after each resizing of the window to restore

the library's connection to the window.

If

.B rio

is not running, it returns

.BR display->image ;

otherwise it negotiates with

.B rio

by looking in

.B /dev/winname

to find the name of the window and opening it using

.B namedimage

(see

.IR allocimage (2)).

The resulting window will be created using the refresh method

.I ref

(see

.IR window (2));

this should almost always be

.B Refnone

because

.B rio

provides backing store for the window.

.PP

.I Getwindow

overwrites the global variables

.BR screen ,

a pointer to the

.B Image

defining the window (or the overall display, if no window system is running); and

.BR _screen ,

a pointer to the

.B Screen

representing the root of the window's hierarchy. (See

.IR window (2).

The overloading of the

.B screen

word is an unfortunate historical accident.)

.I Getwindow

arranges that

.B screen

point to the portion of the window inside the border;

sophisticated clients may use

.B _screen

to make further subwindows.

Programs desiring multiple independent windows

may use the mechanisms of

.IR rio (4)

to create more windows (usually by a fresh mount of the window sytem

in a directory other than

.BR /dev ),

then use

.I gengetwindow

to connect to them.

.IR Gengetwindow 's

extra arguments are the full path of the window's

.B winname

file and pointers to be overwritten with the values of the `global'

.B Image

and

.B Screen

variables for the new window.

.PP

The graphics functions described in

.IR draw (2),

.IR allocimage (2),

.IR cachechars (2),

and

.IR subfont (2)

are implemented by writing commands to files under

.B /dev/draw

(see

.IR draw (3));

the writes are buffered, so the functions may not take effect immediately.

.I Flushimage

flushes the buffer, doing all pending graphics operations.

If

.I vis

is non-zero, any changes are also copied from the `soft screen' (if any) in the

driver to the visible frame buffer.

The various allocation routines in the library flush automatically, as does the event

package (see

.IR event (2));

most programs do not need to call

.IR flushimage .

It returns \-1 on error.

.PP

.I Bufimage

is used to allocate space for

.I n

bytes in the display buffer.

It is used by all the graphics routines to send messages to the display.

.PP

The functions

.I strtochan

and

.I chantostr

convert between the channel descriptor strings

used by

.IR image (6)

and the internal 

.B ulong

representation 

used by the graphics protocol

(see

.IR draw (3)'s

.B b

message).

.B Chantostr

writes at most nine bytes into the buffer pointed at by 

.I s

and returns 

.I s

on success,

on failure.

.B Chantodepth

returns the number of bits per pixel used by the

format specified by

.IR chan .

Both

.B chantodepth

and

.B strtochan

return 0 when presented

with bad input.

.SH EXAMPLES

To reconnect to the window after a resize event,

.IP

.EX

if(getwindow(display, Refnone) < 0)

	sysfatal("resize failed: %r");

.EE

.PP

To create and set up a new

.IR rio (1)

window,

.IP

.EX

Image *screen2;

Screen *_screen2;

srvwsys = getenv("wsys");

if(srvwsys == nil)

	sysfatal("can't find $wsys: %r");

rfork(RFNAMEG); /* keep mount of rio private */

fd = open(srvwsys, ORDWR);

if(fd < 0)

	sysfatal("can't open $wsys: %r");

/* mount creates window; see \f2rio\fP(4) */

if(mount(fd, -1, "/tmp", MREPL, "new -dx 300-dy 200") < 0)

	sysfatal("can't mount new window: %r");

if(gengetwindow(display, "/tmp/winname",

   &screen2, &_screen2, Refnone) < 0)

	sysfatal("resize failed: %r");

/* now open /tmp/cons, /tmp/mouse */

\&...

.EE

.SH FILES

.BR /lib/font/bit "    directory of fonts

.SH SOURCE

.B /sys/src/libdraw

.SH "SEE ALSO"

.IR rio (1),

.IR addpt (2),

.IR allocimage (2),

.IR cachechars (2),

.IR subfont (2),

.IR draw (2),

.IR event (2),

.IR frame (2),

.IR print (2),

.IR window (2),

.IR draw (3),

.IR rio (4),

.IR image (6),

.IR font (6)

.SH DIAGNOSTICS

An error function may call

.IR errstr (2)

for further diagnostics.

.SH BUGS

The names

.B clr

and

.B set

in the 

.B Cursor

structure are reminders of an archaic color map

and might be more appropriately called

.B white

and

.BR black .