mi::shader::LightIterator Class Reference

Iterate over shader or instance light lists. More...

#include <shader_lightlist.h>

List of all members.

Public Member Functions

 LightIterator (miState *state, miTag *shader_light_list=0, int n_shader_lights=0, int version=mi_ray_interface_version)
 construct a LightIterator
 LightIterator (miState *state, const miVector &axis, miScalar spread_cos, miTag *shader_light_list=0, int n_shader_lights=0, int version=mi_ray_interface_version)
 construct a LightIterator
 LightIterator (const LightIterator &liter)
 copy constructor
 ~LightIterator ()
 destructor
miTag operator * () const
 obtain current light tag
LightList * operator-> () const
 access to light list from iterator
const LightIterator & operator++ ()
 pre-increment LightIterator
LightIterator operator++ (int)
 post-increment LightIterator
bool at_end () const
 check if iterator has reached end
const LightIterator & operator= (const LightIterator &iter)
 assign LightIterator
bool operator== (const LightIterator &iter) const
 compare LightIterators for equality
bool operator!= (const LightIterator &iter) const
 compare LightIterators for inequality

Detailed Description

Iterate over shader or instance light lists.

mental ray 3.5 introduces the concept of instance light lists. These lists are not explicitely passed to the shader as a parameter. Instead mental ray makes them available through LightIterators. The LightIterator class allows shaders to iterate over lights for the purpose of sampling. A typical use would look like 

    for (mi::shader::LightIterator iter(state); !iter.at_end(); ++iter) {
        miColor col = {0,0,0,1};
        while (iter->sample()) {
            miColor light_color;
            iter->get_contribution(&light_color);
            col.r += light_color.r;
            col.g += light_color.g;
            col.b += light_color.b;
        }
        const int n_samples = iter->get_number_of_samples();
        if (n_samples > 1) {
            col.r /= n_samples;
            col.g /= n_samples;
            col.b /= n_samples;
        }
    }

Constructor & Destructor Documentation

mi::shader::LightIterator::LightIterator (  miState *  state,
miTag *  shader_light_list = 0,
int  n_shader_lights = 0,
int  version = mi_ray_interface_version
)  [inline]
 

construct a LightIterator

Note that two different light lists may be assigned to instances: a light list and a shadow light list. During regular rendering the iterator uses the light list, but when either rendering shadow maps or tracing shadow rays, then the iterator prefers the shadow light list over the light list, that is, in these cases the light list will only be used if no shadow light list is present. It is also possible to instanciate the iterator with an explicit light list provided by the shader.

Parameters:
state provides the iterator with information about the rendering state, especially where to find the lights for the iteration.
shader_light_list allows to provide a custom list of lights for the iteration. This optional list overrides the instance light lists used by default.
n_shader_lights tells the iterator the number of custom lights passed in.
version allows to specify a specific interface version. By default this is set to the current interface version.
Parameters:
state  use to create iter within shader the state
shader_light_list  optional array of light tags
n_shader_lights  number of lights in above array

mi::shader::LightIterator::LightIterator (  miState *  state,
const miVector &  axis,
miScalar  spread_cos,
miTag *  shader_light_list = 0,
int  n_shader_lights = 0,
int  version = mi_ray_interface_version
)  [inline]
 

construct a LightIterator

The cone for light samples is defined by axis and the cosine of the angle.

Parameters:
state provides the iterator with information about the rendering state, especially where to find the lights for the iteration.
axis specifies the axis for the light cone. The value should be normalized.
spread_cos specifies the cosine of the angle to the light cone axis. The value 0 corresponds to a hemisphere, the value -1 to the complete sphere.
shader_light_list allows to provide a custom list of lights for the iteration. This optional list overrides the instance light lists used by default.
n_shader_lights tells the iterator the number of custom lights passed in.
version allows to specify a specific interface version. By default this is set to the current interface version.
Parameters:
state  use to create iter within shader the state
axis  the axis on the cone for light sample dorections
spread_cos  the cosine of the light spread angle
shader_light_list  optional array of light tags
n_shader_lights  number of lights in above array

mi::shader::LightIterator::LightIterator (  const LightIterator &  liter  )  [inline]
 

copy constructor

creates a copy of a given LightIterator. This constructor is needed to return LightIterators from methods.

Parameters:
liter the LightIterator to be copied.

mi::shader::LightIterator::~LightIterator (   )  [inline]
 

destructor

The destructor for a LightIterator instance is called when it goes out of scope. It releases all resources associated with this instance.

Member Function Documentation

bool mi::shader::LightIterator::at_end (   )  const [inline]
 

check if iterator has reached end

Returns:
true if the end of the light list has been reached, false otherwise.

miTag mi::shader::LightIterator::operator * (   )  const [inline]
 

obtain current light tag

dereferencing a LightIterator with the unary prefix operator '*' yields the tag of the current light. Note that this operation is distinctly different from dereferencing a LightIterator with the postfix operator '->'.

Returns:
the tag of the current light in the light list.

bool mi::shader::LightIterator::operator!= (  const LightIterator &  iter  )  const [inline]
 

compare LightIterators for inequality

Two LightIterators are unequal if they do not refer to the same LightList or have two different current lights within the list.

Returns:
true if the two iterators are unequal, false else.

LightIterator mi::shader::LightIterator::operator++ (  int   )  [inline]
 

post-increment LightIterator

The increment operator advances the LightIterator to the next light in the light list.

Returns:
a copy of the LightIterator as it was before it was advanced to the next light.
The post-increment operator is more expensive than the pre-increment operator, since it need to construct an extra copy of the iterator.

const LightIterator & mi::shader::LightIterator::operator++ (   )  [inline]
 

pre-increment LightIterator

The operator advances the LightIterator to the next light in the light list.

Returns:
a constant reference to the incremented light iterator.
The pre-increment operator should be prefered over the post-increment operator, since it avoids the generation of a temporary LightIterator.

LightList * mi::shader::LightIterator::operator-> (   )  const [inline]
 

access to light list from iterator

the postfix dereference operator '->' allows to invoke public methods of the LightList class as if they would be methods of the LightIterator class.

Returns:
a pointer to the LightList associated with the LightIterator. Note that the LightList pointer is not available for direct use. Instead C++ will immediately use it to invoke the LightList method written to the right of the '->' operator. For example, 
        LightIterator iter(state)->sample();
will invoke the sample method of the LightList class.

const LightIterator & mi::shader::LightIterator::operator= (  const LightIterator &  iter  )  [inline]
 

assign LightIterator

assigns a LightIterator to another one.

bool mi::shader::LightIterator::operator== (  const LightIterator &  iter  )  const [inline]
 

compare LightIterators for equality

Two LightIterators are considered equal if they refer to the same light list and have the same current light within the list.

Returns:
true if the two iterators are equal, false else.

The documentation for this class was generated from the following file:

Copyright © 1986-2008 by mental images GmbH