Category : Printer + Display Graphics
Archive   : PLYDOC16.ZIP
Filename : QUICKREF.TXT

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

Syntax:

polyray datafile [ options ]

Command line options:

-a Perform simple antialiasing (neighbor averaging)
-A Perform adaptive antialiasing (based on threshold)
-b pixels pixels calculated between file flushes
-B Flush the output file every scan line
-d probability Dither objects using the given probability
-D scale Dither all rays using the given probability
-J Perform jittered antialiasing (fixed # of samples/pixel)
-o filename Output file name (default "out.tga")
-p bits/pixel Number of bits per pixel 8/16/24/32/Z (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]
-R Resume an interrupted trace
-s samples # of samples per pixel when performing antialiasing
-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=VGA,2=Hicolor]
-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/jitter/adaptive
clustersize [# of objects stored in a slab]
display none/vga/hicolor
max_level [max depth of recursion]
max_lights [max # of lights]
max_queue_size [max # of objects in a priority queue]
max_samples [# of samples to use with antialiasing, or focal blur]
optimizer none/bounding_slabs/bsp_tree
pallette 884/666/grey
pixel_size 8/16/24/32
pixel_encoding none/rle
renderer ray_trace/scan_convert/wire_frame/raw_triangles
shade_flags [default/bit mask of flags, see section 1.7.1.4]
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.

Input file syntax:

[viewpoint statement]
[object declaration]
[conditional statement]
define token expression
define token [object declaration]
define token [surface declaration]
define token [texture map]

define token [texture declaration]
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"
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
[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), legendre(l, m, x),
ln(x), log(x), max(x, y), min(x, y), noise(P, o), noise(P, ),
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:
color_wheel(x, y, z), dnoise(P, o), dnoise(P, ),
rotate(V1, ), 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(environment, V)
Color map:
color_map([v0, v1, Color0, Color1]
[v2, v3, Color2, Color3]
...
[vx, vy, Colorx, Colory])
String manipulation (build single string from a set of string,
numerical, or vector arguments):
concat(arg1, arg2, ..., arg3)

Viewpoint declaration:

viewpoint {
[ from vexper ]
[ at vexper ]
[ up vexper ]
[ angle fexper ]
[ resolution fexper, fexper ]
[ aspect fexper ]
[ hither fexper ]
[ yon fexper ]
[ dither_rays fexper ]
[ dither_objects fexper ]
[ max_trace_depth fexper ]
[ aperture fexper ]
[ focal_distance ]
[ image_format fexper ] // 0 means normal render, 1 means depth render
}

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.
, , ..., ]

blob threshold:
blob_component1
[, sphere , strength, radius ]
[, cylinder , , strength, radius ]
[, plane , d, strength, distance ]

box ,

cone , r0, , r1

cylinder , , r

disc , , r
disc , , ir, or

function f(x,y,z)

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,

[, ]
[, etc. for total_vertices vertices]

parabola , , r

polygon total_vertices,

[, ]
[, etc. for total_vertices vertices]

polynomial f(x,y,z)

sphere , radius

sweep type, direction, total_vertices,

[, ]
[, etc. for total_vertices vertices]

torus r0, r1, ,

patch , ,
, ,
,

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
rotate
scale
shear yx, zx, xy, zy, xz, yz
shading_flags flag1+flag2+...
u_steps u
v_steps v
uv_steps u0, u1, v0, v1
uv_steps u, v
uv_bounds u0, u1, v0, v1
bounding_box ,
displace expression

Shading flag values:

1 = Shadow_Check, 2 = Reflect_Check, 4 = Transmit_Check,
8 = Two_Sides, 16 = Cast_Shadow, 32 = Check Primary Rays


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

Texture declarations:

surface { [ surface declarations ] }
noise surface { [ surface declarations ] }
special surface { [ 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])

Surface declarations:

color
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:

normal vexper

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]
}