Mitsuba Renderer  0.5.0
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
mitsuba::Sampler Class Referenceabstract

Base class of all sample generators. More...

#include <mitsuba/render/sampler.h>

+ Inheritance diagram for mitsuba::Sampler:

Public Member Functions

virtual ref< Samplerclone ()
 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...
 
Point2next2DArray (size_t size)
 Retrieve the next 2D array of values from the current sample. More...
 
Floatnext1DArray (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 ClassgetClass () 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 PropertiesgetProperties () 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 Classm_theClass
 
- Static Public Attributes inherited from mitsuba::ConfigurableObject
static Classm_theClass
 
- Static Public Attributes inherited from mitsuba::SerializableObject
static Classm_theClass
 
- Static Public Attributes inherited from Object
static Classm_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
resResolution of the target film
blockedWill 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: