Mitsuba Renderer  0.5.0
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
integrator.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
8  as published by the Free Software Foundation.
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_INTEGRATOR_H_)
21 #define __MITSUBA_RENDER_INTEGRATOR_H_
22 
23 #include <mitsuba/core/netobject.h>
25 #include <mitsuba/render/shape.h>
26 
28 
29 /**
30  * \brief Abstract integrator base-class; does not make any assumptions on
31  * how radiance is computed.
32  *
33  * In Mitsuba, the different rendering techniques are collectively referred to as
34  * \a integrators, since they perform integration over a high-dimensional
35  * space. Each integrator represents a specific approach for solving
36  * the light transport equation---usually favored in certain scenarios, but
37  * at the same time affected by its own set of intrinsic limitations.
38  * Therefore, it is important to carefully select an integrator based on
39  * user-specified accuracy requirements and properties of the scene to be
40  * rendered.
41  *
42  * This is the base class of all integrators; it does not make any assumptions on
43  * how radiance is computed, which allows for many different kinds of implementations
44  * ranging from software-based path tracing and Markov-Chain based techniques such
45  * as Metropolis Light Transport up to hardware-accelerated rasterization.
46  *
47  * \ingroup librender
48  */
50 public:
51  /**
52  * \brief Possibly perform a pre-process task.
53  *
54  * This function is called automatically before the main rendering process;
55  * the default implementation does nothing.
56  *
57  * The last three parameters are resource IDs of the associated scene,
58  * sensor and sample generator, which have been made available to all
59  * local and remote workers.i
60  */
61  virtual bool preprocess(const Scene *scene, RenderQueue *queue,
62  const RenderJob *job, int sceneResID, int sensorResID,
63  int samplerResID);
64 
65  /**
66  * \brief Render the scene as seen by the default sensor.
67  *
68  * Progress is tracked by sending status messages to a provided render queue.
69  * The parameter \c job is required to discern multiple render jobs occurring in
70  * parallel. The last three parameters are resource IDs of the associated
71  * scene, sensor and sample generator, which have been made available to
72  * all local and remote workers. Returns true upon successful completion.
73  */
74  virtual bool render(Scene *scene, RenderQueue *queue, const RenderJob *job,
75  int sceneResID, int sensorResID, int samplerResID) = 0;
76 
77  /**
78  * \brief Cancel a running render job
79  *
80  * This function can be called asynchronously to cancel a running render
81  * job. In this case, \ref render() will quit with a return value of
82  * \c false.
83  */
84  virtual void cancel() = 0;
85 
86  /**
87  * \brief Possibly perform a post-process task.
88  *
89  * This function is called automatically before the main rendering process;
90  * the default implementation does nothing.
91  *
92  * The last three parameters are resource IDs of the associated scene,
93  * sensor and sample generator, which have been made available to all
94  * local and remote workers.i
95  */
96  virtual void postprocess(const Scene *scene, RenderQueue *queue,
97  const RenderJob *job, int sceneResID, int sensorResID,
98  int samplerResID);
99 
100  /**
101  * \brief Configure the sample generator for use with this integrator
102  *
103  * This function is called once after instantiation and can be used to
104  * inform the sampler implementation about specific sample requirements
105  * of this integrator.
106  */
107  virtual void configureSampler(const Scene *scene, Sampler *sampler);
108 
109  /**
110  * \brief Return the nested integrator (if any)
111  *
112  * When the integrator contains a nested integrator, this function can
113  * be used to query for it
114  */
115  virtual const Integrator *getSubIntegrator(int index) const;
116 
117  /// Serialize this integrator to a binary data stream
118  void serialize(Stream *stream, InstanceManager *manager) const;
119 
121 protected:
122  /// Create a integrator
123  Integrator(const Properties &props);
124 
125  /// Unserialize an integrator
126  Integrator(Stream *stream, InstanceManager *manager);
127 
128  /// Virtual destructor
129  virtual ~Integrator() { }
130 };
131 
132 /**
133  * \brief Radiance query record data structure used by \ref SamplingIntegrator
134  * \ingroup librender
135  */
137 public:
138  /// List of suported query types. These can be combined by a binary OR.
140  /// Emitted radiance from a luminaire intersected by the ray
141  EEmittedRadiance = 0x0001,
142 
143  /// Emitted radiance from a subsurface integrator */
144  ESubsurfaceRadiance = 0x0002,
145 
146  /// Direct (surface) radiance */
147  EDirectSurfaceRadiance = 0x0004,
148 
149  /*! \brief Indirect (surface) radiance, where the last bounce did not go
150  through a Dirac delta BSDF */
151  EIndirectSurfaceRadiance = 0x0008,
152 
153  /*! \brief Indirect (surface) radiance, where the last bounce went
154  through a Dirac delta BSDF */
155  ECausticRadiance = 0x0010,
156 
157  /// In-scattered radiance due to volumetric scattering (direct)
158  EDirectMediumRadiance = 0x0020,
159 
160  /// In-scattered radiance due to volumetric scattering (indirect)
161  EIndirectMediumRadiance = 0x0040,
162 
163  /// Distance to the next surface intersection
164  EDistance = 0x0080,
165 
166  /*! \brief Store an opacity value, which is equal to 1 when a shape
167  was intersected and 0 when the ray passes through empty space.
168  When there is a participating medium, it can also take on fractional
169  values. */
170  EOpacity = 0x0100,
171 
172  /*! \brief A ray intersection may need to be performed. This can be set to
173  zero if the caller has already provided the intersection */
174  EIntersection = 0x0200,
175 
176  /* Radiance from volumes */
177  EVolumeRadiance = EDirectMediumRadiance | EIndirectMediumRadiance,
178 
179  /// Radiance query without emitted radiance, ray intersection required
180  ERadianceNoEmission = ESubsurfaceRadiance | EDirectSurfaceRadiance
181  | EIndirectSurfaceRadiance | ECausticRadiance | EDirectMediumRadiance
182  | EIndirectMediumRadiance | EIntersection,
183 
184  /// Default radiance query, ray intersection required
185  ERadiance = ERadianceNoEmission | EEmittedRadiance,
186 
187  /// Radiance + opacity
188  ESensorRay = ERadiance | EOpacity
189  };
190 
191  /// Additional flags that can be specified in the \ref extra field
192  enum EExtraFlags {
193  /// This is a query by an irradiance cache
194  ECacheQuery = 0x01,
195  /// This is a query by an adaptive integrator
196  EAdaptiveQuery = 0x02
197  };
198 
199  /// Construct an invalid radiance query record
201  : type(0), scene(NULL), sampler(NULL), medium(NULL),
202  depth(0), alpha(0), dist(-1), extra(0) {
203  }
204 
205  /// Construct a radiance query record for the given scene and sampler
206  inline RadianceQueryRecord(const Scene *scene, Sampler *sampler)
207  : type(0), scene(scene), sampler(sampler), medium(NULL),
208  depth(0), alpha(0), dist(-1), extra(0) {
209  }
210 
211  /// Copy constructor
213  : type(rRec.type), scene(rRec.scene), sampler(rRec.sampler), medium(rRec.medium),
214  depth(rRec.depth), alpha(rRec.alpha), dist(rRec.dist), extra(rRec.extra) {
215  }
216 
217  /// Begin a new query of the given type
218  inline void newQuery(int _type, const Medium *_medium) {
219  type = _type;
220  medium = _medium;
221  depth = 1;
222  extra = 0;
223  alpha = 1;
224  }
225 
226  /// Initialize the query record for a recursive query
227  inline void recursiveQuery(const RadianceQueryRecord &parent, int _type) {
228  type = _type;
229  scene = parent.scene;
230  sampler = parent.sampler;
231  depth = parent.depth+1;
232  medium = parent.medium;
233  extra = parent.extra;
234  }
235 
236  /// Initialize the query record for a recursive query
237  inline void recursiveQuery(const RadianceQueryRecord &parent) {
238  type = parent.type | EIntersection;
239  scene = parent.scene;
240  sampler = parent.sampler;
241  depth = parent.depth+1;
242  medium = parent.medium;
243  extra = parent.extra;
244  }
245 
246  /**
247  * \brief Search for a ray intersection
248  *
249  * This function does several things at once: if the
250  * intersection has already been provided, it returns.
251  *
252  * Otherwise, it
253  * 1. performs the ray intersection
254  * 2. computes the transmittance due to participating media
255  * and stores it in \c transmittance.
256  * 3. sets the alpha value (if \c EAlpha is set in \c type)
257  * 4. sets the distance value (if \c EDistance is set in \c type)
258  * 5. clears the \c EIntersection flag in \c type
259  *
260  * \return \c true if there is a valid intersection.
261  */
262  inline bool rayIntersect(const RayDifferential &ray);
263 
264  /// Retrieve a 2D sample
265  inline Point2 nextSample2D();
266 
267  /// Retrieve a 1D sample
268  inline Float nextSample1D();
269 
270  /// Return a string representation
271  std::string toString() const;
272 public:
273  // An asterisk (*) marks entries, which may be overwritten
274  // by the callee.
275 
276  /// Query type (*)
277  int type;
278 
279  /// Pointer to the associated scene
280  const Scene *scene;
281 
282  /// Sample generator
284 
285  /// Pointer to the current medium (*)
286  const Medium *medium;
287 
288  /// Current depth value (# of light bounces) (*)
289  int depth;
290 
291  /// Surface interaction data structure (*)
293 
294  /// Opacity value of the associated pixel (*)
296 
297  /**
298  * Ray distance to the first surface interaction
299  * (if requested by the query type EDistance) (*)
300  */
302 
303  /**
304  * Internal flag, which can be used to pass additional information
305  * amonst recursive calls inside an integrator. The use
306  * is dependent on the particular integrator implementation. (*)
307  */
308  int extra;
309 };
310 
311 /** \brief Abstract base class, which describes integrators
312  * capable of computing samples of the scene's radiance function.
313  * \ingroup librender
314  */
316 public:
317  /**
318  * \brief Sample the incident radiance along a ray. Also requires
319  * a radiance query record, which makes this request more precise.
320  */
321  virtual Spectrum Li(const RayDifferential &ray,
322  RadianceQueryRecord &rRec) const = 0;
323 
324  /**
325  * \brief Estimate the irradiance at a given surface point
326  *
327  * The default implementation simply samples the hemisphere using
328  * cosine-weighted sampling and a configurable number of rays.
329  * An integrator such as irradiance caching will provide something
330  * smarter.
331  *
332  * \param scene
333  * Const pointer to the underlying scene
334  * \param its
335  * Describes the surface location where the irradiance is to be computed
336  * \param medium
337  * Const pointer to the medium that encloses the ray
338  * <tt>(its.p, its.shFrame.n)</tt>. A value of \c NULL corresponds
339  * to vacuum.
340  * \param sampler
341  * A pointer to a sample generator
342  * \param nSamples
343  * How many samples should be taken
344  * \param includeIndirect
345  * Include indirect illumination in the estimate?
346  */
347  virtual Spectrum E(const Scene *scene, const Intersection &its,
348  const Medium *medium, Sampler *sampler, int nSamples,
349  bool includeIndirect) const;
350 
351  /**
352  * \brief Perform the main rendering task
353  *
354  * The work is automatically parallelized to multiple cores and
355  * remote machines. The default implementation uniformly generates
356  * samples on the sensor aperture and image plane as specified by
357  * the used sampler. The average of the estimated radiance along the
358  * associated rays in a pixel region is then taken as an approximation
359  * of that pixel's radiance value. For adaptive strategies, have a look at
360  * the \c adaptive plugin, which is an extension of this class.
361  */
362  bool render(Scene *scene, RenderQueue *queue, const RenderJob *job,
363  int sceneResID, int sensorResID, int samplerResID);
364 
365  /**
366  * This can be called asynchronously to cancel a running render job.
367  * In this case, <tt>render()</tt> will quit with a return value of
368  * <tt>false</tt>.
369  */
370  void cancel();
371 
372  /**
373  * This method does the main work of <tt>render()</tt> and
374  * runs in parallel for a series of image blocks, which are
375  * being processed at a time.
376  *
377  * \param scene
378  * Pointer to the underlying scene
379  * \param sensor
380  * Pointer to the sensor used to render the image
381  * \param sampler
382  * Pointer to the sampler used to render the image
383  * \param block
384  * Pointer to the image block to be filled
385  * \param points
386  * Specifies the traversal order, i.e. using a space-filling
387  * curve. To limit the size of the array, it is currently assumed
388  * that the block size is smaller than 256x256
389  * \param stop
390  * Reference to a boolean, which will be set to true when
391  * the user has requested that the program be stopped
392  */
393  virtual void renderBlock(const Scene *scene, const Sensor *sensor,
394  Sampler *sampler, ImageBlock *block, const bool &stop,
395  const std::vector< TPoint2<uint8_t> > &points) const;
396 
397  /**
398  * <tt>NetworkedObject</tt> implementation:
399  * When a parallel rendering process starts, the integrator is
400  * given the opportunity to attach globally shared resources to
401  * the process. This is useful for distributing heavy data
402  * structures (e.g. photon maps) without having to re-transmit
403  * them every time an image is rendered.
404  */
405  virtual void bindUsedResources(ParallelProcess *proc) const;
406 
407  /**
408  * <tt>NetworkedObject</tt> implementation:
409  * Called once just before this integrator instance is asked
410  * to process an image block. In comparison to <tt>preprocess()</tt>
411  * this will be executed on _every_ instance of this class, which is
412  * useful for connecting to globally shared resources (photon maps,
413  * irradiance caches, ..) after having been unserialized on a
414  * remote machine. A list of resources bound to the associated
415  * parallel process is given as a parameter.
416  */
417  virtual void wakeup(ConfigurableObject *parent,
418  std::map<std::string, SerializableObject *> &params);
419 
420  /// Serialize this integrator to a binary data stream
421  void serialize(Stream *stream, InstanceManager *manager) const;
422 
424 protected:
425  /// Create a integrator
426  SamplingIntegrator(const Properties &props);
427 
428  /// Unserialize an integrator
429  SamplingIntegrator(Stream *stream, InstanceManager *manager);
430 
431  /// Virtual destructor
432  virtual ~SamplingIntegrator() { }
433 protected:
434  /// Used to temporarily cache a parallel process while it is in operation
436 };
437 
438 /*
439  * \brief Base class of all recursive Monte Carlo integrators, which compute
440  * unbiased solutions to the rendering equation (and optionally
441  * the radiative transfer equation).
442  * \ingroup librender
443  */
445 public:
446  /// Serialize this integrator to a binary data stream
447  void serialize(Stream *stream, InstanceManager *manager) const;
448 
450 protected:
451  /// Create a integrator
452  MonteCarloIntegrator(const Properties &props);
453  /// Unserialize an integrator
454  MonteCarloIntegrator(Stream *stream, InstanceManager *manager);
455  /// Virtual destructor
456  virtual ~MonteCarloIntegrator() { }
457 protected:
462 };
463 
465 
466 #endif /* __MITSUBA_RENDER_INTEGRATOR_H_ */
RadianceQueryRecord()
Construct an invalid radiance query record.
Definition: integrator.h:200
Abstract participating medium.
Definition: medium.h:103
int extra
Definition: integrator.h:308
Generic serializable object, which supports construction from a Properties instance.
Definition: cobject.h:40
int depth
Current depth value (# of light bounces) (*)
Definition: integrator.h:289
virtual void cancel()=0
Cancel a running render job.
int m_maxDepth
Definition: integrator.h:458
Sampler * sampler
Sample generator.
Definition: integrator.h:283
void recursiveQuery(const RadianceQueryRecord &parent)
Initialize the query record for a recursive query.
Definition: integrator.h:237
RadianceQueryRecord(const RadianceQueryRecord &rRec)
Copy constructor.
Definition: integrator.h:212
virtual void bindUsedResources(ParallelProcess *proc) const
Bind any used resources to the process proc.
Principal scene data structure.
Definition: scene.h:49
Render queue - used to keep track of a number of scenes that are simultaneously being rendered...
Definition: renderqueue.h:65
Abstract sensor interface.
Definition: sensor.h:66
Base class of all sample generators.
Definition: sampler.h:66
int m_rrDepth
Definition: integrator.h:459
ERadianceQuery
List of suported query types. These can be combined by a binary OR.
Definition: integrator.h:139
void serialize(Stream *stream, InstanceManager *manager) const
Serialize this integrator to a binary data stream.
Abstract parallelizable task.
Definition: sched.h:197
#define MTS_NAMESPACE_BEGIN
Definition: platform.h:137
void newQuery(int _type, const Medium *_medium)
Begin a new query of the given type.
Definition: integrator.h:218
virtual bool render(Scene *scene, RenderQueue *queue, const RenderJob *job, int sceneResID, int sensorResID, int samplerResID)=0
Render the scene as seen by the default sensor.
ref< ParallelProcess > m_process
Used to temporarily cache a parallel process while it is in operation.
Definition: integrator.h:435
const Scene * scene
Pointer to the associated scene.
Definition: integrator.h:280
Radiance query record data structure used by SamplingIntegrator.
Definition: integrator.h:136
EExtraFlags
Additional flags that can be specified in the extra field.
Definition: integrator.h:192
Ray differential – enhances the basic ray class with information about the rays of adjacent pixels on...
Definition: ray.h:140
Parameterizable two-dimensional point data structure.
Definition: point.h:222
Intersection its
Surface interaction data structure (*)
Definition: integrator.h:292
int type
Query type (*)
Definition: integrator.h:277
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
const Medium * medium
Pointer to the current medium (*)
Definition: integrator.h:286
Reference counting helper.
Definition: ref.h:40
virtual void wakeup(ConfigurableObject *parent, std::map< std::string, SerializableObject * > &params)
Retrieve any required resources.
virtual void serialize(Stream *stream, InstanceManager *manager) const
Serialize this object to a stream.
Storage for an image sub-block (a.k.a render bucket)
Definition: imageblock.h:40
Definition: integrator.h:444
Abstract interface for objects that reference shared network resources.
Definition: netobject.h:40
Abstract integrator base-class; does not make any assumptions on how radiance is computed.
Definition: integrator.h:49
Abstract base class, which describes integrators capable of computing samples of the scene&#39;s radiance...
Definition: integrator.h:315
void serialize(Stream *stream, InstanceManager *manager) const
Serialize this integrator to a binary data stream.
Coordinates the process of rendering a single image.
Definition: renderjob.h:37
Associative parameter map for constructing subclasses of ConfigurableObject.
Definition: properties.h:46
Container for all information related to a surface intersection.
Definition: shape.h:36
Coordinates the serialization and unserialization of object graphs.
Definition: serialization.h:65
bool m_hideEmitters
Definition: integrator.h:461
#define MTS_EXPORT_RENDER
Definition: platform.h:109
bool m_strictNormals
Definition: integrator.h:460
Discrete spectral power distribution based on a number of wavelength bins over the 360-830 nm range...
Definition: spectrum.h:663
Float alpha
Opacity value of the associated pixel (*)
Definition: integrator.h:295
Radiance transport.
Definition: common.h:38
#define MTS_NAMESPACE_END
Definition: platform.h:138
Float dist
Definition: integrator.h:301
void recursiveQuery(const RadianceQueryRecord &parent, int _type)
Initialize the query record for a recursive query.
Definition: integrator.h:227
RadianceQueryRecord(const Scene *scene, Sampler *sampler)
Construct a radiance query record for the given scene and sampler.
Definition: integrator.h:206