These are the functions supplied by the render modules of mental
ray, called RC*. All following trace
functions return miTRUE if any subsequent call of
a shader returned miTRUE to indicate presence of
illumination. Otherwise no
illumination is present and miFALSE is
returned. All trace functions
derive the state of the ray to be cast from the given state of the
parent ray. This state becomes the "child state"
that is passed to subsequent
shaders that are called by the trace function. The state is always
copied, and the given state is not modified except for the state
fields label, point, normal, dist and
motion. These fields are copied from the child state so that
the lens shader can access them in the state modified by
mi_trace_eye. After the
trace function returns, the caller may examine the child state (but
not the grandchild, which is gone if it ever existed). Volume
shaders get the same state as the previous (material) shader. Note
that all point and direction vectors passed as arguments to tracing
functions must be in internal space.
miBoolean mi_trace_eye(
miColor *result,
miState *state,
miVector *origin,
miVector *direction)
casts an eye ray from origin in direction, or
calls the next lens shader. If scanline
rendering is turned on and
state→scanline is not zero, origin and
direction must be the same as in the initial call of
mi_trace_eye, and the
lens shader may not modify them. Lens shaders that depend on
modifying ray origin and direction should be declared with the
trace on option. Origin and direction must be given in
internal space. This function may be used only in lens shaders.
Note that mi_trace_eye
stores origin and direction in
state→org and state→dir,
respectively, overwriting the previous values.
miBoolean mi_trace_reflection(
miColor *result,
miState *state,
miVector *direction)
casts a reflection ray from state→point to
direction. It returns miFALSE if the trace
depth has been exhausted or if the hit object has disabled
reflection receiving. If no intersection is found, the optional
environment shader is called. The direction must be given in
internal space. This function may be used only in shaders called
during image rendering, but not in displacement, geometry, photon,
or output shaders.
miBoolean mi_trace_refraction(
miColor *result,
miState *state,
miVector *direction)
casts a refraction ray from state→point to
direction. It returns miFALSE if the
trace depth has been exhausted or if the
hit object has disabled refraction receiving. If no intersection is
found, the optional environment
shader is called. Before this functions casts the refraction
ray, after copying the state, it copies
state→refraction_volume to
state→volume because the ray is now assumed to be
"inside" the object, so the volume
shader that describes the inside should be used to modify the
ray while traveling inside the object. It is the caller's
responsibility to set state→refraction_volume to
the camera's volume shader
state→camera→volume or some other volume
shader if it determines that the ray is now leaving the object. The
direction must be given in internal space.
If ray tracing has been disabled, mi_trace_refraction cannot modify the ray direction and operates like mi_trace_transparent. This function may be used only in shaders called during image rendering, but not in displacement, geometry, photon, or output shaders.
For rendering with the rasterizer, please see the discussion in the rasterizer section.
miBoolean mi_trace_transparent(
miColor *result,
miState *state)
Does the same as mi_trace_refraction
with dir == state→dir (that is, no change in the ray direction)
but may be executed faster if the parent ray is an eye ray. It also
works when ray tracing is
turned off, and considers visible as well as
trace objects. If the ray direction does not change
(because no index of refraction
or similar modification is applied), it is more efficient to cast a
transparency ray than a refraction ray. Like
mi_trace_refraction, this function
copies the refraction volume
shader to the volume shader because the ray is now assumed to
be inside the object. This function may be used only in shaders
called during image rendering, but not in displacement, geometry,
photon, or output shaders. The function returns
miFALSE and a transparent black color if the hit
object has disabled transparency receiving.
In rasterizer mode
mi_trace_transparent always
returns miFALSE and a transparent black color if no ray
has been traced yet. Since the rasterizer separates shading from
compositing, there is no object behind the current surface
at the time the material shader is called. The object behind
will be shaded at some other time, and both results are composited
long after the material shaders have returned. As long as the shader
uses standard linear composition for
mi_trace_transparent results,
returning black gives exactly the same result regardless of whether
rasterizer mode is in effect or not, the composition just happens
later. However, if the shader performs non-standard compositing, or
evaluates environments if
mi_trace_transparent returns
false, it must be modified to work properly with the rasterizer.
Shaders can detect if the rasterizer is enabled by testing
state→options→scanline == miRENDER_FH_RAST (or
state→options→scanline == 'r' which is identical).
In case rasterizer and ray tracing are both turned on,
state→scanline may be checked to determine if the current
intersection was found by the rasterizer (state→scanline != 0)
or ray tracing (state→scanline == 0).
miBoolean mi_trace_continue(
miColor * const result,
miState * const state)
Continues to trace the current ray in the same direction. Unlike
other trace calls, state→origin is not set to
state→point but remains unchanged,
state→type remains unchanged, and no new state is
created. There are no trace depth checks. Effectively, this call
pretends to the next intersection that the current intersection
never happened, although the shader that calls
mi_trace_continue does have the
option to manipulate the state and returned color. Care should be
taken because the state is not copied, so the next intersection
will have operated on state instead of
state→child, state→child is
left undefined. This function can be used to control object
visibility based on more complex criteria than the object
visible flag.
Unlike mi_trace_transparent, which will ignore the intersections happening very close to the origin of the transparency ray, mi_trace_continue guarantees that if there is another triangle coplanar to the hit triangle, then the other triangle will also be hit. The order with which the multiple coplanar triangles are hit is undefined.
miBoolean mi_trace_environment(
miColor *result,
miState *state,
miVector *direction)
casts a ray into the environment. The trace depth is not incremented or checked. The environment shader in the state is called to compute the color to be returned. The direction must be given in internal space.
miBoolean mi_trace_probe(
miState *state,
miVector *direction,
miVector *org)
Cast a ray into the scene just to check for intersections.
Casts a ray into the scene, starting at org with the direction
direction, both in internal space coordinates. If nothing is hit,
miFALSE is returned. If the ray hits another object,
miTRUE is returned and state→child is set
to the state that the material shader of the hit object would have seen.
However, unlike all other mi_trace_* functions, no shader is called.
Note, that the state state→child does not itself have a
state, so it cannot be used to call a material shader at the hit object
directly. This requires setting up an artificial "grandchild" state:
if (mi_trace_probe(state, &dir, &org)) {
miState grandchild;
state->child->child = &grandchild;
/* no texture, bump, or derivative vectors ! */
if (mi_call_material(&result, state->child))
/* use the result */
}
This sequence works roughly like
mi_trace_reflection, except that no
ray levels are tested, no environment is sampled, and no volume
shaders are called. Note that
mi_trace_probe will always return
miFALSE if ray
tracing is disabled.
If the start point of the ray is changed by modifying
state→origin before calling
mi_trace_probe, then
state→pri should be set to 0, and restored after
mi_trace_probe returns.
state→pri is used to prevent self-intersections,
which is not useful if the start point was modified and/or the
probe ray begins in empty space.
state→child data returned from
mi_trace_probe may be incomplete,
it does not contain any interpolated vectors for tex_list,
bump_x_list, bump_y_list, and derivs.
Note, that probe rays hit only objects that have any of the trace flags set. The reason for this is that visible-only objects don't need to be put into the ray tracing acceleration structures (like the BSP tree), which supports the model of separating high-resolution visible geometry from low-resolution trace geometry. This model is also supported by approximation flags and ray offsets.
miBoolean mi_trace_probe_x(
miState *state,
miVector *direction,
miVector *org,
miUint flags)
Cast a ray into the scene just to check for intersections with objects
carrying certain flags.
Works exactly like mi_trace_probe, with
the additional feature of respecting the object flags of the hit primitive.
The flags argument allows to pass any combination of trace flags
from the enumeration miTrace_flags. This function is typically
more efficient to find specific objects than tracing a regular probe ray and
checking the flags on the hit primitive afterwards.
miBoolean mi_sample_light(
miColor *result,
miVector *dir,
miScalar *dot_nl,
miState *state,
miTag light_inst,
miInteger *samples)
This function casts a light
ray from the light source to
the intersection point, causing the light source's
light shader to be called.
The light shader may then calculate
shadows by casting a
shadow ray to the intersection point.
This may cause shadow shaders
of occluding objects to be called, and will also cause the
volume shader of the state to be
called, if there is one. Before the light is sampled, the direction
from the current intersection point in the state to the light and
the dot product of this direction and the normal in the state are
calculated and returned in dir and dot_nl if
these pointers are nonzero. The direction is returned in internal
space. The light instance to sample must be given in
light_inst. samples must point to an integer
that is initialized to 0. mi_sample_light
must be called in a
loop until it returns miFALSE. *samples
will then contain the total number of light samples taken; it may
be larger than 1 for area light
sources.
For every call in the loop, a different dir and
dot_nl is returned because the rays go to different
points on the area light source. The caller is expected to use
these variables, the returned color, and other variables such as
diffuse and specular colors from the shader parameters to compute a
color. These colors are accumulated until
mi_sample_light returns
miFALSE and the loop terminates (leaving
dir and dot_nl undefined when returning
miFALSE). The caller then divides the accumulated color by the
number of samples ( *samples) if it is greater than 0,
effectively averaging all the intermediate results. See page
mtlshaderex for an example
of a shader using mi_sample_light.
When casting light rays with
mi_sample_light, mental
ray may check whether the primitive's normal is pointing away from
the light and ignore the light in this case. For this reason some
shaders, such as ray
marching volume shaders, should assign 0 to
state→pri first, and restore it before returning.
All mi_query modes that
return information on the intersected surface, such as
miQ_PRI_BBOX_MIN/MAX, miQ_NUM_TEXTURES,
miQ_GEO_LABEL, and miQ_GEO_DATA, do not
work if pri has been modified. Shaders that operate on a
surface such as material shaders may clear
state→normal instead, which disables the backside
light test but preserves the information on the current surface for
mi_query and
self-shadowing tests. (state→pri is an identifier
for the intersected "primitive" of the surface.)
Light instance tags to call this function with can be found
either in shader parameters of type light or
array light, or in the instance light list retrieved
with mi_instance_lightlist,
or in the global light list obtained from
mi_query.
This function works with light groups.
miBoolean mi_trace_light(
miColor *result,
miVector *dir,
miScalar *dot_nl,
miState *state,
miTag light_inst)
This function is a simpler variation of mi_sample_light that does not keep a sample counter, and is not called in a loop. It is equivalent to mi_sample_light except for area light sources. Area light sources must be sampled multiple times with different directions, which is not supported accurately by this function because it can only return a single direction and dot_nl. This function is provided for backwards compatibility with previous versions of mental ray, and should not be used for new projects.
miBoolean mi_trace_shadow(
miColor * const result,
miState * const state)
This function computes shadows for the given
light ray by casting
shadow rays. It is normally called from
a light shader to take
occluding objects that prevent some or all of the light emitted by
the light source to reach the illuminated point (whose
material shader has probably called the
light shader). The result color is modified by the
shadow shaders that are called
if occluding objects are found. Note that
light shaders can improve performance
by tracing shadow rays only if the contribution from the light is
greater than some threshold, for example because distance or angle
attenuation has left so little of the light color (less than
1 ⁄ 256, for example) that applying shadow
occlusion to this value is not going to make any difference. This
function returns miFALSE if full occlusion is
detected, that is, result is black or if the hit object
has shadow receiving disabled.
miBoolean mi_trace_shadow_seg(
miColor * const result,
miState * const state)
recursively calls the shadow
shader for the next shadow segment and returns its result, or
the result of the light shader
if there is no more shadow intersection. It does nothing if shadow
segments are turned off. It is used by shadow shaders only; light
shaders always use mi_trace_shadow.
See the introduction to shader types and the shadow shader explanation for
details on shadow modes. This function returns miFALSE
if full occlusion is detected, that is, result is
black.
miBoolean mi_continue_shadow_seg(
miColor * const result,
miState * const state)
This function allows a shadow
shader to continue tracing the exact same shadow segment that
triggered this shadow shader, which is effectively ignoring the
corresponding occluder. In other words, it allows to ignore
occluders on a per shadow segment basis. The next
shadow shader will be called as if the
previous intersection never existed.
mi_continue_shadow_seg leaves the
state unchanged from the perspective of the next shadow shader.
Like mi_trace_shadow_seg, this function
must be called by shadow shaders only. It returns
miFALSE if full occlusion is detected, that is,
result is black.
miBoolean mi_ray_offset(
miState *state,
double *offset)
All rays cast from this point on will begin a little distance
away from state→point, defined by
*offset. Objects closer than this distance will not be
hit by the ray. This is useful if there are low-resolution shadow
or trace standins (possibly created by
approximation flags) that are some
distance away: if the rays ignore very nearby other objects, they
cannot hit the low-resolution version, which avoids self-shadowing
or self-reflection, especially self-reflection caused by final
gathering. The old *offset value is returned, and should
be restored before the shader returns; it should be used to bracket
functions like mi_trace_reflection
or mi_compute_irradiance.
miBoolean mi_ray_falloff(
miState *state,
double *start,
double *stop)
All rays and photons cast within this shader call from now on
will reach a maximum distance of *stop, measured from
state→point when the ray or photon tracing
function or mi_compute_irradiance
is called.
The maximum distance is applied to every single ray or photon
segment; lengths are not accumulated. Objects farther away will not
be hit; instead, the environment will be returned (unless cleared
in the state by the shader). The *start parameter
defines a falloff distance; objects at a distance between
*start and *stop will fade from the object
color to the environment color (or black if none), to avoid hard
edges in animations. This function is useful to limit the reach of
rays, especially finalgather rays, to keep computation local and
not fill the geometry cache with distant objects that do not matter
much anyway. The old start and stop values are returned, and should
be restored before the shader returns. This function takes
precedence over falloffs in the options and objects.
miBoolean mi_inclusive_lightlist(
int *n_lights,
miTag **lights,
miState *state)
This function accepts a list of light source instances or light groups, and returns a modified list that includes all other instances of the instanced lights as well. If a light is instanced three times in the scene, and one (or more) of them appears in *lights, then *lights will contain all three after this call. Light groups are expanded to return the individual instances. n_lights points to an integer containing the original list size, and lights points to a pointer to the original list. After the function returns, the integer holds the new list length, and the pointer points to a new list. Both the integer and the pointer should be on the stack and should be initialized from the shader parameters using mi_eval to avoid overwriting the actual shader parameters, which should remain intact for the next shader call. The returned list should not be written to by the shader.
The new list is a copy of the global light list (see mi_query) with only those lights that match the passed original list included. The returned list remains valid until the next call to mi_inclusive_lightlist or mi_exclusive_lightlist. Note that this function involves a loop over all lights, and may be a good candidate for calling once in the init shader instead of once every time the shader is called, if *lights is known to be constant during the frame.
miBoolean mi_exclusive_lightlist(
int *n_lights,
miTag **lights,
miState *state)
This function is similar to the previous, but returns all global light instances except those whose instanced light match a light instanced in the given list, or is contained in a given light group. Both functions return mutually exclusive lists when called with the same argument list. n_lights points to an integer containing the original list size, and lights points to a pointer to the original list. After the function returns, the integer holds the new list length, and the pointer points to a new list. Both the integer and the pointer should be on the stack and should be initialized from the shader parameters using mi_eval to avoid overwriting the actual shader parameters, which should remain intact for the next shader call.
The new list is a copy of the global light list (see mi_query) with the matches with the original list removed. This function is slightly slower than the previous. The returned list remains valid until the next call to mi_inclusive_lightlist or mi_exclusive_lightlist.
miBoolean mi_instance_lightlist(
int *n_lights,
miTag **lights,
miState *state)
This function returns the expanded instance lights for the
current geometry instance state→instance as
specified in the scene description (see Instance Light List). This
function does not expect any input lights, both n_lights and
lights are out parameters. The integer
n_lights points to will contain the array size of the
returned light list, and lights will point to the array
content. If the state instance has not inherited a light list, this
functions fills the returned array with all lights present in the
scene. In plain-C shaders this function can be used as an
alternative to light iterators, and enables sharing of the same
shader even on objects with different light sets.
miScalar mi_lightprofile_value(
void *vlp, /* opaque pointer to light profile */
miScalar phi, /* horizontal angle */
miScalar costheta, /* cos of vertical angle */
miVector *pos, /* sampling position on light */
miBoolean rel) /* return pure or relative value */
This function supports direct access to light profile data for
photon emitter shaders.
For a given light profile, identified by the opaque pointer
vlp and obtained by
mi_db_accessing the tag from the
lightprofile parameter, this routine returns a light intensity.
This intensity is either relative (normalized to a factor in the
range 0…1) if rel is miTRUE, or the
raw values from the vendor-supplied profile file (Candelas in the
case of IES and Candelas per 1000 Lumen flux in the case of
Eulumdat) if rel is miFALSE. The phi and
costheta arguments define the horizontal angle and the
cosine of the vertical angle, respectively, as defined by the light
profile. This function is intended for light emitter
shaders that operate directly with angles; light shaders should use
mi_lightprofile_sample.
miScalar mi_lightprofile_sample(
miState *state,
miTag light_profile,
miBoolean rel)
This is a variant of mi_lightprofile_value with a simplified interface suitable for light shaders. The vlp pointer is derived from accessing light_profile, and phi, costheta, and pos are derived from the direction and point variables of state. The rel flag is passed through.
miBoolean mi_compute_irradiance(
miColor *result,
miState *state)
This function computes the irradiance
corresponding to indirect
diffuse illumination at the intersection point given in
state→point. It is used in
material shaders to add
indirect illumination such as
caustics or
color bleeding. If
state→pri is zero, miFALSE is
returned. The mi_compute_irradiance
function, if
called to evaluate irradiance from final gathering, will return the
average of all alphas from finalgather rays. This allows a simple
form of ambient occlusion mapping. The final gather receive mode
must be enabled in order to compute final gather contributions with
this function.
miBoolean mi_compute_irradiance_backside(
miColor *result,
miState *state)
This function is equivalent to mi_compute_irradiance, except that it computes the irradiance on the back side of the surface, as defined by the surface normal.
typedef struct miIrrad_options {
int size; /* size of the structure */
/* finalgather part... */
int finalgather_rays; /* no. rays in final gather */
miScalar finalgather_maxradius; /* maxdist for finalgather */
miScalar finalgather_minradius; /* mindist for finalgather */
miCBoolean finalgather_view; /* radii in raster pixels? */
miUchar finalgather_filter; /* finalgather ray filter */
miUchar padding1[2]; /* padding */
/* globillum part... */
int globillum_accuracy; /* no. GI photons in estimation */
miScalar globillum_radius; /* maxdist for GI photons */
/* caustics part... */
int caustic_accuracy; /* no. caustic photons in est. */
miScalar caustic_radius; /* maxdist for caustic photons */
/* extensions... */
miUint finalgather_points; /* #fg points for interpolation */
miScalar importance; /* importance factor */
/* this structure may be extended in the future */
} miIrrad_options;
miBoolean mi_compute_avg_radiance(
miColor *result,
miState *state,
miUchar face, /* 'f' front, 'b' back */
struct miIrrad_options *irrad_options); /* options to overwrite */
This function is a generalization of the mi_compute_irradiance and mi_compute_irradiance_backside functions with a common interface. Additionally, it allows to override quality parameters for final gathering and photons on a per-call basis.
The function
mi_compute_avg_radiance
(result, state, 'f', NULL) returns the
same result as
mi_compute_irradiance
(result, state) divided by π.
In other words, the color result of
mi_compute_irradiance is exactly
π times brighter than that of
mi_compute_avg_radiance.
There is a similar relationship between
mi_compute_avg_radiance
(result, state, 'b', NULL) and
mi_compute_irradiance_backside
(result, state).
For overriding finalgather and/or photon quality settings, a
non-NULL pointer to a properly setup miIrrad_options
struct must be passed in as fourth argument. All fields must be
initialized before this struct is passed to
mi_compute_avg_radiance. A macro
miIRRAD_DEFAULT may be used to initialize the
structure with defaults from state→options, and a
subset of the structure fields can be modified explicitly after
that.
The importance factor may be used by a shader to
hint mental ray kernel to use more of fewer finalgather rays for a
specific finalgather point. For example, a shader may pass the
intensity of the diffuse component to make mental ray trace more
finalgather rays in the bright part of the scene and less in the
dark part. For a semi-transparent glass, a shader may use the
transparency as importance in order to reduce the number
finalgather rays used for computing finalgather points behind the
glass. If importance is not set, mental ray computes the default
one based on the current reflection and refraction level.
Note that miIrrad_options may be extended in the
future versions, but explicitly given size fields
allows two-way compatibility.
miBoolean mi_compute_volume_irradiance(
miColor *result,
miState *state)
This function computes the irradiance
corresponding to indirect
diffuse illumination at the point given in state
state→point. It is used in
volume shaders to add
indirect illumination such as multiply
scattered light or volume
caustics.
miBoolean mi_compute_directional_irradiance(
miColor *result,
miState *state,
miScalar r,
miScalar g1,
miScalar g2)
This function is a generalization of
mi_compute_volume_irradiance that
calculates the volume irradiance
obtained when the forward or backward scattering directions
(measured with respect to the light
ray direction) are preferred over sideways scattering. The
parameters g1 and g2 are used to quantify two
independent instances of these. Values between 0 and
1 specify forward scattering, while values between
-1 and 0 specify backward scattering. A
value of 0 indicates no preference, that is, diffuse
scattering. The blending parameter r specifies to what
extent the two choices should be (linearly) superimposed. For
r = 0 only the choice with preferences specified by
g2 contributes, while for r = 1 only the
choice with preferences specified by g1 contributes.
Commonly a positive choice for g1 is combined with a
negative g2 and vice versa. Purely diffuse volume
scattering may be computed more efficiently with
mi_compute_volume_irradiance. An
example polar diagram of irradiance
dependent on the angle between
scattering direction and light direction for values
g1 = −g2 = 0.5 is given in
the figure below for r = 1.0,
0.0, and 0.5.
typedef enum miFinalgather_store_mode {
miFG_STORE_COMPUTE = 1,
miFG_STORE_SET = 2
} miFinalgather_store_mode;
miBoolean mi_finalgather_store(
miColor *color,
miState *state,
int mode)
Creates a new finalgather point with the
irradiance value color.
Normally final gather points are created automatically based on
accuracy settings, either during preprocessing, or during rendering
when an irradiance is computed for a point with no nearby
preexisting finalgather points. This function stores a point energy
color explicitly, regardless of accuracy settings. The
color value is either computed by
mi_finalgather_store if
mode is miFG_STORE_COMPUTE, using a
procedure similar to mi_compute_irradiance,
or the value
specified by the caller is used directly if mode is
miFG_STORE_SET.
If the mode is miFG_STORE_SET, then
state→point, state→normal, and
state→dist must be initialized before calling
mi_finalgather_store.
For best quality, state→dist should contain the
distance to the closest object, but if this is not known or too
expensive to probe, it may be left unchanged in the state.
This function is useful for setting finalgather points in places where they would not normally be seen by preprocessing, such as the back sides of objects. This is especially useful for lightmap shaders because light maps that compute irradiances would otherwise look better on parts of the object seen by the camera. For example, the light map shader might use mi_finalgather_store in compute mode to place finalgather points on vertices, for later lookup in output mode.
typedef struct miAmboccl_options {
int size; /* size of the structure */
/* ao compute quality... */
int rays; /* number of rays to shoot */
miVector axis; /* the axis for the cone */
miScalar spread; /* cosine of the spread angle */
miScalar spread_exp; /* the exponent of the cosine distr */
miScalar mindist; /* near clipping distance */
miScalar maxdist; /* far clipping distance */
/* ao lookup quality... */
int cache_points; /* number of ao points for lookup */
} miAmboccl_options;
miScalar mi_ambient_occlusion(
miState *state,
struct miAmboccl_options *amboccl_options,
miVector *bent_normal); /* opt. bent normal */
This function computes the amount of occlusion by surrounding objects
at the intersection point state→point if ambient occlusion
is enabled in mental ray, which is the default. This is typically a faster and
less expensive method to simulate the effects of global illumination.
The return value is the extent to which the area above a point is covered by
geometry, ranging from 0 for no coverageto
1 for fully covered. It may be used in material shaders to scale the contribution from ambient lighting, or create effects like contact shadows.
The occlusion value is computed by tracing a number of rays into the hemisphere above the surface point and testing to what extent this region is blocked. No material shaders are called during these trace calls, hence no shading effects are considered for occlusion (in contrast to final gathering, for example).
The ambient occlusion algorithm supports a caching mechanism similar to final gathering, where occlusion values are pre-computed for distinct points only and stored in a 3d map data structure, for fast look-up and interpolation during final rendering. By default the cache is disabled in mental ray, which results in ambient occlusion calculations performed only on demand from shaders without any caching. The caching can be enabled with a scene option or on the mental ray command line. This will trigger computations for ambient occlusion before rendering starts, and independent of actual calls to this function in shaders.
The function supports additional parameters to control the ambient occlusion computation for the particular call. Passing aNULL
pointer for the amboccl_options will enforce to use the
ambient occlusion options and
defaults set in the scene or from the mental ray
command line.
Passing a valid pointer to a miAmboccl_options structure, on the
other hand, requires to initialize all fields before this structure
is provided to the funtion
mi_ambient_occlusion.
The macro miAMBOCCL_DEFAULT should be used to fill the structure
with reasonable values first, and then individual fields may be modified
explicitly. Note, the macro needs to be called for every shading point, since
it refers to state variables. The fields have the following meanings:
sizerays0
or a negative value then mental ray will use the global scene setting provided
with the options or on the command line, or the default 256
otherwise. The miAMBOCCL_DEFAULT macro sets the value of this
field to -1, hence refers to the scene setting or default.
axismiAMBOCCL_DEFAULT macro sets the value of this
field to the current state→normal.
spread0.0
means an angle of 90 degrees (the maximum spread, or hemisphere), values
approaching 1.0 cause narrower angle, and 1.0
corresponds to 0 degrees. The miAMBOCCL_DEFAULT macro sets the
value of this field to a negative out-of-range value, forcing mental ray to
use the default 0.0 (full coverage).
spread_exp1 causes Lambertian distribution, which is
the default. The miAMBOCCL_DEFAULT macro sets the value to
1.min_dist
max_distmiAMBOCCL_DEFAULT
macro sets the value of these fields to -1, disabling any distance
limitations (distance range: 0.0 to infinity).
cache_points64 otherwise. If set to 0, then mental
ray will ignore the cache if present. The miAMBOCCL_DEFAULT macro
sets the value of this field to -1.
The bent_normal parameter will return an additional direction
vector if a valid pointer is given. It provides the direction into the
unoccluded part of the hemisphere. This may be used for special shading effects
or acceleration purposes. It is determined as follows: during casting of the
rays, the directions of unoccluded probe rays are accumulated to produce an
average at the end, called the bent normal. If the current surface
point is completely unoccluded, this average vector is coincidental with the
original axis (or normal in the default case). If it's partially occluded, then
the resulting vector can be regarded as a bending of the normal into the average
direction of the unoccluded part of the hemisphere. This may be used in shaders
to produce a specular highlight, or to concentrate sampling of the environment
around the bent normal instead of the normal. The mental ray base shader
mib_fast_occlusion provides an example implementation.
Copyright © 1986, 2015 NVIDIA ARC GmbH. All rights reserved.