Core library

Classes
struct	TAABB
	Generic multi-dimensional bounding box data structure. More...
struct	AABB
	Axis-aligned bounding box data structure in three dimensions. More...
class	Appender
	This class defines an abstract destination for logging-relevant information. More...
class	StreamAppender
	Appender implementation, which writes to an arbitrary C++ output stream More...
class	UnbufferedAppender
	Appender implementation, which writes directly to an UNIX-style unbuffered file descriptor. More...
class	Bitmap
	1/8/24/32/128-Bit Raster ("Bitmap") data structure with support for PNG storage and retrieval. When set to 128 bits per pixel, the implementation switches to HDR and the EXR file format. More...
class	BrentSolver
	Brent's method nonlinear zero finder. More...
struct	BSphere
	Bounding sphere data structure in three dimensions. More...
class	ChiSquare
	Chi-square goodness-of-fit test on the sphere. More...
class	Class
	Stores meta-information about Object instances. More...
class	ConfigurableObject
	Generic serializable object, which supports construction from a Properties instance. More...
class	ConsoleStream
	Stream-style interface to the default stdin/stdout console streams. More...
class	Formatter
	Abstract interface for converting log information into a human-readable format. More...
struct	Frame
	Stores a three-dimensional orthonormal coordinate frame. More...
class	FileResolver
	File resolution helper. More...
class	FileStream
	Simple Stream implementation for accessing files. More...
struct	SimpleKDNode
	Simple kd-tree node for use with PointKDTree. More...
struct	LeftBalancedKDNode
	Left-balanced kd-tree node for use with PointKDTree. More...
class	PointKDTree
	Generic multi-dimensional kd-tree data structure for point data. More...
class	Mutex
	Thin wrapper around the recursive pthreads lock. More...
class	WaitFlag
	Wait flag synchronization primitive. Can be used to wait for a certain event to occur. More...
class	ConditionVariable
	Condition variable synchronization primitive. Can be used to wait for a condition to become true in a safe way. More...
class	Logger
	Responsible for processing log messages. More...
struct	LRUCache
	Generic LRU cache implementation. More...
struct	Matrix
	Generic fixed-size dense matrix class using a row-major storage format. More...
struct	Matrix2x2
	Basic 2x2 matrix data type. More...
struct	Matrix3x3
	Basic 3x3 matrix data type. More...
struct	Matrix4x4
	Basic 4x4 matrix data type. More...
class	MemoryPool
	Basic memory pool for efficient allocation and deallocation of objects of the same type. More...
class	MemoryMappedFile
	Basic cross-platform abstraction for memory mapped files. More...
class	MemoryStream
	Simple memory buffer-based stream with automatic memory management. More...
class	NetworkedObject
	Abstract interface for objects that reference shared network resources. More...
struct	Normal
	Three-dimensional normal data structure. More...
class	Object
	Parent of all Mitsuba classes. More...
class	LockFreeList
	Implements a lock-free singly linked list using atomic operations. More...
class	Octree
	Generic multiple-reference octree. More...
struct	DiscretePDF
	Stores a discrete probability distribution. More...
class	Plugin
	Abstract plugin class -- represents loadable configurable objects and utilities. More...
class	PluginManager
	The plugin manager is responsible for resolving and loading external plugins. More...
struct	TPoint2
	Parameterizable two-dimensional point data structure. More...
struct	TPoint3
	Parameterizable three-dimensional point data structure. More...
struct	TPoint4
	Parameterizable four-dimensional point data structure. More...
class	Properties
	Associative parameter map for constructing subclasses of ConfigurableObject. More...
class	GaussLobattoIntegrator
	Computes the integral of a one-dimensional function using adaptive Gauss-Lobatto quadrature. More...
class	NDIntegrator
	Adaptively computes the integral of a multidimensional function using either a Gauss-Kronod (1D) or a Genz-Malik (>1D) cubature rule. More...
struct	TQuaternion
	Parameterizable quaternion data structure. More...
struct	Ray
	Simple three-dimensional ray data structure with minimum / maximum extent information. More...
struct	RayDifferential
	Ray differential -- enhances the basic ray class with information about the rays of adjacent pixels on the view plane More...
class	ref
	Reference counting helper. More...
class	WorkUnit
	Abstract work unit -- represents a small amount of information that encodes part of a larger processing task. More...
class	WorkResult
	Abstract work result -- represents the result of a processed WorkUnit instance. More...
class	WorkProcessor
	Abstract work processor -- takes work units and turns them into WorkResult instances. More...
class	ParallelProcess
	Abstract parallelizable task. More...
class	Scheduler
	Centralized task scheduler implementation. More...
class	LocalWorker
	Acquires work from the scheduler and executes it locally. More...
class	RemoteWorker
	Acquires work from the scheduler and forwards it to a processing node reachable through a Stream. More...
class	RemoteProcess
	Parallel process facade used to insert work units from a remote scheduler into the local one. More...
class	StreamBackend
	Network processing communication backend. More...
class	SerializableObject
	Base class of all reference-counted objects with serialization support. More...
class	InstanceManager
	Coordinates the serialization and unserialization of object graphs. More...
class	HilbertCurve2D
	2D version of the Hilbert space-filling curve More...
struct	SHRotation
	Stores the diagonal blocks of a spherical harmonic rotation matrix. More...
struct	SHVector
	Stores a truncated real spherical harmonics representation of an L2-integrable function. More...
class	ContinuousSpectrum
	Abstract continous spectral power distribution data type, which supports evaluation at arbitrary wavelengths. More...
class	BlackBodySpectrum
	Spectral power distribution based on Planck's black body law. More...
class	RayleighSpectrum
	Spectral distribution for rendering participating media with Rayleigh scattering. More...
class	InterpolatedSpectrum
	Linearly interpolated spectral power distribution. More...
struct	Spectrum
	Discrete spectral power distribution based on a number of wavelength bins over the 360-830 nm range. More...
class	SSHStream
	Stream implementation based on an encrypted SSH tunnel. More...
class	SocketStream
	Portable Stream implementation, which encapsulates a socket for IPv4/IPv6 network communications. More...
class	StatsCounter
	General-purpose statistics counter. More...
class	ProgressReporter
	General-purpose progress reporter. More...
class	Statistics
	Collects various rendering statistics and presents them in a human-readable form. More...
class	Stream
	Abstract seekable stream class. More...
class	Thread
	Cross-platform thread implementation. More...
class	Timer
	Platform independent milli/microsecond timer. More...
class	ThreadLocal
	Thin wrapper around posix thread local storage. Stores references to Object instances. More...
class	PrimitiveThreadLocal
	Thin wrapper around posix thread local storage. Stores heap-allocated data other than Object instances. More...
struct	Transform
	Encapsulates a 4x4 linear transformation and its inverse. More...
struct	Triangle
	Simple triangle class including a collection of routines for analysis and transformation. More...
struct	SimpleStringOrdering
	Simple functor for sorting string parameters by length and content. More...
struct	TVector2
	Parameterizable two-dimensional vector data structure. More...
struct	TVector3
	Parameterizable three-dimensional vector data structure. More...
struct	TVector4
	Parameterizable four-dimensional vector data structure. More...
struct	Version
	A simple data structure for representing and comparing Mitsuba version strings. More...
class	Wavelet2D
	Performs non-standard 2D Haar wavelet transformations. More...
class	SparseWavelet2D
	Sparse 2D wavelet representation using the Haar basis. More...
class	SparseWaveletOctree
	Sparse 3D wavelet representation using the Haar basis and an octree structure. More...
class	ZStream
	Transparent compression/decompression stream based on zlib. More...
Defines
#define	MTS_CLASS(x)   x::m_theClass
	Return the Class object corresponding to a named class.
#define	MTS_DECLARE_CLASS()
	This macro must be used in the initial definition in classes that derive from Object.
#define	MTS_IMPLEMENT_CLASS(name, abstract, super)
	Creates basic RTTI support for a class.
#define	MTS_IMPLEMENT_CLASS_I(name, abstract, super)
	Creates basic RTTI support for a class. To be used when the class has a simple constructor (i.e. one wich does not take any arguments)
#define	MTS_IMPLEMENT_CLASS_S(name, abstract, super)
	Creates basic RTTI support for a class. To be used when the class can be unserialized from a binary data stream.
#define	MTS_IMPLEMENT_CLASS_IS(name, abstract, super)
	Creates basic RTTI support for a class. To be used when the class can be unserialized from a binary data stream as well as instantiated by a constructor that does not take any arguments.
#define	MTS_EXPORT_PLUGIN(name, descr)
	This macro creates the binary interface, which Mitsuba requires to load a plugin.
#define	Log(level, fmt,...)
	Write a Log message to the console (to be used within subclasses of Object)
#define	SLog(level, fmt,...)
	Write a Log message to the console (static version - to be used outside of classes that derive from Object)
#define	Assert(cond)
	Assert that a condition is true (to be used inside of classes that derive from Object)
#define	SAssert(cond)
	``Static'' assertion (to be used outside of classes that derive from Object)
#define	AssertEx(cond, explanation)
	Assertion with a customizable error explanation.
#define	SAssertEx(cond, explanation)
	Static assertion with a customizable error explanation (see SLog)
#define	MTS_VERSION   "0.3.1"
	Current release of Mitsuba.
#define	MTS_YEAR   "2011"
	Year of the current release.
Functions
template<typename T >
bool	atomicCompareAndExchangePtr (T **v, T *newValue, T *oldValue)
	Atomically attempt to exchange a pointer with another value.
bool	atomicCompareAndExchange (volatile int32_t *v, int32_t newValue, int32_t oldValue)
	Atomically attempt to exchange a 32-bit integer with another value.
bool	atomicCompareAndExchange (volatile int64_t *v, int64_t newValue, int64_t oldValue)
	Atomically attempt to exchange a 64-bit integer with another value.
float	atomicAdd (volatile float *dst, float delta)
	Atomically add delta to the floating point destination dst.
double	atomicAdd (volatile double *dst, double delta)
	Atomically add delta to the floating point destination dst.
int32_t	atomicAdd (volatile int32_t *dst, int32_t delta)
	Atomically add delta to the 32-bit integer destination dst.
int64_t	atomicAdd (volatile int64_t *dst, int64_t delta)
	Atomically add delta to the 64-bit integer destination dst.
bool	SimpleStringOrdering::operator() (const std::string &a, const std::string &b) const
MTS_EXPORT_CORE Float	fresnelDielectric (Float cosThetaI, Float cosThetaT, Float etaI, Float etaT)
	Calculates the unpolarized fresnel reflection coefficient for a dielectric material.
MTS_EXPORT_CORE Spectrum	fresnelConductor (Float cosThetaI, const Spectrum &eta, const Spectrum &k)
	Calculates the unpolarized fresnel reflection coefficient on an interface to a conductor.
MTS_EXPORT_CORE Float	fresnel (Float cosThetaI, Float extIOR, Float intIOR)
	Calculates the unpolarized fresnel reflection coefficient for a dielectric material. Handles incidence from either sides.
MTS_EXPORT_CORE Float	fresnelDiffuseReflectance (Float eta, bool fast=false)
	Calculates the diffuse unpolarized fresnel reflectance of a dielectric material (sometimes referred to as "Fdr").
String-related utility functions
MTS_EXPORT_CORE std::vector < std::string >	tokenize (const std::string &string, const std::string &delim)
	Given a list of delimiters, tokenize a std::string into a vector of strings.
MTS_EXPORT_CORE std::string	trim (const std::string &str)
	Trim spaces (' ', '\n', '\r', '\t') from the ends of a string.
MTS_EXPORT_CORE std::string	indent (const std::string &string, int amount=1)
	Indent a string (Used for recursive toString() structure dumping)
MTS_EXPORT_CORE std::string	formatString (const char *pFmt,...)
	Wrapped snprintf.
MTS_EXPORT_CORE std::string	timeString (Float time, bool precise=false)
	Convert a time difference (in ms) to a string representation.
MTS_EXPORT_CORE std::string	memString (size_t size)
	Turn a memory size into a human-readable string.
template<class Iterator >
std::string	containerToString (const Iterator &start, const Iterator &end)
	Return a string representation of a list of objects.
Miscellaneous
MTS_EXPORT_CORE void *__restrict	allocAligned (size_t size)
	Allocate an aligned region of memory.
MTS_EXPORT_CORE void	freeAligned (void *ptr)
	Free an aligned region of memory.
MTS_EXPORT_CORE int	getProcessorCount ()
	Determine the number of available CPU cores.
MTS_EXPORT_CORE std::string	getHostName ()
	Return the host name of this machine.
MTS_EXPORT_CORE std::string	getFQDN ()
	Return the fully qualified domain name of this machine.
MTS_EXPORT_CORE bool	enableFPExceptions ()
	Enable floating point exceptions (to catch NaNs, overflows, arithmetic with infinity).
MTS_EXPORT_CORE bool	disableFPExceptions ()
	Disable floating point exceptions.
MTS_EXPORT_CORE void	restoreFPExceptions (bool state)
	Restore floating point exceptions to the specified state.
template<typename T , typename U >
T	union_cast (const U &val)
	Cast between types that have an identical binary representation.
template<typename T >
T	endianness_swap (T value)
	Swaps the byte order of the underlying representation.
template<typename DataType , typename IndexType >
void	permute_inplace (DataType *data, std::vector< IndexType > &perm)
	Apply an arbitrary permutation to an array in linear time.
Numerical utility functions
const int MTS_EXPORT_CORE	primeTable [primeTableSize]
	Table of the first 1000 prime numbers.
MTS_EXPORT_CORE Float	hypot2 (Float a, Float b)
	sqrt(a^2 + b^2) without underflow (like 'hypot' on compilers that support C99)
MTS_EXPORT_CORE Float	log2 (Float value)
	Base-2 logarithm.
MTS_EXPORT_CORE int	modulo (int a, int b)
	Friendly modulo function (always positive)
MTS_EXPORT_CORE Float	modulo (Float a, Float b)
	Friendly modulo function (always positive)
int	floorToInt (Float value)
	Integer floor function.
MTS_EXPORT_CORE int	log2i (uint32_t value)
	Base-2 logarithm (32-bit integer version)
MTS_EXPORT_CORE int	log2i (uint64_t value)
	Base-2 logarithm (64-bit integer version)
bool	isPowerOfTwo (uint32_t i)
	Check if an integer is a power of two (unsigned 32 bit version)
bool	isPowerOfTwo (int32_t i)
	Check if an integer is a power of two (signed 32 bit version)
bool	isPowerOfTwo (uint64_t i)
	Check if an integer is a power of two (64 bit version)
bool	isPowerOfTwo (int64_t i)
	Check if an integer is a power of two (signed 64 bit version)
MTS_EXPORT_CORE uint32_t	roundToPowerOfTwo (uint32_t i)
	Round an integer to the next power of two.
MTS_EXPORT_CORE uint64_t	roundToPowerOfTwo (uint64_t i)
	Round an integer to the next power of two (64 bit version)
MTS_EXPORT_CORE Float	lanczosSinc (Float t, Float tau=2)
	Windowed sinc filter (Lanczos envelope, tau=number of cycles)
MTS_EXPORT_CORE bool	solveQuadratic (Float a, Float b, Float c, Float &x0, Float &x1)
	Solve a quadratic equation of the form a*x^2 + b*x + c = 0.
MTS_EXPORT_CORE bool	solveQuadraticDouble (double a, double b, double c, double &x0, double &x1)
	Solve a double-precision quadratic equation of the form a*x^2 + b*x + c = 0.
MTS_EXPORT_CORE Float	interpCubic1D (Float p, const Float *data, Float min, Float max, size_t size)
	Evaluate a cubic spline interpolant of a regularly sampled 1D function.
MTS_EXPORT_CORE Float	interpCubic2D (const Point2 &p, const Float *data, const Point2 &min, const Point2 &max, const Size2 &size)
	Evaluate a cubic spline interpolant of a regularly sampled 2D function.
MTS_EXPORT_CORE Float	interpCubic3D (const Point3 &p, const Float *data, const Point3 &min, const Point3 &max, const Size3 &size)
	Evaluate a cubic spline interpolant of a regularly sampled 3D function.
