RixBxdf.h

Go to the documentation of this file.

/*
# ------------------------------------------------------------------------------
#
# Copyright (c) 2020 Pixar. All rights reserved.
#
# The information in this file (the "Software") is provided for the exclusive
# use of the software licensees of Pixar ("Licensees").  Licensees have the
# right to incorporate the Software into other products for use by other
# authorized software licensees of Pixar, without fee. Except as expressly
# permitted herein, the Software may not be disclosed to third parties, copied
# or duplicated in any form, in whole or in part, without the prior written
# permission of Pixar.
#
# The copyright notices in the Software and this entire statement, including the
# above license grant, this restriction and the following disclaimer, must be
# included in all copies of the Software, in whole or in part, and all permitted
# derivative works of the Software, unless such copies or derivative works are
# solely in the form of machine-executable object code generated by a source
# language processor.
#
# PIXAR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL
# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL PIXAR BE
# LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION
# OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
# CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.  IN NO CASE WILL
# PIXAR'S TOTAL LIABILITY FOR ALL DAMAGES ARISING OUT OF OR IN CONNECTION WITH
# THE USE OR PERFORMANCE OF THIS SOFTWARE EXCEED $50.
#
# Pixar
# 1200 Park Ave
# Emeryville CA 94608
#
# ------------------------------------------------------------------------------
*/

#ifndef RixBxdf_h
#define RixBxdf_h

#include <cstddef>         // for NULL
#include <vector>          // for vector
#include "RixBxdfLobe.h"   // for RixBXLobeTraits, etc
#include "RixShading.h"    // for RixSCShadingMode, etc
#include "prmanapi.h"      // for PRMANEXPORT, PRMAN_INLINE
#include "RiTypesHelper.h" // for RtColorRGB, etc

class RixBxdf;
class RixIntegratorContext;
class RixLightingServices;
class RixOpacity;
class RixRNG;
class RixVolumeIntegrator;
class RixPostLighting;
struct RtRayGeometry;

// RixBXEvaluateDomain tells Integrator the domain over which
// lighting/connecting/merging needs to be done.
// Reflect/Front = light samples are from the side the ray came from
// Transmit/Back = light samples are opposite the side the ray came from
// Outside = light samples are from the side the surface normal points into
// Inside =  light samples are from the side the surface normal points away from
// The difference between Both and Volume is whether there's a cosine
// term (for surfaces) or not (for volumes).
enum RixBXEvaluateDomain
{
    // clang-format off
    k_RixBXEmptyDomain     = 0, // black hole (possibly emissive)

    // Elementary subdomains
    // V = view , L = light/connect/merge, N = normal, ------ = surface
    k_RixBXOutsideReflect  = 1, // V\ N /L
                                //----------
                                //

    k_RixBXOutsideTransmit = 2, //    N /L
                                //----------
                                // V/

    k_RixBXInsideReflect   = 4, //    N
                                //----------
                                // V/    \L

    k_RixBXInsideTransmit  = 8, // V\ N
                                //----------
                                //       \L

    // Common domains
    k_RixBXReflect  = (k_RixBXInsideReflect | k_RixBXOutsideReflect),   // 4 | 1 = 5
    k_RixBXTransmit = (k_RixBXInsideTransmit | k_RixBXOutsideTransmit), // 8 | 2 = 10
    // for reference to v19/20 shaders, these are equivalent
    // k_RixBXFront =  k_RixBXReflect,
    // k_RixBXBack  =  k_RixBXTransmit,
    k_RixBXBoth     = (k_RixBXReflect | k_RixBXTransmit)              , // 5 | 10 = 15
    k_RixBXOutside  = (k_RixBXOutsideReflect | k_RixBXOutsideTransmit), // 1 | 2 = 3
    k_RixBXInside   = (k_RixBXInsideReflect | k_RixBXInsideTransmit),   // 4 | 8 = 12

    k_RixBXVolume   = 16 // light from all directions
                        // clang-format on
};

