RixLighting.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 RixLighting_h
#define RixLighting_h

#include "RixBxdf.h"        // for RixBXEvaluateDomain, etc
#include "RixInterfaces.h"  // for RixInterface
#include "RiTypesHelper.h"  // for RtVector3, RtPoint3

class RixPhotonGuiding;
class RixRNG;
class RixShadingContext;
struct RixMWConnectionResult;
struct RixBXLobeSampled;
struct RixBXLobeTraits;
struct RixBXLobeWeights;

class RixLightingServices : public RixInterface
{
public:
    RixLightingServices() : RixInterface(1), shadingCtx(nullptr), domain(k_RixBXBoth)
    {}

    // Local lighting (shading context aware and importance sampled)
    enum IntegratorIntent
    {
        k_LightSamples,
        k_MaterialSamples,
        k_MaterialAndLightSamples
    };

    enum FixedSampleCountMode
    {
        k_IgnoreFixedSampleCount = 0,
        k_RespectFixedSampleCount = 1,
        k_ReducedFixedSampleCount = 2
    };
    typedef FixedSampleCountMode Mode;  // for backward compatibility

    class SampleMode
    {
    public:
        enum Mode
        {
            k_forPoint,
            k_forLineSegment
        };

        Mode mode;

        SampleMode() : mode(k_forPoint){};
    };

    virtual void Begin(
        // inputs
        RixShadingContext const* shadingContext, RixRNG* rixRNG,
        RixBXEvaluateDomain evaluationDomain, IntegratorIntent integratorIntent,
        FixedSampleCountMode fixedSampleCountMode, SampleMode sampleMode,
        // outputs
        int* fixedSampleCount = nullptr,
        // inputs
        int depth = 0, int parentIndirectCount = 1) = 0;

    virtual void GenerateSamples(
        // Pointer parameters that represent arrays are expected to either be of size:
        // - numPts (#1) or
        // - numPts * numLightSamples (#2)
        int numLightSamples, RixRNG* rixRNG,

        // outputs
        int* lightGroupIds,              // #2
        RixLPEToken* lightLpeTokens,     // #2
        RtVector3* directionsToSamples,  // #2
        RtNormal3* lightNormals,         // #2
        float* distancesToSamples,       // #2
        RixBXLobeWeights* lightContributions,

        RtColorRGB* transmissions,    // #2, optional
        RtColorRGB* volumeEmissions,  // #2, optional
        float* directLightingPdfs,    // #2
        float* selectionProbs,        // #2
        // inputs
        RixBXLobeTraits const* materialLobesWanted,  // #1, optional

        // outputs
        RixBXLobeWeights* evaluatedMaterialWeights,  // optional
        float* evaluatedMaterialFPdfs,               // #2, optional
        float* evaluatedMaterialRPdfs,               // #2, optional
        RixBXLobeTraits* evaluatedMaterialLobes,     // #2, optional

        RixLight** sampledLights,  // #2, optional

        // inputs
        RtColorRGB const* pathThroughputs = nullptr,  // #1, optional
        RixMWConnectionResult* mwConnectionResult = nullptr  // optional
        ) = 0;

    virtual void GenerateSamples(
        // Pointer parameters that represent arrays are expected to either be of size:
        // - numPts (#1) or
        // - numPts * numLightSamples (#2)
        // inputs
        int numLightSamples, RixRNG* rixRNG,

        // outputs
        int* lightGroupIds,              // #2
        RixLPEToken* lightLpeTokens,     // #2
        RtVector3* directionsToSamples,  // #2
        RtNormal3* lightNormals,         // #2
        float* distancesToSamples,       // #2
        RixBXLobeWeights* lightContributions,

        RtColorRGB* transmissions,    // #2, optional
        RtColorRGB* volumeEmissions,  // #2, optional
        float* directLightingPdfs,    // #2
        float* selectionProbs,        // #2

        float* emissionPositionPdfs,     // #2
        float* emissionDirectionPdfs,    // #2, FLT_MAX for infinite lights
        float* solidAngleToAreaFactors,  // #2, 1.0f for infinite lights

        // inputs
        RixBXLobeTraits const* materialLobesWanted,  // #1, optional

        // outputs
        RixBXLobeWeights* evaluatedMaterialWeights,  // optional
        float* evaluatedMaterialFPdfs,               // #2, optional
        float* evaluatedMaterialRPdfs,               // #2, optional
        RixBXLobeTraits* evaluatedMaterialLobes,     // #2, optional

        RixLight** sampledLights,  // #2, optional

        // inputs
        RtColorRGB const* pathThroughputs = nullptr,  // #1, optional

        RixPhotonGuiding const* photonGuide = nullptr,  // optional

        RixMWConnectionResult* mwConnectionResult = nullptr  // optional
        ) = 0;

    virtual void GenerateSamplesForRaySegments(
        int numLightSamples,
        // Pointer parameters that represent arrays are expected to be of size numPts
        RixRNG* rixRNG, float* maxDistances, RtVector3* samplePositions, float* selectionProbs,
        float* segmentMinT, float* segmentMaxT) = 0;

    virtual void EvaluateSamples(
        // Pointer parameters that represent arrays are expected to either be of size:
        // - numPts (#1) or
        // - numPts * numMaterialSamples (#2)
        // inputs
        int numMaterialSamples, RixRNG* rixRNG,
        RtVector3 const* directions,  // #2

        // input/output
        float* distances,  // #2

        // inputs
        float const* materialPdfs,  // #2
        RixBXLobeWeights const* materialWeights,
        RixBXLobeSampled const* materialLobeSampled,  // #2

        // outputs
        int* lightGroupIds,           // #2
        RixLPEToken* lightLpeTokens,  // #2
        RixBXLobeWeights* lightContributions,
        RtColorRGB* transmissions,    // #2, optional
        RtColorRGB* volumeEmissions,  // #2, optional
        float* directLightingPdfs,    // #2
        float* selectionProbs,        // #2
        RtNormal3* lightNormals,      // #2

        RixLight** evaluatedLights,  // #2, optional

        // inputs
        RtColorRGB const* pathThroughputs = nullptr  // #1, optional
        ) = 0;

    // Bidirectional
    virtual void EvaluateSamples(
        // Pointer parameters that represent arrays are expected to either be of size:
        // - numPts (#1) or
        // - numPts * numMaterialSamples (#2)
        // inputs
        int numMaterialSamples, RixRNG* rixRNG,
        RtVector3 const* directions,  // #2

        // input/output
        float* distances,  // #2

        // inputs
        float const* materialPdfs,  // #2
        RixBXLobeWeights const* materialWeights,
        RixBXLobeSampled const* materialLobeSampled,  // #2

        // outputs
        int* lightGroupIds,           // #2
        RixLPEToken* lightLpeTokens,  // #2
        RixBXLobeWeights* lightContributions,
        RtColorRGB* transmissions,    // #2, optional
        RtColorRGB* volumeEmissions,  // #2, optional
        float* directLightingPdfs,    // #2
        float* selectionProbs,        // #2

        float* emissionPositionPdfs,     // #2
        float* emissionDirectionPdfs,    // #2, FLT_MAX for infinite lights
        float* solidAngleToAreaFactors,  // #2, 1.0f for infinite lights

        RtNormal3* lightNormals,

        RixLight** evaluatedLights,  // #2, optional

        // inputs
        RtColorRGB const* pathThroughputs = nullptr,  // #1, optional

        RixPhotonGuiding const* photonGuide = nullptr  // optional
        ) = 0;

    // Global lighting / emission for "photons"
    virtual void BeginEmission(FixedSampleCountMode mode, int* fixedSampleCount = nullptr) = 0;

    virtual void GenerateEmission(
        // Pointer parameters that represent arrays are expected to either be of size:
        // - numPts (#1) or
        // - numPts * numSamples (#2)
        // inputs
        int numPts,
        int const* integratorContextIndices,  // #1
        int const* rayIds,                    // #2
        int numSamples, RixRNG* rixRNG,

        // outputs
        int* lightGroupIds,                    // #2
        RixLPEToken* lightLpeTokens,           // #2
        RixBXLobeWeights* lightContributions,  // #2

        RtColorRGB* transmissions,    // #2
        RtColorRGB* volumeEmissions,  // #2

        int* numShadingContexts,                     // #1
        RixShadingContext const*** shadingContexts,  // See method description
        RtPoint3* emissionPositions,                 // #2
        RtVector3* emissionNormals,                  // #2

        float* distances,                // #2
        float* directLightingPdfs,       // #2
        float* selectionProbs,           // #2
        float* emissionPositionsPdfs,    // #2
        RtVector3* emissionDirections,   // #2
        float* emissionCosines,          // #2
        float* emissionDirectionPdfs,    // #2
        float* solidAngleToAreaFactors,  // #2

        // inputs
        RixPhotonGuiding const* photonGuide = nullptr  // optional
        ) = 0;

    virtual void End() = 0;

    virtual void EndEmission() = 0;

    // All the following methods are callable after RixIntegrator::Begin

    virtual int GetNumLightGroups() = 0;
    virtual int GetLightGroup(RtUString const name) = 0;
    virtual RtUString GetLightGroupName(int i) = 0;

    virtual int GetTotalNumLights() = 0;
    virtual int GetTotalNumLightsWithFixedSamples() = 0;
    virtual int GetTotalFixedSamples() = 0;

    virtual void UpdateWithResults(int nSamples, RixBXLobeWeights const* contribution,
                                   RtColorRGB const* trans, float const* lPdfDirect,
                                   float const* lightSelectionProbs, float const* distances,
                                   RixBXLobeWeights const* evaluatedMaterialWeights,
                                   const RixLight* const* lights) = 0;

    virtual void IrradianceEstimate(uint32_t lightSetId, RtPoint3 const* points, int numPts,
                                    float* estimates, float* confidences) = 0;

    // (end)

protected:
    virtual ~RixLightingServices()
    {}
    RixShadingContext const* shadingCtx;
    RixBXEvaluateDomain domain;
};

#endif