RixBxdf.h

Go to the documentation of this file.

/*
# ------------------------------------------------------------------------------
#
# Copyright (c) 2021 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;

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;
}

enum RixBXTransportTrait
{
    k_RixBXDirectLighting = 1 << 0,    
    k_RixBXIndirectLighting = 1 << 1,  
    k_RixBXAnyLighting = k_RixBXDirectLighting | k_RixBXIndirectLighting
};

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;

    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;
    }

    virtual RixBXEvaluateDomain GetEvaluateDomain() = 0;

    virtual void GetAggregateLobeTraits(RixBXLobeTraits* t) = 0;

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

    enum BxdfProperty
    {
        k_Albedo,      
        k_MaterialIor  
    };

    virtual RixSCDetail GetProperty(BxdfProperty property, void const** result) const = 0;

    virtual bool EmitLocal(RtColorRGB* result) = 0;

    virtual void GenerateSample(RixBXTransportTrait transportTrait,
                                RixBXLobeTraits const* lobesWanted, RixRNG* rng,
                                // results:
                                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, // a result
                                RtVector3 const* directions,
                                // more results:
                                RixBXLobeWeights& weights, float* forwardPdfs,
                                float* reversePdfs) = 0;

    virtual void EvaluateSamplesAtIndex(RixBXTransportTrait transportTrait,
                                        RixBXLobeTraits const& lobesWanted, RixRNG* rng, int index,
                                        int numSamples,
                                        // results:
                                        RixBXLobeTraits* lobesEvaluated,
                                        RtVector3 const* directions, RixBXLobeWeights& weights,
                                        float* forwardPdfs, float* reversePdfs) = 0;

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

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

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;
};

class RixVolumeIntegrator
{
public:
    RixVolumeIntegrator(RixShadingContext const* sCtx, RixBxdfFactory* f, void* _instanceData)
        : bxdfFactory(f),
          instanceData(_instanceData),
          params(NULL),
          surfaceCtx(sCtx),
          volumeCtx(NULL)
    {}
    virtual ~RixVolumeIntegrator()
    {}

    RixShadingContext const* GetShadingCtx() const
    {
        return surfaceCtx;
    }

    RixShadingContext* GetVolumeShadingCtx() const
    {
        return volumeCtx;
    }

    RixBxdfFactory* GetBxdfFactory() const
    {
        return bxdfFactory;
    }

    void SetBxdfFactory(RixBxdfFactory* factory)
    {
        bxdfFactory = factory;
    }

    void* GetInstanceData() const
    {
        return instanceData;
    }

    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);
    }

    enum VolumeProperty
    {
        k_DensityType,              
        k_DensityFloat,             
        k_DensityColor,             
        k_MaxDensity,               
        k_Velocity,                 
        k_NontemporalDensityFloat,  
        k_NontemporalDensityColor,  
        k_DensityFloatId,           
        k_DensityColorId,           
        k_Emission,                 
        k_ShadowDensityMultiplier   
    };
    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;
    }

    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;

    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