MTS_EXPORT_CORE Float	radicalInverse (int b, size_t i)
	Calculate the radical inverse function.
MTS_EXPORT_CORE Float	radicalInverseIncremental (int b, Float x)
	Incrementally calculate the radical inverse function.
MTS_EXPORT_CORE double	normalQuantile (double p)
Float	radToDeg (Float value)
	Table of the first 1000 prime numbers.
Float	degToRad (Float value)
	Convert degrees to radians.
Float	clamp (Float value, Float min, Float max)
	Simple floating point clamping function.
int	clamp (int value, int min, int max)
	Simple integer clamping function.
Float	lerp (Float t, Float v1, Float v2)
	Linearly interpolate between two values.
Float	smoothStep (Float min, Float max, Float value)
	S-shaped smoothly varying interpolation between two values.
template<typename VectorType >
Float	unitAngle (const VectorType &u, const VectorType &v)
	Numerically well-behaved routine for computing the angle between two unit direction vectors.
Warping and sampling-related utility functions
MTS_EXPORT_CORE bool	solveLinearSystem2x2 (const Float a[2][2], const Float b[2], Float x[2])
	Solve a 2x2 linear equation system using basic linear algebra.
MTS_EXPORT_CORE void	coordinateSystem (const Vector &a, Vector &b, Vector &c)
	Complete the set {a} to an orthonormal base.
MTS_EXPORT_CORE void	stratifiedSample1D (Random *random, Float *dest, int count, bool jitter)
	Generate (optionally jittered) stratified 1D samples.
MTS_EXPORT_CORE void	stratifiedSample2D (Random *random, Point2 *dest, int countX, int countY, bool jitter)
	Generate (optionally jittered) stratified 2D samples.
MTS_EXPORT_CORE void	latinHypercube (Random *random, Float *dest, size_t nSamples, size_t nDim)
	Generate latin hypercube samples.
MTS_EXPORT_CORE Vector	sphericalDirection (Float theta, Float phi)
	Convert spherical coordinates to a direction.
MTS_EXPORT_CORE Point2	toSphericalCoordinates (const Vector &v)
	Convert a direction to spherical coordinates.
MTS_EXPORT_CORE Vector	squareToSphere (const Point2 &sample)
	Sample a vector on the unit sphere (PDF: 1/(4 * PI), wrt. solid angles)
MTS_EXPORT_CORE Vector	squareToHemisphere (const Point2 &sample)
	Sample a vector on the unit hemisphere (PDF: 1/(2 * PI), wrt. solid angles)
MTS_EXPORT_CORE Vector	squareToHemispherePSA (const Point2 &sample)
	Sample a vector on the unit hemisphere (PDF: cos(theta) / PI, wrt. solid angles)
MTS_EXPORT_CORE Vector	squareToCone (Float cosCutoff, const Point2 &sample)
	Sample a vector that lies in a cone of angles.
MTS_EXPORT_CORE Float	squareToConePdf (Float cosCutoff)
	Solve a 2x2 linear equation system using basic linear algebra.
MTS_EXPORT_CORE Point2	squareToDisk (const Point2 &sample)
	Sample a vector on a 2D disk (PDF: 1/(2 * PI))
MTS_EXPORT_CORE Point2	squareToDiskConcentric (const Point2 &sample)
	Low-distortion concentric square to disk mapping by Peter Shirley (PDF: 1/(2 * PI))
MTS_EXPORT_CORE Point2	diskToSquareConcentric (const Point2 &sample)
	Low-distortion concentric disk to square mapping.
MTS_EXPORT_CORE Point2	squareToTriangle (const Point2 &sample)
	Convert an uniformly distributed square sample into barycentric coordinates.
MTS_EXPORT_CORE Point2	squareToStdNormal (const Point2 &sample)
	Sample a point on a 2D standard normal distribution (uses the Box-Muller transformation)

---

Detailed Description

This library contains the core support API of Mitsuba

The following implementations are based on PBRT

---

Define Documentation

#define Assert

(

cond

)

Value:

do { \
                if (!(cond)) Log(EError, "Assertion \"%s\" failed in %s:%i", \
                #cond, __FILE__, __LINE__); \
        } while (0)

Assert that a condition is true (to be used inside of classes that derive from Object)

#define AssertEx	(		cond,
			explanation
	)

Value:

do { \
                if (!(cond)) Log(EError, "Assertion \"%s\" failed in %s:%i (" explanation ")", \
                #cond, __FILE__, __LINE__); \
        } while (0)

Assertion with a customizable error explanation.

#define Log	(		level,
			fmt,
			...
	)

Value:

Thread::getThread()->getLogger()->log(level, m_theClass, \
        __FILE__, __LINE__, fmt, ## __VA_ARGS__)

Write a Log message to the console (to be used within subclasses of Object)

#define MTS_CLASS

(

x

)

x::m_theClass

Return the Class object corresponding to a named class.

Call the Macro without quotes, e.g. MTS_CLASS(SerializableObject)

#define MTS_DECLARE_CLASS

(

)

Value:

virtual const Class *getClass() const; \
public: \
        static Class *m_theClass;

This macro must be used in the initial definition in classes that derive from Object.

This is needed for the basic RTTI support provided by Mitsuba objects. For instance, a class definition might look like the following:

 class MyObject : public Object {
 public:
     MyObject();

     /// Important: declare RTTI data structures
     MTS_DECLARE_CLASS()
 protected:
     /// Important: needs to declare a protected virtual destructor
     virtual ~MyObject();

 };

#define MTS_EXPORT_PLUGIN	(		name,
			descr
	)

Value:

extern "C" { \
                void MTS_EXPORT *CreateInstance(const Properties &props) { \
                        return new name(props); \
                } \
                const char MTS_EXPORT *GetDescription() { \
                        return descr; \
                } \
        }

This macro creates the binary interface, which Mitsuba requires to load a plugin.

#define MTS_IMPLEMENT_CLASS	(		name,
			abstract,
			super
	)

Value:

Class *name::m_theClass = new Class(#name, abstract, #super); \
        const Class *name::getClass() const { \
                return m_theClass;\
        }

Creates basic RTTI support for a class.

This macro or one of its variants should be invoked in the main implementation .cpp file of any class that derives from Object. This is needed for the basic RTTI support provided by Mitsuba objects. For instance, the corresponding piece for the example shown in the documentation of MTS_DECLARE_CLASS might look like this:

 MTS_IMPLEMENT_CLASS(MyObject, false, Object)

Parameters:

name	Name of the class
abstract	true if the class contains pure virtual methods
super	Name of the parent class

#define MTS_IMPLEMENT_CLASS_I	(		name,
			abstract,
			super
	)

Value:

Object *__##name ##_inst() { \
                return new name(); \
        } \
        Class *name::m_theClass = new Class(#name, abstract, #super, (void *) &__##name ##_inst, NULL); \
        const Class *name::getClass() const { \
                return m_theClass;\
        }

Creates basic RTTI support for a class. To be used when the class has a simple constructor (i.e. one wich does not take any arguments)

This macro or one of its variants should be invoked in the main implementation .cpp file of any class that derives from Object. This is needed for the basic RTTI support provided by Mitsuba objects.

Parameters:

name	Name of the class
abstract	true if the class contains pure virtual methods
super	Name of the parent class

#define MTS_IMPLEMENT_CLASS_IS	(		name,
			abstract,
			super
	)

Value:

Object *__##name ##_unSer(Stream *stream, InstanceManager *manager) { \
                return new name(stream, manager); \
        } \
        Object *__##name ##_inst() { \
                return new name(); \
        } \
        Class *name::m_theClass = new Class(#name, abstract, #super, (void *) &__##name ##_inst, (void *) &__##name ##_unSer); \
        const Class *name::getClass() const { \
                return m_theClass;\
        }

Creates basic RTTI support for a class. To be used when the class can be unserialized from a binary data stream as well as instantiated by a constructor that does not take any arguments.

This macro or one of its variants should be invoked in the main implementation .cpp file of any class that derives from Object. This is needed for the basic RTTI support provided by Mitsuba objects.

Parameters:

name	Name of the class
abstract	true if the class contains pure virtual methods
super	Name of the parent class

#define MTS_IMPLEMENT_CLASS_S	(		name,
			abstract,
			super
	)

Value:

