RixLightFilter plugins modify the lighting contribution to a surface point after a light has been sampled. More...

#include <RixLightFilter.h>

Public Types
enum	FilterRadianceModifierProperty { k_Multiplier, k_MaxDistance }
	Light filters can be queried as to what effect they will have on radiance. More...

enum	LightFilterProperty { k_LinkingGroups, k_FiltersShadows, k_numLightFilterProperties }

enum	SynchronizeHints { k_None = 0x00000000, k_All = 0xFFFFFFFF }
	The renderer offers the ability to shading plugins to track custom data with every instance of the plugin reference. More...

Public Member Functions
int	GetInterface () const override

virtual void	Filter (RixLightFilterContext const lfCtx, void instanceData, int const numSamples, int const shadingCtxIndex, RtVector3 const directions, float const distances, float const lightPdfsDirect, RixBXLobeWeights *contribution)=0
	Called after light sample generation, before bxdf evaluation. More...

virtual bool	GetRadianceModifier (FilterRadianceModifierProperty property, RixLightFilterContext const lfCtx, void instanceData, float *result) const =0

virtual RixSCDetail	GetProperty (void instanceData, LightFilterProperty prop, void const *result) const =0

virtual void	ShadowFilter (RixLightFilterContext const lfCtx, void instanceData, int const numSamples, int const shadingCtxIndex, RtVector3 const directions, float const distances, RixBXLobeSampled const incidentLobeSampled, RtColorRGB *transmissions)
	Called after Filter has run and default shadow rays have been traced. More...

virtual int	GetVersion () const

virtual int	Init (RixContext &ctx, RtUString const pluginPath)=0
	In order to initialize the plugin, the renderer will call Init() once. More...

virtual void	Finalize (RixContext &ctx)=0
	Finalize() is the companion to Init(), called at the end of rendering with the expectation that any data allocated within the Init() implementation will be released. More...

virtual RixSCParamInfo const *	GetParamTable ()=0
	All shading plugins are expected to return a description of their input and output parameters via the GetParamTable() method. More...

virtual void	Synchronize (RixContext &ctx, RixSCSyncMsg syncMsg, RixParameterList const *syncParams)=0
	This method is used to deliver occasional status information from the renderer. More...

virtual void	CreateInstanceData (RixContext &rixCtx, RtUString const handle, RixParameterList const parameterList, InstanceData instanceData)
	CreateInstanceData() is called once per plugin-instance. More...

virtual void	SynchronizeInstanceData (RixContext &rixCtx, RtUString const handle, RixParameterList const instanceParams, uint32_t const editHints, InstanceData instanceData)
	SynchronizeInstanceData() will only be called if InstanceData::synchronizeHints was set to a non-zero value during the initial call to CreateInstanceData(). More...

Protected Member Functions
	RixLightFilter ()

	~RixLightFilter () override

Protected Attributes
int	m_version

Detailed Description

RixLightFilter plugins modify the lighting contribution to a surface point after a light has been sampled.

Light filters operate over a set of samples that are associated with points in a shading context. All of the array paramenters to Filter() are numSamples in length.

Any one point in the shading context may be represented more than once in these arrays if, for instance, the number of light samples provided to an integrator is greater than one. The shadingCtxIndex gives the index in the shading context corresponding to a particular sample, and can be used as an index into data retrieved from the light filter context, such as built-in and primitive variables.

Member Enumeration Documentation

◆ FilterRadianceModifierProperty

enum RixLightFilter::FilterRadianceModifierProperty

Light filters can be queried as to what effect they will have on radiance.

They should return a conservative estimate, since this is used to modifier light selection probabilities. Note that this estimate has no dependence on a shading context. The query is made at the start of rendering, when we build the light selection hierarchy. As such, the floating point result should be applicable across the entire range of influence of the light.

Enumerator
k_Multiplier
k_MaxDistance	The amount by which a light's radiance is multiplied.

◆ LightFilterProperty

enum RixLightFilter::LightFilterProperty

Enumerator
k_LinkingGroups
k_FiltersShadows
k_numLightFilterProperties

◆ SynchronizeHints

enum RixShadingPlugin::SynchronizeHints

inherited

The renderer offers the ability to shading plugins to track custom data with every instance of the plugin reference.

