Lots of man pages.
This commit is contained in:
rsc
parent
08df2a433e
commit
cfa37a7b11
152 changed files with 25407 additions and 148 deletions
651
man/man3/graphics.3
Normal file
651
man/man3/graphics.3
Normal file
|
|
@ -0,0 +1,651 @@
|
|||
.TH GRAPHICS 3
|
||||
.SH NAME
|
||||
Display, Point, Rectangle, Cursor, initdraw, geninitdraw, drawerror, initdisplay, closedisplay, getdefont, getwindow, gengetwindow, flushimage, bufimage, lockdisplay, unlockdisplay, cursorswitch, cursorset, openfont, buildfont, freefont, Pfmt, Rfmt, strtochan, chantostr, chantodepth \- interactive graphics
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
.PP
|
||||
.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 *mousedir, 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
|
||||
Font* getdefont(Display *d)
|
||||
.PP
|
||||
.B
|
||||
int flushimage(Display *d, int vis)
|
||||
.PP
|
||||
.B
|
||||
int bufimage(Display *d, int n)
|
||||
.PP
|
||||
.B
|
||||
int lockdisplay(Display *d)
|
||||
.PP
|
||||
.B
|
||||
int 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
|
||||
void cursorswitch(Cursor *curs)
|
||||
.PP
|
||||
.B
|
||||
void cursorset(Point p)
|
||||
.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.
|
||||
.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 mousedir
|
||||
and
|
||||
.I windir
|
||||
are the directories holding the
|
||||
.B mouse
|
||||
and
|
||||
.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 Font
|
||||
structure from in-core data describing a default font.
|
||||
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 mouse cursor is always displayed.
|
||||
The initial cursor is an arrow.
|
||||
.I Cursorswitch
|
||||
causes the argument cursor to be displayed instead.
|
||||
A zero argument causes a switch back to the arrow cursor.
|
||||
.I Cursorset
|
||||
moves the mouse cursor to position
|
||||
.IR p ,
|
||||
provided (if in a window) that the requesting program is
|
||||
executing in the current window and the mouse is within
|
||||
the window boundaries; otherwise
|
||||
.I cursorset
|
||||
is a no-op.
|
||||
.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 .
|
||||
Loading…
Add table
Add a link
Reference in a new issue