home *** CD-ROM | disk | FTP | other *** search
/ Oakland CPM Archive / oakcpm.iso / cpm / diskplot / diskplot.lbr / DISKPLOT.DQC / DISKPLOT.DOC
Encoding:
Text File  |  1985-06-17  |  8.0 KB  |  191 lines
  1.                                DISKPLOT
  2.  
  3. DISKPLOT was first published in the DEC 83 BYTE in an article by Dan 
  4. Rollins.  Rollins wrote the routines for TRS-80 Disk-BASIC and a IDS 
  5. Paper Tiger printer.  I took the basic programs and re-wrote some of 
  6. the machine dependant parts for CP/M MBASIC and a generic printer.  
  7.  
  8. Files included are:
  9.      DISKPLOT.BAS   the diskplot routines.
  10.      GENDRAGN.BAS   Rollins original program as published above.
  11.      MANDALA.BAS    Plots polygons with all points connected.
  12.      SINEWAVE.BAS   Simple example of a f(x) plot.
  13.      DISKPLOT.DOC   this file
  14.      DISKPLOT.MSG   Messages I've received on diskplot.
  15.  
  16. GENDRAGN, MANDALA, and SINEWAVE all require DISKPLOT.BAS to be merged 
  17. in to run.
  18.  
  19.                          GENERAL DOCUMENTATION
  20.  
  21. As one can easily see, large plots with many dots would require mucho 
  22. memory if one wnated to hold the entire plot in memory at one time.  
  23. What Rollins did was to develop a method to hold the plot on disk, 
  24. instead of memory, so that one is limited now only by disk space.  I 
  25. recommend the BYTE article ("A Dragon meets a Tiger") for a more 
  26. indepth discussion of the dragon curve and the diskplot routines.
  27.  
  28. Of course, some of the picture must be held in memory as the plot in 
  29. generated.  The part of the picture in memory can be considered a 
  30. "window" to the entire plot held on disk.  In some cases, for smaller 
  31. plots and/or for programs that don't require much room, (leaving more 
  32. room for the plot) the entire picture can be held in memory at one 
  33. time.
  34.  
  35. The plot is made of of "dots" - horizontal and vertical.  The width is 
  36. divided up into 128 dot "sectors", cooresponding to the normal string 
  37. length in MBASIC.  DISKPLOT will allocate as many sectors across as 
  38. necessary.  The vertical length is divided into "lines" - the number of 
  39. dots per line is dependant on the number of dots per pass your printer 
  40. will print.  (Mine prints 7 per pass.)  Each line is placed in a buffer 
  41. in memory when dots are to be plotted in that line.  The more lines 
  42. that can be held in memory (that is buffers) at one time the better.  
  43. Minimum number of lines held in memory is 3 (caused by the way the 
  44. program is written - read the article to see why.)
  45.  
  46. Summary of DISKPLOT routines:
  47.  
  48.      1.  Open file.      requires:  Maximum horizontal value
  49.          (GOSUB 3000)               Maximum vertical value
  50.                                     Number of buffers to use
  51.                                     filename to store plot
  52.  
  53.           This routine must be called first.  Note the the size of the 
  54. plot must be known before any plotting is done.  X runs from 0 up, left 
  55. to right; Y runs from 0 up, top to bottom.  One can give diskplot the 
  56. numbers to use for max X and Y and it won't ask for them.  One can also 
  57. have diskplot calculate the maximum number of buffers to use.  (A 
  58. danger in this - diskplot will try is use all available memory for the 
  59. buffers, leaving little for additional programming variable space.)
  60.  
  61.      2.  Plot Point. (GOSUB 1500)  requires:  X,Y
  62.  
  63.           turns the point X,Y on.
  64.  
  65.      3.  Plot Line.  (GOSUB 1000)  requires: (x1,y1) and (x2,y2)
  66.  
  67.           turns all points between (x1,y1) and (x2,y2) on.  Upon 
  68. return, (x1,y1) will have the value of (x2,y2) making the creation of 
  69. segmented lines easy.
  70.  
  71.      4.  Close file. (GOSUB 4000) requires:  nothing
  72.  
  73.      5.  Print file. (GOSUB 5000) requires:  filename to print
  74.                                              number of sectors across
  75.  
  76.           both required variables may be passed.
  77.  
  78. MACHINE DEPENDANCIES
  79.  
  80.      Terminal:  the terminal control codes for clear screen and cursor 
  81. positioning is used in a minor way.  Although not necessary, it does 
  82. make the status messages "neat".
  83.  
  84.      Printer:  (all required)  dot-addressable printer, with least 
  85. significant bit at top of graphics "line".  One must know, and patch 
  86. into diskplot, the printer control codes for entering graphics, exiting 
  87. graphics, and the code to do a graphics linefeed (so that the next 
  88. graphics pass just lines up with the previous pass).  Code is also 
  89. included if the graphics escape character needs to handled differently.  
  90. [On the IDS, ASCII <3> signals to go into graphics; <3>, <14> for a 
  91. graphics linefeed; <3>, <2> to exit graphics; and <3>, <3> means print 
  92. a graphics <3>.]
  93.  
  94.      System:  Must be able to print (i.e. pass through from MBASIC to 
  95. the printer) all graphics chars unchanged.  If your BIOS mucks up some 
  96. of the control characters, try setting all MSB's, providing of course 
  97. that your printer ignores the MSB!  That way ASIC code characters 0 
  98. through 32 get sent as 127 through 159.
  99.  
  100. DISKPLOT Variable Usage
  101. by Dan Rollins as in the Dec 83 BYTE
  102.  
  103. the following variables are used by diskplot:
  104.  
  105. P1       Record in buffer 1 (lowest in memory)
  106. P2       physical file sector # (used in GET and PUT)
  107. P3       current Record (Y/P12)
  108. P4       current bit to set
  109. P5       highest RECORD on disk
  110. P6       total number of BUFFERS (is forced to be odd)
  111. P7       Buffer currently being accessed
  112. P8       middle buffer (INT(p6/2)+1)
  113. P9       total vertical dots (maximum Y)
  114. P10      total horizontal dots (maximum X)
  115. P11      number of physical records per Buffer (line)
  116. P12      number of vertical dots per buffer (dots per line)
  117.        
  118. PH       number of string in buffer
  119. PL       X offset within buffer string
  120.               (also length of string to LPRINT)
  121.        
  122. PP       current value of byte to alter
  123. PQ       temporary value, counter
  124. PI       temporary value, counter
  125. PJ       temporary value, counter
  126. PS       sector to start clearing file
  127. PZ       priming variable (=1 on first call to 1500)
  128.        
  129. X        horizontal ordinate to plot
  130. Y        vertical ordinate to plot
  131. X1,Y1    starting point of line to draw
  132. X2,Y2    ending point of line to draw
  133.        
  134. PD(n)    value to OR for setting dot n (0 is top)
  135. PW(n,1)  flag indicates that a Buffer has been changed
  136.  
  137. PB$(n,1) Buffer storage strings (128 char length)
  138. PC$      128 graphical blanks CHR$(0)
  139. PE$      graphics escape CHR$(3)
  140. PF$      disk filename for plotter image
  141. PQ$      priming flag (="O" for Overlay option)
  142. PR$      FIELDed string (funnels all disk data)
  143. PU$      PRINT USING image for plotting data
  144.  
  145. L1       Distance of long-axis
  146. L2       Distance of short-axis
  147. L3-6     horizontal and vertical steps (1,-1 or 0)
  148. L7       duty master (for determining ratio)
  149. L8       temporary value, long-axis counter
  150.  
  151. CS$      Clear Screen
  152. CPn$     Postion cursor to n'th line
  153.  
  154. Other notes:
  155.  
  156. One may overlay old file plots with new information, provided both use 
  157. the same number of sectors per line.  This is good for plotting on a 
  158. predefined grid.
  159.  
  160. If, upon entering diskplot and opening a file, P9 and/or P10 are zero, 
  161. diskplot will ask for the size of the plot.  Likewise upon printing a file, 
  162. diskplot will ask for the filename and sectors per line if PF$ and P11 are 
  163. <null> and 0 respectively.
  164.  
  165. Several lines in diskplot are commented out for speed reasons.  If you 
  166. want to see how diskplot is working, at the expense of some speed, 
  167. remove the comment marks.
  168.  
  169. diskplot can be asked to calculate the number of buffers.  (The number 
  170. of graphics lines to be held in memory at one time.)  Note that all 
  171. available memory will be grabbed so do not use this option if many 
  172. program variable are still to be defined.
  173.  
  174. The three example programs show various ways of using diskplot.  
  175. GENDRAGN calculated all of the points necessary and the size of the 
  176. dragon curve BEFORE diskplot is ever called.  MANDALA uses very few 
  177. variables, so the lines are calculated as needed and immediately 
  178. plotted.  SINWAVE is an example of what can be done to plot a function 
  179. of x.
  180.  
  181. diskplot.msg contains more information in the form of messages sent and 
  182. received.
  183.  
  184. Additional routines, comments, bug reports, etc. are welcome.  I 
  185. reserve the right to ignore any or all of the same.  This is a hackers 
  186. program!
  187.  
  188. Bob Bloom
  189. 5 McCord Drive
  190. Newark, DE  19713
  191.