/*
    This file is part of Mitsuba, a physically based rendering system.

    Copyright (c) 2007-2012 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 <http://www.gnu.org/licenses/>.
*/

#pragma once
#if !defined(__MITSUBA_RENDER_SCENE_H_)
#define __MITSUBA_RENDER_SCENE_H_

#include <mitsuba/core/netobject.h>
#include <mitsuba/core/pmf.h>
#include <mitsuba/core/aabb.h>
#include <mitsuba/render/trimesh.h>
#include <mitsuba/render/skdtree.h>
#include <mitsuba/render/sensor.h>
#include <mitsuba/render/integrator.h>
#include <mitsuba/render/bsdf.h>
#include <mitsuba/render/subsurface.h>
#include <mitsuba/render/texture.h>
#include <mitsuba/render/medium.h>
#include <mitsuba/render/volume.h>
#include <mitsuba/render/phase.h>

MTS_NAMESPACE_BEGIN

/**
 * \brief Principal scene data structure
 *
 * This class holds information on surfaces, emitters and participating media
 * and coordinates rendering jobs. It also provides useful query routines that
 * are mostly used by the \ref Integrator implementations.
 *
 * \ingroup librender
 * \ingroup libpython
 */
class MTS_EXPORT_RENDER Scene : public NetworkedObject {
public:
	// =============================================================
	//! @{ \name Initialization and rendering
	// =============================================================

	/// Construct a new, empty scene (with the default properties)
	Scene();

	/// Construct a new, empty scene
	Scene(const Properties &props);

	/// Create a shallow clone of a scene
	Scene(Scene *scene);

	/// Unserialize a scene from a binary data stream
	Scene(Stream *stream, InstanceManager *manager);

	/**
	 * \brief Initialize the scene
	 *
	 * This function \a must be called before using any
	 * of the methods in this class.
	 */
	void initialize();

	/**
	 * \brief Initialize the scene for bidirectional rendering algorithms.
	 *
	 * This ensures that certain "special" shapes (such as the aperture
	 * of the sensor) are added to the scene. This function should be called
	 * before using any of the methods in this class.
	 */
	void initializeBidirectional();

	/**
	 * \brief Perform any pre-processing steps before rendering
	 *
	 * This function should be called after \ref initialize() and
	 * before rendering the scene. It might do a variety of things,
	 * such as constructing photon maps or executing distributed overture
	 * passes.
	 *
	 * Progress is tracked by sending status messages to a provided
	 * render queue (the parameter \c job is required to discern multiple
	 * render jobs occurring in parallel).
	 *
	 * The last three parameters are resource IDs of the associated scene,
	 * sensor and sample generator, which have been made available to all
	 * local and remote workers.
	 *
	 * \return \c true upon successful completion.
	 */
	bool preprocess(RenderQueue *queue, const RenderJob *job,
		int sceneResID, int sensorResID, int samplerResID);

	/**
	 * \brief Render the scene as seen by the scene's main sensor.
	 *
	 * Progress is tracked by sending status messages to a provided
	 * render queue (the parameter \c job is required to discern multiple
	 * render jobs occurring in parallel).
	 *
	 * The last three parameters are resource IDs of the associated scene,
	 * sensor and sample generator, which have been made available to all
	 * local and remote workers.
	 *
	 * \return \c true upon successful completion.
	 */
	bool render(RenderQueue *queue, const RenderJob *job,
			int sceneResID, int sensorResID, int samplerResID);

	/**
	 * \brief Perform any post-processing steps after rendering
	 *
	 * Progress is tracked by sending status messages to a provided
	 * render queue (the parameter \c job is required to discern multiple
	 * render jobs occurring in parallel).
	 *
	 * The last three parameters are resource IDs of the associated scene,
	 * sensor and sample generator, which have been made available to all
	 * local and remote workers.
	 */
	void postprocess(RenderQueue *queue, const RenderJob *job,
		int sceneResID, int sensorResID, int samplerResID);

	/// Write out the current (partially rendered) image
	void flush();

	/**
	 * \brief Cancel a running rendering job
	 *
	 * This function can be called asynchronously, e.g. from a GUI.
	 * In this case, \ref render() will quit with a return value of
	 * \c false.
	 */
	void cancel();

	/// Add a child node to the scene
	void addChild(const std::string &name, ConfigurableObject *child);

	/// Add an unnamed child
	inline void addChild(ConfigurableObject *child) { addChild("", child); }

	/** \brief Configure this object (called \a once after construction
	   and addition of all child \ref ConfigurableObject instances).) */
	void configure();

	//! @}
	// =============================================================

	// =============================================================
	//! @{ \name Ray tracing
	// =============================================================

	/**
	 * \brief Intersect a ray against all primitives stored in the scene
	 * and return detailed intersection information
	 *
	 * \param ray
	 *    A 3-dimensional ray data structure with minimum/maximum
	 *    extent information, as well as a time value (which applies
	 *    when the shapes are in motion)
	 *
	 * \param its
	 *    A detailed intersection record, which will be filled by the
	 *    intersection query
	 *
	 * \return \c true if an intersection was found
	 */
	inline bool rayIntersect(const Ray &ray, Intersection &its) const {
		return m_kdtree->rayIntersect(ray, its);
	}

