RixVolumeIntegrators can be obtained from the BxdfFactory at the hit point where a ray enters an interior region. More...

#include <RixBxdf.h>

Inherited by RixSSDiffusion, and RixSSPathTraced.

Classes
class	IntegratorDelegate

Public Types
enum	VolumeProperty { k_DensityType, k_DensityFloat, k_DensityColor, k_MaxDensity, k_Velocity, k_NontemporalDensityFloat, k_NontemporalDensityColor, k_DensityFloatId, k_DensityColorId, k_Emission, k_ShadowDensityMultiplier }

Public Member Functions
	RixVolumeIntegrator (RixShadingContext const sCtx, RixBxdfFactory f, void *_instanceData)

virtual	~RixVolumeIntegrator ()

RixShadingContext const *	GetShadingCtx () const
	Interfaces to obtain the shading context is slightly different for volume integrators compared with bxdfs. More...

RixShadingContext *	GetVolumeShadingCtx () const
	Interfaces to obtain the shading context is slightly different for volume integrators compared with bxdfs. More...

RixBxdfFactory *	GetBxdfFactory () const

void	SetBxdfFactory (RixBxdfFactory *factory)
	This method should be used with caution. More...

void *	GetInstanceData () const

void	SetInstanceData (void *data)
	This method should be used with caution. More...

virtual void	SetParameters (void const *subclassParams)

virtual void	Release ()

virtual RixSCDetail	GetProperty (VolumeProperty, void const **) const
	Volumes can be queried for general material properties to facilitate integration tasks. More...

RixShadingContext *	BeginVolumeSampling ()
	BeginVolumeSampling can be called by a volume integrator to obtain a mutable shading context for the purposes of sampling its volume region. More...

RixShadingContext const *	EndVolumeSampling (RixBXLobeTraits const exposeVol=NULL, int const membership=NULL)

virtual void	GetNearestHits (int numRays, RtRayGeometry const rays, RixRNG rng, RixBXLobeTraits const &lobesWanted, RixIntegratorContext &iCtx, RixLightingServices lightingServices, IntegratorDelegate lcb, int numShadingCtxs, RixShadingContext const *shadingCtxs, RtUString const subset=US_NULL, RtUString const excludeSubset=US_NULL, bool isLightPath=false, RtHitSides hitSides=k_SidesBoth, bool isPrimary=false)=0

virtual void	GetTransmission (int numRays, RtRayGeometry const rays, RixRNG rng, RixIntegratorContext &iCtx, RtColorRGB transmissions, RtColorRGB emission, RtUString const subset=US_NULL, RtUString const excludeSubset=US_NULL)
	We provide a default implementation of GetTransmission because some volume integrators may be opaque to transmission rays. More...

Protected Attributes
RixBxdfFactory *	bxdfFactory

void *	instanceData

void const *	params

Detailed Description

RixVolumeIntegrators can be obtained from the BxdfFactory at the hit point where a ray enters an interior region.

A VolumeIntegrator can be seen as a delegate for the real IntegratorCtx that implements special behavior behind the GetNearestHits and GetTransmission methods. The idea is that the integration complexity in a volume region can be hidden from the outside world by reducing more complex light-paths into a single measurement of energy thruput, transmission, coupled with potentially distinct shading contexts to capture light transfer into the volume region. VolumeIntegrators can either be built-in or compiled-in to a bxdf. In the former case, a reference to an instance of a VolumeIntegrator should be obtained from the RixShadingContext. To support pre-constructed builtin VolumeIntegrators we offer a generic method to pass instance parameters to the integrator. Typically builtin VolumeIntegrators define a struct comprised of the parameters it requires from the enclosing bxdf factory. The memory for (and evaluation of) the parameters is the responsibility of the enclosing bxdf. This extra dance is required to diminish the likelihood of disruption caused by the addition of new parameters by plugin/builtin volume integrators. In the direct-linked case clients can bypass the SetParameters convenience routines in favor of direct constructor.

Member Enumeration Documentation

enum RixVolumeIntegrator::VolumeProperty

See Also: GetProperty

Enumerator
k_DensityType	int - value should be one of k_DensityFloat/k_DensityColor
k_DensityFloat	float
k_DensityColor	RtColorRGB.
k_MaxDensity	float
k_Velocity	RtFloat3.
k_NontemporalDensityFloat	float
k_NontemporalDensityColor	RtColorRGB.
k_DensityFloatId	param id for float density
k_DensityColorId	param id for color density
k_Emission	RtColorRGB.
k_ShadowDensityMultiplier	float

Constructor & Destructor Documentation

RixVolumeIntegrator::RixVolumeIntegrator	(	RixShadingContext const *	sCtx,
		RixBxdfFactory *	f,
		void *	_instanceData
	)

inline

virtual RixVolumeIntegrator::~RixVolumeIntegrator ( )

inlinevirtual

Member Function Documentation

RixShadingContext* RixVolumeIntegrator::BeginVolumeSampling ( )

inline

BeginVolumeSampling can be called by a volume integrator to obtain a mutable shading context for the purposes of sampling its volume region.

