RixLPEInline.h

Go to the documentation of this file.

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

#ifndef RixLPEInline_h
#define RixLPEInline_h

#include <cstddef>                      // for NULL
#include <map>                          // for map, etc
#include <set>                          // for set
#include <utility>                      // for pair
#include <vector>                       // for vector
#include "RixBxdfLobe.h"                // for RixBXLobeSampled, etc
#include "RixIntegrator.h"              // for RixDisplayServices, etc
#include "RixInterfaces.h"              // for RixLPEToken, RixCustomLPE
#include "RixShadingUtils.h"            // for k_ZeroRGB, k_OneRGB
#include "prmanapi.h"                   // for PRMAN_INLINE
#include "RiTypesHelper.h"              // for RtColorRGB

class RixLPE;
class RixLPEState;
class RixShadingContext;

// The number of scattering types: e.g., D1, D2, ..., S1, S2, ...
static const unsigned char k_numScatterTypes = k_RixBXMaxNumDiffuseLobes +
                                               k_RixBXMaxNumSpecularLobes +
                                               k_RixBXMaxNumUserLobes;

// Offsets to start of each group
static const unsigned char k_diffStart = 0;
static const unsigned char k_specStart = k_diffStart + k_RixBXMaxNumDiffuseLobes;
static const unsigned char k_userStart = k_specStart + k_RixBXMaxNumSpecularLobes;

class RixLPEAutomata
{
public:
    short getTransition(short state, RixLPEToken symbol)const
    {
        const State &mystate = m_states[state];
        const Transition *begin = &m_trans[mystate.begin_trans];
        const Transition *end = begin + mystate.ntrans;
        while (begin < end) { // binary search
            const Transition *middle = begin + ((end - begin)>>1);
            if (symbol < middle->symbol)
                end = middle;
            else if (middle->symbol < symbol)
                begin = middle + 1;
            else // match
                return middle->state;
        }
        return mystate.wildcard_trans;
    }

    void * const * getRules(int state, int &count)const
    {
        count = m_states[state].nrules;
        return &m_rules[m_states[state].begin_rules];
    }

    struct State
    {
        unsigned int     begin_trans;
        unsigned int     ntrans;
        unsigned int     begin_rules;
        unsigned int     nrules;
        short            wildcard_trans;
        std::vector<int> customIdVec;
    };
    struct Transition
    {
        // we use this only for sorting
        static bool trans_comp (const Transition &a, const Transition &b)
        {
            return a.symbol < b.symbol;
        }
        RixLPEToken symbol;
        short       state;
    };
    std::vector<Transition> m_trans;
    std::vector<void *>     m_rules;
    std::vector<State>      m_states;
};

//
// class RixLPE inline method implementation
//

// Convert an integer light group id to a LPE token.
PRMAN_INLINE RixLPEToken
RixLPE::LgtGrpIdToToken(int lgtGrpId)
{
    // Offset the light group id by the number of built-in tokens.
    if (lgtGrpId >= 0)
        return lgtGrpId + k_baseLgtGrpTokenOffset;
    else
        return k_BLANK;
}

// Return true if there are any light path expression AOVs.
PRMAN_INLINE bool
RixLPE::AnyLPEs() const
{
    return m_anyLPEs;
}

// Return true if there are any custom light path expressions.
PRMAN_INLINE bool
RixLPE::AnyCustomLPEs() const
{
    return m_anyCustomLPEs;
}

// class RixLPEState implementation

PRMAN_INLINE
RixLPEState::RixLPEState(
    RixLPEAutomata const* automata, const int nautomata )
    : m_automata( automata ), m_nautomata( nautomata )
{
    Reset();
}

PRMAN_INLINE
RixLPEState::~RixLPEState()
{
}

PRMAN_INLINE void
RixLPEState::Reset()
{
    m_state.resize(m_nautomata);
    std::fill(m_state.begin(), m_state.end(), 0);
    m_thruput.One();
}

PRMAN_INLINE std::vector<short>&
RixLPEState::GetState()
{
    return m_state;
}

PRMAN_INLINE const std::vector<short>&
RixLPEState::GetState() const
{
    return m_state;
}

PRMAN_INLINE void
RixLPEState::SetState(const std::vector<short>& state)
{
    m_state = state;
}

PRMAN_INLINE bool
RixLPEState::Broken() const 
{
    if( !m_automata ) return true;
    for( int i = 0; i < m_nautomata; i++ ) if(m_state[i] >=0) return false;
    return true;
}

PRMAN_INLINE bool
RixLPEState::Test(const RixLPEToken dir, const RixLPEToken sca,
                  const RixLPEToken custom)
{
    std::vector<short> saveState = GetState();
    move(dir, sca, custom);
    bool active = !Broken();
    SetState(saveState);
    return active;
}

PRMAN_INLINE const RtColorRGB&
RixLPEState::GetThruput() const
{
    return m_thruput;
}

PRMAN_INLINE const RixLPEAutomata*
RixLPEState::GetAutomata(int& nautomata) const
{
    nautomata = m_nautomata;
    return m_automata;
}

PRMAN_INLINE void
RixLPEState::MoveCamera(RixShadingContext const* sCtx, int sCtxIndex)
{
    PIXAR_ARGUSED(sCtx);
    PIXAR_ARGUSED(sCtxIndex);
    move( RixLPE::k_CAMERA, RixLPE::k_NONE );
}

PRMAN_INLINE void
RixLPEState::MoveCamera(RixShadingContext const* sCtx, int sCtxIndex,
                        const RtColorRGB& thruput)
{
    PIXAR_ARGUSED(sCtx);
    PIXAR_ARGUSED(sCtxIndex);
    move( RixLPE::k_CAMERA, RixLPE::k_NONE );
    m_thruput *= thruput;
}

PRMAN_INLINE void
RixLPEState::MoveEmissiveObject(
        RixShadingContext const* sCtx,
        int sCtxIndex,
        RtColorRGB const& thruput,
        RixLPEToken lpeGroupId)
{
    PIXAR_ARGUSED(sCtx);
    PIXAR_ARGUSED(sCtxIndex);
    PIXAR_ARGUSED(thruput);
    move( RixLPE::k_OBJECT, RixLPE::k_NONE, lpeGroupId );
}

PRMAN_INLINE void
RixLPEState::MoveLight(
        RixShadingContext const* sCtx,
        int sCtxIndex,
        RtColorRGB const& thruput,
        RtColorRGB const* lightTrans,
        bool firstContribution,
        RixLPEToken lgtLpeToken)
{
    PIXAR_ARGUSED(sCtx);
    PIXAR_ARGUSED(sCtxIndex);
    PIXAR_ARGUSED(thruput);
    PIXAR_ARGUSED(lightTrans);
    PIXAR_ARGUSED(firstContribution);
    move( RixLPE::k_LIGHT, RixLPE::k_NONE, lgtLpeToken );
}

PRMAN_INLINE void
RixLPEState::MoveVertex(
        RixShadingContext const* sCtx,
        int sCtxIndex,
        RixLPEScatterEvent const scatterEvent,
        RixLPEToken lpeGroupId)
{
    PIXAR_ARGUSED(sCtx);
    PIXAR_ARGUSED(sCtxIndex);
    if( scatterEvent.GetValid() )
    {
        RixLPEToken event = scatterEvent.GetEvent();
        RixLPEToken scatt = scatterEvent.GetScatt();

        move( event, scatt, lpeGroupId );
    }
}

PRMAN_INLINE void
RixLPEState::MoveVertex(
        RixShadingContext const* sCtx,
        int sCtxIndex,
        RixLPEScatterEvent const scatterEvent,
        const RtColorRGB& thruput,
        RixLPEToken lpeGroupId,
        bool doStateTransition)
{
    PIXAR_ARGUSED(sCtx);
    PIXAR_ARGUSED(sCtxIndex);
    if( scatterEvent.GetValid() )
    {
        RixLPEToken event = scatterEvent.GetEvent();
        RixLPEToken scatt = scatterEvent.GetScatt();

        if( doStateTransition )
        {
            move( event, scatt, lpeGroupId );
        }

        m_thruput *= thruput;
    }
}

PRMAN_INLINE void
RixLPEState::move( const RixLPEToken event, const RixLPEToken scatt,
                     const RixLPEToken custom )
{
    if( !m_automata )
        return;

    for( int i = 0; i < m_nautomata; i++ )
    {
        if (m_state[i] >= 0)
            m_state[i] = m_automata[i].getTransition(m_state[i], event);
        if (m_state[i] >= 0)
            m_state[i] = m_automata[i].getTransition(m_state[i], scatt);
        if (m_state[i] >= 0)
            m_state[i] = m_automata[i].getTransition(m_state[i], custom);
        if (m_state[i] >= 0)
            m_state[i] = m_automata[i].getTransition(m_state[i], RixLPE::k_STOP);
    }
}


//
// class RixLPEScatterEvent implementation
//

PRMAN_INLINE
RixLPEScatterEvent::RixLPEScatterEvent(bool isReflect, bool isUser,
                                       bool isSpecular, unsigned char lpeId)
{
    m_isReflect = isReflect;
    m_lpeId = lpeId;
    if( isUser )
    {
        m_scatter = RixLPE::k_USER1 + m_lpeId;
        m_lpeIndex = static_cast<unsigned char>(k_userStart + m_lpeId);
    }
    else if( isSpecular )
    {
        m_scatter = RixLPE::k_SPECULAR1 + m_lpeId;
        m_lpeIndex = static_cast<unsigned char>(k_specStart + m_lpeId);
    }
    else
    {
        m_scatter = RixLPE::k_DIFFUSE1 + m_lpeId;
        m_lpeIndex = static_cast<unsigned char>(k_diffStart + m_lpeId);
    }
}

PRMAN_INLINE
RixLPEScatterEvent::RixLPEScatterEvent(RixBXLobeSampled lobeSampled)
{
    m_isReflect = lobeSampled.GetReflect();
    m_lpeId = lobeSampled.GetLpeId();

    if( !lobeSampled.GetValid() )
    {
        m_scatter = RixLPE::k_NONE;
        m_lpeIndex = 0;
    }
    else if( lobeSampled.GetUser() )
    {
        m_scatter = RixLPE::k_USER1 + m_lpeId;
        m_lpeIndex = static_cast<unsigned char>(k_userStart + m_lpeId);
    }
    else if( lobeSampled.GetSpecular() )
    {
        m_scatter = RixLPE::k_SPECULAR1 + m_lpeId;
        m_lpeIndex = static_cast<unsigned char>(k_specStart + m_lpeId);
    }
    else
    {
        // Diffuse
        m_scatter = RixLPE::k_DIFFUSE1 + m_lpeId;
        m_lpeIndex = static_cast<unsigned char>(k_diffStart + m_lpeId);
    }
}

PRMAN_INLINE
RixLPEScatterEvent::RixLPEScatterEvent(RixBXLobeTraits traits)
{
    m_isReflect = traits.GetReflect();

    // Find the lpeId
    unsigned short dl = traits.GetDiffuse();
    unsigned short sl = traits.GetSpecular();

    // Only a maximum of one of these should be set
    assert((dl && !sl) ||
           (sl && !dl) ||
           (!dl && !sl));

    if( (dl && sl) || (!dl && !sl) )
    {
        // Neither set is a supported case. We invalidate the scatter event.
        // Both set is unsupported. Again we invalidate the scatter event.
        m_scatter = RixLPE::k_NONE;
        m_lpeId = m_lpeIndex = 0;
        return;
    }

    // An important point to consider here is that, due to the tests above,
    // either dl or sl will be non-zero. As a consequence, the following sequence
    // will never produce an undefined result for m_lpeId because the value
    // passed to RixFindFirstSetBit will always be non-zero.
    bool isDiffuse = (dl != 0);
    if( isDiffuse )
        m_lpeId = static_cast<unsigned char>(RixFindFirstSetBit(dl));
    else
        m_lpeId = static_cast<unsigned char>(RixFindFirstSetBit(sl));

    m_lpeIndex = isDiffuse ? k_diffStart : k_specStart;
    m_lpeIndex = static_cast<unsigned char>(m_lpeIndex + m_lpeId);

    m_scatter = isDiffuse ? RixLPE::k_DIFFUSE1 : RixLPE::k_SPECULAR1;
    m_scatter += m_lpeId;
}

PRMAN_INLINE RixLPEToken
RixLPEScatterEvent::GetEvent() const
{
    return !GetValid() ? RixLPE::k_NONE :
        (m_isReflect ? RixLPE::k_REFLECT : RixLPE::k_TRANSMIT);
}

PRMAN_INLINE RixLPEToken
RixLPEScatterEvent::GetScatt() const
{
    return !GetValid() ? RixLPE::k_NONE : m_scatter;
}

PRMAN_INLINE unsigned char
RixLPEScatterEvent::GetLpeId() const
{
    return !GetValid() ? 0 : m_lpeId;
}

PRMAN_INLINE unsigned char
RixLPEScatterEvent::GetLpeIndex() const
{
    return !GetValid() ? 0 : m_lpeIndex;
}

PRMAN_INLINE bool
RixLPEScatterEvent::GetValid() const
{
    return (m_scatter != RixLPE::k_NONE);
}

//
// class RixLPE::SplatHelper inline method implementation
//

PRMAN_INLINE
RixLPE::SplatHelper::SplatHelper(
    RixDisplayServices* displaySvc,
    int integratorCtxIdx,
    RixLPE& rixLpe,
    RixLPEState& state,
    int depth,
    RixLPEToken lgtLpeToken, 
    RixLPEToken lpeGrpId,
    bool isReflect,
    RtColorRGB const& eyeTrans,
    RtColorRGB const& lgtTrans,
    RixShadingContext const* sCtx,
    int shadingCtxIdx,
    bool writeOpacityAllowed)
    : m_depth(depth),
      m_lgtLpeToken(lgtLpeToken),
      m_lpeGrpId(lpeGrpId),
      m_isReflect(isReflect),
      m_lgtTrans(lgtTrans),
      m_displaySvc(displaySvc),
      m_integratorCtxIdx(integratorCtxIdx),
      m_rixLpe(rixLpe),
      m_state(state),
      m_sCtx(sCtx),
      m_shadingCtxIdx(shadingCtxIdx),
      m_writeOpacityAllowed(writeOpacityAllowed)
{
    m_eyeTrans = eyeTrans;
}

PRMAN_INLINE RixLPE::SplatHelper::~SplatHelper()
{
}

PRMAN_INLINE void
RixLPE::SplatHelper::SplatPerLobe(
    RixBXActiveLobeWeights& activeLobes,
    int weightIndex,
    RtColorRGB const& thruput,
    bool isFinite,
    float clamp,
    bool isHoldout)
{
    // Obtain alpha and write Ci.
    RixLPE const& rixLpe = m_rixLpe;

    // Splat LPEs before splat beauty
    if (rixLpe.m_anyLPEs)
    {
        // Light path expressions.
        bool isReflect = m_isReflect;
        RixLPEToken lgtLpeToken = m_lgtLpeToken;

        bool firstContribution = true;

        // backup path state, try avoiding avoiding memory allocations
        std::vector<short>& state = m_state.GetState();
        size_t stateSize = state.size();
        short stateBuffer[1<<16];

        short* stateBackup = stateBuffer;
        if (stateSize > 1<<16)
            // We seems to have a huge number of automatas, we resort to heap memory
            stateBackup = (short*)malloc(stateSize*sizeof(short));

        memcpy(stateBackup, state.data(), stateSize*sizeof(short));

        // Add any non-blank diffuse lobes.
        for (int i = 0; i < activeLobes.GetNumDiffuseLobes(); i++)
        {
            RtColorRGB const& diffuse =
                activeLobes.GetDiffuseLobe(i)[weightIndex];

            firstContribution = false;

            unsigned char lpeId = activeLobes.GetDiffuseLpeId(i);
            int diffLpeId = k_diffStart + lpeId;
            RixLPEScatterEvent lpeEvent( isReflect, false, false, lpeId );
            m_state.MoveVertex(
                m_sCtx, m_shadingCtxIdx, lpeEvent,
                m_lpeGrpId);
            m_state.MoveLight(
                m_sCtx, m_shadingCtxIdx, diffuse, &m_lgtTrans,
                firstContribution, lgtLpeToken);
            SplatLPE(
                diffuse, &m_lgtTrans, isFinite, clamp, diffLpeId,
                k_Overwrite, isHoldout);

            // Restore path state
            memcpy(state.data(), stateBackup, stateSize*sizeof(short));
        }

        // Add any non-blank specular lobes.
        for (int i = 0; i < activeLobes.GetNumSpecularLobes(); i++)
        {
            RtColorRGB const& specular =
                activeLobes.GetSpecularLobe(i)[weightIndex];

            firstContribution = false;

            unsigned char lpeId = activeLobes.GetSpecularLpeId(i);
            int specLpeId = k_specStart + lpeId;
            RixLPEScatterEvent lpeEvent( isReflect, false, true, lpeId );
            m_state.MoveVertex(
                m_sCtx, m_shadingCtxIdx, lpeEvent,
                m_lpeGrpId);
            m_state.MoveLight(
                m_sCtx, m_shadingCtxIdx, specular, &m_lgtTrans,
                firstContribution, lgtLpeToken);
            SplatLPE(
                specular, &m_lgtTrans, isFinite, clamp, specLpeId,
                k_Overwrite, isHoldout);

            // Restore path state
            memcpy(state.data(), stateBackup, stateSize*sizeof(short));
        }

        // Add any non-blank user lobes.
        for (int i = 0; i < activeLobes.GetNumUserLobes(); i++)
        {
            RtColorRGB const& user = activeLobes.GetUserLobe(i)[weightIndex];

            firstContribution = false;

            unsigned char lpeId = activeLobes.GetUserLpeId(i);
            int userLpeId = k_userStart + lpeId;
            RixLPEScatterEvent lpeEvent( isReflect, true, false, lpeId );
            m_state.MoveVertex(
                m_sCtx, m_shadingCtxIdx, lpeEvent,
                m_lpeGrpId);
            m_state.MoveLight(
                m_sCtx, m_shadingCtxIdx, user, &m_lgtTrans, firstContribution,
                lgtLpeToken);
            SplatLPE(
                user, &m_lgtTrans, isFinite, clamp, userLpeId, k_Overwrite,
                isHoldout);

            // Restore path state
            memcpy(state.data(), stateBackup, stateSize*sizeof(short));
        }

        if (stateBackup != stateBuffer) free(stateBackup);
    }

    // Beauty channel (Ci).
    if (rixLpe.m_beautyChanId != k_InvalidChannelId)
    {
        if (!isHoldout)
        {
            RtColorRGB val = isFinite
                 ? activeLobes.SumAtIndex(weightIndex) * thruput * m_lgtTrans * clamp
                 : RixConstants::k_ZeroRGB;

            SplatBeauty(val, m_eyeTrans);
        }
        else if (m_writeOpacityAllowed && (m_depth == 0))
        {
            float trans1 = m_eyeTrans.ChannelAvg();
            if (trans1 != 1.0f)
            {
                m_displaySvc->WriteOpacity(
                    m_rixLpe.m_beautyChanId, m_integratorCtxIdx, 1.0f - trans1);
            }
        }
    }
}

PRMAN_INLINE void
RixLPE::SplatHelper::SplatEmission(
    RtColorRGB const& emission,
    RtColorRGB const& thruput,
    bool isFinite,
    float clamp,
    bool isHoldout)
{
    // Obtain alpha and write Ci.
    RixLPE const& rixLpe = m_rixLpe;

    // Splat LPEs before splat beauty since we may have holdout LPE that will
    // change the Beauty and alpha
    if (rixLpe.m_anyLPEs)
    {
        // backup path state, try avoiding avoiding memory allocations
        std::vector<short>& state = m_state.GetState();
        size_t stateSize = state.size();
        short stateBuffer[1<<16];

        short* stateBackup = stateBuffer;
        if (stateSize > 1<<16)
            // We seems to have a huge number of automatas, we resort to heap memory
            stateBackup = (short*)malloc(stateSize*sizeof(short));

        memcpy(stateBackup, state.data(), stateSize*sizeof(short));

        m_state.MoveEmissiveObject(
            m_sCtx, m_shadingCtxIdx, emission, m_lpeGrpId);
        SplatLPE(
            emission, 0, isFinite, clamp, -1, k_Accumulate,
            isHoldout);

        // Restore path state
        memcpy(state.data(), stateBackup, stateSize*sizeof(short));

        if (stateBackup != stateBuffer) free(stateBackup);
    }

    // Beauty channel (Ci).
    if (rixLpe.m_beautyChanId != k_InvalidChannelId)
    {
        if (!isHoldout)
        {
            SplatBeauty(
                isFinite
                    ? (emission * thruput * m_lgtTrans * clamp)
                    : RixConstants::k_ZeroRGB,
                m_eyeTrans);
        }
        else if (m_writeOpacityAllowed && (m_depth == 0))
        {
            float trans1 = m_eyeTrans.ChannelAvg();
            if (trans1 != 1.0f)
            {
                m_displaySvc->WriteOpacity(
                    m_rixLpe.m_beautyChanId, m_integratorCtxIdx, 1.0f - trans1);
            }
        }
    }
}

PRMAN_INLINE void
RixLPE::SplatHelper::SplatValue(
    RtColorRGB const& color,
    bool isFinite,
    float clamp)
{
    // Splat LPEs before splat beauty since we may have holdout LPE that will
    // change the Beauty's alpha

    if (m_rixLpe.m_anyLPEs)
    {
        SplatLPE(color, &m_lgtTrans, isFinite, clamp, -1);
    }

    SplatBeauty(
        isFinite
            ? (color * m_lgtTrans * clamp)
            : RixConstants::k_ZeroRGB,
        m_eyeTrans);
}

PRMAN_INLINE void
RixLPE::SplatHelper::SplatBeauty(RtColorRGB const& val, RtColorRGB& trans) const
{
    m_displaySvc->Splat(m_rixLpe.m_beautyChanId, m_integratorCtxIdx, val);

    float trans1 = trans.ChannelAvg();
    if (m_writeOpacityAllowed && (m_depth == 0) && (trans1 != 1.0f))
    {
        m_displaySvc->WriteOpacity(
            m_rixLpe.m_beautyChanId, m_integratorCtxIdx, 1.0f - trans1);
    }
}

PRMAN_INLINE void
RixLPE::SplatHelper::SplatLPE(
    RtColorRGB const& val,
    RtColorRGB const* lgtTrans,
    bool isFinite,
    float clamp,
    int lpeId,
    OverwritePolicy overwritePolicy,
    bool isHoldout)
{
    PIXAR_ARGUSED(lpeId);
    m_rixLpe.Splat( m_state, m_displaySvc, val,
                    m_integratorCtxIdx, lgtTrans,
                    clamp, isFinite, overwritePolicy, isHoldout );
}

#endif