home *** CD-ROM | disk | FTP | other *** search
/ CP/M / CPM_CDROM.iso / zsys / znode-12 / i / plot33.lbr / PLOT-DOC.2Z / PLOT-DOC.2
Encoding:
Text File  |  1993-06-12  |  20.4 KB  |  406 lines

  1.  
  2. The String command is used to mix printed characters and 
  3. graphics. The characters are printed using the printer's normal 
  4. character set. No facility is provided in PLOT33 to send <ESC> 
  5. codes or control characters to the printer to change character 
  6. sizes or font styles. The string is printed starting near the 
  7. coordinates given in the command. The exact position will vary, 
  8. but the first character will cover the coordinate location. The 
  9. ambiguity comes from the fact that most printers can only print 
  10. characters at their normal location on the page, and can't use 
  11. graphics commands to position the characters at any arbitrary 
  12. place on the line. In addition, a printed character can't be part 
  13. on one line of print and part on another. Therefore, PLOT33 
  14. computes the closest character location to the desired 
  15. coordinates and begins the string there.
  16.  
  17. The Text command will immediately send a text string to the 
  18. printer when the command is encountered. This is quite different 
  19. from the String command, because the text is not put in the 
  20. memory map and is not part of the picture. This command is useful 
  21. for positioning the plot on the page, for printing titles and 
  22. headers, and for advancing to the next page after the plot is 
  23. printed. Any ASCII characters may be included in the string, 
  24. including control codes, escape sequences, carriage returns, and 
  25. linefeeds. The only exception is the null character, 00H, which 
  26. is used to signal the end of the string. The string may be of any 
  27. length. This makes it a convenient way of imbedding a figure in 
  28. the middle of a document, since all of the text above the figure 
  29. can be included in one Text command, as can all of the text after 
  30. the plot. Any text to be included in the plotting area itself 
  31. must be entered one line at a time with the String command.
  32.  
  33. Upload Command
  34.  
  35. The Upload command deserves some special attention, because it is 
  36. the least standard of all of the commands currently implemented.  
  37. Most dot matrix printers can, of course, only print in black. To 
  38. give these printers a "color" capability, different patterns have 
  39. been programmed to produce shades of gray and distinctive cross 
  40. hatched patterns. The cross hatched patterns are intended to be 
  41. used for bar charts, dotted and dashed lines, etc. The shades are 
  42. the closest that PLOT33 can come to true colors. The special 
  43. patterns are very useful for matching patterns produced by other 
  44. systems, and for anything that just can't be done with the other 
  45. two methods. The Color command acts as a selector to choose 
  46. between the pre-defined patterns. The Upload command is only 
  47. needed if the default patterns are not capable of producing the 
  48. desired effect. It will redefine the patterns from which the 
  49. Color command can select.
  50.  
  51. The cross hatched patterns are based on seven bytes that provide 
  52. the basic patterns in both the vertical and horizontal directions 
  53. for each cell. One byte from the seven is selected as the X 
  54. pattern and one byte from the seven is selected as the Y pattern. 
  55. The X pattern is extended vertically throughout the cell, and the 
  56. Y pattern is extended horizontally throughout the cell. The two 
  57. patterns are reversed (XOR'ed) where they cross. The effect is 
  58. much like weaving a plaid material. The selection of the bytes 
  59. for the X and Y patterns is made by the Color code. The lower 
  60. three bytes of the Color value select the X byte and the next 
  61. three bytes select the Y byte. The best way to determine the 
  62. exact appearance of each pattern is to experiment by filling 
  63. blocks with different patterns.
  64.  
  65. If the existing patterns are not acceptable, new ones can be 
  66. Uploaded. Set the number field, N, to 07H. The next seven bytes 
  67. will be the bytes that form the basis for the patterns. Each bit 
  68. corresponds to a dot in the pattern. A byte of 07H for the X 
  69. pattern would produce the pattern .....*** . If an F0H is used 
  70. for the Y pattern, the final cell will look like:
  71.  
  72.                        *****...
  73.                        *****...
  74.                        *****...
  75.                        *****...
  76.                        .....***
  77.                        .....***
  78.                        .....***
  79.                        .....***
  80.  
  81. The second type of pattern, used for the 15 special patterns, is 
  82. specified by giving the 8 bytes that produce the pattern. Thus, 
  83. the sequence 00H 00H 99H 00H 00H 99H 00H 00H will produce the 
  84. pattern:
  85.  
  86.                        ..*..*..
  87.                        ........
  88.                        ........
  89.                        ..*..*..
  90.                        ..*..*..
  91.                        ........
  92.                        ........
  93.                        ..*..*..
  94.  
  95. These patterns are uploaded by specifying 120 for N followed by 
  96. the 120 bytes that define all 15 of the special patterns. No 
  97. facility is provided for just uploading one set of 8 bytes.
  98.  
  99. The other method for producing patterns for "colors" is an eight 
  100. by eight byte dither matrix. In this method, each byte in the 
  101. matrix corresponds to one dot in the eight by eight dot cell.  
  102. These cells tile the picture plane, as before. Color code values 
  103. from 64 to 127 are used to select the 64 patterns created by the 
  104. dither matrix. Each element of the matrix is assigned a value 
  105. from 63 to 126. If the Color value is greater than the value in 
  106. the matrix corresponding to a given dot, that dot is plotted.  
  107. Thus, 127 is greater than all of the elements, and all dots in 
  108. the matrix will be plotted, producing black. If each element of 
  109. the matrix is assigned a different value, then a unique pattern 
  110. will be associated with each Color value. For example, if the 
  111. Color code is 64, only the element with a value of 63 will 
  112. produce a dot. If the Color value is 65, those elements with 63 
  113. and 64 will produce dots. As the Color code is increased, and 
  114. figures are plotted, another dot in the "tile" has the potential 
  115. for being plotted.
  116.  
  117. The existing arrangement of values in the dither matrix is 
  118. designed to produce shades of gray with a minimum appearance of 
  119. organized patterns. This matrix came from Foley and Van Dam's 
  120. "Fundamentals of Interactive Computer Graphics". A common use of 
  121. the Upload command is to change the matrix to provide diagonal 
  122. patterns for shading areas. This would produce a pattern that 
  123. looks like (for four cells):
  124.  
  125.                        ////
  126.                        ////
  127.                        ////
  128.                        ////
  129.  
  130. To design an Upload sequence for a given pattern, lay out a 
  131. matrix representing a single cell. Start with 63 and place the 
  132. numbers in the matrix in the pattern desired. For example, a cell 
  133. from the diagonal pattern above could be created from the matrix:
  134.  
  135.                    63 111  85 103  75 115  93  95
  136.                   112  64 104  86 116  76  96  94
  137.                    79 105  65 117  87  97  77 121
  138.                   106  80 118  66  98  88 122  78
  139.                    71 119  81  99  67 123  89 107
  140.                   120  72 100  82 124  68 108  90
  141.                    91 101  73 125  83 109  69 113
  142.                   102  92 126  74 110  84 114  70
  143.  
  144. To see the pattern, look at the matrix part way through its 
  145. construction:
  146.  
  147.                     63              75
  148.                        64              76
  149.                            65              77
  150.                                66              78
  151.                    71              67
  152.                        72              68
  153.                            73              69
  154.                                74              70
  155.  
  156. For this matrix, the Color code 79 will result in all of the 
  157. above points being plotted in any filled in area, and the 
  158. diagonal pattern will emerge.
  159.  
  160. Once the matrix is constructed, the Upload command to load it is 
  161. formed by an ASCII "U" followed by 40H, 00H to indicate 64 bytes 
  162. to come, and finally 03H, 6FH, etc., the bytes of the matrix. The 
  163. matrix is read in one row after another (the [1,1] element 
  164. followed by the [1,2] element, ... , to the [1,8] element, then 
  165. the [2,1] element, ... ). All of the matrix values are binary 8 
  166. bit values. In BASIC, use the MKI$ function to convert the 
  167. integers to strings, then use the first character.
  168.  
  169. To summarize the Upload command: The Color codes from 1 to 48 are 
  170. produced by cross-hatched patterns based on eight pattern bytes. 
  171. These can by Uploaded by a "U" 08H 00H followed by eight new 
  172. pattern bytes. The Color codes from 49 through 63 are Uploaded by 
  173. a "U" 78H 00H and the 120 bytes that define the 15 cell patterns. 
  174. The Color codes from 64 through 127 are produced by a dither 
  175. matrix. This is created by assigning elements of an eight by 
  176. eight matrix the values 63 through 126. The matrix is Uploaded by 
  177. a "U" 40H 00H followed by the 64 elements in row major order.
  178.  
  179. Pitfalls and Limitations
  180.  
  181. This section amplifies the more subtle points and limitaions of 
  182. PLOT33's commands.
  183.  
  184. The valid range for coordinate values is 0 to 1. This corresponds 
  185. to binary integer values from 0 to 32767. As each point is 
  186. plotted, a check is made to insure that the coordinate is within 
  187. the memory map. If it is not, the point is not plotted. This is 
  188. mainly to keep the program from running amok and writing over 
  189. parts of memory that are not part of the memory map of the 
  190. picture. This is not intended to be a form of windowing. If you 
  191. want to zoom in on a part of a larger picture, the picture should 
  192. be clipped by the application program. Note also, that most high 
  193. level languages will not deal with positive integers that are 
  194. larger than 32767, as these larger numbers represent negative 
  195. integers.
  196.  
  197. In contrast to the coordinate values used for all of the graphic 
  198. commands, any coordinate value outside the picture used to 
  199. indicate the start of printing a string will be set to zero. This 
  200. is intended to make the String command act as much as possible 
  201. like a normal printer. When the string goes off of the right hand 
  202. side of the plot, the X coordinate for the next character will be 
  203. set to zero and the string will wrap around - just like a 
  204. carriage return without a linefeed. All characters that attempt 
  205. to be printed above or below the plot will be printed on the 
  206. bottom line.
  207.  
  208. String has a few other points of interest. Only printable 
  209. characters should be used. Control characters and escape codes 
  210. will occupy their respective positions in the memory map but will 
  211. not be printed. This will cause the rest of the line to be 
  212. shifted to the left and destroy its alignment with the rest of 
  213. the page. Also, the character pitch must agree with the character 
  214. width set at assembly time, or the alignment will be affected.
  215.  
  216. The coordinates for the start of the string are truncated to the 
  217. nearest multiple of the size of the character. Thus the specified 
  218. point will be within the first character, but the character will 
  219. not be centered or aligned with the given coordinate position.  
  220. This was done because most printers insist that the printed 
  221. characters occupy these locations, and PLOT33 has to respect this 
  222. or the alignment of the rest of the line will again be affected.
  223.  
  224. PLOT33 prints the strings, it does not plot them as line 
  225. segments. Because of this, a printed character will absolutely 
  226. occupy its location on the plot, and any overlapping lines or 
  227. points will not appear. If a character is printed on a patterned 
  228. background, it will appear as if it were in a white box the size 
  229. of the character. If true graphic characters are desired, they 
  230. must be drawn by the application program as line segments. An 
  231. additional implication of the printed characters is is their size 
  232. relative to the graphic bit images that are sent to the printer.  
  233. The graphics are printed in "strokes" that are one dot wide and 
  234. seven dots high. Many printed characters are higher than seven 
  235. dots especially those that have descenders. A printed character 
  236. occupies a space that is seven dots high in the memory map. Thus, 
  237. the top line of capital letters and the lower case descenders can 
  238. overlap the graphics area above and below the nominal area of a 
  239. printed character. The distance that the paper is advanced 
  240. between lines is dictated by the height of a graphic "stroke", 
  241. and is nearly always smaller than the normal single spaced 
  242. distance. Printed lines must therefore be "double spaced" by 
  243. specifying starting coordinates that are well separated 
  244. vertically. This is a device dependent aspect, and a litle 
  245. experimentation may be needed to achieve a good appearance.
  246.  
  247. The last caution about the String command is that it MUST end 
  248. with a carriage return character. This signals the end of the 
  249. string, and without it, the program will continue to read the 
  250. rest of the input file as part of the string until it either 
  251. encounters a carriage return or the end of the file. The String 
  252. and Text commands are the only commands with this potential, as 
  253. all of the others have a definite number of bytes of data. All 
  254. these caveats regarding the String command may sound a little 
  255. gruesome, but it is really not much different from normal 
  256. printing. If its limitations are too inhibiting, you must draw 
  257. the characters instead of printing them.
  258.  
  259. The Text command is output to the printer at a different time 
  260. than any of the other commands. Its contents are sent immediately 
  261. when it is read, whereas all other commands cause their actions 
  262. to be stored in the memory map and only printed when an Output 
  263. command is received. Thus, it cannot be used to send escape 
  264. sequences to the printer in the middle of the plot. Whether 
  265. graphics commands (such as Draw, Fill, etc.) preceed or follow a 
  266. Text command is immaterial, since these commands affect the 
  267. memory map at the time that they are read and not the printer.  
  268. What really matters is the position of a Text command relative to 
  269. the Output commands in the file.
  270.  
  271. Like the carriage return at the end of the String command, 
  272. omitting the 0 byte at the end of the Text command can have 
  273. disasterous consequences.
  274.  
  275. The line spacing used in the Text command is different from the 
  276. line spacing in the plot itself. The Output command sets the line 
  277. spacing to be appropriate for graphics, and then resets it to the 
  278. normal text single spacing when done. If a uniform appearance is 
  279. required throughout, each Text command should contain the control 
  280. characters or escape sequences required to set the line spacing 
  281. to match that used in the plot itself.
  282.  
  283. The final consequence of the line spacing is that the form length 
  284. and the top of form position set in the printer will be wrong.  
  285. The Output command will result in the printer being positioned at 
  286. the bottom of the plot. This is to allow several plots to be 
  287. printed sequentially as one continuous picture without any gaps 
  288. between them. In order to advance to the top of the next page, 
  289. the Text command must be used to issue the correct number of line 
  290. feeds and then tell the printer to reset the top of form.
  291.  
  292. The Output command does not erase the existing picture. Thus 
  293. several copies of the same plot can be produced by repeating the 
  294. command. In addition, this allows building up a picture in stages 
  295. and printing it at each stage. To print one plot and start anew, 
  296. you must Output the first, set the Color to white, Erase the 
  297. page, and then set the Color back to the plotting color or 
  298. pattern. The program does not automatically execute an Output 
  299. command at the end-of-file or when Quitting. You must include an 
  300. Output command to get any output at all. This philosophy is to 
  301. accomodate those devices, like graphic terminals, that display 
  302. the plot as it is being made, and only need an Output command for 
  303. hardcopy.
  304.  
  305. Error Messages
  306.  
  307. Disk is Full.
  308.  
  309. Fatal error. No more room exists on the designated disk for 
  310. writing the output file. Ensure that enough room is available and 
  311. run PLOT again. Note that a different disk drive may be specified 
  312. for the output file than the one used for the input file. If disk 
  313. space is not available, run PLOT in the direct printing mode.
  314.  
  315. Any remnant of the output file may be printed, but the last 
  316. record will probably contain an incomplete graphic output 
  317. sequence. The printer will expect to receive additional bytes of 
  318. graphics. This will produce a swath of dots with a random 
  319. apperance, unless nulls are sent. In addition, the printer line 
  320. spacing will remain set for the size of the graphic output.
  321.  
  322. End of File.
  323.  
  324. Fatal error. The end of the input file was encountered when PLOT 
  325. attempted to read the next record. Add a Quit command for the 
  326. normal termination of the program.
  327.  
  328. File not Found.
  329.  
  330. Fatal error. The file name given for the input file could not be 
  331. found on the disk. Make sure that the spelling was correct, that 
  332. the proper drive is specified in the file name, or the right 
  333. drive is logged in as the default drive.
  334.  
  335. No Directory Space Available.
  336.  
  337. Fatal error. When PLOT tried to make a new output file, there was 
  338. no more room in the disk directory. Erase a file, use a different 
  339. diskette, or run PLOT in the direct printing mode, without making 
  340. an output file.
  341.  
  342. No File Specified.
  343.  
  344. Fatal error. No input file name was given. PLOT will not prompt 
  345. you for a file name, and there is no interactive mode for 
  346. entering commands. Create an input file and try again.
  347.  
  348. Undefined Command Character Encountered.
  349.  
  350. Warning error. When PLOT attempted to interpret the ASCII letter 
  351. portion of a command, a character was found which did not 
  352. correspond to one of the established commands. PLOT ignores these 
  353. characters and attempts to interpret the next character as a 
  354. command. If a command does not have the proper number of data 
  355. bytes, or if an extraneous character is inserted in the middle of 
  356. the data portion of a command, the rest of the file will be out 
  357. of sequence. Eventually, PLOT should get back in step with the 
  358. command stream, but the overall effects are unpredictable.
  359.  
  360. PART 2. APPLICATION PROGRAMS
  361.  
  362. BASIC Programs
  363.  
  364. Several sample BASIC application programs are included as 
  365. examples of possible implementations. BASIC was selected because 
  366. it is almost universally available on CP/M systems and is a good 
  367. language for quick one-of-a-kind plots. The first file is 
  368. GRAPH.BAS. This file contains a plotting "library" of routines 
  369. that give direct access to the low level commands used by PLOT. 
  370. It also includes routines for scaling, and for drawing a complete 
  371. graph with labeled axes. This file is used by the other programs. 
  372. For each command that can be written to the .VEC file, there is a 
  373. corresponding subroutine in GRAPH.BAS.
  374.  
  375. To use these subroutines, first load the appropriate variables 
  376. with the necessary data. For example, to draw a line segment, set 
  377. X1 and Y1 to the starting coordinates, and set X2 and Y2 to the 
  378. ending coordinates (remember that all coordinate values are 
  379. between 0.0 and 1.0). Then GOSUB to the subroutine for that 
  380. function, in this case the DRAW LINE SEGMENT routine, which is 
  381. currently line 177. That's all that is required. Drawing axes or 
  382. graphs is done the same way. Set the required values and GOSUB to 
  383. the appropriate routine. All of the variables are documented in 
  384. the REM statements at the top of the file, and a sample plot is 
  385. depicted, followed by the settings that would produce it. The 
  386. BASIC package automatically issues the commands to initialize the 
  387. plotting area, so you can start plotting immediately when the the 
  388. application part of the program starts executing. End the plot by 
  389. calling the QUIT PLOTTING routine, at line 200. This will 
  390. automatically add the commands to print the picture and close the 
  391. file.
  392.  
  393. Four statement functions are provided to make it easy to scale 
  394. your data and compute plotting coordinates. Functions RX and RY 
  395. will convert your "real world" values to X and Y coordinates for 
  396. plotting. Functions UX and UY do just the opposite, converting 
  397. coordinates on the page to the equivalent coordinates in the user 
  398. defined plane. These functions require that you have established 
  399. the margins, etc. as if you were plotting a graph. The default 
  400. values for these settings will result in the conversion functions 
  401. simply returning the same value as their input. Note that 
  402. although the margins are useful for confining the plotting to one 
  403. section of the page, no clipping is done to insure that all of 
  404. the points plotted are indeed confined to that area.
  405.  
  406.