...

Generally, there is one shading plugin instance of a RixLightFilter per bound RiLightFilter (RIB) request. This instance may be active in multiple threads simultaneously.

The RIX_LIGHTFILTERPLUGINCREATE() macro defines the CreateRixLightFilter() function, which is called by the renderer to create an instance of the light filter plugin. Generally, the implementation of this method should simply return a new allocated copy of your light filter class. Similarly, the RIX_LIGHTFILTERPLUGINDESTROY() macro defines the DestroyRixLightFilter() function called by the renderer to delete an instance of the light filter plugin; a typical implementation of this method is to delete the passed in light filter pointer:

RIX_LIGHTFILTERPLUGINCREATE
{
    return new MyLightFilter();
}

RIX_LIGHTFILTERPLUGINDESTROY
{
    delete ((MyLightFilter*)filter);
}

RixLightFilter::Filter()

Filter is where the work is done.

...

RixSCDetail PxrGobo::GetProperty(
    RtConstPointer instanceData, LightFilterProperty property, void const** result) const
{
    myData* data = (myData*)instanceData;

    if (RixLightFilter::k_LinkingGroups == property)
    {
        (*result) = &data->m_linkingGroups;
        return k_RixSCUniform;
    }
    return k_RixSCInvalidDetail;
}

GetProperty() is an extensible API through which the renderer may query the plugin.  The list of valid queries are enumerated in LightFilterProperty.  If a plugin can answer the query, it fills in result and returns k_RixSCUniform.  Otherwise GetProperty should return k_RixSCInvalidDetail.  The example given shows how the plugin returns the unique string for the linking groups to which the light filter belongs.

RixLightFilter::GetRadianceModifier()

bool PxrMyLightFilter::GetRadianceModifier(
    FilterRadianceModifierProperty property,
    RixLightFilterContext const* lfCtx,
    RtConstPointer instanceData,
    float* result) const
{
    *result = m_attenuation;
    return true;
}

GetRadianceModifier() returns a single float representing how much the filter modulates the light emitted from a light source.  Not all filters attenuate or amplify the light signal; those plugins would return false and not modify result.

Instance Data

For a detailed discussion of instance data, see lightweight instancing services.  When the CreateInstanceData routine is called, the plugin has access to the parameter list of the light filter and can create arbitrary data that is stored by the renderer and supplied as the instanceData pointer during filtering. This should be uniform data that can be accessed by multiple threads simultaneously.  Pre-processing the parameter list is an important performance optimization.  A light filter will be invoked for every surface-to-light interaction, and in a production-level shot there can be billions of these events.

...