CP/M

home *** CD-ROM | disk | FTP | other *** search

/ CP/M / CPM_CDROM.iso / zsys / znode-12 / i / plot33.lbr / PLOT-DOC.1Z / PLOT-DOC.1

Wrap

Text File | 1993-06-12 | 16.8 KB | 369 lines

PLOT Version 3.3 (PLOT33) DOCUMENTATION PART 1. PLOT USER'S GUIDE General Information Running PLOT Application Programming PLOT Commands Pitfalls and Limitations Error Messages PART 2. APPLICATION PROGRAMS BASIC Programs TURBO PASCAL Library FORTRAN Library PART 3. INSTALLATION INSTRUCTIONS Sizing the Memory Map Printer Settings PART 1 USER'S GUIDE General Information This collection of programs contains a graphics system that can produce high resolution graphics on dot matrix printers and other graphic devices. This system consists of three parts: - high level language subprograms that you include in your application programs, - a disk file created by the application program which is used to describe the pictures to be printed, - and low level device drivers that read the file and produce the pictures on whatever sort of hardware you are using. The application program "plots" by writing simple plot commands to a disk file, which is later read and printed by the low level driver. This file is the key to the whole system, because it makes the application program independent of the plotting device and vice versa. It also makes it possible to plot pictures that were created on different computers or to plot the same picture on different types of hardware, such as CRT's and printers. The system contained in this collection has high level subprogram libraries written in BASIC (GRAPH.BAS), Turbo Pascal (GRAF1.PAS and GRAF2.PAS), and FORTRAN (GRAF.FOR). A C library is being debugged. It contains one assembly language device driver, PLOT33.ASM, which will plot on a variety of dot matrix printers. These printers include the Epson MX-80 etc., CItoh Prowriter, Okidata 92, NEC, Gemini-10, Apple Dot Matrix, and IDS printers. PLOT33 lets you treat your printer as if it were a plotter capable of true vector graphics. All future versions of PLOT (3.x) will support the same basic file format and will be compatible with each other. This documentation describes how to get PLOT33 installed, specifies the format for the disk file of plotting vectors (".VEC" files), and gives an overview of the high level language packages. You will probably want to briefly skim over the descriptions below and go right to the Installation section. If you intend to mainly use the programs and subprogram libraries provided, the exact details of the format of the commands in the file are not important. Capabilities PLOT's command set includes instructions for device independent graphics and commands that provide access to the unique capabilities of specific devices. The device independent commands are patterned after a pen plotter's characteristics, with a rudimentary capability for filling areas on raster scan devices. These device independent commands include the capability to move to a point without plotting, to plot points and straight line segments, to change the current color, and fill in a trapezoidal area. More complex areas can be decomposed into simpler regions for filling. The device dependent commands include the ability to plot/print a string using hardware character capabilities. The Upload command can be used to upload the red-green-blue values used for the color table on color graphics terminals (or stipple patterns to be used for "colors" on monochrome devices as in PLOT33). The Erase command will clear the screen, establish the background color, or advance the page, as appropriate for the type of plotter or display. An Output command is used to produce hardcopy output or print the memory map. A general instruction that can be used to extend the command set for any other non-standard command required rounds out the device dependent commands. Bug Fixes and Future Versions The assembly language and BASIC programs in this system have been tested so far on four different computers and six different types of printers. I would appreciate hearing about any problems you have or changes that you make to the program. I am particularly interested in versions for different printers or drivers for other plotting devices such as graphic terminals and plotters. Please send your comments and questions to the author at: Tom Speer 887 Briddlewood Ln. Dayton, Ohio 45430 (513)429-2781 It is important that a common version be maintained that incorporates fixes to all of the bugs and implements the improvements that are of general interest. As mentioned above, all future updates to this version of PLOT will be compatible with the existing plot files and high level software. Future drivers are also planned for creating and interpreting the vector command file on mainframe computers using CALCOMP or Tektronics plotters and terminals. As much as possible, the eXtend command should be used for adding neat new features for your printer or taking advantage of the capabilities of more advanced devices. This will make it possible to maintain the file format as a means of exchanging information without a fatal proliferation of exclusive versions. Acknowledgments I owe a special debt of thanks to all the people that have been my guinea pigs in adding new printers and discovering bugs. Especially Hal Carter for his help and encouragement, Kirk Horton for really wringing out the system in his VLSI applications, and Mike Gingrich for his critiques of the system and documentation. Running PLOT To use PLOT, first create a sequential disk file of plot commands. These are described fully in the next section. Then execute PLOT by typing: PLOT33 ifn [ofn] ifn is the input file name. A file type of .VEC is assumed if no file type is given. [ofn] is an optional output file name. If no output file is given, the output from PLOT will go directly to the printer (CP/M LST: device). If an output file is specified, all of the information normally sent to the printer will be stored in the disk file instead. In this case, no printed output will be produced. PIP or some other utility may be used to print the picture. This option is useful for making multiple copies or for including graphics in the middle of text files. The default output file type is .PLT. Note: Output files are large- typically 40 to 60k. Be sure to leave enough space on the disk for the entire file. Application Programming Application programs "plot" by writing the appropriate plot command to a disk file. This file later becomes PLOT's input file. The plotting area is a square, with the coordinates (0.0,0.0) located at the bottom left corner, and the coordinates (1.0,1.0) located at the upper right corner. These coordinate values are independent of the resolution or aspect ratio of the plotting device. PLOT converts these values to the actual number of rasters (dots) used by the printer to produce a square plot approximately eight inches on a side. All plot commands are written to disk one after the other, with no spaces or delimiting characters between them. Each command consists of an ASCII character followed by the binary data which it requires. Many languages, such as BASIC, insert extraneous characters, such as carriage returns or line feeds, at the end of each block written. Because of this, plotting commands should not be split between blocks, as these extra characters will be interpreted as data in a command. If the extraneous character occupies the position of a command character, however, it can be detected and ignored. The current application programs output plot commands in 128 byte blocks. If a command will not fit in a given block, the block is written to disk, and the next command written in a new block. This ensures that the extraneous characters will fall between commands where PLOT can deal with them. When using fixed length blocks or records, each can be padded with "N"'s to preserve its length before it is written. The recommended command sequence to produce a picture is: 1. Set the color to black or white (color values 127 or 0) for a background. Usually white is used. 2. Erase the picture to initialize the memory map area and establish the background. 3. Set the color value for plotting. Usually black (127) is used. 4. Establish a starting point by using the Move command, plotting a single point, or plotting a line segment using the Draw command. 5. Proceed to create the remainder of the plot. The Increment command is recommended when one line segment is connected to the previous one, as in a curve. 6. Be sure to include an Output command to print the final plot. 7. Use the Quit command to stop plotting. PLOT will terminate automatically at an end-of-file, but with an error message, and without printing the picture. PLOT Commands Each command is of the form: Adata "A" represents the single ASCII character as explained below. "data" represents 0 to 86 bytes of data required for the particular command. Usually this consists of fixed point numbers giving the coordinates of points or ends of line segments. No spaces or delimitating characters are used between fields within a command or between commands. The individual commands are described in Table 1. The data values required for the plot commands are not ASCII character strings. Thus, they cannot be made using normal formatted output of the coordinate variables in the application program. The coordinate values are 16 bit fixed point numbers. These are created in a high level program by multiplying the floating point value (between 0.0 and 1.0) by 32767 and truncating the result to an integer. In BASIC, the MKI$ function can be used to store the data in a string variable, which is then written to the disk file. FORTRAN programmers can simply use unformatted files or convert everything to characters and use A formats. Under PASCAL, the file can be declared to be a FILE OF CHAR and the binary values converted the characters using the CHR function. This does not work well for Turbo Pascal, however, since Turbo places the file size and record length at the head of a FILE OF CHAR. Turbo Pascal users should use TEXT files instead. The different word lengths, internal storage formats, and file structures have to be considered when constructing the command file on mainframes and microcomputers other than CP/M based machines. The ability to structure a file as a byte stream is the basic requirement. The CP/M Dump utility can be used to ensure that the contents of the file are what you expected. The 16 bit data values are stored with the low order byte first (swapped format). This is the standard way of storing words for the 8080 and Z80 processors. In the case of the one byte integer required by the Color command, the first element of the string created by MKI$ should be used, as MKI$ automatically places the bytes in swapped format. Note that because the data values are not ASCII strings, the CP/M TYPE command will not properly display the file at the console. In addition, the [O] option must be specified when using PIP to transfer either the vector command file (.VEC) or the printer (.PLT) file. TABLE 1 PLOT COMMANDS Command Length Name Character Data (bytes) Command Data Description --------------------------------------------------------------- Color C b 2 8 bit integer specifying one of a range of colors. 0 indicates white, 127 indicates black. Draw D X1,Y1, 9 Coordinate pairs for ends of line X2,Y2 segments. Erase E 1 Sets the entire ploting area to the currently selected Color value. Fill F X1,Y1, 11 Coordinate pairs for ends of line X2,Y2,Yf segment and horizontal level (Yf) defines area to be filled in with currently selected color. Incre- I X,Y 5 Coordinate pair for end of line segment. Starting coordinate is l ast point plotted. Move M X,Y 5 Coordinate pair for new "pen" position. No-op N 1 Ignored. Used as space filler in sequence of commands to exactly fill a disk record. Output O 1 Causes current picture to be printed. Point P X,Y 5 Coordinate pair for point to be plotted. Quit Q 1 Commands normal termination of program. String S X,Y, 6 Coordinate pair for start of string to character string to be printed. 86 String MUST end with a Carriage Return. Text T string 2+ String of arbitrary length. String MUST end with a <NULL> (00H) character. Upload U N, 3 N is a 16 bit unsigned integer values to giving the number of values to N+3 follow. Values specify the basis for creating new "colors". eXtend X N, 3 N is a 16 bit unsigned integer values to giving the number of values to N+3 follow. Values are Nbytes of whatever data is necessary. The following sections describe the way in which the commands have been implemented in PLOT Version 3.3 (PLOT33). Other drivers may not implement them in exactly the same way, but the general sense should be preserved. Colors are simulated in PLOT33 by using stipple patterns. These patterns apply to all points, lines, and filled areas. These patterns are based on 8 dot by 8 dot cells that tile the entire picture area. Imagine cutting each figure out of a sheet entirely covered with the desired pattern and then pasting it on the plot in progress. This gives a general idea of the way in which the patterns work. Three different methods of generating the patterns are used. Each method trades off the memory required to store the basic patterns with the ability to specify exactly what the pattern will look like. When a Color command is given, all subsequent plotting will be done with that "color", or pattern, until it is changed with another Color command. The Color command simply acts as a selector to pick one of a number of colors or patterns that are currently available. A color code of 0 corresponds to white. Lines and filled areas plotted with this color will absolutely erase any dots that were previously plotted. Color codes from 1 through 48 will produce cross hatched patterns that generate checkered areas and other distictive patterns. Codes from 49 to 63 correspond to 15 special patterns that can be programmed to exactly match any desired pattern based on the 8 x 8 dot cells. Codes from 64 through 127 are generated using an ordered dither matrix, in which each succeeding code is the same as the previous one, except for one more dot per cell being plotted. These are currently set to generate a range of shades of gray. All of these patterns can be changed under the control of the application program by using the Upload command. Each dot is added to the memory map by OR'ing it with the dots previously plotted. Each subsequent figure does not totally obscure the existing picture. For example, suppose that a gray shade is being used that consists of every other dot being plotted. The dots that are not plotted will not cause the existing dots to be set to white if they were previously plotted. Negative color values (-1 to -127) will use the same pattern as their positive counterpart, but will be XOR'ed with the existing picture. This means that the figure will be plotted black on white or white on black, depending on what the existing background is. Plotting the same figure twice with a negative color value will have no net effect on the picture. Filling the whole picture with -127 (negative black) will have an effect like making a photographic negative.