diff options
Diffstat (limited to 'man/man3/graphics.3')
| -rw-r--r-- | man/man3/graphics.3 | 651 |
1 files changed, 651 insertions, 0 deletions
diff --git a/man/man3/graphics.3 b/man/man3/graphics.3 new file mode 100644 index 00000000..f7f6a5a9 --- /dev/null +++ b/man/man3/graphics.3 @@ -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 . |