Mitsuba Renderer  0.5.0
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
edge.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_BIDIR_EDGE_H_)
21 #define __MITSUBA_BIDIR_EDGE_H_
22 
23 #include <mitsuba/bidir/common.h>
24 
26 
27 /**
28  * \brief Bidirectional path edge data structure
29  *
30  * The path edge data structure is responsible for representing the transport of
31  * light between pairs of scattering or emission events.
32  * Amongst other things, it keeps track of the medium that fills the space between
33  * adjacent vertices of a \ref Path. Furthermore, it can be used to evaluate and
34  * sample the visibility and transmittance functions of the scene.
35  *
36  * Although they do not correspond to any real transport, this implementation
37  * also places edges next to "supernode" vertices (see \ref PathVertex for a
38  * description), which simplifies the implementations of various rendering
39  * algorithms that make use of this framework.
40  *
41  * \sa PathVertex
42  *
43  * \author Wenzel Jakob
44  * \ingroup libbidir
45  */
47  /* ==================================================================== */
48  //! @{ \name Enumerations and Fields
49  /* ==================================================================== */
50 
51  /// Pointer to the medium that contains this edge (where \c NULL is vacuum)
52  const Medium *medium;
53 
54  /**
55  * \brief Normalized direction vector associated with this edge
56  *
57  * The direction always points along the light path (from the light)
58  */
60 
61  /**
62  * \brief Length of this edge in world-space distance units
63  *
64  * Note that edges adjacent to supernodes have length zero to
65  * mark them as such.
66  */
68 
69  /**
70  * \brief Measurement contribution weight
71  *
72  * This field stores the terms of the path-space measurement contribution
73  * function that are coupled to this specific edge divided by the
74  * associated density function.
75  *
76  * More specifically, it stores the transmittance of the medium across
77  * this edge divided by the density per unit length of the adjacent
78  * vertices int the radiance and importance transport directions (hence,
79  * it is an array with two entries).
80  *
81  * Note that this field only accounts for medium-related terms. The
82  * interactions with vertices are captured by \ref PathVertex::weight.
83  */
85 
86  /**
87  * \brief Medium sampling density of the adjacent vertices
88  *
89  * This field stores the probability of sampling the preceding and
90  * successive path vertices using the sampling technique implemented by
91  * the function \ref PathEdge::sampleNext(). Depending on whether or not
92  * they are medium interactions, this eintries either store a density per
93  * unit length or a discrete probability.
94  */
96 
97  //! @}
98  /* ==================================================================== */
99 
100  /* ==================================================================== */
101  //! @{ \name Sampling-related functions
102  /* ==================================================================== */
103 
104  /**
105  * \brief Given a ray \c ray, sample a distance in this direction and
106  * fill the edge data structure, as well as its target vertex with content.
107  *
108  * \param scene
109  * Pointer to the underlying scene
110  * \param sampler
111  * Pointer to a sample generator
112  * \param pred
113  * Pointer to the preceding vertex
114  * \param ray
115  * Specifies the direction and origin associated with one
116  * endpoint of the edge. The sampling routine will then determine
117  * the other endpoint.
118  * \param succ
119  * Pointer to an unused vertex data structure, which will be filled
120  * with information about the successor vertex
121  * \param mode
122  * Specifies whether radiance or importance is being transported
123  * \return \c true on success
124  */
125  bool sampleNext(const Scene *scene, Sampler *sampler,
126  const PathVertex *pred, const Ray &ray, PathVertex *next,
127  ETransportMode mode);
128 
129  /**
130  * \brief Create a perturbed successor vertex and edge
131  *
132  * This function behaves similar to \ref sampleNext() in that it
133  * generates a successor edge and vertex.
134  *
135  * The main difference is that the desired direction, distance, and
136  * type of the successor vertex are all specified, which makes the
137  * sampling process completely deterministic. This is useful for
138  * implementing path-space perturbation strategies.
139  *
140  * \param scene
141  * Pointer to the underlying scene
142  * \param pred
143  * Pointer to the preceding vertex
144  * \param ray
145  * Specifies the direction and origin associated with one
146  * endpoint of the edge. The sampling routine will then determine
147  * the other endpoint.
148  * \param dist
149  * Specifies the desired distance between the current vertex and \c succ
150  * (this only applies when <tt>desiredType=EMediumInteraction</tt>)
151  * \param desiredType
152  * Specifies the desired vertex type of \c succ.
153  * \param succ
154  * Pointer to an unused vertex data structure, which will be filled
155  * with information about the successor vertex
156  * \param mode
157  * Specifies whether radiance or importance is being transported
158  * \return \c true on success
159  */
160  bool perturbDirection(const Scene *scene, const PathVertex *pred,
161  const Ray &ray, Float dist, PathVertex::EVertexType desiredType,
162  PathVertex *next, ETransportMode mode);
163 
164  //! @}
165  /* ==================================================================== */
166 
167  /* ==================================================================== */
168  //! @{ \name Query functions
169  /* ==================================================================== */
170 
172  EValueImp = 0x01,
173  EValueRad = 0x02,
174  ECosineImp = 0x04,
175  ECosineRad = 0x08,
176  EValue = EValueImp | EValueRad,
177  ECosine = ECosineImp | ECosineRad,
178  EValueCosineImp = EValueImp | ECosineImp,
179  EValueCosineRad = EValueRad | ECosineRad,
180  EInverseSquareFalloff = 0x10,
181  ETransmittance = 0x20,
182  EGeometricTerm = ECosine | EInverseSquareFalloff,
183  EGeneralizedGeometricTerm = EGeometricTerm | ETransmittance,
184  EEverything = EValue | EGeneralizedGeometricTerm
185  };
186 
187  /**
188  * \brief Evaluate cached quantities associated with this edge
189  *
190  * This function computes the product of certain terms that are cached
191  * in this edge and its adjacent vertices. The \c what parameter specifies
192  * the terms to be included; it must be a combination of the flags
193  * in the enumeration \ref ECachedValues.
194  *
195  * \remark This function assumes that \c pred and \c succ are the
196  * vertices associated with this edge, and that they have not been
197  * modified since the edge was created.
198  *
199  * \param pred
200  * The predecessor vertex of this edge
201  * \param succ
202  * The successor vertex of this edge
203  */
204  Spectrum evalCached(const PathVertex *pred, const PathVertex *succ,
205  unsigned int what) const;
206 
207  /**
208  * \brief Compute the density of a successor node
209  *
210  * This function computes the hypothetical transport-related sampling density
211  * of a given successor node conditioned on a specified predecessor when
212  * using the sampling technique implemented by \ref sampleNext(). Depending
213  * on whether or not the successor node is a medium interaction, the returned
214  * value is either a density per unit length or a discrete probability.
215  *
216  * Note: this function only computes terms associated with the transport
217  * between vertices -- to account for the vertices themselves,
218  * refer to \ref PathEdge::evalPdf.
219  *
220  * \param scene
221  * Pointer to the underlying scene
222  * \param pred
223  * Pointer to the preceding vertex
224  * \param succ
225  * Pointer to the successor vertex
226  *
227  * \return The computed probability density
228  */
229  Float evalPdf(const PathVertex *pred, const PathVertex *succ) const;
230 
231  /**
232  * \brief Compute the transmittance between an arbitrary
233  * pair of vertices
234  *
235  * This function queries the medium associated with this edge for the
236  * transmittance between an arbitrary pair of nodes, \c pred and \c succ.
237  *
238  * \param pred
239  * Pointer to the preceding vertex
240  * \param succ
241  * Pointer to the successor vertex
242  *
243  * \return A spectrally varying transmittance value
244  */
245  Spectrum evalTransmittance(const PathVertex *pred, const PathVertex *succ) const;
246 
247  /**
248  * \brief Return the transmittance value associated with this edge
249  *
250  * \param pred
251  * Pointer to the preceding vertex
252  * \param succ
253  * Pointer to the successor vertex
254  *
255  * \return A spectrally varying transmittance value
256  */
257  Spectrum evalTransmittance() const;
258 
259  /**
260  * \brief Evaluate the one of the cosine factors associated with the geometric
261  * term over an edge
262  */
263  Float evalCosine(const PathVertex *pred, const PathVertex *succ, const PathVertex *base) const;
264 
265 
266  //! @}
267  /* ==================================================================== */
268 
269  /* ==================================================================== */
270  //! @{ \name Miscellaneous
271  /* ==================================================================== */
272 
273  /**
274  * \brief Verify the cached values stored in this path vertex
275  * for consistency
276  *
277  * This function re-evaluates a series of quantities associated with
278  * this edge and compares them to locally cached values.
279  * If any mismatch is found, the function sends debug output to a
280  * specified output stream and returns \c false.
281  *
282  * \param scene
283  * Pointer to the underlying scene
284  * \param pred
285  * Pointer to the vertex adjacent in the emitter direction or \c NULL
286  * \param succ
287  * Pointer to the vertex adjacent in the sensor direction or \c NULL
288  * \param mode
289  * Transport mode -- disambiguates the meaning of \c pred and \c succ.
290  * \param os
291  * Target output stream for error messages
292  */
293  bool verify(const Scene *scene, const PathVertex *adjL,
294  const PathVertex *adjE, ETransportMode mode, std::ostream &os) const;
295 
296  /**
297  * \brief Create a connection edge between two vertices
298  *
299  * This function can be used to create an edge data structure
300  * when connecting two separately sampled path vertices. This
301  * involves checking that they are mutually visible and computing
302  * the attenuation caused by the medium in between (if any).
303  *
304  * \param scene
305  * Pointer to the underlying scene
306  * \param predEdge
307  * Pointer to an edge between \c vs and its predecessor
308  * (which is not needed by this function)
309  * \param vs
310  * First path vertex to be connected.
311  * \param vt
312  * Second path vertex to be connected.
313  * \param succEdge
314  * Pointer to an edge between \c vt and its successor
315  * (which is not needed by this function)
316  * \return \c true upon success, \c false when there is no
317  * throughput or an inconsistency has been detected.
318  */
319  bool connect(const Scene *scene, const PathEdge *predEdge,
320  const PathVertex *vs, const PathVertex *vt,
321  const PathEdge *succEdge);
322 
323  /**
324  * \brief Create a connection path between two vertices
325  *
326  * This function is conceptually similar to \ref connect().
327  * However, instead of a single edge, it potentially generates
328  * an entire connection path, where intermediate vertices are
329  * either index-matched medium transitions or other surface
330  * scattering events of type \ref BSDF::ENull.
331  *
332  * This is important to support efficient direct illumination sampling
333  * through such surfaces (e.g. a heterogeneous medium or a leaf with
334  * textured alpha transparency).
335  *
336  * \param scene
337  * Pointer to the underlying scene
338  * \param predEdge
339  * Pointer to an edge between \c vs and its predecessor
340  * (which is not needed by this function)
341  * \param vs
342  * First path vertex to be connected.
343  * \param result
344  * A path data structure that will be filled with the
345  * created vertices and edges
346  * \param vt
347  * Second path vertex to be connected.
348  * \param succEdge
349  * Pointer to an edge between \c vt and its successor
350  * (which is not needed by this function)
351  * \param maxInteractions
352  * Specifies the maximum permissible number of intermediate
353  * vertices (-1 == arbitrarily many)
354  * \param pool
355  * Reference to memory pool that will be used to allocate
356  * edges and vertices.
357  * \return \c true upon success, \c false when there is no
358  * throughput or an inconsistency has been detected.
359  */
360  static bool pathConnect(const Scene *scene, const PathEdge *predEdge,
361  const PathVertex *vs, Path &result, const PathVertex *vt,
362  const PathEdge *succEdge, int maxInteractions, MemoryPool &pool);
363 
364  /**
365  * \brief Create a connection path between two vertices and
366  * collapse it into a single edge that summarizes its properties
367  *
368  * This function can be thought of as being half-way in between
369  * \c connect() and \c pathConnect(). Like \c pathConnect(), it
370  * potentially generates an entire connection path between the
371  * specified endpoints, where intermediate vertices are
372  * either index-matched medium transitions or other surface
373  * scattering events of type \ref BSDF::ENull.
374  *
375  * This is important to support efficient direct illumination sampling
376  * through such surfaces (e.g. a heterogeneous medium or a leaf with
377  * textured alpha transparency).
378  *
379  * However, this variant does not return the intermediate vertices
380  * and edges -- instead, everything is collapsed into a single
381  * edge that captures the aggregate weight and probability densities.
382  *
383  * This function is used by bidirectional path tracing, since it creates
384  * connections through index-matched boundaries but does not require
385  * explicit knowledge about the associated path vertices.
386  *
387  * \param scene
388  * Pointer to the underlying scene
389  * \param predEdge
390  * Pointer to an edge between \c vs and its predecessor
391  * (which is not needed by this function)
392  * \param vs
393  * First path vertex to be connected.
394  * \param vt
395  * Second path vertex to be connected.
396  * \param succEdge
397  * Pointer to an edge between \c vt and its successor
398  * (which is not needed by this function)
399  * \param interactions
400  * Specifies the maximum permissible number of index-matched medium
401  * transitions or \ref BSDF::ENull scattering events on the way
402  * to the light source. (<tt>interactions<0</tt> means arbitrarily many).
403  * When the function is successful, this parameter will
404  * additionally be used to return the actual number of intermediate
405  * interactions.
406  * \return \c true upon success, \c false when there is no
407  * throughput or an inconsistency has been detected.
408  */
409  bool pathConnectAndCollapse(const Scene *scene, const PathEdge *predEdge,
410  const PathVertex *vs, const PathVertex *vt,
411  const PathEdge *succEdge, int &interactions);
412 
413  /// Create a deep copy of this edge
414  PathEdge *clone(MemoryPool &pool) const;
415 
416  /// Compare this edge against another edge
417  bool operator==(const PathEdge &edge) const;
418 
419  /// Compare this edge against another edge
420  inline bool operator!=(const PathEdge &edge) const {
421  return !operator==(edge);
422  }
423 
424  /// Return a string representation of the information stored in this vertex
425  std::string toString() const;
426 
427  //! @}
428  /* ==================================================================== */
429 };
430 
432 
433 #endif /* __MITSUBA_BIDIR_EDGE_H_ */
Abstract participating medium.
Definition: medium.h:103
#define MTS_EXPORT_BIDIR
Definition: platform.h:119
Bidirectional path vertex data structure.
Definition: vertex.h:48
EVertexType
What kind of vertex is this (e.g. medium, surface, emitter)?
Definition: vertex.h:67
Principal scene data structure.
Definition: scene.h:49
Base class of all sample generators.
Definition: sampler.h:66
Float length
Length of this edge in world-space distance units.
Definition: edge.h:67
Bidirectional path data structure.
Definition: path.h:46
#define MTS_NAMESPACE_BEGIN
Definition: platform.h:137
ECachedValues
Evaluate cached quantities associated with this edge.
Definition: edge.h:171
const Medium * medium
Pointer to the medium that contains this edge (where NULL is vacuum)
Definition: edge.h:52
Specifies the number of supported transport modes.
Definition: common.h:42
Vector d
Normalized direction vector associated with this edge.
Definition: edge.h:59
Bidirectional path edge data structure.
Definition: edge.h:46
Definition: fwd.h:65
Definition: fwd.h:96
bool operator!=(const PathEdge &edge) const
Compare this edge against another edge.
Definition: edge.h:420
Discrete spectral power distribution based on a number of wavelength bins over the 360-830 nm range...
Definition: spectrum.h:663
Definition: mempool.h:29
#define MTS_NAMESPACE_END
Definition: platform.h:138
ETransportMode
Specifies the transport mode when sampling or evaluating a scattering function.
Definition: common.h:33