Mitsuba Renderer  0.5.0
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
phase.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_PHASE_H_)
21 #define __MITSUBA_RENDER_PHASE_H_
22 
23 #include <mitsuba/core/netobject.h>
24 #include <mitsuba/render/common.h>
25 
27 
28 /**
29  * \brief Data structure, which contains information
30  * required to sample or query a phase function.
31  *
32  * \ingroup librender
33  */
35  /**
36  * \brief Reference to a Medium sampling record created
37  * by \ref Medium::sampleDistance()
38  */
40 
41  /**
42  * \brief Normalized incident direction vector, which points away
43  * from the scattering event.
44  *
45  * In Mitsuba, the direction convention for phase functions is the
46  * same as for BSDFs, as opposed to much of the literature, where
47  * \c wi points inwards.
48  */
50 
51  /// Normalized outgoing direction vector
53 
54  /* Transported mode (radiance or importance) -- required for
55  rendering with non-reciprocal phase functions */
57 
58  /**
59  * \brief Given a medium interaction and an incident direction,
60  * construct a query record which can be used to sample an outgoing
61  * direction.
62  *
63  * \param mRec
64  * An reference to the underlying medium sampling record
65  * \param wi
66  * An incident direction in world coordinates. This should
67  * be a normalized direction vector that points \a away from
68  * the scattering event.
69  * \param mode
70  * The transported mode (\ref ERadiance or \ref EImportance)
71  */
72 
74  const Vector &wi, ETransportMode mode = ERadiance)
75  : mRec(mRec), wi(wi), mode(mode) { }
76 
77  /*
78  * \brief Given a medium interaction an an incident/exitant direction
79  * pair (wi, wo), create a query record to evaluate the phase function
80  * or its sampling density.
81  *
82  * \param mRec
83  * An reference to the underlying medium sampling record
84  * \param wi
85  * An incident direction in world coordinates. This should
86  * be a normalized direction vector that points \a away from
87  * the scattering event.
88  * \param wo
89  * An outgoing direction in world coordinates. This should
90  * be a normalized direction vector that points \a away from
91  * the scattering event.
92  * \param mode
93  * The transported mode (\ref ERadiance or \ref EImportance)
94  */
96  const Vector &wi, const Vector &wo, ETransportMode mode = ERadiance)
97  : mRec(mRec), wi(wi), wo(wo), mode(mode) { }
98 
99  /**
100  * \brief Reverse the direction of light transport in the record
101  *
102  * This function essentially swaps \c wi and \c wo and adjusts
103  * \c mode appropriately, so that non-symmetric scattering
104  * models can be queried in the reverse direction.
105  */
106  inline void reverse() {
107  std::swap(wo, wi);
108  mode = (ETransportMode) (1-mode);
109  }
110 
111  std::string toString() const;
112 };
113 
114 /** \brief Abstract phase function.
115  * \ingroup librender
116  */
118 public:
120  /// Completely isotropic 1/(4 pi) phase function
121  EIsotropic = 0x01,
122  /// The phase function only depends on \c dot(wi,wo)
123  EAngleDependence = 0x04,
124  /// The opposite of \ref EAngleDependence (there is an arbitrary dependence)
125  EAnisotropic = 0x02,
126  /// The phase function is non symmetric, i.e. eval(wi,wo) != eval(wo, wi)
127  ENonSymmetric = 0x08
128  };
129 
130  /**
131  * \brief Return information flags of this phase function,
132  * combined binary OR.
133  * \sa EPhaseFunctionType
134  */
135  inline unsigned int getType() const {
136  return m_type;
137  }
138 
139  /// Configure the material (called after construction by the XML parser)
140  virtual void configure();
141 
142  /**
143  * \brief Evaluate the phase function for an outward-pointing
144  * pair of directions (wi, wo)
145  */
146  virtual Float eval(const PhaseFunctionSamplingRecord &pRec) const = 0;
147 
148  /**
149  * \brief Sample the phase function and return the importance weight (i.e. the
150  * value of the phase function divided by the probability density of the sample).
151  *
152  * When the probability density is not explicitly required, this function
153  * should be preferred, since it is potentially faster by making use of
154  * cancellations during the division.
155  *
156  * \param pRec A phase function query record
157  * \param sampler A sample generator
158  *
159  * \return The phase function value divided by the probability
160  * density of the sample
161  */
162  virtual Float sample(PhaseFunctionSamplingRecord &pRec,
163  Sampler *sampler) const = 0;
164 
165  /**
166  * \brief Sample the phase function and return the probability density \a and the
167  * importance weight of the sample (i.e. the value of the phase function divided
168  * by the probability density)
169  *
170  * \param pRec A phase function query record
171  * \param sampler A sample generator
172  * \param pdf Will record the probability with respect to solid angles
173  *
174  * \return The phase function value divided by the probability
175  * density of the sample
176  */
177  virtual Float sample(PhaseFunctionSamplingRecord &pRec,
178  Float &pdf, Sampler *sampler) const = 0;
179 
180  /**
181  * \brief Calculate the probability of sampling wo (given wi).
182  *
183  * Assuming that the phase function can be sampled exactly,
184  * the default implementation just evaluates \ref eval()
185  */
186  virtual Float pdf(const PhaseFunctionSamplingRecord &pRec) const;
187 
188  /**
189  * \brief Does this phase function require directionally varying scattering
190  * and extinction coefficients?
191  *
192  * This is used to implement rendering of media that have an anisotropic
193  * structure (cf. "A radiative transfer framework for rendering materials with
194  * anisotropic structure" by Wenzel Jakob, Adam Arbree, Jonathan T. Moon,
195  * Kavita Bala, and Steve Marschner, SIGGRAPH 2010)
196  */
197  virtual bool needsDirectionallyVaryingCoefficients() const;
198 
199  /**
200  * \brief For anisotropic media: evaluate the directionally varying component
201  * of the scattering and absorption coefficients.
202  *
203  * \param cosTheta
204  * Angle between the axis of rotational symmetry and the
205  * direction of propagation
206  */
207  virtual Float sigmaDir(Float cosTheta) const;
208 
209  /**
210  * \brief Returns the maximum value take on on by \ref sigmaDirMax().
211  * This is useful when implementing Woodcock tracking.
212  */
213  virtual Float sigmaDirMax() const;
214 
215  /**
216  * \brief Returns the mean cosine (often referred to by
217  * the constant "g") of this phase function
218  *
219  * The default implementation throws an exception
220  */
221  virtual Float getMeanCosine() const;
222 
223  /// Return a string representation
224  virtual std::string toString() const = 0;
225 
227 protected:
228  /// Create a new phase function instance
229  inline PhaseFunction(const Properties &props) :
230  ConfigurableObject(props) { }
231 
232  /// Unserialize a phase function
233  inline PhaseFunction(Stream *stream, InstanceManager *manager) :
234  ConfigurableObject(stream, manager) { }
235 
236  /// Virtual destructor
237  virtual ~PhaseFunction() { }
238 protected:
239  unsigned int m_type;
240 };
241 
243 
244 #endif /* __MITSUBA_RENDER_PHASE_H_ */
PhaseFunction(Stream *stream, InstanceManager *manager)
Unserialize a phase function.
Definition: phase.h:233
unsigned int m_type
Definition: phase.h:239
Generic serializable object, which supports construction from a Properties instance.
Definition: cobject.h:40
const MediumSamplingRecord & mRec
Reference to a Medium sampling record created by Medium::sampleDistance()
Definition: phase.h:39
PhaseFunctionSamplingRecord(const MediumSamplingRecord &mRec, const Vector &wi, ETransportMode mode=ERadiance)
Given a medium interaction and an incident direction, construct a query record which can be used to s...
Definition: phase.h:73
void reverse()
Reverse the direction of light transport in the record.
Definition: phase.h:106
Vector wo
Normalized outgoing direction vector.
Definition: phase.h:52
ETransportMode mode
Definition: phase.h:56
Base class of all sample generators.
Definition: sampler.h:66
virtual ~PhaseFunction()
Virtual destructor.
Definition: phase.h:237
#define MTS_NAMESPACE_BEGIN
Definition: platform.h:137
Data record for sampling a point on the in-scattering integral of the RTE.
Definition: medium.h:34
PhaseFunctionSamplingRecord(const MediumSamplingRecord &mRec, const Vector &wi, const Vector &wo, ETransportMode mode=ERadiance)
Definition: phase.h:95
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
virtual void configure()
Configure the object (called once after construction and addition of all child ConfigurableObject ins...
Abstract phase function.
Definition: phase.h:117
Definition: fwd.h:96
EPhaseFunctionType
Definition: phase.h:119
unsigned int getType() const
Return information flags of this phase function, combined binary OR.
Definition: phase.h:135
Associative parameter map for constructing subclasses of ConfigurableObject.
Definition: properties.h:46
Data structure, which contains information required to sample or query a phase function.
Definition: phase.h:34
Coordinates the serialization and unserialization of object graphs.
Definition: serialization.h:65
#define MTS_EXPORT_RENDER
Definition: platform.h:109
Vector wi
Normalized incident direction vector, which points away from the scattering event.
Definition: phase.h:49
virtual std::string toString() const
Return a human-readable string representation of the object&#39;s contents.
Radiance transport.
Definition: common.h:38
#define MTS_NAMESPACE_END
Definition: platform.h:138
ETransportMode
Specifies the transport mode when sampling or evaluating a scattering function.
Definition: common.h:33