From 6c429ac43f0eb1d984674a03d06b3e4c1c2ee12f Mon Sep 17 00:00:00 2001 From: Wenzel Jakob Date: Wed, 11 Aug 2010 03:32:46 +0200 Subject: [PATCH] more documentation, create a default luminaire if the scene description contains none --- doc/Makefile | 2 +- doc/format.tex | 122 ++++++++++++++++++++++++++++++++++++++++ doc/main.tex | 1 + doc/plugins.tex | 2 + src/librender/scene.cpp | 7 +++ 5 files changed, 133 insertions(+), 1 deletion(-) create mode 100644 doc/plugins.tex diff --git a/doc/Makefile b/doc/Makefile index 7c8430fc..719543ed 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -1,2 +1,2 @@ -main.pdf: main.tex introduction.tex compiling.tex basics.tex integrator.tex acknowledgements.tex +main.pdf: main.tex introduction.tex compiling.tex basics.tex format.tex integrator.tex acknowledgements.tex pdflatex main.tex diff --git a/doc/format.tex b/doc/format.tex index 3d2e81c1..627160de 100644 --- a/doc/format.tex +++ b/doc/format.tex @@ -1 +1,123 @@ \section{Scene file format} +Mitsuba uses a very simple and general XML-based format to represent scenes. +The framework's underlying approach is to represents discrete blocks of functionality as plugins, +hence a scene file can essentially be interpreted as description that determines which +plugins should be instantiated and how they should be interface with each other. +In the following, we'll look at a few examples to get a feeling for the scope of the +format. + +An simple scene might looks like this +\begin{xml} + + + + + + +\end{xml} +This example already contains the most important things to know about format: you can have +\emph{objects} (such as the objects instantiated by the \code{scene} or \code{shape} tags), which are allowed to be nested within +each other. Each object optionally accepts \emph{properties} (such as \code{string}), +which further characterize its behavior. All objects except for the root object (the \code{scene}) +cause the renderer to load and instantiate a plugin, hence you must provide the plugin name using +\code{type=".."} parameter. + +The tags let the renderer know what kind of object is to be instantiated: for instance \code{obj} is a +WaveFront OBJ loader, which conforms to the \emph{Shape} interface. Similarly, +you could write +\begin{xml} + + + + + + +\end{xml} +This loads a different plugin (\code{sphere}) which is still a \emph{Shape}, but instead represents +a sphere configured with a radius of 10 world-space units. Mitsuba ships with +a large number of plugins; please refer to the next chapter for a reference. + +The most common scene setup is to declare an integrator, some geometry, a camera, a film, a sampler +and one or more luminaires. Here is a more complex example: +\begin{xml} + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +\end{xml} +This example introduces several new object types (\code{integrator, camera, sampler, film, bsdf}, and \code{luminaire}) +and a few property types (\code{integer}, \code{transform}, and \code{rgb}). +Objects are usually declared at the top level except if there is some +inherent relation that links them to another object. For example, BSDFs are usually specific to a certain geometric object, so +they appear as a child object of a shape. Similarly, the sampler and film both affect the way in which +rays are generated from the camera, hence they are nested inside it. + +Note that you should always put properties before nested child objects, otherwise you'll see something like the following slightly cryptic + XML validation error. For instance, +\begin{xml} +... + + + + +... +\end{xml} +produces +\begin{shell} +Caught a critical exeption: 2010-08-11 03:23:31 ERROR main [src/mitsuba/shandler.cpp:359] Error in file "/home/wenzel/mitsuba/test.xml" (line 63): Element 'string' is not valid $\texttt{for}$ content model: '(((integer|float|point|vector|boolean|transform|string|spectrum|rgb)|blackbody),((bsdf|subsurface|ref)|luminaire))' +\end{shell} +\subsection{Property types} +\subsubsection{Numbers} +\subsubsection{Spectra} +\subsubsection{Transformations} +\subsubsection{Vectors, Positions} +\subsubsection{Strings} +\subsection{Instancing materials} +\subsection{Including external files} diff --git a/doc/main.tex b/doc/main.tex index 0f7fbac7..55a829d8 100644 --- a/doc/main.tex +++ b/doc/main.tex @@ -110,6 +110,7 @@ \include{compiling} \include{basics} \include{format} +\include{plugins} \include{integrator} \include{parallelization} \include{acknowledgements} diff --git a/doc/plugins.tex b/doc/plugins.tex new file mode 100644 index 00000000..bfb266de --- /dev/null +++ b/doc/plugins.tex @@ -0,0 +1,2 @@ +\section{Plugin reference} +TBD diff --git a/src/librender/scene.cpp b/src/librender/scene.cpp index d2f1e135..54cdbc38 100644 --- a/src/librender/scene.cpp +++ b/src/librender/scene.cpp @@ -183,6 +183,8 @@ void Scene::configure() { m_integrator->configure(); } if (m_camera == NULL) { + Log(EWarn, "No camera found -- adding a default camera"); + Properties props("perspective"); /* Create a perspective camera with 45deg. FOV, which can see the whole scene */ AABB aabb; @@ -200,6 +202,11 @@ void Scene::configure() { m_camera->configure(); m_sampler = m_camera->getSamplerX(); } + + if (m_luminaires.size() == 0) { + Log(EWarn, "No luminaires found -- adding a constant environment source"); + addChild("", PluginManager::getInstance()->createObject(Luminaire::m_theClass, Properties("constant"))); + } if (m_media.size() > 1) Log(EError, "Scenes are currently restricted to at most one participating medium.");