638 lines
12 KiB
Text
638 lines
12 KiB
Text
.TH GRAPHICS 2
|
|
.SH NAME
|
|
Display, Point, Rectangle, Cursor, initdraw, geninitdraw, newwindow, 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*),
|
|
.PP
|
|
.B
|
|
char *font, char *label, char *windir,
|
|
.B
|
|
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
|
|
file; 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 are 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 system
|
|
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,
|
|
0
|
|
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 .
|