RC Direction Functions

The functions in this section compute ray or photon directions. In both photon and ray tracing, shaders normally first compute a direction for secondary photons or rays using one of the functions with _dir in the name, and then call the corresponding photon or ray tracing function with the resulting direction.

The functions mi_choose_scatter_type, mi_reflection_dir_*, mi_transmission_dir_*, and mi_scattering_dir_* can also be used in other contexts than photon tracing, but they are listed in the photon tracing column above because they are most often used for that purpose. However, the glossy direction functions, for example, can just as well be used for ray tracing if the rendering quality settings (contrast and sampling limits) are high enough to avoid noisy images. Using diffuse directions for ray tracing is unlikely to produce acceptable results due to noise.

In mental ray 3.4, mi_reflection_dir_*_x and mi_transmission_dir_*_x functions are added. They have the same functionality as non-_x ones, but get an explicit sample argument pointing to a 2-dimensional sample array. The values in the sample array can be obtained from mi_sample function. The <*_x> functions are useful when multiple glossy of diffuse rays are shot.

mi_reflection_dir

void mi_reflection_dir(
    miVector        *dir,
    miState         *state);

Calculate the reflection direction based on the dir, normal, and normal_geom state variables. The returned direction dir can be passed to mi_trace_reflection. It is returned in internal space.

mi_reflection_dir_specular

void mi_reflection_dir_specular(
    miVector        *dir,
    miState         *state);

Same as mi_reflection_dir: computes the mirror direction. Created for symmetry with the similar functions for glossy and diffuse reflection.

mi_reflection_dir_glossy

void mi_reflection_dir_glossy(
    miVector        *dir,
    miState         *state,
    miScalar        shiny);
void mi_reflection_dir_glossy_x(
    miVector        *dir,
    miState         *state,
    miScalar        shiny,
    const double    sample[2]);

Choose a direction near the direction of ideal specular reflection (mirror direction). If shiny is low (for example, 5), a wide distribution of directions results; if shiny is high (for example, 100), a narrow distribution results.

mi_reflection_dir_anisglossy

void mi_reflection_dir_anisglossy(
    miVector        *dir,
    miState         *state,
    miVector        *u,
    miVector        *v,
    miScalar        shiny_u,
    miScalar        shiny_v);
void mi_reflection_dir_anisglossy_x(
    miVector        *dir,
    miState         *state,
    miVector        *u,
    miVector        *v,
    miScalar        shiny_u,
    miScalar        shiny_v,
    const double    sample[2]);

Like mi_reflection_dir_glossy, but with different shinynesses in different directions. The u and v vectors specify the local surface orientation.

mi_reflection_dir_diffuse

void mi_reflection_dir_diffuse(
    miVector        *dir,
    miState         *state);
void mi_reflection_dir_diffuse_x(
    miVector        *dir,
    miState         *state,
    const double    sample[2]);

Choose a direction with a distribution according to Lambert's cosine law for diffuse reflection.

mi_refraction_dir

miBoolean mi_refraction_dir(
    miVector        *dir,
    miState         *state,
    miScalar        ior_in,
    miScalar        ior_out);

Calculate the refraction direction in internal space based on the interior and exterior indices of refraction ior_in and ior_out, and on dir, normal, and normal_geom state variables. The returned direction dir can be passed to mi_trace_refraction. Returns miFALSE and leaves * dir undefined in case of total internal reflection.

mi_transmission_dir_specular

miBoolean mi_transmission_dir_specular(
    miVector        *dir,
    miState         *state,
    miScalar        ior_in,
    miScalar        ior_out);

Same as mi_refraction_dir, since specular transmission occurs in the refraction direction. Created for symmetry with the similar functions for glossy and diffuse transmission.

mi_transmission_dir_glossy

miBoolean mi_transmission_dir_glossy(
    miVector        *dir,
    miState         *state,
    miScalar        ior_in,
    miScalar        ior_out,
    miScalar        shiny);
miBoolean mi_transmission_dir_glossy_x(
    miVector        *dir,
    miState         *state,
    miScalar        ior_in,
    miScalar        ior_out,
    miScalar        shiny,
    const double    sample[2]);

Choose a direction near the direction of ideal specular transmission (the refraction direction). If shiny is low, a very wide distribution of directions results; if shiny is high, a narrow distribution results.

mi_transmission_dir_anisglossy

miBoolean mi_transmission_dir_anisglossy(
    miVector     *dir,
    miState      *state,
    miScalar     ior_in,
    miScalar     ior_out,
    miVector     *u,
    miVector     *v,
    miScalar     shiny_u,
    miScalar     shiny_v);
miBoolean mi_transmission_dir_anisglossy_x(
    miVector     *dir,
    miState      *state,
    miScalar     ior_in,
    miScalar     ior_out,
    miVector     *u,
    miVector     *v,
    miScalar     shiny_u,
    miScalar     shiny_v,
    const double sample[2]);

Choose a direction for anisotropic glossy transmission. The u and v vectors specify the local surface orientation.

mi_transmission_dir_diffuse

void mi_transmission_dir_diffuse(
    miVector        *dir,
    miState         *state);
void mi_transmission_dir_diffuse_x(
    miVector        *dir,
    miState         *state,
    const double    sample[2]);

Choose a direction with a distribution according to Lambert's cosine law for diffuse transmission (also known as "diffuse translucency").

mi_scattering_dir_diffuse

void mi_scattering_dir_diffuse(
    miVector        *dir,
    miState         *state)

Choose a direction with a uniform probability over the whole sphere. The returned dir vector is normalized. This is useful for volume scattering.

mi_scattering_dir_directional

void mi_scattering_dir_directional(
    miVector        *dir,
    miState         *state
    miScalar        directionality)

Choose a direction with a probability determined by directionality. For values between -1 and 0 it models volume backscattering (with -1 being the most directional), for a value of 0 it models diffuse (isotropic) volume scattering, and for values between 0 and 1 it models forward volume scattering.

mi_scattering_pathlength

miScalar mi_scattering_pathlength(
    miState  *state,
    miScalar k);

Based on probability and exponential falloff, select a path length for a photon in a participating medium with density k.