RixBxdfFactory Class Reference

#include <RixBxdf.h>

Inherits RixShadingPlugin.

Public Types
enum	InstanceHints {   k_TriviallyOpaque = 0, k_ComputesOpacity = 1, k_OpacityCanBeCached = 2, k_ComputesPresence = 4,   k_PresenceCanBeCached = 8, k_OpacityMask = 0x0F, k_ComputesInterior = 0x10, k_InteriorTransmission = 0x20,   k_InteriorHeterogeneous = 0x40, k_InteriorOverlapping = 0x80, k_InteriorMask = 0xF0, k_ComputesSubsurface = 0x100,   k_ComputesOpacityForAllRays = 0x200, k_BlocksVolumes = 0x400, k_ComputesPostLighting = 0x800, k_StochasticOpacityOnly = 0x1000 }
	Most Bxdfs do not require special opacity handling or support interior shading. More...
enum	{ k_TemporalParamIsProperty = 10000 }
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 int	GetInstanceHints (void *instanceData) const =0
virtual void	RegisterTemporalVolumeParams (void *instanceData, std::vector< int > &paramId) const =0
virtual RixBxdf *	BeginScatter (RixShadingContext const *, RixBXLobeTraits const &hints, RixSCShadingMode, void *parentData, void *instanceData)=0
	BeginScatter is expected to return a RixBxdf for the current ShadingContext. More...
virtual void	EndScatter (class RixBxdf *bxdf)=0
virtual RixOpacity *	BeginOpacity (RixShadingContext const *, RixSCShadingMode, void *parentData, void *instanceData)=0
	BeginOpacity creates a RixOpacity for the current shading context. More...
virtual void	EndOpacity (class RixOpacity *)=0
virtual class RixVolumeIntegrator *	BeginInterior (RixShadingContext const *, RixSCShadingMode, void *parentData, void *instanceData)=0
	BeginInterior creates a RixVolumeIntegrator for the current shading context. More...
virtual void	EndInterior (RixVolumeIntegrator *)=0
virtual class RixVolumeIntegrator *	BeginSubsurface (RixShadingContext const *, RixSCShadingMode, void *parentData, void *instanceData)=0
	BeginSubsurface creates a RixVolumeIntegrator for the current shading context. More...
virtual void	EndSubsurface (RixVolumeIntegrator *)=0
virtual float	GetIndexOfRefraction (void *instanceData) const =0
	Returns the index of refraction of the material. More...
virtual RixPostLighting *	BeginPostLighting (RixShadingContext const *, RixSCShadingMode, void *parentData, void *instanceData)
	parentData role is similar to the one of BeginScatter(). More...
virtual void	EndPostLighting (class RixPostLighting *)
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
	RixBxdfFactory ()
	~RixBxdfFactory () override

Protected Attributes
int	m_version

Member Enumeration Documentation

anonymous enum

anonymous enum

Enumerator
k_TemporalParamIsProperty

InstanceHints

enum RixBxdfFactory::InstanceHints

Most Bxdfs do not require special opacity handling or support interior shading.

These Bxdfs should implement a trivial implementation of GetInstanceHints which simply returns k_TriviallyOpaque. Bxdfs that do modulate opacity and/or require interior shading are required to override the GetInstanceHints method and return InstanceHints to the renderer in order to trigger calls to BeginOpacity and BeginInterior. Values are in the form of a bitfield for compact representation and evaluation.

As a further optimization, Bxdfs that deal with opacity or interiors may choose to change their behavior based upon their instance parameters. For example, they may opt out of opacity entirely if they can prove via inspection of the parameters that the intended result is equivalent to opaque. Bxdfs that choose to do so should "bake" this awareness into their instance data at the time of CreateInstanceData and inspect this instance data within the GetInstanceHints implementation.

Note that at the time of CreateInstanceData, Bxdfs are unable to inspect the values of pattern network inputs, therefore in cases with such inputs (i.e: RixParameterList::GetParamInfo returns k_RixSCNetworkValue) the Bxdf may have no choice but to defer inspection of the inputs until BeginOpacity or BeginInterior. At that time, the Bxdf may then choose to return NULL instead.

