Objects
All geometry is specified in either camera space or object space, depending on the corresponding
statement in the options statement
(see section options). In camera
space mode, the camera is
assumed to sit at the coordinate origin and point down the negative
Z axis, and objects are defined using camera space coordinates. In
object space mode, the camera
location is determined by its instance, and objects are defined in
local object
coordinates that are positioned in the scene with its object
instance. Every object, camera,
and light requires an instance. Camera space mode is only used for
backwards compatibility with mental ray 1.x, and is now obsolete
and not recommended. All existing integrations of mental ray on the
market use object space exclusively.
The appearance of the object, such as color and transparency, is
determined by naming materials in the object definition. Before a
material can be used in an
object, it must be defined. Naming the material determines all
aspects of the object's appearance. No further parameters,
textures, or lights need to be specified; they are all part of the
material definition.
The two most common approaches to materials and objects are to
name all materials first and then all objects, which may simplify
the implementation of material editors because all materials may be
put in a separate file and then included in the .mi file
using a $include command; or materials and objects may be
interspersed. Either way, each material definition precedes its
first use.
All polygonal and free-form surface objects have the same common
format in the .mi file:
object "object_name"
[ visible [on|off] ]
[ shadow [on|off] ]
[ shadow [mode] ]
[ shadowmap [on|off] ]
[ trace [on|off] ]
[ reflection mode ]
[ refraction mode ]
[ transparency mode ]
[ select [on|off] ]
[ tagged [on|off] ]
[ caustic on|off ]
[ globillum on|off ]
[ finalgather on|off ]
[ caustic [mode] ]
[ globillum [mode] ]
[ finalgather mode ]
[ finalgather file file (list) ]
[ face [front|back|both] ]
[ box [min_x min_y min_z max_x max_y max_z] ]
[ motion box [min_x min_y min_z max_x max_y max_z] ]
[ max displace value ]
[ ray offset value ]
[ samples min max ]
[ shading samples samplesscalar ]
[ data null|"data_name" ]
[ tag label_numberint ]
[ file "file_name" ]
[ basis list ]
group
vector list
vertex list
geometry list
approximation list
end group
end object
The individual parameters are:
- The object name
object_name serves to uniquely identify the object. The name
is not used by mental ray in any form except to give meaningful
progress reports and error messages. Object names should be
enclosed in double quotes to disambiguate them from reserved
words.
- The visible flag
causes the object to be visible. Most objects will have this flag
set. Not setting it will make the object invisible to primary rays (those originating from
the camera), which means it will
disappear from the image. The optional boolean argument defaults to
on. If no trace statement is present, it defaults
to off (this is also true for all other boolean flags).
-
In mental ray 3.2, transparency
rays will also hit objects marked visible. In this
case, transparency is not considered a special case of refraction,
but as a scanline rendering feature. This apparent inconsistency
permits using transparency effects even if ray tracing is turned off altogether.
More importantly, it also keeps objects that have the
visible flag but not the trace flag out of the
BSP tree that is used to accelerate ray tracing, which has a
significant performance impact. This tradeoff can become very
significant for large scenes.
- The shadow flag
causes the object to cast shadows. The standard case is specifying
both the visible and shadow flags. If an object
is very complex, it may be desirable to set only the
visible flag but not the shadow flag, and create
a second object that resembles the first one but is much simpler
and set the shadow but not the visible flag on
it. The effect is that the object appears unchanged, but shadow
calculations see a much simpler shadow object that casts
approximately the same shadow as the primary visible object would.
Shadows are globally disabled if the options block specifies shadow
off. In mental ray 3.4 the shadow mode specifies whether the
object casts shadows ( mode 1), receives shadows (
mode 2) or both ( mode 3). The default is mode
2.
- The shadowmap flag controls whether an object can cast a shadowmap.
The default is on. For an object to cast shadowmap shadows, the
shadow cast flag (mode 1) must be on as well. This flag is
useful for transparent volume bounding objects called hull objects, such as visible light cones,
that are fully transparent but should not cast shadows.
- The trace flag
serves a similar purpose as the shadow flag. Normally, it
is always set along with the visible and shadow
flags. It controls whether the object is visible to secondary
(reflected or refracted) rays. If the reflecting or refracting
objects are fuzzy or only slightly reflective or refractive, it may
result in a considerable speedup to make the reflection and refraction rays see a much simpler
object than primary rays would. Like with the shadow flag,
this is achieved by not setting the trace flag in the
primary, high-definition object, and create a second one that
roughly resembles the primary object that has the trace
flag (and perhaps the shadow flag) but not the
visible flag set. Ray tracing is globally disabled if the
options block specifies
trace off.
- The reflection flag controls whether the object is visible to
reflection rays: 1 enables reflection casting, 2 enables reflection
receiving, 3 enables both, and 0 neither. Default is mode 2.
Note that "casting" is used in the sense of becoming visible in a
reflective surface", not as in "casting a ray". This is similar to
"casting a shadow".
- The refraction flag controls whether the object is visible to
refraction rays: 1 enables refraction casting, 2 enables refraction
receiving, 3 enables both, and 0 neither. Default is mode 2.
Again, "casting" means "casting a refraction", which is the
opposite from "casting a refraction ray".
- The transparency flag controls whether the object is visible to
transparency rays: 1 enables transparency casting, 2 enables
transparency receiving, 3 enables both, and 0 neither. Default is
mode 3. Once again, "casting" means "casting a transparency
image", which is the opposite from "casting a transparency
ray".
- The select flag makes the object subject to
select-tracing. This feature is used by some applications to
perform interactive object picking by sending a ray into the scene
(perhaps where a user clicked the mouse) and receiving a list of
objects visited by the ray. Only objects with the select
flag will appear in this list.
- The tagged
flag changes the way geometry
is stored. Normally, every polygon, surface, and triangle comes
with its own optional material. If an object specifies no
materials, the material is inherited from the instance. Objects
marked tagged do not store materials at all and always
rely on the inherited instance material, and permit specifying a
non-optional label integer in place of the material in polygon and
surface definitions. (Non-optional means that a tagged object
must contain one label integer for every polygon and
surface.) This label can be accessed by shaders during rendering
(not in displacement or output shaders) using the
miQ_GEO_LABEL mode of the mi_query function. The idea is that
a shared material distinguishes parts of the object by label
integer, instead of attaching a different material to each polygon
or surface.
- The caustic on flag lets the object participate in
optimized generation of caustics. A caustic is an illumination
effect caused by light that undergoes specular reflections or
refractions before it hits a diffuse object. For example a water
surface casts irregular light patterns on the floor of a swimming
pool. To simulate this effect, the material shader of the floor object
must be written to pick up caustic light, and the light source must
contain a caustic photon statement and contain appropriate
photon energy settings. For optimized caustic generation, the
options should specify caustic 0 and the water surface and floor
objects must have the caustic flag set. Caustics are
globally disabled if the options
block specifies caustic off.
-
The mode argument controls the caustic operation: 1
enables caustic casting, 2 enables caustic receiving, 3 enables
both, and 0 neither. off means that the object is
invisible to caustic photons, and 'on' is the same as 3. In the
pool example, the water surface should have mode 1 and the
floor should have mode 2. If the caustic keyword is
given without mode argument, the mode defaults to 3.
If no caustic keyword is given, caustics default to
mode 0.
- The globillum on flag lets the object participate in
optimized generation of global illumination. Global illumination is
an illumination effect caused by diffuse interreflection, such as a
red table bleeding red color
onto an adjacent white wall. To simulate this effect, the material shader of both the table and
the wall must specify photon
shaders, the wall object material shader must be written to pick
up global illumination light, and the light source must contain
appropriate photon energy settings. For optimized global
illumination simulation, the options should specify globillum 0 and
the red table and white wall must have the globillum flag
set. Global illumination is globally disabled if the options block specifies globillum
off.
-
The mode argument controls the global illumination mode: 1 enables
global illumination casting, 2 enables global illumination
receiving, 3 enables both, and 0 neither. The default is specified
by the options. off means
that the object is invisible to global illumination photons, and on (the default)
enables global illumination interactions with this object. In the
table example, the red table should have (at least) mode 1
and the white wall should have (at least) mode 2. If the
globillum keyword is given without mode argument,
the mode defaults to 3).
-
If an object is very complex, it may be desirable to set only
the visible flag but not the globillum flag, and
create a second object that resembles the first one but is much
simpler and set the globillum but not the visible
flag on it. The effect is that the object appears unchanged, but
simulation of global illumination is faster since a simpler object
is used.
- The finalgather on|off and
finalgather mode arguments control
the final gathering. off means that the object is
invisible to final gather rays, and on (the default)
enables final gathering illumination interactions with this object.
mode: 1 enables final gather illumination casting (if the
bit is not set, but the finalgather on is active,
finalgather ray would be terminated by the object and return black
color), 2 enables final gather illumination receiving, 3 enables
both, and 0 neither. Default is mode 0.
- The finalgather file file (list)
argument allows to specify a file name or a list of file names with
finalgather map(s) to be used for the object. If identical file
names or file name lists are used for several objects, only one
copy of finalgather map will be kept in memory.
- The face statement controls face
culling. The possible values
are 'f' (front), 'b' (back), and 'a'
(all). If not specified, the culling flag given in the options or
in the state is used.
- The box statement specifies a bounding box for the
object, in the space of the object. For polygons, this is easy to
compute: the box components are simply the smallest ( min)
and largest ( max) point-in-space ( v) vector
components. For free-form surfaces, the box can in principle be
derived in the same way; however, such a box would often be much
too large, especially for NURBS. Boxes that are too large are legal
but inefficient. If the box statement is omitted, mental ray will
compute one from all vertices, which is also not very efficient.
Boxes are required if the object is demand-loaded. The box should
not include enlargement caused by displacement or motion.
- The motion box is similar to the box, but contains the
minimum and maximum components of all motion vectors. Note that this is not the
same as the smallest and largest vector; the motion box vectors are
pieced together from the individual smallest and largest motion
vector components. A motion box must be specified if the
object has both a box and motion vectors.
-
The max displace statement specifies the
maximum allowed displacement applied to object control points in
local object space in normal direction. If a displacement shader
returns a value grater than value, the rendered geometry may
appear clipped and a warning is printed. If maxdisplace is
omitted but the object is displaced, mental ray 3.0 prints a
warning and tessellates the object immediately, which results in
correct images but is not very efficient. Displaced objects should
always specify a maximum displacement. mental ray 3.1 and higher do
not pretessellate and may truncate the displacement to 0.0, which
causes it to disappear.
-
A value that is too large generates correct images but puts more
pressure on the cache, so rendering may use more memory and run
more slowly. In particular, mental ray 3.1 and higher may suffer
serious performance losses, easily by an order of magnitude, if the
displaced object uses fine approximations. If the
maxdisplace value is too small, mental ray 3.0 may clip parts of
the object; mental ray 3.1 and higher always limit the absolute
displacement to the maxdisplace value.
- The ray offset statements gives the ability to specify
offsets for secondary rays cast from the geometry. When a ray is
traced, any intersections which are closer to the emanating surface
than the given offset value, are ignored. The offset value
is interpreted in world space units. This can be useful in order to
avoid self-intersections, especially in situations where multiple,
slightly different, tessellations of the same geometry are
used.
- The samples statement controls per-object oversampling. For all pixels that
touch this object, the normal samples range specified in the
options block is constrained to
the min max range, such that at least 2min and at most 2max samples are taken. Constraints that
exceed the min and max limits in the options block are ignored, so that the
options can be used to force quick preview rendering without having
to change all object sampling specifiers. If the pixel touches
multiple objects, perhaps due to reflection or refraction, the
highest min and the highest max are used. If the
pixel touches no objects at all, the default limits defmin
and defmax defined in the options block are used. The defaults are
-128 127, which disables per-object sampling limits. Note that this
setting is not used by the rasterizer.
- When rendering with the rasterizer mode, it is possible to specify
the number of shading samples to be used on a per-object basis.
This will locally override the setting in the render options. It is
also possible to specify this setting per-instance, if needed, but
the instance setting will override the object setting, when both
are present. Overriding the option setting would normally be done
to keep the scene settings low, to keep rendering times down, but
boost the quality of the rendering of one or more objects or
instances, to achieve the required quality in the final image.
- The tag specifies an arbitrary 32-bit number that
identifies the object. mental ray normally uses the term
label, but the keyword tag is retained for
backwards compatibility. The term tag is used by mental ray
to identify entries in the scene database; this is of concern only
to shader writers. By specifying an appropriate output
statement in the camera (see above), it is possible to
cause mental ray to write a label file that, for each pixel,
contains the label code of the object that the camera ray hits
first. Exactly which label is stored is under the control of the
material shader; using the label of the foremost object regardless
of reflections and refractions is merely the default behavior.
- The data statement attaches user data to the object. The argument must be
the name of a previously defined data element in the scene file. If
null is specified instead of a data element name, a
previously existing data reference is removed.
-
The file statement can be used to load the object from
a file when mental ray enters its bounding box. A box
statement, and also a motion box statement if the object
has motion vectors and a max
displace statement if the object is displaced, must be given
too. The actual geometry in the group ... end group block
must be omitted. The specified file must contain an exact copy of
the object, except that the file statement is replaced
with the group ... end group block and the
incremental keyword must be specified before
object. The object may have only a single object group. Demand-loaded objects are
useful to avoid parsing and permanently storing large objects that
may or may not be required for rendering. The -echo explode
command-line option can be used to automatically create demand-loaded
object files.
-
The basis list is a list of bases to be used in free-form surface descriptions. Only
curves and surfaces use bases. For
a list of supported bases, see section basis. The defined bases can be used in all
groups that follow, until the end of the object.
-
Finally, an object groups
contains the actual geometric representation. Multiple object
groups are supported for backwards compatibility with mental ray
1.9, but not recommended; mental ray 2.x and 3.x will automatically
convert a multigroup object to an instance group containing
multiple sub-objects.
-
At the end of each object
group, approximation
statements can be given that control the tessellation method. In
polygonal object groups, the approximation is used only for
polygons whose material contains a displacement shader. Free-form
surfaces are always controlled by their approximations; see page
approx for details.
The visible, shadow, trace,
reflection, refraction, transparency,
caustic, globillum, finalgather and
face flags can be overridden by the instance using the
standard inheritance mechanism.
Instances can specify that a flag in the instanced object is turned
on or off, or that it is left unchanged. The object flags are used
only if all the instances from the root of the scene DAG down to the object all
leave the flag unchanged.
Object groups contain the
actual geometry. All geometry
needs vector lists and vertex lists. The vector
list contains 3D vectors that
can describe points in space, normals, texture vertices, basis
vectors, motion vectors, and others. Vectors are anonymous, they
are triples of floating-point numbers separated by whitespace without inherent meaning.
They are numbered beginning with 0. Numbering restarts at 0
whenever a new object group
starts.
mental ray also accepts a compressed binary format for vectors. Instead of three
floating-point numbers, a sequence of 12 bytes enclosed in
backquotes is accepted. These 12 bytes are the memory image of
three floats in IEEE 854 format, using big-endian byte order. This
format is intended for increasing translation and parsing speed
when ray is connected to a native translator; it should not be used
in files modified with text filters. Many filters and editors
refuse to accept files containing binary data, or corrupt them.
Vertices build on vectors.
In the .mi format, there is no syntactical difference
between polygon vertices and control points vertices for free-form
surfaces; both are collectively referred to as "vertices" in this
discussion. All vertices define a point in space and optional
vertex normals, motion vectors, derivatives, zero or more textures
and basis vectors, and user
vectors:
v indexint
[ n indexint ]
[ d indexint indexint [ indexint [ indexint indexint ] ] ]
[ t indexint [ indexint indexint ] ]
[ m indexint ]
[ u indexint
...
Polygon vertices may use all of these. Free-form surface control
points may use v and m only; the others are
either computed analytically or are specified in other ways as part
of the surface definition.
v
specifies the point in space,
n
specifies the vertex
normal vector (ignored
when the vertex is used as a curve or surface control point). A normal vector defines
the orientation (vertical) of the surface at this vertex.
m
specifies the motion vector.
mental ray 3.1 permits up to 15 m statements per
v statement for nonlinear motion paths. If multiple motion vectors are
specified, the shutter time interval 0..1 is equally subdivided,
and each motion vector specifies the motion from the origin
specified by the v vector to the corresponding point on
the path. In other words, multiple motion vectors do not form a
connected chain but a bundle of "rays" originating at the same
point v.
t
specifies a texture
vertex with an optional
X/Y basis vector pair
for bump map calculation. There
can be up to 64 t lines for any given v vertex.
(The texture and basis vectors are ignored when the vertex is used
as a curve or surface control point. Texture and basis information
for surfaces is defined using a "texture surface", described
below.)
d
specifies a first and/or second surface derivative. First derivatives
describe the UV parametric gradient of a surface; second
derivatives describe the curvature. mental ray can compute surface
derivatives analytically for free-form surfaces but not for
polygons because polygons have no inherent UV coordinate space.
Therefore, the d keyword must be used to define explicit
surface derivatives for polygons. If d is followed by two
indices they are taken to reference the first derivative d P
du and d P dv (with P being the point in space); if
three indices follow they are taken to reference the second
derivative d^2 P du^2, d^2 P dv^2, and d^2 P du
dv; and if five indices follow the first two describe the first
derivatives and the next three the second derivatives. Derivatives
are not used by mental ray, they are made available to shaders
only.
u
specifies a user
vector. No constraints are imposed on user vectors. mental ray
does not operate on them in any way, they are passed through with
the vertex and can be picked up by the shader.
Every vertex begins with a v statement and ends with
the next v statement or with the start of the geometry
description. All occurrences of index above reference the
vector list; 0 is the first vector in this group. References of
different types (for example, v and n) may not
reference the same vector. As stated before, all vectors are 3D. If
the third coordinate is not used (as is the case for 2D texture
vertices, for 2D curve control points, and for 2D surface special
points) it should be set to 0.0 by convention. If both the second
and third coordinates are unused (as is the case for 1D curve
special points), they should both be set to 0.0.
Vertices themselves are numbered independently of vectors. The
first vertex in every group is numbered 0. The geometry description
is referencing vertices by vertex index, just like vertices are referencing
vectors by vector
index. This results in a three-stage definition of
geometry:
- List of vectors
- List of vertices
- List of geometry
The reason for this three-stage process is that it allows both
sharing vectors and sharing vertices. This is best illustrated with
an example. Consider two triangles ABC and ABD sharing an edge AB.
(This example will use the simplest form of polygon syntax that will be described later
in this section.) The simplest definition of this two-triangle
object is:
object "twotri"
visible
group
0.0 0.0 0.0
1.0 0.0 0.0
0.0 1.0 0.0
1.0 0.0 0.0
1.0 1.0 0.0
0.0 1.0 0.0
v 0
v 1
v 2
v 3
v 4
v 5
p "material_name" 0 1 2
p 3 4 5
end group
end object
The first three vectors are used to build the first three
vertices, which are used in the first triangle. The remaining three
vectors build the next three vertices, which are used for the
second triangle. Two vectors are listed twice and can be
shared:
object "twotri"
visible
group
0.0 0.0 0.0
1.0 0.0 0.0
0.0 1.0 0.0
1.0 1.0 0.0
v 0
v 1
v 2
v 1
v 3
v 2
p "material_name" 0 1 2
p 3 4 5
end group
end object
The order of vector references is noncontiguous to ensure that
the second triangle is in counter-clockwise order. Two vertices are
redundant and can also be removed by sharing:
object "twotri"
visible
group
0.0 0.0 0.0
1.0 0.0 0.0
0.0 1.0 0.0
1.0 1.0 0.0
v 0
v 1
v 2
v 3
p "material_name" 0 1 2
p 1 3 2
end group
end object
The need for sharing both vectors and vertices can be shown by
specifying vertex normals:
object "twotri"
visible
group
0.0 0.0 0.0
1.0 0.0 0.0
0.0 1.0 0.0
1.0 1.0 0.0
0.0 0.0 1.0
v 0 n 4
v 1 n 4
v 2 n 4
v 3 n 4
p "material_name" 0 1 2
p 1 3 2
end group
end object
In this last example, both vector sharing and vertex sharing
takes place. The normal in this example is actually redundant: if
no normal is specified, mental ray uses the polygon normal. Defaulting to the polygon
normal is slightly more efficient than interpolating vertex
normals, if vertex normals are explicitly specified.
Two types of geometry can be contained in the geometry
list, polygonal geometry and free-from surfaces. In the next
sections the syntax of the definitions of polygonal geometry and
free-form surfaces is described and illustrated by examples.
If the optional mental matter
product is available, objects can also contain subdivision surface geometry. Although
part of the standard mental ray grammar (see the appendix),
subdivision surfaces are not described in here. Refer to the mental
matter manual instead.
An object group permits only
one type of geometry, either
polygons or surfaces but not both. It is recommended that objects
contain only a single object group, so normally objects are either
polygonal or surface objects but not both at the same time. Also,
vector sharing is supported only for vectors of similar types
(point in space, normal, motion, texture, basis vector, derivative,
or user vector. A vector may not be referenced by vertices once as
a point in space and once as a normal, for example.
Copyright © 1986-2008 by
mental images GmbH