RixShading.h

Go to the documentation of this file.

/*
# ------------------------------------------------------------------------------
#
# Copyright (c) 1986-2019 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 RixShading_h
#define RixShading_h

#include <algorithm>        // for fill_n
#include <cassert>          // for assert
#include <cstddef>          // for NULL, size_t
#include <cstring>          // for memcpy
#include <new>              // for operator new
#include <vector>           // for vector
#include "RixInterfaces.h"  // for RixContext
#include "RixRNG.h"         // for random number generation
#include "ri.hpp"           // for RtConstPointer, etc

class RixBxdf;
class RixBxdfFactory;
class RixDisplacement;
class RixDisplayFilter;
class RixDisplayServices;
class RixIntegratorContext;
class RixLPEState;
class RixLight;
class RixLightFilter;
class RixOpacity;
class RixParameterList;
class RixPostLighting;
class RixSampleFilter;
class RixVolumeIntegrator;
struct RixBXLobeTraits;
struct RixSCParamInfo;
struct RtHitPoint;
struct RtRayGeometry;

#define k_RixShadingVersion 230  // XXY  (XX: MAJOR, Y:MINOR)

enum RtHitSides
{
    k_SidesFront = 1,
    k_SidesBack = 2,
    k_SidesBoth = 3
};

enum RixShadingInterface
{
    k_RixInvalid = 0,
    k_RixPattern,
    k_RixBxdfFactory,
    k_RixIntegratorFactory,
    k_RixLightFactory,
    k_RixLightFilter,
    k_RixProjectionFactory,
    k_RixDisplacementFactory,
    k_RixSampleFilter,
    k_RixDisplayFilter,
};

enum RixSCSyncMsg
{
    // delivered in primary thread...
    k_RixSCRenderBegin,
    k_RixSCRenderEnd,
    k_RixSCInstanceEdit,       // Currently unused
    k_RixSCCancel,             // Currently unused
    k_RixSCCheckpointRecover,  // Restarting at "int increment"
                               // delivered by one (arbitrary) thread...
    k_RixSCCheckpointWrite,    // Writing "int increment" for "string reason" ("checkpoint",
                               // "exiting", or "finished").
    k_RixSCIncrementBarrier,   // Indicates "int increment" about to begin (only sent if
                               // wantsIncrementBarrier is true.)
};

class RixShadingPlugin
{
public:
    virtual int GetVersion() const
    {
        return m_version;
    }
    virtual int GetInterface() const
    {
        return k_RixInvalid;
    }

    virtual int Init(RixContext& ctx, RtUString const pluginPath) = 0;

    virtual void Finalize(RixContext& ctx) = 0;

    virtual RixSCParamInfo const* GetParamTable() = 0;

    virtual void Synchronize(RixContext& ctx, RixSCSyncMsg syncMsg,
                             RixParameterList const* syncParams) = 0;

    enum SynchronizeHints
    {
        k_None = 0x00000000,
        k_All =  0xFFFFFFFF
    };

    struct InstanceData
    {
        InstanceData()
            : data(NULL),
              datalen(0),
              freefunc(NULL),
              paramtable(NULL),
              synchronizeHints(SynchronizeHints::k_None)
        {}
        RtPointer data;
        size_t datalen;
        void (*freefunc)(RtPointer);
        RixSCParamInfo const* paramtable;
        uint32_t synchronizeHints;
    };

    virtual void CreateInstanceData(RixContext& rixCtx, RtUString const handle,
                                    RixParameterList const* parameterList,
                                    InstanceData* instanceData)
    {
        PIXAR_ARGUSED(rixCtx);
        PIXAR_ARGUSED(handle);
        PIXAR_ARGUSED(parameterList);
        PIXAR_ARGUSED(instanceData);
    }

    virtual void SynchronizeInstanceData(RixContext& rixCtx, RtUString const handle,
                                         RixParameterList const* instanceParams,
                                         uint32_t const editHints,
                                         InstanceData* instanceData)
    {
        PIXAR_ARGUSED(rixCtx);
        PIXAR_ARGUSED(handle);
        PIXAR_ARGUSED(instanceParams);
        PIXAR_ARGUSED(editHints);
        PIXAR_ARGUSED(instanceData);
    }

protected:
    RixShadingPlugin(int version) : m_version(version)
    {}
    virtual ~RixShadingPlugin()
    {}
    int m_version;
};

enum RixSCType
{
    k_RixSCInvalidType = 0,
    k_RixSCAnyType,  // signals a dynamic binding scenario
    k_RixSCInteger,
    k_RixSCFloat,
    k_RixSCFloat2,
    k_RixSCFloat3,
    k_RixSCColor,
    k_RixSCPoint,
    k_RixSCVector,
    k_RixSCNormal,
    k_RixSCMatrix,
    k_RixSCString,
    k_RixSCBxdf,           // always uniform
    k_RixSCLightFilter,    // always uniform
    k_RixSCStructBegin,    // always uniform
    k_RixSCStructEnd,      // always uniform
    k_RixSCSampleFilter,   // always uniform
    k_RixSCDisplayFilter,  // always uniform
    k_RixSCNumTypes
};

enum RixSCDetail
{
    k_RixSCInvalidDetail = 0,
    k_RixSCUniform,  // needs an eval per shading "grid"
    k_RixSCVarying,  // needs an eval per shading point
    k_RixSCAnyDetail
};

enum RixSCAccess
{
    // clang-format off
    k_RixSCInput                   = 0,
    k_RixSCOutput                  = 1 << 0,
    k_RixSCPresenceInput           = 1 << 1,
    k_RixSCOpacityInput            = 1 << 2,
    k_RixSCScatterInput            = 1 << 3,
    k_RixSCVolumeTransmissionInput = 1 << 4,
    k_RixSCVolumeScatterInput      = 1 << 5,
    k_RixSCDisplacementInput       = 1 << 6,
    k_RixSCEmissionInput           = 1 << 7,
    // use Input + output at the same time to indicate invalid
    k_RixSCInvalidAccess           = 0xFF,
    // clang-format on
};

enum RixSCVolumeSelector
{
    k_RixSCAnyVolume,
    k_RixSCIncidentVolume,
    k_RixSCOppositeVolume,
    k_RixSCSubsurfaceVolume
};

enum RixSCConnectionInfo
{
    k_RixSCDefaultValue = 0,
    k_RixSCParameterListValue,
    k_RixSCNetworkValue
};

enum RayProperty
{
    k_RayDepth,  // ray depth (scattering events)
    k_RayRngSampleCtx,
    k_RayThruput,
    k_RayVolumeScatterCount,
    k_RayVolumeSampleCount,
    k_RayTrueDepth  // ray depth (scattering events + volume envelopes etc.)
};

struct RixSCParamInfo
{
    // most common constructor of POD parameters.
    RixSCParamInfo(RtUString const _name, RixSCType t, RixSCAccess a = k_RixSCInput,
                   int length = -1)
        : name(_name), customtype(US_NULL), type(t), access(a), arraylen(length)
    {}

    // full constructor
    RixSCParamInfo(RtUString const structName, RtUString const _name, RixSCType t,
                   RixSCAccess a = k_RixSCInput, int length = -1)
        : name(_name), customtype(structName), type(t), access(a), arraylen(length)
    {}

    // default constructor, useful to signal end of paraminfo table
    RixSCParamInfo()
        : name(US_NULL),
          customtype(US_NULL),
          type(k_RixSCInvalidType),
          access(k_RixSCInvalidAccess),
          arraylen(-1)
    {}

    RtUString name;
    RtUString customtype;  // NULL unless struct
    RixSCType type;
    RixSCAccess access;
    int arraylen;  // -1 means no array, 0 means empty
    bool IsArray() const
    {
        return (arraylen != -1);
    }
};

enum RixSCShadingMode
{
    k_RixSCInvalidShadingMode,       
    k_RixSCPresenceQuery,            
    k_RixSCOpacityQuery,             
    k_RixSCScatterQuery,             
    k_RixSCVolumeTransmissionQuery,  
    k_RixSCVolumeScatterQuery,       
    k_RixSCBakeQuery,                
    k_RixSCDisplacementQuery,        
    k_RixSCEmissionQuery,            
    k_RixSCNumShadingModes           
};

class RixParameterList
{
public:
    virtual int GetNumParams() const = 0;

    virtual int GetParamId(const RtUString name, int* paramId) const = 0;

    virtual int GetParamId(int plistIndex, int* paramId) const = 0;

    virtual int GetParamInfo(int paramId, RixSCType* type, RixSCConnectionInfo* cInfo,
                             int* arrayLength = NULL) const = 0;

    int GetParamInfo(int paramId, RixSCType* type, bool* isConnected, int* arrayLength = NULL) const
    {
        RixSCConnectionInfo cInfo;
        int err = GetParamInfo(paramId, type, &cInfo, arrayLength);
        if (isConnected) *isConnected = (cInfo == k_RixSCNetworkValue);
        return err;
    }

    virtual RixSCDetail EvalParam(int paramId, int arrayIndex, int* result) const = 0;
    virtual RixSCDetail EvalParam(int paramId, int arrayIndex, float* result) const = 0;
    virtual RixSCDetail EvalParam(int paramId, int arrayIndex, RtColorRGB* result) const = 0;
    virtual RixSCDetail EvalParam(int paramId, int arrayIndex, RtFloat3* result) const = 0;
    virtual RixSCDetail EvalParam(int paramId, int arrayIndex, RtMatrix4x4* result) const = 0;
    virtual RixSCDetail EvalParam(int paramId, int arrayIndex, RtUString* result) const = 0;
    virtual RixSCDetail EvalParam(int paramId, int arrayIndex, RixLightFilter** result,
                                  RtConstPointer* instance) const = 0;
    virtual RixSCDetail EvalParam(int paramId, int arrayIndex, RixSampleFilter** result,
                                  RtConstPointer* instance) const = 0;
    virtual RixSCDetail EvalParam(int paramId, int arrayIndex, RixDisplayFilter** result,
                                  RtConstPointer* instance) const = 0;

protected:
    virtual ~RixParameterList()
    {}
};

class RixShadingContext : public RixContext
{
public:
    struct Id
    {
        Id() : shadingCtxNum(-6666)
        {}
        Id(unsigned int i) : shadingCtxNum(static_cast<short>(i & 0xFFFF))
        {}
        // Convert to a serialized integral representation.
        unsigned int Serialize() const
        {
            return shadingCtxNum;
        }
        void Invalidate()
        {
            shadingCtxNum = -6666;
        }
        bool IsValid() const
        {
            return shadingCtxNum != -6666;
        }
        short shadingCtxNum;
    } shadingCtxId;

    int numPts;

    struct
    {
        // clang-format off
        unsigned eyePath     : 1; 
        unsigned lightPath   : 1; 
        unsigned primaryHit  : 1; 
        unsigned missContext : 1; 
        unsigned reyesGrid   : 1; 
        // clang-format on

        RixSCShadingMode shadingMode;

        RixBxdf* bxdf;

        // The opacity shader is non-NULL when computing presence and
        // transmission.
        RixOpacity* opacity;

        // The displacement shader is non-NULL when computing displacement
        RixDisplacement* displacement;

        // The subsurface shader is non-NULL when invoking subsurf. integrators
        RixVolumeIntegrator* subsurface;

        // The volume shader is non-NULL when invoking volume integrators.
        RixVolumeIntegrator* volume;

        // The postlighting shader is non-NULL when invoking postlighting
        RixPostLighting* postlighting;
    } scTraits;  // "uniform" traits associated with the shading context

    bool HasHits() const
    {
        return (scTraits.missContext == 0);
    }
    bool HasMisses() const
    {
        return (scTraits.missContext == 1);
    }

    RixBxdf* GetBxdf() const
    {
        assert(scTraits.shadingMode == k_RixSCScatterQuery ||
               scTraits.shadingMode == k_RixSCVolumeScatterQuery ||
               scTraits.shadingMode == k_RixSCVolumeTransmissionQuery);
        return scTraits.bxdf;
    }

    RixOpacity* GetOpacity() const
    {
        assert(scTraits.shadingMode == k_RixSCOpacityQuery ||
               scTraits.shadingMode == k_RixSCPresenceQuery ||
               scTraits.shadingMode == k_RixSCVolumeTransmissionQuery);
        return scTraits.opacity;
    }

    RixDisplacement* GetDisplacement() const
    {
        assert(scTraits.shadingMode == k_RixSCDisplacementQuery);
        return scTraits.displacement;
    }

    RixVolumeIntegrator* GetSubsurface() const
    {
        assert(scTraits.shadingMode == k_RixSCScatterQuery ||
               scTraits.shadingMode == k_RixSCVolumeScatterQuery ||
               scTraits.shadingMode == k_RixSCVolumeTransmissionQuery);
        return scTraits.subsurface;
    }

    RixVolumeIntegrator* GetVolume() const
    {
        assert(scTraits.shadingMode == k_RixSCScatterQuery ||
               scTraits.shadingMode == k_RixSCVolumeScatterQuery ||
               scTraits.shadingMode == k_RixSCVolumeTransmissionQuery ||
               scTraits.shadingMode == k_RixSCEmissionQuery);
        return scTraits.volume;
    }

    RixPostLighting* GetPostLighting() const
    {
        assert(scTraits.shadingMode == k_RixSCScatterQuery ||
               scTraits.shadingMode == k_RixSCVolumeScatterQuery);
        return scTraits.postlighting;
    }
    
    virtual bool HasSubsurface() const = 0;
    virtual RixVolumeIntegrator* BeginSubsurface(int numRays, RtRayGeometry* rays) const = 0;
    virtual void EndSubsurface(RixVolumeIntegrator*) const = 0;

    virtual bool HasVolume(RixSCVolumeSelector) const = 0;
    virtual RixVolumeIntegrator* BeginVolume(RixSCVolumeSelector, int numRays,
                                             RtRayGeometry* rays) const = 0;
    virtual void EndVolume(RixVolumeIntegrator*) const = 0;
    RixVolumeIntegrator* BeginIncidentVol(int numRays, RtRayGeometry* rays) const
    {
        return BeginVolume(k_RixSCIncidentVolume, numRays, rays);
    }
    RixVolumeIntegrator* BeginOppositeVol(int numRays, RtRayGeometry* rays) const
    {
        return BeginVolume(k_RixSCOppositeVolume, numRays, rays);
    }

    virtual std::vector<const RixShadingContext*> const* GetOverlappingVolumes() const = 0;

    enum BuiltinVolume  // built-in subsurface interior integrator
    {
        k_SSDiffusion,  // sss using Burley's normalized diffusion model
        k_SSPathTraced  // sss using brute-force volume scattering
    };
    virtual RixVolumeIntegrator* GetBuiltinVolume(BuiltinVolume builtin, RixBxdfFactory* factory,
                                                  RtPointer instanceData) const = 0;

    int* integratorCtxIndex;

    int* rayId;

    RtColorRGB* transmission;

    float* pointWeight;

    RtInt* pointSampleCount;

    // When dealing with non-fully-opaque surfaces, and when using probabilistic hit-testing, the
    // total opacity (product of the `presence` and the `opacity` values returned by RixOpacity) can
    // be interpreted as the probability that we actually hit the surface.
    //
    // When only considering a scalar presence value (i.e. opacity is one, so the total opacity is
    // monochromatic), the hit probability is usually the inverse of the scalar presence value, and
    // no special weighting needs to be applied to the shading on hits.
    //
    // However, when dealing with arbitrary (i.e. colored) total opacity, it is necessary to weight
    // the shading on hit by the product of:
    // - `opacityThroughput`: a colored weight resulting from stochastic continuations that
    // happened before reaching the selected hit
    // - `opacityStochasticWeight`: inverse of the local probability of having selected the hit,
    // knowing that we have reached it
    // - `opacity`: the total opacity of the selected hit

    // Per-point colored weight resulting from stochastic continuations that happened before
    // reaching the selected hit.
    //
    // If no probabilistic hit-testing was involved before reaching the current point, or if the ray
    // only went through surfaces with monochromatic opacity, then this quantity is [1 1 1]. If the
    // ray went through surfaces with colored opacity, then this quantity is the total transmission
    // (up to the current point) divided by the probability of reaching this point.
    RtColorRGB* opacityThroughput;

    // Per-point combined opacity: the product of presence and opacity for the current point.
    RtColorRGB* opacity;

    // Per-point probabilistic hit-testing weight.
    //
    // If the current hit's opacity is monochromatic, or if the `opacityThroughput` up to it is
    // monochromatic, then this quantity only depends on the hit's total opacity. Otherwise, this
    // weight also depends on the accumulated transmission up to the hit.
    float* opacityStochasticWeight;

    mutable void* lightingServicesData;

    // The light shader is non-NULL when the shading context contains
    // points on the surface of a light
    RixLight const* light;

    // This is accessed and used by patterns to generate random numbers
    // A NULL value of m_rngCtx means the integrator in use does not support
    // this functionality. Pattern writer needs to check against NULL pointer
    // before using m_rngCtx. See PxrRand pattern for example code.
    mutable RixRNG* m_rngCtx;
    virtual void SetupRngCtxForPattern() const = 0;

    enum BuiltinBxdf
    {
        k_NullBxdf
    };
    virtual RixBxdf* GetBuiltinBxdf(BuiltinBxdf, RixBxdfFactory*) const = 0;

    virtual RixDisplayServices* GetDisplayServices(int version = 1) const = 0;

    enum BuiltinVar
    {
        // clang-format off
        k_P = 0,               
        k_PRadius,             
        k_Po,                  
        k_Nn,                  
        k_Ngn,                 
        k_Non,                 
        k_Tn,                  
        k_Vn,                  
        k_VLen,                
        k_curvature,           
        k_incidentRaySpread,   
        k_incidentRayRadius,   
        k_incidentLobeSampled, 
        k_mpSize,              
        k_biasR,               
        k_biasT,               
        k_u,                   
        k_v,                   
        k_w,                   
        k_du,                  
        k_dufp = k_du,
        k_dv,                  
        k_dvfp = k_dv,
        k_dw,                  
        k_dwfp = k_dw,
        k_dPdu,                
        k_dPdv,                
        k_dPdw,                
        k_dPdtime,             
        k_time,                
        k_Id,                  
        k_Id2,                 
        k_outsideIOR,          
        k_Oi,                  
        k_lpeState,            
        k_launchShadingCtxId,  
        k_motionFore,          
        k_motionBack,          
        k_curvatureU,          
        k_curvatureV,          
        k_dPcameradtime,       
        k_wavelength,          
        k_Naon,                
        k_numBuiltinVars
        // clang-format on
    };
    virtual void GetBuiltinVar(BuiltinVar, int const** var) const = 0;
    virtual void GetBuiltinVar(BuiltinVar, float const** var) const = 0;
    virtual void GetBuiltinVar(BuiltinVar, RtFloat3 const** var) const = 0;
    virtual void GetBuiltinVar(BuiltinVar, RixLPEState* const** var) const = 0;

    virtual void SetBuiltinVar(BuiltinVar, float* var) = 0;
    virtual void SetBuiltinVar(BuiltinVar, RtFloat3* var) = 0;

    virtual RixSCDetail GetPrimVar(const RtUString name, RixSCType* type, int* arraylen) const = 0;

    virtual RixSCDetail GetPrimVar(const RtUString name, float fill, float const** var,
                                   float const** radius = NULL) const = 0;

    virtual RixSCDetail GetPrimVar(const RtUString name, RtFloat2 fill, RtFloat2 const** var,
                                   float const** radius = NULL) const = 0;

    virtual RixSCDetail GetPrimVar(const RtUString name, RtFloat3 fill, RtFloat3 const** var,
                                   float const** radius = NULL) const = 0;

    virtual RixSCDetail GetPrimVar(const RtUString name, RtUString const** var) const = 0;

    virtual RixSCDetail GetPrimVar(const RtUString name, RtMatrix4x4 const& fill,
                                   RtMatrix4x4 const** var) const = 0;


    virtual RixSCDetail GetPrimVar(const RtUString name, float const** var, float const** dXdu,
                                   float const** dXdv) const = 0;

    virtual RixSCDetail GetPrimVar(const RtUString name, RtFloat2 const** var, float const** dXdu,
                                   float const** dYdu, float const** dXdv,
                                   float const** dYdv) const = 0;

    virtual RixSCDetail GetPrimVar(const RtUString name, RtFloat3 const** var, float const** dXdu,
                                   float const** dYdu, float const** dZdu, float const** dXdv,
                                   float const** dYdv, float const** dZdv) const = 0;

    virtual void SetPrimVar(const RtUString name, RixSCDetail d, float* var, float* radius) = 0;

    virtual void SetPrimVar(const RtUString name, RixSCDetail d, RtFloat2* var, float* radius) = 0;

    virtual void SetPrimVar(const RtUString name, RixSCDetail d, RtFloat3* var, float* radius) = 0;

    virtual void SetPrimVar(const RtUString name, RixSCDetail d, RtUString* var) = 0;

    virtual void SetPrimVar(const RtUString name, RixSCDetail d, RtMatrix4x4* var) = 0;

    virtual bool GetProperty(RayProperty, void const* /* result */) const
    {
        return false;
    }

    // Shading context obtains the pointer to the corresponding
    // integrator and integrator context.
    // The integrator is responsible for setting the values.
    virtual bool SetProperty(RayProperty, void const* /* in */) const
    {
        return false;
    }

    enum TransformInterpretation
    {
        k_AsPoints,
        k_AsVectors,
        k_AsNormals
    };

    virtual int Transform(TransformInterpretation interp, const RtUString fromSpace,
                          const RtUString toSpace, RtFloat3* var, float* radius = NULL) const = 0;

    virtual int GetTransform(const RtUString fromSpace, const RtUString toSpace,
                             RtMatrix4x4 const** matrix, int* numMatrices) const = 0;

    virtual RixShadingContext* CreateMutableContext() const = 0;

    virtual RixShadingContext const* GetPrimaryContext() const = 0;

    virtual RixIntegratorContext* GetIntegratorContext() const = 0;

    virtual RixShadingContext const* GetContextById(RixShadingContext::Id sCtxId) const = 0;


    virtual RixSCDetail EvalParam(int paramId, int arrayIndex, int const** result,
                                  int const* dflt = NULL, bool promoteToVarying = false) const = 0;

    virtual RixSCDetail EvalParam(int paramId, int arrayIndex, float const** result,
                                  float const* dflt = NULL,
                                  bool promoteToVarying = false) const = 0;

    virtual RixSCDetail EvalParam(int paramId, int arrayIndex, RtColorRGB const** result,
                                  RtColorRGB const* dflt = NULL,
                                  bool promoteToVarying = false) const = 0;

    virtual RixSCDetail EvalParam(int paramId, int arrayIndex, RtFloat3 const** result,
                                  RtFloat3 const* dflt = NULL,
                                  bool promoteToVarying = false) const = 0;

    virtual RixSCDetail EvalParam(int paramId, int arrayIndex, RtMatrix4x4 const** result,
                                  RtMatrix4x4 const* dflt = NULL,
                                  bool promoteToVarying = false) const = 0;

    virtual RixSCDetail EvalParam(int paramId, int arrayIndex, RtUString const** result,
                                  RtUString const* dflt = NULL,
                                  bool promoteToVarying = false) const = 0;

    virtual RixSCDetail EvalParam(int paramId, int arrayIndex, RixBxdfFactory** result,
                                  RixBxdfFactory* dflt = NULL,
                                  bool promoteToVarying = false) const = 0;

    enum MemCategory
    {
        k_BxdfMem,
        k_PatternMem
    };

    template <class T>
    RixSCDetail EvalAndCopyParam(int paramId, int arrayIndex, T** result, T const* dflt = NULL,
                                 bool promoteToVarying = false, MemCategory mcat = k_BxdfMem) const
    {
        T const* constResult;
        RixSCDetail d = EvalParam(paramId, arrayIndex, &constResult, dflt);
        switch (d)
        {
        case k_RixSCVarying:
            *result = (T*)Allocate(this->numPts, sizeof(T), mcat);
            memcpy(*result, constResult, this->numPts * sizeof(T));
            break;
        case k_RixSCUniform:
            if (promoteToVarying)
            {
                *result = (T*)Allocate(this->numPts, sizeof(T), mcat);
                std::fill_n(*result, this->numPts, constResult[0]);
            }
            else
            {
                *result = (T*)Allocate(1, sizeof(T), mcat);
                (*result)[0] = constResult[0];
            }
            break;
        default:
            *result = 0x0;
            break;
        }
        return d;
    }

    virtual int GetParamId(const RtUString name, int* paramId) const = 0;

    virtual int GetParamInfo(int paramId, RixSCType* type, RixSCConnectionInfo* cInfo,
                             int* arrayLength = NULL) const = 0;

    int GetParamInfo(int paramId, RixSCType* type, bool* isConnected, int* arrayLength = NULL) const
    {
        RixSCConnectionInfo cInfo;
        int err = GetParamInfo(paramId, type, &cInfo, arrayLength);
        if (isConnected) *isConnected = (cInfo == k_RixSCNetworkValue);
        return err;
    }

    virtual void GetNearestHits(int numRays, RtRayGeometry const* rays,
                                // result:
                                RtHitPoint* hits,
                                // optional parameters:
                                const RtUString subset = US_NULL,
                                const RtUString excludeSubset = US_NULL,
                                RtHitSides hitSides = k_SidesBoth) const = 0;

    virtual bool GetLightEmission(RtColorRGB* emission, int* lightGroupIds = NULL) const = 0;

    virtual void* Allocate(size_t n, size_t size, MemCategory m) const = 0;

    template <class T>
    T* New(size_t nObjs, MemCategory cat = k_BxdfMem) const
    {
        T* mem = static_cast<T*>(Allocate(nObjs, sizeof(T), cat));
        return new (mem) T[nObjs];
    }

    class Allocator
    {
    public:
        Allocator(RixShadingContext const* sCtx) : m_sCtx(sCtx)
        {}
        template <typename T>
        T* Allocate(int num)
        {
            if (num == 0) return NULL;
            return (T*)m_sCtx->Allocate(num, sizeof(T), k_BxdfMem);
        }
        template <typename T>
        T* AllocFor(MemCategory memcat, int num)
        {
            if (num == 0) return NULL;
            return (T*)m_sCtx->Allocate(num, sizeof(T), memcat);
        }
        template <typename T>
        T* AllocForVolume(int num)
        {
            // currently the memory-pool lifetime of volumes matches
            // that of Bxdf.
            if (num == 0) return NULL;
            return (T*)m_sCtx->Allocate(num, sizeof(T), k_BxdfMem);
        }
        template <typename T>
        T* AllocForBxdf(int num)
        {
            if (num == 0) return NULL;
            return (T*)m_sCtx->Allocate(num, sizeof(T), k_BxdfMem);
        }
        template <typename T>
        T* AllocForPattern(int num)
        {
            if (num == 0) return NULL;
            return (T*)m_sCtx->Allocate(num, sizeof(T), k_PatternMem);
        }

    private:
        RixShadingContext const* m_sCtx;
    };

protected:
    virtual ~RixShadingContext()
    {}

    // Hide these interfaces. These are not useful/relevant for clients to
    // directly call. However, they need to be accessed by the
    // RixVolumeIntegrator internals, so allow access for this class only.
    friend class RixVolumeIntegrator;
    // LightVertexCache::RayDensityEstimation() in UPBP needs to call
    // BeginVolumeSampling() so allow it access, too.
    friend class LightVertexCache;
    virtual RixShadingContext* BeginVolumeSampling() const = 0;
    virtual RixShadingContext const* EndVolumeSampling(const RixShadingContext*,
                                                       RixBXLobeTraits const* exposeVol = NULL,
                                                       int const* membership = NULL) const = 0;

    mutable RixRNG::SampleCtx* m_rngSampleCtx;  // assembled by querying into the integrator
};

#endif