diff options
Diffstat (limited to 'sys/gio/cursor/doc')
| -rw-r--r-- | sys/gio/cursor/doc/cursor.hlp | 194 | ||||
| -rw-r--r-- | sys/gio/cursor/doc/giotr.notes | 330 |
2 files changed, 524 insertions, 0 deletions
diff --git a/sys/gio/cursor/doc/cursor.hlp b/sys/gio/cursor/doc/cursor.hlp new file mode 100644 index 00000000..d9912607 --- /dev/null +++ b/sys/gio/cursor/doc/cursor.hlp @@ -0,0 +1,194 @@ +.help GIO Mar85 "Cursor Mode" +.nh 3 +Cursor Mode + + In cursor mode, i.e., after a call to \fBclgcur\fR or after typing "=gcur", +a number of special keystrokes shall be recognized for interactive display +control. All graphics output to stdgraph and stdimage is routed through the +CL on the way to the graphics kernel. The CL will optionally spool in an +internal buffer all graphics instructions output to an interactive device. +This internal buffer is emptied whenever the device screen is cleared. +In cursor mode, special keystrokes may be used to redraw all or any portion +of the spooled graphics, e.g., one may zoom in on a portion of the plot and +then roam about on the plot at high magnification. Since the spooled graphics +vectors typically contain more information than can be displayed at normal +magnification, zooming in on a feature may bring out additional detail +(the maximum resolution is 32768 points in either axis). Increasing the +magnification will increase the precision of the cursor by the same factor. + +Cursor mode is implemented by performing coordinate transformation and +clipping on each GKI instruction in the frame buffer, passing the transformed +and clipped instructions on to the graphics kernel. +The cursor mode operations perform a simple geometric transformation on +the spooled graphics frame, mapping a rectangular window of the spooled +frame onto the device screen. The graphics frame itself is not modified, +hence zoom out or reset and redraw will restore the original display. + +If the graphics frame is a typical vector plot with drawn and labeled +axes, magnifying a portion of the plot may cause the axes to be lost. +If this is not what is desired a keystroke is provided to draw and label +the axes of the displayed window. The axes will be overplotted on the +current display and will not be saved in the frame buffer, hence they +will be lost when the frame is redrawn. In cursor mode the viewport is +the full display area of the output device, hence the tick mark labels +of the drawn axes will be drawn inside the viewport. This form of axes +labeling is used because it is simple and because it is appropriate for +both vector graphics and image display output devices (and cursor mode +must serve both). + +The cursor mode keystrokes are all upper case letters, reserving lower case +for applications programs. The terminal shift lock key may be used to +minimize typing. The recognized cursor mode keystrokes are shown below. + + +.ks +.nf +(*X* means not yet implemented) + + ? print list of keystrokes + *A* draw and label the axes of current viewport + C print the cursor position as it moves + *D* draw a line by marking the endpoints + E expand plot by setting window corners + F set fast cursor (for HJKL) + H step cursor left + J step cursor down + K step cursor up + L step cursor right + M move point under cursor to center of screen + P zoom out (restore previous expansion) + *S* select WCS at current position of cursor + *T* draw a text string + *U* undo (delete) the last instruction in the frame buffer + V set slow cursor (for HJKL) + X zoom in, X only + Y zoom in, Y only + Z zoom in, both X and Y + < set lower limit of plot to the cursor y value + > set upper limit of plot to the cursor y value + *\* escape next character + : set cursor mode options + :! send a command to the host system + 0 reset and redraw + 1-9 roam + +.fi +.ce +Figure 2. Cursor Mode Keystrokes +.ke + + +The numeric keypad of the terminal (if it has one) is used for directional +roaming. The directional significance of the numeric keys for roaming +is obvious if the terminal has a keypad, and is illustrated below. + + +.ks +.nf + 7 8 9 135 090 045 + + 4 5 6 180 000 000 + + 1 2 3 225 -90 -45 +.fi +.ke + + +If the character : is typed while in cursor mode the alpha cursor will appear +at the bottom of the screen, allowing a command line to be entered. If the +command \fIbegins with a period it is interpreted as a cursor mode command\fR, +otherwise the command is passed as a string to the applications program. +Multiple commands may be entered on a line delimited by semicolons. +The command set currently recognized is shown below. Minimum match +abbreviations are permitted. + +.ls 4 +.ls 15 help +Print a list of the cursor mode commands. +.le +.ls case[+-] +Ignore case when interpreting keystrokes. If this option is selected the cursor +mode keystrokes may conflict with those of the applications program. +.le +.ls clear +Clear the alpha screen (but not the graphics screen). This is done by writing +sufficient blank lines to scroll any text off the screen. Does not work if +terminal has only one memory. +.le +.ls markcur[+-] +Draw a small graphics mark at the position of the cursor whenever the cursor +is read, i.e., when cursor mode exits. The default is to not mark. +.le +.ls off [keys] +Disable all cursor mode keystrokes except : (colon). If followed by a list +of keys, e.g., ":.off 0-9IC", only the listed keys are disabled. +.le +.ls on [keys] +Renable all cursor mode keystrokes, or just the listed keystrokes. +.le +.ls page[+-] +Clear the screen when large blocks of text are to be printed, e.g., for '?', +show, and so on. If paging is disabled the text will overwrite the graphics +display. +.le +.ls read <file> +Load the graphics frame from the named metafile. +The current graphics frame is discarded. +.le +.ls reset +Disconnect any connected graphics kernels and free all file descriptors and +memory used by the graphics system. Exit cursor mode. +.le +.ls show +Print the values of all cursor mode parameters, show the status of any +connected graphics kernels, summarize memory utilization, etc. +.le +.ls snap [device] +Dispose of the graphics frame to the standard plotter or to the named device. +A magnified graph will be plotted as it appears on the screen. +.le +.ls txset [size] [up] +Set the text drawing parameters (character size and character up vector). +For example, ".tx 2 180" would set the character size to 2.0 and character +up to 180 degrees for a vertical string drawn upwards. +.le +.ls write <file> +Save the graphics frame in (or append to) the named metafile. +If an exclamation is appended to the command (e.g., "w! file") the output +file, if any, will be overwritten. If a plus sign is appended the entire +frame will be saved regardless of any plot expansion. +.le +.ls xres=N +Set the (soft) device resolution in X. A decrease in resolution will generally +yield an increase in plotting speed. Only plots generated on the graphics +terminal are affected. +.le +.ls yres=N +Set the (soft) device resolution in Y. +.le +.ls zero +Equivalent to the numeric key 0, i.e., restore the unitary workstation +transformation and redraw the screen. +.le +.le + + +For example, to set the X and Y resolutions to 250 and 100, respectively, +one could enter the following command (the computer will type the ':' at +the bottom of the screen when the ':' key is pressed): + + :.xres=250;yres=100 + +Cursor mode may be initialized at login time by supplying a CL environment +variable named "cminit". For example, + + cl> set cminit = off + +would disable cursor mode, and + + cl> set cminit = "mark;case-;xres=100;yres=50" + +would enable marking, turn off case sensitivity, and set the plotting +resolution to 100x50. Initialization is performed only once, when cursor +mode is first entered. +.sh diff --git a/sys/gio/cursor/doc/giotr.notes b/sys/gio/cursor/doc/giotr.notes new file mode 100644 index 00000000..a9221445 --- /dev/null +++ b/sys/gio/cursor/doc/giotr.notes @@ -0,0 +1,330 @@ +.help GIO Feb85 "Graphics I/O" +.nh +Graphics I/O Dataflow + + The GIO procedures are resident in an external applications task which +does graphics. GIO writes a GKI instruction stream which, if not sent directly +to a metafile, is sent to one of the standard graphics streams STDGRAPH, +STDIMAGE, or STDPLOT, much as output is sent to STDOUT or STDERR. +The procedure \fBprfilbuf\fR (directory etc$), which reads the command +stream from a subprocess, is resident in the CL and executes all pseudofile +i/o instructions from a subprocess. Note that \fBprfilbuf\fR is part of the +i/o system of IRAF and operates transparently to the CL. + + +.ks +.nf + GIO(task) ---ipc--> PRFILBUF(CL) --> file (or pipe) + | + v external + GIOTR ---ipc--> graphics + | kernel + v + stdgraph kernel + | + v + (zfioty) + graphics terminal + + + task | cl | task +.fi + +.ce +Graphics Output Dataflow +.ke + + +The \fBprfilbuf\fR procedure passes record read or write requests for the +pseudofiles STDIN, STDOUT or STDERR on to file descriptors assigned by the +CL with the \fBprredir\fR procedure at task execution time. The sole function +of the CL in graphics i/o is to control the redirection of the graphics +i/o streams with \fBprredir\fR. The CL may redirect any of the graphics +streams, i.e., the user may redirect any graphics stream on the command line +when a command is entered, but by default output is directed to a filter +resident in the CL process. This filter is a procedure named \fBgiotr\fR. + + giotr (stream, buffer, nchars) + +The primary function of GIOTR is to pass metacode instructions on to a kernel. +The instruction stream is scanned and special actions are taken for some of +the GKI control instructions. In particular, GIOTR must spawn graphics kernel +subprocesses upon demand. GIOTR is also capabable of performing an +additional transformation upon the drawing instructions before they are passed +to the kernel. This transformation, known as the \fBworkstation +transformation\fR, maps a rectangular portion of the NDC space into the full +device screen, clipping at the boundary of the viewport into NDC space. +The workstation transformation provides a zoom and pan capability and is +controlled interactively by the user in \fBcursor mode\fR (section 3.3). + +As noted earlier, the \fBstdgraph kernel\fR ("fast" kernel) is resident in +the CL process. This is necessary for efficiency reasons and is desirable +in any case because the CL process owns the graphics device, i.e., the +graphics terminal. All devices except the user's graphics terminal are +controlled by external graphics kernel processes. The STDGRAPH kernel is +itself available as an external process and may be called as such to drive +a graphics terminal other than the user terminal (or even to drive the user +terminal if one is willing to shuffle output back through IPC). A graphics +kernel may support an arbitrary number of devices, and may write to more +than one device simultaneously. In addition to being called by GIOTR, +a graphics kernel may be called directly as a CL task to process metacode from +either a file or the standard input, e.g., from a pipe. This offers +additional flexibility as the CL parameter mechanism may then be used to +gain control over metacode translation. + +.nh 2 +Graphics Stream I/O + + The functions performed by GIOTR are summarized in pseudocode below. +GIOTR maintains a separate descriptor for each of the three graphics streams +and is capable of servicing intermixed i/o requests for all streams +simultaneously. The information stored in the descriptor +includes the workstation name, process information, WCS storage for +the SETWCS and GETWCS instructions, the workstation transformation, +and the frame buffer, used to spool GKI instructions for cursor mode. + + +.tp 6 +.nf +procedure giotr (fd, buffer, nchars) + +fd graphics stream (STDGRAPH, etc.) +buffer[] buffer containing GKI metacode instructions +nchars number of chars to be read or written + +begin + # Note that a GKI instruction may span a buffer boundary. + # The code which gets the next instruction from the buffer + # must always return a full instruction, hence some local + # buffering is required therein to reconstruct instructions. + + while (get next instruction != buffer empty) { + + # Handle special instructions. + switch (instruction) { + + case GKI_OPENWS: + if (device not already open) { + read graphcap entry for device + get process name from graphcap entry + if (process not already connected) { + if (some other process is connected) + disconnect current kernel process + connect new kernel process + } + } + output instruction + flush output + clear frame buffer + + case GKI_CLOSEWS, GKI_FLUSH: + output instruction + flush output + + case GKI_CANCEL: + output instruction + flush output + clear frame buffer + + case GKI_SETWCS: + save WCS in descriptor + + case GKI_GETWCS: + write saved WCS to fd + flush (fd) + + default: + append unmodified instruction to frame buffer + perform workstation transformation upon instruction + output transformed instruction + } + } +end +.fi + + +The action implied by "output instruction" above is the following: + + +.ks +.nf + if (kernel is resident in this process) + call gki_execute to execute the instruction + else + call write (process, instruction, nchars) +.fi +.ke + + +The frame buffer (required for cursor mode) will be dynamically allocated and +will be no larger than it has to be, but will have a fixed (user defined) +upper limit, e.g., 128Kb. The median size for a plot is typically 5-10Kb. +Instructions will be silently discarded if the buffer grows too large. +Buffering can be turned off completely if desired, and will always be turned +off for STDPLOT. + +.nh 2 +Cursor Mode Details + + Most of the functionality required to implement cursor mode is provided +by GIOTR. The primary functions of the cursor mode code are to read the +cursor and keystroke, modify the workstation transformation, and redraw the +contents of the frame buffer subject to the new workstation transformation. +Cursor mode does not modify the contents of the frame buffer, except for +possibly appending new graphics instructions to the frame buffer. +A workstation transformation set with cursor mode remains in effect until +the frame buffer is cleared, hence any additional graphics output from the +task which initiated the cursor read (and cursor mode) will undergo the +workstation transformation when drawn. + + +.nf +# PR_FILBUF -- Fill FIO buffer from an IPC channel subject to the CL/IPC +# protocol for multiplexing pseudofile data streams with the command stream. +# Each process has an associated set of pseudofile streams. Each pseudofile +# stream is connected to one, and only one, file or pseudofile of another +# process. I/O requests to XMIT or XFER to an ordinary file are straightforward +# to satisfy. An i/o request from one pseudofile to another is satisfied +# by posting the request (pushing it on a stack) and redirecting our input +# to the process owning the pseudofile being read or written. Pseudofile +# requests are then processed from the second process until a request is +# received which satisfies the posted request from the original process. +# When the original request is satisfied it is popped from the stack and input +# will again be taken from the original process. Note that we cannot write +# directly to the output process since that would violate the IPC protocol +# (the second process may wish to write to its stdout or stderr rather than +# read, etc.: the process must be allowed to complete the original request +# itself). +# +# Request Packet (pushed onto stack for IPC to IPC i/o). +# +# pr process slot number of process placing the request +# iomode request is a read or a write +# count number of chars to be transferred +# ps_server pseudofile number in server process +# ps_receiver pseudofile number in receiver process +# +# The request packet describes a pending pseudofile i/o request. The named +# pseudofile in the server process is either reading from or writing to the +# named pseudofile in the receiver process. + +int procedure pr_filbuf (fd) + +begin + input = fd (the IPC input channel of a process) + + repeat { + get a line from the input file + if (neither XMIT nor XFER directive) + if (request pending) + error: IPC protocol corrupted + else + return command + + if (line is an XMIT directive) { + if (destination is a file) { + # Write from pseudofile to an ordinary file. + get data record from input + write data record to file + + } else { + # Write from pseudofile to another pseudofile. + if (XMIT satisfies XFER request on top of stack) + get data record from input + write record to stacked process + restore input to stacked process + pop request from stack + + } else { + # If writing to local kernel GIOTR will return a null + # length record and we are done. + + get data record from input + if (writing to a graphics stream) + call giotr filter to transform record + if (anything left to output) { + push request on stack + switch input to IPC input of receiver process + } + } + } + + } else if (line is an XFER directive) { + if (source is an ordinary file) { + # Read from a file. + read data record from file + write to active process + + } else if (source is another process) { + # Read from another pseudofile. + if (XFER satisfies XMIT request on top of stack) { + read record from stacked process + write to active process + restore input to stacked process + pop request from stack + } else { + push request on stack + switch input to IPC input channel of receiver process + } + } + } + } +end + + +# GIOTR -- Graphics i/o filter. + +procedure giotr (fd, buffer, nchars) + +fd graphics stream (STDGRAPH, etc.) +buffer[] buffer containing GKI metacode instructions +nchars number of chars to be read or written + +begin + # Note that a GKI instruction may span a buffer boundary. + # The code which gets the next instruction from the buffer + # must always return a full instruction, hence some local + # buffering is required therein to reconstruct instructions. + + while (buffer not empty) { + + # Handle special instructions. + switch (next_instruction) { + + case GKI_OPENWS: + if (device not already open) { + read graphcap entry for device + get process name from graphcap entry + if (process not already connected) { + if (some other process is connected) + disconnect current kernel process + connect new kernel process + } + } + output instruction + flush output + clear frame buffer + + case GKI_CLOSEWS, GKI_FLUSH: + output instruction + flush output + + case GKI_CANCEL: + output instruction + flush output + clear frame buffer + + case GKI_SETWCS: + save WCS in descriptor + + case GKI_GETWCS: + write saved WCS to fd + flush (fd) + + default: + append unmodified instruction to frame buffer + perform workstation transformation upon instruction + output transformed instruction + } + } +end |