	/**
	 * \brief Intersect a ray against all primitives stored in the scene
	 * and return the traveled distance and intersected shape
	 *
	 * This function represents a performance improvement when the
	 * intersected shape must be known, but there is no need for
	 * a detailed intersection record.
	 *
	 * \param ray
	 *    A 3-dimensional ray data structure with minimum/maximum
	 *    extent information, as well as a time value (which applies
	 *    when the shapes are in motion)
	 *
	 * \param t
	 *    The traveled ray distance will be stored in this parameter

	 * \param shape
	 *    A pointer to the intersected shape will be stored in this
	 *    parameter
	 *
	 * \param n
	 *    The geometric surface normal will be stored in this parameter
	 *
	 * \param uv
	 *    The UV coordinates associated with the intersection will
	 *    be stored here.
	 *
	 * \return \c true if an intersection was found
	 */
	inline bool rayIntersect(const Ray &ray, Float &t,
			ConstShapePtr &shape, Normal &n, Point2 &uv) const {
		return m_kdtree->rayIntersect(ray, t, shape, n, uv);
	}

	/**
	 * \brief Intersect a ray against all primitives stored in the scene
	 * and \a only determine whether or not there is an intersection.
	 *
	 * This is by far the fastest ray tracing method. This performance
	 * improvement comes with a major limitation though: this function
	 * cannot provide any additional information about the detected
	 * intersection (not even its position).
	 *
	 * \param ray
	 *    A 3-dimensional ray data structure with minimum/maximum
	 *    extent information, as well as a time value (which applies
	 *    when the shapes are in motion)
	 *
	 * \return \c true if an intersection was found
	 */
	inline bool rayIntersect(const Ray &ray) const {
		return m_kdtree->rayIntersect(ray);
	}

	/**
	 * \brief Return the transmittance between \c p1 and \c p2 at the
	 * specified time.
	 *
	 * This function is essentially a continuous version of \ref isOccluded(),
	 * which additionally accounts for the presence of participating media
	 * and surface interactions that attenuate a ray without changing
	 * its direction (i.e. geometry with an alpha mask)
	 *
	 * The implementation correctly handles arbitrary amounts of index-matched
	 * medium transitions. The \c interactions parameter can be used to
	 * specify a maximum number of possible surface interactions and medium
	 * transitions between \c p1 and \c p2. When this number is exceeded,
	 * the function returns zero.
	 *
	 * Note that index-mismatched boundaries (i.e. a transition from air to
	 * water) are not supported by this function. The integrator needs to take
	 * care of these in some other way.
	 *
	 * \param p1
	 *     Source position
	 * \param p2
	 *     Target position
	 * \param p1OnSurface
	 *     Is the source position located on a surface? This information is
	 *     necessary to set up the right ray epsilons for the kd-tree traversal
	 * \param p2OnSurface
	 *     Is the target position located on a surface?
	 * \param medium
	 *     The medium at \c p1
	 * \param interactions
	 *    Specifies the maximum permissible number of index-matched medium
	 *    transitions or \ref BSDF::ENull scattering events on the way
	 *    to the light source. (<tt>interactions<0</tt> means arbitrarily many).
	 *    When the function returns a nonzero result, this parameter will
	 *    additionally be used to return the actual number of intermediate
	 *    interactions.
	 * \param time
	 *     Associated scene time value for the transmittance computation
	 * \param sampler
	 *     Optional: A sample generator. This may be used
	 *     to compute a random unbiased estimate of the transmission.
	 * \return An spectral-valued transmittance value with components
	 *     between zero and one.
	 */
	Spectrum evalTransmittance(const Point &p1, bool p1OnSurface,
		const Point &p2, bool p2OnSurface, Float time, const Medium *medium,
		int &interactions, Sampler *sampler = NULL) const;

	//! @}
	// =============================================================

	// =============================================================
	//! @{ \name Ray tracing support for bidirectional algorithms
	// =============================================================

	/**
	 * \brief Intersect a ray against all scene primitives \a and
	 * "special" primitives, such as the aperture of a sensor.
	 *
	 * This function does exactly the same thing as \ref rayIntersect,
	 * except that it additionally performs intersections against a
	 * list of "special" shapes that are intentionally kept outside
	 * of the main scene kd-tree (e.g. because they are not static
	 * and might change from rendering to rendering). This is needed
	 * by some bidirectional techniques that e.g. care about
	 * intersections with the sensor aperture.
	 *
	 * \param ray
	 *    A 3-dimensional ray data structure with minimum/maximum
	 *    extent information, as well as a time value (which applies
	 *    when the shapes are in motion)
	 *
	 * \param its
	 *    A detailed intersection record, which will be filled by the
	 *    intersection query
	 *
	 * \return \c true if an intersection was found
	 */
	bool rayIntersectAll(const Ray &ray, Intersection &its) const;

