From 7a18e4312322b1ea385aabbb7148d394fbda68b9 Mon Sep 17 00:00:00 2001 From: Wenzel Jakob Date: Wed, 15 Sep 2010 21:15:42 +0200 Subject: [PATCH] more source-level documentation --- include/mitsuba/core/cstream.h | 2 +- include/mitsuba/core/fresolver.h | 7 +- include/mitsuba/core/grid.h | 12 +- include/mitsuba/core/octree.h | 7 +- include/mitsuba/core/random.h | 17 +- include/mitsuba/core/ray.h | 21 +- include/mitsuba/core/sched.h | 303 ++++++++++++++++------------ include/mitsuba/core/sched_remote.h | 40 ++-- include/mitsuba/core/shvector.h | 62 +++--- include/mitsuba/core/shvector4d.h | 9 +- include/mitsuba/core/triangle.h | 44 ++-- include/mitsuba/core/wavelet.h | 33 +-- 12 files changed, 331 insertions(+), 226 deletions(-) diff --git a/include/mitsuba/core/cstream.h b/include/mitsuba/core/cstream.h index d6019ad6..a1596453 100644 --- a/include/mitsuba/core/cstream.h +++ b/include/mitsuba/core/cstream.h @@ -23,7 +23,7 @@ MTS_NAMESPACE_BEGIN -/** \brief Console stream +/** \brief Interface to the default stdin/stdout console streams */ class MTS_EXPORT_CORE ConsoleStream : public Stream { public: diff --git a/include/mitsuba/core/fresolver.h b/include/mitsuba/core/fresolver.h index f2a8fb0d..b09d3826 100644 --- a/include/mitsuba/core/fresolver.h +++ b/include/mitsuba/core/fresolver.h @@ -38,9 +38,10 @@ MTS_NAMESPACE_BEGIN class MTS_EXPORT_CORE FileResolver : public Object { public: /** - * Create a new file resolver containing the - * current working directory as the initial - * search path. + * \brief Create a new file resolver with the default settings + * + * Create a new file resolver containing the current working + * directory as the initial search path. */ FileResolver(); diff --git a/include/mitsuba/core/grid.h b/include/mitsuba/core/grid.h index 092bf6b9..e1169a17 100644 --- a/include/mitsuba/core/grid.h +++ b/include/mitsuba/core/grid.h @@ -24,8 +24,7 @@ MTS_NAMESPACE_BEGIN /** - * Uniform 3D grid for storing arbitrary quantities, which can - * be queried and updated by rasterizing rays to the grid. + * \brief Uniform 3D grid for storing and manipulating arbitrary quantities */ template class Grid { public: @@ -82,7 +81,7 @@ public: /// Return the grid AABB inline const AABB &getAABB() const { return m_aabb; } - + /// Return the grid resolution inline const Vector3i &getResolution() const { return m_res; } @@ -98,7 +97,7 @@ public: inline const ValueType &operator()(int x, int y, int z) const { return m_cells[x + y*m_res.x + z*m_slab]; } - /// Return the underlying array + /// Return a pointer to the underlying array inline ValueType *getData() const { return m_cells; } /// Return a string representation @@ -172,7 +171,10 @@ public: return true; } - /// Rasterize a ray to the grid + /** + * \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; diff --git a/include/mitsuba/core/octree.h b/include/mitsuba/core/octree.h index 07a0ecc3..27533524 100644 --- a/include/mitsuba/core/octree.h +++ b/include/mitsuba/core/octree.h @@ -25,9 +25,10 @@ MTS_NAMESPACE_BEGIN /** - * Templated multiple-reference octree. Based on the excellent - * implementation in PBRT. Modifications are the addition of a - * bounding sphere query and support for multithreading. + * \brief Generic multiple-reference octree. + * + * Based on the excellent implementation in PBRT. Modifications are + * the addition of a bounding sphere query and support for multithreading. */ template class Octree { public: diff --git a/include/mitsuba/core/random.h b/include/mitsuba/core/random.h index 1504ba70..ab61cad6 100644 --- a/include/mitsuba/core/random.h +++ b/include/mitsuba/core/random.h @@ -86,12 +86,17 @@ MTS_NAMESPACE_BEGIN - +/** + * \brief %Random number generator based on Mersenne Twister + * by Takuji Nishimura and Makoto Matsumoto. + */ class MTS_EXPORT_CORE Random : public SerializableObject { public: /** - * Construct a new seeded random generator. Uses the default - * seed on Windows and '/dev/urandom' on OSX and Linux. + * \brief Construct a new seeded random generator. + * + * Uses the default seed on Windows and '/dev/urandom' + * on OSX and Linux. */ Random(); @@ -123,8 +128,10 @@ public: Float nextFloat(); /** - * Draw a uniformly distributed permutation and permute the given STL container - * (see Knuth, TAoCP Vol. 2 (3rd 3d), Section 3.4.2) + * \brief Draw a uniformly distributed permutation and permute the + * given STL container. + * + * See Knuth, TAoCP Vol. 2 (3rd 3d), Section 3.4.2. */ template void shuffle(Iterator it1, Iterator it2) { for (Iterator it = it2 - 1; it > it1; --it) diff --git a/include/mitsuba/core/ray.h b/include/mitsuba/core/ray.h index 84a866dc..e986d405 100644 --- a/include/mitsuba/core/ray.h +++ b/include/mitsuba/core/ray.h @@ -102,7 +102,7 @@ struct Ray { } }; -/** \brief Ray differential -- enhances the basic ray class with +/** \brief %Ray differential -- enhances the basic ray class with information about the rays of adjacent pixels on the view plane */ struct RayDifferential : public Ray { bool hasDifferentials; @@ -119,16 +119,29 @@ struct RayDifferential : public Ray { inline explicit RayDifferential(const Ray &ray) : Ray(ray), hasDifferentials(false) { } - + inline RayDifferential(const RayDifferential &ray) : Ray(ray), hasDifferentials(ray.hasDifferentials), rx(ray.rx), ry(ray.ry) { } + + inline void operator=(const RayDifferential &ray) { + o = ray.o; + mint = ray.mint; + d = ray.d; + maxt = ray.maxt; + dRcp = ray.dRcp; + hasDifferentials = ray.hasDifferentials; + rx = ray.rx; + ry = ray.ry; + } inline void operator=(const Ray &ray) { - setOrigin(ray.o); - setDirection(ray.d); + o = ray.o; mint = ray.mint; + d = ray.d; maxt = ray.maxt; + dRcp = ray.dRcp; + hasDifferentials = false; } }; diff --git a/include/mitsuba/core/sched.h b/include/mitsuba/core/sched.h index 0b97b4c3..c33f03dd 100644 --- a/include/mitsuba/core/sched.h +++ b/include/mitsuba/core/sched.h @@ -32,7 +32,7 @@ MTS_NAMESPACE_BEGIN /** - * Abstract work unit. Represents a small amount of information + * \brief Abstract work unit -- represents a small amount of information * that encodes part of a larger processing task. */ class MTS_EXPORT_CORE WorkUnit : public Object { @@ -56,8 +56,8 @@ protected: }; /** - * Abstract work result. Represents the information that encodes - * the result of a processed WorkUnit instance. + * \brief Abstract work result -- represents the result of a + * processed \ref WorkUnit instance. */ class MTS_EXPORT_CORE WorkResult : public Object { public: @@ -77,30 +77,28 @@ protected: }; /** - * Abstract work processor. Takes work units and turns them into - * WorkResult instances. The class is serializable so that - * it can be sent over the network if required. It is possible to - * keep local state in WorkProcessor instances (e.g. scratch - * space for computations), though anything not returned in the form - * of WorkResults will eventually be lost. Each worker - * (both locally and remotely) has its own WorkProcessor, - * and therefore no form of locking is required. + * \brief Abstract work processor -- takes work units and turns them into + * WorkResult instances. + * + * The class is serializable so that it can be sent over the network if + * required. It is possible to keep local state in WorkProcessor + * instances (e.g. scratch space for computations), though anything not + * returned in the form of WorkResults will eventually be lost. + * Each worker (both locally and remotely) has its own WorkProcessor, + * and therefore no form of locking is required within instances of this class. */ class MTS_EXPORT_CORE WorkProcessor : public SerializableObject { friend class Scheduler; public: - /** - * Create a work unit of the proper type and size. - */ + /// Create a work unit of the proper type and size. virtual ref createWorkUnit() const = 0; - /** - * Create a work result of the proper type and size - */ + /// Create a work result of the proper type and size virtual ref createWorkResult() const = 0; /** - * Create a copy of this work processor instance. + * \brief Create a copy of this work processor instance. + * * Note: Before the cloned work processor is used, its * prepare() method will be called - therefore, state * that is initialized there does not have to be copied. @@ -108,22 +106,23 @@ public: virtual ref clone() const = 0; /** - * Called once before processing starts. This is useful for allocating - * scratch space or resolving references to resource objects. Lengthy - * computations should be performed in process() instead of here, since - * this this method will be called while the central scheduler lock - * is held. A thrown exception will lead to the termination of the parallel - * process. + * \brief Called once before processing starts. + * + * This is useful for allocating scratch space or resolving references + * to resource objects. Lengthy computations should be performed in + * process() instead of here, since this this method will be called + * while the central scheduler lock is held. A thrown exception will + * lead to the termination of the parallel process. */ virtual void prepare() = 0; /** - * Process a work unit and store the computed results. The active - * parameter can be used to signal a premature stop of the execution flow. - * In this case, the work result is allowed to be undefined (it will - * simply be ignored). - * A thrown exception will lead to the termination of the parallel - * process. + * \brief Process a work unit and store the computed results. + * + * The active parameter can be used to signal a premature + * stop of the execution flow. In this case, the work result is allowed + * to be undefined (it will simply be ignored). A thrown exception will + * lead to the termination of the parallel process. */ virtual void process(const WorkUnit *workUnit, WorkResult *workResult, const bool &stop) = 0; @@ -138,9 +137,10 @@ protected: : SerializableObject(stream, manager) { } /** - * Look up a named resource, which has been bound to the associated - * parallel process. Throws an exception if the resource is not - * known / bound. + * \brief Look up a named resource, which has been bound to + * the associated parallel process. + * + * Throws an exception if the resource is not known / bound. */ SerializableObject *getResource(const std::string &name); protected: @@ -148,114 +148,143 @@ protected: }; /** - * Abstract parallelizable task. Models a larger piece of work that - * can be split into independent `units' and subsequently farmed - * out over a cluster or processed locally. After the work units have - * been completed, the results are pieced back together to a solution of - * the original large-scale problem. This class implements the core logic - * running on the central scheduling server, i.e. the part that is - * responsible for generating work units and accepting their results. - * The module that performs the actual computation is an instance of - * WorkProcessor, which is also specified here. + * \brief Abstract parallelizable task. + * + * Models a larger piece of work that can be split into independent + * `units' and subsequently farmed out over a cluster or processed locally. + * After the work units have been completed, the results are pieced back + * together to a solution of the original large-scale problem. This class + * implements the core logic running on the central scheduling server, + * i.e. the part that is responsible for generating work units and + * accepting their results. The module that performs the actual computation + * is an instance of WorkProcessor, which is also specified here. * Finally, the this class references `resources', which denote * chunks of globally shared read-only data required during execution. */ class MTS_EXPORT_CORE ParallelProcess : public Object { friend class Scheduler; public: + /// Binding from local resource names to global resource IDs typedef std::map ResourceBindings; /// Return codes used by generateWork() and getReturnStatus() enum EStatus { - EUnknown, - EPause, - ESuccess, - EFailure + EUnknown, ///< Unknown return status + EPause, ///< Temporarily, no work units can be created + ESuccess, ///< The process finished / a piece of work was generated + EFailure ///< The process failed / no more work is available }; /** - * Generate a piece of work. Takes a pre-allocated WorkUnit - * instance of the appropriate sub-type and size (as specified by - * ParallelProcess::getWorkUnitName) and fills it with the - * appropriate content. Returns ESuccess on success and EFailure or EPause - * when no more work is left -- in that case, the work unit will - * be ignored and the process completed (EFailure) or temporarily - * paused (EPause). When EPause was used, resubmission via - * Scheduler::schedule() will be required once more work - * is available. In some cases, it is useful to distribute 'nearby' - * pieces of work to the same processor -- the worker - * parameter can be used to implement this. - * This function should run as quickly as possible, since it will - * be executed while the scheduler mutex is held. A thrown exception - * will lead to the termination of the parallel process. + * \brief Generate a piece of work. + * + * Takes a pre-allocated \ref WorkUnit instance of + * the appropriate sub-type and size (as specified by + * \ref ParallelProcess::getWorkUnitName()) and + * fills it with the appropriate content. Returns ESuccess + * on success and EFailure or EPause when no more work is + * left -- in that case, the work unit will be ignored and + * the process completed (\ref EFailure) or temporarily + * paused (\ref EPause). When \ref EPause was used, + * resubmission via \ref Scheduler::schedule() will + * be required once more work is available. In some cases, it + * is useful to distribute 'nearby' pieces of work to the same + * processor -- the worker parameter can be used to + * implement this. + * This function should run as quickly as possible, since it + * will be executed while the scheduler mutex is held. A + * thrown exception will lead to the termination of the + * parallel process. + * + * \param unit Work unit data structure to be filled + * \param worker ID of the worker executing this function */ virtual EStatus generateWork(WorkUnit *unit, int worker) = 0; /** - * Called whenever a work unit has been completed. Note - * that this may be executed by different threads and - * likely out of order (some sort of locking will - * generally be required when modifying data structures). + * \brief Called whenever a work unit has been completed. + * + * Note that this function may concurrently be executed by + * multiple threads. Also, processing of work results will + * generally be out of order with respect to the creation + * in \ref generateWork(). + * * When a work unit is only partially completed due to * a call to Scheduler::cancel, the second * parameter is set to true. * A thrown exception will lead to the termination of * the parallel process. + * + * \param result Work result to be processed + * \param cancelled Was the associated work unit not fully completed */ virtual void processResult(const WorkResult *result, bool cancelled) = 0; /** - * Called when the parallel process is canceled - * by Scheduler::cancel(). The default implementation - * does nothing. + * \brief Called when the parallel process is canceled by + * \ref Scheduler::cancel(). + * + * The default implementation does nothing. */ virtual void handleCancellation(); /** - * After a process has finished excecution, its return - * status can be queried through this method. - * Returns one of Success, Failure or Unknown - * (EUnknown means that the process is either still running + * \brief Query the return status of a process after its + * execution has finished. + * + * Returns one of \ref Success, \ref Failure or \ref Unknown + * (\ref EUnknown means that the process is either still running * or has never been scheduled). */ inline EStatus getReturnStatus() const { return m_returnStatus; } /** - * Create an instance of the algorithm responsible + * \brief Create an instance of the algorithm responsible * for executing the work units of this parallel process. */ virtual ref createWorkProcessor() const = 0; /** - * Bind a resource to this parallel process. Takes a resource - * ID as given by the scheduler and associates it with a name. - * This name can later be used by the work processor to access - * the resource data. + * \brief Bind a resource to this parallel process. + * + * Takes a resource ID as given by the scheduler and associates it + * with a name. This name can later be used by the work processor + * to access the resource data. + * + * \param name Process-specific name of the resource + * \param id Resource ID as returned by \ref Scheduler::registerResource() + * \sa WorkProcessor::getResource */ virtual void bindResource(const std::string &name, int id); /** - * Is this process local, i.e. not distributed to remote - * processing nodes? The default implementation returs false. + * \brief Is this process strictly local? + * + * If a process is marked as local, it shouldn't be distributed + * to remote processing nodes? The default implementation + * returns false. */ virtual bool isLocal() const; /** - * Return the log level for events associated with this process. + * \brief Return the log level for events associated with this process. + * * By default, this is set to EDebug */ inline ELogLevel getLogLevel() const { return m_logLevel; } /** - * Return a list of the bound resources + * \brief Return a list of all bound resources */ inline const ResourceBindings &getResourceBindings() const { return m_bindings; } /** - * Return a list of plugins required by this parallel process. - * The default implementation just returns all plugins that are - * loaded in the current application image. + * \brief Return a list of plugins required by this parallel process. + * + * This is required so that remote machines can load the plugins before + * they accept work from this process. The default implementation just + * returns all plugins that are loaded in the current application. */ virtual std::vector getRequiredPlugins(); @@ -275,35 +304,40 @@ protected: class Worker; /** - * Centralized task scheduler implementation. Accepts parallelizable - * jobs and distributes their computational load both locally and remotely. - * This is done by associating different types of Workers with - * the scheduler. These try to acquire work units from the scheduler, - * which are then executed on the current machine or sent to remote - * nodes over a network connection. + * \brief Centralized task scheduler implementation. + * + * Accepts parallelizable jobs and distributes their computational load + * both locally and remotely. This is done by associating different types + * of \ref Workers with the scheduler. These try to acquire work + * units from the scheduler, which are then executed on the current machine + * or sent to remote nodes over a network connection. */ class MTS_EXPORT_CORE Scheduler : public Object { friend class Worker; public: /** - * Schedule a parallelizable process for execution. If the - * scheduler is currently running and idle, its execution - * will begin immediately. Returns false if the process - * is already scheduled and has not yet terminated. + * \brief Schedule a parallelizable process for execution. + * + * If the scheduler is currently running and idle, its execution + * will begin immediately. Returns \a false if the process + * is already scheduled and has not yet terminated and \a true + * in any other case. */ bool schedule(ParallelProcess *process); /** - * Block until the process has successfully been completed - * or canceled prematurely. Returns false if the process - * does not exist or has already finished by the time - * wait() is invoked. + * \brief Block until the process has successfully been completed + * or canceled prematurely. + * + * Returns false if the process does not exist or has already + * finished by the time \ref wait() is invoked. */ bool wait(const ParallelProcess *process); /** - * Cancel the execution of a parallelizable process. Upon - * return, no more work from this process is running. + * \brief Cancel the execution of a parallelizable process. + * + * Upon return, no more work from this process is running. * Returns false if the process does not exist (anymore). */ inline bool cancel(ParallelProcess *proc) { @@ -311,41 +345,48 @@ public: } /** - * Register a serializable resource with the scheduler. This should be - * thought of as a constant state that is shared amongst all processing - * nodes. Resources can be reused by subsequent parallel processes, and - * consequently do not have to be re-transmitted over the network. Returns - * a resource ID, which can be used to reference the associated data. + * \brief Register a serializable resource with the scheduler. + * + * A resource should be thought of as a constant state that is shared + * amongst all processing nodes. Resources can be reused by + * subsequent parallel processes, and consequently do not have to be + * re-transmitted over the network. Returns a resource ID, which can be + * used to reference the associated data. */ int registerResource(SerializableObject *resource); /** - * Register a 'manifold' resource with the scheduler. Manifold means that - * in comparison to the previous method, a separate instance is provided - * for every core. An example where this is useful is to distribute - * random generator state when performing parallel Monte Carlo simulations. - * resources must be a vector whose length is equal - * to getCoreCount(). + * \brief Register a \a manifold resource with the scheduler. + * Manifold means that in comparison to the previous method, a separate + * instance is provided for every core. An example where this is useful + * is to distribute random generator state when performing parallel + * Monte Carlo simulations. resources must be a vector whose + * length is equal to \ref getCoreCount(). */ int registerManifoldResource(std::vector &resources); /** - * Increase the reference count of a previously registered resource. + * \brief Increase the reference count of a previously registered resource. + * * The resource must be unregistered an additional time after calling * this function. + * + * \sa unregisterResource */ void retainResource(int resourceID); /** - * Unregister a resource from the scheduler (takes the previously - * created ID). Note that the resource's won't be removed - * until all processes using it have terminated) + * \brief Unregister a resource from the scheduler + * + * Note that the resource's won't be removed until all processes using + * it have terminated) */ void unregisterResource(int id); /** - * Return the ID of a registered resource. Throws an exception - * if the resource cannot be found. + * \brief Return the ID of a registered resource + * + * Throws an exception if the resource cannot be found. */ int getResourceID(const SerializableObject *resource) const; @@ -365,15 +406,15 @@ public: void start(); /** - * Puase the distribution of work units and shut down all running workers. - * Any currently scheduled work units are still completed. Processing can - * be resumed via start(). + * \brief Pause the distribution of work units and shut down all + * running workers. + * + * Any currently scheduled work units are still completed. + * Processing can be resumed via \ref start(). */ void pause(); - - /** - * Cancel all running processes and free memory used by resources - */ + + /// Cancel all running processes and free memory used by resources void stop(); /// Return the total number of cores exposed through this scheduler @@ -525,7 +566,7 @@ protected: signalProcessTermination(item.proc, item.rec); m_mutex->unlock(); } - + /** * Cancel the execution of a parallelizable process. Upon * return, no more work from this process is running. When @@ -589,7 +630,7 @@ private: }; /** - * Base class of all worker implementations + * \brief Base class of all worker implementations */ class MTS_EXPORT_CORE Worker : public Thread { friend class Scheduler; @@ -615,20 +656,22 @@ protected: int workerIndex, int coreOffset); /** - * Called to inform a worker that a resource is no longer in use. The - * remote worker uses this to notify the machine on the other end that + * \brief Called to inform a worker that a resource is no longer in use. + * + * The remote worker uses this to notify the machine on the other end that * the memory used by this resource can now be released. */ virtual void signalResourceExpiration(int id) = 0; /** - * Called to inform a worker that a process has been cancelled + * \brief Called to inform a worker that a process has been cancelled + * * Guaranteed to be called while the Scheduler's main lock is held. */ virtual void signalProcessCancellation(int id) = 0; /** - * Called to inform a worker that a process has successfully been + * \brief Called to inform a worker that a process has successfully been * completed and any associated resources can be freed. */ virtual void signalProcessTermination(int id) = 0; @@ -669,7 +712,7 @@ protected: }; /** - * Local worker thread. Acquires work from the scheduler and executes + * \brief Acquires work from the scheduler and executes * it locally. */ class MTS_EXPORT_CORE LocalWorker : public Worker { diff --git a/include/mitsuba/core/sched_remote.h b/include/mitsuba/core/sched_remote.h index bdeb2226..c68c7626 100644 --- a/include/mitsuba/core/sched_remote.h +++ b/include/mitsuba/core/sched_remote.h @@ -21,11 +21,11 @@ #include -/* How many work units should be sent to a remote worker +/** How many work units should be sent to a remote worker at a time? This is a multiple of the worker's core count */ #define BACKLOG_FACTOR 3 -/* Once the back log factor drops below this value (also a +/** Once the back log factor drops below this value (also a multiple of the core size), the stream processor will continue sending batches of work units */ #define CONTINUE_FACTOR 2 @@ -36,13 +36,16 @@ class RemoteWorkerReader; class StreamBackend; /** - * Remote worker thread. Acquires work from the scheduler and forwards - * it to a processing node reachable over some form of stream (usually - * a SocketStream). + * \brief Acquires work from the scheduler and forwards + * it to a processing node reachable through a \ref Stream. */ class MTS_EXPORT_CORE RemoteWorker : public Worker { friend class RemoteWorkerReader; public: + /** + * \brief Construct a new remote worker with the given name and + * communication stream + */ RemoteWorker(const std::string &name, Stream *stream); /// Return the name of the node on the other side @@ -84,8 +87,9 @@ protected: }; /** - * Remote worker helper thread - constantly waits for finished - * work units sent by the processing node. + * \brief Communication helper thread required by \ref RemoteWorker. + * + * Constantly waits for finished work units sent by the processing node. */ class MTS_EXPORT_CORE RemoteWorkerReader : public Thread { friend class RemoteWorker; @@ -110,11 +114,19 @@ private: }; /** - * 'Fake' parallel process used to insert work units from a + * \brief Parallel process facade used to insert work units from a * remote scheduler into the local one. */ class MTS_EXPORT_CORE RemoteProcess : public ParallelProcess { public: + /** + * \brief Create a new remote process + * + * \param id Identification number for this process + * \param logLevel Log level for events associated with this process + * \param backend The responsible server-side communication backend + * \param proc Work processor instance for use with this process + */ RemoteProcess(int id, ELogLevel logLevel, StreamBackend *backend, WorkProcessor *proc); @@ -125,6 +137,7 @@ public: ref createWorkProcessor() const; void handleCancellation(); + /// Get an empty work unit from the process (or create one) inline WorkUnit *getEmptyWorkUnit() { ref wu; m_mutex->lock(); @@ -139,12 +152,14 @@ public: return wu; } + /// Make a full work unit available to the process inline void putFullWorkUnit(WorkUnit *wu) { m_mutex->lock(); m_full.push_back(wu); m_mutex->unlock(); } + /// Mark the process as finished inline void setDone() { m_mutex->lock(); m_done = true; @@ -166,9 +181,10 @@ private: }; /** - * Stream backend - attaches to the end of a stream, accepts work units - * and forwards them to the local scheduler. Can be used to create - * remote processing nodes. + * \brief Network processing communication backend + * + * Attaches to the end of a stream, accepts work units and forwards + * them to the local scheduler. Can be used to create network processing nodes. */ class MTS_EXPORT_CORE StreamBackend : public Thread { friend class RemoteProcess; @@ -192,7 +208,7 @@ public: }; /** - * Create a new stream backend + * \brief Create a new stream backend * * @param name * Name of the created thread diff --git a/include/mitsuba/core/shvector.h b/include/mitsuba/core/shvector.h index 08f81d78..347048a3 100644 --- a/include/mitsuba/core/shvector.h +++ b/include/mitsuba/core/shvector.h @@ -32,10 +32,13 @@ namespace ublas = boost::numeric::ublas; struct SHVector; -/* Stores the diagonal blocks of a spherical harmonic rotation matrix */ +/** + * \brief Stores the diagonal blocks of a spherical harmonic rotation matrix + */ struct MTS_EXPORT_CORE SHRotation { std::vector > blocks; + /// Construct a new rotation storage for the given number of bands inline SHRotation(int bands) : blocks(bands) { for (int i=0; i * 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} * }] + * */ struct MTS_EXPORT_CORE SHVector { public: @@ -169,18 +177,20 @@ public: /// Evaluate for a direction given in spherical coordinates Float eval(Float theta, Float phi) const; - /// Evaluate for a direction given in cartesian coordinates + /// Evaluate for a direction given in Cartesian coordinates Float eval(const Vector &v) const; /** - * Evaluate for a direction given in spherical coordinates. + * \brief Evaluate for a direction given in spherical coordinates. + * * This function is much faster but only works for azimuthally * invariant functions */ Float evalAzimuthallyInvariant(Float theta, Float phi) const; /** - * Evaluate for a direction given in cartesian coordinates. + * \brief Evaluate for a direction given in cartesian coordinates. + * * This function is much faster but only works for azimuthally * invariant functions */ @@ -214,8 +224,10 @@ public: void offset(Float value); /** - * Convolve the SH representation with the supplied kernel, - * which must be rotationally symmetric around the Z-axis. + * \brief Convolve the SH representation with the supplied kernel. + * + * Based on the Funk-Hecke theorem -- the kernel must be rotationally + * symmetric around the Z-axis. */ void convolve(const SHVector &kernel); @@ -303,7 +315,7 @@ public: return error/denom; } - /* Evaluate an associated Legendre polynomial using the usual recurrence formulae */ + /// Evaluate an associated Legendre polynomial using the usual recurrence formulae static Float legendre(int l, int m, Float x); /// Return a normalization coefficient @@ -315,8 +327,9 @@ public: } /** - * Recursively computes rotation matrices for each band of SH coefficients. Based on - * 'Rotation Matrices for Real Spherical Harmonics. Direct Determination by Recursion' + * \brief Recursively computes rotation matrices for each band of SH coefficients. + * + * Based on 'Rotation Matrices for Real Spherical Harmonics. Direct Determination by Recursion' * by Ivanic and Ruedenberg. The implemented tables follow the notation in * 'Spherical Harmonic Lighting: The Gritty Details' by Robin Green. */ @@ -340,22 +353,23 @@ private: }; /** - * Implementation of 'Importance Sampling Spherical Harmonics' + * \brief Implementation of 'Importance Sampling Spherical Harmonics' * by W. Jarsz, N. Carr and H. W. Jensen (EUROGRAPHICS 2009) */ class MTS_EXPORT_CORE SHSampler : public Object { public: /** - * Create a spherical harmonics sampler object for the - * specified amount of SH coefficient bands. The 'depth' - * parameter specifies the number of recursive sample - * warping steps. + * \brief Precompute a spherical harmonics sampler object + * + * \param bands Number of SH coefficient bands to support + * \param depth Number of recursive sample warping steps. */ SHSampler(int bands, int depth); /** - * Warp a uniform sample in [0,1]^2 to one that is + * \brief Warp a uniform sample in [0,1]^2 to one that is * approximately proportional to the specified function. + * * The resulting sample will have spherical coordinates * [0,pi]x[0,2pi] and its actual PDF (which might be * slightly different from the function evaluated at the @@ -370,7 +384,7 @@ public: protected: /// Virtual destructor virtual ~SHSampler(); - + /* Index into the assoc. legendre polynomial table */ inline int I(int l, int m) const { return l*(l+1)/2 + m; } @@ -381,11 +395,11 @@ protected: return -m_phiMap[depth][phiBlock][P(m)] * m_legendreMap[depth][zBlock][I(l, std::abs(m))]; } - /* Recursively compute assoc. legendre & phi integrals */ + /// Recursively compute assoc. legendre & phi integrals Float *legendreIntegrals(Float a, Float b); Float *phiIntegrals(Float a, Float b); - /* Integrate a SH expansion over the specified mip-map region */ + /// Integrate a SH expansion over the specified mip-map region Float integrate(int depth, int zBlock, int phiBlock, const SHVector &f) const; protected: int m_bands; diff --git a/include/mitsuba/core/shvector4d.h b/include/mitsuba/core/shvector4d.h index fc084df6..1270c736 100644 --- a/include/mitsuba/core/shvector4d.h +++ b/include/mitsuba/core/shvector4d.h @@ -24,10 +24,11 @@ MTS_NAMESPACE_BEGIN /** - * Stores a 4D function f(wi, wo) (such as a BRDF or phase function) - * using a 2D table of spherical harmonics expansions. Discretizaiton - * occurs in the 'wi' space. Later lookups interpolate amongst - * the 4 adjacent samples + * \brief Stores a 4D function f(wi, wo) (such as a BRDF or phase function) + * using a 2D table of spherical harmonics expansions. + * + * Discretizaiton occurs in the 'wi' space. Lookups interpolate amongst + * the 4 adjacent samples. */ struct SHVector4D { public: diff --git a/include/mitsuba/core/triangle.h b/include/mitsuba/core/triangle.h index e1917481..e317173c 100644 --- a/include/mitsuba/core/triangle.h +++ b/include/mitsuba/core/triangle.h @@ -25,14 +25,15 @@ MTS_NAMESPACE_BEGIN /** - * Mesh vertex data structure. Stores 3D coordinates, - * vertex normals, UV coordinates and a tangent frame + * \brief Mesh vertex data structure. Stores 3D coordinates, + * vertex normals, UV coordinates and a tangent frame. */ struct Vertex { - Point v; - Normal n; - Point2 uv; - Vector dpdu, dpdv; + Point v; ///< %Vertex position + Normal n; ///< %Vertex normal + Point2 uv; ///< %Texture coordinates + Vector dpdu; ///< Partial derivative of the position with respect to \a u. + Vector dpdv; ///< Partial derivative of the position with respect to \a v. inline bool operator==(const Vertex &vert) const { return (v == vert.v && n == vert.n && uv == vert.uv @@ -44,26 +45,29 @@ struct Vertex { } }; -/** \brief Triangle class including a collection of routines - * for analysis and transformation. Triangles are stored as - * indices into a vertex array +/** + * \brief Simple triangle class including a collection of routines + * for analysis and transformation. + * + * Triangles are stored as indices into a vertex array */ struct MTS_EXPORT_CORE Triangle { - /* Indices into a vertex buffer */ + /// Indices into a vertex buffer unsigned int idx[3]; /// Construct an axis-aligned box, which contains the triangle AABB getAABB(const Vertex *buffer) const; /** - * Returns the axis-aligned bounding box of a triangle after it has - * clipped to the extends of another, given AABB. This function uses the - * Sutherland-Hodgman algorithm to calculate the convex polygon, which - * is created when applying all 6 AABB splitting planes to the triangle. - * Afterwards, the AABB of the newly created convex polygon is returned. - * This function is an important component for efficiently creating - * 'Perfect Split' KD-trees. For more detail, see - * "On building fast kd-Trees for Ray Tracing, and on doing + * \brief Returns the axis-aligned bounding box of a triangle after it has + * clipped to the extends of another, given AABB. + * + * This function uses the Sutherland-Hodgman algorithm to calculate the + * convex polygon, which is created when applying all 6 AABB splitting + * planes to the triangle. Afterwards, the AABB of the newly created + * convex polygon is returned. This function is an important component + * for efficiently creating 'Perfect Split' KD-trees. For more detail, + * see "On building fast kd-Trees for Ray Tracing, and on doing * that in O(N log N)" by Ingo Wald and Vlastimil Havran */ AABB getClippedAABB(const Vertex *buffer, const AABB &aabb) const; @@ -73,8 +77,8 @@ struct MTS_EXPORT_CORE Triangle { * Uses the algorithm presented by Moeller and Trumbore at * http://www.acm.org/jgt/papers/MollerTrumbore97/code.html * Returns true if an intersection has been detected - * On success, pT contains the distance from the ray origin to the - * intersection point and pUV contains the intersection point in + * On success, \a t contains the distance from the ray origin to the + * intersection point, and \a u and \a v contain the intersection point in * the local triangle coordinate system */ bool rayIntersect(const Vertex *buffer, const Ray &ray, Float &u, diff --git a/include/mitsuba/core/wavelet.h b/include/mitsuba/core/wavelet.h index 9ac619a5..8fae9b2a 100644 --- a/include/mitsuba/core/wavelet.h +++ b/include/mitsuba/core/wavelet.h @@ -38,19 +38,18 @@ MTS_NAMESPACE_BEGIN -class SparseWavelet2D; -class SparseWaveletOctree; - /** - * Non-standard 2D Haar wavelet transformation. Based on - * "Wavelets for computer graphics: A primer, part 1" by + * \brief Performs non-standard 2D Haar wavelet transformations. + * + * Based on "Wavelets for computer graphics: A primer, part 1" by * Eric J. Stollnitz, Tony D. DeRose, and David H. Salesin * (IEEE Computer Graphics and Applications, May 1995) */ class MTS_EXPORT_CORE Wavelet2D : public Object { public: /** - * Create a wavelet representation from a given bitmap. + * \brief Create a wavelet representation from a given bitmap. + * * Only one color channel is supported for this encoding, so * the desired channel must be selected using the `colorChannel' * parameter. @@ -61,7 +60,8 @@ public: Wavelet2D(const SparseWavelet2D *sw); /** - * Turn the wavelet representation back into an image. + * \brief Turn the wavelet representation back into an image. + * * Optionally, scale+offset factors can be supplied to * map the bitmap to a desired brightness */ @@ -71,7 +71,7 @@ public: void discard(Float fraction); /** - * Discard components such that the relative L^2-error is below the + * \brief Discard components such that the relative L^2-error is below the * given bound. Returns the achieved compression ratio. */ Float compress(Float maxError); @@ -122,7 +122,8 @@ protected: }; /** - * Implements the non-standard 3D wavelet transform using Haar basis functions. + * \brief Implements the non-standard 3D wavelet transform using + * Haar basis functions. */ class MTS_EXPORT_CORE Wavelet3D : public Object { public: @@ -134,7 +135,7 @@ public: Wavelet3D(const float *data, size_t resolution); /** - * Turn the wavelet representation back into a dense format + * \brief Turn the wavelet representation back into a dense format */ void decode(float *target); @@ -142,7 +143,7 @@ public: void discard(Float fraction); /** - * Discard components such that the relative L^2-error is below the + * \brief Discard components such that the relative L^2-error is below the * given bound. Returns the achieved compression ratio. */ Float compress(Float maxRelError); @@ -193,7 +194,7 @@ protected: }; /** - * Sparse 2D wavelet representation using the Haar basis + * \brief Sparse 2D wavelet representation using the Haar basis */ class MTS_EXPORT_CORE SparseWavelet2D : public SerializableObject { public: @@ -302,8 +303,9 @@ public: Float getPixel(const Point2i &pt) const; /** - * Compute a line integral in 2D wavelet space. Coordinates are - * expected as pixel coordinates in [0,0]-[size,size], + * \brief Compute a line integral in 2D wavelet space. + * + * Coordinates are expected as pixel coordinates in [0,0]-[size,size], * but are allowed to be fractional */ Float lineIntegral(Point2 start, Point2 end) const; @@ -329,7 +331,8 @@ protected: }; /** - * Sparse 3D wavelet representation using the Haar basis and an octree structure + * \brief Sparse 3D wavelet representation using the Haar basis and an + * octree structure */ class MTS_EXPORT_CORE SparseWaveletOctree : public Object { public: