Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
GRAPHICS(3)		   Library Functions Manual		   GRAPHICS(3)

NAME
       Display,	 Point,	 Rectangle,  Cursor, initdraw, geninitdraw, drawerror,
       initdisplay, closedisplay, getwindow, gengetwindow, flushimage,	bufim-
       age,  lockdisplay,  unlockdisplay,  cursorswitch,  cursorset, openfont,
       buildfont, freefont, Pfmt, Rfmt,	strtochan,  chantostr,	chantodepth  -
       interactive graphics

SYNOPSIS
       #include	<u.h>
       #include	<libc.h>
       #include	<draw.h>
       #include	<cursor.h>

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

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

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

       int   newwindow(char *str)

       void  drawerror(Display *d, char	*msg)

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

       void  closedisplay(Display *d)

       int   flushimage(Display	*d, int	vis)

       int   bufimage(Display *d, int n)

       int   lockdisplay(Display *d)

       int   unlockdisplay(Display *d)

       int   getwindow(Display *d, int ref)

       int   gengetwindow(Display *d, char *winname,
		Image **ip, Screen **sp, int ref)

       int   scalesize(Display *d, int n)

       void  cursorswitch(Cursor *curs)

       void  cursorset(Point p)

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

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

       void  freefont(Font *f)

       int   Pfmt(Fmt*)

       int   Rfmt(Fmt*)

       ulong strtochan(char *s)

       char* chantostr(char *s,	ulong chan)

       int   chantodepth(ulong chan)

       extern Display *display

       extern Image   *screen

       extern Screen   *_screen

       extern Font    *font

