Abstract radiance/importance emitter interface. More...

#include <mitsuba/render/emitter.h>

Inheritance diagram for mitsuba::AbstractEmitter:

Public Types
enum	EEmitterType { EDeltaDirection = 0x01, EDeltaPosition = 0x02, EOnSurface = 0x04 }
	Flags used to classify the emission profile of different types of emitters. More...

Public Member Functions
virtual const Class *	getClass () const
	Retrieve this object's class. More...

Sampling interface
virtual Spectrum	samplePosition (PositionSamplingRecord &pRec, const Point2 &sample, const Point2 *extra=NULL) const
	Importance sample the spatial component of the emission profile. More...

virtual Spectrum	sampleDirection (DirectionSamplingRecord &dRec, PositionSamplingRecord &pRec, const Point2 &sample, const Point2 *extra=NULL) const
	Conditioned on the spatial component, importance sample the directional part of the emission profile. More...

virtual Spectrum	sampleDirect (DirectSamplingRecord &dRec, const Point2 &sample) const
	Direct sampling: given a reference point in the scene, sample an emitter position that contributes towards it. More...

Query functions for the emission profile and
sampling density functions
virtual Spectrum	evalPosition (const PositionSamplingRecord &pRec) const
	Evaluate the spatial component of the emission profile. More...

virtual Spectrum	evalDirection (const DirectionSamplingRecord &dRec, const PositionSamplingRecord &pRec) const
	Evaluate the directional component of the emission profile. More...

virtual Float	pdfPosition (const PositionSamplingRecord &pRec) const
	Evaluate the spatial component of the sampling density implemented by the samplePosition() method. More...

virtual Float	pdfDirection (const DirectionSamplingRecord &dRec, const PositionSamplingRecord &pRec) const
	Evaluate the directional component of the sampling density implemented by the sampleDirection() method. More...

virtual Float	pdfDirect (const DirectSamplingRecord &dRec) const
	Evaluate the probability density of the direct sampling method implemented by the sampleDirect() method. More...

Other query functions
uint32_t	getType () const
	Return a listing of classification flags combined using binary OR. More...

const AnimatedTransform *	getWorldTransform () const
	Return the local space to world space transformation. More...

void	setWorldTransform (AnimatedTransform *trafo)
	Set the local space to world space transformation. More...

bool	needsPositionSample () const
	Does the method samplePosition() require a uniformly distributed sample for the spatial component? More...

bool	needsDirectionSample () const
	Does the method sampleDirection() require a uniformly distributed sample for the direction component? More...

bool	isOnSurface () const
	Does the emitter lie on some kind of surface? More...

bool	isDegenerate () const
	Does the sensor have a degenerate directional or spatial distribution? More...

bool	needsDirectSample () const
	Does the method sampleDirect() require a uniformly distributed sample? More...

EMeasure	getDirectMeasure () const
	Return the measure associated with the sampleDirect() operation. More...

Miscellaneous
Medium *	getMedium ()
	Return a pointer to the medium that surrounds the emitter. More...

const Medium *	getMedium () const
	Return a pointer to the medium that surrounds the emitter (const version) More...

Shape *	getShape ()
	Return the shape, to which the emitter is currently attached. More...

const Shape *	getShape () const
	Return the shape, to which the emitter is currently attached (const version) More...

virtual ref< Shape >	createShape (const Scene *scene)
	Create a special shape that represents the emitter. More...

virtual AABB	getAABB () const =0
	Return an axis-aligned box bounding the spatial extents of the emitter. More...

void	setMedium (Medium *medium)
	Set the medium that surrounds the emitter. More...

virtual void	serialize (Stream stream, InstanceManager manager) const
	Serialize this emitter to a binary data stream. More...

ConfigurableObject interface
virtual void	addChild (const std::string &name, ConfigurableObject *child)
	Add a child ConfigurableObject. More...

void	addChild (ConfigurableObject *child)
	Add an unnamed child. More...

Public Member Functions inherited from mitsuba::ConfigurableObject
virtual void	setParent (ConfigurableObject *parent)
	Notify the ConfigurableObject instance about its parent object. More...

void	addChild (ConfigurableObject *child)
	Add an unnamed child. More...

virtual void	configure ()
	Configure the object (called once after construction and addition of all child ConfigurableObject instances)) More...

const std::string &	getID () const
	Return the identifier associated with this instance (or "unnamed") More...

void	setID (const std::string &name)
	Set the identifier associated with this instance. More...

const Properties &	getProperties () const
	Return the properties object that was originally used to create this instance. More...