This is useful primarily to plugin types like Bxdf and Pattern that expect to see multiple instances. Instance data is usually a function of the instance parameters, and plugins that operate in performance sensitive conditions may "bake" an understanding of their behavior/requirements into custom representation for tracking with the instance. The instance data can be recovered from the operating context associated with the plugin type, or via inspection of the parameter list (using RixParameterList::EvalParam). Note that in the latter case, the ability to inspect the parameter list is restricted: "network" connections (i.e. upstream pattern graph inputs) cannot be evaluated at the time CreateInstanceData is invoked.

Note that CreateInstanceData() is only called once, when the plugin instance is created. As a consequence, edits happening during an interactive session can't be captured by this method. The InstanceData::synchronizeHints member allows a plugin to subscribe to a synchronization call, following some edits. In order for SynchronizeInstanceData() to be called, this member needs to be set to a non-zero value by CreateInstanceData().

Note that some quantities are not accessible anymore through the RixContext object in CreateInstanceData(), for reasons related to interactive rendering. In particular:

LPE-related quantities
Display-related quantities (e.g. resolution)
editable options should only be queried in SynchronizeInstanceData().

Additionally, a plugin can create its parameter table dynamically based on the parameters provided to each instance of the plugin. This dynamically created table should be saved in the paramtable member of InstanceData, and should be freed by the InstanceData freefunc. Generally, concrete interfaces should be preferred over dynamic interfaces due to their extra memory expense. If the paramtable member remains null, all instances will share the parameter table returned by GetParamTable. In order to prevent the renderer from filtering out dynamic parameters as bad inputs, a plugin that is using a dynamically created table should have a k_RixSCAnyType entry in its plugin parameter table.

A trivial implementation of the following methods doesn't modify the InstanceData objects provided. Plugins should consider the number of potential instances that may be produced in a worst-case render to assess the memory impact of the instance data. The renderer will free data via freefunc when it understands that the plugin instance will no longer be needed. The handle parameter the value associated with the Ri instance but may not be guaranteed to be globally unique. The instanceid parameter is optionally delivered via the parameterlist (see RI_INSTANCEID docs) and is expected (though not guaranteed) to be unique. This call might be called in multiple threads and should be re-entrant and thread-safe.

Enumerator
k_None
k_All

Constructor & Destructor Documentation

◆ RixLightFilter()

RixLightFilter::RixLightFilter ( )

inlineprotected

◆ ~RixLightFilter()

RixLightFilter::~RixLightFilter ( )

inlineoverrideprotected

Member Function Documentation

◆ CreateInstanceData()

virtual void RixShadingPlugin::CreateInstanceData	(	RixContext &	rixCtx,
		RtUString const	handle,
		RixParameterList const *	parameterList,
		InstanceData *	instanceData
	)

inlinevirtualinherited

CreateInstanceData() is called once per plugin-instance.

It may be called before other renderer options and/or plugins have been set-up. As a consequence, some quantities may not be accessible in CreateInstanceData(). For example:

LPE-related quantities
Display-related quantities (e.g. resolution)
editable options SynchronizeInstanceData() should be used to retrieve the up-to-date related quantities.

Reimplemented in RixIntegratorFactory, and RixProjectionFactory.

References PIXAR_ARGUSED.

◆ Filter()

virtual void RixLightFilter::Filter	(	RixLightFilterContext const *	lfCtx,
		void *	instanceData,
		int const	numSamples,
		int const *	shadingCtxIndex,
		RtVector3 const *	directions,
		float const *	distances,
		float const *	lightPdfsDirect,
		RixBXLobeWeights *	contribution
	)

pure virtual

Called after light sample generation, before bxdf evaluation.

Setting the contribution to zero across all lobes will disable shadow ray generation for the sample.

◆ Finalize()

virtual void RixShadingPlugin::Finalize ( RixContext & ctx )

pure virtualinherited

Finalize() is the companion to Init(), called at the end of rendering with the expectation that any data allocated within the Init() implementation will be released.

◆ GetInterface()

int RixLightFilter::GetInterface ( ) const

inlineoverridevirtual

Reimplemented from RixShadingPlugin.

References k_RixLightFilter.

◆ GetParamTable()

virtual RixSCParamInfo const* RixShadingPlugin::GetParamTable ( )

pure virtualinherited

All shading plugins are expected to return a description of their input and output parameters via the GetParamTable() method.

