Public Member Functions
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 constructor 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 constructor 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
LightListoperator-> () const
 access to light list from iterator
const LightIteratoroperator++ ()
 pre-increment operator
LightIterator operator++ (int)
 post-increment operator
bool at_end () const
 check if iteration should continue.
const LightIteratoroperator= (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 explicitly 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 constructor 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 instantiate the iterator with an explicit light list provided by the shader.

Parameters:
stateprovides the iterator with information about the rendering state, especially where to find the lights for the iteration.
shader_light_listallows to provide a custom list of lights for the iteration. This optional list overrides the instance light lists used by default.
n_shader_lightstells the iterator the number of custom lights passed in.
versionallows 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 constructor for the LightIterator with sampling cone.

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

Parameters:
stateprovides the iterator with information about the rendering state, especially where to find the lights for the iteration.
axisspecifies the axis for the light cone. The value should be normalized.
spread_cosspecifies 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_listallows to provide a custom list of lights for the iteration. This optional list overrides the instance light lists used by default.
n_shader_lightstells the iterator the number of custom lights passed in.
versionallows 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:
iterthe LightIterator to be copied.

References mi::shader_v3::LightList::connect().

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.

References mi::shader_v3::LightList::release().


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.

References mi::shader_v3::LightList::get_number_of_lights().

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.

References operator==().

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.

References mi::shader_v3::LightList::get_light_tag().

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 preferred over the post-increment operator, since it avoids the generation of a temporary LightIterator.

Returns:
a constant reference of the iterator
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.
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.

References mi::shader_v3::LightList::set_current().

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:
itergives the LightIterator to be assigned
Returns:
a constant reference to the LightIterator that has been assigned to.

References mi::shader_v3::LightList::connect(), and mi::shader_v3::LightList::release().

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.

Referenced by operator!=().

Copyright © 1986, 2013 NVIDIA Corporation