	/**
	 * \brief Intersect a ray against all normal and "special" primitives
	 * and only return the traveled distance and intersected shape
	 *
	 * This function represents a performance improvement when the
	 * intersected shape must be known, but there is no need for
	 * a detailed intersection record.
	 *
	 * This function does exactly the same thing as \ref rayIntersect,
	 * except that it additionally performs intersections against a
	 * list of "special" shapes that are intentionally kept outside
	 * of the main scene kd-tree (e.g. because they are not static
	 * and might change from rendering to rendering). This is needed
	 * by some bidirectional techniques that e.g. care about
	 * intersections with the sensor aperture.
	 *
	 * \param ray
	 *    A 3-dimensional ray data structure with minimum/maximum
	 *    extent information, as well as a time value (which applies
	 *    when the shapes are in motion)
	 *
	 * \param t
	 *    The traveled ray distance will be stored in this parameter

	 * \param shape
	 *    A pointer to the intersected shape will be stored in this
	 *    parameter
	 *
	 * \param n
	 *    The geometric surface normal will be stored in this parameter
	 *
	 * \param uv
	 *    The UV coordinates associated with the intersection will
	 *    be stored here.
	 *
	 * \return \c true if an intersection was found
	 */
	bool rayIntersectAll(const Ray &ray, Float &t,
			ConstShapePtr &shape, Normal &n, Point2 &uv) const;

	/**
	 * \brief Intersect a ray against all normal and "special" primitives
	 * and \a only determine whether or not there is an intersection.
	 *
	 * This is by far the fastest ray tracing method. This performance
	 * improvement comes with a major limitation though: this function
	 * cannot provide any additional information about the detected
	 * intersection (not even its position).
	 *
	 * This function does exactly the same thing as \ref rayIntersect,
	 * except that it additionally performs intersections against a
	 * list of "special" shapes that are intentionally kept outside
	 * of the main scene kd-tree (e.g. because they are not static
	 * and might change from rendering to rendering). This is needed
	 * by some bidirectional techniques that e.g. care about
	 * intersections with the sensor aperture.
	 *
	 * \param ray
	 *    A 3-dimensional ray data structure with minimum/maximum
	 *    extent information, as well as a time value (which applies
	 *    when the shapes are in motion)
	 *
	 * \return \c true if an intersection was found
	 */
	bool rayIntersectAll(const Ray &ray) const;

	/**
	 * \brief Return the transmittance between \c p1 and \c p2 at the
	 * specified time (and acount for "special" primitives).
	 *
	 * This function is essentially a continuous version of \ref isOccluded(),
	 * which additionally accounts for the presence of participating media
	 * and surface interactions that attenuate a ray without changing
	 * its direction (i.e. geometry with an alpha mask)
	 *
	 * The implementation correctly handles arbitrary amounts of index-matched
	 * medium transitions. The \c interactions parameter can be used to
	 * specify a maximum number of possible surface interactions and medium
	 * transitions between \c p1 and \c p2. When this number is exceeded,
	 * the function returns zero.
	 *
	 * Note that index-mismatched boundaries (i.e. a transition from air to
	 * water) are not supported by this function. The integrator needs to take
	 * care of these in some other way.
	 *
	 * This function does exactly the same thing as \ref evalTransmittance,
	 * except that it additionally performs intersections against a
	 * list of "special" shapes that are intentionally kept outside
	 * of the main scene kd-tree (e.g. because they are not static
	 * and might change from rendering to rendering). This is needed
	 * by some bidirectional techniques that care about intersections
	 * with the sensor aperture, etc.
	 *
	 * \param p1
	 *     Source position
	 * \param p2
	 *     Target position
	 * \param p1OnSurface
	 *     Is the source position located on a surface? This information is
	 *     necessary to set up the right ray epsilons for the kd-tree traversal
	 * \param p2OnSurface
	 *     Is the target position located on a surface?
	 * \param medium
	 *     The medium at \c p1
	 * \param interactions
	 *    Specifies the maximum permissible number of index-matched medium
	 *    transitions or \ref BSDF::ENull scattering events on the way
	 *    to the light source. (<tt>interactions<0</tt> means arbitrarily many).
	 *    When the function returns a nonzero result, this parameter will
	 *    additionally be used to return the actual number of intermediate
	 *    interactions.
	 * \param time
	 *     Associated scene time value for the transmittance computation
	 * \param sampler
	 *     Optional: A sample generator. This may be used
	 *     to compute a random unbiased estimate of the transmission.
	 * \return An spectral-valued transmittance value with components
	 *     between zero and one.
	 */
	Spectrum evalTransmittanceAll(const Point &p1, bool p1OnSurface,
		const Point &p2, bool p2OnSurface, Float time, const Medium *medium,
		int &interactions, Sampler *sampler = NULL) const;

	//! @}
	// =============================================================

	// =============================================================
	//! @{ \name Direct sampling techniques
	// =============================================================

	/**
	 * \brief Direct illumination sampling routine
	 *
	 * Given an arbitrary reference point in the scene, this method samples a
	 * position on an emitter that has a nonzero contribution towards that point.
	 *
	 * Ideally, the implementation should importance sample the product of
	 * the emission profile and the geometry term between the reference point
	 * and the position on the emitter.
	 *
	 * \param dRec
	 *    A direct illumination sampling record that specifies the
	 *    reference point and a time value. After the function terminates,
	 *    it will be populated with the position sample and related information
	 *
	 * \param sample
	 *    A uniformly distributed 2D vector
	 *
	 * \param testVisibility
	 *    When set to \c true, a shadow ray will be cast to ensure that the
	 *    sampled emitter position and the reference point are mutually visible.
	 *
	 * \return
	 *    An importance weight given by the radiance received along
	 *    the sampled ray divided by the sample probability.
	 */
	Spectrum sampleEmitterDirect(DirectSamplingRecord &dRec,
			const Point2 &sample, bool testVisibility = true) const;

	/**
	 * \brief "Direct illumination" sampling routine for the main scene sensor
	 *
	 * Given an arbitrary reference point in the scene, this method samples a
	 * position on an sensor that has a nonzero contribution towards that point.
	 * This function can be interpreted as a generalization of a direct
	 * illumination sampling strategy to sensors.
	 *
	 * Ideally, the implementation should importance sample the product of
	 * the response profile and the geometry term between the reference point
	 * and the position on the emitter.
	 *
	 * \param dRec
	 *    A direct illumination sampling record that specifies the
	 *    reference point and a time value. After the function terminates,
	 *    it will be populated with the position sample and related information
	 *
	 * \param sample
	 *    A uniformly distributed 2D vector
	 *
	 * \param testVisibility
	 *    When set to \c true, a shadow ray will be cast to ensure that the
	 *    sampled sensor position and the reference point are mutually visible.
	 *
	 * \return
	 *    An importance weight given by the importance emitted along
	 *    the sampled ray divided by the sample probability.
	 */
	Spectrum sampleSensorDirect(DirectSamplingRecord &dRec,
			const Point2 &sample, bool testVisibility = true) const;

	/**
	 * \brief Direct illumination sampling with support for participating
	 * media (medium variant)
	 *
	 * Given an arbitrary reference point in the scene, this method samples a
	 * position on an emitter that has a nonzero contribution towards that point.
	 * In comparison to \ref sampleEmitterDirect, this version also accounts for
	 * attenuation by participating media and should be used when \c dRec.p
	 * lies \a inside a medium, i.e. \a not on a surface!
	 *
	 * Ideally, the implementation should importance sample the product of
	 * the emission profile and the geometry term between the reference point
	 * and the position on the emitter.
	 *
	 * \param dRec
	 *    A direct illumination sampling record that specifies the
	 *    reference point and a time value. After the function terminates,
	 *    it will be populated with the position sample and related information
	 *
	 * \param medium
	 *    The medium located at the reference point (or \c NULL for vacuum).
	 *
	 * \param interactions
	 *    Specifies the maximum permissible number of index-matched medium
	 *    transitions or \ref BSDF::ENull scattering events on the way
	 *    to the light source. (<tt>interactions<0</tt> means arbitrarily many).
	 *    When the function returns a nonzero result, this parameter will
	 *    additionally be used to return the actual number of intermediate
	 *    interactions.
	 *
	 * \param sample
	 *    A uniformly distributed 2D vector
	 *
	 * \param sampler
	 *    Optional: a pointer to a sample generator. Some particular
	 *    implementations can do a better job at sampling when they have
	 *    access to additional random numbers.
	 *
	 * \return
	 *    An importance weight given by the radiance received along
	 *    the sampled ray divided by the sample probability.
	 */
	Spectrum sampleAttenuatedEmitterDirect(DirectSamplingRecord &dRec,
			const Medium *medium, int &interactions, const Point2 &sample,
			Sampler *sampler = NULL) const;

	/**
	 * \brief "Direct illumination" sampling routine for the main scene sensor
	 * with support for participating media (medium variant)
	 *
	 * Given an arbitrary reference point in the scene, this method samples a
	 * position on an sensor that has a nonzero response towards that point.
	 * In comparison to \ref sampleSensorDirect, this version also accounts for
	 * attenuation by participating media and should be used when \c dRec.p
	 * lies \a inside a medium, i.e. \a not on a surface!
	 * This function can be interpreted as a generalization of a direct
	 * illumination sampling strategy to sensors.
	 *
	 * Ideally, the implementation should importance sample the product of
	 * the response profile and the geometry term between the reference point
	 * and the position on the sensor.
	 *
	 * \param dRec
	 *    A direct illumination sampling record that specifies the
	 *    reference point and a time value. After the function terminates,
	 *    it will be populated with the position sample and related information
	 *
	 * \param medium
	 *    The medium located at the reference point (or \c NULL for vacuum).
	 *
	 * \param interactions
	 *    Specifies the maximum permissible number of index-matched medium
	 *    transitions or \ref BSDF::ENull scattering events on the way
	 *    to the light source. (<tt>interactions<0</tt> means arbitrarily many).
	 *    When the function returns a nonzero result, this parameter will
	 *    additionally be used to return the actual number of intermediate
	 *    interactions.
	 *
	 * \param sample
	 *    A uniformly distributed 2D vector
	 *
	 * \param sampler
	 *    Optional: a pointer to a sample generator. Some particular
	 *    implementations can do a better job at sampling when they have
	 *    access to additional random numbers.
	 *
	 * \return
	 *    An importance weight given by the radiance received along
	 *    the sampled ray divided by the sample probability.
	 */
	Spectrum sampleAttenuatedSensorDirect(DirectSamplingRecord &dRec,
			const Medium *medium, int &interactions, const Point2 &sample,
			Sampler *sampler = NULL) const;

