home *** CD-ROM | disk | FTP | other *** search
/ Micro R&D 1 / MicroRD-CD-ROM-Vol1-1994.iso / more3d / 3dtools / rayshade40_enh2.lha / README.AMIGA < prev   
Text File  |  1992-11-23  |  8KB  |  188 lines
  1. # This is an update version of the readme that came with the original archive
  2.  
  3.  
  4. November 23, 1992            Amiga Rayshade Readme (port by Colin DeWolfe)
  5. -----------------
  6.  
  7. What we have here in this directory is the current release of Rayshade 4.0.  The purpose
  8. of this readme is not to explain the use of Rayshade in general, but to explain how to
  9. use it on the Amiga.  There is nothing really new here except for some '881 code bug fixes
  10. and a co-processorless version (which hopefully work under 1.3, if not, let me know)
  11.  
  12.  
  13. Installation
  14. ------------
  15.  
  16.     The only thing you have to do to install rayshade is to copy the file ixemul.library
  17. in the libs directory to LIBS: and add the bin directory to your path.
  18.  
  19.  
  20. The Stack
  21. ---------
  22.  
  23.     Rayshade is a stack pig.  The newest release isn't as much of a pig as the older
  24. revisions were (Thanks Craig) but it still loves stack space. Most of the examples in
  25. the Examples directory can be rendered using a stack of under 200,000 but some exhibit
  26. wierd results if they do run out of stack, especially the constructive solid geometry ones.  
  27. If rayshade does happen to run out of stack one of three things will happen: 1) it will crash
  28. gloriously, 2) the ixemul.library will trap the error and return gracefully to the shell, or
  29. 3) you will just get unpredictable results.  All these seem to depend on how many processes 
  30. you have running and if rayshade's stack ends up running over some other program's data.
  31.     Included is a program called StackWatch (James Locker) which will report stack 
  32. usage every 30'th of a second.  This is great for examining how much stack Rayshade is 
  33. actually using.  It will probably miss alot of peak usage, but it will give you an idea.
  34.  
  35.  
  36. Running Rayshade
  37. ----------------
  38.  
  39.     You run Rayshade by using a CLI command of the following form:
  40.  
  41. 1.drive:dir/dir> rayshade < file.ray -O file.mtv [options]
  42.  
  43.     The documents say that you can use the form "rayshade file.ray > file.mtv [options]"
  44. however I had some trouble supporting this with the GNU C pre-processor and the current version of
  45. ixemul.library, so just use the form above and you will be fine.  I will try to fix this, even if 
  46. it means switching to  another pre-processor or SAS libraries.
  47.   
  48. (aside for this release)
  49.  
  50.     Rayshade will (no longer) fire up the C pre-processor on your input.  I have removed
  51. this support for the time being, but gcc-cpp is still in the bin directory for
  52. those die-hard include people (and for pre-processing one of the examples). .
  53. You must pre-process the file first, then feed it seperately to the raytracer.
  54. To invoke the preprocessor in the following way
  55.  
  56. gcc-cpp infile.ray outfile.ray (very important, keep the names different)
  57.  
  58. (end of aside)
  59.  
  60. Documentation
  61. -------------
  62.  
  63.     In the Doc directory are the postscript file for the Guide, Copyright notice,
  64. documentation for some of the support utilities, BUGS, TODO list and other legal stuff.
  65. Some of the utility programs are lacking documentation.  These are: 24toppm, ppmto24,
  66. mtv2tmp, splitanim, and ppmtomtv.  These last three I wrote and have since lost the
  67. source code for (long story).  The other two have notices in the program and did not come
  68. with documentation in the archive that I had.  These will be documented below.
  69.  
  70. Viewing Pictures
  71. ----------------
  72.  
  73.     Once Rayshade has finished cooking you probably want to look at what it did.
  74. Currently there are three methods for doing this.
  75.  
  76. 1)    run mtvtoppm < file.mtv > pipe:a
  77.     ppmtoilbm -hamforce < pipe:a > file.ilbm
  78.     (Then use your favorite display utility or paint program.)
  79.  
  80. 2)    mtvtoppm < file.mtv > file.ppm
  81.     ppmto24 file.ppm file.iff24
  82.     (This will create a 24 bit iff file for you lucky people with 24 bit boards or A4000's.)
  83.  
  84. 3)  or for preview
  85.  
  86.     mtv2tmp file.mtv file.tmp         (size limit of 320 400)
  87.     ray2 file                         (note: no extension)
  88.  
  89.     (Ray2 is taken from DBW Render. It has problems writing a 'correct' ilbm file.
  90.     Most paint programs and AdPro can load it, but most display viewers can't. Go figure.)
  91.  
  92.  
  93. Image Mapping
  94. -------------
  95.  
  96.     Rayshade supports image mapping.  All the details are in the guide, however
  97. I must mention that it likes its input images in the mtv format.  For this reason
  98. the utilities 24toppm, ilbmtoppm, and ppmtomtv are included.  They have usage guides if you
  99. just type their name at the shell prompt or have a doc file in the Doc. directory.
  100.  
  101.  
  102.  
  103. Animations
  104. ----------
  105.  
  106.     Rayshade has built in animation support as documented in the guide.  It is quite 
  107. basic however and you will probably end up doing animations using C to generate N input 
  108. files.  For those of you who will use the built in animation support, I have included a 
  109. program called splitanim which will split up the sometimes huge image file that is
  110. produced (Rayshade renders all the frames of an animation into one long file.)
  111. The usage is as follows:
  112.  
  113.     splitanim coin.mtv (for the example animation given in the Examples directory)
  114.  
  115. You will be presented with immense disk activity and then after that, a whole plethora
  116. of files named "*.mtv.n" files where * is the base name (in this case coin) and n is the 
  117. frame number.  You can then do with these what you will.
  118.  
  119.  
  120. IT'S NOT A BUG, IT'S A FEATURE
  121. ------------------------------
  122.  
  123.     The GCC support for the pipe: device is abysmal.  So, I have given up (for a little
  124. while anyway) supporting the automatic invoking of it from rayshade.  It is however
  125. in the bin directory so that you can preprocess files which need it. (See above) 
  126. The reason I am saying that it's a feature is because gcc-cpp will sometimes
  127. embed spaces where you don't want them, i.e., in the middle of a file path.
  128. Rayshade will complain about this. What you can then do is edit the pre-processed file
  129.  to fix this and then feed this file into. 
  130.  
  131. Rayshade will now happily generate your image.
  132. I am going to work on this further, but it may mean moving to another CPP.
  133. Or if anyone has a working version of popen(), mail it to me.
  134.  
  135.  
  136. Other Bugs
  137. ----------
  138.  
  139. The projector source code (as far as I can tell) was written with the URT toolkit in mind
  140. and thus renders the image upsidedown. This can be corrected through rotating the light
  141. source (but then it's flipped left to right, just can't win, can we?)  Over XMas I plan to
  142. build in support for the URT libraries, but I have too many midterms to do anything more right now.
  143.  
  144. Other Notes:
  145. -----------
  146.  
  147.     Aspect:  try using a fov value of <x> <x/1.3> when you render for ham, this will keep
  148.              everything looking right
  149.  
  150.     Sampling:The default sampling method is jittered sampling.  For native amiga lo-res displays
  151.              (such as ham), switch to adaptive as the colour resolution is not great and gives you
  152.              fuzzy looking pictures.  If you own an A4000, disregard above.
  153.  
  154.     A4000:     I have no idea if Rayshade works on an A4000. If you have one, send me info.
  155.  
  156.  
  157. Acknowledgements
  158. ----------------
  159.  
  160. For :   Rayshade 4.0:          Craig Kolb of Princeton University
  161.  
  162.         ppmtoilbm:             The German dudes who ported the great PPM toolkit.
  163.                                You know who you are.  (Blatant plug: Get this thing)
  164.  
  165.         ppmto24, 24toppm:    A.J. Brouwer
  166.  
  167.         mtv2tmp, splitanim:    Me.  :-)  (What a self serving little snot, eh?)
  168.         ppmtomtv        
  169.  
  170.         gcc-cpp:        GNU.  Also Markus Wild, who ported it to the Amiga
  171.                         and without who's port of GCC this wouldn't have
  172.                         been possible (SAS and Manx both barfed on the
  173.                         source code.)
  174.  
  175.         Sustainance:    Ron the Pizza Guy
  176. -------------------------------------------------------------------------------
  177.  
  178. Mail messages (no money, this is freely redistributable) can be sent to:
  179.  
  180. Snail (Canada Post):
  181.  
  182. Colin G. DeWolfe            | email:        dewolfe@ug.cs.dal.ca
  183. Apt 1115                    |                dewolfcg@newton.csc.tuns.ca
  184. 1030 South Park St.,         |            
  185. Halifax, Nova Scotia        | phone:        (902) 423-2612
  186. Canada                    
  187. B3H 2W3
  188.