PRMAN_INLINE bool RixVisibleToDomain(RixBXEvaluateDomain domain, RtVector3 const& L,
                                     RtVector3 const& N, RtVector3 const& V)
{
    // we've been told to sample everything, so don't reject
    if (domain & k_RixBXVolume || domain == k_RixBXBoth) return true;
    if (domain == k_RixBXEmptyDomain) return false;
#if 0
    // reference implementation
    float dpL = L.Dot(N);
    float dpV = N.Dot(V);

    switch(domain){
    case k_RixBXOutsideTransmit: // 2
        return (dpL > 0.0f && dpV < 0.0f);
        break;
    case k_RixBXOutsideReflect:  // 1
        return (dpL > 0.0f && dpV > 0.0f);
        break;
    case k_RixBXInsideTransmit:  // 8
        return (dpL < 0.0f && dpV > 0.0f);
        break;
    case k_RixBXInsideReflect:   // 4
        return (dpL < 0.0f && dpV < 0.0f);
        break;
    case k_RixBXInside:          // 12
        return (dpL < 0.0f);
        break;
    case k_RixBXOutside:         // 3
        return (dpL > 0.0f);
        break;
    case k_RixBXReflect:         // 5
        return ((dpL > 0.0f) != (dpV < 0.0f));
        break;
    case k_RixBXTransmit:        // 10
        return ((dpL > 0.0f) == (dpV < 0.0f));
        break;
    case k_RixBXOutsideTransmit | k_RixBXInsideReflect:   // 2 | 4  = 6
        return ((dpL > 0.0f && dpV < 0.0f) || (dpL < 0.0f && dpV < 0.0f));
        break;
    case k_RixBXOutsideReflect | k_RixBXInsideTransmit:   // 1 | 8 = 9
        return ((dpL > 0.0f && dpV > 0.0f) || (dpL < 0.0f && dpV > 0.0f));
        break;
    case k_RixBXOutsideTransmit | k_RixBXOutsideReflect | k_RixBXInsideReflect:  // 2 | 1 | 4 = 7
        return ((dpL > 0.0f && dpV < 0.0f) || (dpL > 0.0f && dpV > 0.0f) || 
                (dpL < 0.0f && dpV < 0.0f));
        break;
    case k_RixBXOutsideReflect | k_RixBXInsideTransmit | k_RixBXInsideReflect:   // 1 | 8 | 4 = 13
        return ((dpL > 0.0f && dpV > 0.0f) || (dpL < 0.0f && dpV > 0.0f) || 
                (dpL < 0.0f && dpV < 0.0f));
        break;
    case k_RixBXOutsideTransmit | k_RixBXInsideTransmit | k_RixBXInsideReflect:  // 2 | 8 | 4 = 14
        return ((dpL > 0.0f && dpV < 0.0f) || (dpL < 0.0f && dpV > 0.0f) || 
                (dpL < 0.0f && dpV < 0.0f));
        break;
    case k_RixBXOutsideReflect | k_RixBXOutsideTransmit | k_RixBXInsideTransmit: // 1 | 2 | 8 = 11
        return ((dpL > 0.0f && dpV > 0.0f) || (dpL > 0.0f && dpV < 0.0f) || 
                (dpL < 0.0f && dpV > 0.0f));
        break;
    default:
        return false;
    }
#else
    float dpL = L.Dot(N);
    if (domain == k_RixBXInside || domain == k_RixBXOutside)
    {
        // We can avoid the dot product with V in these two cases
        if (domain == k_RixBXOutside) return (dpL > 0.0f);
        if (domain == k_RixBXInside) return (dpL < 0.0f);
    }
    else
    {
        float dpV = N.Dot(V);
        bool valid = false;
        // clang-format off
        valid = valid || 
            ((domain & k_RixBXOutsideTransmit) && (dpL > 0.0f && dpV < 0.0f));
        valid = valid || 
            ((domain & k_RixBXOutsideReflect)  && (dpL > 0.0f && dpV > 0.0f));
        valid = valid || 
            ((domain & k_RixBXInsideTransmit)  && (dpL < 0.0f && dpV > 0.0f));
        valid = valid || 
            ((domain & k_RixBXInsideReflect)   && (dpL < 0.0f && dpV < 0.0f));
        return valid;
        // clang-format on
    }
#endif
    return true;
}

// RixBXTransportTrait tells Bxdf the subset of light transport to consider.
enum RixBXTransportTrait
{
    k_RixBXDirectLighting = 1 << 0,    // (direct lighting samples only)
    k_RixBXIndirectLighting = 1 << 1,  // (indirect lighting samples only)
    k_RixBXAnyLighting = k_RixBXDirectLighting | k_RixBXIndirectLighting
};

// Tells whether ray end points lies in volume or on boundary(interface)
enum RixBXRayFlags
{
    k_RixBXBothEndsInVolume = 0,
    k_RixBXOriginOnBoundary = 1,
    k_RixBXEndOnBoundary = 2,
    k_RixBXBothEndsOnBoundary = 3
};

class RixBxdfFactory : public RixShadingPlugin
{
public:
    int GetInterface() const override
    {
        return k_RixBxdfFactory;
    }

    enum InstanceHints
    {
        // clang-format off
        k_TriviallyOpaque       = 0,

        // returns RixOpacity for opacity
        k_ComputesOpacity       = 1,
        // do not set unless k_ComputesOpacity is set
        k_OpacityCanBeCached    = 2,

        // returns RixOpacity for presence
        k_ComputesPresence      = 4,
        // do not set unless k_ComputesPresence is set
        k_PresenceCanBeCached   = 8,

        k_OpacityMask           = 0x0F,

        // has interior integration requirements
        k_ComputesInterior      = 0x10,
        // supports transmission
        k_InteriorTransmission  = 0x20,
        // requires volume, not surface, primvars
        k_InteriorHeterogeneous = 0x40, 
        // supports overlapping of interiors
        k_InteriorOverlapping   = 0x80,
        //
        k_InteriorMask          = 0xF0,
        // subsurface interior integration
        k_ComputesSubsurface    = 0x100,

        // computes opacity for camera/indirect rays too
        k_ComputesOpacityForAllRays = 0x200,

        // blocks volumes. Will only have an effect if
        // kComputesInterior is also not set.
        k_BlocksVolumes         = 0x400,

        // returns RixPostLighting
        k_ComputesPostLighting  = 0x800,

        // cannot support non-stochastic opacity
        k_StochasticOpacityOnly = 0x1000,

        // clang-format on
    };

    virtual int GetInstanceHints(void* instanceData) const = 0;

    // Any parameter registered with an ID higher or equal to k_TemporalParamIsProperty will be
    // evaluated using GetProperty calls instead using the same ID. Since the type cannot be
    // inferred from the param table the caller is responsible for ensuring proper type safety on
    // EvalTemporalParam calls.
    enum
    {
        k_TemporalParamIsProperty = 10000
    };
    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;

    // usually called by RixBxdf::Release()
    virtual void EndScatter(class RixBxdf* bxdf) = 0;

    virtual RixOpacity* BeginOpacity(RixShadingContext const*, RixSCShadingMode, void* parentData,
                                     void* instanceData) = 0;

    virtual void EndOpacity(class RixOpacity*) = 0;

    virtual class RixVolumeIntegrator* BeginInterior(RixShadingContext const*, RixSCShadingMode,
                                                     void* parentData, void* instanceData) = 0;

    virtual void EndInterior(RixVolumeIntegrator*) = 0;

    virtual class RixVolumeIntegrator* BeginSubsurface(RixShadingContext const*, RixSCShadingMode,
                                                       void* parentData, void* instanceData) = 0;

    virtual void EndSubsurface(RixVolumeIntegrator*) = 0;

    virtual float GetIndexOfRefraction(void* instanceData) const = 0;

    virtual RixPostLighting* BeginPostLighting(RixShadingContext const*, RixSCShadingMode,
                                               void* parentData, void* instanceData)
    {
        PIXAR_ARGUSED(parentData);
        PIXAR_ARGUSED(instanceData);

        return NULL;
    }

    virtual void EndPostLighting(class RixPostLighting*)
    {}

protected:
    RixBxdfFactory() : RixShadingPlugin(k_RixShadingVersion)
    {}
    ~RixBxdfFactory() override
    {}
};

// RixBxdf holds all state computed by BeginScatter, including
// the RixShadingContext.
class RixBxdf
{
public:
    RixBxdf(RixShadingContext const* sCtx, RixBxdfFactory* factory)
        : shadingCtx(sCtx), bxdfFactory(factory)
    {}

    virtual ~RixBxdf()
    {}

    RixShadingContext const* GetShadingCtx()
    {
        return shadingCtx;
    }
    RixBxdfFactory* GetBxdfFactory()
    {
        return bxdfFactory;
    }

    // The domain over which this Bxdf evaluates samples. Note
    // that it may Generate discrete samples in any direction, this only
    // tells where incoming samples could Evaluate to non-zero.
    virtual RixBXEvaluateDomain GetEvaluateDomain() = 0;

    // The types of samples this BxdfEvaluator can generate.
    virtual void GetAggregateLobeTraits(RixBXLobeTraits* t) = 0;

    PRMAN_INLINE RixBXLobeTraits GetAllLobeTraits()
    {
        RixBXLobeTraits t;
        this->GetAggregateLobeTraits(&t);
        return t;
    }

    // Bxdfs can be queried for general material properties to
    // facilitate integration tasks.  Bxdfs should return
    // k_RixSCInvalidDetail if a particular property is unsupported.
    // If a property is supported Bxdf should return k_RixSCUniform or
    // k_RixSCVarying according to the detail of the result. A trivial
    // implementation that supports no properties of any sort should
    // simply return k_RixSCInvalidDetail.
    enum BxdfProperty
    {
        k_Albedo,      // RtColorRGB
        k_MaterialIor  // float
    };
    virtual RixSCDetail GetProperty(BxdfProperty, void const** result) const = 0;

    // EmitLocal: used for baked, pre-integrated, indirect results.  A
    // trivial implementation with no local emission should simply
    // return false, indicating to the integrator that 'result' is
    // untouched and that the integrator should not do anything with
    // the results. For bxdfs that do have local emission, they should
    // return true and write shadingCtx->numPts colors to the 'result'
    // array.  The integrator will then include the returned colors in
    // the direct lighting for the geometry.
    virtual bool EmitLocal(RtColorRGB* result) = 0;

    virtual void GenerateSample(RixBXTransportTrait transportTrait,
                                RixBXLobeTraits const* lobesWanted, RixRNG* rng,
                                RixBXLobeSampled* lobesSampled, RtVector3* directions,
                                RixBXLobeWeights& weights, float* forwardPdfs, float* reversePdfs,
                                RtColorRGB* compTrans = NULL) = 0;

    virtual void EvaluateSample(RixBXTransportTrait transportTrait,
                                RixBXLobeTraits const* lobesWanted, RixRNG* rng,
                                RixBXLobeTraits* lobesEvaluated,  
                                RtVector3 const* directions,
                                RixBXLobeWeights& weights, float* forwardPdfs,
                                float* reversePdfs) = 0;

    // EvaluateSamplesAtIndex:
    //  Do multiple evals at a single shading point. Also see the documentation
    //  above for EvaluateSample().
    virtual void EvaluateSamplesAtIndex(RixBXTransportTrait transportTrait,
                                        RixBXLobeTraits const& lobesWanted, RixRNG* rng, int index,
                                        int numSamples,
                                        RixBXLobeTraits* lobesEvaluated,
                                        RtVector3 const* directions, RixBXLobeWeights& weights,
                                        float* forwardPdfs, float* reversePdfs) = 0;

    // Release does any cleanup that might be needed (often none and the
    // base implementation is fine) and then calls the base implementation.
    // A RixBxdf that contains another RixBxdf would need to call Release
    // on its child as part of its own Release.
    virtual void Release()
    {
        if (bxdfFactory) bxdfFactory->EndScatter(this);
    }

protected:
    RixShadingContext const* shadingCtx;
    RixBxdfFactory* bxdfFactory;
};

// RixOpacity objects are obtained from the BxdfFactory::BeginOpacity
// when it determines conditions warrant non-trivial responses to
// either or both of Presence and Opacity queries.  GetPresence
// is invoked when an object isn't trivially 'present' and may
// be used for radiance queries to infer "ray continuation". It is
// useful to express cutouts as, for example, a leaf shape modeled
// with a texture map. Most objects are trivially present and the
// BxdfFactory should respond to NULL RixOpacity when the
// RixSCShadingMode is k_RixSCPresenceQuery.  In the case of
// an opaque leaf, BxdfFactory should instantiate a RixOpacity
// subclass to respond to GetPresence requests and the
// "presence closure" should be constructed with the minimum
// state required to respond to this request.  If our example
// leaf is opaque for shadowing, the BxdfFactory should respond
// to BeginOpacity requests with NULL for k_RixSCTransmissionQuery.
// But if the shadow of the leaf wants leaf coloration, BxdfFactory
// should produce a RixOpacity subclass that combines the effects
// of presence and coloration into a single opacity value.  Since
// opacity can be colored, keep in mind that it is the inverse of
// transparency and user interfaces usually  prefer to present
// a transparency color to the user.
//
class RixOpacity
{
public:
    RixOpacity(RixShadingContext const* sCtx, RixBxdfFactory* factory)
        : shadingCtx(sCtx), bxdfFactory(factory)
    {}
    virtual ~RixOpacity()
    {}
    RixBxdfFactory* GetBxdfFactory()
    {
        return bxdfFactory;
    }
    RixShadingContext const* GetShadingCtx()
    {
        return shadingCtx;
    }

    virtual bool GetPresence(float* result) = 0;

    virtual bool GetOpacity(RtColorRGB* result) = 0;

    virtual void Release()
    {
        if (bxdfFactory) bxdfFactory->EndOpacity(this);
    }

protected:
    RixShadingContext const* shadingCtx;
    RixBxdfFactory* bxdfFactory;
};

// RixVolumeIntegrators can be obtained from the BxdfFactory at
// the hit point where a ray enters an interior region.
// A VolumeIntegrator can be seen as a delegate for the real
// IntegratorCtx that implements special behavior behind the
// GetNearestHits and GetTransmission methods.  The idea is
// that the integration complexity in a volume region can be
// hidden from the outside world by reducing more complex
// light-paths into a single measurement of energy thruput,
// transmission, coupled with potentially distinct shading
// contexts to capture light transfer into the volume region.
// VolumeIntegrators can either be built-in or compiled-in to
// a bxdf.  In the former case, a reference to an instance of
// a VolumeIntegrator should be obtained from the RixShadingContext.
// To support pre-constructed builtin VolumeIntegrators we offer
// a generic method to pass instance parameters to the integrator.
// Typically builtin VolumeIntegrators define a struct comprised of
// the parameters it requires from the enclosing bxdf factory.
// The memory for (and evaluation of) the parameters is the responsibility
// of the enclosing bxdf. This extra dance is required to diminish
// the likelihood of disruption caused by the addition of new parameters
// by plugin/builtin volume integrators. In the direct-linked case
// clients can bypass the SetParameters convenience routines in
// favor of direct constructor.
class RixVolumeIntegrator
{
public:
    RixVolumeIntegrator(RixShadingContext const* sCtx, RixBxdfFactory* f, void* _instanceData)
        : bxdfFactory(f),
          instanceData(_instanceData),
          params(NULL),
          surfaceCtx(sCtx),
          volumeCtx(NULL)
    {}
    virtual ~RixVolumeIntegrator()
    {}

    // Interfaces to obtain the shading context is slightly different for
    // volume integrators compared with bxdfs. There are two contexts for
    // shading contexts; one representing the volume "surface" (the interface
    // for the volume) and one for the volume interior. The surface context
    // can be obtained by using GetShadingCtx. The returned context can never
    // be NULL. To obtain a shading context for volume interiors, use
    // GetVolumeShadingCtx.
    RixShadingContext const* GetShadingCtx() const
    {
        return surfaceCtx;
    }

    RixShadingContext* GetVolumeShadingCtx() const
    {
        return volumeCtx;
    }

    RixBxdfFactory* GetBxdfFactory() const
    {
        return bxdfFactory;
    }

    // This method should be used with caution. In most circumstances, the factory that is set by
    // the constructor should suffice and should not need to be overriden. The only known situation
    // which requires the use of this method involves nested Bxdfs, when an outer RixBxdfFactory's
    // implementation of BeginInterior delegates to a nested inner RixBxdfFactory's implementation
    // of BeginInterior. In this situation, it may be appropriate for the outer RixBxdfFactory
    // to override the volume integrator's bxdf factory with this method, in order to guarantee
    // that the renderer can correctly find the outer RixBxdfFactory for calls to BeginScatter().
    //
    //     RixVolumeIntegrator* OuterFactory::BeginInterior(...) {
    //         RixBxdfFactory* innerFactory = ...;
    //         RixVolumeIntegrator* integrator = innerFactory->BeginInterior(...);
    //         if (integrator) {
    //             integrator->SetBxdfFactory(this); // factory override
    //         }
    //         return integrator;
    //     }
    void SetBxdfFactory(RixBxdfFactory* factory)
    {
        bxdfFactory = factory;
    }

    void* GetInstanceData() const
    {
        return instanceData;
    }

    // Same caveats for SetBxdfFactory() apply to SetInstanceData() - it is likely only useful for
    // nested Bxdf situations.
    void SetInstanceData(void* data)
    {
        instanceData = data;
    }

    virtual void SetParameters(void const* subclassParams)
    {
        params = subclassParams;
    }

    class IntegratorDelegate
    {
    public:
        virtual void PerformDirectLighting(RixShadingContext const&,
                                           RixBXLobeTraits const* lobesWanted, int step) = 0;

    protected:
        virtual ~IntegratorDelegate()
        {}
    };

    virtual void Release()
    {
        if (bxdfFactory) bxdfFactory->EndInterior(this);
    }

    // Volumes can be queried for general material properties to
    // facilitate integration tasks. Volumes should return
    // k_RixSCInvalidDetail if a particular property is unsupported.
    // If a property is supported the volume should return
    // k_RixSCUniform or k_RixSCVarying according to the detail of the
    // result.
    enum VolumeProperty
    {
        k_DensityType,              // int - value should be one of
                                    // k_DensityFloat/k_DensityColor
        k_DensityFloat,             // float
        k_DensityColor,             // RtColorRGB
        k_MaxDensity,               // float
        k_Velocity,                 // RtFloat3
        k_NontemporalDensityFloat,  // float
        k_NontemporalDensityColor,  // RtColorRGB
        k_DensityFloatId,           // param id for float density
        k_DensityColorId,           // param id for color density
        k_Emission,                 // RtColorRGB
    };
    virtual RixSCDetail GetProperty(VolumeProperty, void const** /* result */) const
    {
        // Note: currently we offer a default implementation.  We may
        // choose to enforce implementing this in the future so we
        // encourage you to implement this method.
        return k_RixSCInvalidDetail;
    }

    //  Begin/EndVolumeSampling: can be called by a volume integrator
    //  to obtain a mutable shading context for the purposes of
    //  sampling its volume region. The resulting shading context
    //  has the same size as its creator context. Two options
    //  for cleanup are offered.  If the volume integrator wishes
    //  to expose/publicize a new shading context to the primary
    //  integrator, it should set exposeVol to a non-NULL
    //  RixBXLobeTraits pointer (which usually points to the same
    //  RixBXLobeTraits passed to the interior's GetNearestHits
    //  method). The optional membership array can be used to
    //  communicate the subset of points on the current shading
    //  context that should be conveyed to the new one.  A non-zero
    //  value signals the membership request in a new context. If
    //  NULL, all points will be used to construct a new shading
    //  context. In this usage, the return result will be a distinct
    //  shading context appropriate for use by the primary
    //  integrator. If exposeVol is NULL, the the result is NULL and
    //  internal volume sampling state is released.
    RixShadingContext* BeginVolumeSampling()
    {
        const RixShadingContext* sCtx = GetShadingCtx();
        RixShadingContext* newCtx = sCtx->BeginVolumeSampling();
        volumeCtx = newCtx;
        return volumeCtx;
    }