	/**
	 * \brief Direct illumination sampling with support for participating
	 * media (surface variant)
	 *
	 * Given an arbitrary reference point in the scene, this method samples a
	 * position on an emitter that has a nonzero contribution towards that point.
	 * In comparison to \ref sampleEmitterDirect, this version also accounts for
	 * attenuation by participating media and should be used when the target
	 * position lies on a surface.
	 *
	 * Ideally, the implementation should importance sample the product of
	 * the emission profile and the geometry term between the reference point
	 * and the position on the emitter.
	 *
	 * \param dRec
	 *    A direct illumination sampling record that specifies the
	 *    reference point and a time value. After the function terminates,
	 *    it will be populated with the position sample and related information
	 *
	 * \param its
	 *    An intersection record associated with the reference point in
	 *    \c dRec. This record is needed to determine the participating
	 *    medium between the emitter sample and the reference point
	 *    when \c its marks a medium transition.
	 *
	 * \param medium
	 *    The medium located at \c its (or \c NULL for vacuum). When the shape
	 *    associated with \c its marks a medium transition, it does not matter
	 *    which of the two media is specified.
	 *
	 * \param interactions
	 *    Specifies the maximum permissible number of index-matched medium
	 *    transitions or \ref BSDF::ENull scattering events on the way
	 *    to the light source. (<tt>interactions<0</tt> means arbitrarily many).
	 *    When the function returns a nonzero result, this parameter will
	 *    additionally be used to return the actual number of intermediate
	 *    interactions.
	 *
	 * \param sample
	 *    A uniformly distributed 2D vector
	 *
	 * \param sampler
	 *    Optional: a pointer to a sample generator. Some particular
	 *    implementations can do a better job at sampling when they have
	 *    access to additional random numbers.
	 *
	 * \return
	 *    An importance weight given by the radiance received along
	 *    the sampled ray divided by the sample probability.
	 */
	Spectrum sampleAttenuatedEmitterDirect(DirectSamplingRecord &dRec,
			const Intersection &its, const Medium *medium, int &interactions,
			const Point2 &sample, Sampler *sampler = NULL) const;

	/**
	 * \brief "Direct illumination" sampling routine for the main scene sensor
	 * with support for participating media (surface variant)
	 *
	 * Given an arbitrary reference point in the scene, this method samples a
	 * position on an sensor that has a nonzero response towards that point.
	 * In comparison to \ref sampleSensorDirect, this version also accounts for
	 * attenuation by participating media and should be used when the target
	 * position lies on a surface.
	 *
	 * Ideally, the implementation should importance sample the product of
	 * the emission profile and the geometry term between the reference point
	 * and the position on the sensor.
	 *
	 * \param dRec
	 *    A direct illumination sampling record that specifies the
	 *    reference point and a time value. After the function terminates,
	 *    it will be populated with the position sample and related information
	 *
	 * \param its
	 *    An intersection record associated with the reference point in
	 *    \c dRec. This record is needed to determine the participating
	 *    medium between the sensor sample and the reference point
	 *    when \c its marks a medium transition.
	 *
	 * \param medium
	 *    The medium located at \c its (or \c NULL for vacuum). When the shape
	 *    associated with \c its marks a medium transition, it does not matter
	 *    which of the two media is specified.
	 *
	 * \param interactions
	 *    Specifies the maximum permissible number of index-matched medium
	 *    transitions or \ref BSDF::ENull scattering events on the way
	 *    to the light source. (<tt>interactions<0</tt> means arbitrarily many).
	 *    When the function returns a nonzero result, this parameter will
	 *    additionally be used to return the actual number of intermediate
	 *    interactions.
	 *
	 * \param sample
	 *    A uniformly distributed 2D vector
	 *
	 * \param sampler
	 *    Optional: a pointer to a sample generator. Some particular
	 *    implementations can do a better job at sampling when they have
	 *    access to additional random numbers.
	 *
	 * \return
	 *    An importance weight given by the radiance received along
	 *    the sampled ray divided by the sample probability.
	 */
	Spectrum sampleAttenuatedSensorDirect(DirectSamplingRecord &dRec,
			const Intersection &its, const Medium *medium, int &interactions,
			const Point2 &sample, Sampler *sampler = NULL) const;

	/**
	 * \brief Evaluate the probability density of the \a direct sampling
	 * method implemented by the \ref sampleEmitterDirect() method.
	 *
	 * \param dRec
	 *    A direct sampling record, which specifies the query
	 *    location. Note that this record need not be completely
	 *    filled out. The important fields are \c p, \c n, \c ref,
	 *    \c dist, \c d, \c measure, and \c uv.
	 *
	 * \param p
	 *    The world-space position that would have been passed to \ref
	 *    sampleEmitterDirect()
	 *
	 * \return
	 *    The density expressed with respect to the requested measure
	 *    (usually \ref ESolidAngle)
	 */
	Float pdfEmitterDirect(const DirectSamplingRecord &dRec) const;

	/**
	 * \brief Evaluate the probability density of the \a direct sampling
	 * method implemented by the \ref sampleSensorDirect() method.
	 *
	 * \param dRec
	 *    A direct sampling record, which specifies the query
	 *    location. Note that this record need not be completely
	 *    filled out. The important fields are \c p, \c n, \c ref,
	 *    \c dist, \c d, \c measure, and \c uv.
	 *
	 * \param p
	 *    The world-space position that would have been passed to \ref
	 *    sampleSensorDirect()
	 *
	 * \return
	 *    The density expressed with respect to the requested measure
	 *    (usually \ref ESolidAngle)
	 */
	Float pdfSensorDirect(const DirectSamplingRecord &dRec) const;

	//! @}
	// =============================================================

	// =============================================================
	//! @{ \name Emission sampling techniques
	// =============================================================

	/**
	 * \brief Sample a position according to the emission profile
	 * defined by the emitters in the scene.
	 *
	 * To sample the directional component, please use the
	 * \ref Emitter::sampleDirection() method.
	 *
	 * \param pRec
	 *    A position record to be populated with the sampled
	 *    position and related information
	 *
	 * \param sample
	 *    A uniformly distributed 2D vector
	 *
	 * \return
	 *    An importance weight associated with the sampled position.
	 *    This accounts for the difference in the spatial part of the
	 *    emission profile and the density function.
	 */
	Spectrum sampleEmitterPosition(PositionSamplingRecord &pRec,
		const Point2 &sample) const;

	/**
	 * \brief Sample a position on the main sensor of the scene.
	 *
	 * This function is provided here mainly for symmetry
	 * with respect to \ref sampleEmitterPosition().
	 *
	 * To sample the directional component, please use the
	 * \ref Sensor::sampleDirection() method.
	 *
	 * \param pRec
	 *    A position record to be populated with the sampled
	 *    position and related information
	 *
	 * \param sample
	 *    A uniformly distributed 2D vector
	 *
	 * \param extra
	 *    An additional 2D vector provided to the sampling
	 *    routine -- its use is implementation-dependent.
	 *
	 * \return
	 *    An importance weight associated with the sampled position.
	 *    This accounts for the difference in the spatial part of the
	 *    response profile and the density function.
	 */
	inline Spectrum sampleSensorPosition(PositionSamplingRecord &pRec,
		const Point2 &sample, const Point2 *extra = NULL) const {
		pRec.object = m_sensor.get();
		return m_sensor->samplePosition(pRec, sample, extra);
	}

	/**
	 * \brief Evaluate the spatial component of the sampling density
	 * implemented by the \ref sampleEmitterPosition() method
	 *
	 * \param pRec
	 *    A position sampling record, which specifies the query location
	 *
	 * \return
	 *    The area density at the supplied position
	 */
	Float pdfEmitterPosition(const PositionSamplingRecord &pRec) const;

	/**
	 * \brief Evaluate the spatial component of the sampling density
	 * implemented by the \ref sampleSensorPosition() method
	 *
	 * \param pRec
	 *    A position sampling record, which specifies the query location
	 *
	 * \return
	 *    The area density at the supplied position
	 */
	inline Float pdfSensorPosition(const PositionSamplingRecord &pRec) const {
		return m_sensor->pdfPosition(pRec);
	}

	/**
	 * \brief Return the discrete probability of choosing a
	 * certain emitter in <tt>sampleEmitter*</tt>
	 */
	inline Float pdfEmitterDiscrete(const Emitter *emitter) const {
		return emitter->getSamplingWeight() * m_emitterPDF.getNormalization();
	}

	/**
	 * \brief Sample a position according to the emission profile
	 * defined by the emitters in the scene.
	 *
	 * To sample the directional component, please use the
	 * \ref Emitter::sampleDirection() method.
	 *
	 * \param pRec
	 *    A position record to be populated with the sampled
	 *    position and related information
	 *
	 * \param sample
	 *    A uniformly distributed 2D vector
	 *
	 * \return
	 *    An importance weight associated with the sampled position.
	 *    This accounts for the difference in the spatial part of the
	 *    emission profile and the density function.
	 */
 	/**
	 * \brief Importance sample a ray according to the emission profile
	 * defined by the sensors in the scene
	 *
	 * This function combines both steps of choosing a ray origin and
	 * direction value. It does not return any auxiliary sampling
	 * information and is mainly meant to be used by unidirectional
	 * rendering techniques.
	 *
	 * Note that this function potentially uses a different sampling
	 * strategy compared to the sequence of running \ref sampleEmitterPosition()
	 * and \ref Emitter::sampleDirection(). The reason for this is that it may
	 * be possible to switch to a better technique when sampling both
	 * position and direction at the same time.
	 *
	 * \param ray
	 *    A ray data structure to be populated with a position
	 *    and direction value
	 *
	 * \param spatialSample
	 *    Denotes the sample that is used to choose the spatial component
	 *
	 * \param directionalSample
	 *    Denotes the sample that is used to choose the directional component
	 *
	 * \param time
	 *    Scene time value to be associated with the sample
	 *
	 * \return
	 *    An importance weight associated with the sampled ray.
	 *    This accounts for the difference between the emission profile
	 *    and the sampling density function.
	 */
	Spectrum sampleEmitterRay(Ray &ray,
		const Emitter* &emitter,
		const Point2 &spatialSample,
		const Point2 &directionalSample,
		Float time) const;

	//! @}
	// =============================================================

