further documentation updates

include/mitsuba/render/camera.h

@@ -59,15 +59,27 @@ public:
 	 */
 	virtual Float areaDensity(const Point2 &p) const = 0;
 
-	/// Return the camera's sampler
+	/**
-	inline Sampler *getSamplerX() { return m_sampler; }
+	 * \brief Return the camera's sampler.
+	 *
+	 * This is the 'root' sampler, which will later be cloned a 
+	 * number of times to provide each participating worker thread 
+	 * with its own instance (see \ref Scene::getSampler()). 
+	 * Therefore, this sampler should never be used for anything 
+	 * except creating clones.
+	 */
+	inline Sampler *getSampler() { return m_sampler; }
 
 	/**
-	 * Return the camera's sampler. This is the 'root' sampler,
+	 * \brief Return the camera's sampler.
-	 * which will later be replicated for submission to all
+	 *
-	 * participating workers.
+	 * This is the 'root' sampler, which will later be cloned a 
+	 * number of times to provide each participating worker thread 
+	 * with its own instance (see \ref Scene::getSampler()). 
+	 * Therefore, this sampler should never be used for anything 
+	 * except creating clones.
 	 */
-	inline const Sampler *getSamplerX() const { return m_sampler.get(); }
+	inline const Sampler *getSampler() const { return m_sampler.get(); }
 
 	/// Return the image plane normal
 	inline Normal getImagePlaneNormal() const {

include/mitsuba/render/scene.h

@@ -325,7 +325,15 @@ public:
 	 * and re-attached on the remote side using <tt>setSampler</tt>.
 	 **/
 	inline void setSampler(Sampler *sampler) { m_sampler = sampler; }
-	/// Return the scene's sampler
+
+	/**
+	 * Return the scene's sampler. Note that when rendering using multiple
+	 * different threads, each thread will be passed a shallow copy of the
+	 * scene, which has a different sampler instance. This helps to avoid 
+	 * locking/contention issues and ensures that different threads render 
+	 * with different random number sequences. The sampler instance provided
+	 * here is a clone of the original sampler specified in the camera.
+	 */
 	inline Sampler *getSampler() { return m_sampler; }
 	/// Return the scene's sampler
 	inline const Sampler *getSampler() const { return m_sampler.get(); }

src/librender/scene.cpp

@@ -244,7 +244,7 @@ void Scene::configure() {
 
 		m_camera = static_cast<Camera *> (PluginManager::getInstance()->createObject(Camera::m_theClass, props));
 		m_camera->configure();
-		m_sampler = m_camera->getSamplerX();
+		m_sampler = m_camera->getSampler();
 	}
 
 	if (m_media.size() > 1)
@@ -503,7 +503,7 @@ void Scene::addChild(const std::string &name, ConfigurableObject *child) {
 	if (cClass->derivesFrom(Camera::m_theClass)) {
 		AssertEx(m_camera == NULL, "There can only be one camera per scene");
 		m_camera = static_cast<Camera *>(child);
-		m_sampler = m_camera->getSamplerX();
+		m_sampler = m_camera->getSampler();
 	} else if (cClass->derivesFrom(Integrator::m_theClass)) {
 		AssertEx(m_integrator == NULL, "There can only be one integrator per scene");
 		m_integrator = static_cast<Integrator *>(child);