From e86dbea5d552c899567a5708ff316b446f627a23 Mon Sep 17 00:00:00 2001 From: Wenzel Jakob Date: Wed, 17 Aug 2011 15:02:24 -0400 Subject: [PATCH] documentation updates --- include/mitsuba/core/aabb_sse.h | 5 +- include/mitsuba/core/appender.h | 1 + include/mitsuba/core/bitmap.h | 1 + include/mitsuba/core/chisquare.h | 9 +- include/mitsuba/core/class.h | 2 +- include/mitsuba/core/grid.h | 338 --------------------------- include/mitsuba/core/logger.h | 1 + include/mitsuba/core/lrucache.h | 3 +- include/mitsuba/core/mmap.h | 1 - include/mitsuba/core/object.h | 1 + include/mitsuba/core/plugin.h | 2 + include/mitsuba/core/properties.h | 15 +- include/mitsuba/core/quad.h | 1 - include/mitsuba/core/random.h | 1 + include/mitsuba/core/ray.h | 1 + include/mitsuba/core/sched.h | 7 + include/mitsuba/core/sched_remote.h | 1 + include/mitsuba/core/serialization.h | 2 + include/mitsuba/core/shvector.h | 8 +- include/mitsuba/core/spectrum.h | 3 + include/mitsuba/core/spline.h | 2 + include/mitsuba/core/sshstream.h | 2 + include/mitsuba/core/transform.h | 1 + include/mitsuba/core/version.h | 17 +- 24 files changed, 68 insertions(+), 357 deletions(-) delete mode 100644 include/mitsuba/core/grid.h diff --git a/include/mitsuba/core/aabb_sse.h b/include/mitsuba/core/aabb_sse.h index b0fd1cd8..e04c711e 100644 --- a/include/mitsuba/core/aabb_sse.h +++ b/include/mitsuba/core/aabb_sse.h @@ -22,8 +22,9 @@ MTS_NAMESPACE_BEGIN /** - * NaN-aware slab test using SSE by Thierry Berger-Perrin (Intersects against - * 4 rays simultaneously). Returns false if none of the rays intersect. + * NaN-aware slab test using SSE by Thierry Berger-Perrin (Intersects + * against 4 rays simultaneously). Returns false if none of the rays + * intersect. */ FINLINE bool AABB::rayIntersectPacket(const RayPacket4 &ray, RayInterval4 &interval) const { diff --git a/include/mitsuba/core/appender.h b/include/mitsuba/core/appender.h index f4e7b2c8..b3ee5373 100644 --- a/include/mitsuba/core/appender.h +++ b/include/mitsuba/core/appender.h @@ -27,6 +27,7 @@ MTS_NAMESPACE_BEGIN * for logging-relevant information * * \ingroup libcore + * \ingroup libpython */ class MTS_EXPORT_CORE Appender : public Object { public: diff --git a/include/mitsuba/core/bitmap.h b/include/mitsuba/core/bitmap.h index a48a9e5b..7c4ffa7d 100644 --- a/include/mitsuba/core/bitmap.h +++ b/include/mitsuba/core/bitmap.h @@ -31,6 +31,7 @@ MTS_NAMESPACE_BEGIN * This class can efficiently handle 1-bit masks * * \ingroup libcore + * \ingroup libpython */ class MTS_EXPORT_CORE Bitmap : public Object { public: diff --git a/include/mitsuba/core/chisquare.h b/include/mitsuba/core/chisquare.h index f2e0cdd5..6ec31e6a 100644 --- a/include/mitsuba/core/chisquare.h +++ b/include/mitsuba/core/chisquare.h @@ -46,7 +46,7 @@ MTS_NAMESPACE_BEGIN * * Given a probability distribution with the following interface * - * + * \code * class MyDistribution { * // Sample a (optionally weighted) direction. A non-unity weight * // in the return value is needed when the sampling distribution @@ -56,11 +56,11 @@ MTS_NAMESPACE_BEGIN * /// Compute the probability density for the specified direction and measure * Float pdf(const Vector &direction, EMeasure) const; * }; - * + * \endcode * * the code in this class might be used as follows * - * + * \code * MyDistribution myDistrInstance; * ChiSquare chiSqr; * @@ -75,7 +75,8 @@ MTS_NAMESPACE_BEGIN * * if (!chiSqr.runTest()) * Log(EError, "Uh oh -- test failed, the implementation is probably incorrect!"); - * + * \endcode + * \ingroup libcore */ class MTS_EXPORT_CORE ChiSquare : public Object { public: diff --git a/include/mitsuba/core/class.h b/include/mitsuba/core/class.h index db38e67d..aab33c11 100644 --- a/include/mitsuba/core/class.h +++ b/include/mitsuba/core/class.h @@ -24,6 +24,7 @@ MTS_NAMESPACE_BEGIN /** * \headerfile mitsuba/core/class.h mitsuba/mitsuba.h * \brief Stores meta-information about \ref Object instances. + * \ingroup libcore * * This class provides a thin layer of RTTI (run-time type information), * which is useful for doing things like: @@ -36,7 +37,6 @@ MTS_NAMESPACE_BEGIN * * * \sa ref, Object - * \ingroup libcore */ class MTS_EXPORT_CORE Class { public: diff --git a/include/mitsuba/core/grid.h b/include/mitsuba/core/grid.h deleted file mode 100644 index 4da9a665..00000000 --- a/include/mitsuba/core/grid.h +++ /dev/null @@ -1,338 +0,0 @@ -/* - This file is part of Mitsuba, a physically based rendering system. - - Copyright (c) 2007-2011 by Wenzel Jakob and others. - - Mitsuba is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License Version 3 - as published by the Free Software Foundation. - - Mitsuba is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program. If not, see . -*/ - -#if !defined(__GRID_H) -#define __GRID_H - -#include - -MTS_NAMESPACE_BEGIN - -/** - * \brief Uniform 3D grid for storing and manipulating arbitrary quantities - * - * \ingroup libcore - */ -template class Grid { -public: - /// Construct a new grid with the given resolution (initialized to zero) - Grid(const Vector3i &res, const AABB &aabb) : m_res(res), m_aabb(aabb) { - m_slab = res.x*res.y; - m_numCells = m_slab*res.z; - m_cells = new ValueType[m_numCells]; - for (int i=0; i<3; ++i) - m_cellWidth[i] = m_aabb.getExtents()[i] / (Float) res[i]; - clear(); - } - - /// Unserialize a grid from a binary data stream - Grid(Stream *stream) { - m_res = Vector3i(stream); - m_aabb = AABB(stream); - m_slab = m_res.x*m_res.y; - m_numCells = m_slab*m_res.z; - m_cells = new ValueType[m_numCells]; - stream->read(m_cells, sizeof(ValueType)*m_numCells); - for (int i=0; i<3; ++i) - m_cellWidth[i] = m_aabb.getExtents()[i] / (Float) m_res[i]; - } - - /// Serialize a grid to a binary data stream - inline void serialize(Stream *stream) const { - m_res.serialize(stream); - m_aabb.serialize(stream); - for (int i=0; i<3; ++i) - stream->writeSingle((float) m_aabb.min[i]); - for (int i=0; i<3; ++i) - stream->writeSingle((float) m_aabb.max[i]); - stream->write(m_cells, sizeof(ValueType)*m_numCells); - } - - /// Reset everything to zero - inline void clear() { - memset(m_cells, 0, sizeof(ValueType) * m_numCells); - } - - /// Add the values from another grid of identical shape and type - inline void operator+=(const Grid &grid) { - SAssert(grid.m_numCells == m_numCells); - for (size_t i=0; i void apply(const Point &p, const Functor &functor) { - /* Intersect with the voxel grid */ - if (!m_aabb.contains(p)) { - std::ostringstream oss; - oss << "The grid " << m_aabb.toString() << " does not contain the " - "position " << p.toString() << "!" << endl; - throw std::runtime_error(oss.str()); - } - Vector pos = p - m_aabb.min; - Vector3i dpos( - std::max(0, std::min((int) (pos.x / m_cellWidth.x), m_res.x-1)), - std::max(0, std::min((int) (pos.y / m_cellWidth.y), m_res.y-1)), - std::max(0, std::min((int) (pos.z / m_cellWidth.z), m_res.z-1)) - ); - int index = dpos.x + dpos.y * m_res.x + dpos.z * m_slab; - m_cells[index] = functor(m_cells[index]); - } - - /** - * Apply the given functor to a grid cell - don't throw an error if - * the point is not part of the grid. Returns 'true' upon success - */ - template bool applyIfContained(const Point &p, const Functor &functor) { - if (!m_aabb.contains(p)) - return false; - - Vector pos = p - m_aabb.min; - Vector3i dpos( - std::max(0, std::min((int) (pos.x / m_cellWidth.x), m_res.x-1)), - std::max(0, std::min((int) (pos.y / m_cellWidth.y), m_res.y-1)), - std::max(0, std::min((int) (pos.z / m_cellWidth.z), m_res.z-1)) - ); - int index = dpos.x + dpos.y * m_res.x + dpos.z * m_slab; - m_cells[index] = functor(m_cells[index]); - return true; - } - - /** - * \brief Rasterize a ray to the grid and apply the functor to - * every traversed cell - */ - template void rasterize(const Ray &ray, Functor &functor) { - Float mint, maxt, t; - - /* Intersect with the voxel grid */ - if (!m_aabb.rayIntersect(ray, mint, maxt)) - return; - - /* Find the covered range in the ray space */ - mint = std::max(mint, ray.mint); maxt = std::max(mint, std::min(maxt, ray.maxt)); - if (mint == maxt) - return; - - /* Compute the discrete coordinates of the first intersected voxel */ - Vector pos = ray(mint) - m_aabb.min; - Vector3i dpos( - std::max(0, std::min((int) (pos.x / m_cellWidth.x), m_res.x-1)), - std::max(0, std::min((int) (pos.y / m_cellWidth.y), m_res.y-1)), - std::max(0, std::min((int) (pos.z / m_cellWidth.z), m_res.z-1)) - ); - t = mint; - - /* Precompute useful traversal information */ - Vector corner1 = Vector(dpos.x * m_cellWidth.x, - dpos.y * m_cellWidth.y, dpos.z * m_cellWidth.z); - Vector corner2 = Vector((dpos.x+1) * m_cellWidth.x, - (dpos.y+1) * m_cellWidth.y, (dpos.z+1) * m_cellWidth.z); - Vector delta, next; - Vector3i step, bounds; - for (int i=0; i<3; ++i) { - if (std::abs(ray.d[i]) < Epsilon) { - delta[i] = 0; step[i] = 0; next[i] = - std::numeric_limits::infinity(); - } else if (ray.d[i] > 0) { - delta[i] = m_cellWidth[i]/ray.d[i]; - next[i] = mint + (corner2[i] - pos[i]) / ray.d[i]; - step[i] = 1; - bounds[i] = m_res[i]; - } else { - delta[i] = -m_cellWidth[i]/ray.d[i]; - next[i] = mint + (corner1[i] - pos[i]) / ray.d[i]; - step[i] = -1; - bounds[i] = -1; - } - } - - /* Walk through the voxel grid (3D DDA) */ - while (true) { - Float nextT = std::min(std::min(std::min(next.x, next.y), next.z), maxt); - - const int arrayIdx = dpos.x + dpos.y * m_res.x + dpos.z * m_slab; - m_cells[arrayIdx] = functor(m_cells[arrayIdx], nextT - t); - t = nextT; - - if (next.x <= next.y && next.x <= next.z) { - if (next.x > maxt) - break; - dpos.x += step.x; - if (dpos.x == bounds.x) - break; - next.x += delta.x; - } else if (next.y <= next.x && next.y <= next.z) { - if (next.y > maxt) - break; - dpos.y += step.y; - if (dpos.y == bounds.y) - break; - next.y += delta.y; - } else { - if (next.z > maxt) - break; - dpos.z += step.z; - if (dpos.z == bounds.z) - break; - next.z += delta.z; - } - } - } - - /// Return a string representation (MATLAB format) - std::string toStringMATLAB() const { - std::ostringstream oss; - - oss << "v=reshape(["; - for (int z=0; z= m_res.x-1 || - j >= m_res.y || k >= m_res.z) - return ValueType(); - - const Float alpha = x-i, - beta = y-j, - gamma = z-k; - - const ValueType - A1 = m_cells[pos], - B1 = (i+1. */ - #if !defined(__MMAP_H) #define __MMAP_H diff --git a/include/mitsuba/core/object.h b/include/mitsuba/core/object.h index e14af4ae..140803c3 100644 --- a/include/mitsuba/core/object.h +++ b/include/mitsuba/core/object.h @@ -33,6 +33,7 @@ MTS_NAMESPACE_BEGIN * * \sa ref, Class * \ingroup libcore + * \ingroup libpython */ class MTS_EXPORT_CORE Object { public: diff --git a/include/mitsuba/core/plugin.h b/include/mitsuba/core/plugin.h index efc6a799..5634ff65 100644 --- a/include/mitsuba/core/plugin.h +++ b/include/mitsuba/core/plugin.h @@ -34,6 +34,7 @@ MTS_NAMESPACE_BEGIN * \ref Utility classes for details * * \ingroup libcore + * \ingroup libpython */ class MTS_EXPORT_CORE Plugin { typedef void *(*CreateInstanceFunc)(const Properties &props); @@ -88,6 +89,7 @@ private: * loading external plugins. * * \ingroup libcore + * \ingroup libpython */ class MTS_EXPORT_CORE PluginManager : public Object { public: diff --git a/include/mitsuba/core/properties.h b/include/mitsuba/core/properties.h index 3f348220..57b79fc5 100644 --- a/include/mitsuba/core/properties.h +++ b/include/mitsuba/core/properties.h @@ -25,8 +25,19 @@ MTS_NAMESPACE_BEGIN -/** \brief Associative map for values of various types. Used to - * construct subclasses of ConfigurableObject. +/** \brief Associative parameter map for constructing + * subclasses of \ref ConfigurableObject. + * + * Note that the Python bindings for this class do not implement + * the various type-dependent getters and setters. Instead, they + * are accessed just like a normal Python map, e.g: + * + * \code + * myProps = mitsuba.core.Properties("pluginName") + * myProps["stringProperty"] = "hello" + * myProps["spectrumProperty"] = mitsuba.core.Spectrum(1.0) + * \endcode + * * \ingroup libcore * \ingroup libpython */ diff --git a/include/mitsuba/core/quad.h b/include/mitsuba/core/quad.h index 40e7edc2..f4e82290 100644 --- a/include/mitsuba/core/quad.h +++ b/include/mitsuba/core/quad.h @@ -16,7 +16,6 @@ along with this program. If not, see . */ - #if !defined(__QUADRATURE_H) #define __QUADRATURE_H diff --git a/include/mitsuba/core/random.h b/include/mitsuba/core/random.h index faeea48a..6975609c 100644 --- a/include/mitsuba/core/random.h +++ b/include/mitsuba/core/random.h @@ -90,6 +90,7 @@ MTS_NAMESPACE_BEGIN /** * \brief %Random number generator based on Mersenne Twister * by Takuji Nishimura and Makoto Matsumoto. + * \ingroup libpython */ class MTS_EXPORT_CORE Random : public SerializableObject { public: diff --git a/include/mitsuba/core/ray.h b/include/mitsuba/core/ray.h index 54b2b04f..81bcf1e8 100644 --- a/include/mitsuba/core/ray.h +++ b/include/mitsuba/core/ray.h @@ -30,6 +30,7 @@ MTS_NAMESPACE_BEGIN * to alignment purposes and should not be changed. * * \ingroup libcore + * \ingroup libpython */ struct Ray { Point o; ///< Ray origin diff --git a/include/mitsuba/core/sched.h b/include/mitsuba/core/sched.h index 62d4e029..3e1199b7 100644 --- a/include/mitsuba/core/sched.h +++ b/include/mitsuba/core/sched.h @@ -35,6 +35,7 @@ MTS_NAMESPACE_BEGIN * \brief Abstract work unit -- represents a small amount of information * that encodes part of a larger processing task. * \ingroup libcore + * \ingroup libpython */ class MTS_EXPORT_CORE WorkUnit : public Object { public: @@ -60,6 +61,7 @@ protected: * \brief Abstract work result -- represents the result of a * processed \ref WorkUnit instance. * \ingroup libcore + * \ingroup libpython */ class MTS_EXPORT_CORE WorkResult : public Object { public: @@ -90,6 +92,7 @@ protected: * and therefore no form of locking is required within instances of this class. * * \ingroup libcore + * \ingroup libpython */ class MTS_EXPORT_CORE WorkProcessor : public SerializableObject { friend class Scheduler; @@ -166,6 +169,7 @@ protected: * chunks of globally shared read-only data required during execution. * * \ingroup libcore + * \ingroup libpython */ class MTS_EXPORT_CORE ParallelProcess : public Object { friend class Scheduler; @@ -319,6 +323,7 @@ class Worker; * or sent to remote nodes over a network connection. * * \ingroup libcore + * \ingroup libpython */ class MTS_EXPORT_CORE Scheduler : public Object { friend class Worker; @@ -642,6 +647,7 @@ private: /** * \brief Base class of all worker implementations + * \ingroup libpython */ class MTS_EXPORT_CORE Worker : public Thread { friend class Scheduler; @@ -727,6 +733,7 @@ protected: * it locally. * * \ingroup libcore + * \ingroup libpython */ class MTS_EXPORT_CORE LocalWorker : public Worker { public: diff --git a/include/mitsuba/core/sched_remote.h b/include/mitsuba/core/sched_remote.h index 0e6be587..e7243d53 100644 --- a/include/mitsuba/core/sched_remote.h +++ b/include/mitsuba/core/sched_remote.h @@ -43,6 +43,7 @@ class StreamBackend; * it to a processing node reachable through a \ref Stream. * * \ingroup libcore + * \ingroup libpython */ class MTS_EXPORT_CORE RemoteWorker : public Worker { friend class RemoteWorkerReader; diff --git a/include/mitsuba/core/serialization.h b/include/mitsuba/core/serialization.h index c507ac80..d74e4265 100644 --- a/include/mitsuba/core/serialization.h +++ b/include/mitsuba/core/serialization.h @@ -29,6 +29,7 @@ MTS_NAMESPACE_BEGIN * RTTI macros \ref MTS_IMPLEMENT_CLASS_S or \ref MTS_IMPLEMENT_CLASS_IS. * * \ingroup libcore + * \ingroup libpython */ class MTS_EXPORT_CORE SerializableObject : public Object { public: @@ -58,6 +59,7 @@ protected: * object graph has the same structure. * * \ingroup libcore + * \ingroup libpython */ class MTS_EXPORT_CORE InstanceManager : public Object { friend class SerializableObject; diff --git a/include/mitsuba/core/shvector.h b/include/mitsuba/core/shvector.h index 82b04051..de224224 100644 --- a/include/mitsuba/core/shvector.h +++ b/include/mitsuba/core/shvector.h @@ -33,7 +33,9 @@ namespace ublas = boost::numeric::ublas; struct SHVector; /** - * \brief Stores the diagonal blocks of a spherical harmonic rotation matrix + * \brief Stores the diagonal blocks of a spherical harmonic + * rotation matrix + * * \ingroup libcore */ struct MTS_EXPORT_CORE SHRotation { @@ -65,14 +67,14 @@ struct MTS_EXPORT_CORE SHRotation { * * The Mathematica equivalent of the basis functions implemented here is: * - * 
+ * \code
  * SphericalHarmonicQ[l_, m_, \[Theta]_, \[Phi]_] :=
  *   Piecewise[{
  *      {SphericalHarmonicY[l, m, \[Theta], \[Phi]], m == 0},
  *      {Sqrt[2]*Re[SphericalHarmonicY[l, m, \[Theta], \[Phi]]], m > 0},
  *      {Sqrt[2]*Im[SphericalHarmonicY[l, -m, \[Theta], \[Phi]]], m < 0}
  *  }]
- *
+ * \endcode * * \ingroup libcore */ diff --git a/include/mitsuba/core/spectrum.h b/include/mitsuba/core/spectrum.h index 41fac5c6..091803a5 100644 --- a/include/mitsuba/core/spectrum.h +++ b/include/mitsuba/core/spectrum.h @@ -45,6 +45,7 @@ MTS_NAMESPACE_BEGIN * that it is a function over the reals (as opposed to the discrete * spectrum, which only stores samples for a discrete set of wavelengths). * + * \ingroup libpython * \ingroup libcore */ class MTS_EXPORT_CORE ContinuousSpectrum { @@ -187,6 +188,7 @@ private: * spectrum. * * \ingroup libcore + * \ingroup libpython */ class MTS_EXPORT_CORE InterpolatedSpectrum : public ContinuousSpectrum { public: @@ -290,6 +292,7 @@ private: * The implementation of this class is based on PBRT. * * \ingroup libcore + * \ingroup libpython */ struct MTS_EXPORT_CORE Spectrum { public: diff --git a/include/mitsuba/core/spline.h b/include/mitsuba/core/spline.h index 62fcb8ff..e3eb1ff7 100644 --- a/include/mitsuba/core/spline.h +++ b/include/mitsuba/core/spline.h @@ -25,6 +25,8 @@ MTS_NAMESPACE_BEGIN /** * \brief Simple natural cubic spline interpolation + * + * \ingroup libcore */ class MTS_EXPORT_CORE CubicSpline : public SerializableObject { public: diff --git a/include/mitsuba/core/sshstream.h b/include/mitsuba/core/sshstream.h index 1ab9323d..001b1833 100644 --- a/include/mitsuba/core/sshstream.h +++ b/include/mitsuba/core/sshstream.h @@ -39,6 +39,8 @@ MTS_NAMESPACE_BEGIN * pageant.exe is required to load and authenticate the key. * * Note: SSH streams are set to use network byte order by default. + * + * \ingroup libcore */ class MTS_EXPORT_CORE SSHStream : public Stream { public: diff --git a/include/mitsuba/core/transform.h b/include/mitsuba/core/transform.h index 39ab43ea..a2252164 100644 --- a/include/mitsuba/core/transform.h +++ b/include/mitsuba/core/transform.h @@ -27,6 +27,7 @@ MTS_NAMESPACE_BEGIN /** * \brief Encapsulates a 4x4 linear transformation and its inverse * \ingroup libcore + * \ingroup libpython */ struct MTS_EXPORT_CORE Transform { public: diff --git a/include/mitsuba/core/version.h b/include/mitsuba/core/version.h index d8b6bee4..8d315f3c 100644 --- a/include/mitsuba/core/version.h +++ b/include/mitsuba/core/version.h @@ -21,15 +21,24 @@ MTS_NAMESPACE_BEGIN -/// Current release of Mitsuba +/** + * Current release of Mitsuba + * \ingroup libcore + */ #define MTS_VERSION "0.3.0" -// Year of this release +/** + * Current release of Mitsuba + * \ingroup libcore + */ +#define MTS_VERSION "0.3.0" #define MTS_YEAR "2011" /** - * \brief A simple data structure for representing and comparing - * Mitsuba version strings + * \brief A simple data structure for representing and + * comparing Mitsuba version strings + * + * \ingroup libcore */ struct MTS_EXPORT_CORE Version { public: