RixRNG.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 RixRNG_h
#define RixRNG_h

#include <cassert>                         // for assert
#include "prmanapi.h" // IWYU pragma: keep // for PRMAN_INLINE
#include "RiTypesHelper.h"                 // for RtFloat2, RtFloat3


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

class RixRNG
{
public:

    // A bit pattern used to create new RixRNG domains.  An empty scoped enum
    // is used to make this distinct from unsigned int for type-safety.
    // Use an explicit cast to create a value of this type, e.g.:
    //      static_cast<RixRNG::Scramble>(0xfa1afe1)
    enum class Scramble : unsigned {};

    struct SampleCtx
    {
        unsigned patternid;   // bit pattern used to select a sample sequence
        unsigned patternidEmit;  // bit pattern used to select a sample sequence for photon emission
        unsigned sampleid;    // sample number

        SampleCtx NewDomain(Scramble scramble) const
        {
            const unsigned oldPatternid = patternid;
            SampleCtx newd = *this;
            newd.patternid =
                RixRNGUtils::shufflePattern(oldPatternid + static_cast<unsigned>(scramble));
            newd.patternid = (oldPatternid & 0xffff0000) | (newd.patternid & 0xffff);  // keep top 16 bits
            // Handle the rare case (1 out of 65,536) that the new patternid is the same as the old
            if (newd.patternid == oldPatternid)
            {
                newd.patternid = (oldPatternid & 0xffff0000) | ((newd.patternid + 19) & 0xffff);
            }
            assert(newd.patternid != oldPatternid);
            return newd;
        }

        SampleCtx NewDomainDistrib(Scramble scramble, unsigned newsampleid) const
        {
            const unsigned oldPatternid = patternid;
            SampleCtx newd;
            newd.patternid =
                RixRNGUtils::shufflePattern(oldPatternid + static_cast<unsigned>(scramble), sampleid);
            newd.patternid = (oldPatternid & 0xffff0000) | (newd.patternid & 0xffff);  // keep top 16 bits
            // Handle the rare case (1 out of 65,536) that the new patternid is the same as the old
            if (newd.patternid == oldPatternid)
            {
                newd.patternid = (oldPatternid & 0xffff0000) | ((newd.patternid + 19) & 0xffff);
            }
            newd.sampleid = newsampleid;
            return newd;
        }

        SampleCtx NewDomainSplit(Scramble scramble, unsigned newnumsamples) const
        {
            const unsigned oldPatternid = patternid;
            SampleCtx newd = *this;
            newd.patternid =
                RixRNGUtils::shufflePattern(oldPatternid + static_cast<unsigned>(scramble));
            newd.patternid = (oldPatternid & 0xffff0000) | (newd.patternid & 0xffff);  // keep top 16 bits
            // Handle the rare case (1 out of 65,536) that the new patternid is the same as the old
            if (newd.patternid == oldPatternid)
            {
                newd.patternid = (oldPatternid & 0xffff0000) | ((newd.patternid + 19) & 0xffff);
            }
            newd.sampleid *= newnumsamples;
            return newd;
        }
    }; // end of struct SampleCtx

    // Overrideable implementation
    class Generator
    {
    public:
        Generator() {}
        virtual ~Generator() {}

        // Generator functions to draw a single sample from a sequence.
        // The parameter 'i' is for sample generators that need the shading context index
        // to keep track of internal data.  (The default PMJ Generator does not need it.)
        virtual float Sample1D(const SampleCtx& rCtx, unsigned i) const = 0;
        virtual RtFloat2 Sample2D(const SampleCtx& rCtx, unsigned i) const = 0;
        virtual RtFloat2 ScrambledSample2D(const SampleCtx& rCtx, unsigned i) const = 0;
        virtual RtFloat3 Sample3D(const SampleCtx& rCtx, unsigned i) const = 0;

        // Generator functions to draw multiple samples, each from a different sequence
        virtual void MultiSample1D(
            unsigned n,
            const SampleCtx* rCtx,
            float* xis) const = 0;
        virtual void MultiSample2D(
            unsigned n,
            const SampleCtx* rCtx,
            RtFloat2* xis) const = 0;
        virtual void MultiScrambledSample2D(
            unsigned n,
            const SampleCtx* rCtx,
            RtFloat2* xis) const = 0;
        virtual void MultiSample3D(
            unsigned n,
            const SampleCtx* rCtx,
            RtFloat3* xis) const = 0;
    };

// Default implementation
#include "RixRNGProgressive.h" // IWYU pragma: export

public:

    // RixRNG constructors

    RixRNG(Generator const *imp, unsigned scaSize = 0)
        : numPts(scaSize), sampleCtxArray(0), impl(imp)
    {
    }

    // Construct a new RixRNG, with specified number of points and SampleCtx
    // memory block.
    RixRNG(Generator const *imp, unsigned scaSize, SampleCtx* sca)
        : numPts(scaSize), sampleCtxArray(sca), impl(imp)
    {
    }

    // Construct a RixRNG based on another, but with a new number of points
    // and SampleCtx memory block.
    RixRNG(RixRNG const* parent, unsigned scaSize, SampleCtx* sca)
        : numPts(scaSize), sampleCtxArray(sca), impl(parent->impl)
    {
    }

    // Construct a RixRNG based on another, but with a new SampleCtx memory block.
    // (Same as constructor above, except parameter order.)
    RixRNG(RixRNG const* parent, SampleCtx* sca, unsigned scaSize)
        : numPts(scaSize), sampleCtxArray(sca), impl(parent->impl)
    {
    }

    // Construct a RixRNG based on another, but with a new SampleCtx memory
    // block. Derivation of the new SampleCtx domain uses NewDomains(), ie.
    // no trajectory splitting and no independent distribution.
    // WARNING: if your parent RNG is of a different size, do not use
    //          this routine.
    RixRNG(RixRNG const* parent, SampleCtx* sca, unsigned scaSize, Scramble scramble)
        : numPts(scaSize), sampleCtxArray(sca), impl(parent->impl)
    {
        // Ensure that the new RixRNG isn't larger than the parent.
        // If the new one is larger we'll read uninitialized memory in NewDomains().
        assert(scaSize <= parent->numPts);

        parent->NewDomains(scramble, this);
    }

    // Construct a RixRNG based on another, but with a new SampleCtx memory
    // block. Derivation of the new SampleCtx domain uses trajectory splitting
    // by calling NewDomainsSplit().  If nsamps=1 then there is no
    // actual splitting; in that case, it's the same as calling the function
    // above.
    // WARNING: if your parent RNG is of a different size, do not use
    //          this routine.
    RixRNG(RixRNG const* parent, SampleCtx* sca, unsigned scaSize, Scramble scramble, unsigned nsamps)
        : numPts(scaSize), sampleCtxArray(sca), impl(parent->impl)
    {
        // Ensure that the new RixRNG isn't larger than the parent.
        // If the new one is larger we'll read uninitialized memory in NewDomainsSplit().
        assert(scaSize <= parent->numPts);

        parent->NewDomainsSplit(scramble, nsamps, this);
    }

    // Construct a RixRNG based on another, but with a new SampleCtx memory
    // block. Derivation of the new SampleCtx domain generates a new distribution
    // if doDistrib = true, and ordinary path tracing if false.
    // WARNING: if your parent RNG is of a different size, do not use
    //          this routine.
    RixRNG(
        RixRNG const* parent,
        SampleCtx* sca,   // sample context array
        unsigned scaSize,   // size of sample context array
        Scramble scramble,
        unsigned sampleid,   // only used if doDistrib is true
        bool doDistrib)
        : numPts(scaSize), sampleCtxArray(sca), impl(parent->impl)
    {
        // Ensure that the new RixRNG isn't larger than the parent.
        // If the new one is larger we'll read uninitialized memory in NewDomains().
        assert(scaSize <= parent->numPts);

        if (doDistrib) {
            parent->NewDomainsDistrib(scramble, sampleid, this);
        } else {
            parent->NewDomains(scramble, this);
        }
    }

    // Construct a single-element RNG based on another, need new SampleCtx
    // memory and an offset into parent's sample array.
    RixRNG GetSlice(SampleCtx* sca, unsigned index) const
    {
        RixRNG result(this->impl);
        result.numPts            = 1;
        result.sampleCtxArray    = sca;
        result.sampleCtxArray[0] = this->sampleCtxArray[index];
        return result;
    }

    virtual ~RixRNG() {}

    unsigned numPts;   // number of elements in sampleCtxArray[]
    SampleCtx* sampleCtxArray;   // sample contexts: pattern ids and sample ids
    Generator const *impl;   // implementation of sample generator

    SampleCtx& GetSampleCtx(unsigned i) { return sampleCtxArray[i]; }

    // The 'Generate' family of interfaces assumes caller will generate
    // a sequence of samples based on a SampleCtx obtained from the
    // renderer.  Generate functions increment the sampleid; Draw functions
    // do not.

    // Generate a sample from the sequence and increment sample id
    float GenerateSample1D(unsigned i) const
    {
        float f = impl->Sample1D(sampleCtxArray[i], i);   // second param is ignored for PMJ
        sampleCtxArray[i].sampleid++;
        return f;
    }

    RtFloat2 GenerateSample2D(unsigned i) const
    {
        RtFloat2 f2 = impl->Sample2D(sampleCtxArray[i], i);   // second param is ignored for PMJ
        sampleCtxArray[i].sampleid++;
        return f2;
    }

    RtFloat2 GenerateScrambledSample2D(unsigned i) const
    {
        RtFloat2 f2 = impl->ScrambledSample2D(sampleCtxArray[i], i);   // second param is ignored for PMJ
        sampleCtxArray[i].sampleid++;
        return f2;
    }

    RtFloat3 GenerateSample3D(unsigned i) const
    {
        RtFloat3 f3 = impl->Sample3D(sampleCtxArray[i], i);   // second param is ignored for PMJ
        sampleCtxArray[i].sampleid++;
        return f3;
    }

    // Generate a sample from the sequence and increment sample id
    float GenerateSample1D(SampleCtx& c, unsigned i) const
    {
        float f = impl->Sample1D(c, i);   // second param is ignored for PMJ
        c.sampleid++;
        return f;
    }

    RtFloat2 GenerateSample2D(SampleCtx& c, unsigned i) const
    {
        RtFloat2 f2 = impl->Sample2D(c, i);   // second param is ignored for PMJ
        c.sampleid++;
        return f2;
    }

    RtFloat2 GenerateScrambledSample2D(SampleCtx& c, unsigned i) const
    {
        RtFloat2 f2 = impl->ScrambledSample2D(c, i);   // second param is ignored for PMJ
        c.sampleid++;
        return f2;
    }

    RtFloat3 GenerateSample3D(SampleCtx& c, unsigned i) const
    {
        RtFloat3 f3 = impl->Sample3D(c, i);   // second param is ignored for PMJ
        c.sampleid++;
        return f3;
    }

    // Generate numPts samples (each from a different sequence) and increment sample ids
    void GenerateSamples1D(float* xis) const
    {
        impl->MultiSample1D(numPts, sampleCtxArray, xis);
        IncrementSampleIds();
    }

    void GenerateSamples2D(RtFloat2* xis) const
    {
        impl->MultiSample2D(numPts, sampleCtxArray, xis);
        IncrementSampleIds();
    }

    void GenerateScrambledSamples2D(RtFloat2* xis) const
    {
        impl->MultiScrambledSample2D(numPts, sampleCtxArray, xis);
        IncrementSampleIds();
    }

    void GenerateSamples3D(RtFloat3* xis) const
    {
        impl->MultiSample3D(numPts, sampleCtxArray, xis);
        IncrementSampleIds();
    }

    // Draw a sample from the sequence
    float DrawSample1D(unsigned i) const
    {
        return impl->Sample1D(sampleCtxArray[i], i);   // second param is ignored for PMJ
    }

    RtFloat2 DrawSample2D(unsigned i) const
    {
        return impl->Sample2D(sampleCtxArray[i], i);   // second param is ignored for PMJ
    }

    RtFloat2 DrawScrambledSample2D(unsigned i) const
    {
        return impl->ScrambledSample2D(sampleCtxArray[i], i);   // second param is ignored for PMJ
    }

    RtFloat3 DrawSample3D(unsigned i) const
    {
        return impl->Sample3D(sampleCtxArray[i], i);   // second param is ignored for PMJ
    }

    // Draw a sample from the sequence
    float DrawSample1D(const SampleCtx& c, unsigned i) const
    {
        return impl->Sample1D(c, i);   // second param is ignored for PMJ
    }

    RtFloat2 DrawSample2D(const SampleCtx& c, unsigned i) const
    {
        return impl->Sample2D(c, i);   // second param is ignored for PMJ
    }

    RtFloat2 DrawScrambledSample2D(const SampleCtx& c, unsigned i) const
    {
        return impl->ScrambledSample2D(c, i);   // second param is ignored for PMJ
    }

    RtFloat3 DrawSample3D(const SampleCtx& c, unsigned i) const
    {
        return impl->Sample3D(c, i);   // second param is ignored for PMJ
    }

    // Draw numPts samples (each from a different sequence)
    void DrawSamples1D(float* xis) const
    {
        impl->MultiSample1D(numPts, sampleCtxArray, xis);
    }

    void DrawSamples2D(RtFloat2* xis) const
    {
        impl->MultiSample2D(numPts, sampleCtxArray, xis);
    }

    void DrawSamples3D(RtFloat3* xis) const
    {
        impl->MultiSample3D(numPts, sampleCtxArray, xis);
    }

    // Increment all sampleids
    void IncrementSampleIds() const
    {
        for (unsigned i = 0; i < numPts; ++i)
            sampleCtxArray[i].sampleid++;
    }

    // Setting up new random domains
    SampleCtx NewDomain(unsigned i, Scramble scramble) const
    {
        return sampleCtxArray[i].NewDomain(scramble);
    }

    SampleCtx NewDomainDistrib(unsigned i, Scramble scramble,
                               unsigned newsampleid) const
    {
        return sampleCtxArray[i].NewDomainDistrib(scramble, newsampleid);
    }

    SampleCtx NewDomainSplit(unsigned i, Scramble scramble,
                             unsigned newnumsamples) const
    {
        return sampleCtxArray[i].NewDomainSplit(scramble, newnumsamples);
    }

    // Multi-point versions of NewDomain() functions.
    // Setting up new random domains for all sampleCtxs.
    // These generate new patternids in-place.
    void NewDomains(Scramble scramble) const
    {
        for (unsigned i = 0; i < numPts; i++) {
            sampleCtxArray[i] = sampleCtxArray[i].NewDomain(scramble);
        }
    }

    void NewDomainsDistrib(Scramble scramble, unsigned newsampleid) const
    {
        for (unsigned i = 0; i < numPts; i++) {
            sampleCtxArray[i] =
                sampleCtxArray[i].NewDomainDistrib(scramble, newsampleid);
        }
    }

    void NewDomainsSplit(Scramble scramble, unsigned newnumsamples) const
    {
        for (unsigned i = 0; i < numPts; i++) {
            sampleCtxArray[i] =
                sampleCtxArray[i].NewDomainSplit(scramble, newnumsamples);
        }
    }

    // More multi-point versions of NewDomain() functions.
    // Setting up new random domains for all sampleCtxs.
    // (To facilitate future more efficient simd implementations.)
    // These ones require the new RixRNG to have a size smaller or equal to the
    // current ("parent") one.
    void NewDomains(Scramble scramble, RixRNG *newRng) const
    {
        unsigned minNumPts = newRng->numPts < numPts ? newRng->numPts : numPts;
        for (unsigned i = 0; i < minNumPts; i++) {
            newRng->sampleCtxArray[i] = sampleCtxArray[i].NewDomain(scramble);
        }
        newRng->numPts = minNumPts;
    }

    void NewDomainsDistrib(Scramble scramble, unsigned newsampleid,
                           RixRNG *newRng) const
    {
        unsigned minNumPts = newRng->numPts < numPts ? newRng->numPts : numPts;
        for (unsigned i = 0; i < minNumPts; i++) {
            newRng->sampleCtxArray[i] =
                sampleCtxArray[i].NewDomainDistrib(scramble, newsampleid);
        }
        newRng->numPts = minNumPts;
    }

    void NewDomainsSplit(Scramble scramble, unsigned newnumsamples,
                         RixRNG *newRng) const
    {
        unsigned minNumPts = newRng->numPts < numPts ? newRng->numPts : numPts;
        for (unsigned i = 0; i < minNumPts; i++) {
            newRng->sampleCtxArray[i] =
                sampleCtxArray[i].NewDomainSplit(scramble, newnumsamples);
        }
        newRng->numPts = minNumPts;
    }

};

#endif