RixLighting.h

#ifndef RixLighting_h
#define RixLighting_h
/* $Revision: #2 $ $Date: 2015/07/06 $
# ------------------------------------------------------------------------------
#
# Copyright (c) 2013-2015 Pixar Animation Studios. All rights reserved.
#
# The information in this file (the "Software") is provided for the
# exclusive use of the software licensees of Pixar.  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 Animation Studios.
#
# 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.
#
# Pixar
# 1200 Park Ave
# Emeryville CA 94608
#
# ------------------------------------------------------------------------------
*/

#include "RixShading.h"
#include "RixBxdf.h"

/* RixLightingServices
 *
 * RIS usage: when RixLightingServices is obtained via RixIntegratorCtx
 *
 *   For Unidirectional integrators:
 *
 *      Begin(shadingCtx, ...)  // for direct lighting to RixShadingContext
 *      GenerateSamples()
 *      EvaluateSamples()
 *      End()
 *
 *   For Bidirectional integrators:
 *
 *      BeginEmission() // for "photon" generation
 *      GenerateEmission()
 *      End()
 *
 *      Begin(shadingCtx)  // for direct lighting to RixShadingContext
 *      GenerateSamples()
 *      EvaluateSamples()
 *      End()
 *
 *  Random number contexts:
 *
 *  When creating an RNG for use by GenerateSamples, either pass 
 *  the inherited (passed-in) RNG or make a new one with NewDomain(), 
 *  selecting ONE sample. The LightingServices implementation will derive 
 *  the appropriate number of samples from it internally.
 *
 *  Fixed sample count lights:
 *
 *  Individual lights may be configured to have a fixed sample count in which
 *  case their sample budget is fixed and not statistically chosen from the 
 *  global count.  In order to support this, k_RespectFixedSampleCount should 
 *  be passed to the Begin() method. In addition, caller must provide a
 *  handle into which we return the total required number of fixed samples.
 *
 *  Subsequent lighting services calls should be invoked with at least
 *  that number of samples in order for the fixed sample count requests 
 *  to be satisfied.  If the number of samples is smaller that the fixed
 *  sample requirement then we fall back to statistical (globally-budgeted) 
 *  sampling.  
 *
 *  In order for MIS weights to be correctly computed, the evaluation
 *  of material samples needs to be aware of whether fixed sample counts
 *  were satisfied or not.  This guarantee is provided to Begin().
 *  Passing k_IgnoreFixedSampleCount permits sample counts to be
 *  tailored down as the trace depth increases.
 *
 *  Note: passing k_RespectFixedSampleCount to the BeginEmission() method
 *  does not dictate sample counts but rather indicates that the count would
 *  have / will be respected for the GenerateSamples calls that will be made
 *  in subsequent Begin(RixShadingContext) / End() pairs.  The information
 *  returned by BeginEmission() indicates the fixed sampling requests to 
 *  expect for subsequent non global Begin()s, and is not an indication to 
 *  pass at least that many samples to GenerateEmission().
 *
 *  Bidirectional variants:
 *
 *  Two versions of GenerateSamples() and EvaluateSamples() are provided.
 *  One has additional outputs and will compute pdfs and other entities
 *  relevant for bidirectional transport.  To use them, the integrator must
 *  specify bidirectional requirements when it configures itself.
 *
 *  GenerateSamples can trigger evaluation of the Bxdf:
 *
 *  Optional arguments can be provided for GenerateSamples() which match
 *  those traditionally passed to RixBxdf::EvaluateSample().  When provided, 
 *  we take over the task of invoking the bxdf to evaluate the light samples
 *  and will pass back the same results that would have been handeled by a 
 *  loop over Bxdf::EvaluateSample().  By doing so the per-lightsample bxdf 
 *  weights can be known by lighting services. This information can be used
 *  to reduce the shadowing computations, therfore it is strongly advised 
 *  that integrators allow lighting services to perform the bxdf evaluation.
 *  This behavior is requested by passing non-NULL values for these parameters:
 *
 *  evaluatedMaterialWeights, evaluatedMaterialFPdf, 
 *  evaluatedMaterialRPdf (for bidirectional), 
 *  lobesEvaluated
 *
 *  The evaluatedMaterial arrays must have space for nsamples * npoints,  
 *  whilst the lobesWanted array should contain space for npoints values.
 *
 */

class RixLightingServices : public RixInterface
{
public:

    RixLightingServices() : 
        RixInterface(1), 
        shadingCtx(NULL), 
        domain(k_RixBXBoth) 
    {}

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

    enum Mode 
    {
        k_IgnoreFixedSampleCount  = 0,
        k_RespectFixedSampleCount = 1,
        k_ReducedFixedSampleCount = 2
    };

    class SampleMode {
    public:
        unsigned SaveSamples:1;    // Whether or not to save current samples for reuse
        unsigned RestoreSamples:1; // Whether or not to restore from saved samples
        unsigned RESERVED:30;
        SampleMode():
             SaveSamples(0),   // Don't save by default, most don't want to
             RestoreSamples(1) // Restore for compatibility with those that save
             {};
    };
    
    // Begin for a Rix shading context (RIS usage)
    virtual void Begin(RixShadingContext const *sCtx, 
                       RixRNG *rng, // arraylength: npoints
                       RixBXEvaluateDomain dom,
                       IntegratorIntent f,
                       Mode m, SampleMode sm,
                       RtInt *fixedSampleCount = NULL,
                       int depth = 0,
                       int parentIndirectCount = 1) = 0;

    // GenerateSamples for unidirectional integrators 
    virtual void GenerateSamples(RtInt numSamples,
                      RixRNG *rng, // size of internal array should be  npoints
                      // outputs
                      RtInt *lightGrpIds,
                      RtVector3 *toLight,
                      RtFloat *dist,
                      RixBXLobeWeights *contribution,
                      RtColorRGB *trans, // pass NULL if shadowing not required
                      RtFloat *lightPdfIllum,
                              
                      // the following outputs may be NULL if evaluation
                      // against the bxdf is not required, sizes are
                      // expected to be either npoints (#1) or 
                      // npoints * numSamples (#2)
                      RixBXLobeTraits  *lobesWanted,  // #1
                      RixBXLobeWeights *evaluatedMaterialWeights, // #2
                      RtFloat          *evaluatedMaterialFPdf,  // #2
                      RtFloat          *evaluatedMaterialRPdf,  // #2
                      RixBXLobeTraits  *lobesEvaluated,         // #2
                      // optional input throughput will be used to
                      // help cull shadow rays based on path throughput
                      RtColorRGB        *throughput = NULL        // #1
                      ) = 0;

    // GenerateSamples for bidirectional integrators
    virtual void GenerateSamples(RtInt numSamples,
                      RixRNG *rng, // size of internal array should be  npoints
                      // outputs
                      RtInt *lightGrpIds,
                      RtVector3 *toLight,
                      RtFloat *dist,
                      RixBXLobeWeights *contribution,
                      RtColorRGB *trans, // pass NULL if shadowing not required
                      RtFloat *lightPdfIllum,
                      RtFloat *lightPdfEmit,
                      RtFloat *dirPdf,          // FLT_MAX for infinite/distantlight/env
                      RtFloat *solidAngToArea,  // 1.0f for infinite/distant/env

                      // the following outputs may be NULL if evaluation
                      // against the bxdf is not required, sizes are
                      // expected to be either npoints (#1) or 
                      // npoints * numSamples (#2)
                      RixBXLobeTraits  *lobesWanted,  // #1
                      RixBXLobeWeights *evaluatedMaterialWeights, // #2
                      RtFloat          *evaluatedMaterialFPdf,  // #2
                      RtFloat          *evaluatedMaterialRPdf,  // #2
                      RixBXLobeTraits  *lobesEvaluated,         // #2
                      // optional input throughput will be used to
                      // help cull shadow rays based on path throughput
                      RtColorRGB        *throughput = NULL,       // #1

                      // Following parameters are currently unused and
                      // reserved for possible future use
                      RtFloat * volForwardPdf = NULL,
                      RtFloat * volReversePdf = NULL,
                      RtFloat * volCrossPdf = NULL
                      ) = 0;