The resulting shading context has the same size as its creator context. Two options for cleanup are offered. If the volume integrator wishes to expose/publicize a new shading context to the primary integrator, it should set exposeVol to a non-NULL RixBXLobeTraits pointer (which usually points to the same RixBXLobeTraits passed to the interior's GetNearestHits method). The optional membership array can be used to communicate the subset of points on the current shading context that should be conveyed to the new one. A non-zero value signals the membership request in a new context. If NULL, all points will be used to construct a new shading context. In this usage, the return result will be a distinct shading context appropriate for use by the primary integrator. If exposeVol is NULL, the the result is NULL and internal volume sampling state is released.

References RixShadingContext::BeginVolumeSampling(), and GetShadingCtx().

RixShadingContext const* RixVolumeIntegrator::EndVolumeSampling	(	RixBXLobeTraits const *	exposeVol = `NULL`,
		int const *	membership = `NULL`
	)

inline

See Also: BeginVolumeSampling

References RixShadingContext::EndVolumeSampling(), and GetShadingCtx().

RixBxdfFactory* RixVolumeIntegrator::GetBxdfFactory ( ) const

inline

References bxdfFactory.

void* RixVolumeIntegrator::GetInstanceData ( ) const

inline

References instanceData.

virtual void RixVolumeIntegrator::GetNearestHits	(	int	numRays,
		RtRayGeometry const *	rays,
		RixRNG *	rng,
		RixBXLobeTraits const &	lobesWanted,
		RixIntegratorContext &	iCtx,
		RixLightingServices *	lightingServices,
		IntegratorDelegate *	lcb,
		int *	numShadingCtxs,
		RixShadingContext const **	shadingCtxs,
		RtUString const	subset = `US_NULL`,
		RtUString const	excludeSubset = `US_NULL`,
		bool	isLightPath = `false`,
		RtHitSides	hitSides = `k_SidesBoth`,
		bool	isPrimary = `false`
	)

pure virtual

Implemented in RixSSPathTraced, and RixSSDiffusion.

virtual RixSCDetail RixVolumeIntegrator::GetProperty	(	VolumeProperty	,
		void const **
	)		const

inlinevirtual

Volumes can be queried for general material properties to facilitate integration tasks.

Volumes should return k_RixSCInvalidDetail if a particular property is unsupported. If a property is supported the volume should return k_RixSCUniform or k_RixSCVarying according to the detail of the result.

References k_RixSCInvalidDetail.

RixShadingContext const* RixVolumeIntegrator::GetShadingCtx ( ) const

inline

Interfaces to obtain the shading context is slightly different for volume integrators compared with bxdfs.

There are two contexts for shading contexts; one representing the volume "surface" (the interface for the volume) and one for the volume interior. The surface context can be obtained by using GetShadingCtx. The returned context can never be NULL. To obtain a shading context for volume interiors, use GetVolumeShadingCtx.

Referenced by BeginVolumeSampling(), and EndVolumeSampling().

virtual void RixVolumeIntegrator::GetTransmission	(	int	numRays,
		RtRayGeometry const *	rays,
		RixRNG *	rng,
		RixIntegratorContext &	iCtx,
		RtColorRGB *	transmissions,
		RtColorRGB *	emission,
		RtUString const	subset = `US_NULL`,
		RtUString const	excludeSubset = `US_NULL`
	)

inlinevirtual

We provide a default implementation of GetTransmission because some volume integrators may be opaque to transmission rays.

This occurs when the only supported light transport mode is indirect. In this case, the volume integrator's associated bxdffactory may select to return a NULL volume integrator for transmission queries.

RixShadingContext* RixVolumeIntegrator::GetVolumeShadingCtx ( ) const

inline

Interfaces to obtain the shading context is slightly different for volume integrators compared with bxdfs.

There are two contexts for shading contexts; one representing the volume "surface" (the interface for the volume) and one for the volume interior. The surface context can be obtained by using GetShadingCtx. The returned context can never be NULL. To obtain a shading context for volume interiors, use GetVolumeShadingCtx.

virtual void RixVolumeIntegrator::Release ( )

inlinevirtual

References bxdfFactory, and RixBxdfFactory::EndInterior().

void RixVolumeIntegrator::SetBxdfFactory ( RixBxdfFactory * factory)

inline

This method should be used with caution.

In most circumstances, the factory that is set by the constructor should suffice and should not need to be overriden. The only known situation which requires the use of this method involves nested Bxdfs, when an outer RixBxdfFactory's implementation of BeginInterior delegates to a nested inner RixBxdfFactory's implementation of BeginInterior. In this situation, it may be appropriate for the outer RixBxdfFactory to override the volume integrator's bxdf factory with this method, in order to guarantee that the renderer can correctly find the outer RixBxdfFactory for calls to BeginScatter().

RixVolumeIntegrator* OuterFactory::BeginInterior(...) {
    RixBxdfFactory* innerFactory = ...;
    RixVolumeIntegrator* integrator = innerFactory->BeginInterior(...);
    if (integrator) {
        integrator->SetBxdfFactory(this); // factory override
    }
    return integrator;
}