mi::shader_v3::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)
 the contructor for the 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)
 the contructor for the LightIterator with sampling cone.
 LightIterator (const LightIterator &iter)
 the copy constructor.
 ~LightIterator ()
 the destructor
miTag operator * () const
 obtain the tag for the current light
LightList * operator-> () const
 access to light list from iterator
const LightIterator & operator++ ()
 pre-increment operator
LightIterator operator++ (int)
 post-increment operator
bool at_end () const
 check if iteration should continue.
const LightIterator & operator= (const LightIterator &iter)
 assign LightIterator
bool operator== (const LightIterator &iter) const
 check if two LightIterators are equal
bool operator!= (const LightIterator &iter) const
 check if two LightIterators are unequal.

Detailed Description

Iterate over shader or instance light lists.

mental ray 3.5 introduced 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_v3::LightIterator::LightIterator (  miState *  state,
miTag *  shader_light_list = 0,
int  n_shader_lights = 0,
int  version = mi_ray_interface_version
)  [inline]
 

the contructor for the LightIterator

Construct a LightIterator from state and an optional shader light list. 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.

mi::shader_v3::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]
 

the contructor for the LightIterator with sampling cone.

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.

mi::shader_v3::LightIterator::LightIterator (  const LightIterator &  iter  )  [inline]
 

the copy constructor.

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

Parameters:
iter the LightIterator to be copied.

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

the 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_v3::LightIterator::at_end (   )  const [inline]
 

check if iteration should continue.

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

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

obtain the tag for the current light

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_v3::LightIterator::operator!= (  const LightIterator &  iter  )  const [inline]
 

check if two LightIterators are unequal.

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_v3::LightIterator::operator++ (  int   )  [inline]
 

post-increment operator

The increment operator advances the LightIterator to the next light in the light list. The post-increment operator is more expensive than the pre-increment operator, since it need to construct an extra copy of the iterator.

Returns:
a copy of the LightIterator before it was advanced to the next light.

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

pre-increment operator

The operator advances the LightIterator to the next light in the light list. The pre-increment operator should be prefered over the post-increment operator, since it avoids the generation of a temporary LightIterator.

Returns:
a constant reference of the iterator

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

access to light list from iterator

the postfix dereference operator allows to invoke public methods of the LightList class from the LightIterator.

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_v3::LightIterator::operator= (  const LightIterator &  iter  )  [inline]
 

assign LightIterator

Assign a LightIterator to this LightIterator. If the two iterators refer to different light lists, make sure that proper reference counting is performed on the two lists.

Parameters:
iter gives the LightIterator to be assigned
Returns:
a constant reference to the LightIterator that has been assigned to.

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

check if two LightIterators are equal

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.

Copyright © 1986-2009 by mental images GmbH