Return to lib2648.3 CVS log

Up to [CSRG BSD Unix] / 43BSDReno / old / lib2648

Annotation of 43BSDReno/old/lib2648/lib2648.3, revision 1.1

1.1     ! root        1: .\" Copyright (c) 1983 Regents of the University of California.
        !             2: .\" All rights reserved.  The Berkeley software License Agreement
        !             3: .\" specifies the terms and conditions for redistribution.
        !             4: .\"
        !             5: .\"    @(#)lib2648.3   6.2 (Berkeley) 5/27/86
        !             6: .\"
        !             7: .TH LIB2648 3X "May 27, 1986"
        !             8: .UC 5
        !             9: .SH NAME
        !            10: lib2648 \- subroutines for the HP 2648 graphics terminal
        !            11: .SH SYNOPSIS
        !            12: .B #include <stdio.h>
        !            13: .sp
        !            14: .B "typedef char"
        !            15: .RB * bitmat ;
        !            16: .br
        !            17: FILE *trace;
        !            18: .sp
        !            19: cc file.c
        !            20: .B \-l2648
        !            21: .SH DESCRIPTION
        !            22: .I Lib2648
        !            23: is a general purpose library of subroutines useful
        !            24: for interactive graphics on the Hewlett-Packard 2648 graphics terminal.
        !            25: To use it you must call the routine
        !            26: .IR ttyinit ()
        !            27: at the beginning of execution,
        !            28: and
        !            29: .IR done ()
        !            30: at the end of execution.
        !            31: All terminal input and output must go through the routines
        !            32: .IR rawchar ,
        !            33: .IR readline ,
        !            34: .IR outchar ,
        !            35: and
        !            36: .IR outstr .
        !            37: .PP
        !            38: .I Lib2648
        !            39: does the necessary ^E/^F handshaking if
        !            40: .I "getenv(``TERM'')"
        !            41: returns ``hp2648'', as it will if set by
        !            42: .IR tset (1).
        !            43: Any other value, including for example ``2648'', will disable handshaking.
        !            44: .PP
        !            45: Bit matrix routines are provided to model the graphics memory of the 2648.
        !            46: These routines are generally useful, but are specifically useful for the
        !            47: .I update
        !            48: function which efficiently changes what is on the screen to what is
        !            49: supposed to be on the screen.
        !            50: The primative bit matrix routines are
        !            51: .IR newmat ,
        !            52: .IR mat ,
        !            53: and
        !            54: .IR setmat .
        !            55: .PP
        !            56: The file
        !            57: .IR trace ,
        !            58: if non-null, is expected to be a file descriptor as returned by
        !            59: .IR fopen .
        !            60: If so,
        !            61: .I lib2648
        !            62: will trace the progress of the output by writing onto
        !            63: this file.
        !            64: It is provided to make debugging output feasible for graphics programs without
        !            65: messing up the screen or the escape sequences being sent.
        !            66: Typical use of trace will include:
        !            67: .nf
        !            68:        \fBswitch\fP (argv[1][1]) {
        !            69:        \fBcase\fP 'T':
        !            70:                trace = fopen("trace", "w");
        !            71:                \fBbreak\fP;
        !            72:        ...
        !            73:        \fBif\fP (trace)
        !            74:                fprintf(trace, "x is %d, y is %s\en", x, y);
        !            75:        ...
        !            76:        dumpmat("before update", xmat);
        !            77: .fi
        !            78: .SH ROUTINES
        !            79: .TP
        !            80: .B agoto(x, y)
        !            81: Move the alphanumeric cursor to position (x, y),
        !            82: measured from the upper left corner of the screen.
        !            83: .TP
        !            84: .B aoff()
        !            85: Turn the alphanumeric display off.
        !            86: .TP
        !            87: .B aon()
        !            88: Turn the alphanumeric display on.
        !            89: .TP
        !            90: .B areaclear(rmin, cmin, rmax, cmax)
        !            91: Clear the area on the graphics screen bordered by the four arguments.
        !            92: In normal mode the area is set to all black, in inverse video mode
        !            93: it is set to all white.
        !            94: .TP
        !            95: .B beep()
        !            96: Ring the bell on the terminal.
        !            97: .TP
        !            98: .B bitcopy(dest, src, rows, cols) bitmat dest, src;
        !            99: Copy a
        !           100: .I rows
        !           101: by
        !           102: .I cols
        !           103: bit matrix from
        !           104: .I src
        !           105: to (user provided)
        !           106: .I dest.
        !           107: .TP
        !           108: .B cleara()
        !           109: Clear the alphanumeric display.
        !           110: .TP
        !           111: .B clearg()
        !           112: Clear the graphics display.
        !           113: Note that the 2648 will only clear the part of the screen
        !           114: that is visible if zoomed in.
        !           115: .TP
        !           116: .B curoff()
        !           117: Turn the graphics cursor off.
        !           118: .TP
        !           119: .B curon()
        !           120: Turn the graphics cursor on.
        !           121: .TP
        !           122: .B dispmsg(str, x, y, maxlen) char *str;
        !           123: Display the message 
        !           124: .I str
        !           125: in graphics text at position
        !           126: .I (x, y).
        !           127: The maximum message length is given by
        !           128: .IR maxlen ,
        !           129: and is needed for dispmsg to know how big an area to clear
        !           130: before drawing the message.
        !           131: The lower left corner of the first character is at
        !           132: .I (x, y).
        !           133: .TP
        !           134: .B done()
        !           135: Should be called before the program exits.
        !           136: Restores the tty to normal, turns off graphics screen,
        !           137: turns on alphanumeric screen, flushes the standard output, etc.
        !           138: .TP
        !           139: .B draw(x, y)
        !           140: Draw a line from the pen location to
        !           141: .I (x, y).
        !           142: As with all graphics coordinates,
        !           143: .I (x, y)
        !           144: is measured from the bottom left corner of the screen.
        !           145: .I (x, y)
        !           146: coordinates represent the first quadrant of the usual Cartesian system.
        !           147: .TP
        !           148: .B drawbox(r, c, color, rows, cols)
        !           149: Draw a rectangular box on the graphics screen.
        !           150: The lower left corner is at location
        !           151: .I (r, c).
        !           152: The box is
        !           153: .I rows
        !           154: rows high and
        !           155: .I cols
        !           156: columns wide.
        !           157: The box is drawn if
        !           158: .I color
        !           159: is 1, erased if
        !           160: .I color
        !           161: is 0.
        !           162: .I (r, c)
        !           163: absolute coordinates represent row and column on the screen,
        !           164: with the origin at the lower left.
        !           165: They are equivalent to
        !           166: .I (x, y)
        !           167: except for being reversed in order.
        !           168: .TP
        !           169: .B "dumpmat(msg, m, rows, cols) char *msg; bitmat m;"
        !           170: If
        !           171: .I trace
        !           172: is non-null, write a readable ASCII representation
        !           173: of the matrix
        !           174: .I m
        !           175: on
        !           176: .I trace.
        !           177: .I Msg
        !           178: is a label to identify the output.
        !           179: .TP
        !           180: .B emptyrow(m, rows, cols, r) bitmat m;
        !           181: Returns 1 if row
        !           182: .I r
        !           183: of matrix
        !           184: .I m
        !           185: is all zero, else returns 0.
        !           186: This routine is provided because it can be implemented more
        !           187: efficiently with a knowledge of the internal representation
        !           188: than a series of calls to
        !           189: .I mat.
        !           190: .TP
        !           191: .B error(msg) char *msg;
        !           192: Default error handler.
        !           193: Calls
        !           194: .I message(msg)
        !           195: and returns.
        !           196: This is called by certain routines in
        !           197: .IR lib2648 .
        !           198: It is also suitable for calling by the user program.
        !           199: It is probably a good idea for a fancy graphics program
        !           200: to supply its own error procedure which uses
        !           201: .IR setjmp (3)
        !           202: to restart the program.
        !           203: .TP
        !           204: .B gdefault()
        !           205: Set the terminal to the default graphics modes.
        !           206: .TP
        !           207: .B goff()
        !           208: Turn the graphics display off.
        !           209: .TP
        !           210: .B gon()
        !           211: Turn the graphics display on.
        !           212: .TP
        !           213: .B koff()
        !           214: Turn the keypad off.
        !           215: .TP
        !           216: .B kon()
        !           217: Turn the keypad on.
        !           218: This means that most special keys on the terminal (such as the alphanumeric
        !           219: arrow keys) will transmit an escape sequence instead of doing their function
        !           220: locally.
        !           221: .TP
        !           222: .B line(x1, y1, x2, y2)
        !           223: Draw a line in the current mode from
        !           224: .I (x1, y1)
        !           225: to
        !           226: .I (x2, y2).
        !           227: This is equivalent to
        !           228: .I "move(x1, y1); draw(x2, y2);"
        !           229: except that a bug in the terminal involving repeated lines from the
        !           230: same point is compensated for.
        !           231: .TP
        !           232: .B lowleft()
        !           233: Move the alphanumeric cursor to the lower left (home down) position.
        !           234: .TP
        !           235: .B "mat(m, rows, cols, r, c) bitmat m;"
        !           236: Used to retrieve an element from a bit matrix.
        !           237: Returns 1 or 0 as the value of the
        !           238: .I [r, c]
        !           239: element of the
        !           240: .I rows
        !           241: by
        !           242: .I cols
        !           243: matrix
        !           244: .I m.
        !           245: Bit matrices are numbered
        !           246: .I (r, c)
        !           247: from the upper left corner of the matrix,
        !           248: beginning at (0, 0).
        !           249: .I R
        !           250: represents the row, and
        !           251: .I c
        !           252: represents the column.
        !           253: .TP
        !           254: .B message(str) char *str;
        !           255: Display the text message
        !           256: .I str
        !           257: at the bottom of the graphics screen.
        !           258: .TP
        !           259: .B "minmax(g, rows, cols, rmin, cmin, rmax, cmax) bitmat g;"
        !           260: .ti -.5i
        !           261: .B int *rmin, *cmin, *rmax, *cmax;
        !           262: .br
        !           263: Find the smallest rectangle that contains all the 1 (on) elements in
        !           264: the bit matrix g.
        !           265: The coordinates are returned in the variables
        !           266: pointed to by rmin, cmin, rmax, cmax.
        !           267: .TP
        !           268: .B move(x, y)
        !           269: Move the pen to location
        !           270: .I (x, y).
        !           271: Such motion is internal and will not cause output
        !           272: until a subsequent
        !           273: .I sync().
        !           274: .TP
        !           275: .B movecurs(x, y)
        !           276: Move the graphics cursor to location
        !           277: .I (x, y).
        !           278: .TP
        !           279: .B bitmat newmat(rows, cols)
        !           280: Create (with
        !           281: .IR malloc (3))
        !           282: a new bit matrix of size
        !           283: .I rows
        !           284: by
        !           285: .I cols.
        !           286: The value created (e.g. a pointer to the first location) is returned.
        !           287: A bit matrix can be freed directly with
        !           288: .IR free .
        !           289: .TP
        !           290: .B outchar(c) char c;
        !           291: Print the character
        !           292: .I c
        !           293: on the standard output.
        !           294: All output to the terminal should go through this routine or
        !           295: .IR outstr .
        !           296: .TP
        !           297: .B outstr(str) char *str;
        !           298: Print the string str on the standard output by repeated calls to
        !           299: .I outchar.
        !           300: .TP
        !           301: .B printg()
        !           302: Print the graphics display on the printer.
        !           303: The printer must be configured as device 6 (the default) on the HPIB.
        !           304: .TP
        !           305: .B char rawchar()
        !           306: Read one character from the terminal and return it.
        !           307: This routine or
        !           308: .I readline
        !           309: should be used to get all input,
        !           310: rather than
        !           311: .IR getchar (3).
        !           312: .TP
        !           313: .B rboff()
        !           314: Turn the rubber band line off.
        !           315: .TP
        !           316: .B rbon()
        !           317: Turn the rubber band line on.
        !           318: .TP
        !           319: .B char *rdchar(c) char c;
        !           320: Return a readable representation of the character
        !           321: .I c.
        !           322: If
        !           323: .I c
        !           324: is a printing character it returns itself, if a control
        !           325: character it is shown in the ^X notation, if negative
        !           326: an apostrophe is prepended.  Space returns ^\`, rubout returns ^?.
        !           327: .IP
        !           328: .B NOTE:
        !           329: A pointer to a static place is returned.
        !           330: For this reason, it will not work to pass rdchar twice to the same
        !           331: .IR fprintf / sprintf
        !           332: call.
        !           333: You must instead save one of the values in your own buffer with strcpy.
        !           334: .TP
        !           335: .B readline(prompt, msg, maxlen) char *prompt, *msg;
        !           336: Display
        !           337: .I prompt
        !           338: on the bottom line of the graphics display
        !           339: and read one line of text from the user, terminated by a newline.
        !           340: The line is placed in the buffer
        !           341: .IR msg ,
        !           342: which has size
        !           343: .I maxlen
        !           344: characters.
        !           345: Backspace processing is supported.
        !           346: .TP
        !           347: .B setclear()
        !           348: Set the display to draw lines in erase mode.
        !           349: (This is reversed by inverse video mode.)
        !           350: .TP
        !           351: .B "setmat(m, rows, cols, r, c, val) bitmat m;"
        !           352: The basic operation to store a value in an element of a bit matrix.
        !           353: The
        !           354: .I [r, c]
        !           355: element of
        !           356: .I m
        !           357: is set to
        !           358: .I val,
        !           359: which should be either 0 or 1.
        !           360: .TP
        !           361: .B setset()
        !           362: Set the display to draw lines in normal (solid) mode.
        !           363: (This is reversed by inverse video mode.)
        !           364: .TP
        !           365: .B setxor()
        !           366: Set the display to draw lines in exclusive or mode.
        !           367: .TP
        !           368: .B sync()
        !           369: Force all accumulated output to be displayed on the screen.
        !           370: This should be followed by fflush(stdout).
        !           371: The cursor is not affected by this function.
        !           372: Note that it is normally never necessary to call
        !           373: .IR sync ,
        !           374: since
        !           375: .I rawchar
        !           376: and
        !           377: .I readline
        !           378: call
        !           379: .I sync()
        !           380: and
        !           381: .I fflush(stdout)
        !           382: automatically.
        !           383: .TP
        !           384: .B togvid()
        !           385: Toggle the state of video.
        !           386: If in normal mode, go into inverse video mode,
        !           387: and vice versa.
        !           388: The screen is reversed as well as the
        !           389: internal state of the library.
        !           390: .TP
        !           391: .B ttyinit()
        !           392: Set up the terminal for processing.
        !           393: This routine should be called at the beginning of execution.
        !           394: It places the terminal in CBREAK mode, turns off echo,
        !           395: sets the proper modes in the terminal,
        !           396: and initializes the library.
        !           397: .TP
        !           398: .B "update(mold, mnew, rows, cols, baser, basec) bitmat mold, mnew;"
        !           399: Make whatever changes are needed to make a window on the screen
        !           400: look like
        !           401: .IR mnew .
        !           402: .I Mold
        !           403: is what the window on the screen currently looks like.
        !           404: The window has size
        !           405: .I rows
        !           406: by
        !           407: .IR cols ,
        !           408: and the lower left corner on
        !           409: the screen of the window is
        !           410: .I [baser, basec].
        !           411: Note:
        !           412: .I update
        !           413: was not intended to be used for the entire screen.
        !           414: It would work but be very slow and take 64K bytes
        !           415: of memory just for mold and mnew.
        !           416: It was intended for 100 by 100 windows with objects in the center
        !           417: of them, and is quite fast for such windows.
        !           418: .TP
        !           419: .B vidinv()
        !           420: Set inverse video mode.
        !           421: .TP
        !           422: .B vidnorm()
        !           423: Set normal video mode.
        !           424: .TP
        !           425: .B zermat(m, rows, cols) bitmat m;
        !           426: Set the bit matrix
        !           427: .I m
        !           428: to all zeros.
        !           429: .TP
        !           430: .B zoomn(size)
        !           431: Set the hardware zoom to value
        !           432: .I size,
        !           433: which can range from 1 to 15.
        !           434: .TP
        !           435: .B zoomoff()
        !           436: Turn zoom off.
        !           437: This forces the screen to zoom level 1 without affecting the
        !           438: current internal zoom number.
        !           439: .TP
        !           440: .B zoomon()
        !           441: Turn zoom on.
        !           442: This restores the screen to the previously specified zoom size.
        !           443: .SH DIAGNOSTICS
        !           444: The routine
        !           445: .I error
        !           446: is called when an error is detected.
        !           447: The only error currently detected is overflow of the buffer
        !           448: provided to
        !           449: .IR readline .
        !           450: .PP
        !           451: Subscripts out of bounds to
        !           452: .I setmat
        !           453: return without setting anything.
        !           454: .SH FILES
        !           455: /usr/lib/lib2648.a
        !           456: .SH "SEE ALSO"
        !           457: fed(1)
        !           458: .SH AUTHOR
        !           459: Mark Horton
        !           460: .SH BUGS
        !           461: This library is not supported.
        !           462: It makes no attempt to use all of the features of the terminal,
        !           463: only those needed by fed.
        !           464: Contributions from users will be accepted for addition to the library.
        !           465: .PP
        !           466: The HP 2648 terminal is somewhat unreliable at speeds over 2400 baud,
        !           467: even with the ^E/^F handshaking.
        !           468: In an effort to improve reliability, handshaking is done every 32 characters.
        !           469: (The manual claims it is only necessary every 80 characters.)
        !           470: Nonetheless, I/O errors sometimes still occur.
        !           471: .PP
        !           472: There is no way to control the amount of debugging output generated
        !           473: on
        !           474: .I trace
        !           475: without modifying the source to the library.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.