documentation updates

doc/compiling.tex

@@ -142,7 +142,7 @@ repository, put the two \code{deb}-files built in the last section,
 as well as the \code{collada-dom} \code{deb}-files into a public directory 
 made available by a HTTP server and inside it, run
 \begin{shell}
-$path-to-htdocs\text{\$}$ dpkg-scanpackages path/to/deb-directory /dev/null | gzip -9c > path/to/deb-directory/Packages.gz
+path-to-htdocs$\text{\$}$ dpkg-scanpackages path/to/deb-directory /dev/null | gzip -9c > path/to/deb-directory/Packages.gz
 \end{shell}
 This will create a respository index file named \code{Packages.gz}.
 Note that you must execute this command in the root directory of the

doc/gendoc.py

@@ -87,4 +87,4 @@ f.write('\input{section_films}\n')
 walk('../src/films', traverse, f)
 f.close()
 os.system('bibtex main.aux')
-os.system('pdflatex main.tex')
+os.system('pdflatex main.tex | grep -i warning')

doc/introduction.tex

@@ -24,7 +24,7 @@ foundation for research in this domain.
 Other design considerations are are:
 
 \parheader{Performance:}
-One important goal of Mitsuba is to provide optimized implementations of the most commonly 
+Mitsuba provides optimized implementations of the most commonly 
 used rendering algorithms. By virtue of running on a shared foundation, comparisons between them can
 better highlight the merits and limitations of different approaches. This is in contrast to, say, 
 comparing two completely different rendering products, where technical information on the underlying 
@@ -70,4 +70,9 @@ settings. Experimental integration into Blender 2.5 is also available.
 Mitsuba is free software and can be redistributed and modified under the terms of the GNU General 
 Public License (Version 3) as provided by the Free Software Foundation.
 
-
+\remarks{
+	\item Being a ``viral'' license, the GPL is automatically enforced on
+	derivative work. Amongst other things, this means that without express
+	permission, Mitsuba's source code is \emph{absolutely off-limits} to companies that
+	develop rendering software not distributed under a compatible license.
+}

doc/main.bib

@@ -185,10 +185,10 @@
 	year={1941}
 }
 
-@inproceedings{Kajiya1989Rendering,
+@article{Kajiya1989Rendering,
 	title={Rendering fur with three dimensional textures},
 	author={Kajiya, J.T. and Kay, T.L.},
-	booktitle={ACM Siggraph Computer Graphics},
+	journal={ACM Transactions on Graphics},
 	volume={23},
 	number={3},
 	pages={271--280},

src/bsdfs/roughplastic.cpp

@@ -125,7 +125,6 @@ MTS_NAMESPACE_BEGIN
  *     \medrendering{Textured rough plastic model and \code{nonlinear=false}}{bsdf_roughplastic_preserve}
  *     \medrendering{Textured rough plastic model and \code{nonlinear=true}}{bsdf_roughplastic_nopreserve}
  *     \caption{
- *        \label{fig:plastic-nonlinear}
  *        When asked to do so, this model can account for subtle nonlinear color shifts due
  *        to internal scattering processes. The above images show a textured
  *        object first rendered using \pluginref{diffuse}, then 

src/shapes/hair.cpp

@@ -47,7 +47,7 @@ MTS_NAMESPACE_BEGIN
  *     \parameter{toWorld}{\Transform}{
  *	      Specifies an optional linear object-to-world transformation.
  *        Note that non-uniform scales are not permitted!
- *        \default{none (i.e. object space $=$ world space)}
+ *        \default{none, i.e. object space $=$ world space}
  *     }
  * }
  * \renderings{

src/shapes/shapegroup.cpp

@@ -34,7 +34,15 @@ MTS_NAMESPACE_BEGIN
  * so that they can efficiently be referenced many times using the 
  * \pluginref{instance} plugin. This is useful for rendering things like 
  * forests, where only a few distinct types of trees have to be kept
- * in memory.
+ * in memory. 
+ *
+ * \remarks{
+ *   \item Note that it is currently not possible to assign a different
+ *    material to each instance --- the material assignment specified within
+ *    the shape group is the one that matters.
+ *   \item Shape groups can currently not be used to replicate shapes with
+ *   attached emitters, sensors, or subsurface integrators.
+ * }
  *
  * \begin{xml}[caption={An example of geometry instancing}, label=lst:instancing]
  * <!-- Declare a named shape group containing two objects -->
@@ -43,7 +51,6 @@ MTS_NAMESPACE_BEGIN
  *         <string name="filename" value="data.ply"/>
  *         <bsdf type="roughconductor"/>
  *     </shape>
- *
  *     <shape type="sphere">
  *         <transform name="toWorld">
  *             <scale value="5"/>
@@ -53,17 +60,14 @@ MTS_NAMESPACE_BEGIN
  *     </shape>
  * </shape>
  *
- * <!-- Instantiate the shape group without
+ * <!-- Instantiate the shape group without any kind of transformation -->
- *      any kind of transformation -->
  * <shape type="instance">
  *     <ref id="myShapeGroup"/>
  * </shape>
  *
- * <!-- Instantiate another version of the shape
+ * <!-- Create instance of the shape group, but rotated, scaled, and translated -->
- *      group, but rotated, scaled, and translated -->
  * <shape type="instance">
  *     <ref id="myShapeGroup"/>
- *
  *     <transform name="toWorld">
  *         <rotate x="1" angle="45"/>
  *         <scale value="1.5"/>

src/textures/checkerboard.cpp

@@ -36,7 +36,11 @@ MTS_NAMESPACE_BEGIN
  *       Numerical offset that should be applied to UV values before a lookup
  *     }
  * }
- * This plugin implements a simple procedural checkerboard texture.
+ * \renderings{
+ *     \rendering{Checkerboard applied to the material test object}{tex_checkerboard}
+ * }
+ * This plugin implements a simple procedural checkerboard texture with
+ * customizable colors.
  */
 class Checkerboard : public Texture2D {
 public:

src/textures/gridtexture.cpp

@@ -43,7 +43,11 @@ MTS_NAMESPACE_BEGIN
  *       Numerical offset that should be applied to UV values before a lookup
  *     }
  * }
- * This plugin implements a simple procedural grid texture.
+ * \renderings{
+ *     \rendering{Grid texture applied to the material test object}{tex_gridtexture}
+ * }
+ * This plugin implements a simple procedural grid texture with customizable
+ * colors and line width.
  */
 class GridTexture : public Texture2D {
 public:

src/textures/scale.cpp

@@ -22,11 +22,32 @@
 
 MTS_NAMESPACE_BEGIN
 
-/**
+/*!\plugin{scale}{Scaling passthrough texture}
- * \brief Scaling passthrough texture
+ * \parameters{
+ *     \parameter{value}{\Spectrum\Or\Texture}{
+ *       Specifies the spectrum or nested texture that should be scaled
+ *     }
+ *     \parameter{value}{\Float}{
+ *       Specifies the scale value
+ *     }
+ * }
  *
- * Includes a \ref Shader implementation for hardware rendering
+ * This simple plugin wraps a nested texture plugin and multiplies its 
+ * contents by a user-specified value. This can be quite useful when a
+ * texture is too dark or too bright. The plugin can also be used to adjust
+ * the height of a bump map when using the \pluginref{bump} plugin.
+ * \begin{xml}[caption=Scaling the contents of a bitmap texture]
+ * <texture type="scale">
+ *     <float name="scale" value="0.5"/>
+ *
+ *     <texture type="bitmap">
+ *         <string name="filename" value="wood.jpg"/>
+ *     </texture>
+ * </texture>
+ * \end{xml}
+
  */
+
 class ScalingTexture : public Texture {
 public:
 	ScalingTexture(const Properties &props) : Texture(props) {

src/textures/wireframe.cpp

@@ -44,6 +44,9 @@ MTS_NAMESPACE_BEGIN
  *        \default{0.5}
  *     }
  * }
+ * \renderings{
+ *     \rendering{Wireframe texture applied to the material test object}{tex_wireframe}
+ * }
  *
  * This plugin implements a simple two-color wireframe texture map 
  * that reveals the structure of a triangular mesh.