    RixShadingContext const* EndVolumeSampling(RixBXLobeTraits const* exposeVol = NULL,
                                               int const* membership = NULL)
    {
        const RixShadingContext* sCtx = GetShadingCtx();
        const RixShadingContext* newCtx = sCtx->EndVolumeSampling(volumeCtx, exposeVol, membership);
        volumeCtx = NULL;

        return newCtx;
    }

    virtual void GetNearestHits(int numRays, RtRayGeometry const* rays, RixRNG* rng,
                                RixBXLobeTraits const& lobesWanted, RixIntegratorContext& iCtx,
                                RixLightingServices* lightingServices,
                                // results: (per-ray transmission deposited
                                //  on resulting ShadingContexts'
                                //  transmission field). Inscattered
                                //  radiance can be splatted directly to
                                //  the screen.
                                IntegratorDelegate* lcb, int* numShadingCtxs,
                                RixShadingContext const** shadingCtxs,
                                // optional inputs:
                                RtUString const subset = US_NULL,
                                RtUString const excludeSubset = US_NULL, bool isLightPath = false,
                                RtHitSides hitSides = k_SidesBoth, bool isPrimary = false) = 0;

    // We provide a default implementation of GetTransmission because
    // some volume integrators may be opaque to transmission rays.
    // This occurs when the only supported light transport mode is indirect.
    // In this case, the volume integrator's associated bxdffactory may
    // select to return a NULL volume integrator for transmission queries.
    virtual void GetTransmission(int numRays, RtRayGeometry const* rays, RixRNG* rng,
                                 RixIntegratorContext& iCtx, RtColorRGB* transmissions,
                                 // optional output
                                 RtColorRGB* emission,
                                 // optional input;
                                 RtUString const subset = US_NULL,
                                 RtUString const excludeSubset = US_NULL)
    {
        PIXAR_ARGUSED(rays);
        PIXAR_ARGUSED(rng);
        PIXAR_ARGUSED(iCtx);
        PIXAR_ARGUSED(emission);
        PIXAR_ARGUSED(subset);
        PIXAR_ARGUSED(excludeSubset);
        for (int i = 0; i < numRays; ++i)
        {
            transmissions[i] = RtColorRGB(0.0f);
        }
    }

protected:
    RixBxdfFactory* bxdfFactory;
    void* instanceData;
    void const* params;

private:
    RixShadingContext const* surfaceCtx;
    RixShadingContext* volumeCtx;
};

class RixPostLighting
{
public:
    RixPostLighting(RixShadingContext const* sCtx, RixBxdfFactory* factory)
        : shadingCtx(sCtx), bxdfFactory(factory)
    {}

    virtual ~RixPostLighting()
    {}

    // Release does any cleanup that might be needed (often none and the
    // base implementation is fine) and then calls the base implementation.
    virtual void Release()
    {
        if (bxdfFactory) bxdfFactory->EndPostLighting(this);
    }

    virtual void Filter(int const numLightSamples, RtVector3 const* directions,
                        float const* distances, const RixLight** lights,
                        RixBXLobeWeights* bxdfWeights, RixBXLobeWeights* lightWeights,
                        RtColorRGB* transmissions) = 0;

protected:
    RixShadingContext const* shadingCtx;
    RixBxdfFactory* bxdfFactory;
};

// clang-format off
#define RIX_BXDFPLUGINCREATE \
    extern "C" PRMANEXPORT RixBxdfFactory* CreateRixBxdfFactory(const char* hint)

#define RIX_BXDFPLUGINDESTROY \
    extern "C" PRMANEXPORT void DestroyRixBxdfFactory(RixBxdfFactory* bxdf)
// clang-format on

#endif