further work on the documentation

2011-06-26 03:29:50 +02:00 · 2011-06-26 03:29:50 +02:00 · 7f8e92becd
parent 83ebeb7edf
commit 7f8e92becd
6 changed files with 131 additions and 50 deletions
--- a/doc/Makefile
+++ b/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
-	pdflatex main.tex
+all: 
+	./gendoc.py
--- a/doc/macros.sty
+++ b/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\\
+	}
--- a/doc/main.tex
+++ b/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{lstframe}{gray}{0.75}
+\definecolor{lstshade}{gray}{0.95}
+\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}}
--- a/doc/section_bsdf.tex
+++ b/doc/section_bsdf.tex
@ -1,22 +1,20 @@
 \subsection{Surface scattering models}
-Surface scattering models describe the way in which light reflects
-from surfaces in the scene. Even slight adjustments to such a description
-can significantly change the appearance of a rendering.
-To achieve realistic results, Mitsuba comes with a library of 
-both general-purpose models (smooth or rough glass, metal, plastic, ..) and 
-more specialized models (woven cloth, masks, ..).
+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.).

 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 assigned to \emph{shapes}, which
-describe the visible surfaces in the scene. In the scene 
-description language, this assignment must
-either be performed by nesting BSDFs within shapes, 
-or they can be named and then later referenced 
-by by name.
+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 
+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.

 The following fragment shows an example of both kinds of usages:
 \begin{xml}
--- a/src/bsdfs/lambertian.cpp
+++ b/src/bsdfs/lambertian.cpp
@ -23,38 +23,43 @@

 MTS_NAMESPACE_BEGIN

-/*! \plugin{lambertian}{Ideally diffuse / Lambertian material}
+/*! \newpage\plugin{lambertian}{Ideally diffuse / Lambertian material}
 *
- * \begin{center}
- * \begin{tabular}{c@{\hspace{1cm}}c}
- * \fbox{\includegraphics[width=6cm]{images/bsdf_lambertian_plain.jpg}}&
- * \fbox{\includegraphics[width=6cm]{images/bsdf_lambertian_textured.jpg}}\\
- * Homogeneous reflectance, see \lstref{lambertian-uniform}&
- * Textured reflectance, see \lstref{lambertian-textured}
- * \end{tabular}
- * \end{center}
+ * \parameters{
+ *     \lastparameter{reflectance}{\Spectrum\Or\Texture}{
+ *       Specifies the diffuse reflectance / albedo of the material \linebreak(Default: 0.5)
+ *     }
+ * }
+ *
+ * \renderings{
+ *     \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,
- * the default of 50% reflectance is used.
+ * with a user-specified amount of reflectance. Apart from a 
+ * homogeneous reflectance value, the plugin can also accept a nested 
+ * or referenced texture map to be used as the source of reflectance 
+ * 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.
 *
- * Optionally, a texture map may be applied. 
- *
- * Note that this material is one-sided --- that is, observed from the 
+ * Note that this material is one-sided---that is, observed from the 
 * back side, it will be completely black. If this is undesirable, 
 * consider using the \pluginref{twosided} BRDF adapter plugin.
 *
 * \begin{xml}[caption=Reflectance specified as an sRGB color, label=lst:lambertian-uniform]
 * <bsdf type="lambertian">
- *   <srgb name="reflectance" value="#6d7185"/>
+ *     <srgb name="reflectance" value="#6d7185"/>
 * </bsdf>
 * \end{xml}
 *
 * \begin{xml}[caption=Lambertian material with a texture map, label=lst:lambertian-textured]
 * <bsdf type="lambertian">
- *   <texture type="ldrtexture" name="reflectance">
- *     <string name="filename" value="wood.jpg"/>
- *   </texture>
+ *     <texture type="ldrtexture" name="reflectance">
+ *       <string name="filename" value="wood.jpg"/>
+ *     </texture>
 * </bsdf>
 * \end{xml}
 */
--- a/src/bsdfs/roughglass.cpp
+++ b/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)