RixVolume.h

Go to the documentation of this file.

/*
# ------------------------------------------------------------------------------
#
# Copyright (c) 2022 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 RixVolume_h
#define RixVolume_h

#include <cstddef>          // for NULL
#include "RiTypesHelper.h"  // for RtPoint3, etc.
#include "RixIntegrator.h"  // for RtRayGeometry
#include "RixInterfaces.h"  // for RixInterface
#include "RixShading.h"     // for RixSCDetail, etc

class RixVolumeIrradianceEstimateContext
{
public:
    RixVolumeIrradianceEstimateContext()
    {}

    virtual ~RixVolumeIrradianceEstimateContext()
    {}
};

class RixVolumeAggregateIterator
{
public:
    virtual ~RixVolumeAggregateIterator()
    {}

    // Returns true if the iterator was able to advance the full
    // distance, otherwise returns false, signalling that some local
    // new maximum density information is now available.
    virtual bool Advance(float distance) = 0;

    // Returns the distance at the end of the current segment
    virtual float GetSegmentEnd() const = 0;

    virtual float GetTotalDistance() const = 0;

    virtual RtPoint3 GetOrigin() const = 0;

    virtual RtVector3 GetDirection() const = 0;

    virtual float GetOriginRadius() const = 0;

    virtual float GetRaySpread() const = 0;

    virtual float GetMaxDensity() const = 0;

    virtual float GetMinDensity() const = 0;

    virtual float GetMeanDensity() const = 0;

    virtual float GetVarDensity() const = 0;

    virtual RixVolumeAggregateIterator& operator=(const RixVolumeAggregateIterator& rhs) = 0;

    bool finished;

    float currentDistance;

protected:
    RixVolumeAggregateIterator() : finished(false), currentDistance(0.0f)
    {}
};

enum VolumeAggregateTransmittanceEstimator
{
    k_TransmittanceRatioTracking,
    k_TransmittanceRayMarching
};

enum VolumeAggregateProperty
{
    k_SkipMatteVolumes,       // Whether to skip volumes with Matte 1; bool input
    k_TransmittanceEstimator  // A hint on what type of method will be used for transmittance
                              // estimation; enum VolumeAggregateTransmittanceEstimator
};

class RixVolumeAggregate
{
public:
    virtual ~RixVolumeAggregate()
    {}

    virtual RixVolumeAggregateIterator* CreateIterator(int index) = 0;

    virtual void ComputeDensity(RixVolumeAggregateIterator** iterators, float* densities) = 0;

    virtual void ComputeEmission(RixVolumeAggregateIterator** iterators, RtColorRGB* emissions) = 0;

    virtual void CreateScatterContexts(RixVolumeAggregateIterator** iterators,
                                       int* numShadingContexts,
                                       RixShadingContext** shadingContexts) = 0;

    virtual void CreateScatterContexts(RixShadingContext const* parentContext,
                                       RixVolumeAggregateIterator** iterators,
                                       int* numShadingContexts,
                                       RixShadingContext** shadingContexts) = 0;

    virtual void ReleaseScatterContexts(int numShadingContexts, RixShadingContext** shadingContexts,
                                        RixBXLobeTraits const* exposeVol = NULL,
                                        int** memberships = NULL, int* numNewShadingContexts = NULL,
                                        RixShadingContext const** newShadingContexts = NULL) = 0;

    virtual void GenerateLightSamples(RixVolumeAggregateIterator** iterators, RixRNG* rng,
                                      RixLightingServices* lightingServices, float* maxDistances,
                                      RtPoint3* positions, bool* sampleFailed, float* segmentMinT, float* segmentMaxT) = 0;

    virtual void ComputeDensity(RixVolumeAggregateIterator** iterators, RtColorRGB* densities) = 0;

    virtual bool SetProperty(VolumeAggregateProperty, void const* in) = 0;

    virtual RixVolumeIrradianceEstimateContext* CreateIrradianceEstimateContext() = 0;

    virtual void AddToIrradianceQueries(RixVolumeAggregateIterator* iterator, int stepNum,
                                        RixVolumeIrradianceEstimateContext* queryContext) = 0;

    virtual void ServiceIrradianceQueries(RixVolumeIrradianceEstimateContext* queryContext,
                                          RixLightingServices* lightingServices, float* estimates,
                                          float* confidences) = 0;

    virtual void ComputeDensityAndEmission(RixVolumeAggregateIterator** iterators,
                                           RtColorRGB* densities, RtColorRGB* emissions) = 0;

    virtual void ComputeDensityAndMatte(RixVolumeAggregateIterator** iterators,
                                        RtColorRGB* densities, RtColorRGB* matteDensities) = 0;
};

class RixVolumeServices : public RixInterface
{
public:
    RixVolumeServices() : RixInterface(1), shadingCtx(NULL)
    {}

    // Begin for a Rix shading context (RIS usage)
    virtual void Begin(RixShadingContext const* sCtx) = 0;

    virtual void End() = 0;

    virtual int GetDensityRanges(const RtPoint3& pt0, const RtPoint3& pt1, float length,
                                 float maxDensity, float** dist, float** minDensities,
                                 float** maxDensities, float* minTrans, float* maxTrans) const = 0;

    virtual RixSCDetail EvalTemporalParam(int paramId, int arrayIndex, float const** result,
                                          float const* dflt) const = 0;

    virtual RixSCDetail EvalTemporalParam(int paramId, int arrayIndex, RtColorRGB const** result,
                                          RtColorRGB const* dflt) const = 0;

    virtual RixSCDetail EvalTemporalParam(int paramId, int arrayIndex, RtFloat3 const** result,
                                          RtFloat3 const* dflt) const = 0;

    virtual RixVolumeAggregate* GetAggregate(RtUString const name, int numRays,
                                             RtRayGeometry const* rays,
                                             RtUString const subset = US_NULL,
                                             RtUString const excludeSubset = US_NULL) const = 0;

    virtual bool HasAggregate(RtUString const name, bool& hasMatte) const = 0;

protected:
    ~RixVolumeServices() override
    {}
    RixShadingContext const* shadingCtx;
};

#endif