DESCRIPTION
       A  Display  structure  represents  a connection to the graphics device,
       holding all graphics resources associated with the connection,  includ-
       ing  in particular raster image data in use by the client program.  The
       structure is defined (in	part) as:

	      typedef
	      struct Display
	      {
		    ...
		    void      (*error)(Display*, char*);
		    ...
		    Image     *black;
		    Image     *white;
		    Image     *opaque;
		    Image     *transparent;
		    Image     *image;
		    Font      *defaultfont;
		    Subfont   *defaultsubfont;
		    ...
	      };

       A Point is a location in	an Image (see below and	such as	 the  display,
       and is defined as:

	      typedef
	      struct Point {
		    int	x;
		    int	y;
	      }	Point;

       The  coordinate	system	has x increasing to the	right and y increasing
       down.

       A Rectangle is a	rectangular area in an image.

	      typedef
	      struct Rectangle {
		    Point min;	    /* upper left */
		    Point max;	    /* lower right */
	      }	Rectangle;

       By definition, min.xaxmax.x and min.yaxmax.y.  By convention, the right
       (maximum	 x)  and bottom	(maximum y) edges are excluded from the	repre-
       sented rectangle, so abutting rectangles	 have  no  points  in  common.
       Thus,  max  contains the	coordinates of the first point beyond the rec-
       tangle.

       The Image data structure	is defined in

       A Font is a set of character images, indexed by runes (see  The	images
       are  organized  into  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 is immaterial	for most applications.
       Font and	Subfont	structures contain two interrelated fields:  the  dis-
       tance  from  the	 top of	the highest character (actually	the top	of the
       image holding all the characters) to the	 baseline,  and	 the  distance
       from the	top of the highest character to	the bottom of the lowest char-
       acter (and hence, the interline spacing).  See for more details.

       Buildfont parses	the font description in	the buffer desc,  returning  a
       Font*  pointer  that can	be used	by string (see to draw characters from
       the font.  Openfont does	the same, but reads the	description  from  the
       named  font.  Freefont frees a font.  In	contrast to Plan 9, font names
       in Plan 9 from User Space are a small language describing  the  desired
       font.  See for details.

       A Cursor	is defined:

	      typedef struct
	      Cursor {
		    Point offset;
		    uchar clr[2*16];
		    uchar set[2*16];
	      }	Cursor;

       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  dis-
       played  on  the	screen by adding offset	to the current mouse position,
       using clr as a mask to draw white at the	pixels where clr is  one,  and
       then drawing black at the pixels	where set is one.

       The routine initdraw connects to	the display; it	returns	-1 if it fails
       and sets	the error string.  Initdraw sets up the	global variables  dis-
       play  (the  Display  structure representing the connection), screen (an
       Image representing the display memory itself or,	 if  is	 running,  the
       client's	 window), and font (the	default	font for text).	 The arguments
       to initdraw include a label, which is written to	/dev/label if  non-nil
       so that it can be used to identify the window when hidden (see The font
       is created by reading the named font file.  If font is  null,  initdraw
       reads the file named in the environment variable	$font; if $font	is not
       set, it imports the default (usually minimal) font from	the  operating
       system.	(See for a full	discussion of font syntaxes.)  The global font
       will be set to point to the resulting Font structure.  The errfun argu-
       ment is a 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 errfun	is nil,	the library provides a
       default,	called drawerror.  Another effect of initdraw is that  it  in-
       stalls formats Pfmt and Rfmt as and for printing	Points and Rectangles.

       The  geninitdraw	 function provides a less automated way	to establish a
       connection, for programs	that wish to  connect  to  multiple  displays.
       Devdir is the name of the directory containing the device files for the
       display (if nil,	default	/dev); errfun, font, and label are as in init-
       draw;  mousedir	and  windir  are the directories holding the mouse and
       winname files; and ref specifies	the refresh function  to  be  used  to
       create the window, if running under (see

       Initdisplay  is	part of	geninitdraw; it	sets up	the display structures
       but does	not allocate any fonts or call getwindow.  The	arguments  are
       similar to those	of initdraw; win names the directory, default /dev, in
       which the files associated with the window reside.   Closedisplay  dis-
       connects	the display and	frees the associated data structures.  Neither
       of these	routines is needed by most programs, since initdraw calls them
       as needed.

       The  data structures associated with the	display	must be	protected in a
       multi-process program, because they assume only one process will	be us-
       ing them	at a time.  Multi-process programs should set display->locking
       to 1, to	notify the library to use a locking protocol for its  own  ac-
       cesses,	and call lockdisplay and unlockdisplay around any calls	to the
       graphics	library	that will cause	messages to be sent to the display de-
       vice.   Initdraw	 and  geninitdraw initialize the display to the	locked
       state.

       Getwindow returns a pointer to the window associated with the  applica-
       tion;  it  is  called automatically by initdraw to establish the	screen
       pointer but must	be called after	each resizing of the window to restore
       the  library's connection to the	window.	 If rio	is not running,	it re-
       turns display->image; otherwise it negotiates with rio  by  looking  in
       /dev/winname to find the	name of	the window and opening it using	named-
       image (see The resulting	window	will  be  created  using  the  refresh
       method  ref  (see this should almost always be Refnone because rio pro-
       vides backing store for the window.

       Getwindow overwrites the	global variables screen, a pointer to the  Im-
       age defining the	window (or the overall display,	if no window system is
       running); and _screen, a	pointer	to the Screen representing the root of
       the  window's  hierarchy. (See The overloading of the screen word is an
       unfortunate historical accident.)  Getwindow arranges that screen point
       to  the	portion	of the window inside the border; sophisticated clients
       may use _screen to make further	subwindows.   If  getwindow  is	 being
       called  due  to a resizing of the window, the resize may	be accompanied
       by a change in screen pixel density (DPI), in which case	the  value  of
       the  Display's  dpi  field and any open Font's height and ascent	fields
       may be updated during the call to getwindow.  Programs  should  discard
       any cached information about display or font sizes.  Gengetwindow's ex-
       tra arguments are the full path of the window's winname file and	point-
       ers  to be overwritten with the values of the `global' Image and	Screen
       variables for the new window.

       Historically, Plan 9 graphics programs have  used  fixed-size  graphics
       features	 that  assume  a narrow	range of display densities, around 100
       dpi: pixels (or dots) per inch.	The new	 field	display->dpi  contains
       the  display's  actual  density	if  known,  or	else DefaultDPI	(100).
       Scalesize scales	the fixed pixel	count  n  by  display->dpi/DefaultDPI,
       rounding	appropriately.

       The  mouse cursor is always displayed.  The initial cursor is an	arrow.
       Cursorswitch causes the argument	cursor to  be  displayed  instead.   A
       zero  argument  causes  a  switch  back to the arrow cursor.  Cursorset
       moves the mouse cursor to position 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 cursorset is a no-op.

       The graphics functions described	in and are implemented by writing com-
       mands  to  files	 under	/dev/draw (see the writes are buffered,	so the
       functions may not take effect immediately.  Flushimage flushes the buf-
       fer,  doing  all	 pending graphics operations.  If 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  most  pro-
       grams do	not need to call flushimage.  It returns -1 on error.

       Bufimage	 is  used to allocate space for	n bytes	in the display buffer.
       It is used by all the graphics routines to send messages	 to  the  dis-
       play.

       The  functions  strtochan and chantostr convert between the channel de-
       scriptor	strings	used by	and the	internal ulong representation used  by
       the  graphics  protocol (see b message).	 Chantostr writes at most nine
       bytes into the buffer pointed at	by s and returns s on  success,	 0  on
       failure.	  Chantodepth returns the number of bits per pixel used	by the
       format specified	by chan.  Both chantodepth and strtochan return	0 when
       presented with bad input.

EXAMPLES
       To reconnect to the window after	a resize event,

	      if(getwindow(display, Refnone) < 0)
		    sysfatal("resize failed: %r");

       To create and set up a new window,

	      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 rio(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	*/
	      ...

FILES
       /font/bit    directory of fonts

SOURCE
       /src/libdraw

SEE ALSO
DIAGNOSTICS
       An error	function may call for further diagnostics.

BUGS
       The  names  clr and set in the Cursor structure are reminders of	an ar-
       chaic color map and might be more appropriately called white and	black.

       These manual  pages  contain  many  references  to  the	now-fictitious
       /dev/draw.

								   GRAPHICS(3)

NAME | SYNOPSIS | DESCRIPTION | EXAMPLES | FILES | SOURCE | SEE ALSO | DIAGNOSTICS | BUGS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=graphics&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help