Mitsuba Renderer  0.5.0
sampler.h
Go to the documentation of this file.
1 /*
2  This file is part of Mitsuba, a physically based rendering system.
3
4  Copyright (c) 2007-2014 by Wenzel Jakob and others.
5
6  Mitsuba is free software; you can redistribute it and/or modify
7  it under the terms of the GNU General Public License Version 3
9
10  Mitsuba is distributed in the hope that it will be useful,
11  but WITHOUT ANY WARRANTY; without even the implied warranty of
12  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13  GNU General Public License for more details.
14
15  You should have received a copy of the GNU General Public License
16  along with this program. If not, see <http://www.gnu.org/licenses/>.
17 */
18
19 #pragma once
20 #if !defined(__MITSUBA_RENDER_SAMPLER_H_)
21 #define __MITSUBA_RENDER_SAMPLER_H_
22
23 #include <mitsuba/mitsuba.h>
24 #include <mitsuba/core/random.h>
26
28
29 /**
30  * \brief Base class of all sample generators.
31  *
32  * For each sample in a pixel, a sample generator produces a (hypothetical)
33  * point in the infinite dimensional random number cube. A rendering
34  * algorithm can then request subsequent 1D or 2D components of this point
35  * using the \ref next1D() and \ref next2D() functions. Some implementations
36  * make certain guarantees about the stratification of the first n components
37  * with respect to the other points that are sampled within a pixel (the
38  * low-discrepancy and stratified samplers do this for instance).
39  *
40  * The general interaction between a sampler and a rendering algorithm is as
41  * follows: Before beginning to render a pixel, the rendering algorithm calls
42  * \ref generate(). The first pixel sample can now be computed, after which
43  * \ref advance() needs to be invoked. This repeats until all pixel samples have
44  * been generated. Note that some implementations need to be configured for a
45  * certain number of pixel samples, and exceeding these will lead to an
46  * exception being thrown. While computing a pixel sample, the rendering
47  * algorithm usually requests batches of (pseudo-) random numbers using
48  * the \ref next1D(), \ref next2D(), \ref next1DArray() and
49  * \ref next2DArray() functions.
50  *
51  * The difference between calling \ref next1D(), \ref next2D() a number of
52  * times versus using the array variants \ref next1DArray() and
53  * \ref next2DArray() is that the latter can provide stratification
54  * not only with respect to random numbers obtained within another pixel
55  * sample, but also within the array itself. This is useful e.g. in the
56  * direct illumination strategy, which spawns several rays after hitting
57  * a surface when computing a pixel sample. Since this is done over and
58  * over again for each one of the pixel samples, it makes sense to
59  * stratify over all of the rays that are ultimately generated, and the
60  * \ref next1DArray() and \ref next2DArray() methods allow to do this.
61  * See the file \c direct.cpp for an example.
62  *
63  * \ingroup librender
64  * \ingroup libpython
65  */
67 public:
68  /**
69  * \brief Create a clone of this sampler
70  *
71  * The clone is allowed to be different to some extent, e.g. a pseudorandom
72  * generator should be based on a different random seed compared to the
73  * original. All other parameters, are copied exactly.
74  *
75  * The default implementation throws an exception.
76  */
77  virtual ref<Sampler> clone();
78
79  /**
80  * \brief Set the film size in pixels
81  *
82  * When this sampler is used to render an image using a \c SampleIntegrator,
83  * the camera implementation will call this method to inform the sampler
84  * about the dimensions of the target film in pixels. Some samplers might
85  * choose to use this hint to further improve stratification, but this is
86  * entirely optional. The default implementation does nothing.
87  *
88  * \param res
89  * Resolution of the target film
90  * \param blocked
91  * Will the rendering be blocked, i.e. parallelized over many
92  * rectangular image regions?
93  */
94  virtual void setFilmResolution(const Vector2i &res, bool blocked);
95
96  /**
97  * \brief Generate new samples
98  *
99  * This function is called initially and every time the generated
100  * samples have been exhausted. When used in conjunction with a
101  * \ref SamplingIntegrator, this will be called before starting to
102  * render each pixel, and the argument denotes the pixel position.
103  * Otherwise, some dummy value should be provided, e.g. Point2i(-1)
104  */
105  virtual void generate(const Point2i &offset);
106
107  /// Advance to the next sample
109
110  /// Manually set the current sample index
111  virtual void setSampleIndex(size_t sampleIndex);
112
113  /// Retrieve the next component value from the current sample
114  virtual Float next1D() = 0;
115
116  /// Retrieve the next two component values from the current sample
117  virtual Point2 next2D() = 0;
118
119  /**
120  * \brief Retrieve the next 2D array of values from the current sample.
121  *
122  * Note that this is different from just calling \ref next2D()
123  * repeatedly - this function will generally return a set of 2D vectors,
124  * which are not only well-laid out over all samples at the current pixel,
125  * but also with respect to each other. Note that this 2D array has to be
126  * requested initially using \ref request2DArray() and later, they have
127  * to be retrieved in the same same order and size configuration as the
128  * requests. An exception is thrown when a mismatch is detected.
129  *
130  * This function is useful to support things such as a direct illumination
131  * rendering technique with "n" pixel samples and "m" shading samples,
132  * while ensuring that the "n*m" sampled positions on an area light source
133  * are all well-stratified with respect to each other.
134  *
135  * \remark This function is currently not exposed by the Python API
136  */
137  Point2 *next2DArray(size_t size);
138
139  /// Same as above, but 1D
140  Float *next1DArray(size_t size);
141
142  /**
143  * \brief Request that a 2D array will be made available for
144  * later consumption by \ref next2DArray().
145  *
146  * This function must be called before \ref generate().
147  * See \ref next2DArray() for a more detailed description
148  * of this feature.
149  */
150  virtual void request2DArray(size_t size);
151
152  /// Same as \ref request2DArray(), but in 1D
153  virtual void request1DArray(size_t size);
154
156  inline size_t getSampleCount() const { return m_sampleCount; }
157
158  /// Return the current sample index
159  inline size_t getSampleIndex() const { return m_sampleIndex; }
160
161  /// Serialize this sampler to a binary data stream
162  virtual void serialize(Stream *stream, InstanceManager *manager) const;
163
165 protected:
166  /// Construct a new sampler
167  Sampler(const Properties &props);
168
169  /// Unserialize a sampler
170  Sampler(Stream *stream, InstanceManager *manager);
171
172  /// Virtual destructor
173  virtual ~Sampler();
174 protected:
175  size_t m_sampleCount;
176  size_t m_sampleIndex;
177  std::vector<size_t> m_req1D, m_req2D;
178  std::vector<Float *> m_sampleArrays1D;
179  std::vector<Point2 *> m_sampleArrays2D;
180  size_t m_dimension1DArray, m_dimension2DArray;
181 };
182
184
185 #endif /* __MITSUBA_RENDER_SAMPLER_H_ */
size_t getSampleCount() const
Definition: sampler.h:156
Generic serializable object, which supports construction from a Properties instance.
Definition: cobject.h:40
Base class of all sample generators.
Definition: sampler.h:66
#define MTS_NAMESPACE_BEGIN
Definition: platform.h:137
virtual void serialize(Stream *stream, InstanceManager *manager) const
Serialize this object to a binary data stream.
Abstract seekable stream class.
Definition: stream.h:58
#define MTS_DECLARE_CLASS()
This macro must be used in the initial definition in classes that derive from Object.
Definition: class.h:158
Definition: fwd.h:99
Reference counting helper.
Definition: ref.h:40
Associative parameter map for constructing subclasses of ConfigurableObject.
Definition: properties.h:46
Coordinates the serialization and unserialization of object graphs.
Definition: serialization.h:65
#define MTS_EXPORT_RENDER
Definition: platform.h:109
size_t getSampleIndex() const
Return the current sample index.
Definition: sampler.h:159
Definition: fwd.h:95
#define MTS_NAMESPACE_END
Definition: platform.h:138