Bidirectional path data structure. More...

#include <mitsuba/bidir/path.h>

Public Types
typedef PathEdge *	PathEdgePtr

typedef PathVertex *	PathVertexPtr

Public Member Functions
Accessors
size_t	vertexCount () const
	Return the number of vertices stored in this path. More...

size_t	edgeCount () const
	Return the number of edges stored in this path. More...

int	length () const
	Return the length of the path. This is just the number of edges. More...

PathVertexPtr &	vertex (size_t index)
	Return an vertex by its index. More...

const PathVertexPtr &	vertex (size_t index) const
	Return an vertex by its index (const version) More...

PathVertexPtr	vertexOrNull (size_t index)
	Return an vertex by its index (or NULL if out of bounds) More...

PathVertexPtr	vertexOrNull (size_t index) const
	Return an vertex by its index (or NULL if out of bounds, const version) More...

PathEdgePtr &	edge (size_t index)
	Return an edge by its index. More...

const PathEdgePtr &	edge (size_t index) const
	Return an edge by its index (const version) More...

PathEdgePtr	edgeOrNull (size_t index)
	Return an edge by its index (or `NULL` if out of bounds) More...

PathEdgePtr	edgeOrNull (size_t index) const
	Return an edge by its index (or `NULL` if out of bounds, const version) More...

Path construction
	Path ()
	Create a new, empty path. More...

	Path (size_t size)
	Create a new path of the specified size. More...

	Path (const Path &path)
	Copy constructor. More...

void	initialize (const Scene *scene, Float time, ETransportMode mode, MemoryPool &pool)
	Initialize the path with an endpoint vertex. More...

int	randomWalk (const Scene scene, Sampler sampler, int nSteps, int rrStart, ETransportMode mode, MemoryPool &pool)
	Perform/continue a random walk starting from the current endpoint. More...

int	randomWalkFromPixel (const Scene scene, Sampler sampler, int nSteps, const Point2i &pixelPosition, int rrStart, MemoryPool &pool)
	Perform a random walk starting at a specified pixel on the sensor. More...

bool	verify (const Scene *scene, ETransportMode mode, std::ostream &os) const
	Verify the cached values stored in this path. More...

static std::pair< int, int >	alternatingRandomWalkFromPixel (const Scene scene, Sampler sampler, Path &emitterPath, int nEmitterSteps, Path &sensorPath, int nSensorSteps, const Point2i &pixelPosition, int rrStart, MemoryPool &pool)
	Perform two random walks on an emitter and sensor subpath. More...

Miscellaneous
Spectrum	getPrefixSuffixWeight (int l, int m) const
	Return the spectrally varying path weight that corresponds to a prefix of length `l` and a suffix of length `m`. More...

bool	matchesConfiguration (const Path &p) const
	Determine whether another path of the same length matches the configuration of this path. More...

Spectrum	getRelativeWeight () const
	Return the relative spectrally varying path weight associated with this path. More...

void	collapseTo (PathEdge &edge) const
	Collapse a path into an entire edge that summarizes the aggregate transport and sampling densities. More...

void	reverse ()
	Reverse a path. More...

void	swapEndpoints (PathVertexPtr &supernode, PathEdgePtr &edge, PathVertexPtr &sample)
	Swap the two endpoint vertices of a path with the provided values. More...

void	append (PathVertex *vertex)
	Append a vertex to this path. More...

void	append (PathEdge *edge)
	Append an edge to this path. More...

void	append (PathEdge edge, PathVertex vertex)
	Append an edge and a vertex to this path. More...

void	append (const Path &path)
	Append an entire path to this path. More...

void	append (const Path &path, size_t start, size_t end, bool reverse=false)
	Append the vertex range `[start, end)` of `path` (and all intermediate edges) to the current path. More...

void	release (MemoryPool &pool)
	Clear the path and release all elements to the memory pool. More...

void	release (size_t start, size_t end, MemoryPool &pool)
	Release a certain subpath [start, end) to the memory pool. More...

