...

RixShadingPlugin is a base class characterizing the requirements of a RenderMan renderer from shading plugins: RixBxdfFactory, RixDisplacementFactory, RixDisplayFilter, RixIntegratorFactory, RixLightFactory, RixLightFilter, RixLightFactory, RixPattern, RixProjectionFactory, and RixSampleFilter. These are plugins that implement services for the renderer.

...

The other plugin types using this representation are: RixBxdf, RixDisplacement, RixDisplayFilter, RixLightFilter and  RixSampleFilter. RixBxdf and RixDisplacement additionally make use of closures.Note that RixShadingPlugin

XXX* RixYYYPlugin()::CreateXXX()

...

The other plugin types using this representation are: RixIntegrator and RixLightFactory.

Closures

...

lightweightinstancelightweightinstanceLightweight instancing)Generally, the RixShadingPlugin subclass (e.g. RixPattern) will expose only a few compute methods (e.g. RixPattern::ComputeOutputParams()) that is executed once per batch of points (RixShadingContext), per plugin instance. When a specific class is used to represent the plugin instance (e.g. RixProjection), it will usually expose the compute methods itself (e.g. RixProjection::Project()).

...

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.

Note
The Init() method will only ever be called once per plugin.

Plugin instance initialization

...

RixParameterList allows for the evaluation of the plugin instance parameters via the EvalParam() method. To aid in this, it allows for the querying via RixParameterList::GetParamInfo() of whether the parameters have been unset (and are therefore at their default value), set as a uniform value, or are part of a network  connection, i.e. the parameter is computed by an upstream node in the shading graph. A network connection is understood to be a varying quantity, and its value cannot be evaluated at the time that CreateInstanceData is evoked; this is why EvalParam() will return k_RixSCInvalidDetail if the parameter is a network connection. Otherwise, EvalParam() can be used to get an understanding of the uniform, non-varying parameters that are passed to the shading instance, and these can be used to perform any precomputations as needed.

...

Anchor
synchronization synchronization

Plugin Synchronization

The Synchronize() routine allows the plugin The Synchronize() routine allows the plugin to respond to synchronization signals delivered by the renderer. This call may happen multiple times during a render session and/or during a given render.

...

• k_RixSCRenderBegin: The renderer is being initialized.
• k_RixSCRenderEnd: The renderer is about to end.
• k_RixSCInstanceEdit: Currently unused.
• k_RixSCCancel: Currently unused.
• k_RixSCCheckpointRecover: A signal that the renderer is about to restart rendering from a checkpoint. The parameter list will contain a single constant integer "increment" which contains the increment value from which the renderer will restart.
• k_RixSCCheckpointWrite: A signal that the renderer is about to write a checkpoint. The parameter list will contain two values: a constant integer "increment" indicating the increment value the renderer will write, and a constant string "reason" which contains one of three values: "checkpoint", "exiting", or "finished", indicating why the renderer is writing the checkpoint.
• k_RixSCIncrementBarrier: A signal that the rendering of an new increment is about to begin. This signal will only be received if the integrator has set wantsIncrementBarrier to true in the RixIntegratorEnvironment. The parameter list will contain a single constant integer "increment" which contains the increment value the renderer is about to render.

Plugin instance synchronization

...

• there is no synchronization message, it is always assumed to be k_RixSCRenderBegin
• the plugin instance must explicitly subscribe to this mechanism, by appropriately setting InstanceData::synchronizeHints duringCreateInstanceData()

If the plugin type doesn't use CreateInstanceData() but CreateXXX(), the created objects will sometimes expose an Edit() or Synchronize() method.

Closures synchronization

Closures are transient objects with a very short lifetime, and are re-created with such a frequency that there is no need for synchronization mechanism.

...

Because Init() and CreateInstanceData() are only called once during a rendering session, they are unable to capture edits that may have happened after the previous renderplugin instance has been initialized. In some cases, this includes edits that may have happened before the render starts, yielding counter-intuitive behaviors.

It is therefore strongly recommended for these two methods to only rely on data that was explicitly provided (e.g. the plugin instance parameter list). In particular, special care should be taken not to query options or anything related to the render state (displays, integrator environment, lpe-related quantities, etc...) for the following reasons:

...