Base class of all sample generators. More...

#include <mitsuba/render/sampler.h>

Inheritance diagram for mitsuba::Sampler:

Public Member Functions
virtual ref< Sampler >	clone ()
	Create a clone of this sampler. More...

virtual void	setFilmResolution (const Vector2i &res, bool blocked)
	Set the film size in pixels. More...

virtual void	generate (const Point2i &offset)
	Generate new samples. More...

virtual void	advance ()
	Advance to the next sample. More...

virtual void	setSampleIndex (size_t sampleIndex)
	Manually set the current sample index. More...

virtual Float	next1D ()=0
	Retrieve the next component value from the current sample. More...

virtual Point2	next2D ()=0
	Retrieve the next two component values from the current sample. More...

Point2 *	next2DArray (size_t size)
	Retrieve the next 2D array of values from the current sample. More...

Float *	next1DArray (size_t size)
	Same as above, but 1D. More...

virtual void	request2DArray (size_t size)
	Request that a 2D array will be made available for later consumption by next2DArray(). More...

virtual void	request1DArray (size_t size)
	Same as request2DArray(), but in 1D. More...

size_t	getSampleCount () const
	Return total number of samples. More...

size_t	getSampleIndex () const
	Return the current sample index. More...

virtual void	serialize (Stream stream, InstanceManager manager) const
	Serialize this sampler to a binary data stream. More...

virtual const Class *	getClass () const
	Retrieve this object's class. More...

Public Member Functions inherited from mitsuba::ConfigurableObject
virtual void	setParent (ConfigurableObject *parent)
	Notify the ConfigurableObject instance about its parent object. More...

virtual void	addChild (const std::string &name, ConfigurableObject *child)
	Add a child (default implementation throws an error) More...

void	addChild (ConfigurableObject *child)
	Add an unnamed child. More...

virtual void	configure ()
	Configure the object (called once after construction and addition of all child ConfigurableObject instances)) More...

const std::string &	getID () const
	Return the identifier associated with this instance (or "unnamed") More...

void	setID (const std::string &name)
	Set the identifier associated with this instance. More...

const Properties &	getProperties () const
	Return the properties object that was originally used to create this instance. More...

Public Member Functions inherited from mitsuba::SerializableObject
	SerializableObject (Stream stream, InstanceManager manager)
	Unserialize a serializable object. More...

Public Member Functions inherited from Object
	Object ()
	Construct a new object. More...

int	getRefCount () const
	Return the current reference count. More...

void	incRef () const
	Increase the reference count of the object by one. More...

void	decRef (bool autoDeallocate=true) const
	Decrease the reference count of the object and possibly deallocate it. More...

virtual std::string	toString () const
	Return a human-readable string representation of the object's contents. More...

Static Public Attributes
static Class *	m_theClass

Static Public Attributes inherited from mitsuba::ConfigurableObject
static Class *	m_theClass

Static Public Attributes inherited from mitsuba::SerializableObject
static Class *	m_theClass

Static Public Attributes inherited from Object
static Class *	m_theClass
	Pointer to the object's class descriptor. More...

Protected Member Functions
	Sampler (const Properties &props)
	Construct a new sampler. More...

	Sampler (Stream stream, InstanceManager manager)
	Unserialize a sampler. More...

virtual	~Sampler ()
	Virtual destructor. More...

Protected Member Functions inherited from mitsuba::ConfigurableObject
virtual	~ConfigurableObject ()
	Virtual destructor. More...

	ConfigurableObject (const Properties &props)
	Construct a configurable object. More...

	ConfigurableObject (Stream stream, InstanceManager manager)
	Unserialize a configurable object. More...

Protected Member Functions inherited from mitsuba::SerializableObject
	SerializableObject ()
	Construct a serializable object. More...

virtual	~SerializableObject ()
	Virtual deconstructor. More...

Protected Member Functions inherited from Object
virtual	~Object ()
	Virtual private deconstructor. (Will only be called by ref) More...

Protected Attributes
size_t	m_sampleCount

size_t	m_sampleIndex

std::vector< size_t >	m_req1D

std::vector< size_t >	m_req2D

std::vector< Float * >	m_sampleArrays1D

std::vector< Point2 * >	m_sampleArrays2D

size_t	m_dimension1DArray

size_t	m_dimension2DArray

Protected Attributes inherited from mitsuba::ConfigurableObject
Properties	m_properties

Additional Inherited Members
Static Public Member Functions inherited from Object
static void	staticInitialization ()
	Initializes the built-in reference count debugger (if enabled) More...

static void	staticShutdown ()
	Free the memory taken by staticInitialization() More...

Detailed Description

Base class of all sample generators.

For each sample in a pixel, a sample generator produces a (hypothetical) point in the infinite dimensional random number cube. A rendering algorithm can then request subsequent 1D or 2D components of this point using the next1D() and next2D() functions. Some implementations make certain guarantees about the stratification of the first n components with respect to the other points that are sampled within a pixel (the low-discrepancy and stratified samplers do this for instance).

The general interaction between a sampler and a rendering algorithm is as follows: Before beginning to render a pixel, the rendering algorithm calls generate(). The first pixel sample can now be computed, after which advance() needs to be invoked. This repeats until all pixel samples have been generated. Note that some implementations need to be configured for a certain number of pixel samples, and exceeding these will lead to an exception being thrown. While computing a pixel sample, the rendering algorithm usually requests batches of (pseudo-) random numbers using the next1D(), next2D(), next1DArray() and next2DArray() functions.

The difference between calling next1D(), next2D() a number of times versus using the array variants next1DArray() and next2DArray() is that the latter can provide stratification not only with respect to random numbers obtained within another pixel sample, but also within the array itself. This is useful e.g. in the direct illumination strategy, which spawns several rays after hitting a surface when computing a pixel sample. Since this is done over and over again for each one of the pixel samples, it makes sense to stratify over all of the rays that are ultimately generated, and the next1DArray() and next2DArray() methods allow to do this. See the file direct.cpp for an example.

Constructor & Destructor Documentation

mitsuba::Sampler::Sampler ( const Properties & props )

protected

Construct a new sampler.

mitsuba::Sampler::Sampler	(	Stream *	stream,
		InstanceManager *	manager
	)

protected

Unserialize a sampler.

virtual mitsuba::Sampler::~Sampler ( )

protectedvirtual

Virtual destructor.

Member Function Documentation

virtual void mitsuba::Sampler::advance ( )

virtual

Advance to the next sample.

Reimplemented in mitsuba::ReplayableSampler.

virtual ref<Sampler> mitsuba::Sampler::clone ( )

virtual

Create a clone of this sampler.

The clone is allowed to be different to some extent, e.g. a pseudorandom generator should be based on a different random seed compared to the original. All other parameters, are copied exactly.

The default implementation throws an exception.

Reimplemented in mitsuba::ReplayableSampler.

virtual void mitsuba::Sampler::generate ( const Point2i & offset )

virtual

Generate new samples.

This function is called initially and every time the generated samples have been exhausted. When used in conjunction with a SamplingIntegrator, this will be called before starting to render each pixel, and the argument denotes the pixel position. Otherwise, some dummy value should be provided, e.g. Point2i(-1)

Reimplemented in mitsuba::ReplayableSampler.

virtual const Class* mitsuba::Sampler::getClass ( ) const

virtual

Retrieve this object's class.

Reimplemented from mitsuba::ConfigurableObject.

Reimplemented in mitsuba::ReplayableSampler.

size_t mitsuba::Sampler::getSampleCount ( ) const

inline

Return total number of samples.

size_t mitsuba::Sampler::getSampleIndex ( ) const

inline

Return the current sample index.

virtual Float mitsuba::Sampler::next1D ( )

pure virtual

Retrieve the next component value from the current sample.

Implemented in mitsuba::ReplayableSampler.

Float* mitsuba::Sampler::next1DArray ( size_t size )

Same as above, but 1D.

virtual Point2 mitsuba::Sampler::next2D ( )

pure virtual

Retrieve the next two component values from the current sample.

Implemented in mitsuba::ReplayableSampler.

Point2* mitsuba::Sampler::next2DArray ( size_t size )

Retrieve the next 2D array of values from the current sample.

Note that this is different from just calling next2D() repeatedly - this function will generally return a set of 2D vectors, which are not only well-laid out over all samples at the current pixel, but also with respect to each other. Note that this 2D array has to be requested initially using request2DArray() and later, they have to be retrieved in the same same order and size configuration as the requests. An exception is thrown when a mismatch is detected.

This function is useful to support things such as a direct illumination rendering technique with "n" pixel samples and "m" shading samples, while ensuring that the "n*m" sampled positions on an area light source are all well-stratified with respect to each other.

Remarks: This function is currently not exposed by the Python API

virtual void mitsuba::Sampler::request1DArray ( size_t size )

virtual

Same as request2DArray(), but in 1D.

Reimplemented in mitsuba::ReplayableSampler.

virtual void mitsuba::Sampler::request2DArray ( size_t size )

virtual

Request that a 2D array will be made available for later consumption by next2DArray().

This function must be called before generate(). See next2DArray() for a more detailed description of this feature.

Reimplemented in mitsuba::ReplayableSampler.

virtual void mitsuba::Sampler::serialize	(	Stream *	stream,
		InstanceManager *	manager
	)		const

virtual

Serialize this sampler to a binary data stream.

Reimplemented from mitsuba::ConfigurableObject.

Reimplemented in mitsuba::ReplayableSampler.

virtual void mitsuba::Sampler::setFilmResolution	(	const Vector2i &	res,
		bool	blocked
	)

virtual

Set the film size in pixels.

When this sampler is used to render an image using a SampleIntegrator, the camera implementation will call this method to inform the sampler about the dimensions of the target film in pixels. Some samplers might choose to use this hint to further improve stratification, but this is entirely optional. The default implementation does nothing.

Parameters

res	Resolution of the target film
blocked	Will the rendering be blocked, i.e. parallelized over many rectangular image regions?

virtual void mitsuba::Sampler::setSampleIndex ( size_t sampleIndex )

virtual

Manually set the current sample index.

Reimplemented in mitsuba::ReplayableSampler.

Member Data Documentation

size_t mitsuba::Sampler::m_dimension1DArray

protected

size_t mitsuba::Sampler::m_dimension2DArray

protected

std::vector<size_t> mitsuba::Sampler::m_req1D

protected

std::vector<size_t> mitsuba::Sampler::m_req2D

protected

std::vector<Float *> mitsuba::Sampler::m_sampleArrays1D

protected

std::vector<Point2 *> mitsuba::Sampler::m_sampleArrays2D

protected

size_t mitsuba::Sampler::m_sampleCount

protected

size_t mitsuba::Sampler::m_sampleIndex

protected

Class* mitsuba::Sampler::m_theClass

static

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

include/mitsuba/render/sampler.h

Public Member Functions

Static Public Attributes

Protected Member Functions

Protected Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation