LIB2648(3X-BSD) RISC/os Reference Manual LIB2648(3X-BSD)
NAME
lib2648 - 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 graph-
ics terminal. To use it you must call the routine ttyinit()
at the beginning of execution, and done() at the end of exe-
cution. 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 sup-
posed to be on the screen. The primative bit matrix rou-
tines 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 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),
measured from the upper left corner of the screen.
Printed 1/15/91 Page 1
LIB2648(3X-BSD) RISC/os Reference Manual LIB2648(3X-BSD)
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 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 posi-
tion (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
Page 2 Printed 1/15/91
LIB2648(3X-BSD) RISC/os Reference Manual LIB2648(3X-BSD)
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 pro-
gram.
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
Printed 1/15/91 Page 3
LIB2648(3X-BSD) RISC/os Reference Manual LIB2648(3X-BSD)
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 coordi-
nates 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 subse-
quent 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 rou-
tine 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 see getc(3S).
rboff() Turn the rubber band line off.
rbon() Turn the rubber band line on.
Page 4 Printed 1/15/91
LIB2648(3X-BSD) RISC/os Reference Manual LIB2648(3X-BSD)
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 nota-
tion, 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.
Printed 1/15/91 Page 5
LIB2648(3X-BSD) RISC/os Reference Manual LIB2648(3X-BSD)
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 pro-
vided to readline.
Subscripts out of bounds to setmat return without setting
anything.
FILES
/usr/lib/lib2648.a
AUTHOR
Mark Horton
ERROR
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.
Page 6 Printed 1/15/91
LIB2648(3X-BSD) RISC/os Reference Manual LIB2648(3X-BSD)
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 trace without modifying the source to the
library.
Printed 1/15/91 Page 7