	// =============================================================
	//! @{ \name Environment emitters
	// =============================================================

	/// Return the scene's environment emitter (if there is one)
	inline const Emitter *getEnvironmentEmitter() const { return m_environmentEmitter.get(); }

	/// Does the scene have a environment emitter?
	inline bool hasEnvironmentEmitter() const { return m_environmentEmitter.get() != NULL; }

	/**
	 * \brief Return the environment radiance for a ray that did not intersect
	 * any of the scene objects.
	 *
	 * This is primarily meant for path tracing-style integrators.
	 */
	inline Spectrum evalEnvironment(const RayDifferential &ray) const {
		return hasEnvironmentEmitter() ?
			m_environmentEmitter->evalEnvironment(ray) : Spectrum(0.0f);
	}

	/**
	 * \brief Return the environment radiance for a ray that did not intersect
	 * any of the scene objects. This method additionally considers
	 * transmittance by participating media
	 *
	 * This is primarily meant for path tracing-style integrators.
	 */
	inline Spectrum evalAttenuatedEnvironment(const RayDifferential &ray,
			const Medium *medium, Sampler *sampler) const {
		if (!m_environmentEmitter)
			return Spectrum(0.0f);
		Spectrum result = evalEnvironment(ray);
		if (medium)
			result *= medium->evalTransmittance(ray, sampler);
		return result;
	}

	//! @}
	// =============================================================

	// =============================================================
	//! @{ \name Miscellaneous
	// =============================================================

	/// Return an axis-aligned bounding box containing the whole scene
	inline const AABB &getAABB() const {
		return m_aabb;
	}

	/**
	 * \brief Is the main scene sensor degenerate?  (i.e. has it
	 * collapsed to a point or line)
	 *
	 * Note that this function only cares about the spatial component
	 * of the sensor -- its value does not depend on whether the directional
	 * response function is degenerate.
	 */
	inline bool hasDegenerateSensor() const { return m_degenerateSensor; }

	/**
	 * \brief Area \a all emitters in this scene degenerate?
	 * (i.e. they has collapsed to a point or line)
	 *
	 * Note that this function only cares about the spatial component
	 * of the emitters -- its value does not depend on whether the
	 * directional emission profile is degenerate.
	 */
	inline bool hasDegenerateEmitters() const { return m_degenerateEmitters; }

	/// Return a bounding sphere containing the whole scene
	inline BSphere getBSphere() const {
		// todo: switch to something smarter at some point
		return m_aabb.getBSphere();
	}

	/// Does the scene contain participating media?
	inline bool hasMedia() const { return !m_media.empty(); }

	/**
	 * \brief Set the main scene sensor.
	 *
	 * Note that the main sensor is not included when this Scene instance
	 * is serialized -- the sensor field will be \c NULL after
	 * unserialization. This is intentional so that the sensor can
	 * be changed without having to re-transmit the whole scene.
	 * Hence, it needs to be submitted separately and re-attached
	 * on the remote side using \ref setSensor().
	 **/
	void setSensor(Sensor *sensor);

	/// \brief Remove a sensor from the scene's sensor list
	void removeSensor(Sensor *sensor);

	/// \brief Add a sensor to the scene's sensor list
	void addSensor(Sensor *sensor);

	/// Return the scene's sensor
	inline Sensor *getSensor() { return m_sensor; }

	/// Return the scene's sensor (const version)
	inline const Sensor *getSensor() const { return m_sensor.get(); }

	/**
	 * \brief Return the list of sensors that are specified
	 * by the scene.
	 *
	 * As scene can have multiple sensors -- however, during
	 * a rendering, there will always be one "main" sensor that
	 * is currently active.
	 *
	 * \sa getSensor
	 */
	inline ref_vector<Sensor> &getSensors() { return m_sensors; }

	/**
	 * \brief Return the list of sensors that are specified
	 * by the scene (const version)
	 *
	 * As scene can have multiple sensors -- however, during
	 * a rendering, there will always be one "main" sensor that
	 * is currently active.
	 *
	 * \sa getSensor
	 */
	inline const ref_vector<Sensor> &getSensors() const { return m_sensors; }

	/**
	 * \brief Set the scene's integrator.
	 *
	 * Note that the integrator is not included when this Scene instance
	 * is serialized -- the integrator field will be \c NULL after
	 * unserialization. This is intentional so that the integrator can
	 * be changed without having to re-transmit the whole scene. Hence,
	 * the integrator needs to be submitted separately and re-attached
	 * on the remote side using \ref setIntegrator().
	 **/
	inline void setIntegrator(Integrator *integrator) { m_integrator = integrator; }

	/// Return the scene's integrator
	inline Integrator *getIntegrator() { return m_integrator; }
	/// Return the scene's integrator (const version)
	inline const Integrator *getIntegrator() const { return m_integrator.get(); }

	/**
	 * \brief Set the scene's sampler.
	 *
	 * Note that the sampler is not included when this Scene instance
	 * is serialized -- the sampler field will be \c NULL after
	 * unserialization. This is intentional so that the sampler can
	 * be changed without having to re-transmit the whole scene.
	 * Hence, the sampler needs to be submitted separately
	 * and re-attached on the remote side using \ref setSampler().
	 **/
	inline void setSampler(Sampler *sampler) { m_sampler = sampler; }

