RixIntegrator.h

Go to the documentation of this file.

/*
# ------------------------------------------------------------------------------
#
# Copyright (c) 2023 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 RixIntegrator_h
#define RixIntegrator_h

#include <math.h>             // for sqrtf
#include <algorithm>          // for max
#include <cassert>            // for assert
#include <cstddef>            // for size_t
#include "RixBxdfLobe.h"      // for RixBXLobeSampled, etc
#include "RixInterfaces.h"    // for RixContext
#include "RixShading.h"       // for RixShadingContext, etc
#include "RixShadingUtils.h"  // for RixIsFinite
#include "prmanapi.h"         // for PRMANEXPORT, PRMAN_INLINE
#include "RiTypesHelper.h"    // for RtNormal3, Dot, RtPoint3, etc

class RixLPE;
class RixLPEState;
class RixLightingServices;
class RixRNG;
class RixVolumeServices;

typedef unsigned int      RixChannelId;
static const RixChannelId k_InvalidChannelId = 2147483647;

struct RixDisplayChannel
{
    RixChannelId id;
    enum ChannelStyle
    {
        k_ChannelName,
        k_ChannelExpression
    } style;
    enum ChannelType
    {
        k_FloatChannel,
        k_RGBChannel,
        k_PointChannel,
        k_NormalChannel,
        k_IntegerChannel
    } type;
    RtUString channel;
};

class RixDisplayServices
{
public:
    //
    virtual bool Splat(RixChannelId id, int iCtxIndex, float const value) = 0;
    virtual bool Splat(RixChannelId id, int iCtxIndex, RtColorRGB const value) = 0;

    virtual bool SplatMulti(
        int nChans, RixChannelId const* ids, int iCtxIndex, float const value) = 0;
    virtual bool SplatMulti(
        int nChans, RixChannelId const* id, int iCtxIndex, RtColorRGB const value) = 0;

    virtual bool Write(RixChannelId id, int iCtxIndex, float const value) = 0;
    virtual bool Write(RixChannelId id, int iCtxIndex, RtColorRGB const value) = 0;
    virtual bool Write(RixChannelId id, int iCtxIndex, int const value) = 0;

    virtual void WriteDistance(
        int const                iCtxIndex,
        float const              distance,
        bool const               isVolume = true,
        RixShadingContext const* sCtx     = nullptr) = 0;

    virtual void WriteOpacity(RixChannelId id, int iCtxIndex, float const value) = 0;
    virtual void WriteOpacity(RixChannelId id, int iCtxIndex, RtColorRGB& value) = 0;

    virtual void SplatOpacity(RixChannelId id, int iCtxIndex, float const opacity) = 0;
    virtual void SplatOpacity(RixChannelId id, int iCtxIndex, RtColorRGB& opacity) = 0;

    virtual int AddSample(int iCtxIndex) = 0;

    virtual void GetDisplayChannels(int* numDisplays, RixDisplayChannel const** displays) = 0;

    virtual void DiscardIteration(bool redo = false) = 0;

protected:
    virtual ~RixDisplayServices() {}

public:
    virtual bool Read(RixChannelId id, int iCtxIndex, float& value) = 0;
    virtual bool Read(RixChannelId id, int iCtxIndex, RtColorRGB& value) = 0;
    virtual bool Read(RixChannelId id, int iCtxIndex, int& value) = 0;
};

struct PRMAN_ALIGNED_16 RtRayGeometry
{
    enum RayType
    {
        k_rtInvalid      = 0,
        k_rtCamera       = 1, /* primary visibility ray from a camera */
        k_rtLight        = 2, /* photon ray directly from a light source */
        k_rtTransmission = 3, /* shadow ray */
        k_rtDirectlight  = 4, /* directlighting ray */
        k_rtIndirect     = 5, /* indirect ray */
        k_rtNumRayTypes  = 6
    };
    
    RtPoint3  origin;        
    float     originRadius;  
    RtVector3 direction;     

    float raySpread;  
    float minDist;    
    float maxDist;    
    float time;       

    uint16_t              raytype;       
    RixBXLobeSampled      lobeSampled;   
    RixShadingContext::Id shadingCtxId;  
    int16_t               integratorCtxIndex;  
    uint16_t              shadingCtxIndex;     
    uint16_t              rayId;               
    RixLPEState*          lpeState;            

    float pixelEstimate;     
    uint32_t privateData[4]; 
    float opacityThreshold;  
    mutable uint16_t hitId;  
    uint16_t         flags;  

    uint16_t wavelength;

    uint16_t ignoreGroupingId;

    void InitOrigination(RixShadingContext const* sCtx, RtNormal3 const* Ngn, int _shadingCtxIndex)
    {
        this->shadingCtxId       = sCtx->shadingCtxId;
        this->shadingCtxIndex    = _shadingCtxIndex;
        this->integratorCtxIndex = sCtx->integratorCtxIndex[_shadingCtxIndex];
        if (this->lobeSampled.GetTransmit())
        {
            bool const entering = Dot(Ngn[_shadingCtxIndex], this->direction) <= 0.f;
            this->lobeSampled.SetEntering(entering);
        }
    }

    void InitTransmitOrigination(RixShadingContext const* sCtx, int _shadingCtxIndex)
    {
        this->shadingCtxId       = sCtx->shadingCtxId;
        this->shadingCtxIndex    = _shadingCtxIndex;
        this->integratorCtxIndex = sCtx->integratorCtxIndex[_shadingCtxIndex];
        this->lobeSampled.Set(
            true,   // discrete
            false,  // specular
            false,  // transmit, not reflect
            false,  // scattering
            false,  // not user
            0,      // lpeid
            0       // lobeid (unused)
        );
        this->lobeSampled.SetEntering(true);
    }

    void SetRaySpread(
        RixBXLobeSampled lobe,
        float            rayOriginRadius,
        float            rayOriginSpread,
        float            curvature,
        float            fPdf,
        bool             lightPath = false)
    {
        float pdfSpread = 0.0f;
        float newSpread;

        // Compute ray spread based on pdf (and hence surface roughness). If Dirac delta, don't use
        // pdf -- it is 1.0 by convention.
        if (!lightPath && lobe.GetSolidAngle() && fPdf > 0.0f)
        {
            // Inverse square root of pdf is a heuristic that seems to work.
            assert(fPdf > 0.0f);  // Avoid division by 0 (fPdf=inf is okay here).
            pdfSpread = 0.125f / sqrtf(fPdf);
            assert(RixIsFinite(pdfSpread));
        }

        // Compute ray spread based on surface curvature.
        if (lobe.GetReflect())
        {
            // Treat this as reflection:
            // - `k_RixBXReflectSpecular`
            // - `k_RixBXReflectGlossy`
            // - `k_RixBXReflectDiffuse`

            // Spread for specular reflection: The new ray spread is the incident ray spread plus
            // change induced by local curvature. The factor of 2 comes from differentiating the
            // formula for mirror reflection direction -- see [Igehy99].
            // Note that we clamp the spread so it doesn't become negative for highly negative
            // curvature, for example a concave mirror.
            float curvatureSpread = rayOriginSpread + 2.0f * curvature * rayOriginRadius;
            newSpread             = std::max(curvatureSpread, pdfSpread);
        }
        else if (lobe.GetTransmit())
        {
            // Treat this as refraction:
            // - `k_RixBXTransmitSpecular`
            // - `k_RixBXTransmitGlossy`

            // Spread for specular transmission -- simpler than [Igehy99] since we only need spread
            // amount, not differential direction vector:
            // - newSpread = eta * raySpread - (1.0f - eta) * curvature * rayOriginRadius;
            //
            // This can give negative spread and focusing of the ray, with the width of the ray
            // increasing beyond the focus distance. This is all good and fine, but we skip this
            // effect for now. For now: simply copy parent ray spread to avoid having to deal with
            // ior vs. 1/ior
            newSpread = std::max(rayOriginSpread, pdfSpread);

            // - `k_RixBXTransmitDiffuse`

            // Use very conservative spread for diffuse reflection and transmission: same as for
            // specular/glossy reflection.
            // (Could do better if we know PixelSamples and diffusemultfactor: compute ray solid
            // angle = 2pi / (pixsam*diffmultfac)
        }
        else
        {
            // We have no idea what this ray is, let's use the provided ray spread.
            newSpread = rayOriginSpread;
        }

        // Disallow |newSpread| > 1 or newSpread == nan
        if (!(newSpread <= 1.0f)) newSpread = 1.0f;
        if (newSpread < -1.0f) newSpread = -1.0f;
        assert(-1.0f <= newSpread && newSpread <= 1.0f);

        this->raySpread = newSpread;
    }

    static PRMAN_INLINE uint16_t EncodeWavelength(float wavelength)
    {
        return wavelength != 0.0f ?
                   (int((wavelength - 380.0f) * (65534.0f / (780.0f - 380.0f)) + 0.5f) + 1) :
                   0;
    }

    static PRMAN_INLINE float DecodeWavelength(uint16_t encodedWavelength)
    {
        return encodedWavelength != 0 ?
                   (float(encodedWavelength - 1) * ((780.0f - 380.0f) / 65534.0f) + 380.0f) :
                   0.0f;
    }
};

struct RtHitPoint
{
    RtPoint3  P;           
    RtNormal3 Ng;          
    float     dist;        
    RtPoint2  uv;          
    float     filterSize;  
    float     mpSize;      
    uint16_t  groupingId;  
    uint16_t  unused;      
};

class RixIntegratorEnvironment
{
public:
    enum SamplingModes
    {
        k_Invalid     = 0,
        k_Fixed       = 1,
        k_Adaptive    = 2,
        k_Incremental = 4,

        k_AllModes = (k_Fixed | k_Adaptive | k_Incremental)
    };

    enum LightingModes
    {
        k_UnidirectionalLighting = 0,
        k_BidirectionalLighting  = 1
    };

    RixIntegratorEnvironment()
        : m_version(2),
          maxIntegrateSize(1024),
          maxShadingCtxSize(1024),
          supportedSamplingModes(k_AllModes),
          lightingRequirements(k_UnidirectionalLighting),
          numDisplays(0),
          displays(0),
          wantsEmptyIntegrate(false),
          wantsIncrementBarrier(false),
          numRaysPerIncrement(-1),
          numIncrements(0),
          numBootstrapIncrements(0),
          lobesWanted(k_RixBXTraitsAllLobe),
          cameraMediumIOR(1.f),
          cameraMediumPriority(0),
          wantsTransmission(false),
          usesLightingServices(true),
          manifoldWalkMaxSamples(0),
          shadowExcludeSubset(),
          lightingServicesManagesParticipatingMedia(false)
    {}

    PRMAN_INLINE RixDisplayChannel const* GetDisplayChannel(RtUString name) const
    {
        for (int i = 0; i < numDisplays; ++i)
            if (displays[i].channel == name) return &displays[i];
        return nullptr;
    }

    int m_version;

    // Some of the following quantities can be modified by the integrator on the object provided to
    // `RixIntegrator::RenderBegin()`.
    
    int maxIntegrateSize;
    int           maxShadingCtxSize;
    SamplingModes supportedSamplingModes;
    LightingModes lightingRequirements;

    int const                      numDisplays;
    RixDisplayChannel const* const displays;

    bool wantsEmptyIntegrate;
    bool wantsIncrementBarrier;  

    int const numRaysPerIncrement;
    int const numIncrements;

    int       numBootstrapIncrements;  

    RixBXLobeTraits lobesWanted;  
    float cameraMediumIOR;
    int   cameraMediumPriority;
    bool  wantsTransmission;

    bool usesLightingServices;  
    bool unused1;
    bool unused2;
    int manifoldWalkMaxSamples;

    RtUString shadowExcludeSubset;
    
    bool lightingServicesManagesParticipatingMedia;
#ifdef PIXAR_ANIM
    // The offset of `manifoldWalkMaxSamples` is at byte 64.
    // Due to padding, excludeSubset's offset is at byte 72, and RtUString is 8 bytes long.
    // The length of the `_reserved` array puts the size of the struct at 96.
#endif
    char _reserved[15];
};

namespace RixConstants
{
    static const int k_MaxRaysPerBatch = 32768; 
}

class RixIntegratorContext : public RixContext
{
public:
    int integratorCtxId;  
    int numRays;          
    int numActiveRays;  
    RtRayGeometry* primaryRays;
    RixRNG*        rngCtx;
    float*         time;  

    virtual RixDisplayServices*             GetDisplayServices(int version = 1) const  = 0;
    virtual RixLightingServices*            GetLightingServices(int version = 1) const = 0;
    virtual RixVolumeServices*              GetVolumeServices(int version = 1) const   = 0;
    virtual RixRefCntPtr<RixLPE>            GetRixLPE(int version = 1) const           = 0;
    virtual RixIntegratorEnvironment const& GetEnv(int version = 1) const              = 0;

    enum NearestHitFlags
    {
        k_None                  = 0,
        k_Primary               = 0x01, 
        k_IncludeMisses         = 0x02, 
        k_ConstrainToVolume     = 0x04, 
        k_ContinuationOpacity   = 0x08, 
        k_SkipVolumes           = 0x10, 
        k_Reserved1             = 0x20  
    };

    virtual void GetNearestHits(
        int nRays,
        RtRayGeometry const* rays,
        RixBXLobeTraits const& lobesWanted,
        RtRayGeometry::RayType rayType,
        int nearestHitFlags,
        RtUString const subset,
        RtUString const excludeSubset,
        RtHitSides hitSides,
        int* numShadingCtxs,
        RixShadingContext const** shadingCtxs) = 0;

    virtual void GetNearestHits(
        int nRays,
        RtRayGeometry const* rays,
        RtRayGeometry::RayType rayType,
        int nearestHitFlags,
        RtUString const subset,
        RtUString const excludeSubset,
        RtHitSides hitSides,
        RtHitPoint* hits) = 0;

    virtual void GetNearestHits(
        int                       nRays,
        RtRayGeometry const*      rays,
        RixBXLobeTraits const&    lobesWanted,
        bool                      wantsMisses,
        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,
        bool            isVolume       = false,
        bool            stochasticMode = true)
    {
        int nearestHitFlags =
            (isPrimary ? k_Primary : k_None) |            
            (wantsMisses ? k_IncludeMisses : k_None) |
            (isVolume ? k_ConstrainToVolume : k_None) |
            (stochasticMode ? k_None : k_ContinuationOpacity);
        RtRayGeometry::RayType raytype =
            (isLightPath ? RtRayGeometry::k_rtLight :
                (isPrimary ? RtRayGeometry::k_rtCamera : RtRayGeometry::k_rtIndirect));
        GetNearestHits(nRays, rays, lobesWanted,
            raytype, nearestHitFlags, subset, excludeSubset, hitSides, numShadingCtxs, shadingCtxs);
    }

    virtual void GetNearestHits(
        int                  nRays,
        RtRayGeometry const* rays,
        RtHitPoint*          hits,
        // optional inputs:
        RtUString const subset         = US_NULL,
        RtUString const excludeSubset  = US_NULL,
        RtHitSides      hitSides       = k_SidesBoth,
        bool            isPrimary      = false,
        bool            isVolume       = false,
        bool            stochasticMode = true)
    {
        int nearestHitFlags =
            (isPrimary ? k_Primary : k_None) |
            (isVolume ? k_ConstrainToVolume : k_None) |
            (stochasticMode ? k_None : k_ContinuationOpacity);
        RtRayGeometry::RayType raytype = (isPrimary ? RtRayGeometry::k_rtCamera : RtRayGeometry::k_rtIndirect);
        GetNearestHits(nRays, rays, raytype,
            nearestHitFlags, subset, excludeSubset, hitSides, hits);
    }

    virtual void GetTransmission(
        int                  nRays,
        RtRayGeometry const* rays,
        RtColorRGB*          transmissions,
        RtColorRGB*          volumeEmissions,
        // optional input:
        RtUString const subset        = US_NULL,
        RtUString const excludeSubset = US_NULL) = 0;

    virtual void ReleaseShadingContexts(
        int numShadingCtxs, RixShadingContext const** shadingCtxs) = 0;

    enum MemCategory
    {
        k_IntegratorMem
    };
    virtual void* Allocate(size_t nObjs, size_t objSize, MemCategory) = 0;

    // contexts for ray misses
    template <class T> T* Allocate(size_t nObjs)
    {
        T* mem = static_cast<T*>(Allocate(nObjs, sizeof(T), k_IntegratorMem));
        return mem;
    }

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

protected:
    ~RixIntegratorContext() override {}

public:
};

class RixIntegrator
{
public:
    virtual void RenderBegin(
        RixContext&               rCtx,
        RixIntegratorEnvironment& rixIntegratorEnv,
        RixParameterList const*   rixParameterList) = 0;
    virtual void RenderEnd(RixContext& ctx)         = 0;

    virtual void Synchronize(
        RixContext&             rCtx,
        RixSCSyncMsg            rixSCSyncMsg,
        RixParameterList const* rixParameterList)
    {
        PIXAR_ARGUSED(rCtx);
        PIXAR_ARGUSED(rixSCSyncMsg);
        PIXAR_ARGUSED(rixParameterList);
    }


    virtual void IntegrateRays(
        RixBXLobeTraits const&    lobesWanted,
        int*                      numShadingCtxs,
        RixShadingContext const** shadingCtxs,
        RixIntegratorContext&     iCtx)
    {
        if (iCtx.numActiveRays)
        {
            iCtx.GetNearestHits(
                iCtx.numActiveRays,
                iCtx.primaryRays,
                lobesWanted,
                RtRayGeometry::k_rtCamera,
                RixIntegratorContext::k_Primary,
                US_NULL, /*subset*/
                US_NULL, /*excludeSubset*/
                k_SidesFront,
                numShadingCtxs,
                shadingCtxs);
            RixDisplayServices* displayServices = iCtx.GetDisplayServices();
            for (int i = 0; i < *numShadingCtxs; ++i)
            {
                RixShadingContext const* sCtx = shadingCtxs[i];
                float const*           VLen;
                sCtx->GetBuiltinVar(RixShadingContext::k_VLen, &VLen);
                for (int j = 0; j < sCtx->numPts; ++j)
                {
                    int ctxIdx = sCtx->integratorCtxIndex[j];
                    displayServices->WriteDistance(ctxIdx, VLen[j], false);
                }
            }
            Integrate(*numShadingCtxs, shadingCtxs, iCtx);
        }
    }

    virtual void Integrate(
        int numShadingCtxs, RixShadingContext const* shadingCtxs[], RixIntegratorContext& iCtx) = 0;

    virtual void GetTransmission(
        int                   nRays,
        RtRayGeometry const*  rays,
        RtColorRGB*           transmissions,
        RtColorRGB*           volumeEmissions,
        RtUString const       subset,
        RtUString const       excludeSubset,
        RixLight const**      lights,
        RixIntegratorContext& iCtx)
    {
        PIXAR_ARGUSED(nRays);
        PIXAR_ARGUSED(rays);
        PIXAR_ARGUSED(transmissions);
        PIXAR_ARGUSED(volumeEmissions);
        PIXAR_ARGUSED(subset);
        PIXAR_ARGUSED(excludeSubset);
        PIXAR_ARGUSED(lights);
        PIXAR_ARGUSED(iCtx);
    }

    virtual bool GetProperty(
        RixIntegratorContext& iCtx,
        const int*            rayIds,
        int                   nRays,
        RayProperty           rayProperty,
        void const*           results)
    {
        PIXAR_ARGUSED(iCtx);
        PIXAR_ARGUSED(rayIds);
        PIXAR_ARGUSED(nRays);
        PIXAR_ARGUSED(rayProperty);
        PIXAR_ARGUSED(results);

        return false;
    }

    virtual bool SetProperty(
        RixIntegratorContext& iCtx,
        const int*            rayIds,
        int                   nRays,
        RayProperty           rayProperty,
        void const*           values)
    {
        PIXAR_ARGUSED(iCtx);
        PIXAR_ARGUSED(rayIds);
        PIXAR_ARGUSED(nRays);
        PIXAR_ARGUSED(rayProperty);
        PIXAR_ARGUSED(values);

        return false;
    }

protected:
    virtual ~RixIntegrator() {}
};

class RixIntegratorFactory : public RixShadingPlugin
{
public:
    int GetInterface() const override
    {
        return k_RixIntegratorFactory;
    }

    // Integrator plugins do not support InstanceData. As a consequence, the following methods are
    // not expected to be implemented and won't be called by the renderer.
    void CreateInstanceData(RixContext& rixCtx, RtUString const handle,
                            RixParameterList const* instanceParams,
                            InstanceData* instanceData) final
    {
        PIXAR_ARGUSED(rixCtx);
        PIXAR_ARGUSED(handle);
        PIXAR_ARGUSED(instanceParams);
        PIXAR_ARGUSED(instanceData);
    }

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

    virtual RixIntegrator* CreateIntegrator(RixContext& rCtx, RtUString const handle,
                                            RixParameterList const* pList) = 0;

    virtual void DestroyIntegrator(RixIntegrator const* integrator) = 0;

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

#define RIX_INTEGRATORFACTORYCREATE \
    extern "C" PRMANEXPORT RixIntegratorFactory* CreateRixIntegratorFactory(const char* hint)

#define RIX_INTEGRATORFACTORYDESTROY \
    extern "C" PRMANEXPORT void DestroyRixIntegratorFactory(RixIntegratorFactory* factory)

#endif