Public Member Functions inherited from mitsuba::SerializableObject
	SerializableObject (Stream stream, InstanceManager manager)
	Unserialize a serializable object. More...

Public Member Functions inherited from Object
	Object ()
	Construct a new object. More...

int	getRefCount () const
	Return the current reference count. More...

void	incRef () const
	Increase the reference count of the object by one. More...

void	decRef (bool autoDeallocate=true) const
	Decrease the reference count of the object and possibly deallocate it. More...

virtual std::string	toString () const
	Return a human-readable string representation of the object's contents. More...

Static Public Attributes
static Class *	m_theClass

Static Public Attributes inherited from mitsuba::ConfigurableObject
static Class *	m_theClass

Static Public Attributes inherited from mitsuba::SerializableObject
static Class *	m_theClass

Static Public Attributes inherited from Object
static Class *	m_theClass
	Pointer to the object's class descriptor. More...

Protected Member Functions
	AbstractEmitter (const Properties &props)
	Construct a new emitter instance. More...

	AbstractEmitter (Stream stream, InstanceManager manager)
	Unserialize a emitter instance from a binary data stream. More...

virtual	~AbstractEmitter ()
	Virtual destructor. More...

Protected Member Functions inherited from mitsuba::ConfigurableObject
virtual	~ConfigurableObject ()
	Virtual destructor. More...

	ConfigurableObject (const Properties &props)
	Construct a configurable object. More...

	ConfigurableObject (Stream stream, InstanceManager manager)
	Unserialize a configurable object. More...

Protected Member Functions inherited from mitsuba::SerializableObject
	SerializableObject ()
	Construct a serializable object. More...

virtual	~SerializableObject ()
	Virtual deconstructor. More...

Protected Member Functions inherited from Object
virtual	~Object ()
	Virtual private deconstructor. (Will only be called by ref) More...

Protected Attributes
ref< const AnimatedTransform >	m_worldTransform

ref< Medium >	m_medium

Shape *	m_shape

uint32_t	m_type

Protected Attributes inherited from mitsuba::ConfigurableObject
Properties	m_properties

Additional Inherited Members
Static Public Member Functions inherited from Object
static void	staticInitialization ()
	Initializes the built-in reference count debugger (if enabled) More...

static void	staticShutdown ()
	Free the memory taken by staticInitialization() More...

Detailed Description

Abstract radiance/importance emitter interface.

This class implements an abstract interface to all emitters in Mitsuba. The term emitter is interpreted in a loose bidirectional sense here, where luminaires and sensors are both considered to be emitters of radiance and importance, respectively.

Subclasses must implement functions for evaluating and sampling the emission profile and furthermore support querying the probability density of the provided sampling technique.

Subclasses must also provide a specialized direct sampling method (a generalization of direct illumination sampling to both emitters and sensors). A direct sampling is given an arbitrary input position in the scene and in turn returns a sampled emitter position and direction, which has a nonzero contribution towards the provided position. The main idea is that direct sampling reduces the underlying space from 4D to 2D, hence it is often possible to use smarter sampling techniques than in the fully general case.

Since the emission profile is defined as function over both positions and directions, there are functions to sample and query each of the two components separately. Furthermore, there is a convenience function to sample both at the same time, which is mainly used by unidirectional rendering algorithms that do not need this level of flexibility.

One underlying assumption of this interface is that position and direction sampling will happen in sequence. This means that the direction sampling step is allowed to statistically condition on properties of the preceding position sampling step.

When rendering scenes involving participating media, it is important to know what medium surrounds the sensors and light sources. For this reason, every emitter instance keeps a reference to a medium (or NULL when it is surrounded by vacuum).

Member Enumeration Documentation

enum mitsuba::AbstractEmitter::EEmitterType

Flags used to classify the emission profile of different types of emitters.

Enumerator
EDeltaDirection	Emission profile contains a Dirac delta term with respect to direction.
EDeltaPosition	Emission profile contains a Dirac delta term with respect to position.
EOnSurface	Is the emitter associated with a surface in the scene?

Constructor & Destructor Documentation

mitsuba::AbstractEmitter::AbstractEmitter ( const Properties & props )

protected

Construct a new emitter instance.

mitsuba::AbstractEmitter::AbstractEmitter	(	Stream *	stream,
		InstanceManager *	manager
	)

protected

Unserialize a emitter instance from a binary data stream.

virtual mitsuba::AbstractEmitter::~AbstractEmitter ( )

protectedvirtual

Virtual destructor.

Member Function Documentation

virtual void mitsuba::AbstractEmitter::addChild	(	const std::string &	name,
		ConfigurableObject *	child
	)

virtual

Add a child ConfigurableObject.