const Point2 &	getSamplePosition () const
	Return the sample position associated with the path. More...

void	clear ()
	Clear the path. More...

bool	operator== (const Path &path) const
	Compare this path against another path. More...

bool	operator!= (const Path &path) const
	Compare this path against another path. More...

void	clone (Path &target, MemoryPool &pool) const
	Create a deep copy of this path. More...

std::string	toString () const
	Return a string representation of the path. More...

std::string	summarize () const
	Return a basic string summary of the path. More...

static Float	miWeight (const Scene scene, const Path &emitterSubpath, const PathEdge connectionEdge, const Path &sensorSubpath, int s, int t, bool direct, bool lightImage)
	Compute the multiple importance sampling weight of the `(s,t)` sampling strategy in BDPT. More...

Detailed Description

Bidirectional path data structure.

In the path-space light transport framework, a path is represented as a linear sequence of interactions (expressed using vertices) and transport (expressed using edges).

The Path data structure is responsible for the storage of this information. It also contains useful utility functions, for instance to perform a random walk, or to splice and connect path segments.

See Also: PathVertex; PathEdge

Author: Wenzel Jakob

Member Typedef Documentation

typedef PathEdge* mitsuba::Path::PathEdgePtr

typedef PathVertex* mitsuba::Path::PathVertexPtr

Constructor & Destructor Documentation

mitsuba::Path::Path ( )

inline

Create a new, empty path.

mitsuba::Path::Path ( size_t size )

inline

Create a new path of the specified size.

mitsuba::Path::Path ( const Path & path )

inline

Copy constructor.

Member Function Documentation

static std::pair<int, int> mitsuba::Path::alternatingRandomWalkFromPixel	(	const Scene *	scene,
		Sampler *	sampler,
		Path &	emitterPath,
		int	nEmitterSteps,
		Path &	sensorPath,
		int	nSensorSteps,
		const Point2i &	pixelPosition,
		int	rrStart,
		MemoryPool &	pool
	)

static

Perform two random walks on an emitter and sensor subpath.

This function is almost identical to calling randomWalk() twice in sequence. The main difference is that it performs the random walk steps in a staggered order (i.e. one step on the emitter subpath, one step on the sensor subpath, and so on..), which is important for obtaining good results with QMC random number sequences. Additinally, it ensures that the sensor path passes through a specified pixel instead of sampling it uniformly.

Used by bidirectional path tracing.

Parameters

scene	Pointer to the underlying scene
sampler	Pointer to a sample generator
emitterPath	Reference to the emitter subpath to be filled
nEmitterSteps	Desired number of random walk steps on the emitter subpath (`-1`=infinite)
sensorPath	Reference to the sensor subpath to be filled
nSensorSteps	Desired number of random walk steps on the sensor subpath (`-1`=infinite)
pixelPosition	Pixel position associated with the newly created sensor subpath
rrStart	Depth to start using russian roulette (`-1`=never, `0`=starting at the first bounce, and so on)
pool	Reference to a memory pool that will be used to allocate edges and vertices.

Returns: The number of successful steps performed by the random walk on the emitter and sensor subpath, respectively.

void mitsuba::Path::append ( PathVertex * vertex )

inline

Append a vertex to this path.

void mitsuba::Path::append ( PathEdge * edge )

inline

Append an edge to this path.

void mitsuba::Path::append	(	PathEdge *	edge,
		PathVertex *	vertex
	)

inline

Append an edge and a vertex to this path.

Parameters

edge	And edge from `vertex(vertexCount()-1)` to `vertex`.
vertex	A vertex to be appended at the end of the path

void mitsuba::Path::append ( const Path & path )

Append an entire path to this path.

void mitsuba::Path::append	(	const Path &	path,
		size_t	start,
		size_t	end,
		bool	reverse = `false`
	)

Append the vertex range [start, end) of path (and all intermediate edges) to the current path.

Parameters

