home *** CD-ROM | disk | FTP | other *** search
/ Crawly Crypt Collection 1 / crawlyvol1.bin / graphics / pearl / pearle.dok < prev    next >
Text File  |  1987-09-23  |  10KB  |  256 lines
  1.             PEARLE.PRG
  2.  
  3.    PEARLE.PRG renders 3-dimensional scenes in a world of reflective and 
  4. refractive spheres, using ray tracing techniques. Movies formed from
  5. sequences of frames can be generated, showing reflective balls linked and 
  6. bouncing in a gravitational field. They resemble a string of bouncing pearles
  7. -- hence the name.
  8.  
  9.    The amount of computation required to produce one ray traced image on
  10. an ST is enormous -- it is measured in hours. To display animated movies,
  11. images must be precomputed in (overnight) batch runs. PEARLE provides the 
  12. ability generate sequences of images on disk in Degas PI1 format, for later 
  13. replay by BLASTRAM.TTP (also included).
  14.  
  15.    PEARLE.PRG generates a low resolution approximation of each picture first,
  16. followed by refinement to successively higher resolutions. In this way, 
  17. a rough image is seen quickly for (somewhat) interactive debug. The size, 
  18. position, velocity and optical properties of the balls in the scenes are 
  19. specified numerically in the initialization file PEARLE.IN. Scenes can be 
  20. changed without recompilation of PEARL.PRG. 
  21.  
  22.    The ray tracing heart of PEARLE was taken from net.sources, documented
  23. Fredrich Knauss of University of California, San Diego. I've ported it to 
  24. the ST, added animation, (primitive) color, and the various other features
  25. you see here. I place PEARLE in the public domain, for non-comercial use only.
  26.  
  27.    PEARLE.PRG runs only on a color ST in low resolution. 1 Meg is required 
  28. if resolutions greater than one ray per pixel or replaying movies from RAM 
  29. is desired. Operation with only 512K will produced slightly aliased pictures
  30. (one ray per pixel) which can be displayed staticaly, slowly from floppy, 
  31. or from hard disk (if you have a disk blaster program).
  32.  
  33.    The rest of this document contains sections entitled Getting Started, 
  34. Configuration File Format, and Checkpointing. The sources are available 
  35. upon request. With enough interest I could post them.
  36.  
  37.  
  38.  
  39.             GETTING STARTED
  40.  
  41.    The screen must be set to low resolution mode. Once started, type '?' for 
  42. help. Keys 'r' reads and 'w' writes the current screen using the current 
  43. disk file, whose name is displayed in the upper left corner of the screen.
  44. Key 'e' exits. The average number of rays shot through each pixel
  45. is also displayed in the margin and updated as the computation develops.
  46.  
  47.    After unpacking PEARLE, the first logical thing to do is to start it up 
  48. with configuration file PEARLE.IN supplied.  After a few minutes, you'll see 
  49. the resolution increasing. You might wait 1 to 4 hours to get complete 
  50. development, but if you get bored, hit the 'r' key. This will read the one 
  51. pre-computed picture PEARL001.PI1 which came in the "arc".
  52.  
  53.    Now put PEARLE aside until you are willing to dedicate about 6 hours of
  54. the ST for making a movie. The configuration file PEARLE.IN will also do
  55. that. When done, you will find the movie in a sequence of disk files
  56. named PEARLxxx.PI1 . Play these using BLASTRAM.TTP, supplying the argument
  57. PEARL in the dialog box. With BLASTRAM running, type '?' for help. 
  58.  
  59.    The configuration file PEARLE.IN can be modified to give different 
  60. initial ball positions, velocities and optical properties, as well as varying
  61. lighting and viewing perspectives, picture resolution, and gravity.
  62.  
  63.  
  64.  
  65.  
  66.             CONFIGURATION FILE FORMAT
  67.  
  68.  
  69.    The following section discusses the format of the configuration file,
  70. PEARL.IN, which is performed line at a time at startup. The character in 
  71. column 1 specifies the meaning of the rest of each line. Lines may be up 
  72. to 200 characters long. Lines beginning with whitespace are comments. 
  73. The following other formats are supported:
  74.  
  75.  
  76.  
  77.      - - - 'p' Format: - - -
  78.  
  79. specifies the physical size and velocity of a ball. There are 7 properties 
  80. required for each ball, and they must be specified on one line in the 
  81. following order: 
  82.  
  83.  (1) x coordinate of center        (2) x velocity
  84.  (3) y coordinate            (4) y velocity   
  85.  (5) z coordinate            (6) z velocity
  86.  (7) radius
  87.  
  88. Some Notes:
  89.  A) In the coordinate system used, Y is upward, X is to the right, and Z 
  90.     is depth.
  91.  B) Balls will bounce off the floor (the plane Y == 0) and an invisible 
  92.     viewing port (the plane Z==0). Be sure to start them so that all portions 
  93.     of the ball are above the floor and farther away than the viewing port.
  94.  C) If balls start out overlapping, they will stick together.
  95.     This turned out to be a serendipitous bug in the bounce algorithm.
  96.  D) The current version is compiled for up to 15 balls maximum.
  97.  
  98.    The first p-format statement in the file defines the "first" ball PEARLE 
  99. knows about, the second the second and so on. Here are 6 balls which
  100. form an interesting scene:
  101.  
  102.   (1)    (2)    (3)    (4)   (5)    (6) (7)      (see (1)-(7) above)
  103. p 195.0,-20,    130.0, 0,    250.0, 10,    30.0     these are the 4 linked balls:
  104. p 150.0, -5,     100.0, 20,   250.0, 10, 30.0         "
  105. p 105.0,  5,    70.0,  20,   250.0,-20, 30.0         "
  106. p 60.0,  20,    40.0,  0,    250.0,-20, 30.0         "
  107. p  0.0, -10,    300.0, 20,   600.0, 0,    300.0    this is the big ball
  108. p 200.0,  2,     50.0,  5,   60.0,30,   50.0    a medium size (lone) ball
  109.  
  110.  
  111.  
  112.  
  113.      - - - 'o' Format: - - - 
  114.  
  115. specifies the optical properties of a ball. The following 8 properties 
  116. must be put on one line:
  117.  
  118.  (1) index of refraction
  119.  
  120.  (2) amount of refraction
  121.  (3) amount of reflection
  122.  (4) amount of diffuse light (omnidirectional)
  123.  (5) amount of ambient light (from light source)
  124.  
  125.  (6) surface color redness
  126.  (7) surface color greenness
  127.  (8) surface color blueness
  128.  
  129.  
  130. Some notes are in order to make realistic objects:
  131.  A) All parameters should be positive or zero.
  132.  B) Items (2) through (5) should sum to less than 1.0
  133.  C) Surface colors (6) through (8) modulate the affect the diffuse and ambient
  134.     reflective properties (4) and (5). None should be greater than 1.0 .
  135.  C) Due to the size of the ST's color palette, surface color items (6) 
  136.     through (8) are constrained to be patterns corresponding to one of the 
  137.     following three colors:
  138.  
  139.         white:        (6) == (7) == (8) == 1.0
  140.         red:        (6) == (7) == 1.0, (8) == 0.0
  141.         blue:        (6) == 0.0, (7) == (8) == 1.0
  142.  
  143.  
  144.    The i'th 'o' Format line refers to the same ball as the i'th 'p' Format line.
  145. Here are the optical properties for the scene:
  146.  
  147.   (1)  (2)  (3)  (4)  (5)    (6) (7) (8)
  148. o 0.0, 0.0, 0.3, 0.6, 0.1,   1.0,0.0,0.0   diffuse red, somewhat reflective
  149. o 0.0, 0.0, 0.6, 0.3, 0.1,   1.0,1.0,1.0   reflective, somewhat white
  150. o 0.0, 0.0, 0.9, 0.0, 0.1,   1.0,1.0,1.0   reflective, some ambient
  151. o 0.0, 0.0, 0.0, 0.8, 0.2,   1.0,0.0,0.0   diffuse red, some ambient
  152. o 0.0, 0.0, 0.7, 0.1, 0.2,   1.0,1.0,1.0   reflective and ambient (the big one)
  153. o 1.6, 0.8, 0.0, 0.0, 0.2,   1.0,1.0,1.0   refractive
  154.  
  155.  
  156.  
  157.  
  158.      - - - 'v' Format: - - -
  159.  
  160. specifies the viewpoint of the display. x, y, and z values are required.
  161.  
  162. v 215.0,     100.0,       -550.0
  163.   |        |         z coordinate of viewpoint
  164.   |        y coordinate of viewpoint
  165.   x coordinate of viewpoint
  166.  
  167.  
  168.  
  169.      - - - 'l' Format: - - -
  170.  
  171.    specifies the location of the lightsource, and its diameter. Like before
  172. its x, y, and z coordinates, now followed by the diameter of the light.
  173.  
  174. l 150.0,     950.0,          0.0,         100.0
  175.  
  176.  
  177.      - - - 'r' Format: - - -
  178.  
  179. specifies the resolution of the picture to be produced, in Rays projected
  180. through each Pixel, followed by the color schema index, a number from 1 
  181. through 3.
  182.  
  183. r .20, 3
  184.  
  185.    The inputted value of Rays Per Pixel will be rounded up to the next 
  186. greater power of 4.0. Thus in the line above, the .20 will be rounded up 
  187. to (4.0)**(-1) = .25.
  188.  
  189.    The time to compute images varies linearly with the resolution (Rays Per
  190. Pixel) chosen. The constant of proportionality varies greatly depending on 
  191. the complication of the scene, but for the 6-ball scene here on a 520ST:
  192.  
  193.       .0625 rays per pixel      4 min
  194.       .25 rays per pixel     15 min
  195.      1.0 rays per pixel      1 hr
  196.      4.0 rays per pixel       4 hrs
  197.     16.0 rays per pixel     16 hrs
  198.  
  199.  
  200.    The color index specifies how the 16 colors of the low resolution monitor
  201. are divided amongst hues and saturation. Three values are accepted currently:
  202.  
  203.     1:    white            16 saturations
  204.     2:    white, red        8 saturations each
  205.     3:    white, red, blue    6 saturations each
  206.  
  207. Although the ray tracing algorithm computes arbitrary red/green/blue hues,
  208. the palate limitations of the ST prohibit their display.
  209.  
  210.  
  211.  
  212.  
  213.      - - - 'g' Format: - - -
  214.  
  215. specifies the strength of gravity. The following is realistic:
  216.  
  217. g 32.0
  218.  
  219.  
  220.  
  221.      - - - 'f' Format: - - -
  222.  
  223. specifies the first 5 characters of the filename to be used to save 
  224. completed pictures. (The rest of the name is the frame sequence number,
  225. and the suffix .PI1)  Also specified are the starting and ending frame
  226. numbers to be computed (positive integers less than 999).
  227.  
  228. f pearl, 1, 24
  229.  
  230. generates 24 frames on the disk, labeled PEARLL001.PI1 through PEARL024.PI1.
  231. At 32K per frame, that will just about fill an 820Kb double sided drive.
  232.  
  233.  
  234.  
  235.  
  236.             CHECKPOINTING
  237.  
  238.    Since PEARLE.PRG runs are so long, checkpointing information is generated
  239. following the completion of a frame, so that if the computation of the next
  240. frame is interupted, it may be restarted.  The checkpointing information
  241. is written in a file named PEARLE.CKP in the same format as PEARLE.IN.  
  242. PEARLE.PRG will use this file instead of PEARLE.IN if the former exists.  
  243. BE SURE TO REMOVE PEARLE.CKP FILES IF YOU WANT THE RUN TO START A NEW RUN.
  244.  
  245.  
  246.  
  247.    Thats it for now. Tell me of you ventures, send me interesting 
  248. configurations you find, and enjoy!
  249.  
  250.  
  251.  
  252.         Allen King    1-617-449-3359 evenings
  253.         30 Gibson St        
  254.         Needham Ma.    ucbvax!aking@bfly-vax.bbn.com
  255.         02192
  256.