further work on the documentation

doc/Makefile

@@ -1,2 +1,2 @@
-main.pdf: main.tex introduction.tex compiling.tex basics.tex format.tex import.tex integrator.tex parallelization.tex acknowledgements.tex
+all: 
-	pdflatex main.tex
+	./gendoc.py

doc/macros.sty

@@ -0,0 +1,58 @@
+% Cite a figure/listing
+\renewcommand{\lstlistingname}{Listing}
+\newcommand{\figref}[1]{\mbox{Figure \ref{fig:#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]{\subsubsection{#2 (\texttt{#1})}\label{plg:#1}}
+\newcommand{\pluginref}[1]{\texttt{\hyperref[plg:#1]{#1}}}
+
+\newcommand{\Spectrum}{\texttt{spectrum}}
+\newcommand{\String}{\texttt{string}}
+\newcommand{\Float}{\texttt{float}}
+\newcommand{\Texture}{\texttt{texture}}
+\newcommand{\Or}{~~\small or \footnotesize}
+\newcolumntype{P}[1]{>{\RaggedRight\hspace{0pt}}p{#1}}
+
+\newcommand{\showbreak}{$\rhookswarrow$ }
+
+\newcommand{\otoprule}{\midrule[.8pt]}
+\newlength\fboxrulebackup
+\newcommand{\parameters}[1]{
+	\setlength\fboxrulebackup\fboxrule
+	\setlength\fboxrule{0.8pt}
+	\begin{figure}[h]\centering\arrayrulecolor{lstframe}
+	\fcolorbox{lstframe}{lstshade}{\begin{tabular}{@{\hspace{3mm}}P{3cm}P{2.2cm}p{8.3cm}@{\hspace{3mm}}}
+ 		%\toprule
+		\\[-2.2ex]
+		\textbf{Parameter}&\textbf{Type}&\textbf{Description}\\
+		\otoprule
+		#1
+		%\bottomrule
+	\end{tabular}}
+	\end{figure}
+	\setlength\fboxrule\fboxrulebackup
+	}
+	
+\newcommand{\renderings}[1]{
+	\begin{figure}[h]
+		\centering
+		\hfill
+		#1
+	\end{figure}
+}
+
+\newcommand{\rendering}[2]{
+	\subfigure[#1]{\fbox{\includegraphics[width=0.4\textwidth]{images/#2}}}
+	\hfill
+}
+
+\newcommand{\parameter}[3]{
+		\small\texttt{#1} & \small #2 & \small #3\\
+		\otoprule
+	}
+
+\newcommand{\lastparameter}[3]{
+		\small\texttt{#1} & \small #2 & \small #3\\
+	}

doc/main.tex

@@ -7,12 +7,17 @@
 \usepackage[T1]{fontenc}
 \usepackage[utf8]{inputenc}
 \usepackage{graphicx}
+\usepackage{amsmath}
 \usepackage{array}
 \usepackage{booktabs}
+\usepackage{tabularx}
 \usepackage{color}
+\usepackage{colortbl}
 \usepackage{listings}
-\usepackage{amsmath}
+\usepackage{subfigure}
 \usepackage{enumerate}
+\usepackage{ragged2e} % Ragged-right columns with hyphenation
+\usepackage{macros}
 
 % Make sure that ligatures remain searchable in the PDF
 \input glyphtounicode
@@ -60,21 +65,11 @@
 
 \definecolor{myblue}{rgb}{0,.1,.6}
 \definecolor{myred}{rgb}{0.63,.16,.16}
-\definecolor{lstshade}{gray}{0.94}
+\definecolor{lstshade}{gray}{0.95}
-\definecolor{lstframe}{gray}{0.75}
+\definecolor{lstframe}{gray}{0.80}
 \definecolor{lstcomment}{gray}{0.5}
 \definecolor{lstattrib}{rgb}{0,0.34,0}
 
-% Cite a figure/listing
-\renewcommand{\lstlistingname}{Listing}
-\newcommand{\figref}[1]{\mbox{Figure \ref{fig:#1}}}
-\newcommand{\lstref}[1]{\mbox{Listing \ref{lst:#1}}}
-\newcommand{\code}[1]{\texttt{#1}}
-
-% Macros for plugin documentation
-\newcommand{\plugin}[2]{\subsubsection{#2 (\texttt{#1})}\label{plg:#1}}
-\newcommand{\pluginref}[1]{\texttt{\hyperref[plg:#1]{#1}}}
-
 
 % Listings settings
 \lstset{
@@ -112,6 +107,9 @@
 \setlength\fboxsep{0pt}
 \setlength\fboxrule{1.5pt}
 
+% Less vertical spacing for \figure[h] floats
+\setlength{\intextsep}{3pt}
+
 \lstnewenvironment{cpp}[1][]{\lstset{language=c++, #1}}
 	{}
 \lstnewenvironment{xml}[1][]{\lstset{language=xml, #1}}

doc/section_bsdf.tex

@@ -1,22 +1,20 @@
 \subsection{Surface scattering models}
-Surface scattering models describe the way in which light reflects
+Surface scattering models describe the manner in which light is reflected
-from surfaces in the scene. Even slight adjustments to such a description
+by surfaces in the scene, which is fundamentally related to the perceptual
-can significantly change the appearance of a rendering.
+material appearance of an object. To achieve realistic results, Mitsuba 
-To achieve realistic results, Mitsuba comes with a library of 
+comes with a library of both general-purpose models (smooth or rough glass, 
-both general-purpose models (smooth or rough glass, metal, plastic, ..) and 
+metal, plastic, etc.) and specializations to particular materials 
-more specialized models (woven cloth, masks, ..).
+(woven cloth, masks, etc.).
 
 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 
+scattering model''. This is an abbreviation for  \emph{Bidirectional 
-\emph{Bidirectional Scattering Distribution Function}, a more 
+Scattering Distribution Function}, a more precise technical 
-precise technical description of the model's properties.
+description of the model's properties. In Mitsuba, BSDFs are 
-In Mitsuba, BSDFs are assigned to \emph{shapes}, which
+assigned to \emph{shapes}, which describe the visible surfaces in
-describe the visible surfaces in the scene. In the scene 
+the scene. In the scene description language, this assignment can
-description language, this assignment must
+either be performed by nesting BSDFs within shapes, or they can 
-either be performed by nesting BSDFs within shapes, 
+be named and then later referenced by their name.
-or they can be named and then later referenced 
-by by name.
 
 The following fragment shows an example of both kinds of usages:
 \begin{xml}

src/bsdfs/lambertian.cpp

@@ -23,22 +23,27 @@
 
 MTS_NAMESPACE_BEGIN
 
-/*! \plugin{lambertian}{Ideally diffuse / Lambertian material}
+/*! \newpage\plugin{lambertian}{Ideally diffuse / Lambertian material}
  *
- * \begin{center}
+ * \parameters{
- * \begin{tabular}{c@{\hspace{1cm}}c}
+ *     \lastparameter{reflectance}{\Spectrum\Or\Texture}{
- * \fbox{\includegraphics[width=6cm]{images/bsdf_lambertian_plain.jpg}}&
+ *       Specifies the diffuse reflectance / albedo of the material \linebreak(Default: 0.5)
- * \fbox{\includegraphics[width=6cm]{images/bsdf_lambertian_textured.jpg}}\\
+ *     }
- * Homogeneous reflectance, see \lstref{lambertian-uniform}&
+ * }
- * Textured reflectance, see \lstref{lambertian-textured}
+ *
- * \end{tabular}
+ * \renderings{
- * \end{center}
+ *     \rendering{Homogeneous reflectance, see \lstref{lambertian-uniform}}{bsdf_lambertian_plain}
+ *     \rendering{Textured reflectance, see \lstref{lambertian-textured}}{bsdf_lambertian_textured}
+ * }
  *
  * The Lambertian material represents an ideally diffuse material
- * with the specified amount of reflectance. When nothing is specified,
+ * with a user-specified amount of reflectance. Apart from a 
- * the default of 50% reflectance is used.
+ * homogeneous reflectance value, the plugin can also accept a nested 
- *
+ * or referenced texture map to be used as the source of reflectance 
- * Optionally, a texture map may be applied. 
+ * information, which is then mapped onto the shape based on its UV
+ * parameterization.
+ * When no parameters are specified, the model uses the default 
+ * of 50% reflectance.
  *
  * Note that this material is one-sided---that is, observed from the 
  * back side, it will be completely black. If this is undesirable, 

src/bsdfs/roughglass.cpp

@@ -21,12 +21,34 @@
 
 MTS_NAMESPACE_BEGIN
 
-/**
+/*! \newpage\plugin{roughglass}{Rough dielectric/glass material}
+ * \parameters{
+ *     \parameter{alpha}{\Float}{Roughness value (Default: 0.1)}
+ *     \parameter{intIOR}{\Float}{Interior index of refraction (Default: 1.5046)}
+ *     \parameter{extIOR}{\Float}{Exterior index of refraction (Default: 1)}
+ *     \parameter{specular\showbreak Reflectance}{\Spectrum}{Modulation)}
+ *     \parameter{specular\showbreak Transmittance}{\Spectrum}{Modulation)}
+ *     \lastparameter{distribution}{\String}{
+ *       Specifies the microfacet distribution
+ *       \begin{enumerate}[(i)]
+ *           \item \code{beckmann}: Beckmann distribution derived from
+ *               Gaussian random surfaces.
+ *           \item \code{phong}: Phong distribution
+ *           \item \code{ggx}: New distribution proposed by
+ *               Walter et al., meant to better handle the long
+ *               tails observed in measurements of rough glass.
+ *       \end{enumerate}
+ *     }
+ * }
+ *
  * Rough glass BSDF model based on
  * "Microfacet Models for Refraction through Rough Surfaces"
  * by Bruce Walter, Stephen R. Marschner, Hongsong Li
  * and Kenneth E. Torrance
+ * The default settings are set to a borosilicate glass BK7/air interface.
  */
+
+
 class RoughGlass : public BSDF {
 public:
 	//// Microfacet distribution types supported by the model
@@ -52,7 +74,7 @@ public:
 			m_alpha = props.getFloat("alpha", .1f);
 		}
 
-		m_intIOR = props.getFloat("intIOR", 1.5);
+		m_intIOR = props.getFloat("intIOR", 1.5046f);
 		m_extIOR = props.getFloat("extIOR", 1.0f);
 
 		if (m_intIOR == m_extIOR)