Category : Printer + Display Graphics
Archive   : PVPRNC.ZIP
Filename : PVRAY05.DOC

Persistence of Vision Raytracer
Version 0.5 BETA Documentation
-----------------------------------------

For general documentation see PVDOC.ZIP.
Also see whatsnew.txt, texture.doc, docformt.txt, pvinfo.txt, etc.

This is a BETA version, so please keep those bug reports comin'!

INTERPOLATE keyword added for bump and image maps.
Syntax: interpolate 2 or interpolate 4
2 == Bilinear Interpolation
4 == Normalized Distance Interpolation
USE_COLOUR keyword added for maps.
USE_INDEX keyowrd added for maps.
END_MAP keyword added for maps.

IMPORTANT Case sensitivity
--------------------------
Case sensitive keywords and command line option added.
> case_sensitive_yes -- All words checked for exact case. Keywords must be
in upper case. (*Old DKB Style*)
> case_sensitive_no -- Case is ignored for all words.
> case_sensitive_opt -- DEFAULT - All words checked for exact case except
keywords. Keywords will be accepted in upper and/or
lower case.
- The declared colors Red, Green, and Blue in colors.dat are now CRed, CBlue,
CGreen.
- The declared quadric Sphere in shapes.dat is now QSphere.
- The texture Sky is now Blue_Sky

COMMAND LINE Options
--------------------
> Case sensitivity -- /ty = yes, /tn = no, /to = opt (see above)

+vO will enable old style terse verbose, line number only.
+v0 will enable old new style verbose.
+v1 (default) will enable new improved style verbose.


New IBM-PC display options
--------------------------
+dxy enables display adapter type x, with palette option y.

Supported Display Adapter Types:

0 - (default) Autodetect display adapter from types below:
1 - Basic, Plain Vanilla VGA 320x200
2 - MVGA (Mode 13X) Tweaked VGA 360x480 (if > 320x200)
3 - Tseng Labs 3000 SVGA 640x350, 640x480, 800x600
4 - Tseng Labs 4000 SVGA 640x350, 640x400, 640x480, 800x600, 1024x768
5 - AT&T VDC600 SVGA 640x400 (with cheesy autodetect)
6 - Oak Technologies OTI-067 SVGA 640x480
7 - Video 7 SVGA, VRAM FastRAM 640x480
8 - Video 7 Vega VGA, Cirrus Chip (uses Mode 1 or 2 above)
9 - Paradise SVGA 640x480
A - Ahead Systems Version A SVGA 640x480
B - Ahead Systems Version B SVGA 640x480
C - Chips And Technologies SVGA 640x480
D - ATI VGA Wonder 640x480
E - Everex SVGA 640x480
F - Trident SVGA 640x480
G - VESA Standard SVGA 640x400, 640x480, 800x600, 1024x768, 1280x1024

H - N reserved, unassigned (S)VGA adapter types

O - TIGA/Hercules Graphics Workstation 16-bit
P - TIGA/Hercules Graphics Workstation 24-bit

Q - Z reserved, unassigned True-Color adapter types

Supported Palette Options:

0 - (default) HSV->RGB method
3 - 3-3-2 RGB method
G - Grey Scale (optimized 64-shade palette for IBM PC's)
H - Sierra High Color pallete DAC on T4000 Based Cards.


TEXTURES
--------

We don't have documentation for ONION & LEOPARD yet, but their syntax
is the same as GRANITE or MARBLE. They do require a COLOR_MAP.


IMAGEMAP - new stuff is a set of new image projection types. To specify an
imagemap, an additional parameter is optional, i.e.

IMAGEMAP MAPTYPE 1 GIF "xxx.gif" END_MAP

Gives a spherical image map. The types of imagemaps that are now
defined are:

0) (default) Planar map - this is the one that was already there.

1) Spherical map - wraps the image around a sphere.
2) Cylindrical map - wraps the image around a cylinder (works good for
hyperboloids, cones, and paraboloids too).
5) Torus map - wraps the image around a torus. For this map you need
to put the major radius of the torus into the first parameter of the
gradient vector.

3-4) Parabolic and Hyperbolic maps - these are not implemented yet, but
will be tailored for mapping to the respective types. The reason for
having these in addition to the cylindrical types is that these shapes
deflect differently than a cylinder.

NOTE: Gradient only effects planar mapping.

For all of these image mappers it is assumed that the imagemap will work
in the interval 0 <= Y <= 1. This means that you need to use the shapes:
QUADRIC Sphere, QUADRIC Cylinder_Y, QUADRIC Hyperbola_Y, etc. If the default
Planar mapping is used, no object dimensions or coordinates need be changed.

See the file "mapper.dat" and the associated gif file "mapper0.gif" for an
example of how the new various types of mappers work. This file wraps the
picture "rough.gif" around various shapes.


KEYWORD: MATERIAL_MAP

BRIEFLY:
MATERIAL_MAP maps textures onto an object indexed via a bit-mapped image.

SYNTAX:
MATERIAL_MAP Image-Type "imagefilename" (ONCE) (TURBULENCE 0.0)
TEXTURE ... END_TEXTURE
TEXTURE ... END_TEXTURE
(up to 256 textures)

END_MATERIAL_MAP

DESCRIPTION:
MATERIAL_MAP is a lot like IMAGE_MAP. Image map takes a picture and
projects it onto an image. Like gluing a picture onto a sphere. Material
map does the same, but instead of changing the color of the sphere it
actually changes the texture of the sphere based on the color in the image.
When it finds a point that would have color number 0 projected on it, it
changes that point to the first texture in the MATERIAL_MAP definition.
Color index number 1 will become texture number 2 and so on.

EXAMPLE:
OBJECT
SPHERE <0.0 25.0 0.0> 50.0 END_SPHERE

TEXTURE { X-Y oriented bitmap image }
MATERIAL_MAP <1.0 -1.0 0.0> GIF "st.gif"

TEXTURE
COLOR Yellow
SPECULAR 0.75
SCALE <7.0 1.5 3.0>
END_TEXTURE
TEXTURE
Mirror
SPECULAR 0.75
END_TEXTURE
TEXTURE
Dark_Wood
SPECULAR 0.75
END_TEXTURE
TEXTURE
Jade
SPECULAR 0.75
END_TEXTURE

END_MATERIAL_MAP
ROTATE <0.0 35.0 0.0>
SCALE < 15.0 15.0 15.0 >
END_TEXTURE
END_OBJECT


KEYWORD: BUMPMAP

BRIEFLY:
BUMPMAP maps surface "bumps" onto an object indexed via a bit-mapped image.

SYNTAX:
BUMPMAP () Image-Type "imagefilename" (ONCE) (TURBULENCE 0.0)
(BUMPSIZE Height) (USE_COLOR) (USE_INDEX)
(INTERPOLATE 2 or 4)
END_MAP

DESCRIPTION:
BUMPMAP is a lot like IMAGEMAP. IMAGEMAP takes a picture and projects it
onto an image, like gluing a picture onto a sphere. BUMPMAP does the same,
but instead of changing the color of the sphere it actually changes the
orientation of the surface normal based on the colors in the image.
When it finds a point that would have color number 0 projected on it, it
leaves that point's surface normal alone. Color index number 1 will become
"bumped" out from the flat surface, color number 2 further still, and so on.
Try using one of FRACTINT's continuous potential fractals for interesting
BUMPMAP effects! BUMPSIZE can be negative. Try USE_COLOUR and INTERPOLATION.

EXAMPLE:
OBJECT
SPHERE <0.0 25.0 0.0> 50.0 END_SPHERE

TEXTURE { X-Y oriented bitmap image }
BUMPMAP <1.0 -1.0 0.0> GIF "bumpy.gif"
BUMPSIZE 1.0 {typ. between 0 and 1. Try > 1 for really big bumps }
INTERPOLATE 2
END_MAP
AMBIENT 0.2
DIFFUSE 0.8
SPECULAR 1.0
END_TEXTURE

ROTATE <0.0 35.0 0.0>
SCALE < 15.0 15.0 15.0 >
END_TEXTURE
END_OBJECT


KEYWORD: GOUGEMAP

BRIEFLY:
GOUGEMAP maps indentations into an object indexed via a bit-mapped image.

SYNTAX:
GOUGEMAP Image-Type "imagefilename" (ONCE) (TURBULENCE 0.0)
(GOUGESIZE or BUMPSIZE Depth )
END_MAP

DESCRIPTION:
GOUGEMAP is a lot like IMAGEMAP. IMAGEMAP takes a picture and projects it
onto an image, like gluing a picture onto a sphere. GOUGEMAP does the same,
but instead of changing the color of the sphere it actually changes the
orientation of the surface normal based on the colors in the image.
When it finds a point that would have color number 0 projected on it, it
leaves that point's surface normal alone. Color index number 1 will become
indented from the flat surface, color number 2 further still, and so on.

EXAMPLE:
OBJECT
SPHERE <0.0 25.0 0.0> 50.0 END_SPHERE

TEXTURE { X-Y oriented bitmap image }
GOUGEMAP <1.0 -1.0 0.0> GIF "scratchy.gif"
GOUGESIZE 1.0 {typ. between 0 and 1. Try > 1 for really deep gouges }
AMBIENT 0.3
DIFFUSE 0.7
PHONG 1.0
END_TEXTURE

ROTATE <0.0 35.0 0.0>
SCALE < 15.0 15.0 15.0 >
END_TEXTURE
END_OBJECT



POLYNOMIAL SURFACES
-------------------

Polynomials of arbitrary degree are handled by one of the following
declarations:

CUBIC < 10 Coefficients > END_CUBIC,

QUARTIC < 35 Coefficients > END_QUARTIC,

POLY < Max-Degree > < (n+1)*(n+2)*(n+3)/6 Coefficients > END_POLY

Quartics are the only case handled as a seperate case, with code to solve
them specifically. Higher order polynomial surfaces are solved using
Sturmian sequences. (The root solver is based on code from "Graphics Gems"
by Glassner, and is not debugged. Use at your own risk for surfaces of
degree higher than 4.) Cubics and quartics seem to be safe - the code for
these surfaces is the same as previous versions and suffers only from
precisions problems leading to digital noise.

See "SINSURF.DAT" for a 6th order surface. So far I haven't gotten a good
render of it as a result of system crashes and too much time spent working
on bicubic patches.


CLIPPING
--------

The keywords CLIPPED_BY and END_CLIP have been added to allow for chopping
parts of a surface by another surface. The effect is identical to an
INTERSECTION with a transparent surface, but quite a bit faster. See
"GRAFBIC.DAT" for a Bicorn that has had its front and back chopped.


BICUBIC PATCHES
---------------

Bicubic patches are a mesh of control points that describe the shape of
a surface. There are several types of bicubic patches, however the only
one currently understood is the Bezier patch.

Bezier patches are bicubic patches that take on the values of the corner
vertices of the mesh, and are influenced by the other values. A notable
computer graphic object that has this sort of patch definition is the
UTAH Teapot. (See TEAPOT.DAT.)

In order to ray-trace a patch, the patch is approximated by a mesh of vertices
that interpolate the patch. By increasing the number of points in each of
the two mesh parameters (u, and v), a smoother approximation to the true grid
will be traced. NOTE: Increasing the number of points increases the amount
of work in proportion to U-Resolution * V-Resolution. If the patch is going
to be small on the screen then you will not need to use a very high resolution.

The definition of a BICUBIC patch takes the form:

BICUBIC_PATCH
< vertex (0,0) > < vertex (0,1) > < vertex (0,2) > < vertex (0,3) >
< vertex (1,0) > < vertex (1,1) > < vertex (1,2) > < vertex (1,3) >
< vertex (2,0) > < vertex (2,1) > < vertex (2,2) > < vertex (2,3) >
< vertex (3,0) > < vertex (3,1) > < vertex (3,2) > < vertex (3,3) >

[ , , , ... ]
END_BICUBIC

The value of "Patch Type" determines the shading characteristics of the
patch, and the amount of storage used for mesh constants. There are
currently three allowed values for "Patch Type":


0) Bezier patch, only sufficient storage is allocated to store the tri-
angular vertices.

1) Bezier patch, vertices, all plane equations defined by the triangulation
of the patch into subpatches are stored.

2) Bezier patch, using binary subdivision to find the point of surface
intersection.

3) Bezier patch, using binary subdivision, with vertices and all values
precomputed and stored.

4) Bezier patch, vertices, all plane equations, normals at each vertex of
a subpatch are stored (to be used for a SMOOTH_TRIANGLE shading in each
of subpatch).

At some future date, other types of patches besides Bezier may be used. In
this case new values of Patch Type will be defined for them.

The value of "U Resolution" determines the number of steps along the
U parameter (row variable) that are taken when subdividing the patch.

The value of "V Resolution" determines the number of steps along the
V parameter (column variable) that are taken when subdividing the patch.

An example of a Bezier patch is:

BICUBIC_PATCH 1 4 4
< 0.0 0.0 2.0> < 1.0 0.0 0.0> < 2.0 0.0 0.0> < 3.0 0.0 -2.0>
< 0.0 1.0 0.0> < 1.0 1.0 0.0> < 2.0 1.0 0.0> < 3.0 1.0 0.0>
< 0.0 2.0 0.0> < 1.0 2.0 0.0> < 2.0 2.0 0.0> < 3.0 2.0 0.0>
< 0.0 3.0 2.0> < 1.0 3.0 0.0> < 2.0 3.0 0.0> < 3.0 3.0 -2.0>
END_BICUBIC

This is a patch that is interpolated by a 4x4 mesh of vertices. This is
subdivided into 2x4x4 = 32 triangles. This second subdivision into triangles
is algorithmic and occurs in two situatons, when the patch is parsed and when
intersections are being calculated. In addition the plane equation of all
32 triangles are stored so that intersection calculations can be optimized
a bit.

If the Patch Type were changed from 1 to 3, normal calculations based on the
normal to the patch at each of the mesh vertices would be used. This gives
the same shading effect that SMOOTH_TRIANGLE's have.

For example, the following patch definition has taken 16 co-planar points
arranged in the grid 0 <= x <= 1 && 0 <= y <= 1 && z = 0, and pulled two
corners down and two corners up along the z-axis. (See BEZIER.DAT.)

OBJECT
BICUBIC_PATCH 1 4 4
< 0.0 0.0 2.0> < 1.0 0.0 0.0> < 2.0 0.0 0.0> < 3.0 0.0 -2.0>
< 0.0 1.0 0.0> < 1.0 1.0 0.0> < 2.0 1.0 0.0> < 3.0 1.0 0.0>
< 0.0 2.0 0.0> < 1.0 2.0 0.0> < 2.0 2.0 0.0> < 3.0 2.0 0.0>
< 0.0 3.0 2.0> < 1.0 3.0 0.0> < 2.0 3.0 0.0> < 3.0 3.0 -2.0>
TEXTURE CHECKER COLOR RED 1.0 COLOR BLUE 1.0 ROTATE <90 0 0>
AMBIENT 0.1 DIFFUSE 0.9 PHONG 1 END_TEXTURE
END_BICUBIC
TRANSLATE <-1.5 -1.5 0>
SCALE <2 2 2>
ROTATE <30 -70 0>
BOUNDED_BY SPHERE <0 0 0> 6 END_SPHERE END_BOUND
END_OBJECT


STURMIAN SEQUENCES
------------------

There have been many improvements in calcluating 3rd and 4th order surfaces.
By default they are still computed the same was as previously, but there is
a new and better way: Sturmian Sequences! - these seem to cure the majority
of problems with math precision errors resulting in digital acne or outright
noise bursts in the QUARTIC shapes. The classic error-prone TEARDROP file
now runs beautifully! This takes care of some of the worst of the problems,
but seems to lead to occasional problems when the normal is calculated (the
surface is correct but the shading is sometimes a little off). The bad
shading isn't totally random either - it often makes sort of swirl patterns.
In order to use the Sturmian Sequence method, place the keyword STURM anywhere
after the end of the vectors inside a Cubic, Quartic or Bicubic Patch shape
definition.

Example:

OBJECT
QUARTIC
< 1.0 0.0 0.0 0.0 2.0 0.0 0.0 2.0 0.0 -104.0
0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0
1.0 0.0 0.0 2.0 0.0 56.0 0.0 0.0 0.0 0.0
1.0 0.0 -104.0 0.0 784.0 >
STURM { <-----<<< Must be placed before the END_ statement! <----<<<< }
END_QUARTIC
.
.
.
END_OBJECT


DECLARED CONSTANTS
------------------

Here are the various types of constants allowed by the DECLARE statement:

OBJECT_CONSTANT
SPHERE_CONSTANT
PLANE_CONSTANT
TRIANGLE_CONSTANT
SMOOTH_TRIANGLE_CONSTANT
QUADRIC_CONSTANT
POLY_CONSTANT (QUARTIC)
POLY_CONSTANT (CUBIC)
POLY_CONSTANT (POLY)
BICUBIC_PATCH_CONSTANT
CSG_INTERSECTION_CONSTANT
CSG_UNION_CONSTANT
CSG_DIFFERENCE_CONSTANT
COMPOSITE_CONSTANT
TEXTURE_CONSTANT
VIEW_POINT_CONSTANT
COLOUR_CONSTANT
VECTOR_CONSTANT
FLOAT_CONSTANT

Smile -

If you cannot afford a texture block, a default one will be appointed to you!