Object *__##name ##_unSer(Stream *stream, InstanceManager *manager) { \
                return new name(stream, manager); \
        } \
        Class *name::m_theClass = new Class(#name, abstract, #super, NULL, (void *) &__##name ##_unSer); \
        const Class *name::getClass() const { \
                return m_theClass;\
        }

Creates basic RTTI support for a class. To be used when the class can be unserialized from a binary data stream.

This macro or one of its variants should be invoked in the main implementation .cpp file of any class that derives from Object. This is needed for the basic RTTI support provided by Mitsuba objects.

Parameters:

name	Name of the class
abstract	true if the class contains pure virtual methods
super	Name of the parent class

#define MTS_VERSION   "0.3.1"

Current release of Mitsuba.

#define MTS_YEAR   "2011"

Year of the current release.

#define SAssert

(

cond

)

Value:

do { \
                if (!(cond)) SLog(EError, "Assertion \"%s\" failed in %s:%i", \
                #cond, __FILE__, __LINE__); \
        } while (0)

``Static'' assertion (to be used outside of classes that derive from Object)

#define SAssertEx	(		cond,
			explanation
	)

Value:

do { \
                if (!(cond)) SLog(EError, "Assertion \"%s\" failed in %s:%i (" explanation ")", \
                #cond, __FILE__, __LINE__); \
        } while (0)

Static assertion with a customizable error explanation (see SLog)

#define SLog	(		level,
			fmt,
			...
	)

Value:

Thread::getThread()->getLogger()->log(level, NULL, \
        __FILE__, __LINE__, fmt, ## __VA_ARGS__)

Write a Log message to the console (static version - to be used outside of classes that derive from Object)

---

Function Documentation

MTS_EXPORT_CORE void* __restrict allocAligned

(

size_t

size

)

Allocate an aligned region of memory.

float atomicAdd	(	volatile float *	dst,
		float	delta
	)		[inline]

Atomically add delta to the floating point destination dst.

Returns:

The final value written to dst

double atomicAdd	(	volatile double *	dst,
		double	delta
	)		[inline]

Atomically add delta to the floating point destination dst.

Returns:

The final value written to dst

int32_t atomicAdd	(	volatile int32_t *	dst,
		int32_t	delta
	)		[inline]

Atomically add delta to the 32-bit integer destination dst.

Returns:

The final value written to dst

int64_t atomicAdd	(	volatile int64_t *	dst,
		int64_t	delta
	)		[inline]

Atomically add delta to the 64-bit integer destination dst.

Returns:

The final value written to dst

bool atomicCompareAndExchange	(	volatile int32_t *	v,
		int32_t	newValue,
		int32_t	oldValue
	)		[inline]

Atomically attempt to exchange a 32-bit integer with another value.

Parameters:

v	Pointer to the memory region in question
oldValue	Last known value of the destination v
newValue	Replacement value for the destination v

Returns:

true if *v was equal to oldValue and the exchange was successful.

bool atomicCompareAndExchange	(	volatile int64_t *	v,
		int64_t	newValue,
		int64_t	oldValue
	)		[inline]

Atomically attempt to exchange a 64-bit integer with another value.

Parameters:

v	Pointer to the memory region in question
oldValue	Last known value of the destination v
newValue	Replacement value for the destination v

Returns:

true if *v was equal to oldValue and the exchange was successful.

template<typename T >

bool atomicCompareAndExchangePtr	(	T **	v,
		T *	newValue,
		T *	oldValue
	)		[inline]

Atomically attempt to exchange a pointer with another value.

Parameters:

v	Pointer to the pointer in question
oldValue	Last known value of the destination v
newValue	Replacement value for the destination v

Template Parameters:

T	Base type of the pointer

Returns:

true if *v was equal to oldValue and the exchange was successful.

Float clamp	(	Float	value,
		Float	min,
		Float	max
	)		[inline]

Simple floating point clamping function.

int clamp	(	int	value,
		int	min,
		int	max
	)		[inline]

Simple integer clamping function.

template<class Iterator >

std::string containerToString	(	const Iterator &	start,
		const Iterator &	end
	)

Return a string representation of a list of objects.

MTS_EXPORT_CORE void coordinateSystem	(	const Vector &	a,
		Vector &	b,
		Vector &	c
	)

Complete the set {a} to an orthonormal base.

Float degToRad

(

Float

value

)

[inline]

Convert degrees to radians.

MTS_EXPORT_CORE bool disableFPExceptions

(

)

Disable floating point exceptions.

Returns:

true if floating point exceptions were active before calling the function

MTS_EXPORT_CORE Point2 diskToSquareConcentric

(

const Point2 &

sample

)

Low-distortion concentric disk to square mapping.

MTS_EXPORT_CORE bool enableFPExceptions

(

)

Enable floating point exceptions (to catch NaNs, overflows, arithmetic with infinity).

On Intel processors, this applies to both x87 and SSE2 math

Returns:

true if floating point exceptions were active before calling the function

template<typename T >

T endianness_swap

(

T

value

)

[inline]

Swaps the byte order of the underlying representation.

int floorToInt

(

Float

value

)

[inline]

Integer floor function.

MTS_EXPORT_CORE std::string formatString	(	const char *	pFmt,
			...
	)

Wrapped snprintf.

MTS_EXPORT_CORE void freeAligned

(

void *

ptr

)

Free an aligned region of memory.

MTS_EXPORT_CORE Float fresnel	(	Float	cosThetaI,
		Float	extIOR,
		Float	intIOR
	)

Calculates the unpolarized fresnel reflection coefficient for a dielectric material. Handles incidence from either sides.

Parameters:

cosThetaI	Cosine of the angle between the normal and the incident ray
extIOR	Refraction coefficient outside of the material
intIOR	Refraction coefficient inside the material

MTS_EXPORT_CORE Spectrum fresnelConductor	(	Float	cosThetaI,
		const Spectrum &	eta,
		const Spectrum &	k
	)

Calculates the unpolarized fresnel reflection coefficient on an interface to a conductor.

Parameters:

cosThetaI	Cosine of the angle between the normal and the incident ray
eta	Real refractive index (wavelength-dependent)
k	Imaginary refractive index (wavelength-dependent)

MTS_EXPORT_CORE Float fresnelDielectric	(	Float	cosThetaI,
		Float	cosThetaT,
		Float	etaI,
		Float	etaT
	)

Calculates the unpolarized fresnel reflection coefficient for a dielectric material.

Parameters:

cosThetaI	Cosine of the angle between the normal and the incident ray
cosThetaT	Cosine of the angle between the normal and the transmitted ray
etaI	Refraction coefficient at the incident direction
etaT	Refraction coefficient at the transmitted direction

MTS_EXPORT_CORE Float fresnelDiffuseReflectance	(	Float	eta,
		bool	fast = false
	)

Calculates the diffuse unpolarized fresnel reflectance of a dielectric material (sometimes referred to as "Fdr").

This value quantifies what fraction of completely diffuse incident illumination will be reflected by a dielectric material on average.

Parameters:

eta	Relative refraction coefficient, i.e. etaT/etaI
fast	Compute an approximate value? If set to true, the implementation will use a polynomial approximation with a max relative error of ~0.5% on the interval 0.5 < eta < 2. When fast=false, the code will use Gauss-Lobatto quadrature to compute the diffuse reflectance more accurately, and for a wider range of refraction coefficients, but at a cost in terms of performance.

MTS_EXPORT_CORE std::string getFQDN

(

)

Return the fully qualified domain name of this machine.

MTS_EXPORT_CORE std::string getHostName

(

)

Return the host name of this machine.

MTS_EXPORT_CORE int getProcessorCount

(

)

Determine the number of available CPU cores.

MTS_EXPORT_CORE Float hypot2	(	Float	a,
		Float	b
	)

sqrt(a^2 + b^2) without underflow (like 'hypot' on compilers that support C99)

MTS_EXPORT_CORE std::string indent	(	const std::string &	string,
		int	amount = 1
	)

Indent a string (Used for recursive toString() structure dumping)

MTS_EXPORT_CORE Float interpCubic1D	(	Float	p,
		const Float *	data,
		Float	min,
		Float	max,
		size_t	size
	)

Evaluate a cubic spline interpolant of a regularly sampled 1D function.

This implementation uses Catmull-Rom splines, i.e. it uses finite differences to approximate the derivatives at the endpoints of each spline segment.

Parameters:

p	Evaluation point of the interpolant
data	Floating point array containing nKnots regularly spaced evaluations in the range [a,b] of the function to be approximated.
min	Position of the first knot
max	Position of the last knot
size	Total number of knots

Returns:

The interpolated value or zero when t lies outside of [a,b]

MTS_EXPORT_CORE Float interpCubic2D	(	const Point2 &	p,
		const Float *	data,
		const Point2 &	min,
		const Point2 &	max,
		const Size2 &	size
	)

Evaluate a cubic spline interpolant of a regularly sampled 2D function.

This implementation uses a tensor product of Catmull-Rom splines, i.e. it uses finite differences to approximate the derivatives at the endpoints of each spline segment.

Parameters:

p	Evaluation point of the interpolant
data	Floating point array containing nKnots regularly spaced evaluations in the range [a,b] of the function to be approximated.
min	Position of the first knot on each dimension
max	Position of the last knot on each dimension
size	Total number of knots for each dimension

Returns:

The interpolated value or zero when t lies outside of the knot range

MTS_EXPORT_CORE Float interpCubic3D	(	const Point3 &	p,
		const Float *	data,
		const Point3 &	min,
		const Point3 &	max,
		const Size3 &	size
	)

Evaluate a cubic spline interpolant of a regularly sampled 3D function.

This implementation uses a tensor product of Catmull-Rom splines, i.e. it uses finite differences to approximate the derivatives at the endpoints of each spline segment.

Parameters:

p	Evaluation point of the interpolant
data	Floating point array containing nKnots regularly spaced evaluations in the range [a,b] of the function to be approximated.
min	Position of the first knot on each dimension
max	Position of the last knot on each dimension
size	Total number of knots for each dimension

Returns:

The interpolated value or zero when t lies outside of the knot range

bool isPowerOfTwo

(

uint32_t

i

)

[inline]

Check if an integer is a power of two (unsigned 32 bit version)

bool isPowerOfTwo

(

int32_t

i

)

[inline]

Check if an integer is a power of two (signed 32 bit version)

bool isPowerOfTwo

(

uint64_t

i

)

[inline]

Check if an integer is a power of two (64 bit version)

bool isPowerOfTwo

(

int64_t

i

)

[inline]

Check if an integer is a power of two (signed 64 bit version)

MTS_EXPORT_CORE Float lanczosSinc	(	Float	t,
		Float	tau = 2
	)

Windowed sinc filter (Lanczos envelope, tau=number of cycles)

MTS_EXPORT_CORE void latinHypercube	(	Random *	random,
		Float *	dest,
		size_t	nSamples,
		size_t	nDim
	)

Generate latin hypercube samples.

Float lerp	(	Float	t,
		Float	v1,
		Float	v2
	)		[inline]

Linearly interpolate between two values.

MTS_EXPORT_CORE Float log2

(

Float

value

)

Base-2 logarithm.

MTS_EXPORT_CORE int log2i

(

uint32_t

value

)

Base-2 logarithm (32-bit integer version)

MTS_EXPORT_CORE int log2i

(

uint64_t

value

)

Base-2 logarithm (64-bit integer version)

MTS_EXPORT_CORE std::string memString

(

size_t

size

)

Turn a memory size into a human-readable string.

MTS_EXPORT_CORE int modulo	(	int	a,
		int	b
	)

Friendly modulo function (always positive)

MTS_EXPORT_CORE Float modulo	(	Float	a,
		Float	b
	)

Friendly modulo function (always positive)

MTS_EXPORT_CORE double normalQuantile

(

double

p

)

Rational approximation to the inverse normal cumulative distribution function Source: http://home.online.no/~pjacklam/notes/invnorm/impl/sprouse/ltqnorm.c

Author:

Peter J. Acklam

bool SimpleStringOrdering::operator()	(	const std::string &	a,
		const std::string &	b
	)		const [inline]

template<typename DataType , typename IndexType >

void permute_inplace	(	DataType *	data,
		std::vector< IndexType > &	perm
	)

Apply an arbitrary permutation to an array in linear time.

This algorithm is based on Donald Knuth's book "The Art of Computer Programming, Volume 3: Sorting and Searching" (1st edition, section 5.2, page 595)

Given a permutation and an array of values, it applies the permutation in linear time without requiring additional memory. This is based on the fact that each permutation can be decomposed into a disjoint set of permutations, which can then be applied individually.

Parameters:

data	Pointer to the data that should be permuted
perm	Input permutation vector having the same size as data. After the function terminates, this vector will be set to the identity permutation.

MTS_EXPORT_CORE Float radicalInverse	(	int	b,
		size_t	i
	)

Calculate the radical inverse function.

(Implementation based on "Instant Radiosity" by Alexander Keller in Computer Graphics Proceedings, Annual Conference Series, SIGGRAPH 97, pp. 49-56.

MTS_EXPORT_CORE Float radicalInverseIncremental	(	int	b,
		Float	x
	)

Incrementally calculate the radical inverse function.

(Implementation based on "Instant Radiosity" by Alexander Keller in Computer Graphics Proceedings, Annual Conference Series, SIGGRAPH 97, pp. 49-56.

Float radToDeg

(

Float

value

)

[inline]

Table of the first 1000 prime numbers.

MTS_EXPORT_CORE void restoreFPExceptions

(

bool

state

)

Restore floating point exceptions to the specified state.

MTS_EXPORT_CORE uint32_t roundToPowerOfTwo

(

uint32_t

i

)

Round an integer to the next power of two.

MTS_EXPORT_CORE uint64_t roundToPowerOfTwo

(

uint64_t

i

)

Round an integer to the next power of two (64 bit version)

Float smoothStep	(	Float	min,
		Float	max,
		Float	value
	)		[inline]

S-shaped smoothly varying interpolation between two values.

MTS_EXPORT_CORE bool solveLinearSystem2x2	(	const Float	a[2][2],
		const Float	b[2],
		Float	x[2]
	)

Solve a 2x2 linear equation system using basic linear algebra.

MTS_EXPORT_CORE bool solveQuadratic	(	Float	a,
		Float	b,
		Float	c,
		Float &	x0,
		Float &	x1
	)

Solve a quadratic equation of the form a*x^2 + b*x + c = 0.

Returns:

true if a solution could be found

MTS_EXPORT_CORE bool solveQuadraticDouble	(	double	a,
		double	b,
		double	c,
		double &	x0,
		double &	x1
	)

Solve a double-precision quadratic equation of the form a*x^2 + b*x + c = 0.

Returns:

true if a solution could be found

MTS_EXPORT_CORE Vector sphericalDirection	(	Float	theta,
		Float	phi
	)

Convert spherical coordinates to a direction.

MTS_EXPORT_CORE Vector squareToCone	(	Float	cosCutoff,
		const Point2 &	sample
	)

Sample a vector that lies in a cone of angles.

MTS_EXPORT_CORE Float squareToConePdf

(

Float

cosCutoff

)

Solve a 2x2 linear equation system using basic linear algebra.

MTS_EXPORT_CORE Point2 squareToDisk

(

const Point2 &

sample

)

Sample a vector on a 2D disk (PDF: 1/(2 * PI))

MTS_EXPORT_CORE Point2 squareToDiskConcentric

(

const Point2 &

sample

)

Low-distortion concentric square to disk mapping by Peter Shirley (PDF: 1/(2 * PI))

MTS_EXPORT_CORE Vector squareToHemisphere

(

const Point2 &

sample

)

Sample a vector on the unit hemisphere (PDF: 1/(2 * PI), wrt. solid angles)

MTS_EXPORT_CORE Vector squareToHemispherePSA

(

const Point2 &

sample

)

Sample a vector on the unit hemisphere (PDF: cos(theta) / PI, wrt. solid angles)

MTS_EXPORT_CORE Vector squareToSphere

(

const Point2 &

sample

)

Sample a vector on the unit sphere (PDF: 1/(4 * PI), wrt. solid angles)

MTS_EXPORT_CORE Point2 squareToStdNormal

(

const Point2 &

sample

)

Sample a point on a 2D standard normal distribution (uses the Box-Muller transformation)

MTS_EXPORT_CORE Point2 squareToTriangle

(

const Point2 &

sample

)

Convert an uniformly distributed square sample into barycentric coordinates.

MTS_EXPORT_CORE void stratifiedSample1D	(	Random *	random,
		Float *	dest,
		int	count,
		bool	jitter
	)

Generate (optionally jittered) stratified 1D samples.

Parameters:

random	Source of random numbers
dest	A pointer to a floating point array with at least count entries
count	The interval [0, 1] is split into count strata
jitter	Randomly jitter the samples?

MTS_EXPORT_CORE void stratifiedSample2D	(	Random *	random,
		Point2 *	dest,
		int	countX,
		int	countY,
		bool	jitter
	)

Generate (optionally jittered) stratified 2D samples.

Parameters:

random	Source of random numbers
dest	A pointer to a floating point array
countX	The X axis interval [0, 1] is split into countX strata
countY	The Y axis interval [0, 1] is split into countY strata
jitter	Randomly jitter the samples?

MTS_EXPORT_CORE std::string timeString	(	Float	time,
		bool	precise = false
	)

Convert a time difference (in ms) to a string representation.

Parameters:

time	Time value in milliseconds
precise	When set to true, a higher-precision string representation is generated.

MTS_EXPORT_CORE std::vector<std::string> tokenize	(	const std::string &	string,
		const std::string &	delim
	)

Given a list of delimiters, tokenize a std::string into a vector of strings.

MTS_EXPORT_CORE Point2 toSphericalCoordinates

(

const Vector &

v

)

Convert a direction to spherical coordinates.

MTS_EXPORT_CORE std::string trim

(

const std::string &

str

)

Trim spaces (' ', '\n', '\r', '\t') from the ends of a string.

template<typename T , typename U >

T union_cast

(

const U &

val

)

[inline]

Cast between types that have an identical binary representation.

template<typename VectorType >

Float unitAngle	(	const VectorType &	u,
		const VectorType &	v
	)		[inline]

Numerically well-behaved routine for computing the angle between two unit direction vectors.

This should be used wherever one is tempted to compute the arc cosine of a dot product!

Proposed by Don Hatch at http://www.plunk.org/~hatch/rightway.php

---

Variable Documentation

const int MTS_EXPORT_CORE primeTable[primeTableSize]

Table of the first 1000 prime numbers.