Reimplemented from mitsuba::ConfigurableObject.

Reimplemented in mitsuba::Sensor.

void mitsuba::AbstractEmitter::addChild ( ConfigurableObject * child )

inline

Add an unnamed child.

virtual ref<Shape> mitsuba::AbstractEmitter::createShape ( const Scene * scene )

virtual

Create a special shape that represents the emitter.

Some types of emitters are inherently associated with a surface, yet this surface is not explicitly needed for many kinds of rendering algorithms.

An example would be an environment map, where the associated shape is a sphere surrounding the scene. Another example would be a perspective camera with depth of field, where the associated shape is a disk representing the aperture (remember that this class represents emitters in a generalized bidirectional sense, which includes sensors).

When this shape is in fact needed by the underlying rendering algorithm, this function can be called to create it. The default implementation simply returns NULL.

Parameters

scene A pointer to the associated scene (the created shape is allowed to depend on it)

virtual Spectrum mitsuba::AbstractEmitter::evalDirection	(	const DirectionSamplingRecord &	dRec,
		const PositionSamplingRecord &	pRec
	)		const

virtual

Evaluate the directional component of the emission profile.

When querying a smooth (i.e. non-degenerate) component, it already multiplies the result by the cosine foreshortening factor with respect to the outgoing direction.

Parameters

dRec	A direction sampling record, which specifies the query direction
pRec	A position sampling record, which specifies the query position

Returns: The component of the emission profile that depends on the direction (having units of 1/steradian)

virtual Spectrum mitsuba::AbstractEmitter::evalPosition ( const PositionSamplingRecord & pRec ) const

virtual

Evaluate the spatial component of the emission profile.

Parameters

pRec	A position sampling record, which specifies the query location

Returns: The component of the emission profile that depends on the position (i.e. emitted power per unit area for luminaires and sensor response, or inverse power per unit area for sensors)

virtual AABB mitsuba::AbstractEmitter::getAABB ( ) const

pure virtual

Return an axis-aligned box bounding the spatial extents of the emitter.

virtual const Class* mitsuba::AbstractEmitter::getClass ( ) const

virtual

Retrieve this object's class.

Reimplemented from mitsuba::ConfigurableObject.

Reimplemented in mitsuba::Emitter, mitsuba::PerspectiveCamera, mitsuba::ProjectiveCamera, and mitsuba::Sensor.

EMeasure mitsuba::AbstractEmitter::getDirectMeasure ( ) const

inline

Return the measure associated with the sampleDirect() operation.

Medium* mitsuba::AbstractEmitter::getMedium ( )

inline

Return a pointer to the medium that surrounds the emitter.

const Medium* mitsuba::AbstractEmitter::getMedium ( ) const

inline

Return a pointer to the medium that surrounds the emitter (const version)

Shape* mitsuba::AbstractEmitter::getShape ( )

inline

Return the shape, to which the emitter is currently attached.

const Shape* mitsuba::AbstractEmitter::getShape ( ) const

inline

Return the shape, to which the emitter is currently attached (const version)

uint32_t mitsuba::AbstractEmitter::getType ( ) const

inline

Return a listing of classification flags combined using binary OR.

See Also: EEmitterType

const AnimatedTransform* mitsuba::AbstractEmitter::getWorldTransform ( ) const

inline

Return the local space to world space transformation.

bool mitsuba::AbstractEmitter::isDegenerate ( ) const

inline

Does the sensor have a degenerate directional or spatial distribution?

bool mitsuba::AbstractEmitter::isOnSurface ( ) const

inline

Does the emitter lie on some kind of surface?

bool mitsuba::AbstractEmitter::needsDirectionSample ( ) const

inline

Does the method sampleDirection() require a uniformly distributed sample for the direction component?

bool mitsuba::AbstractEmitter::needsDirectSample ( ) const

inline

Does the method sampleDirect() require a uniformly distributed sample?

Since sampleDirect() essentially causes a 2D reduction of the sampling domain, this is the case exactly when the original domain was four-dimensionsional.

bool mitsuba::AbstractEmitter::needsPositionSample ( ) const

inline

Does the method samplePosition() require a uniformly distributed sample for the spatial component?

virtual Float mitsuba::AbstractEmitter::pdfDirect ( const DirectSamplingRecord & dRec ) const

virtual

Evaluate the probability density of the direct sampling method implemented by the sampleDirect() method.

Parameters

dRec	A direct sampling record, which specifies the query location. Note that this record need not be completely filled out. The important fields are `p`, `n`, `ref`, `dist`, `d`, `measure`, and `uv`.

Returns: The density expressed with respect to the requested measure (usually ESolidAngle)

