Objects
All geometry is typically specified in
object space. In
object space mode, enabled with
a setting in the options block,
the camera location is determined by its instance, all objects are defined in
local object
coordinates and positioned in the scene with their object
instances. Every object, camera,
or light requires an instance to be established in the scene for
rendering.
Deprecated In camera space mode, the
camera is fixed and assumed to
sit at the coordinate origin and point down the negative Z axis,
all objects are defined using camera space coordinates. Camera
space mode is supported only for backwards compatibility, and is
not recommended.
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 [xmin ymin zmin xmax ymax zmax] ]
[ motion box [xmin ymin zmin xmax ymax zmax] ]
[ 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, or setting it to
off
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).
- Note, that 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 scene options block specifies shadow
off.
- The shadow
mode allows to control shadowing details of the object.
It specifies whether the object casts shadows (1),
receives shadows (2), does both (3), or has no
impact on any shadows (
0
). The default is
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 mode must have casting enabled 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
scene options block specifies
trace off.
- The reflection mode controls if an object is visible in reflections on
other objects, and if it shows reflections of other objects:
1
enables reflection casting, 2
enables
reflection receiving, 3
enables both, and
0
disables both. Default is mode
2
.
-
Note, that casting reflections has an opposite meaning to
casting reflection rays: in order to cast
reflections or become visible in reflections on other
objects an object must receive reflection rays, and
to receive reflections or show reflections of other
objects an object has to cast reflection rays. The
mode controls casting and receiving the shading
effect, like in casting shadows.
- The refraction mode controls if an object is visible in refractions on
other objects, and if it shows other objects in refractions:
1
enables refraction casting, 2
enables
refraction receiving, 3
enables both, and
0
disables both. Default is mode
2
. Note, that casting means casting a
refraction, which is the opposite to casting a refraction
ray. See reflection mode notice
for details.
- The transparency mode controls if an object is visible in transparent
parts of other objects, and if it shows other objects in
transparent parts:
1
enables transparency casting,
2
enables transparency receiving, 3
enables both, and 0
disabled both. Default is
mode 3
. See refraction
mode for details.
- 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 point-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 output shaders) using the miQ_GEO_LABEL
query. 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 which casts irregular light patterns on the floor of a
swimming pool. To simulate this effect, the light source must emit
caustic photons and contain appropriate photon energy
settings, and the material
shader of the floor object needs to pick up caustic light
information. For optimized caustic generation, the rendering
options should specify
caustic 0
and the water surface
and floor objects must have the caustic flag set. Setting
this flag to off means that the object is hidden from
caustics alltogether. Caustics can be globally disabled in the
render options with caustic
off.
- The caustic mode
controls the interaction of caustics with the object:
1
enables caustic casting, 2
enables
caustic receiving, 3
enables both, and 0
disables both. 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 it defaults to 3
. If no
caustic keyword is given the mode defaults to
0
.
- The globillum on flag lets the object participate in
optimized generation of global illumination. Global illumination is
a lighting effect caused by diffuse interreflection, such as a red
table bleeding red color onto
an adjacent white wall. To simulate this effect, the material of both the table and the wall
must provide photon shaders,
the light source must emit globillum photons and contain
appropriate photon energy settings, and the material shader of the wall must pick
up global illumination light information. For optimized global
illumination simulation, the render options should specify
globillum 0
and the red table and white wall must have
the globillum flag set. Setting the flag to off
means that the object is hidden to global illumination photons, and on (the default)
enables global illumination interactions with this object. Global
illumination can be globally disabled in the render options with globillum
off.
- The globillum mode
controls the global illumination
interaction with the object:
1
enables global
illumination casting, 2
enables global illumination
receiving, 3
enables both, and 0
disables
both. The default mode can be specified in the options.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
with simplified geometry that resembles the first one with the
globillum but not the visible flag set. The
effect is that the rendered object appears in full detail but
simulation of global illumination is faster since a simpler object
representation is used.
- The finalgather on|off and
finalgather mode control final gathering for this
object. If set to off means that the object is hidden to
final gather rays, and on, the default, enables final
gathering illumination interactions with this object. The
mode
1
enables final gather illumination
casting. If the bit is not set but finalgather on is given
then finalgather ray would be terminated by the object and return
black color. The mode 2
enables final
gather illumination receiving, 3
enables both, and
0
disables both. 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 flag controls face culling for the object.
The possible values are
'f' for front, 'b' for
back, and 'a' for both (all). If not
specified, the culling flag default of the options or the override
in the shader state will be 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 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. Displaced objects should always
specify a maximum displacement. The default is 0. Without max
displace mental ray will truncate any displacement to 0.0,
actually disabling displacement.
- A
max
displace
value that is too large generates correct images
but puts more pressure on memory and performance, since larger
areas of an object may be displaced, thus creating much more
triangles in longer time. In particular, mental ray may suffer
serious performance losses, even by an order of magnitude, if the
displaced object uses fine approximations. If the max
displace
value is too small, mental ray will limit the
absolute displacement to the max displace
value.
- The ray offset allows to enforce an offset for the
origin of secondary rays cast from the geometry, in world space
units. When a ray is traced, any intersections which are closer to
the emanating surface than the given offset value are
ignored. This can be useful to avoid self-intersections, especially
in situations where multiple, slightly different, tessellations of
the same geometry are used, like rasterized triangles for primary
visible rendering and approximate tessellations for ray
tracing.
- 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 render 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 are used. The defaults are -128
127, which disables per-object sampling limits. Note that this
setting is not used by the rasterizer.
- The shading samples controls per-object sampling for
the rasterizer. This will locally
override the global 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. Typically, this
is used to keep the global scene default low for performance
reasons, but boost the setting for selected objects or instances
only, to achieve the desired quality in the final rendering.
- The tag assigns a label number to the
object for identification. The number is an arbitrary 32-bit
integer value. The term label is normally used in mental ray
for this identifier, the keyword tag is retained for
backwards compatibility (a tag is used in shaders to
identify entries in the scene database). With an appropriate
output or framebuffer statement in the
camera it is possible
to let mental ray 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 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 final object from a separate file when mental ray hits the
bounding box of the object, also known as a placeholder
object. The placeholder object needs to specify a valid
box, optionally a motion box if the object has
motion vectors, and a max
displace setting if the object is displaced. The actual
geometry in the group ... end group block can 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 is
specified for the 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.
- The
group
contains the actual geometric
representation. Multiple object groups are supported for backwards
compatibility but deprecated; mental ray will automatically convert
a multi-group object to an instance group containing multiple
sub-objects. See object group 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 Group
Object groups contain the actual geometry. Common to all
geometry are vector lists and vertex lists.
Vector List
The vector list contains 3D vectors which 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 to increase translation and parsing speed when
ray is connected to a native translator; it should not be used in
files to be modified with text editors or filters, since they may
refuse to accept files containing binary data, or corrupt them.
Vertex List
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 optional 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 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
the following examples.
Example
The examples will use the simplest form of polygon syntax that will be described later
in this section.
Consider two triangles ABC and ABD sharing an edge AB. 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.
Geometry List
Various types of geometry can be contained in the geometry
list, like polygonal geometry, triangle lists, free-from and
subdivision surfaces. In the next sections the syntax of these
definitions is described in detail.
Approximation List
At the end of each object group
several approximation statements may be given
which control the tessellation of the geometry. In polygonal object
groups, the approximation is used only for polygons whose material
contains a displacement shader. Free-form and subdivision surfaces
are always controlled by their approximations. See approxomations for details.
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-2010 by
mental images GmbH