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