sgikern: Simple graphics interface (SGI) graphics kernel

Package: plot

Usage

sgikern input

Parameters

input

The list of input metacode files.

device = "sgimc"

The name of the logical or physical graphics device for which SGI metacode is to be generated.

generic = no

The remaining parameters are ignored when generic = yes.

debug = no

If debug = yes, the graphics instructions are decoded and printed during processing.

verbose = no

If verbose = yes, the elements of polylines, cell arrays, etc. will be printed in debug mode.

gkiunits = no

By default, coordinates are printed in NDC rather than GKI units.

Description

Task sgikern translates GKI metacode into a much simpler format and then calls up a host system task to dispose of the intermediate file to a plotter device. The SGI kernel can generate as output either an SGI metacode file, used to drive laser plotters and pen plotters, or a bitmap file, used to drive raster graphics devices. Both types of files have a very simple format, making it straightforward to implement interfaces for new devices.

The SGI/SGK metacode format is a sequence of 16 bit integer values encoded in the machine independent MII format (twos complement, most significant byte first). The SGI kernel reduces all IRAF plotting instructions to only four SGK metacode instructions, i.e.:

opcode  arguments                description

   1      0    0                start a new frame
   2      X    Y                move to (x,y)
   3      X    Y                draw to (x,y)
   4      W    0                set line width (>= 1)

All coordinates are specified in GKI NDC units in the range 0-32767. Note that all metacode instructions are the same length. All text generation, line type emulation, mark drawing, etc., is done in the higher level IRAF software. The metacode file is a standard IRAF random access (non record structured) binary file.

The bitmap format written by the SGK is even simpler than the metacode format. Output consists either of a single binary raster file containing one or more bitmaps with no embedded header information, or a set of binary files with the same root name and the extensions .1, .2, etc., each of which contains a single bitmap. All bitmaps the same size. The size is specified in the graphcap entry for the device and may be passed to the host dispose task on the foreign task command line if desired. Page offsets may also be passed on the command line, e.g., to position the plot on the plotter page.

The following graphcap fields apply to both metacode and bitmap devices.

DD      host command to dispose of metacode file ($F)
DB      have the kernel print debug messages during execution
RM      boolean; if present, SGK will delete metacode file
MF      multiframe count (max frames per job)
NF      store each frame in a new file (one frame/file)
RO      rotate plot (swap x and y)
YF      y-flip plot (flip y axis) (done after rotate)

The following additional fields are defined for bitmap devices.

BI      boolean; presence indicates a bitmapped or raster device
LO      width in device pixels of a line of size 1.0
LS      difference in device pixels between line sizes
PX      physical x size of bitmap as stored in memory, bits
PY      physical y size of bitmap, i.e., number of lines in bitmap
XO,YO   origin of plotting window in device pixels
XW,YW   width of plotting window in device pixels
NB      number of bits to be set in each 8 bit byte output
BF      bit-flip each byte in bitmap (easier here than later)
BS      byte swap the bitmap when output (swap every two bytes)
WS      word swap the bitmap when output (swap every four bytes)

The multiframe count (MF) limits the number of frames per job, where a job refers to the dispose command submitted to the host to process the frames. If the new file flag (NF) is absent, all frames will be stored in the same physical file (this holds for both metacode and bitmap frames). If the new file flag (NF) is set, each frame will be stored in a separate file, with the N files having the names $F.1, $F.2, ... $F.N, where $F is the unique (root) filename generated from the template given in the DD string. The $F is replaced by the root filename, rather than by a list of all the filenames, to keep the OS command to a reasonable length and to permit the use of host file templates to perform operate upon the full set of files (and to avoid having to choose between spaces and commas to delimit the filenames). For example, if MF=8 and NF=yes, then "$F.[1-8]" will match the file set on a UNIX host. The template "$F.*" is less precise but would also work.

The values of graphcap device capability fields may also be substituted symbolically when building up the dispose command. If the sequence $(CC) is encountered in the dispose command template, the string value of the capability CC will be substituted. For example, given the sequence "-w $(xr)" and the graphcap capability entry ":xr#1024:", the output sequence would be "-w 1024". This feature is particularly useful when several high level device entries include (via "tc=device") a generic device entry. The DD string in the generic entry may substitute the values of device parameters defined differently in the high level entries; this avoids the need to duplicate an almost identical DD string in several device entries.

The output raster will consist of PY lines each of length PX bits. If PX is chosen to be a multiple of 8, there will be PX/8 bytes per line of the output raster. Note that the values of PX and PY are arbitrary and should be chosen to simplify the code of the translator and maximize efficiency. In particular, PX and PY do not in general define the maximum physical resolution of the device, although if NB=8 the value of PX will typically approximate the physical resolution in X. If there are multiple bitmap frames per file, each frame will occupy an integral number of SPP char units of storage in the output file, with the values of any extra bits at the end of the bitmap being undefined (a char is 16 bits on most IRAF host machines).

The plot will be rasterized in a logical window XW one-bit pixels wide and YW pixels high. The first YO lines of the output raster will be zero, with the plotting window beginning at line YO+1. The first XO bits of each output line will be zeroed, with the plotting window beginning at bit XO+1. The bytes in each output line may be bit-flipped if desired, and all of the bits in each output byte need not be used for pixel data. If the bit packing factor NB is set to 8 the plotting window will map into XW bits of storage of each output line. If fewer than 8 bits are used in each output byte more than XW physical bits of storage will be used, e.g., if NB=4, XW*2 bits of storage are required for a line of the plotting window. The unused bits are set to zero. The translator can later "or" a mask into the zeroed bits, flip the data bits, or perform any other bytewise operation using simple lookup table mapping techniques.

The DD entry consists of three fields delimited by commas, i.e., the device name, including node name (not used at present for this kernel), the VOS root filename to be used to make a temporary file to contain the output (note that this is NOT a host filename), and lastly the command to be sent to the host system to dispose of the output metacode file or bitmap file to the plotter device.

Examples

1. Convert the GIO/GKI metacode file "dev$mc" into an SGI format metacode file.

cl> sgikern dev$mc device=sgimc

2. The same GIO/GKI metacode file read in the previous example ("dev$mc") can be plotted on the SGI device "qms_sgi".

cl> sgikern dev$mc device=qms_sgi

See also

"The IRAF Simple Graphics Interface (SGI)", August 1986
sgidecode, stdgraph, stdplot