From 7f8e92becdd31ac4904d166c01fe442f64e7643d Mon Sep 17 00:00:00 2001 From: Wenzel Jakob Date: Sun, 26 Jun 2011 03:29:50 +0200 Subject: [PATCH] further work on the documentation --- doc/Makefile | 4 +-- doc/macros.sty | 58 ++++++++++++++++++++++++++++++++++++++++ doc/main.tex | 24 ++++++++--------- doc/section_bsdf.tex | 28 +++++++++---------- src/bsdfs/lambertian.cpp | 41 +++++++++++++++------------- src/bsdfs/roughglass.cpp | 26 ++++++++++++++++-- 6 files changed, 131 insertions(+), 50 deletions(-) create mode 100644 doc/macros.sty diff --git a/doc/Makefile b/doc/Makefile index b13efbde..c64ad654 100644 --- 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 diff --git a/doc/macros.sty b/doc/macros.sty new file mode 100644 index 00000000..d20fea4c --- /dev/null +++ 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\\ + } diff --git a/doc/main.tex b/doc/main.tex index 9cd28251..55cc85c9 100644 --- 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}} diff --git a/doc/section_bsdf.tex b/doc/section_bsdf.tex index 5484741d..5aa8108d 100644 --- 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} diff --git a/src/bsdfs/lambertian.cpp b/src/bsdfs/lambertian.cpp index e32703ca..f377738e 100644 --- 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] * - * + * * * \end{xml} * * \begin{xml}[caption=Lambertian material with a texture map, label=lst:lambertian-textured] * - * - * - * + * + * + * * * \end{xml} */ diff --git a/src/bsdfs/roughglass.cpp b/src/bsdfs/roughglass.cpp index 3bf70684..0c162106 100644 --- 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)