This returns a pointer to an array of RixSCParamInfo, containing one entry for each input and output parameter, as well as an extra empty entry to mark the end of the table. This parameter table is used by the renderer to ensure proper type checking and validate the connections of upstream and downstream nodes. As such, each entry in the table should set a name, a type (RixSCType enumeration), detail (varying vs uniform, RixSCDetail enumeration), and access (input vs output, RixSCAccess enumeration). These declarations also need to be kept in sync with the associated .args file.

◆ GetProperty()

virtual RixSCDetail RixLightFilter::GetProperty	(	void *	instanceData,
		LightFilterProperty	prop,
		void const **	result
	)		const

pure virtual

◆ GetRadianceModifier()

virtual bool RixLightFilter::GetRadianceModifier	(	FilterRadianceModifierProperty	property,
		RixLightFilterContext const *	lfCtx,
		void *	instanceData,
		float *	result
	)		const

pure virtual

◆ GetVersion()

virtual int RixShadingPlugin::GetVersion ( ) const

inlinevirtualinherited

References RixShadingPlugin::m_version.

◆ Init()

virtual int RixShadingPlugin::Init	(	RixContext &	ctx,
		RtUString const	pluginPath
	)

pure virtualinherited

In order to initialize the plugin, the renderer will call Init() once.

Even if the plugin is evoked multiple times during the render with different arguments, Init() will still be called only once during the lifetime of the render. The RixContext parameter can be used by the plugin to request any RixInterfaces services provided by the renderer. Any expensive memory allocations or operations that can be reused during the lifetime of the plugin can be performed in this routine. Upon successful initialization, this routine should return a zero status.

◆ ShadowFilter()

virtual void RixLightFilter::ShadowFilter	(	RixLightFilterContext const *	lfCtx,
		void *	instanceData,
		int const	numSamples,
		int const *	shadingCtxIndex,
		RtVector3 const *	directions,
		float const *	distances,
		RixBXLobeSampled const *	incidentLobeSampled,
		RtColorRGB *	transmissions
	)

inlinevirtual

Called after Filter has run and default shadow rays have been traced.

The transmittance values from tracing those shadow rays are provided in transmission. This method can choose to incorporate or ignore those values when computing new transmittance values.

References PIXAR_ARGUSED.

◆ Synchronize()

virtual void RixShadingPlugin::Synchronize	(	RixContext &	ctx,
		RixSCSyncMsg	syncMsg,
		RixParameterList const *	syncParams
	)

pure virtualinherited

This method is used to deliver occasional status information from the renderer.

Parameterlist contents depend upon the SyncMsg. A trivial implementation simply does nothing, ignoring all events.

◆ SynchronizeInstanceData()

virtual void RixShadingPlugin::SynchronizeInstanceData	(	RixContext &	rixCtx,
		RtUString const	handle,
		RixParameterList const *	instanceParams,
		uint32_t const	editHints,
		InstanceData *	instanceData
	)

inlinevirtualinherited

SynchronizeInstanceData() will only be called if InstanceData::synchronizeHints was set to a non-zero value during the initial call to CreateInstanceData().

This method is allowed to modify:

data (including freeing the previous pointer and allocating new memory)
datalen
freefunc
synchronizeHints

However, it is not currently possible to modify:

paramtable

Note that special care should be taken when modifying synchronizeHints, so that the plugin instance doesn't lock itself out of synchronization notifications.

Reimplemented in RixIntegratorFactory, and RixProjectionFactory.

References PIXAR_ARGUSED.

Member Data Documentation

◆ m_version

int RixShadingPlugin::m_version

protectedinherited

Referenced by RixShadingPlugin::GetVersion().

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

RixLightFilter.h

Public Types

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Member Enumeration Documentation

◆ FilterRadianceModifierProperty

◆ LightFilterProperty

◆ SynchronizeHints

Constructor & Destructor Documentation

◆ RixLightFilter()

◆ ~RixLightFilter()

Member Function Documentation

◆ CreateInstanceData()

◆ Filter()

◆ Finalize()

◆ GetInterface()

◆ GetParamTable()

◆ GetProperty()

◆ GetRadianceModifier()

◆ GetVersion()

◆ Init()

◆ ShadowFilter()

◆ Synchronize()

◆ SynchronizeInstanceData()

Member Data Documentation

◆ m_version