![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to lib2648.3 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSDReno / old / lib2648|
Return to lib2648.3 CVS log | Up to [CSRG BSD Unix] / 43BSDReno / old / lib2648 |
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.