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
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 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:

	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 constructor 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.

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

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().

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++

(

)

[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.

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().

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.

References mi::shader_v3::LightList::connect(), m_current, m_list, 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.

References m_current, and m_list.

Referenced by operator!=().

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==().