4.3BSD-UWisc/man/cat3/lib2648.3x
LIB2648(3X) UNIX Programmer's Manual LIB2648(3X)
NAME
lib2648 - subroutines for the HP 2648 graphics terminal
SYNOPSIS
#include <stdio.h>
typedef char *bitmat;
FILE *trace;
cc file.c -l2648
DESCRIPTION
_L_i_b_2_6_4_8 is a general purpose library of subroutines useful
for interactive graphics on the Hewlett-Packard 2648 graph-
ics terminal. To use it you must call the routine _t_t_y_i_n_i_t()
at the beginning of execution, and _d_o_n_e() at the end of exe-
cution. All terminal input and output must go through the
routines _r_a_w_c_h_a_r, _r_e_a_d_l_i_n_e, _o_u_t_c_h_a_r, and _o_u_t_s_t_r.
_L_i_b_2_6_4_8 does the necessary ^E/^F handshaking if
_g_e_t_e_n_v(``_T_E_R_M'') returns ``hp2648'', as it will if set by
_t_s_e_t(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 _u_p_d_a_t_e function which
efficiently changes what is on the screen to what is sup-
posed to be on the screen. The primative bit matrix rou-
tines are _n_e_w_m_a_t, _m_a_t, and _s_e_t_m_a_t.
The file _t_r_a_c_e, if non-null, is expected to be a file
descriptor as returned by _f_o_p_e_n. If so, _l_i_b_2_6_4_8 will trace
the progress of the output by writing onto this file. It is
provided to make debugging output feasible for graphics pro-
grams 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), meas-
ured from the upper left corner of the screen.
Printed 12/27/86 May 27, 1986 1
LIB2648(3X) UNIX Programmer's Manual LIB2648(3X)
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,
Copy a _r_o_w_s by _c_o_l_s bit matrix from _s_r_c to (user pro-
vided) _d_e_s_t.
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 _s_t_r in graphics text at position
(_x, _y). The maximum message length is given by _m_a_x_l_e_n,
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)
Printed 12/27/86 May 27, 1986 2
LIB2648(3X) UNIX Programmer's Manual LIB2648(3X)
Draw a rectangular box on the graphics screen. The
lower left corner is at location (_r, _c). The box is
_r_o_w_s rows high and _c_o_l_s columns wide. The box is drawn
if _c_o_l_o_r is 1, erased if _c_o_l_o_r 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 _t_r_a_c_e is non-null, write a readable ASCII represen-
tation of the matrix _m on _t_r_a_c_e. _M_s_g 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 _m_a_t.
error(msg) char *msg;
Default error handler. Calls _m_e_s_s_a_g_e(_m_s_g) and returns.
This is called by certain routines in _l_i_b_2_6_4_8. 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 _s_e_t_j_m_p(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 (_x_1, _y_1) to (_x_2,
_y_2). This is equivalent to _m_o_v_e(_x_1, _y_1); _d_r_a_w(_x_2, _y_2);
except that a bug in the terminal involving repeated
lines from the same point is compensated for.
lowleft()
Printed 12/27/86 May 27, 1986 3
LIB2648(3X) UNIX Programmer's Manual LIB2648(3X)
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 _r_o_w_s
by _c_o_l_s 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 _s_t_r 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 inter-
nal and will not cause output until a subsequent
_s_y_n_c().
movecurs(x, y)
Move the graphics cursor to location (_x, _y).
bitmat newmat(rows, cols)
Create (with _m_a_l_l_o_c(3)) a new bit matrix of size _r_o_w_s
by _c_o_l_s. The value created (e.g. a pointer to the first
location) is returned. A bit matrix can be freed
directly with _f_r_e_e.
outchar(c) char c;
Print the character _c on the standard output. All out-
put to the terminal should go through this routine or
_o_u_t_s_t_r.
outstr(str) char *str;
Print the string str on the standard output by repeated
calls to _o_u_t_c_h_a_r.
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 _r_e_a_d_l_i_n_e should be used to get all
Printed 12/27/86 May 27, 1986 4
LIB2648(3X) UNIX Programmer's Manual LIB2648(3X)
input, rather than _g_e_t_c_h_a_r(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 con-
trol character it is shown in the ^X notation, if nega-
tive 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 _f_p_r_i_n_t_f/_s_p_r_i_n_t_f call. You must instead save
one of the values in your own buffer with strcpy.
readline(prompt, msg, maxlen) char *prompt, *msg;
Display _p_r_o_m_p_t on the bottom line of the graphics
display and read one line of text from the user, ter-
minated by a newline. The line is placed in the buffer
_m_s_g, which has size _m_a_x_l_e_n characters. Backspace pro-
cessing 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 _v_a_l,
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 _s_y_n_c, since
_r_a_w_c_h_a_r and _r_e_a_d_l_i_n_e call _s_y_n_c() and _f_f_l_u_s_h(_s_t_d_o_u_t)
automatically.
togvid()
Printed 12/27/86 May 27, 1986 5
LIB2648(3X) UNIX Programmer's Manual LIB2648(3X)
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 _m_n_e_w. _M_o_l_d is what the window on
the screen currently looks like. The window has size
_r_o_w_s by _c_o_l_s, and the lower left corner on the screen
of the window is [_b_a_s_e_r, _b_a_s_e_c]. Note: _u_p_d_a_t_e 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 win-
dows 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 _s_i_z_e, 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 previ-
ously specified zoom size.
DIAGNOSTICS
The routine _e_r_r_o_r is called when an error is detected. The
only error currently detected is overflow of the buffer pro-
vided to _r_e_a_d_l_i_n_e.
Subscripts out of bounds to _s_e_t_m_a_t return without setting
anything.
Printed 12/27/86 May 27, 1986 6
LIB2648(3X) UNIX Programmer's Manual LIB2648(3X)
FILES
/usr/lib/lib2648.a
SEE ALSO
fed(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 charac-
ters. (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 _t_r_a_c_e without modifying the source to the
library.
Printed 12/27/86 May 27, 1986 7