home *** CD-ROM | disk | FTP | other *** search
/ Ray Tracing Box / RAY_CD.mdf / raytrace / form / docs / form.doc < prev    next >
Text File  |  1993-11-10  |  14KB  |  350 lines
  1. LEGAL STUFF AND COPYRIGHT
  2.  
  3. The FORM program is not public domain software. It is copyrighted
  4. software, Copyright (C) 1993 Andrew Rowbottom. It is however free
  5. software, or what some people term 'Freeware'. You may use it for
  6. whatever you wish, even using it to produce commercial pictures,
  7. animations, sculptures, deep sea diving equipment, etc. You may NOT
  8. however re-distribute modified versions of the executable nor
  9. distribute any of the files in this distribution for a profit. 
  10.  
  11. Since this software is free, it is supplied WITHOUT ANY WARRANTY;
  12. without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
  13. PARTICULAR PURPOSE. It is supplied as it, in the hope the people will
  14. find it useful.
  15.  
  16.  
  17. CONFIGURING FORM
  18.  
  19. Most if not all the facilities in form can be specified in one of three ways, 
  20.  
  21. 1. Through command line switches, use form -? to get the most
  22.     upto date list of these.
  23.  
  24. 2. Through an environment variable FORM, i.e. if you always use the
  25.     command line switches "-res2 -w" you can use the command 
  26.     "set FORM=-res2 -w" 
  27.  
  28. 3. Through the FORM section of the sstools.ini file, virtually all
  29.     the command line switches have their equivalents in this section.
  30.     They are described in the example file, but the above two flags
  31.     would become:   
  32.  
  33. screen_res=2
  34. SaveBackgroundAsWhite=yes
  35.  
  36.  
  37. COMMAND LINE OPTIONS
  38.  
  39. DISPLAY Switches 
  40.  
  41. These command line switches affect how form uses the screen display
  42.  
  43. -bios[+-]  
  44.             When this is enabled FORM uses bios to draw to the
  45.             screen, and even uses bios to switch to 320x200. Turn
  46.             this flag off for more speed. You may need to leave this
  47.             flag on if you are using a notebook.
  48.  
  49.  
  50. -modex      When enabled and -bios is NOT enabled FORM will use a VGA
  51.             ModeX method of accessing a 320x200 screen, faster than
  52.             BIOS and a little slower than standard access.
  53.  
  54. -vesa       Use a vesa driver if found for Video Control, provided
  55.             since the autodetect routines crash windows normally!
  56.             steps: 
  57.                 1. load your vesa driver if need be
  58.                 2. go into windows (if you want)
  59.                 3. run "form -vesa" (is default) 
  60.  
  61.             There usually isn't any apparent slowdown.
  62.             
  63.             You can use your manufacturer supplied Vesa driver, or a
  64.             public domain one such as "UNIVESA".
  65.  
  66.  
  67.             While a VESA driver is not required by FORM for most VGA
  68.             cards it is advisable to install one if you have one. For
  69.             example FORM mistakenly thinks that my machine at work
  70.             can use 800x600, but it can't, installing the supplied
  71.             vesa driver cures this problem and FORM correctly uses
  72.             640x480. Sometimes FORM will crash if running under
  73.             windows, this is caused by the autodetect methods,
  74.             installing a VESA driver before I run up windows cures
  75.             the problem.
  76.  
  77.  
  78.  
  79. -res[1|2|3] This flag sets the screen resolution used to display the form.
  80.             1 : screen display is 320x200 (default)
  81.             2 : screen display is one of 640x350, 640x400 or 640x480
  82.                 depending on your video card and available extended memory 
  83.             3 : screen display is one of 800x600, 1024x768 or 1280x1024 
  84.                 depending on your video card and available extended memory 
  85.  
  86.  
  87. -display[1|2|3|4]   This flag tells FORM to draw your form at the end. 
  88.          This is on by default, there are four drawing styles:
  89.  
  90.          1 : display at end Wireframe
  91.          2 : display at end Flat
  92.          3 : display at end Gouraud(default)
  93.          3 : display at end Phong
  94.  
  95. -float[+-]      This flag tells FORM to use a floating point scan line 
  96.             conversion method, it improves the quality of the display
  97.             at the expense of speed. Only use on a 486 or for saving.
  98.  
  99. -q[0|1|2|3|4|5]  Quality, very crude, try it on a single sphere and see 
  100.             what you think.
  101.  
  102. OUTPUT Switches 
  103.  
  104. These switches determine how FORM will save your form to disk.
  105.  
  106. -pov[-|+|1|2|3] If enabled FORM will produce a file called TEMP.POV
  107.         suitable for use with formvue.pov and the raytracer POV.
  108.         The output file can be in one of three "styles".
  109.  
  110.      - : no temp.pov output file
  111.      + : produce a temp.pov file (default)
  112.      1 : the form is made of individual objects, there is no heirachy
  113.          of objects, they are all specified relative to "world
  114.          coordinates"
  115.  
  116.      2 : the form is made using composites, there is a strict
  117.          heirachy of objects which matches your input form file. 
  118.  
  119.      3 : the form is made using #declares (default), again there is a
  120.          strict heirachy of objects which matches your input form
  121.          file right down to the names, this file is quite compact
  122.          (relatively speaking), and it is fairly easy to apply
  123.          textures in the right place. This output style also creates
  124.          bounding boxes, speeding up raytracing a few times.
  125.  
  126.  
  127. -pov_version=[1|2]
  128.         change pov version output is intrended for (version 2 is the only
  129.         one I've tested lately).
  130.  
  131. -plg[-|+]   If enabled FORM will produce a file called TEMP.PLG
  132.         suitable for use with rend386 software.
  133.      - : no temp.plg output file
  134.      + : produce a temp.plg file (default)
  135.  
  136.  
  137. -save           When enabled FORM will display your form at the end, 
  138. -save+          and save the screen display to a file called TEMP.GIF
  139. -save+filename  or TEMP.TGA, unless you specify a different filename 
  140. -save=filename
  141. -save-      
  142.  
  143. -w[+|-]         save background as white -w[+-] flag
  144.  
  145. -g[+|-]         If saving save the screen to a GIF file
  146.  
  147. -t[+|-]         If saving save the screen to a TGA file
  148.  
  149. -spin=number    COMMAND LINE FLAG only.
  150.                 What do all computer graphics people do with an image
  151.                 when they are bored? They spin it! Give a number and
  152.                 FORM will display (and save if asked) the image so
  153.                 that it turns a full circle in that many frames.
  154.  
  155.                 Not very useful without the -save= and -k- flags
  156.                 if -save specified Files are named with trailing digits, i.e.
  157.                 spin=9    takes save=abcdefgh and produces abcdefg#(.gif)
  158.                 spin=9999 creates abcd####(.gif)
  159.  
  160.  
  161. OTHER Switches
  162.  
  163. -k[+-]          Pause at end of display. Default on, turn it off if you
  164.                 are using the -spin option, or batch mode saving.
  165.  
  166. -path=dir1;dir2 Include directories to search for form files.
  167.  
  168. -dump [-|+]     Produce a Debug Dump at end
  169.  
  170. -v [-|+]        Overly Verbose and useless output
  171.  
  172. -?              Help
  173.  
  174. -ems            Use EMS memory for the ZBUFFER, (faster).
  175.  
  176.  
  177. OUTPUT formats, and historical digression
  178.  
  179.     When form was originally written it was designed to output text
  180. files for input to POVRAY and to REND386, this used to be the only
  181. way to actually see what had been created, but I got fed up with the
  182. low quality of display from REND386 (although there is a lot to be
  183. said for real time display), and didn't have the patience to wait for
  184. a raytrace from POV every time, so I built in the screen display that
  185. you have seen and now I use it all the time.  
  186.  
  187. POV output
  188.  
  189.     Pov output from FORM goes to a file temp.pov. The output file is
  190. (usually :-) suitable for raytracing using the formvue2.pov sample
  191. file. The form is always scaled so that it fits inside a unit box for
  192. ease of placement. You can input textures inside FORM but you will 
  193. probably want to edit the output file to fine tune the textures. 
  194.  
  195. PLG output
  196.  
  197.     PLG output from FORM goes to a file temp.plg. The output file is
  198. suitable for input to rend386 (sometimes known as DEMO3 or DEMO4).
  199. This output is crude and not optimal at all. REND386 does give a fast
  200. real time display, but a problem I have had is that if the form
  201. starts getting complicated (which they do very rapidly) bits start to
  202. disappear from the screen.  
  203.  
  204. Motive
  205.  
  206.     The FORM program was started in April '93 as an excercise in
  207. using C++ and LEX and YACC it has grown from it's original modest
  208. intentions.
  209.  
  210. TOOLS USED
  211.  
  212.     The code was originally developed under DJDelories Gnu C++, but I
  213. changed to Borland's C 3.1 compiler, debugger and profiler. The
  214. source code has been kept under control by MKS RCS, which has saved
  215. the code from being completly lost twice so far. I use GNU's FLEX and
  216. BYACC, although I have had to modify the code to FLEX to provide
  217. include file capability and fix other minor incompatibilities.
  218.  
  219.  
  220. BORROWED, BEGGED AND STOLEN SOURCE CODE :-).
  221.  
  222.     Since I hate re-inventing the wheel I have in the course of this
  223. project used code from Graphics Gems (the source not the book) and
  224. xxx's SVGAKIT.  The Graphics Gems code proved a great source of
  225. inspiration, and a good stepping stone to developing customised
  226. algorithms since I could see if the idea worked first and then
  227. rewrite for integer arithmetic.  
  228.  
  229.     SVGAKIT on the other hand is used practically as is. A very
  230. useful package for IBM PC programmers.   
  231.  
  232. TECHNICAL INFORMATION
  233.  
  234.     I have rigged the code so that integers are used for most of the
  235. drawing, giving somewhere around a five times increase in speed
  236. compared against using floating point operations on a non 486. There
  237. was a slight loss in quality, (try a single sphere at 320x200 res)
  238. but it was worth it. I may improve the quality since I now know what
  239. causes it, much rewritten code later!  
  240.  
  241.     The drawing method used is a simple polygonal ZBUFFER algorithm,
  242. with gouraud shading. The polygons are rendered using integer
  243. algoritms, including the depth, and intensity fields.  
  244.  
  245.     All other calculations in the system are performed using single
  246. precision floating point. 
  247.  
  248.     Dos memory is used for the Zbuffer unless there isn't enough at
  249. which point EMS memory is used. Failting that XMS memory is used, 
  250. this is copied to and from a single 64K cache in standard DOS memory. 
  251. This use of XMS is not the fastest possible, but what the heck - 
  252. it works!
  253.  
  254.     If you want to see how long form takes to parse a file run with
  255. the command line flags "-display- -plg- -pov-", no output is
  256. generated, and so the time taken is simply the load and process time.
  257.  
  258.     For those of you who are really interested the TGA file is
  259. uncompressed with a 256 colour palette. It's only TGA because that
  260. was the easiest. GIF is now my standard (ta fractint).
  261.  
  262.  
  263. REGISTRATION (Part 2)
  264.  
  265.     Personally I hate readme's that either don't tell you how to
  266. register (or even if you should), or give you half a book on the
  267. subject right at the beginning. This program is free, give it to your
  268. friends if you think they may like it. I don't charge anything for
  269. this program, it costs nothing, and is warranted to no purpose except
  270. that it will occupy some space on your hard disk/floppy until
  271. deleted. You get what you paid for.
  272.  
  273. PS. If no-one sends me e-mail, I'll conclude that this program is
  274. rubbish and probably stop development. 
  275.  
  276.  
  277. CREDITS
  278.  
  279.     The code for this program came from many sources, 
  280.  
  281.     UNIVESA and SVGAKIT came from Kendall Bennett.
  282.     FLEX the lexical analyser came from the GNU project
  283.     BYACC came from heaven knows where.
  284.     The GIF encoder is a very mutilated version of the one in
  285.     Fractint. Thanks to the stone soup team, for making their source
  286.     freely available.  ( and for sstools.ini , you should see the
  287.     junk in mine!)
  288.  
  289.     Thanks to the people who published code from Graphics Gemsxxx.
  290.     While very little of their code finally ended up in FORM many of
  291.     the display routines were originally tested using their code. The
  292.     Graphics Gems collection was a real godsend and should be in your
  293.     source code collection. It can be retreived from wuarchive.wustl.edu 
  294.     somewhere in \graphics\graphics.
  295.  
  296.  
  297.     PANTEK Ltd for allowing me to release this code.
  298.  
  299.     Stephen Todd and William Latham for the inspiration and a good book.
  300.  
  301.     Andrew Pearmund for providing a much needed get_pixel function
  302.     without which FORM couldn't save any pictures, and for breaking 
  303.     the program it every time I showed it to him.
  304.  
  305.     Sue Cunningham for being with me, and constantly praising my
  306.     feeblest efforts at creativity, and finally showing me the sort 
  307.     of form that could be created.
  308.  
  309.  
  310. Future List (in no particular order, except the first two)
  311.  
  312.     Bug fixing,     I need to add brackets
  313.                     I need to improve error checking
  314.  
  315.  
  316.     MUTATIONS   -   for an explanation see TODD & LATHAM, this is a
  317.                     priority option! 
  318.  
  319.     Improved xms Zbuffer caching (not gonna do this, EMS is good enough)
  320.     add ems Zbuffer caching      (done)
  321.     add disk Zbuffer caching     
  322.     add memory screen images for those that don't have SVGA cards
  323.     (and for text only machines to run overnight)
  324.     
  325.     Perspective. (well why not!)
  326.  
  327.     A graphical interface, very much vapourware at the moment.
  328.  
  329.     different language syntax - I'm not happy with the current
  330.                     language implementation, if anyone has any ideas
  331.                     for a better syntax let me know.
  332.  
  333.     Portability to gnu cc compiler (for the hell of it)
  334.  
  335.     Portability to other platforms (will happen after gnu cc port)
  336.  
  337.     more output formats. (some other raytracers, polyray etc.)
  338.  
  339.     Textures I am particulary open to suggestions regarding implementing
  340.                     textures in POV. - (underway)
  341.  
  342.     If I can do textures I may add truecolour facilities.
  343.  
  344.  
  345.  
  346.  
  347.         rummy@snaffle.demon.co.uk
  348.  
  349.         Andrew Rowbottom
  350.