    // EvaluateSamples for unidirectional integrators
    virtual void EvaluateSamples(RtInt numSamples,
                      RixRNG *rng, // size of internal array should be npoints
                      RtVector3 *toLight,
                      RtFloat *dist,    // (modified - input and output)
                      RtFloat *matPdf,
                      RixBXLobeWeights *weights,
                      RixBXLobeSampled *lobeSampled,
                      // outputs
                      RtInt *lightGrpIds,
                      RixBXLobeWeights *contribution,
                      RtColorRGB *trans,// pass NULL if shadowing not required
                      RtFloat *lightPdfIllum,
                      // optional input throughput will be used to
                      // help cull shadow rays based on path throughput
                      RtColorRGB        *throughput = NULL         // #1
                      ) = 0;

    // Bidirectional
    virtual void EvaluateSamples(RtInt numSamples,
                      RixRNG *rng, // size of internal array should be npoints        
                      RtVector3 *toLight,
                      RtFloat *dist,    // (modified - input and output)
                      RtFloat *matPdf,
                      RixBXLobeWeights *weights,
                      RixBXLobeSampled *lobeSampled,
                      // outputs
                      RtInt *lightGrpIds,
                      RixBXLobeWeights *contribution,
                      RtColorRGB *trans, // pass  NULL if shadowing not required
                      RtFloat *lightPdfIllum,
                      RtFloat *lightPdfEmit,
                      RtFloat *dirPdf,          // FLT_MAX for infinite/distantlight/env
                      RtFloat *solidAngToArea,  // 1.0f for infinite/distantlight/env
                      // optional input throughput will be used to
                      // help cull shadow rays based on path throughput
                      RtColorRGB        *throughput = NULL,        // #1

                      // Following parameters are currently unused and
                      // reserved for possible future use
                      RtFloat * volForwardPdf = NULL,
                      RtFloat * volReversePdf = NULL,
                      RtFloat * volCrossPdf = NULL
                      ) = 0;

    // Global lighting / emission for "photons"
    virtual void BeginEmission(Mode m, RtInt *fixedSampleCount = NULL) = 0;

    // GenerateEmission returns the RxiShadingContexts hit by each sample
    // separately, such that sample 0 is returned into shadeCtxs[0], sample
    // 1 into shadeCtxs[1] and so on.  each index of shadeCtxs must point to
    // a RixShadingContext** which is of length numPts.
    //
    // Similarly the caller must pass an array of nsamples size to numGrps.
    // numGrps[0] describes the count of unique shading contexts in shadeCtxs[0]
    // and numGrps[1] the count of shadeCtxs[1] and so on.
    //
    // Caller is responsible for freeing ShadingContexts produced by 
    // GenerateEmission via: RixIntegratorContext::ReleaseShadingContexts.
    
    virtual void GenerateEmission(RtInt numPts,
                              RtInt *integratorCtxIds,
                              RtInt *rayIds,
                              RtInt numSamples,
                              RixRNG *rng, // length should be numPts
                              // outputs
                              RtInt *lightGrpIds,
                              RixBXLobeWeights *contribution,
                              RtColorRGB *trans,
                              RtInt *numGrps, 
                              RixShadingContext const***shadeCtxs,
                              RtPoint3 *lightPos,
                              RtVector3 *lightNorm,
                              RtFloat *dist,
                              RtFloat *lightPdfIllum,
                              RtFloat *lightPdfEmit,
                              RtVector3 *dir,
                              RtFloat *fDir,
                              RtFloat *dirPdf,          // FLT_MAX for infinite/distantlight/env
                              RtFloat *solidAngToArea,  // 1.0f for infinite/distantlight/env
                              RtInt   *directIllumDisabled = NULL,   
                                // values of 1 in this array indicate
                                // the light was disabled via illuminate
                                // or subsets for direct illumination
                                // but may still want to be bounced

                              // Following parameters are currently
                              // unused and reserved for possible
                              // future use
                              RtFloat * volForwardPdf = NULL,
                              RtFloat * volReversePdf = NULL,
                              RtFloat * volCrossPdf = NULL
                              ) = 0;

    virtual void End() = 0;

    // All callable _after_ integrator::Begin
    
    virtual int GetNumLightGroups() = 0;
    virtual int GetLightGroup(const char *name) = 0;
    virtual const char *GetLightGroupName(int i) = 0;
    virtual int GetTotalFixedSamples() = 0;

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

#endif