Commit | Line | Data |
---|---|---|
927955d2 KM |
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 | .\" | |
3d10db30 | 5 | .\" @(#)lib2648.3 6.2 (Berkeley) %G% |
927955d2 | 6 | .\" |
66a99ca4 | 7 | .TH LIB2648 3X "" |
927955d2 KM |
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 , | |
3d10db30 | 129 | and is needed for dispmsg to know how big an area to clear |
927955d2 KM |
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. |