virtual Float mitsuba::AbstractEmitter::pdfDirection	(	const DirectionSamplingRecord &	dRec,
		const PositionSamplingRecord &	pRec
	)		const

virtual

Evaluate the directional component of the sampling density implemented by the sampleDirection() method.

Parameters

dRec	A direction sampling record, which specifies the query direction
pRec	A position sampling record, which specifies the query position

Returns: The directional density at the supplied position

virtual Float mitsuba::AbstractEmitter::pdfPosition ( const PositionSamplingRecord & pRec ) const

virtual

Evaluate the spatial component of the sampling density implemented by the samplePosition() method.

Parameters

pRec	A position sampling record, which specifies the query location

Returns: The area density at the supplied position

virtual Spectrum mitsuba::AbstractEmitter::sampleDirect	(	DirectSamplingRecord &	dRec,
		const Point2 &	sample
	)		const

virtual

Direct sampling: given a reference point in the scene, sample an emitter position that contributes towards it.

Given an arbitrary reference point in the scene, this method samples a position on the emitter that has a nonzero contribution towards that point. This can be seen as a generalization of direct illumination sampling so that it works on both luminaires and sensors.

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.

The default implementation throws an exception.

Parameters

dRec	A direct 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
sample	A uniformly distributed 2D vector (or any value when needsDirectSample() == `false`)

Returns: An importance weight associated with the sample. Includes any geometric terms between the emitter and the reference point.

virtual Spectrum mitsuba::AbstractEmitter::sampleDirection	(	DirectionSamplingRecord &	dRec,
		PositionSamplingRecord &	pRec,
		const Point2 &	sample,
		const Point2 *	extra = `NULL`
	)		const

virtual

Conditioned on the spatial component, importance sample the directional part of the emission profile.

Some implementations may choose to implement extra functionality based on the value of extra: for instance, Sensors (which are a subclass of AbstractEmitter) perform uniform sampling over the entire image plane if extra == NULL, but other values, they will restrict sampling to a pixel-sized rectangle with that offset.

The default implementation throws an exception.

Parameters

dRec	A direction record to be populated with the sampled direction and related information
pRec	A position record generated by a preceding call to samplePosition()
sample	A uniformly distributed 2D vector (or any value when needsDirectionSample() == `false`)

Returns: An importance weight associated with the sampled direction. This accounts for the difference between the directional part of the emission profile and the density function.

virtual Spectrum mitsuba::AbstractEmitter::samplePosition	(	PositionSamplingRecord &	pRec,
		const Point2 &	sample,
		const Point2 *	extra = `NULL`
	)		const

virtual

Importance sample the spatial component of the emission profile.

This function takes an uniformly distributed 2D vector and maps it to a position on the surface of the emitter.

Some implementations may choose to implement extra functionality based on the value of extra: for instance, Sensors (which are a subclass of AbstractEmitter) perform uniform sampling over the entire image plane if extra == NULL, but other values, they will restrict sampling to a pixel-sized rectangle with that offset.

The default implementation throws an exception.

Parameters

pRec	A position record to be populated with the sampled position and related information
sample	A uniformly distributed 2D vector (or any value, when needsPositionSample() == `false`)
extra	An additional 2D vector provided to the sampling routine – its use is implementation-dependent.

Returns: An importance weight associated with the sampled position. This accounts for the difference between the spatial part of the emission profile and the density function.

virtual void mitsuba::AbstractEmitter::serialize	(	Stream *	stream,
		InstanceManager *	manager
	)		const

virtual

Serialize this emitter to a binary data stream.

Reimplemented from mitsuba::ConfigurableObject.

Reimplemented in mitsuba::Emitter, mitsuba::PerspectiveCamera, mitsuba::ProjectiveCamera, and mitsuba::Sensor.

void mitsuba::AbstractEmitter::setMedium ( Medium * medium )

inline

Set the medium that surrounds the emitter.

void mitsuba::AbstractEmitter::setWorldTransform ( AnimatedTransform * trafo )

inline

Set the local space to world space transformation.

Member Data Documentation

ref<Medium> mitsuba::AbstractEmitter::m_medium

protected

Shape* mitsuba::AbstractEmitter::m_shape

protected

Class* mitsuba::AbstractEmitter::m_theClass

static

uint32_t mitsuba::AbstractEmitter::m_type

protected

ref<const AnimatedTransform> mitsuba::AbstractEmitter::m_worldTransform

protected

The documentation for this class was generated from the following file:

include/mitsuba/render/emitter.h

Public Types

Public Member Functions

Static Public Attributes

Protected Member Functions

Protected Attributes

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation