home *** CD-ROM | disk | FTP | other *** search
/ Ray Tracing Box / RAY_CD.mdf / raytrace / form / docs / language.doc < prev    next >
Text File  |  1993-11-11  |  11KB  |  357 lines
  1. LANGUAGE.DOC
  2.  
  3. This is a brief description of the command line flags, and language
  4. of form. This file is updated very sporadically so I'm sorry about
  5. the lack of organisation to it.
  6.  
  7. Latest revisions give:
  8. textures        new keyword for POV support (see flagpole and webgood 
  9.                 for examples) can be used almost anywhere after an object.
  10.                 Still in prototype stage.
  11.  
  12. -float[+-]      Turn use of floats on/off when rendering to the screen
  13.                 improved quality at the sake of time. 
  14.  
  15. -pov_version=[1|2] the version of POV you're using default 2
  16. -q[0|1|2|3|4|5] "Quality" I'm still working on this, default is -q0,
  17.                 try other options.
  18.  
  19. -modex          use VGA "ModeX" for 320x200 mode (-res1), required on
  20.                 some VGA cards. This mode is slightly slower than
  21.                 normal, and much faster than BIOS.
  22.  
  23. -ems[+-]        use/don't use ems for ZBUFFER if present this is
  24.                 sometimes a lot faster, and sometimes not at all.
  25.  
  26. -angle=number   command line flag for initial rotation around y axis
  27. scale   number - scales the object by the number
  28. twistx  number - like twist only around x axis
  29. twistz  number - like twist only around z axis
  30. spin flag, command line only -spin=frames to use. 
  31.         Spins the scene through 360 degrees in the frames you specify.
  32.         Not very useful without the -save= and -k- flags
  33.         if -save specified Files are named with trailing digits, i.e.
  34.         spin=9    takes save=abcdefgh and produces abcdefg#(.gif)
  35.         spin=9999 creates abcd###(.gif)
  36.  
  37. save as Gif flag -g[+-] 
  38. and it's alias save as tga -t[-+], (SaveAs=GIF or TGA)
  39.  
  40. save background as white -w[+-] flag (SaveBackgroundAsWhite=Yes|No)
  41.  
  42. include directories -path=dir1;dir2... (path=dir1,dir2... in sstools.ini)
  43.  
  44. Propellors when parsing a file, so you know it hasn't died!
  45. Each script is written to TEMP.FRM.
  46.  
  47. WEB now has HOLE and EXCESS
  48.  
  49. Pressing <ESC> during a display should stop the display
  50. Saving to TGA file, use -save=filename (default temp.tga for "-save")
  51.  
  52. display at end using -display(1,2,3,4) 
  53.     type 1=wire  2=flat  3=gouraud   4=phong
  54.  
  55. In the language new command "#include filename", verrrry crude and
  56.     barely tested!
  57.     NOTE: the statement "end" in an include file is ignored
  58.     "end" is only understood in the first file.
  59.  
  60. -k[+-]  pause at end of display. I know I put this in for a good
  61.         reason, something to do with Batch mode and saving, but I'm
  62.         not too clear what. I've remembered ... see -spin above, 
  63.  
  64. -bios[+-]  Super duper Bios compatability, use bios putpixel, 
  65.             and 320x200 bios mode switch, use on nasty notebooks.
  66.  
  67. -vesa      use a vesa driver if found for Video Control, 
  68.             the autodetect routines crash windows normally!
  69.             steps: 
  70.                 1. load your vesa driver if need be
  71.                 2. go into windows (if you want)
  72.                 3. run "form -vesa" (the default) 
  73.                     there isn't any apparent slowdown anyway 
  74.             
  75.            You can load a Vesa driver such as "univesa".
  76.  
  77. SSTOOLS.INI
  78.         all the command line switches can be saved in the [FORM]
  79.         section of an sstools.ini file somewhere on your path.
  80.         (thanks Fractint!).
  81.         see example sstools.ini file.
  82.  
  83.  
  84.  
  85.  
  86. usage:
  87.     form    [options] [file] [options]
  88.    if [file] is ommited the form is read from stdin
  89.    options are also read from the environment variable FORM, and sstools.ini
  90.  
  91.  
  92. options are:
  93.  
  94.   -pov[-|+|1|2|3]
  95.      - : no temp.pov output file
  96.      + : produce a temp.pov file (default)
  97.      1 : output file is made of individual objects
  98.      2 : output file is made using composites
  99.      3 : output file is made using #declares (default)
  100.  
  101.   -plg[-|+]
  102.      - : no temp.plg output file
  103.      + : produce a temp.plg file (default)
  104.  
  105.   -res[1|2|3]
  106.      1 : screen display is 320x200 (default)
  107.      2 : screen display is 640x400 or 640x480 depending on memory 
  108.      3 : screen display is 1024x768
  109.  
  110.   -display[1|2|3|4]
  111.      1 : display at end Wireframe
  112.      2 : display at end Flat
  113.      3 : display at end Gouraud(default)
  114.      3 : display at end Phong
  115.  
  116.   -dump [-|+]
  117.      Debug Dump at end
  118.  
  119.   -k[+-] pause at end of display. I know I put this in for a good
  120.         reason, something to do with Batch mode and saving, but I'm
  121.         not too clear what.
  122.  
  123.   -bios[+-]  Super duper Bios compatability, use bios putpixel, 
  124.         and 320x200 bios mode switch.
  125.  
  126.   -vesa    use a vesa driver if found for Video Control, 
  127.         the autodetect routines crash windows normally!
  128.         steps: 
  129.                 1. load your vesa driver if need be
  130.                 2. go into windows (if you want)
  131.                 3. run "form -vesa" (is default) 
  132.                     there isn't any apparent slowdown anyway 
  133.   -v [-|+]
  134.      Overly Verbose and useless output
  135.   -?
  136.      Help
  137.  
  138.                      *******   ****   *****   **   **
  139.                      *        *    *  *    *  * * * *
  140.                      ****     *    *  *****   *  *  *
  141.                      *        *    *  * *     *     *
  142.                      *        *    *  *  *    *     *
  143.                      *         ****   *   *   *     *
  144.  
  145.  
  146.  
  147. C style comments are allowed both /**/ and // forms
  148.  
  149. SYMBOL is a standard C symbol ie. a-z followed by any of a-z 0-9 and _.
  150. NUMBERS are all real, converted to int wherever appropriate.  
  151. NUMBERS can be expressions using +, -, *, /, ^, ().
  152. VECTORS are in the form "<" real "," real "," real ">"
  153. ANGLES are in degrees
  154.  
  155.  
  156. The form file essentially describes a scene.
  157. it has the shape of :-
  158.  
  159. any number of: objectdefinitions
  160. any number of: debug flag assignments
  161. any number of: configurable item assignments
  162. any number of: output commands (currently only display!)
  163. at least ONE: object        (usually only one)
  164. optionally terminated with the word "end" (meaning produce some output)
  165. simple end of file simply stops processing
  166.  
  167.  
  168. OBJECT
  169. ======
  170. an object is a set of part objects terminated by a ';'
  171.  
  172. a (part) object is :
  173.  
  174. an object followed by a FORM
  175. an object followed by a simple modifier
  176. an object followed by a FORM modifier 
  177. a PRIMITIVE
  178. a DEFINED_OBJECT
  179. a DEFINED_OBJECT enclosed by "[ ]", this has the effect of rotating
  180.                  the object by 90 degrees
  181. an object "," object.
  182.  
  183.  
  184. OBJECT DEFINITION 
  185. =================
  186. is a name (symbol) followed by "=" and then an object.
  187.  
  188.  
  189.  
  190. COMMANDS
  191. ========
  192.  
  193. DEBUG RELATED COMMANDS
  194. ----------------------
  195.  
  196. these have no effect on the objects or output
  197.  
  198. lexdebug <on|off>   turns debug prinouts from lex on or off (default off)
  199.  
  200. yaccdebug <on|off>  turns debug prinouts from yacc on or off (default off)
  201.  
  202. yydebug <on|off>    turns internal yacc debug prints on or off (default off)
  203.  
  204. OUTPUT RELATED COMMANDS
  205. -----------------------
  206. these affect the output not the shape
  207.  
  208. plg scale = number; 
  209.                 defines the plg scale used for output to plg - default 500
  210.  
  211. old_pov_method;     
  212.                 not used anymore
  213.  
  214. screen_res   = [1|2|3];   
  215.                 equivalent to -res[1|2|3] command line option
  216.  
  217. screen_scale = number;
  218.                 scale up the screen output, 1.2 is usually OK
  219.  
  220. display [object] [save file name] [rendering style];
  221.                 will display object (default current object) in the
  222.                 rendering style specified. save file name is not
  223.                 actually implemented, it takes time but doesn't do
  224.                 anything. This does not in any way represent the
  225.                 views of the author to freeware, it's just I haven't
  226.                 done it yet!
  227.  
  228.  
  229. PRIMITIVES
  230. ==========
  231.  
  232. sphere  
  233. sphere radius 
  234.  
  235. ellipse
  236. ellipse width , height
  237. ellipse <vector>            (vector gives x, y, z axis lengths)
  238.  
  239. box
  240. box size
  241. box vector                   (vector gives x , y , z size)
  242.  
  243. torus
  244. torus minradius , maxradius
  245.  
  246.  
  247.  
  248. FORMS
  249. =====
  250.  
  251. these take an object (list of objects) and create another object from
  252. a compound of these to which have been applied transformations
  253.  
  254. STACK number_to_stack
  255. STACK number_to_stack IN space_of_number 
  256. STACK number_to_stack IN space_percentage "%"
  257.  
  258.     This stacks number_to_stack objects with compression of:
  259.     1.0
  260.     space_of_number / number_to_stack
  261.     space_percentage / 100
  262.             
  263. The resulting object is similar to that created by a list of objects
  264.             i.e. sphere stack 2 is the same as sphere , sphere
  265.             
  266. FAN   number , angle [ , tightness]
  267.  
  268.     takes no_objs copies of object and fans them through 0 .. angle
  269.     degrees in a sphere (angle usually 0 .. 180), optional tightness
  270.     defaults to 1 gives a bunching effect, 0.1 shows what it does the
  271.     result is a single object of height 0;
  272.  
  273. web   number1 WITH defined_object 
  274.             [SCALE(number2)] number3 [hole number] [excess number]
  275.  
  276.     uses number1 spokes of object webbed with number3 of defined object
  277.     which are optionally scaled up by number2.!
  278.     hole is the gap to leave in the middle (2 = 2 * length of a spoke)
  279.     excess is amount to exceed by (proportions of a spoke)
  280.     eg. 
  281.         spokeobject WEB 8 WITH webbing_object 3
  282.         creates a sort of 8 spoked 3 ringed waggon-wheel.
  283.  
  284. rib     NYI
  285.  
  286.  
  287. MODIFIERS
  288. =========
  289.  
  290. these are applied to an object and are used to change the shape
  291.  
  292. SIMPLE MODIFIERS
  293. ----------------
  294.  
  295. DELETE delete_range e.g delete 1   or delete 10 .. 5
  296.     makes the x..y'th object in the list invisible.
  297.  
  298. MOVE <vector>
  299.     moves every object in the list by vector (remember Y is up)
  300.  
  301. TEXTURE <texture name> eg texture "Metal pigment{White}"
  302.     applies the POV texture from that point downwards.
  303.  
  304. STACK MODIFIERS
  305. ---------------
  306.  
  307. these give a warning if they do not follow a stack but will often
  308. work if there is a list of more than one object
  309.  
  310. GROW    size    
  311.  
  312.     takes the stack and uniformly grows each object (about it's own
  313.     center) by an amount: 1 for the first object, and size for the
  314.     last. 
  315.  
  316. POWERED_GROW    
  317. CENTERED_GROW
  318. POWERED_CENTERED_GROW
  319.     slightly different in how they actually do the growing. 
  320.     Not too hot. Powered grow is the best of the lot, it isn't
  321.     linear, that's all.
  322.  
  323. BEND    angle   
  324.  
  325.     bends the stack fromthe vertical by angle. Bend of 360 gives one
  326.     loop of a spiral, bend of 90 gives a quarter loop.
  327.  
  328. TWIST   angle [ , displacement]
  329.  
  330.     rotates each obj in stack around vertical axis by 0 .. angle
  331.     degrees optional offset moves stack by displcement, rotates about
  332.     original axis and then moves back. Gives a spiral effect
  333.  
  334. TWISTX   angle 
  335.     rotates each obj in stack around X axis by 0 .. angle.
  336.  
  337. TWISTZ   angle 
  338.     rotates each obj in stack around vertical axis by 0 .. angle.
  339.     interesting effect when combined with BEND.
  340.  
  341. incremental twist   ILLEGAL
  342. incremental grow    ILLEGAL
  343. incremental bend    ILLEGAL
  344.  
  345.  
  346. OTHER VALID INPUT
  347. =================
  348.  
  349. exists      test token
  350.  
  351. end         marks EndOfFile, REQUIRED or you don't get any output!
  352.  
  353.  
  354.         rummy@snaffle.demon.co.uk
  355.  
  356.         Andrew Rowbottom
  357.