--- ray/src/rt/driver.h	1989/02/02 10:41:13	1.1
+++ ray/src/rt/driver.h	1990/03/08 10:10:44	1.7
@@ -15,6 +15,8 @@ struct driver {				/* driver functions */
 	int  (*getcur)();			/* get cursor position */
 	int  (*comout)();			/* command line output */
 	int  (*comin)();			/* command line input */
+	int  (*flush)();			/* flush output */
+	double  pixaspect;			/* pixel aspect ratio */
 	int  xsiz, ysiz;			/* device size */
 	int  inpready;				/* input ready on device */
 };
@@ -23,49 +25,51 @@ extern int  stderr_v();			/* error vectors */
 extern int  (*wrnvec)(), (*errvec)(), (*cmdvec)();
 
 extern struct driver  *comm_init();	/* stream interface */
+					/* magic numbers for verification */
+#define COM_SENDM		0x6f37
+#define COM_RECVM		0x51da
 					/* stream commands */
 #define COM_CLEAR		0
 #define COM_PAINTR		1
 #define COM_GETCUR		2
 #define COM_COMOUT		3
 #define COM_COMIN		4
-#define NREQUESTS		5	/* number of valid requests */
+#define COM_FLUSH		5
+#define NREQUESTS		6	/* number of valid requests */
 
-struct device {				/* interactive device */
+extern struct device {			/* interactive device */
 	char  *name;				/* device name */
 	char  *descrip;				/* description */
 	struct driver  *(*init)();		/* initialize device */
-};
+}  devtable[];				/* supported devices */
 
-extern struct device  devtable[];	/* supported devices */
-
 #define  MB1		('\n')		/* mouse button 1 */
 #define  MB2		('\r')		/* mouse button 2 */
 #define  MB3		(' ')		/* mouse button 3 */
 #define  ABORT		('C'-'@')	/* abort key */
 
-#define  MAXRES		4000		/* preposterous display resolution */
-
 /*
  *  struct driver *
- *  dname_init(name)
- *  char  *name;
+ *  dname_init(name, id)
+ *  char  *name, *id;
  *  {
  *	Initialize device and return pointer to driver
  *	functions.  Returns NULL if an error occurred.
- *	The name string is used to identify the client.
+ *	The name string identifies the driver,
+ *	and the id string identifies the client.
  *	A device can be open by at most one client.
  *	Be verbose in error reports; call stderr_v().
- *	If device has its own error output, set errvec.
+ *	If device has its own error output, set errvec,
+ *	cmdvec and wrnvec.
  *  }
  *  (*dev->close)()
  *  {
- *	Close the device.  Reset errvec to stderr_v.
+ *	Close the device.  Reset error vectors.
  *  }
  *  (*dev->clear)(xres, yres)
  *  int  xres, yres;
  *  {
- *	Clear the device for xres by yres output.  This call must
+ *	Clear the device for xres by yres output.  This call will
  *	be made prior to any output.
  *  }
  *  (*dev->paintr)(col, xmin, ymin, xmax, ymax)
@@ -73,7 +77,7 @@ extern struct device  devtable[];	/* supported devices
  *  int  xmin, ymin, xmax, ymax;
  *  {
  *	Paint a half-open rectangle from (xmin,ymin) to (xmax,ymax)
- *	with the color col.  Can call repaint() if necessary.
+ *	with the color col.
  *  }
  *  (*dev->getcur)(xp, yp)
  *  int  *xp, *yp;
@@ -90,19 +94,30 @@ extern struct device  devtable[];	/* supported devices
  *	string ends with '\n', the message is considered complete,
  *	and the next call can erase it.
  *  }
- *  (*dev->comin)(in)
- *  char  *in;
+ *  (*dev->comin)(in, prompt)
+ *  char  *in, *prompt;
  *  {
- *	Read an edited input string from the command line.  If
- *	an unrecognized control character is entered, terminate
- *	input and return the string with only that character.
- *	The input string should not contain a newline ('\n').
- *	Must work in consort with comout.
+ *	Print a prompt then read an edited input command line
+ *	assuming the in buffer is big enough.  Unless prompt is NULL,
+ *	the driver may substitute its own rview command.  This is
+ *	the most reliable way to repaint areas of the screen.
+ *	If the user enters an unrecognized control character,
+ *	terminate input and return the string with only that character.
+ *	The input string should not contain a newline.  The routines in
+ *	editline.c may be useful.  Comin must work in consort with comout.
  *  }
+ *  (*dev->flush)()
+ *  {
+ *	Flush output to the display.  This is guaranteed to be called
+ *	frequently enough to keep the display up to date.
+ *	This is an ideal time to check for device input.
+ *	This function can be NULL for devices that don't need it.
+ *  }
  *  xsiz, ysiz
  *	The maximum allowable x and y dimensions.  If any
  *	size is allowable, these should be set to MAXRES.
  *  inpready
- *	This variable should be positive
- *	when characters are ready on the input.
+ *	This variable should be made positive asynchronously
+ *	when characters are ready on the input.  (Often easiest
+ *	to check for input during calls to paintr.)
  */