...

Introduction

RixShadingPlugin is a base class characterizing the requirements of a RenderMan renderer from shading plugins.

This class provides entry points that are executed with a mix of various frequencies:

• once per rendering session
• once per render (in an interactive session, there can be multiple renders)
• once per batch of points to be shaded (i.e. RixShadingContext)
• multiple times per batch of points to be shaded

and various granularities:

• once per plugin
• once per instance of the shading plugin (as defined in the next section)
• multiple times per instance of the shading plugin

Plugin vs. Plugin instance

Here, the term instance is unfortunately overloaded, and it is important to differentiate between: an instance of a shading plugin as defined by the unique set of parameters given to the material definition, and a C++ instance which involves an actual memory allocation, construction, and destruction of an object.

Each use of a shading plugin with a different set of parameters will be considered as separate plugin instance. A render using two PxrTexture patterns (each using a different texture file parameter), will trigger the initialization of the (unique) PxrTexture plugin, and the initialization of two instances of the PxrTexture plugin (independently of the internal C++ representation chosen).

Plugin Instance C++ representation

Depending on the plugin type, plugin instances may correspond to different internal C++ structures.

RixShadingPlugin::CreateInstanceData()

Some shading plugin types can create private instance data using the CreateInstanceData() method. Instance data would typically be computed from the unique evocation parameters, supplied to CreateInstanceData() via the RixParameterList class. This occurs when the shading plugin instance is created for the first time from those parameters (e.g. at the time a material definition is created (i.e. very early on in a render)).

Using these parameters, plugins may bake a cached understanding of their behavior, requirements, or even precomputed results into a private representation that the renderer will automatically track with the instance and supply back to the plugin methods. This allows the plugin to cache and therefore avoid repeated computations with each new lightweight instantiation. In this case, the instance data is essentially a C++ structure representing one instance of the plugin.

If the shading plugin does create instance data, it should be stored in InstanceData::data. If the data requires non-trivial deletion, InstanceData::freefunc should be set to a function that the renderer will invoke when the plugin instance will no longer be needed. A trivial implementation of CreateInstanceData() produces no instance data and returns without modifying any member of the provided InstanceData structure.

For example, the RixPattern plugin type uses this mechanism:

• RixPattern::CreateInstanceData(..., RixParameterList const*, InstanceData*)
• RixPattern::ComputeOutputParams(RixShadingContext*, RtPointer data, ...)

The other plugin types using this representation are: RixDisplacement, RixLightFilter, RixDisplayFilter, RixSampleFilter, and RixBxdf. (with some subtleties in RixBxdf, see the closure section).

RixXXXPlugin()::CreateXXX()

Some other shading plugin types use a different mechanism instead of CreateInstanceData(). Generally, the RixShadingPlugin sub-class associated with the plugin type will expose a CreateXXX() method, used to build a new C++ object. In this case, the C++ object is a direct representation of the plugin instance. Generally, the render will then call methods on the newly minted C++ object, instead of using RixShadingPlugin methods and passing an instance data pointer.

For example, the RixProjection plugin type uses this mechanism:

• RixProjection* RixProjectionFactory::CreateProjection(..., RixParameterList const*)
• RixProjection::Project(RixProjectionContext&)

The other plugin types using this representation are: RixLightFactory.

the base class for RixBxdfFactory, RixDisplacementFactory, RixDisplayFilter, RixIntegrator, RixLightFilter, RixLightFactory, RixPattern, RixProjection, and RixSampleFilter. These are plugins that implement services for the renderer.

Here, it is important to distinguish between two types of plugins: ones that need to create short-lived lightweight instances during the course of a render, and ones that do not. RixBxdf, RixDisplacement, and RixLight represent lightweight instances that may be created many times during the course of a single render, and therefore are not directly subclasses of RixShadingPlugin. Instead, instancees of those classes are returned by the appropriate Factory (e.g. RixBxdfFactory), with the Factory itself being the subclass of RixShadingPlugin.

RixIntegrator, RixDisplayFilter, RixLightFilter, RixPattern, RixProjection, and RixSampleFilter do not create many lightweight instances. As such, these classes are directly subclasses of RixShadingPlugin.

All RixShadingPlugins share common methods related to initialization, synchronization with the renderer, and management of lightweight instances.

Anchor
initialization initialization

Initialization

...