updates to the documentation

doc/gendoc.py

@@ -45,6 +45,8 @@ f = open('plugins_generated.tex', 'w')
 f.write('\section{Plugin reference}\n')
 f.write('\input{section_bsdf}\n')
 os.path.walk('../src/bsdfs', traverse, f)
+f.write('\input{section_integrators}\n')
+os.path.walk('../src/integrators', traverse, f)
 f.close()
 os.system('bibtex main.aux')
 os.system('pdflatex main.tex')

doc/macros.sty

@@ -1,19 +1,26 @@
 % Cite a figure/listing
 \renewcommand{\lstlistingname}{Listing}
-\newcommand{\figref}[1]{\mbox{Figure \ref{fig:#1}}}
-\newcommand{\lstref}[1]{\mbox{Listing \ref{lst:#1}}}
+\newcommand{\figref}[1]{\mbox{Figure~\ref{fig:#1}}}
+\newcommand{\secref}[1]{\mbox{Section~\ref{sec:#1}}}
+\newcommand{\lstref}[1]{\mbox{Listing~\ref{lst:#1}}}
 \newcommand{\code}[1]{\texttt{#1}}
 
 % Macros that are used in the plugin documentation
 \newcommand{\plugin}[2]{\newpage\subsubsection{#2 (\texttt{#1})}\label{plg:#1}}
 \newcommand{\pluginref}[1]{\texttt{\hyperref[plg:#1]{#1}}}
 
+\newcommand{\Transform}{\texttt{transform}}
 \newcommand{\Spectrum}{\texttt{spectrum}}
+\newcommand{\Integer}{\texttt{integer}}
 \newcommand{\String}{\texttt{string}}
+\newcommand{\Boolean}{\texttt{boolean}}
 \newcommand{\Float}{\texttt{float}}
+\newcommand{\Vector}{\texttt{vector}}
+\newcommand{\Point}{\texttt{point}}
 \newcommand{\Texture}{\texttt{texture}}
 \newcommand{\Or}{~~\small or \small}
 \newcolumntype{P}[1]{>{\RaggedRight\hspace{0pt}}p{#1}}
+\newcommand{\MtsVer}{\color{lstattrib}\texttt{"\MitsubaVersion"}}
 
 \newcommand{\showbreak}{$\rhookswarrow$ }
 
@@ -48,6 +55,11 @@
 	\hfill
 }
 
+\newcommand{\smallrendering}[2]{
+	\subfigure[#1]{\fbox{\includegraphics[width=0.2\textwidth]{images/#2}}}
+	\hfill
+}
+
 \newcommand{\parameter}[3]{
 		\small\texttt{#1} & \small #2 & \small #3\\
 		\otoprule

doc/main.tex

@@ -19,6 +19,7 @@
 \usepackage{enumerate}
 \usepackage{ragged2e} % Ragged-right columns with hyphenation
 \usepackage{macros}
+\usepackage[format=hang,font=small,labelfont=bf]{caption}
 
 % Make sure that ligatures remain searchable in the PDF
 \input glyphtounicode
@@ -100,7 +101,7 @@
 	keywords= [1] {
 		shape,bsdf,scene,texture,phase,integer,float,
 		string,transform,ref,rgb,srgb,spectrum,blackbody,
-		medium,camera,film,sampler
+		medium,camera,film,sampler,integrator
 	},
 }
 

doc/section_bsdf.tex

@@ -1,21 +1,76 @@
 \subsection{Surface scattering models}
-Surface scattering models describe the manner in which light is reflected
-by surfaces in the scene, which is fundamentally related to the perceptual
-material appearance of an object. To achieve realistic results, Mitsuba 
-comes with a library of both general-purpose models (smooth or rough glass, 
-metal, plastic, etc.) and specializations to particular materials 
-(woven cloth, masks, etc.).
+\label{sec:bsdfs}
+Surface scattering models describe the manner in which light interacts
+with surfaces in the scene. They conveniently summarize the mesoscopic 
+scattering processes that take place within the material and 
+cause it to look the way it does.
+This represents one central component of the material system in Mitsuba---another 
+part of the renderer concerns itself with what happens 
+\emph{in between} surface interactions. For more information on this aspect, 
+please refer to Sections~\ref{sec:media} and \ref{sec:subsurface}.
+This section presents an overview of all surface scattering models that are 
+supported, along with their parameters.
 
-Throughout the documentation and within the scene description language, 
-the word \emph{BSDF} is used synonymously with the term ``surface
-scattering model''. This is an abbreviation for  \emph{Bidirectional 
+\subsubsection*{Correctness considerations}
+\begin{figure}[b!]
+\centering
+\vspace{-5mm}
+\includegraphics[width=15cm]{images/glass_explanation.pdf}
+\vspace{-5mm}
+\caption{
+	\label{fig:glass-explanation}
+	Some of the scattering models in Mitsuba need to know
+	the indices of refraction on the exterior and interior-facing
+	side of a surface. 
+	It is therefore important to decompose the mesh into meaningful
+	separate surfaces corresponding to each index of refraction change.
+	The example here shows such a decomposition for a water-filled Glass.
+}
+\end{figure}
+
+
+A vital consideration when modeling a scene in a physically-based rendering 
+system is that the used materials do not violate physical properties, and 
+that their arrangement is meaningful. For instance, imagine having designed
+an architectural interior scene that looks good except for a white desk that 
+seems a bit too dark. A closer inspection reveals that it uses a Lambertian 
+material with a diffuse reflectance of $0.9$. 
+
+In many rendering systems, it would be feasible to increase the 
+reflectance value above $1.0$ in such a situation. But in Mitsuba, even a 
+small surface that reflects a little more light than it receives will 
+likely break the available rendering algorithms, or cause them to produce otherwise 
+unpredictable results. In fact, we should rather change the lighting setup and
+then \emph{reduce} the material's reflectance, since it is quite unlikely that 
+we could find a real-world desk with a reflectance as high as $0.9$.
+
+As an example of the necessity for a meaningful material arrangement, consider
+the glass model illustrated in \figref{glass-explanation}. Here, careful thinking 
+is needed to decompose the object into boundaries that mark index of 
+refraction-changes. If this is done incorrectly and a beam of light can
+potentially pass through a sequence of incompatible index of refraction changes (e.g. $1.00\to 1.33$
+followed by $1.50\to1.33$), the output is undefined and will quite likely
+even contain inaccuracies in parts of the scene that are some distance
+away from the glass.
+
+\subsubsection*{BSDFs}
+To achieve realistic results, Mitsuba comes with a library of both 
+general-purpose surface scattering models (smooth or rough glass, metal,
+plastic, etc.) and specializations to particular materials (woven cloth,
+masks, etc.). Some model plugins fit neither category and could be described
+as \emph{modifiers} that are applied on top of one or more scattering models. 
+
+Throughout the documentation and within the scene description 
+language,  the word \emph{BSDF} is used synonymously with the term ``surface
+scattering model''. This is an abbreviation for \emph{Bidirectional 
 Scattering Distribution Function}, a more precise technical 
-description of the model's properties. In Mitsuba, BSDFs are 
+term. 
+
+In Mitsuba, BSDFs are 
 assigned to \emph{shapes}, which describe the visible surfaces in
 the scene. In the scene description language, this assignment can
 either be performed by nesting BSDFs within shapes, or they can 
-be named and then later referenced by their name.
-
+be named and then later referenced by their name. 
 The following fragment shows an example of both kinds of usages:
 \begin{xml}
 <scene>
@@ -26,13 +81,11 @@ The following fragment shows an example of both kinds of usages:
 
 	<shape type="sphere">
 		<!-- Example of referencing a named material -->
-
 		<ref id="myNamedMaterial"/>
 	</shape>
 
 	<shape type="sphere">
-		<!-- Example of using an unnamed material -->
-
+		<!-- Example of instantiating an unnamed material -->
 		<bsdf type=".. BSDF type ..">
 			<!-- BSDF parameters go here -->
 		</bsdf>
@@ -42,3 +95,4 @@ The following fragment shows an example of both kinds of usages:
 It is generally more economical to use named BSDFs when they
 are used in several places, since this reduces Mitsuba's internal
 memory usage.
+

doc/section_integrators.tex

@@ -0,0 +1,88 @@
+\newpage
+\subsection{Integrators}
+\label{sec:integrators}
+In Mitsuba, the different rendering techniques are collectively referred to as 
+\emph{integrators}, since they perform integration over a high-dimensional
+space. Each integrator represents a specific approach for solving
+the light transport equation---usually favored in certain scenarios, but
+at the same time affected by its own set of intrinsic limitations.
+Therefore, it is important to carefully select an integrator based on 
+user-specified accuracy requirements and properties of the scene to be 
+rendered. 
+
+In Mitsuba's XML description language, a single integrator
+is usually instantiated by declaring it at the top level within the
+scene, e.g.
+\begin{xml}
+<scene version=$\MtsVer$>
+	<!-- Instantiate a unidirectional path tracer that
+	     renders paths up to a depth of 5 -->
+	<integrator type="path">
+		<integer name="maxDepth" value="5"/>
+	</integrator>
+
+	<!-- Some geometry to be rendered -->
+	<shape type="sphere">
+		<bsdf type="lambertian"/>
+	</shape>
+</scene>
+\end{xml}
+
+This section gives a brief overview of the available choices 
+along with their parameters.
+
+\subsubsection*{Path length}
+\begin{figure}[htb!]
+\centering
+\hfill
+\smallrendering{Max. length = 1}{pathlength-1}
+\smallrendering{Max. length = 2}{pathlength-2}
+\smallrendering{Max. length = 3}{pathlength-3}
+\smallrendering{Max. length = $\infty$}{pathlength-all}
+\caption{
+	\label{fig:pathlengths}
+	These Cornell box renderings demonstrate the visual 
+	effect of a maximum path length. As the paths
+	are allowed to grow longer, the color saturation
+	increases due to multiple scattering interactions
+	with the colored surfaces. At the same time, the
+	computation time increases.
+}
+\end{figure}
+
+Almost all integrators use the concept of \emph{path length}.
+Here, a path refers to a chain of scattering events that 
+starts at the light source and ends at the eye or camera.
+It is often useful to limit the path length (\figref{pathlengths}) 
+when rendering scenes for preview purposes, since this reduces the amount 
+of computation that is necessary per pixel. Furthermore, such renderings
+usually converge faster and therefore need fewer samples per pixel.
+When reference-quality is desired, one should always leave the path 
+length unlimited.
+
+\begin{figure}[h!]
+\centering
+\vspace{-5mm}
+\includegraphics[width=10cm]{images/path_explanation.pdf}
+\vspace{-5mm}
+\caption{
+	\label{fig:path-explanation}
+	A ray of emitted light is scattered by an object and subsequently 
+	reaches the eye/camera.
+	In Mitsuba, this is a \emph{length-2} path, since it has two edges.
+}
+\end{figure}
+Mitsuba counts lengths starting at $1$, which correspond to
+visible light sources (i.e. a path that starts at the light 
+source and ends at the eye or camera without any scattering 
+interaction in between).
+A length-$2$ path (also known as ``direct illumination'') includes
+a single scattering event (\figref{path-explanation}).
+
+\subsubsection*{Progressive versus non-progressive}
+Some of the rendering techniques in Mitsuba are \emph{progressive}.
+What this means is that they display a rough preview, which
+improves over time. Leaving them running indefinitely will
+continually reduce noise (e.g. in Metropolis Light Transport)
+or both noise and bias (e.g. in Progressive Photon Mapping).
+

schema/scene.xsd

@@ -26,6 +26,7 @@
 				<xsd:element name="srgb" type="string"/>
 				<xsd:element name="blackbody" type="blackbody"/>
 			</xsd:choice>
+			<xsd:attribute name="version" type="xsd:string"/>
 		</xsd:complexType>
 	</xsd:element>
 

src/bsdfs/dielectric.cpp

@@ -28,14 +28,21 @@ MTS_NAMESPACE_BEGIN
  *     \parameter{extIOR}{\Float}{Exterior index of refraction \default{1.0}}
  *     \parameter{specular\showbreak Reflectance}{\Spectrum\Or\Texture}{Optional
  *         factor used to modulate the reflectance component\default{1.0}}
- *     \parameter{specular\showbreak Transmittance}{\Spectrum\Or\Texture}{Optional
+ *     \lastparameter{specular\showbreak Transmittance}{\Spectrum\Or\Texture}{Optional
  *         factor used to modulate the transmittance component\default{1.0}}
  * }
  *
- * Models an interface between two materials with non-matched indices of refraction.
- * The microscopic surface structure is assumed to be perfectly flat, resulting 
- * in a BSDF equal to a Dirac delta function. 
- * The default settings are set to a borosilicate glass BK7/air interface.
+ * This plugin models an interface between two materials having mismatched 
+ * indices of refraction (e.g. a boundary between water and air).
+ * The microscopic surface structure of the surface is assumed to be perfectly 
+ * smooth, resulting in a degenerate BSDF described by a Dirac delta function.
+ * For non-smooth interfaces, please take a look at the \pluginref{roughglass}
+ * model. When using this plugin, it is crucial that the scene contains
+ * meaningful and mutally compatible index of refraction change -- see
+ * \figref{glass-explanation} for an example.
+ * 
+ * The default settings of this plugin are set to a borosilicate glass BK7/air 
+ * interface.
  */
 class Dielectric : public BSDF {
 public:

src/bsdfs/roughglass.cpp

@@ -73,6 +73,10 @@ MTS_NAMESPACE_BEGIN
  * distributions and a texturable roughness. The default settings are set 
  * to a borosilicate glass BK7/air interface with a light amount of rougness 
  * modeled using a Beckmann distribution.
+ *
+ * When using this plugin, it is crucial that the scene contains
+ * meaningful and mutally compatible index of refraction change -- see
+ * \figref{glass-explanation} for an example.
  */
 class RoughGlass : public BSDF {
 public:

src/integrators/path/path.cpp

@@ -23,19 +23,26 @@ MTS_NAMESPACE_BEGIN
 
 static StatsCounter avgPathLength("Path tracer", "Average path length", EAverage);
 
- /**
-  * Extended path tracer -- uses multiple importance sampling to combine 
-  * two sampling strategies, namely BSDF and luminaire sampling. 
-  * This class does not attempt to solve the full radiative transfer 
-  * equation (see <tt>volpath</tt> if this is needed).
-  */
+/*! \plugin{path}{Path tracer with multiple importance sampling}
+ * \parameters{
+ *     \parameter{maxDepth}{\Integer}{Maximum path depth \default{-1}}
+ *     \parameter{strictNormals}{\Boolean}{Strict normals?}
+ * }
+ * Extended path tracer -- uses multiple importance sampling to combine 
+ * two sampling strategies, namely BSDF and luminaire sampling. 
+ * This class does not attempt to solve the full radiative transfer 
+ * equation (see <tt>volpath</tt> if this is needed).
+ */
 class MIPathTracer : public MonteCarloIntegrator {
 public:
-	MIPathTracer(const Properties &props) : MonteCarloIntegrator(props) { }
+	MIPathTracer(const Properties &props)
+		: MonteCarloIntegrator(props) {
+		//m_shadingSamples = props.getInteger("shadingSamples");
+	}
 
 	/// Unserialize from a binary data stream
 	MIPathTracer(Stream *stream, InstanceManager *manager)
-	 : MonteCarloIntegrator(stream, manager) { }
+		: MonteCarloIntegrator(stream, manager) { }
 
 	Spectrum Li(const RayDifferential &r, RadianceQueryRecord &rRec) const {
 		/* Some aliases and local variables */