RixLPE.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 RixLPE_h
#define RixLPE_h

#include <map>                          // for map
#include <vector>                       // for vector
#include "RixBxdfLobe.h"
#include "RixIntegrator.h"              // for RixChannelId, etc
#include "RixInterfaces.h"              // for RixLPEToken, etc
#include "RixShadingUtils.h"            // for k_ZeroRGB
#include "prmanapi.h"                   // for PRMAN_INLINE
#include "RiTypesHelper.h"              // for RtColorRGB

class RixLPEAutomata;
class RixLPEState;
class RixShadingContext;

typedef std::vector<RixChannelId> ChanIdVec;

/* RixLPE interface -- Rix Light Path Expression (LPE) interface
 *
 * Use this interface to help support light path expression AOV display
 * channels in RIS integrators.
 *
 * RIS usage:
 *
 * See the source code for PxrDirectLighting and PxrPathTracer for
 * example code that uses the RixLPE interface in order to support light
 * path expression AOV display channels, and/or follow the example code
 * below.
 *
 * First, use RixIntegratorContext::GetRixLPE() to obtain a RixLPE instance:
 *
 *   RixLPE *rixLPE = integratorCtx->GetRixLPE();
 *
 * Then allocate RixLPEState instances (typically one per light path):
 *
 *   RixLPEState *states = rixLPE->AllocateStates(maxShadingCtxSize);
 *
 * Next, at each scattering event along the light path, call MoveXXX() on
 * the RixLPEState instance corresponding to that light path in order to
 * perform state transitions in the LPE deterministic finite automata for
 * each scattering event.
 *
 *   states[sCtxIndex].MoveCamera(sCtx, sCtxIndex);
 *   states[sCtxIndex].MoveVertex(sCtx, sCtxIndex, scatterEvent1); // primary hit
 *   states[sCtxIndex].MoveVertex(sCtx, sCtxIndex, scatterEvent2); // secondary hit
 *
 * Finally, use the RixLPE::SplatHelper class to aid with writing results to
 * the LPE AOV display channels:
 *
 *   RixLPE::SplatHelper aovs(...);
 *   aovs.SplatPerLobe(lobeWeights, weightIndex, thruput, isFinite, clamp, isHoldout);
 *
 * Note that SplatHelper::SplatPerLobe() is a utility routine that performs
 * the final direct lighting (or emissive object) light path transitions and
 * will accumulate the per-lobe contributions into the beauty and LPE AOVs.
 * (See the implementation of SplatPerLobe() in RixLPEInline.h for details.)
 *
 * Alternatively, some integrators may wish to manually perform the final
 * state transitions that reach a light or emissive object, and then make
 * separate per-lobe invocations of the SplatHelper::SplatValue() method to
 * accumulate contributions for each lobe. E.g.,:
 *
 *   states[sCtxIndex].MoveVertex(sCtx, sCtxIndex, scatterEvent3);
 *   states[sCtxIndex].MoveLight(sCtx, sCtxIndex, ...);
 *   RixLPE::SplatHelper aovs(...);
 *   aovs.SplatValue(lobe1Contribution, isFinite, clamp);
 *   aovs.SplatValue(lobe2Contribution, isFinite, clamp);
 *
 * For emissive objects, the SplatHelper::SplatEmission() method is used to 
 * record the illumination scattering event information:
 *
 *   aovs.SplatEmission(emission, thruput, isFinite, clamp, isHoldout);
 *
 * When the integrator is finished with the RixLPEState instances, then
 * use RixLPE::FreeStates() to free the memory of the RixLPEState instances:
 *
 *   rixLPE->FreeStates(maxShadingCtxSize, states);
 *
 * Use the RixLPE::AnyLPEs() method to determine whether there are any
 * light path expression (LPE) AOV display channels at all.
 *
 * Use the RixLPE::AnyCustomLPEs() method to determine whether there are any
 * custom (non-display channel) light path expressions (LPEs) at all.
 *
 * Use RixLPE::LgtGrpIdToToken() to convert a lightGroupId into a RixLPEToken
 * that can be passed into RixLPEState::MoveLight().
 *
 */

class RixLPE : public RixInterface
{
public:
    // The built-in LPE tokens.
    enum RixLPEBuiltInTokens
    {
        k_NULL = 0,
        k_NONE,
        k_CAMERA,
        k_LIGHT,
        k_OBJECT,
        k_TRANSMIT,
        k_REFLECT,
        k_STOP,
        k_BLANK,
        k_LAMBDA,
        k_DOT,
        k_DIFFUSE1,
        k_DIFFUSE2,
        k_DIFFUSE3,
        k_DIFFUSE4,
        k_SPECULAR1,
        k_SPECULAR2,
        k_SPECULAR3,
        k_SPECULAR4,
        k_SPECULAR5,
        k_SPECULAR6,
        k_SPECULAR7,
        k_SPECULAR8,
        k_USER1,
        k_USER2,
        k_USER3,
        k_USER4,
        k_USER5,
        k_USER6,
        k_USER7,
        k_USER8,
        k_USER9,
        k_USER10,
        k_USER11,
        k_USER12,
        k_EVERYLOBE,
        k_EVERYDIFFUSE,
        k_EVERYSPECULAR,
        k_EVERYUSER,
        k_numBuiltinTokens,
    };

    // Flags that control various aspects of what is written to the framebuffer
    // for LPE AOVs.
    enum RixLPEFlags
    {
        k_FlagWithOcclusion   = 0x1,
        k_FlagWithThruput     = 0x2,
        k_FlagWithClamp       = 0x4,
        k_FlagShadowsOnly     = 0x8,
        k_FlagOverwrite       = 0x10,
        k_FlagNoInfiniteCheck = 0x20,
        k_FlagHoldoutsOnly    = 0x40,
        k_FlagWhite           = 0x80,
        k_FlagWorldTransform  = 0x100,
        k_FlagObjectTransform = 0x200,
        k_FlagCameraTransform = 0x400,
        k_FlagVector          = 0x800,
        k_FlagNormal          = 0x1000,
    };

    static const int k_baseLgtGrpTokenOffset = k_numBuiltinTokens;

    // How to update LPE AOVs with the overwrite flag set.
    enum OverwritePolicy
    {
        k_Ignore,
        k_Overwrite,
        k_Accumulate
    };

    RixLPE()
        : RixInterface(1),
          m_anyLPEs(false),
          m_anyCustomLPEs(false),
          m_beautyChanId(k_InvalidChannelId)
    {
    }

    // Allocate and initialize an array of size 'count' of RixLPEState
    // instances.
    virtual RixLPEState* AllocateStates(int count) = 0;

    // Free an array of RixLPEState instances.
    virtual void FreeStates(int count, RixLPEState* states) = 0;

    // Convert an integer RixLPEToken identifier to a string.
    virtual RtUString TokenToString(RixLPEToken token) const = 0;

    // Convert a string to an integer RixLPEToken identifier.
    virtual RixLPEToken StringToToken(RtUString str) const = 0;

    // Convert an LPE group / object name to an integer RixLPEToken identifier.
    virtual RixLPEToken GroupAndObjectToToken(RtUString lpeGroup, 
                                              RtUString objName) const = 0;

    // Increment reference count on this object.
    virtual void IncRef() = 0;

    // Decrement reference count on this object, deleting it when zero.
    virtual void DecRef() = 0;

    // Return the current reference count on this object.
    virtual int  GetRefCnt() const = 0;

    PRMAN_INLINE static RixLPEToken LgtGrpIdToToken(int lightGroupId);

    // Return true if there are any light path expression AOVs.
    PRMAN_INLINE bool AnyLPEs() const;

    // Return true if there are any custom light path expressions.
    PRMAN_INLINE bool AnyCustomLPEs() const;

    virtual void Splat(const RixLPEState& accum, RixDisplayServices *dspy,
                       const RtColorRGB& val,
                       const int integratorCtxIdx, const RtColorRGB* lgtTrans,
                       const float clamp, const bool isFinite,
                       const OverwritePolicy overwritePolicy,
                       const bool isHoldout,
                       const RtMatrix4x4* worldXform = nullptr,
                       const RtMatrix4x4* objectXform = nullptr,
                       const RtMatrix4x4* cameraXform = nullptr) const = 0;

protected:
    // The destructor is protected: no need to delete RixLPE instances.
    virtual ~RixLPE() {}

    // True if there are any light path expression AOVs.
    bool m_anyLPEs;

    // True if there are any custom light path expressions.
    bool m_anyCustomLPEs;

    // The channel id of the beauty pass.
    RixChannelId m_beautyChanId;

public:
    // Represents the necessary information that we'll need to write out the
    // standard AOV channels.
    class SplatHelper
    {
    public:
        // Constructor overload that sets all fields. Pass in the current
        // RixLPEState instance up to this point along the light path
        // (the 'state' parameter), along with the light LPE token of the
        // current sample ('lightLpeToken'), the camera to primary hit transmission
        // ('eyeTrans'), and the shadowing term ('lightTrans').
        PRMAN_INLINE
        SplatHelper(
            RixDisplayServices* displaySvc,
            int integratorCtxIndex,
            RixLPE& rixLpe,
            RixLPEState& state,
            int depth,
            RixLPEToken lightLpeToken,
            RixLPEToken lpeGroupId,
            bool isReflect,
            RtColorRGB const& eyeTrans,
            RtColorRGB const& lightTrans,
            RixShadingContext const* shadingCtx,
            int shadingCtxIndex,
            bool writeOpacityAllowed = true);

        PRMAN_INLINE ~SplatHelper();

        // Call this routine to splat per-lobe illumination to the beauty and
        // LPE AOVs when performing the direct lighting optimization. We want
        // to perform the splat for some AOVs only if each component of the
        // beauty RGB value is finite. Also, in the case of clamping, we want
        // to use a consistent clamp factor across all illumination AOVs, so
        // pass in the clamping scalar factor as an argument to this method
        // (default is 1.0, or no clamping).
        PRMAN_INLINE void SplatPerLobe(
            RixBXActiveLobeWeights& activeLobes,
            int weightIndex,
            RtColorRGB const& thruput,
            bool isFinite,
            float clamp                       = 1.0f,
            bool isHoldout                    = false);

        // Call this routine to splat emissive objects to the beauty and
        // LPE AOVs when performing the direct lighting optimization. We want
        // to perform the splat for some AOVs only if each component of the
        // beauty RGB value is finite. Also, in the case of clamping, we want
        // to use a consistent clamp factor across all illumination AOVs, so
        // pass in the clamping scalar factor as an argument to this method
        // (default is 1.0, or no clamping).
        PRMAN_INLINE void SplatEmission(
            RtColorRGB const& emission,
            RtColorRGB const& thruput,
            bool isFinite,
            float clamp            = 1.0f,
            bool isHoldout         = false);

        // Call this routine to splat a single illumination contribution to the
        // beauty and LPE AOVs. The RixLPEState instance passed by reference
        // into the SplatHelper class constructor should have already performed
        // the final state transition that corresponds to hitting a geolight or
        // emissive object just prior to calling this routine, and then this
        // method will accumulate the illumination contribution for the
        // appropriate set of LPE AOVs (along with the beauty display channel).
        PRMAN_INLINE void SplatValue(
            RtColorRGB const& color,
            bool isFinite,
            float clamp                       = 1.0f);

        // Helper routine to splat a color/alpha to the beauty channel id.
        PRMAN_INLINE void SplatBeauty(
            RtColorRGB const& val,
            RtColorRGB& trans) const;

        // Helper routine to splat a color/alpha to the array of channel ids
        // associated with the current light path expression automata state.
        PRMAN_INLINE void SplatLPE(
            RtColorRGB const& val,
            RtColorRGB const* lightTrans,
            bool isFinite,
            float clamp,
            int lpeId                       = -1,
            OverwritePolicy overwritePolicy = k_Overwrite,
            bool isHoldout                  = false);

        // The following fields represent the information that we'll
        // need to write out the standard set of AOVs.
        int m_depth;
        RixLPEToken m_lgtLpeToken;
        RixLPEToken m_lpeGrpId;
        bool m_isReflect;
        RtColorRGB m_eyeTrans;
        RtColorRGB m_lgtTrans;

        // Cached references to the display services, context index, rixLpe,
        // and the state of the LPE automata.
        RixDisplayServices* m_displaySvc;
        int m_integratorCtxIdx;
        RixLPE& m_rixLpe;
        RixLPEState& m_state;
        RixShadingContext const* m_sCtx;
        int m_shadingCtxIdx;
        bool m_writeOpacityAllowed;
        const RtMatrix4x4 * m_worldXform;
        const RtMatrix4x4 * m_objectXform;
        const RtMatrix4x4 * m_cameraXform;
    };
};

// Represents a scatter event in the LPE system. One of these should be
// constructed for each call to the MoveVertex overloads when state should
// be transitioned at a light path vertex.
// There are three constructors for three use-cases:
//  One to construct a scatter event from a vertex that has generated a sample
//  This is predominantly used by a forward path tracer
//
//  One to construct a scatter event from a vertex that has evaluated a sample
//  This is predominantly used when trying to connect paths or merge paths in
//  a bidirectional path tracer or VCM
//
//  One to allow the LPE system to transition state for multiple lobes generated
//  by next-event-estimation independently.
//
// The constructors perform error checking to ensure that there is only one
// scatter event defined by the passed in lobe traits and to ensure that the
// sampled lobe is valid. If neither of these are true an invalid scatter
// event is returned. Invalid scatter events have no effect on the LPE automatas
// when transitioning state.
class RixLPEScatterEvent
{
public:
    // Configures the event from a lobe sampled. The user lobe is ignored in the
    // lobe sampled so this is mostly useful to transition state for indirect.
    PRMAN_INLINE RixLPEScatterEvent(RixBXLobeSampled lobeSampled);

    // Configures the event as a scatter event determined from traits. The
    // traits must represent a single lobe, otherwise the scatter event is
    // invalid.
    PRMAN_INLINE RixLPEScatterEvent(RixBXLobeTraits traits);

    // Configures the event arbitrarily.
    PRMAN_INLINE RixLPEScatterEvent(bool isReflect, bool isUser,
                                    bool isSpecular, unsigned char lpeId);

    // Is the scatter event valid
    PRMAN_INLINE bool GetValid() const;

    // Get the token corresponding to the event type from this scatter event.
    // Should be one of k_REFLECT or k_TRANSMIT
    PRMAN_INLINE RixLPEToken GetEvent() const;

    // Get the token corresponding to the scatter type. This will be one of
    // the DIFFUSE, SPECULAR or USER types.
    PRMAN_INLINE RixLPEToken GetScatt() const;

    // Get the lpe id of the lobe that this scatter event represents
    PRMAN_INLINE unsigned char GetLpeId() const;

    // Get the lpe index of the lobe that this scatter event represents. This
    // is different from the lpe id since this is an absolute index starting
    // at 0. E.g. the 0'th specular index is k_numDiffuse since the specular
    // indices follow the diffuse indices, although the specular lpe id will
    // be 0 in this case.
    PRMAN_INLINE unsigned char GetLpeIndex() const;

private:
    bool          m_isReflect;
    unsigned char m_lpeId;
    unsigned char m_lpeIndex;
    RixLPEToken   m_scatter;
};

class RixLPEState
{
public:
    RixLPEState( RixLPEAutomata const* automata, const int nautomata );

    ~RixLPEState();

    void Reset();

    std::vector<short>& GetState();
    const std::vector<short>& GetState() const;
    void SetState(const std::vector<short>& state);
    bool Broken() const;
    bool Test(const RixLPEToken dir, const RixLPEToken sca,
              const RixLPEToken custom);

    const RtColorRGB& GetThruput() const;
    const RixLPEAutomata* GetAutomata(int &nautomata) const;

    void MoveCamera(RixShadingContext const* sCtx, int sCtxIndex);

    void MoveCamera(RixShadingContext const* sCtx, int sCtxIndex,
                   const RtColorRGB& thruput);

    void MoveEmissiveObject(
        RixShadingContext const* sCtx,
        int sCtxIndex,
        RtColorRGB const& thruput,
        RixLPEToken lpeGroupId = RixLPE::k_BLANK);

    void MoveLight(
        RixShadingContext const* sCtx,
        int sCtxIndex,
        RtColorRGB const& thruput,
        RtColorRGB const* lightTrans,
        bool firstContribution,
        RixLPEToken lgtLpeToken);

    void MoveVertex(
        RixShadingContext const* sCtx,
        int sCtxIndex,
        RixLPEScatterEvent const scatterEvent,
        RixLPEToken lpeGroupId   = RixLPE::k_BLANK);

    void MoveVertex(
        RixShadingContext const* sCtx,
        int sCtxIndex,
        RixLPEScatterEvent const scatterEvent,
        const RtColorRGB& thruput,
        RixLPEToken lpeGroupId   = RixLPE::k_BLANK,
        bool doStateTransition = true);

private:

    void move( const RixLPEToken event, const RixLPEToken scatt,
               const RixLPEToken custom = RixLPE::k_BLANK );

    // Constant, read-only, data shared amongst all state mutable accumulator
    // instances
    const RixLPEAutomata *m_automata;
    int                   m_nautomata;

    // Mutable data specific per-path
    std::vector<short>    m_state;

    // This LPE's current path thruput
    RtColorRGB            m_thruput;
};

//
// class RixLPE inline method implementation
//

#include "RixLPEInline.h" // IWYU pragma: export

#endif