Enumerator
k_TriviallyOpaque
k_ComputesOpacity
k_OpacityCanBeCached
k_ComputesPresence
k_PresenceCanBeCached
k_OpacityMask
k_ComputesInterior
k_InteriorTransmission
k_InteriorHeterogeneous
k_InteriorOverlapping
k_InteriorMask
k_ComputesSubsurface
k_ComputesOpacityForAllRays
k_BlocksVolumes
k_ComputesPostLighting
k_StochasticOpacityOnly

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

RixBxdfFactory()

RixBxdfFactory::RixBxdfFactory ( )

inlineprotected

~RixBxdfFactory()

RixBxdfFactory::~RixBxdfFactory ( )

inlineoverrideprotected

Member Function Documentation

BeginInterior()

virtual class RixVolumeIntegrator* RixBxdfFactory::BeginInterior ( RixShadingContext const *  , RixSCShadingMode  , void *  parentData, void *  instanceData  )

pure virtual

BeginInterior creates a RixVolumeIntegrator for the current shading context.

BeginInterior will only be called by the renderer if GetInstanceHints returns k_ComputesInterior.

A non-NULL result indicates that for the specified shading mode, the Bxdf desires to express non-trivial volume behavior for the presumed volume interior region associated with the bound surface. A NULL result (as should be returned by a trivial implementation) supports the common case where a material has no special volume integrator. As an optimization, a Bxdf might choose to return NULL if inspection of the inputs proves that the volume is provably non-existent everywhere (even across all varying inputs).

BeginInterior may be called with one of two shading modes:

k_RixSCVolumeTransmissionQuery: this is a hint that only the GetTransmission method will be called on the RixVolumeIntegrator object created. Bxdf implementations may use this as a hint that any pattern inputs not required by the RixVolumeIntegrator::GetTransmission method can be skipped.

k_RixSCScatterQuery: this is a hint that that only the GetNearestHits method will be called on the RixVolumeIntegrator object created. Bxdf implementations should evaluate any pattern inputs relevant to the RixVolumeIntegrator::GetNearestHits method.

parentData role is similar to the one of BeginScatter().

BeginOpacity()

virtual RixOpacity* RixBxdfFactory::BeginOpacity ( RixShadingContext const *  , RixSCShadingMode  , void *  parentData, void *  instanceData  )

pure virtual

BeginOpacity creates a RixOpacity for the current shading context.

BeginOpacity will not be called by the renderer unless GetInstanceHints returns k_ComputesOpacity or k_ComputesPresence.

A non-NULL result indicates that for the Bxdf wishes to implement non-trivial opacity behavior, where a NULL result (as should be returned by a trivial implementation) implies that the material is fully present and fully opaque. As an optimization, a Bxdf may also choose to return NULL if inspection of the inputs proves that the surface is provably opaque everywhere (even across all varying inputs). For more details on opacity, refer to RixOpacity class comments.

BeginOpacity may be called with one of two shading modes:

k_RixSCPresenceQuery: this is a hint that only the GetPresence method will be called on the RixOpacity object created. Bxdf implementations may use this as a hint that any pattern inputs not required by the RixOpacity::GetPresence method can be skipped.

k_RixSCOpacityQuery: this is a hint that both the GetPresence or GetOpacity methods will be called on the RixOpacity object created. Bxdf implementations should evaluate all pattern inputs relevant to both GetPresence and GetOpacity in this shading mode.

parentData role is similar to the one of BeginScatter().

BeginPostLighting()

virtual RixPostLighting* RixBxdfFactory::BeginPostLighting ( RixShadingContext const *  , RixSCShadingMode  , void *  parentData, void *  instanceData  )

inlinevirtual

parentData role is similar to the one of BeginScatter().

References RixVolumeIntegrator::instanceData, and PIXAR_ARGUSED.

BeginScatter()

virtual RixBxdf* RixBxdfFactory::BeginScatter ( RixShadingContext const *  , RixBXLobeTraits const &  hints, RixSCShadingMode  , void *  parentData, void *  instanceData  )

pure virtual

BeginScatter is expected to return a RixBxdf for the current ShadingContext.

The shading mode allows the factory to construct different Bxdfs for different scattering regimes (currently: surface vs volume interior). In constructing a bxdf, the factory plugin typically "samples" its bxdf input parameters via EvalParam method calls on the ShadingContext. A single factory plugin can have several RixBxdf 'sessions' opened simultaneously and in different threads. Caller of BeginScatter is expected to call RixBxdf's Release method which, in turn, should call RixBxdfFactory::EndScatter. RixBxdfFactory's subclasses should use 'placement new' atop RixShadingContext::Allocated memory for best performance.

BeginScatter may be called with one of two shading modes:

k_RixSCScatterQuery: the factory should construct a Bxdf for scattering on the surface.

k_RixSCVolumeScatterQuery: the factory should construct a Bxdf (typically a phase function) for scattering on the inside of a volume. This mode will only be used if the Bxdf also implements an interior integrator.

When using nested bxdfs in a shading network, a bxdf factory calling BeginScatter() on children bxdf factories can provide an opaque pointer, parentData. This pointer is passed as-is by the renderer, and it is the responsibility of the user shading framework to deal with constness and/or multithreading issues. When BeginScatter() is called by the renderer (on the top-level bxdf), parentData will always be nullptr.

BeginSubsurface()

virtual class RixVolumeIntegrator* RixBxdfFactory::BeginSubsurface ( RixShadingContext const *  , RixSCShadingMode  , void *  parentData, void *  instanceData  )

pure virtual

BeginSubsurface creates a RixVolumeIntegrator for the current shading context.

BeginSubsurface will only be called by the renderer if GetInstanceHints returns k_ComputesSubsurface.

A non-NULL result indicates that for the specified shading mode, the Bxdf desires to express non-trivial subsurface behavior for interior region associated with the bound surface. A NULL result (as should be returned by a trivial implementation) supports the common case where a material has no special volume integrator. As an optimization, a Bxdf might choose to return NULL if inspection of the inputs proves that there is no subsurface scattering (even across all varying inputs).

BeginSubsurface may be called with one of two shading modes:

k_RixSCVolumeTransmissionQuery: this is a hint that only the GetTransmission method will be called on the RixVolumeIntegrator object created. Bxdf implementations may use this as a hint that any pattern inputs not required by the RixVolumeIntegrator::GetTransmission method can be skipped.

k_RixSCScatterQuery: this is a hint that that only the GetNearestHits method will be called on the RixVolumeIntegrator object created. Bxdf implementations should evaluate any pattern inputs relevant to the RixVolumeIntegrator::GetNearestHits method.

parentData role is similar to the one of BeginScatter().

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.

EndInterior()

virtual void RixBxdfFactory::EndInterior ( RixVolumeIntegrator *  )

pure virtual

Referenced by RixVolumeIntegrator::Release().

EndOpacity()

virtual void RixBxdfFactory::EndOpacity ( class RixOpacity *  )

pure virtual

Referenced by RixOpacity::Release().

EndPostLighting()

virtual void RixBxdfFactory::EndPostLighting ( class RixPostLighting *  )

inlinevirtual

Referenced by RixPostLighting::Release().

EndScatter()

virtual void RixBxdfFactory::EndScatter ( class RixBxdf *  bxdf )

pure virtual

Referenced by RixBxdf::Release().

EndSubsurface()

virtual void RixBxdfFactory::EndSubsurface ( RixVolumeIntegrator *  )

pure virtual

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.

GetIndexOfRefraction()

virtual float RixBxdfFactory::GetIndexOfRefraction ( void *  instanceData ) const

pure virtual

Returns the index of refraction of the material.

Most materials should simply return an IOR of 1.0f.

GetInstanceHints()

virtual int RixBxdfFactory::GetInstanceHints ( void *  instanceData ) const

pure virtual

GetInterface()

int RixBxdfFactory::GetInterface ( ) const

inlineoverridevirtual

Reimplemented from RixShadingPlugin.

References k_RixBxdfFactory.

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.

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.

RegisterTemporalVolumeParams()

virtual void RixBxdfFactory::RegisterTemporalVolumeParams ( void *  instanceData, std::vector< int > &  paramId  ) const

pure virtual

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:

• RixBxdf.h