LIB2648(3X)LIB2648(3X)NAMElib2648 - subroutines for the HP 2648 graphics terminal
SYNOPSIS
#include <stdio.h>
typedef char *bitmat;
FILE *trace;
cc file.c -l2648
DESCRIPTION
Lib2648 is a general purpose library of subroutines useful for
interactive graphics on the Hewlett-Packard 2648 graphics terminal. To
use it you must call the routine ttyinit() at the beginning of
execution, and done() at the end of execution. All terminal input and
output must go through the routines rawchar, readline, outchar, and
outstr.
Lib2648 does the necessary ^E/^F handshaking if getenv(``TERM'')
returns ``hp2648'', as it will if set by tset(1). Any other value,
including for example ``2648'', will disable handshaking.
Bit matrix routines are provided to model the graphics memory of the
2648. These routines are generally useful, but are specifically useful
for the update function which efficiently changes what is on the screen
to what is supposed to be on the screen. The primative bit matrix
routines are newmat, mat, and setmat.
The file trace, if non-null, is expected to be a file descriptor as
returned by fopen. If so, lib2648 will trace the progress of the
output by writing onto this file. It is provided to make debugging
output feasible for graphics programs without messing up the screen or
the escape sequences being sent. Typical use of trace will include:
switch (argv[1][1]) {
case 'T':
trace = fopen("trace", "w");
break;
...
if (trace)
fprintf(trace, "x is %d, y is %s\n", x, y);
...
dumpmat("before update", xmat);
ROUTINES
agoto(x, y)
Move the alphanumeric cursor to position (x, y), measured from
the upper left corner of the screen.
aoff() Turn the alphanumeric display off.
aon() Turn the alphanumeric display on.
areaclear(rmin, cmin, rmax, cmax)
Clear the area on the graphics screen bordered by the four
arguments. In normal mode the area is set to all black, in
inverse video mode it is set to all white.
beep() Ring the bell on the terminal.
bitcopy(dest, src, rows, cols) bitmat dest, src;
Copy a rows by cols bit matrix from src to (user provided) dest.
cleara()
Clear the alphanumeric display.
clearg()
Clear the graphics display. Note that the 2648 will only clear
the part of the screen that is visible if zoomed in.
curoff()
Turn the graphics cursor off.
curon()
Turn the graphics cursor on.
dispmsg(str, x, y, maxlen) char *str;
Display the message str in graphics text at position (x, y).
The maximum message length is given by maxlen, and is needed for
dispmsg to know how big an area to clear before drawing the
message. The lower left corner of the first character is at (x,
y).
done() Should be called before the program exits. Restores the tty to
normal, turns off graphics screen, turns on alphanumeric screen,
flushes the standard output, etc.
draw(x, y)
Draw a line from the pen location to (x, y). As with all
graphics coordinates, (x, y) is measured from the bottom left
corner of the screen. (x, y) coordinates represent the first
quadrant of the usual Cartesian system.
drawbox(r, c, color, rows, cols)
Draw a rectangular box on the graphics screen. The lower left
corner is at location (r, c). The box is rows rows high and
cols columns wide. The box is drawn if color is 1, erased if
color is 0. (r, c) absolute coordinates represent row and
column on the screen, with the origin at the lower left. They
are equivalent to (x, y) except for being reversed in order.
dumpmat(msg, m, rows, cols) char *msg; bitmat m;
If trace is non-null, write a readable ASCII representation of
the matrix m on trace. Msg is a label to identify the output.
emptyrow(m, rows, cols, r) bitmat m;
Returns 1 if row r of matrix m is all zero, else returns 0.
This routine is provided because it can be implemented more
efficiently with a knowledge of the internal representation than
a series of calls to mat.
error(msg) char *msg;
Default error handler. Calls message(msg) and returns. This is
called by certain routines in lib2648. It is also suitable for
calling by the user program. It is probably a good idea for a
fancy graphics program to supply its own error procedure which
uses setjmp(3) to restart the program.
gdefault()
Set the terminal to the default graphics modes.
goff() Turn the graphics display off.
gon() Turn the graphics display on.
koff() Turn the keypad off.
kon() Turn the keypad on. This means that most special keys on the
terminal (such as the alphanumeric arrow keys) will transmit an
escape sequence instead of doing their function locally.
line(x1, y1, x2, y2)
Draw a line in the current mode from (x1, y1) to (x2, y2). This
is equivalent to move(x1, y1); draw(x2, y2); except that a bug
in the terminal involving repeated lines from the same point is
compensated for.
lowleft()
Move the alphanumeric cursor to the lower left (home down)
position.
mat(m, rows, cols, r, c) bitmat m;
Used to retrieve an element from a bit matrix. Returns 1 or 0
as the value of the [r, c] element of the rows by cols matrix m.
Bit matrices are numbered (r, c) from the upper left corner of
the matrix, beginning at (0, 0). R represents the row, and c
represents the column.
message(str) char *str;
Display the text message str at the bottom of the graphics
screen.
minmax(g, rows, cols, rmin, cmin, rmax, cmax) bitmat g;
int *rmin, *cmin, *rmax, *cmax;
Find the smallest rectangle that contains all the 1 (on)
elements in the bit matrix g. The coordinates are returned in
the variables pointed to by rmin, cmin, rmax, cmax.
move(x, y)
Move the pen to location (x, y). Such motion is internal and
will not cause output until a subsequent sync().
movecurs(x, y)
Move the graphics cursor to location (x, y).
bitmat newmat(rows, cols)
Create (with malloc(3)) a new bit matrix of size rows by cols.
The value created (e.g. a pointer to the first location) is
returned. A bit matrix can be freed directly with free.
outchar(c) char c;
Print the character c on the standard output. All output to the
terminal should go through this routine or outstr.
outstr(str) char *str;
Print the string str on the standard output by repeated calls to
outchar.
printg()
Print the graphics display on the printer. The printer must be
configured as device 6 (the default) on the HPIB.
char rawchar()
Read one character from the terminal and return it. This
routine or readline should be used to get all input, rather than
getchar(3).
rboff()
Turn the rubber band line off.
rbon() Turn the rubber band line on.
char *rdchar(c) char c;
Return a readable representation of the character c. If c is a
printing character it returns itself, if a control character it
is shown in the ^X notation, if negative an apostrophe is
prepended. Space returns ^`, rubout returns ^?.
NOTE: A pointer to a static place is returned. For this reason,
it will not work to pass rdchar twice to the same
fprintf/sprintf call. You must instead save one of the values
in your own buffer with strcpy.
readline(prompt, msg, maxlen) char *prompt, *msg;
Display prompt on the bottom line of the graphics display and
read one line of text from the user, terminated by a newline.
The line is placed in the buffer msg, which has size maxlen
characters. Backspace processing is supported.
setclear()
Set the display to draw lines in erase mode. (This is reversed
by inverse video mode.)
setmat(m, rows, cols, r, c, val) bitmat m;
The basic operation to store a value in an element of a bit
matrix. The [r, c] element of m is set to val, which should be
either 0 or 1.
setset()
Set the display to draw lines in normal (solid) mode. (This is
reversed by inverse video mode.)
setxor()
Set the display to draw lines in exclusive or mode.
sync() Force all accumulated output to be displayed on the screen.
This should be followed by fflush(stdout). The cursor is not
affected by this function. Note that it is normally never
necessary to call sync, since rawchar and readline call sync()
and fflush(stdout) automatically.
togvid()
Toggle the state of video. If in normal mode, go into inverse
video mode, and vice versa. The screen is reversed as well as
the internal state of the library.
ttyinit()
Set up the terminal for processing. This routine should be
called at the beginning of execution. It places the terminal in
CBREAK mode, turns off echo, sets the proper modes in the
terminal, and initializes the library.
update(mold, mnew, rows, cols, baser, basec) bitmat mold, mnew;
Make whatever changes are needed to make a window on the screen
look like mnew. Mold is what the window on the screen currently
looks like. The window has size rows by cols, and the lower
left corner on the screen of the window is [baser, basec].
Note: update was not intended to be used for the entire screen.
It would work but be very slow and take 64K bytes of memory just
for mold and mnew. It was intended for 100 by 100 windows with
objects in the center of them, and is quite fast for such
windows.
vidinv()
Set inverse video mode.
vidnorm()
Set normal video mode.
zermat(m, rows, cols) bitmat m;
Set the bit matrix m to all zeros.
zoomn(size)
Set the hardware zoom to value size, which can range from 1 to
15.
zoomoff()
Turn zoom off. This forces the screen to zoom level 1 without
affecting the current internal zoom number.
zoomon()
Turn zoom on. This restores the screen to the previously
specified zoom size.
DIAGNOSTICS
The routine error is called when an error is detected. The only error
currently detected is overflow of the buffer provided to readline.
Subscripts out of bounds to setmat return without setting anything.
FILES
/usr/lib/lib2648.a
SEE ALSOfed(1)AUTHOR
Mark Horton
BUGS
This library is not supported. It makes no attempt to use all of the
features of the terminal, only those needed by fed. Contributions from
users will be accepted for addition to the library.
The HP 2648 terminal is somewhat unreliable at speeds over 2400 baud,
even with the ^E/^F handshaking. In an effort to improve reliability,
handshaking is done every 32 characters. (The manual claims it is only
necessary every 80 characters.) Nonetheless, I/O errors sometimes
still occur.
There is no way to control the amount of debugging output generated on
trace without modifying the source to the library.
4.2 Berkeley Distribution May 27, 1986 LIB2648(3X)
