LIB2648(3X)                                                        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
       Lib2648 is a general purpose library of subroutines useful for interac‐
       tive 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 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  out‐
       put 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 argu‐
              ments.   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 mes‐
              sage.   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 graph‐
              ics  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  col‐
              umn  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) posi‐
              tion.

       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) ele‐
              ments 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 rou‐
              tine 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  nec‐
              essary  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 termi‐
              nal, 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  win‐
              dows.

       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 speci‐
              fied 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 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 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)
 
Generated: 2016-12-26
Generated by man2html V0.25
page hit count: 382
Valid CSS Valid XHTML 1.0 Strict