path	Source of vertices and edges to be added
l	Specifies the start of the range `[start, end)`.
m	Specifies the end of the range `[start, end)`.
reverse	Should the vertices and edges be added in reverse order?

void mitsuba::Path::clear ( )

inline

Clear the path.

void mitsuba::Path::clone	(	Path &	target,
		MemoryPool &	pool
	)		const

Create a deep copy of this path.

void mitsuba::Path::collapseTo ( PathEdge & edge ) const

Collapse a path into an entire edge that summarizes the aggregate transport and sampling densities.

This is only allowed when the path only consists of BSDF::ENull surface scattering events (e.g. index-matched medium transitions)

PathEdgePtr& mitsuba::Path::edge ( size_t index )

inline

Return an edge by its index.

const PathEdgePtr& mitsuba::Path::edge ( size_t index ) const

inline

Return an edge by its index (const version)

size_t mitsuba::Path::edgeCount ( ) const

inline

Return the number of edges stored in this path.

For a nonempty path, the number of vertices is always equal To vertexCount()-1.

PathEdgePtr mitsuba::Path::edgeOrNull ( size_t index )

inline

Return an edge by its index (or NULL if out of bounds)

PathEdgePtr mitsuba::Path::edgeOrNull ( size_t index ) const

inline

Return an edge by its index (or NULL if out of bounds, const version)

Spectrum mitsuba::Path::getPrefixSuffixWeight	(	int	l,
		int	m
	)		const

inline

Return the spectrally varying path weight that corresponds to a prefix of length l and a suffix of length m.

This operation is used by path mutation strategies that operate by cutting out a pice of a path and replacing it with something else. In that case, it is necessary know about the effects of vertices and edges outside of the modified range.

Spectrum mitsuba::Path::getRelativeWeight ( ) const

inline

Return the relative spectrally varying path weight associated with this path.

This function computes the product of all the importance weights (see the weight field) along the path, and the result is normalized so that it has luminance 1. This quantity is required by the sample splatting implementation in Veach-MLT.

const Point2& mitsuba::Path::getSamplePosition ( ) const

inline

Return the sample position associated with the path.

void mitsuba::Path::initialize	(	const Scene *	scene,
		Float	time,
		ETransportMode	mode,
		MemoryPool &	pool
	)

Initialize the path with an endpoint vertex.

This function clears the path and initializes it with a single endpoint vertex of the type implied by the mode parameter.

Parameters

scene	Pointer to the underlying scene
time	Specifies the time value to be associated with the path.
mode	Specifies the desired endpoint type
pool	Reference to a memory pool that will be used to release and allocate edges and vertices.

int mitsuba::Path::length ( ) const

inline

Return the length of the path. This is just the number of edges.

bool mitsuba::Path::matchesConfiguration ( const Path & p ) const

inline

Determine whether another path of the same length matches the configuration of this path.

More specifically, this function verifies that the length matches, that all vertices are of the same type, and that the paths have identical values of isConnectable() for each vertex.

static Float mitsuba::Path::miWeight	(	const Scene *	scene,
		const Path &	emitterSubpath,
		const PathEdge *	connectionEdge,
		const Path &	sensorSubpath,
		int	s,
		int	t,
		bool	direct,
		bool	lightImage
	)

static

Compute the multiple importance sampling weight of the (s,t) sampling strategy in BDPT.

This implementation uses the power heuristic with exponent 2 and repeatedly evaluates equation (10.9) from Eric Veach's PhD thesis to compute the weight in an efficient and numerically stable manner.

The function completely ignores the effects of russian roulette, since this allows for a more efficient implementation. The resulting estimator is still unbiased despite this apparent inaccuracy.

Parameters

scene	Pointer to the underlying scene
emitterSubpath	Reference to the emitter subpath
connectionEdge	Pointer to an edge data structure associated with the transport between `emitterSubpath[s]` and `sensorSubpath[t]`.
sensorSubpath	Reference to the sensor subpath
s	Number of steps to take along the emitter subpath
t	Number of steps to take along the sensor subpath
direct	When the parameter `direct` is set to `true`, the implementation accounts for the fact that specialized direct sampling strategies are used for paths with `s==1` and `t==1`.
lightImage	Denotes whether or not rendering strategies that require a 'light image' (specifically, those with `t==0` or `t==1`) are included in the rendering process.

bool mitsuba::Path::operator!= ( const Path & path ) const

inline

Compare this path against another path.

bool mitsuba::Path::operator== ( const Path & path ) const

Compare this path against another path.

int mitsuba::Path::randomWalk	(	const Scene *	scene,
		Sampler *	sampler,
		int	nSteps,
		int	rrStart,
		ETransportMode	mode,
		MemoryPool &	pool
	)

Perform/continue a random walk starting from the current endpoint.

Parameters

scene	Pointer to the underlying scene
sampler	Pointer to a sample generator
nSteps	Desired number of random walk steps (`-1`=infinite)
rrStart	Depth to start using russian roulette (`-1`=never, `0`=starting at the first bounce, and so on)
mode	Denotes whether radiance or importance are being transported
pool	Reference to a memory pool that will be used to allocate edges and vertices.

Returns: The number of successful steps performed by the random walk.

int mitsuba::Path::randomWalkFromPixel	(	const Scene *	scene,
		Sampler *	sampler,
		int	nSteps,
		const Point2i &	pixelPosition,
		int	rrStart,
		MemoryPool &	pool
	)

Perform a random walk starting at a specified pixel on the sensor.

Parameters

scene	Pointer to the underlying scene
sampler	Pointer to a sample generator
nSteps	Desired number of random walk steps (`-1`=infinite)
pixelPosition	Pixel position associated with the newly created sensor subpath
rrStart	Depth to start using russian roulette (`-1`=never, `0`=starting at the first bounce, and so on)
pool	Reference to a memory pool that will be used to allocate edges and vertices.

Returns: The number of successful steps performed by the random walk.

void mitsuba::Path::release ( MemoryPool & pool )

Clear the path and release all elements to the memory pool.

void mitsuba::Path::release	(	size_t	start,
		size_t	end,
		MemoryPool &	pool
	)

Release a certain subpath [start, end) to the memory pool.

void mitsuba::Path::reverse ( )

Reverse a path.

std::string mitsuba::Path::summarize ( ) const

Return a basic string summary of the path.

void mitsuba::Path::swapEndpoints	(	PathVertexPtr &	supernode,
		PathEdgePtr &	edge,
		PathVertexPtr &	sample
	)

inline

Swap the two endpoint vertices of a path with the provided values.

std::string mitsuba::Path::toString ( ) const

Return a string representation of the path.

bool mitsuba::Path::verify	(	const Scene *	scene,
		ETransportMode	mode,
		std::ostream &	os
	)		const

Verify the cached values stored in this path.

This function re-evaluates a series of quantities associated with each vertex and edge and compares them to locally cached values. If any mismatch is found, the function sends debug output to a specified output stream and returns false.

Parameters

scene	Pointer to the underlying scene
mode	Disambiguates the order of the vertices in this path
os	Target output stream for error messages

PathVertexPtr& mitsuba::Path::vertex ( size_t index )

inline

Return an vertex by its index.

const PathVertexPtr& mitsuba::Path::vertex ( size_t index ) const

inline

Return an vertex by its index (const version)

size_t mitsuba::Path::vertexCount ( ) const

inline

Return the number of vertices stored in this path.

For a nonempty path, the number of vertices is always equal To edgeCount()+1.

PathVertexPtr mitsuba::Path::vertexOrNull ( size_t index )

inline

Return an vertex by its index (or NULL if out of bounds)

PathVertexPtr mitsuba::Path::vertexOrNull ( size_t index ) const

inline

Return an vertex by its index (or NULL if out of bounds, const version)

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

include/mitsuba/bidir/path.h

Public Types

Public Member Functions

Path construction

Miscellaneous

Detailed Description

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation