Previous
OBJECTs
blob
This object is a blob, that is to say a set of interacting meta-balls.
A blob is the isosurface of a three-dimensional
field, defined by the sum of spherical functions that possess maximum
absolute density at their center and zero density at their border.
For their nature blobs always enclose a solid volume.
- string "threshold", float density
Specify the threshold density value at which the surface is extracted.
- string "blob", vector3 center, float radius, float strength = 1.0
Specify a blob component.
box
This object is an axis aligned box.
- string "position", vector3 c1, vector3 c2
Specify two opposite corners of the box.
boundary
This object allows to define a boundary composed by many
surfaces.
If the boundary is closed it also defines a solid, which may be
used in boolean operations.
- string "surfaces", { object surface } | intarray surfaces
Specify the surfaces that form the boundary.
box
This object is an axis aligned box.
- string "position", vector3 c1, vector3 c2
Specify two opposite corners of the box.
bspline
This object is a bspline patch.
It is a complex type, and its explanation would require an
entire book.
This implementation is similar to the one described in: The
RenderMan Companion, from Addison Wesley [6].
Bspline objects are rendered using the surface-engine.
To understand how to optimize rendering
correctly, you'd better see the documentation of the
"surface-engine" interface.
- string "tolerance", float low-tolerance, float hi-tolerance, float expansionfactor
Specify the maximum size of the faces that are used to
approximate the surface.
The surface-engine works in two stages: in the first phase it
splits all the geometry in faces smaller than hi-tolerance, in
order to obtain a global but rough approximation of the entire
surface, while in the final phase, that is performed at
run-time during ray-tracing, it refines only the faces that are going
to be hit by the current ray, so that their size is less than
low-tolerance.
expansionfactor has a complex analytical meaning: it is the
necessary expansion factor that is to be applied to the minimal
sphere that contains two arbitrary points of the surface, in order to
contain all the surface segment connecting those points (for
surface segment we mean the segment defined in uv coordinates).
For example if two points have a distance of d, and we
know that the sphere containing the segment formed by them
have a diameter of d*(1+e), in order to make the surface render
correctly we have to specify an expansion factor of
e.
In practice this value may not be known a priori, since
we do not always possess the analytical description of the
surface, which may also be the result of very complex
displacement patterns, but we may obtain this value by trials
and by a bit of good sense.
For example we know this value is 0 for
planar surfaces, and making some simple geometric
considerations we may find it is 0 also for spheres.
Then we may notice that an expansion factor equal to or
greater than 1 is needed only for surfaces with infinite area, even
if with finite volume: such surfaces should have fractal peaks
at all scales.
So we have already reduced our research field to the range [0,1[.
Here you can easily search a good value by bisection.
Obviously the smaller this value is, the faster the rendering
times.
- string "subdivision", int min, int max
Specify the minimum and maximum recursion depth in the surface
subdivision process that produces the final tessellation.
The max value should not be much larger than the min value,
otherwise geometry caching would perform poorly. It would
be better to keep (max - min) < 4.
The default values are 3 and 6 respectively.
- string "curvature", float c
Specify the maximum allowed curvature for the final tessellation. If a region has a greater
curvature it is subdivided recursively.
- string "size", int usize, int vsize
Specify the size of the patch as the number of control points
in the U and V directions.
- string "step", int ustep, int vstep
Specify the U-V steps for the evaluation window.
Predefined values are: BezierStep(), BSplineStep(), CatmullRomStep() and
HermiteStep(), according to the specified basis.
- string "wrap", int uwrap, int vwrap
Specify if the surface is wrapped on the U-V directions.
- string "basis", matrix4 ubasis, matrix4 vbasis
Specify the U-V matrices for the bspline bases.
Predefined values are: BezierBasis(), BSplineBasis(), CatmullRomBasis() and
HermiteBasis().
- string "points", vector3array | vector4array points
Specify the control points as a monodimensional array of
U-rows of points.
The points may be four dimensional, and in this case they are
interpreted as homogenous coordinates, producing a rational surface.
- string "region",
(vector2 c1, vector2 c2) |
(float minu, float minv, float maxu, float maxv)
Specify the visible region of the surface.
The parametric domain is [0,1] x [0,1].
- string "texture",
(vector2 c1, vector2 c2, vector2 c3, vector2 c4) |
(float u1, float v1, float u2, float v2, float u3, float v3, float u4, float v4)
Specify the texture coordinates at the four corners of the surface.
- string "trimmer", trimmer trim
Specify the trimmer that is used to trim the visible region of
the surface.
cone
This object is an open cone with the apex pointing in the Z
direction, and the base on XY plane.
- string "radius", float r
Specify the radius of the base of the cone.
- string "height", float h
Specify the height of the cone.
- string "region",
(vector2 u, float maxv, ) |
(float minu, float maxu, float maxv)
Specify the visible region of the surface.
The U parametric direction defines the angle of rotation around
the Z axis.
V isolines define the circles from the base to the apex.
The parametric domain is [0,1] x [0,1].
The region is specified by the minimum and maximum U and by the maximum V.
This means that the cone always starts from its base, even if
it may be truncated before the apex, and only an arc may
be visible.
- string "texture",
(vector2 c1, vector2 c2, vector2 c3, vector2 c4) |
(float u1, float v1, float u2, float v2, float u3, float v3, float u4, float v4)
Specify the texture coordinates at the four corners of the surface.
cylinder
This object is an open cylinder parallel to the Z axis, with the
base on the XY plane.
- string "radius", float r
Specify the radius of the base of the cylinder.
- string "height", float h
Specify the height of the cylinder.
- string "region",
(vector2 u) |
(float minu, float maxu)
Specify the visible region of the surface.
The U parametric direction defines the angle of rotation around
the Z axis.
V isolines define the circles from one base to the other.
The parametric domain is [0,1] x [0,1].
The region is specified by the minimum and maximum U, so that
only an arc may be visible.
- string "texture",
(vector2 c1, vector2 c2, vector2 c3, vector2 c4) |
(float u1, float v1, float u2, float v2, float u3, float v3, float u4, float v4)
Specify the texture coordinates at the four corners of the surface.
disc
This object is a flat disc on the XY plane.
- string "radius", float r
Specify the radius of the base of the cylinder.
- string "hole", float h
Specify the radius of an optional hole at the center of the disc.
- string "region",
(vector2 u) |
(float minu, float maxu)
Specify the visible region of the surface.
The U parametric direction defines the angle of rotation around
the Z axis.
V isolines define the circles from the center to the border.
The parametric domain is [0,1] x [0,1].
The region is specified by the minimum and maximum U, so that
only an arc may be visible.
- string "texture",
(vector2 c1, vector2 c2, vector2 c3, vector2 c4) |
(float u1, float v1, float u2, float v2, float u3, float v3, float u4, float v4)
Specify the texture coordinates at the four corners of the surface.
hfield
This object is a height-field.
In practice it is a square patch, parallel to the X-Y axes, with
varying heights on the Z axis.
It may be used to model geographical landscapes or to represent
real functions of two variables.
- string "size", int usize, int vsize
Specify the number of control points in the U and V directions.
- string "points", floatarray points
Specify the height at each point of the height field.
The values are stored in a monodimensional array made by
concatenating all the U-rows. The size of the array must be usize x vsize.
- string "texture",
(vector2 c1, vector2 c2, vector2 c3, vector2 c4) |
(float u1, float v1, float u2, float v2, float u3, float v3, float u4, float v4)
Specify the texture coordinates at the four corners of the surface.
mesh
This object is a polygonal mesh, with convex faces.
The representation is the standard one, with separate lists for
points, normals, texture coordinates and faces.
- string "points", vector3array | floatarray array
Specify the list of points.
Points may be represented as vectors or floats. If floats
are used their number must be a multiple of 3.
- string "normals", vector3array | floatarray array
Specify the list of normals.
Normals may be represented as vectors or floats. If floats
are used their number must be a multiple of 3.
- string "textures", vector2array | floatarray array
Specify the list of uv texture coordinates.
Texture coordinates may be represented as vectors or floats. If floats
are used their number must be a multiple of 2.
- string "faces", int nf, intarray nv,
intarray p, , intarray n, , intarray t
Specify the list of faces.
nf is the number of faces
nv is the array that specifies the number of vertices of each
face, that is to say nv[i] is the size of the i-th face.
p is the array of points, represented as indices in the list
of points of the mesh.
n is the array of normals, represented as indices in the list
of normals of the mesh.
t is the array of textures, represented as indices in the list
of texture coordinates of the mesh.
Each face must be convex.
- string "file", string filename, int index
Specify a mesh-file to load the mesh from.
A mesh-file can contain many meshes: index specify which mesh
to load.
Here is the description of the mesh-file structure:
long nm = number of meshes
for each mesh :
long np = number of points
long nn = number of normals
long nt = number of texture coordinates
long nf = number of faces
long nvtot = total number of vertices, given by the sum
of the number of vertices of each face
for each mesh :
float p[np*3] = points
float n[nn*3] = normals
float t[nt*2] = texture coordinates
long nv[nf] = number of vertices of each face
long fp[nvtot] = faces' points (as indices)
long fn[nvtot] = faces' normals (as indices)
long ft[nvtot] = faces' texture coordinates (as indices)
(both floats and longs have 32 bits of precision)
nurbs
This object is a nurbs patch.
It is a complex type, and its explanation would require an
entire book.
This implementation is similar to the one described in: The
RenderMan Companion, from Addison Wesley [6].
Nurbs objects are rendered using the surface-engine.
To understand how to optimize rendering
correctly, you'd better see the documentation of the
"surface-engine" interface.
- string "tolerance", float low-tolerance, float hi-tolerance, float expansionfactor
Specify the maximum size of the faces that are used to
approximate the surface.
The surface-engine works in two stages: in the first phase it
splits all the geometry in faces smaller than hi-tolerance, in
order to obtain a global but rough approximation of the entire
surface, while in the final phase, that is performed at
run-time during ray-tracing, it refines only the faces that are going
to be hit by the current ray, so that their size is less than
low-tolerance.
expansionfactor has a complex analytical meaning: it is the
necessary expansion factor that is to be applied to the minimal
sphere that contains two arbitrary points of the surface, in order to
contain all the surface segment connecting those points (for
surface segment we mean the segment defined in uv coordinates).
For example if two points have a distance of d, and we
know that the sphere containing the segment formed by them
have a diameter of d*(1+e), in order to make the surface render
correctly we have to specify an expansion factor of
e.
In practice this value may not be known a priori, since
we do not always possess the analytical description of the
surface, which may also be the result of very complex
displacement patterns, but we may obtain this value by trials
and by a bit of good sense.
For example we know this value is 0 for
planar surfaces, and making some simple geometric
considerations we may find it is 0 also for spheres.
Then we may notice that an expansion factor equal to or
greater than 1 is needed only for surfaces with infinite area, even
if with finite volume: such surfaces should have fractal peaks
at all scales.
So we have already reduced our research field to the range [0,1[.
Here you can easily search a good value by bisection.
Obviously the smaller this value is, the faster the rendering
times.
- string "subdivision", int min, int max
Specify the minimum and maximum recursion depth in the surface
subdivision process that produces the final tessellation.
The max value should not be much larger than the min value,
otherwise geometry caching would perform poorly. It would
be better to keep (max - min) < 4.
The default values are 3 and 6 respectively.
- string "curvature", float c
Specify the maximum allowed curvature for the final tessellation. If a region has a greater
curvature it is subdivided recursively.
- string "size", int usize, int vsize
Specify the size of the patch as the number of control points
in the U and V directions.
- string "degree", int udeg, int vdeg
Specify the U-V degrees of the nurbs surface.
- string "points", vector3array | vector4array points
Specify the control points as a monodimensional array of
U-rows of points.
The points may be four dimensional, and in this case they are
interpreted as homogenous coordinates, producing a rational surface.
- string "knots", floatarray uknots, floatarray vknots
Specify the U-V knot vectors.
The size of the knot vectors should be usize + udegree + 1 and
vsize + vdegree + 1 respectively.
- string "region",
(vector2 c1, vector2 c2) |
(float minu, float minv, float maxu, float maxv)
Specify the visible region of the surface.
The parametric domain is directly determined by the knot vectors.
- string "texture",
(vector2 c1, vector2 c2, vector2 c3, vector2 c4) |
(float u1, float v1, float u2, float v2, float u3, float v3, float u4, float v4)
Specify the texture coordinates at the four corners of the surface.
- string "trimmer", trimmer trim
Specify the trimmer that is used to trim the visible region of
the surface.
patch
This object is a bilinear patch.
A bilinear patch is the surface formed connecting two lines by
linear interpolation. The edges of this surface are always
straight lines, but the interior may be non planar.
In particular if the two original lines are not coplanar
the resulting patch is a piece of hyperboloid.
- string "points", vector3 p1, vector3 p2, vector3 p3, vector3 p4
Specify the four control points.
You can imagine the patch to be the surface that connects the
two edges p1-p2 and p3-p4, or equivalently p1-p3 and p2-p4.
Note that the control points are not connected sequentially:
the resulting polygon is p1-p2-p4-p3.
- string "normals", vector3 n1, vector3 n2, vector3 n3, vector3 n4
Specify the normals at the four control points.
If you do not set them the real geometric normals are used.
- string "texture",
(vector2 c1, vector2 c2, vector2 c3, vector2 c4) |
(float u1, float v1, float u2, float v2, float u3, float v3, float u4, float v4)
Specify the texture coordinates at the four corners of the surface.
solid
This object is a solid resulting from a boolean operation between
two different objects.
- string "type", string operation
Specify the type of boolean operation.
Valid types are:
- "union" : joins the two objects
- "difference" : subtracts the second object from the first
- "intersection" : intersects the two objects
- string "solids", object o1, object o2
Specify the two objects involved in the boolean operation.
These two objects must have a well defined interior, and so
their surface must be closed.
- string "closure", int switch
Specify if the resulting solid is closed (switch = 1) or open
(switch = 0).
This attribute affects only intersections and differences: in
these cases if it is set to 0 the surface of the second object
will not be visible, leaving an open side.
sphere
This object is a sphere centered in the local origin.
- string "radius", float r
Specify the radius of the sphere.
- string "region",
(vector2 minuv, vector2 maxuv, ) |
(float minu, float minv, float maxu, float maxv)
Specify the visible region of the surface.
The U parametric direction defines the angle of rotation around
the Z axis.
V isolines define the circles between the south and north poles.
The parametric domain is [0,1] x [0,1].
- string "texture",
(vector2 c1, vector2 c2, vector2 c3, vector2 c4) |
(float u1, float v1, float u2, float v2, float u3, float v3, float u4, float v4)
Specify the texture coordinates at the four corners of the surface.
surface-engine
This object is an advanced type that allows to handle very large sets of generic
parametric surfaces, with accurate displacement mapping.
It is very useful when rendering complex models defined by a
great number of triangles that after displacement mapping assume
curved shapes.
The surface-engine is highly optimized to handle quantities of
geometry that exceed the physical memory. To do this it
implements a powerful caching mechanism, that can be controlled
using the "surface-engine" interface.
- string "tolerance", float low-tolerance, float hi-tolerance, float expansionfactor
Specify the maximum size of the faces that are used to
approximate the surface.
The surface-engine works in two stages: in the first phase it
splits all the geometry in faces smaller than hi-tolerance, in
order to obtain a global but rough approximation of the entire
surface, while in the final phase, that is performed at
run-time during ray-tracing, it refines only the faces that are going
to be hit by the current ray, so that their size is less than
low-tolerance.
expansionfactor has a complex analytical meaning: it is the
necessary expansion factor that is to be applied to the minimal
sphere that contains two arbitrary points of the surface, in order to
contain all the surface segment connecting those points (for
surface segment we mean the segment defined in uv coordinates).
For example if two points have a distance of d, and we
know that the sphere containing the segment formed by them
have a diameter of d*(1+e), in order to make the surface render
correctly we have to specify an expansion factor of
e.
In practice this value may not be known a priori, since
we do not always possess the analytical description of the
surface, which may also be the result of very complex
displacement patterns, but we may obtain this value by trials
and by a bit of good sense.
For example we know this value is 0 for
planar surfaces, and making some simple geometric
considerations we may find it is 0 also for spheres.
Then we may notice that an expansion factor equal to or
greater than 1 is needed only for surfaces with infinite area, even
if with finite volume: such surfaces should have fractal peaks
at all scales.
So we have already reduced our research field to the range [0,1[.
Here you can easily search a good value by bisection.
Obviously the smaller this value is, the faster the rendering
times.
- string "subdivision", int min, int max
Specify the minimum and maximum recursion depth in the surface
subdivision process that produces the final tessellation.
The max value should not be much larger than the min value,
otherwise geometry caching would perform poorly. It would
be better to keep (max - min) < 4.
The default values are 3 and 6 respectively.
- string "curvature", float c
Specify the maximum allowed curvature for the final tessellation. If a region has a greater
curvature it is subdivided recursively.
- string "surfaces", { object surface } | objectarray surfaces
Specify the set of objects whose surface is to be rendered.
These objects must have a well defined parametric surface, so they
should not be composite objects, like boundaries or solids
resulting from boolean operations.
triangle
This object is a triangle.
- string "points", vector3 p1, vector3 p2, vector3 p3
Specify the three corners of the triangle.
- string "normals", vector3 n1, vector3 n2, vector3 n3
Specify the normals at the three corners of the triangle.
If you do not set them the real geometric normal is used.
- string "texture",
(vector2 c1, vector2 c2, vector2 c3) |
(float u1, float v1, float u2, float v2, float u3, float v3)
Specify the texture coordinates at the three corners of the surface.