.TH GRAPHICS 2.SH NAMEDisplay, 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.Bint initdraw(void (*errfun)(Display*, char*), char *font,.B char *label).PP.Bint geninitdraw(char *devdir, void(*errfun)(Display*, char*),.PP.B char *font, char *label, char *mousedir, char *windir,.B int ref).PP.Bint newwindow(char *str).PP.Bvoid drawerror(Display *d, char *msg).PP.BDisplay* initdisplay(char *devdir, char *win, void(*errfun)(Display*, char*)).PP.Bvoid closedisplay(Display *d).PP.BSubfont* getdefont(Display *d).PP.Bint flushimage(Display *d, int vis).PP.Buchar* bufimage(Display *d, int n).PP.Bvoid lockdisplay(Display *d).PP.Bvoid unlockdisplay(Display *d).PP.Bint getwindow(Display *d, int ref).PP.Bint gengetwindow(Display *d, char *winname,.br.B Image **ip, Screen **sp, int ref).PP.BFont* openfont(Display *d, char *name).PP.BFont* buildfont(Display *d, char *desc, char *name).PP.Bvoid freefont(Font *f).PP.Bint Pfmt(Fmt*).PP.Bint Rfmt(Fmt*).PP.Bulong strtochan(char *s).PP.Bchar* chantostr(char *s, ulong chan).PP.Bint chantodepth(ulong chan).PP.Bextern Display *display.PP.Bextern Image *screen.PP.Bextern Screen *_screen.PP.Bextern Font *font.fi.SH DESCRIPTIONA.B Displaystructure 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 +10ntypedefstruct Display{ ... void (*error)(Display*, char*); ... Image *black; Image *white; Image *opaque; Image *transparent; Image *image; Font *defaultfont; Subfont *defaultsubfont; ...};.EE.PPA.B Pointis a location in an Image(see below and.IR draw (2)),such as the display, and is defined as:.IP.EX.ta 6ntypedefstruct Point { int x; int y;} Point;.EE.PPThe coordinate system has.I xincreasing to the right and.I yincreasing down..PPA.B Rectangleis a rectangular area in an image..IP.EX.ta 6ntypedefstruct Rectangle { Point min; /* upper left */ Point max; /* lower right */} Rectangle;.EE.PPBy definition,.BR min.x ≤ max.xand.BR min.y ≤ max.y .By convention, the right (maximum.IR x )and bottom (maximum.IR y )edges areexcluded from the represented rectangle, so abutting rectangles have nopoints in common.Thus,.B maxcontains the coordinates of the first point beyond the rectangle..PPThe.B Imagedata structure is defined in.IR draw (2)..PPA.B Fontis 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 Fontand.B Subfontstructures 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 ofthe lowest character (and hence, the interline spacing).See.IR cachechars (2)for more details..PP.I Buildfontparses 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 Openfontdoes the same, but reads the descriptionfrom the named file..I Freefontfrees a font.The convention for naming font files is:.IP.B /lib/font/bit/\fIname\fP/\fIrange\fP.\fIsize\fP.font.PD.PPwhere.I sizeis approximately the height in pixels of the lower case letters(without ascenders or descenders)..I Rangegives some indication of which characters will be available: for example.BR ascii ,.BR latin1 ,.BR euro ,or.BR unicode ..B Euroincludes most European languages, punctuation marks, the International PhoneticAlphabet, etc., but no Oriental languages..B Unicodeincludes every character for which appropriate-sized images exist on the system..PPA.I Cursoris defined:.IP.EX.ta 6n +\w'Point 'utypedef structCursor { Point offset; uchar clr[2*16]; uchar set[2*16];} Cursor;.EE.PPThe arrays are arranged in rows, two bytes per row, left toright in big-endian order to give 16 rowsof 16 bits each.A cursor is displayed on the screen by adding.B offsetto the current mouse position, using.B clras a mask to draw white at the pixels where.B clris one, and then drawing black at the pixels where.B setis one..I Setcursorand.I moveto(see.IR mouse (2))and.I esetcursorand.I emoveto(see.IR event (2))change the cursor image and its location on the screen..PPThe routine.I initdrawconnects to the display; it returns \-1 if it fails and sets the error string..I Initdrawsets up the global variables.B display(the.B Displaystructure representing the connection),.B screen(an.B Imagerepresenting 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 initdrawinclude a.IR label ,which is written to.B /dev/labelif non-nilso that it can be used to identify the window when hidden (see.IR rio (1)).The font is created by reading the named.I fontfile. If.B fontis null,.I initdrawreads the file named in the environment variable.BR $font ;if.B $fontis not set, it imports the default (usually minimal)font from the operating system.The global.I fontwill be set to point to the resulting.B Fontstructure.The.I errfunargument is a.I graphics error functionto call in the event of a fatal error in the library; it must never return.Its arguments are thedisplay pointer and an error string.If.I errfunis nil, the library provides a default, called.IR drawerror .Another effect of.I initdrawis that it installs.IR print (2)formats.I Pfmtand.I Rfmtas.L %Pand.L %Rfor printing.B Pointsand.BR Rectangles ..PPThe.I geninitdrawfunction provides a less automated way to establish a connection, for programsthat wish to connect to multiple displays..I Devdiris the name of the directory containing the device files for the display(if nil, default.BR /dev );.IR errfun ,.IR font ,and.I labelare as in.IR initdraw ;.I mousedirand.I windirare the directories holding the.B mouseand.B winnamefiles; and.I refspecifies the refresh function to be used to create the window, if running under.IR rio (1)(see.IR window (2))..PPThe function.I newwindowmay be called before.I initdrawor.IR geninitdrawto cause the program to occupy a newly created window rather than take over the one inwhich it is running when it starts.The.I strargument, if non-null, is concatenated to the string \f5\&"new\ "\fPthat 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 window100 pixels high..PP.I Initdisplayis 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 winnames the directory, default.BR /dev ,in which the files associated with the window reside..I Closedisplaydisconnects the display and frees the associated data structures..I Getdefontbuilds a.B Subfontstructure from in-core data describing a default subfont.None of these routines is needed by most programs, since.I initdrawcalls them as needed..PPThe 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->lockingto.BR 1 ,to notify the library to use a locking protocol for its own accesses,and call.I lockdisplayand.I unlockdisplayaround any calls to the graphics library that will cause messages to be sent to the display device..I Initdrawand.I geninitdrawinitialize the display to the locked state..PP.I Getwindowreturns a pointer to the window associated with the application; it is calledautomatically by.I initdrawto establish the.B screenpointer but must be called after each resizing of the window to restorethe library's connection to the window.If.B riois not running, it returns.BR display->image ;otherwise it negotiates with.B rioby looking in.B /dev/winnameto 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 Refnonebecause.B rioprovides backing store for the window..PP.I Getwindowoverwrites the global variables.BR screen ,a pointer to the.B Imagedefining the window (or the overall display, if no window system is running); and.BR _screen ,a pointer to the.B Screenrepresenting the root of the window's hierarchy. (See.IR window (2).The overloading of the.B screenword is an unfortunate historical accident.).I Getwindowarranges that.B screenpoint to the portion of the window inside the border;sophisticated clients may use.B _screento make further subwindows.Programs desiring multiple independent windowsmay use the mechanisms of.IR rio (4)to create more windows (usually by a fresh mount of the window sytemin a directory other than.BR /dev ),then use.I gengetwindowto connect to them.Lines 1–500 of 642. Load more
.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*), .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 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 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 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.