	/**
	 * \brief 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 sensor.
	 */
	inline Sampler *getSampler() { return m_sampler; }
	/// Return the scene's sampler
	inline const Sampler *getSampler() const { return m_sampler.get(); }

	/// Return the scene's film
	inline Film *getFilm() { return m_sensor->getFilm(); }
	/// Return the scene's film
	inline const Film *getFilm() const { return m_sensor->getFilm(); }

	/// Return the scene's kd-tree accelerator
	inline ShapeKDTree *getKDTree() { return m_kdtree; }
	/// Return the scene's kd-tree accelerator
	inline const ShapeKDTree *getKDTree() const { return m_kdtree.get(); }

	/// Return the a list of all subsurface integrators
	inline ref_vector<Subsurface> &getSubsurfaceIntegrators() { return m_ssIntegrators; }
	/// Return the a list of all subsurface integrators
	inline const ref_vector<Subsurface> &getSubsurfaceIntegrators() const { return m_ssIntegrators; }

	/// Return the scene's triangular meshes (a subset of \ref getShapes())
	inline std::vector<TriMesh *> &getMeshes() { return m_meshes; }
	/// Return the scene's triangular meshes (a subset of \ref getShapes())
	inline const std::vector<TriMesh *> &getMeshes() const { return m_meshes; }
	/// Return the scene's normal shapes (including triangular meshes)
	inline ref_vector<Shape> &getShapes() { return m_shapes; }
	/// Return the scene's normal shapes (including triangular meshes)
	inline const ref_vector<Shape> &getShapes() const { return m_shapes; }

	/**
	 * \brief Return the scene's shapes (including triangular meshes)
	 */
	inline ref_vector<Shape> &getSpecialShapes() { return m_specialShapes; }
	/// Return the scene's shapes (including triangular meshes)
	inline const ref_vector<Shape> &getSpecialShapes() const { return m_specialShapes; }

	/// Return the scene's emitters
	inline ref_vector<Emitter> &getEmitters() { return m_emitters; }
	/// Return the scene's emitters
	inline const ref_vector<Emitter> &getEmitters() const { return m_emitters; }
	/// Return the scene's participating media
	inline ref_vector<Medium> &getMedia() { return m_media; }
	/// Return the scene's participating media
	inline const ref_vector<Medium> &getMedia() const { return m_media; }
	/// Return referenced objects (such as textures, BSDFs)
	inline ref_vector<ConfigurableObject> &getReferencedObjects() { return m_objects; }
	/// Return referenced objects (such as textures, BSDFs)
	inline const ref_vector<ConfigurableObject> &getReferencedObjects() const { return m_objects; }

	/// Return the name of the file containing the original description of this scene
	inline const fs::path &getSourceFile() const { return *m_sourceFile; }
	/// Set the name of the file containing the original description of this scene
	void setSourceFile(const fs::path &name);
	/// Return the render output filename
	inline const fs::path &getDestinationFile() const { return *m_destinationFile; }
	/// Set the render output filename
	void setDestinationFile(const fs::path &name);

	/// Does the destination file already exist?
	inline bool destinationExists() const { return m_sensor->getFilm()->destinationExists(*m_destinationFile); }

	/// Set the block resolution used to split images into parallel workloads
	inline void setBlockSize(uint32_t size) { m_blockSize = size; }
	/// Return the block resolution used to split images into parallel workloads
	inline uint32_t getBlockSize() const { return m_blockSize; }

	/// Serialize the whole scene to a network/file stream
	void serialize(Stream *stream, InstanceManager *manager) const;

	/* NetworkedObject implementation */
	void bindUsedResources(ParallelProcess *proc) const;
	void wakeup(ConfigurableObject *parent,
		std::map<std::string, SerializableObject *> &params);

	/// Return a string representation
	std::string toString() const;

	//! @}
	// =============================================================

	MTS_DECLARE_CLASS()
protected:
	/// Virtual destructor
	virtual ~Scene();

	/// \cond
	/// Add a shape to the scene
	void addShape(Shape *shape);
	/// \endcond
private:
	ref<ShapeKDTree> m_kdtree;
	ref<Sensor> m_sensor;
	ref<Integrator> m_integrator;
	ref<Sampler> m_sampler;
	ref<Emitter> m_environmentEmitter;
	ref_vector<Shape> m_shapes;
	ref_vector<Shape> m_specialShapes;
	ref_vector<Sensor> m_sensors;
	ref_vector<Emitter> m_emitters;
	ref_vector<ConfigurableObject> m_objects;
	ref_vector<NetworkedObject> m_netObjects;
	ref_vector<Subsurface> m_ssIntegrators;
	ref_vector<Medium> m_media;
	std::vector<TriMesh *> m_meshes;
	fs::path *m_sourceFile;
	fs::path *m_destinationFile;
	DiscreteDistribution m_emitterPDF;
	AABB m_aabb;
	uint32_t m_blockSize;
	bool m_degenerateSensor;
	bool m_degenerateEmitters;
};

MTS_NAMESPACE_END

#include <mitsuba/render/records.inl>

#endif /* __MITSUBA_RENDER_SCENE_H_ */