This file contains an extremely abbreviated description of the command line
flags, initialization file statements, and data file declarations for Polyray.
See "polyray.doc" for more details.

Syntax:

   polyray datafile [ options ]

Command line options:

   -a mode         Antialiasing (0=none,1=corner average,2-4=adaptive)
   -b pixels       pixels calculated between file flushes
   -B              Flush the output file every scan line
   -d              Generate a depth file instead of an image file
   -o filename     Output file name (default "out.tga")
   -p bits/pixel   Number of bits per pixel 8/16/24/32 (default 16)
   -P pallette     Which pallette to use [0=grey, 1=666, 2=884]
   -Q              Abort if any key is hit during trace
   -q flags        Turn on/off various global shading options
   -r renderer     Which rendering method [0=raytrace, 1=scan convert,
                   2=wireframe, 3=raw triangle information,4=uv triangles]
   -R              Resume an interrupted trace
   -s samples      # of samples per pixel when performing focal blur
   -t status_vals  Status display type [0=none,1=totals,2=line,3=pixel].
   -T threshold    Threshold to start oversampling (default 0.2)
   -u              Write the output file in uncompressed form
   -v              Trace from bottom to top
   -V mode         Display mode while tracing (0=none,1-5=8bit,6-10=16,11-15=24)
   -W              Wait for key before clearing display
   -x columns      Set the x resolution
   -y lines        Set the y resolution
   -z start_line   Start a trace at a specified line

Initialization file ("polyray.ini") keywords:

   abort_test       true/false/on/off
   alias_threshold  [Value to cause adaptive anitaliasing to start]
   antialias        none/filter/adaptive1/adaptive2
   clustersize      [# of objects stored in a slab]
   display          none/vga1...vga5/hicolor1...hicolor5/truecolor1...truecolor5
   max_level        [max depth of recursion]
   max_samples      [# of samples when performing focal blur]
   optimizer        none/slabs
   pallette         884/666/grey
   pixel_size       8/16/24/32
   pixel_encoding   none/rle
   renderer         ray_trace/scan_convert/wire_frame/raw_triangles/uv_triangles
   shade_flags      [default/bit mask of flags, see section 1.7.1.4 of docs]
   shadow_tolerance [miminum distance for blocking objects]
   status           none/totals/line/pixel
   warnings         on/off

   Any lines starting with "//" will be treated as comments & ignored.
   Any lines surrounded with "/*" ... "*/" will be ignored

Input file syntax:

   [viewpoint statement]
   [object declaration]
   [conditional statement]
   define token expression
   define token [object declaration]
   define token [surface declaration]
   define token [texture declaration]
   define token texture_map([a, b, texture1, texture2]
			    ...
			    [x, y, texturei, texturej])
   define token particle { [particle declarations] }
   define token transform { [rotate/translate/scale/shear statements] }
   total_frames val
   start_frame val
   end_frame val
   outfile "name"
   outfile name
   file_flush xxx
   include "filename"
   system(arg1, ..., argn)
   background color
   background expression
   haze coeff, starting_distance, color
   light color, location
   light location
   spot_light color, location, pointed_at, Tightness, Angle, Falloff
   spot_light location, pointed_at
   textured_light {
      color color_expression
      [sphere center, radius]
      [rotate/translate/... statements]
      }
   directional_light color, direction
   directional_light direction
   depthmapped_light {
      [ angle fexper ]
      [ aspect fexper ]
      [ at vexper ]
      [ color expression ]
      [ depth "depthfile.tga" ]
      [ from vexper ]
      [ hither fexper ]
      [ up vexper ]
      }

Expressions:
   Floating point operators:
      +, -, *, /, ^
   Functions returning floats:
      acos(x), asin(x), atan(x), atan2(x, y), ceil(x), cos(x), cosh(x),
      degrees(x), exp(x), fabs(x), floor(x), fmod(x, y), heightmap(image, P),
      indexed(image,P), legendre(l, m, x), ln(x), log(x), max(x, y), min(x, y),
      noise(P), noise(P, o), noise(P, <p, n, o>), pow(x, y), radians(x),
      sawtooth(x), sin(x), sinh(x), sqrt(x), tan(x), tanh(x), visible(V1, V2),
      V1 . V2, |x|
   Vector operators:
      +, -, * (cross product, or float times a vector)
   Functions returning vectors/colors:
      brownian(P), brownian(P, S), color_wheel(x, y, z), dnoise(P),
      dnoise(P, o), dnoise(P, <p, n, o>), rotate(V1, <xdeg, ydeg, zdeg>),
      rotate(V1, V2, deg), reflect(V1, V2) trace(P, D)
   Predefined variables:
      u, v, x, y, z, P, W, N, I, start_frame, frame, end_frame
   Image file manipulation:
      environment("file1", "file2", ..., "file6")
      image("file")
      cylindrical_imagemap(image, V [, repeat flag])
      planar_imagemap(image, V [, repeat flag])
      spherical_imagemap(image, V [, repeat flag])
      heightmap(image, V)
      indexed_map(image, V [, repeat flag])
      environment_map(V, environment)
   Color map:
      color_map([v0, v1, Color0, Color1]
	        [v2, v3, Color2, Color3]
                ...
		[vx, vy, Colorx, Colory])
      color_map([v0, v1, Color0, alpha0, Color1, alpha1]
	        [v2, v3, Color2, alpha2, Color3]
                ...
		[vx, vy, Colorx, Colory, alphay])
   String manipulation (build single string from a set of string,
   numerical, or vector arguments):
      concat(arg1, arg2, ..., arg3)

Viewpoint declaration:

    viewpoint {
       [ from vexper ]                 // Default: <0, 0,-1>
       [ at vexper ]                   // Default: <0, 0, 0>
       [ up vexper ]                   // Default: <0, 1, 0>
       [ angle fexper ]                // Default: 45
       [ resolution fexper, fexper ]   // Default: 256x256
       [ aspect fexper ]               // Default: 1.0
       [ hither fexper ]               // Default: 1.0e-3
       [ yon fexper ]                  // Default: 1.0e6
       [ max_trace_depth fexper ]      // Default: 5
       [ aperture fexper ]             // Default: 0
       [ focal_distance fexper ]       // Default: distance between from & at
       [ image_format fexper ]         // 0 = image, 1 = depth
       [ pixelsize fexper ]            // valid: 8, 16, 24, 32
       [ pixel_encoding fexper ]       // 0 = normal, 1 = RLE
       [ antialias fexper ]            // 0 = none, 1 = filter, 2-4 = adaptive
       [ antialias_threshold fexper ]  // Default: 0.02
       }

Object declaration:

   object {
      Shape declaration
      [ texture declaration ]
      [ Object modifier declaration ]
      }

Shape Declarations:

   bezier subdivision_type, flatness_value,
          u_subdivisions, v_subdivision,
          [ 16 comma-separated vertices, i.e.
             <x0, y0, z0>, <x1, y1, z1>, ..., <x15, y15, z15> ]

   blob threshold:
      blob_component1
      [, sphere <x, y, z>, strength, radius ]
      [, cylinder <x0, y0, z0>, <x1, y1, z1>, strength, radius ]
      [, plane <nx, ny, nz>, d, strength, distance ]

   box <x0, y0, z0>, <x1, y1, z1>

   cone <x0, y0, z0>, r0, <x1, y1, z1>, r1

   cylinder <x0, y0, z0>, <x1, y1, z1>, r

   disc <cx, cy, cz>, <nx, ny, nz>, r
   disc <cx, cy, cz>, <nx, ny, nz>, ir, or

   function f(x,y,z)

   glyph contour_count,
      contour num_points1, V11, ..., V1n
      ...
      contour num_pointsm, Vm1, ..., Vmn

   gridded "filename", object1 object2 ...

   height_field "filename"
   smooth_height_field "filename"

   height_fn xsize, zsize, min_x, max_x, min_z, max_z, expression
   height_fn xsize, zsize, expression
   smooth_height_fn xsize, zsize, min_x, max_x, min_z, max_z, expression
   smooth_height_fn xsize, zsize, expression

   lathe type, direction, total_vertices,
      <vert1.x,vert1.y,vert1.z>
      [, <vert2.x, vert2.y, vert2.z>]
      [, etc. for total_vertices vertices]

   nurb u_order, u_vertices, v_order, v_vertices,
	[u_knot1, ..., u_knot(u_order+u_vertices)],
	[v_knot1, ..., v_knot(v_order+v_vertices)],
	[[<vert(1,1)>, ..., <vert(1,v_order)>],
	 ...
	 [<vert(u_order,1)>, ..., <vert(u_order,v_order)>]]

   nurb u_order, u_vertices, v_order, v_vertices,
	[[<vert(1,1)>, ..., <vert(1,v_order)>],
	 ...
	 [<vert(u_order,1)>, ..., <vert(u_order,v_order)>]]

   parabola <x0, y0, z0>, <x1, y1, z1>, r

   parametric <fx(u,v), fy(u,v), fz(u,v)>

   polygon total_vertices,
      <vert1.x,vert1.y,vert1.z>
      [, <vert2.x, vert2.y, vert2.z>]
      [, etc. for total_vertices vertices]

   polynomial f(x,y,z)

   sphere <center.x, center.y, center.z>, radius

   sweep type, direction, total_vertices,
      <vert1.x,vert1.y,vert1.z>
      [, <vert2.x, vert2.y, vert2.z>]
      [, etc. for total_vertices vertices]

   torus r0, r1, <center.x, center.y, center.z>, <dir.x, dir.y, dir.z>

   patch <v1.x,v1.y,v1.z>, <n1.x,n1.y,n1.z>, [ UV u1, v1, ]
         <v2.x,v2.y,v2.z>, <n2.x,n2.y,n2.z>, [ UV u2, v2, ]
         <v3.x,v3.y,v3.z>, <n3.x,n3.y,n3.z> [, UV u3, v3 ]

   object1 + object2  - Union
   object1 * object2  - Intersection
   object1 - object2  - Difference
   object1 & object2  - Clipping
   ~object1           - Inverse

Root solver declarations (for blobs, polynomials, splined lathes, and tori):

   root_solver Ferrari
   root_solver Vieta
   root_solver Sturm

Object modifier statements:

   translate <tx, ty, tz>
   rotate <rx,ry,rz>
   scale <sx,sy,sz>
   shear yx, zx, xy, zy, xz, yz
   shading_flags flag1+flag2+...
   u_steps u
   v_steps v
   w_steps w
   uv_steps u, v
   uv_steps u, v, w
   uv_bounds u0, u1, v0, v1
   bounding_box <x0,y0,z0>, <x1,y1,z1>
   displace expression

Shading flag values:

   1 = Shadow_Check, 2 = Reflect_Check, 4 = Transmit_Check,
   8  = Two_Sides, 16 = UV_Check, 32 = Cast_Shadow


Textures:
   texture {
      [ texture declaration ]
      [ rotate/translate/scale/shear ]
      }

Texture declarations:

   surface { [ surface declarations ] }
   noise surface { [ surface declarations ] }
   noise surface_sym
   noise surface_sym { [ surface declarations ] }
   special surface { [ surface declarations ] }
   special surface_sym
   special surface_sym { [ surface declarations ] }
   checker texture1, texture2
   hexagon texture1, texture2, texture3
   layered texture1, texture2, ..., textureN
   indexed fn, texture_map([a, b, texture1, texture2]
			   ...
			   [x, y, texturei, texturej])
   indexed fn, texture_map_sym
   summed fexper, texture1,
	  ...
	  fexper, texturen

Surface declarations:

   color <r, g, b>
   ambient scale
   ambient color, scale
   diffuse scale
   diffuse color, scale
   specular color, scale
   specular scale
   reflection color, scale
   reflection scale
   transmission color, scale, ior
   transmission scale, ior
   microfacet kind angle

Microfacet kinds: Blinn, Cook, Gaussian, Phong, Reitz.

Special Surface declarations add the following to Surface declarations:

   position vexper     // Turbulence: P + x * (dnoise(P, o) - <0.5, 0.5, 0.5>)
   normal vexper       // Bumps: N + x * (dnoise(P, o) - <0.5, 0.5, 0.5>)

Bumpmap declarations to use in the normal component of special surfaces:

      cylindrical_bumpmap(image, V [, bump size])
      planar_bumpmap(image, V [, bump size])
      spherical_bumpmap(image, V [, bump size])

Noise Surface declarations include all surface declarations plus:

   color_map(map_entries)
   bump_scale fexper
   frequency fexper
   phase fexper
   lookup_fn index
   normal_fn index
   octaves fexper
   position_fn index
   position_scale fexper
   turbulence fexper

The output of the following function is passed through the lookup function,
then into the color map.
   nval = pos * position_scale + turbulence * noise(P, octaves);

Valid values for position_fn are:
   0 - No position function used (default)
   1 - X coordinate in object space
   2 - X coordinate in world space
   3 - Distance from z-axis
   4 - Distance from the origin
   5 - Radial measure (counter clockwise) around y-axis

Valid values for normal_fn are:
   0 - No modification made to normal (default)
   1 - Bumpy
   2 - Rippled
   3 - Dented

Valid values for lookup_fn are:
   0 - Use nval directly
   1 - sawtooth applied to nval
   2 - sin function
   3 - ramp function

Conditional processing:

   if (cexper)
      [single declaration]

   if (cexper) {
      [object/light/... declarations]
      }
   else {
      [other object/light/... declarations]
      }

Particles:

   particle { [particle_declarations] }
   particle_sym
   particle_sym { [particle_declarations] }


Particle declarations:
   birth expression           // Particles are born when exper is non-zero
   count fexper               // # of objects to create when birth is non-zero
   death expression           // Dies when the expression is non-zero
   position vexper            // Starting position
   velocity vexper            // Starting velocity
   acceleration vexper        // Acceleration added every frame
   avoid expression           // Any non-null expression invokes avoid
   object object_sym          // Previously defined object

Particle variables:
   P   - Current location of the particle
   x   - X location of particle
   y   - Y location of particle
   z   - Z location of particle
   I   - Current velocity of the particle
   u   - Age of the particle

