RixLight.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 RixLight_h
#define RixLight_h

#include <cstddef>                      // for NULL
#include "RixBxdf.h"                    // for RixBXEvaluateDomain
#include "RixIES.h"                     // for RixIES
#include "RixShading.h"                 // for RixParameterList (ptr only), etc
#include "prmanapi.h"                   // for PRMANEXPORT
#include "RiTypesHelper.h"              // for RtColorRGB, RtPoint3, etc

class RixContext;
class RixLightFactory;
class RixPhotonGuiding;

class RixLightContext : public RixContext
{
public:
    // Retrieve the RixPhotonGuiding object given to the LightingServices
    RixPhotonGuiding const* GetPhotonGuiding() const
    {
        return m_pPhotonGuiding;
    }

    // Obtain the time associated with this query
    virtual float GetTime() const = 0;

    // Obtain a sample for the i'th element in this query context.
    // Only valid when in a sampling context. Will return 0,0 otherwise
    virtual RtFloat2 GetSample2D() const = 0;
    virtual void GetSample4D(RtFloat2& xy, RtFloat2& zw) const = 0;

    // BBox encompassing the world. Needed for environment lights to emit
    // photons when there is no photon guiding object available
    virtual void GetWorldBBox(RtBBox& worldBBox) const = 0;

    // Transform between named spaces
    virtual void GetFromToTransform(
        RtUString from, RtUString to,
        const float time,
        RtMatrix4x4& xform) const = 0;
    virtual void GetFromToTransform(
        RtUString from, RtUString to,
        RtMatrix4x4& xform) const = 0;
    // light space to current space
    virtual void GetLightToCurrentTransform(
        RtMatrix4x4& lightToCurrent) const = 0;
    // light space to current space
    virtual void GetLightToCurrentTransform(
        float const time,
        RtMatrix4x4& lightToCurrent) const = 0;
    // current space to light space
    virtual void GetCurrentToLightTransform(
        RtMatrix4x4& lightToCurrent) const = 0;
    // current space to light space
    virtual void GetCurrentToLightTransform(
        float const time,
        RtMatrix4x4& lightToCurrent) const = 0;

protected:
    // Hide the constructor of this class. It should never be constructed
    // nor copied directly.
    RixLightContext() {}
    ~RixLightContext() override {}

    RixPhotonGuiding const* m_pPhotonGuiding;
};

class RixLight
{
public:
    enum Type
    {
        k_RixLocal,
        k_RixInfinite
    };

    struct RixScatterPoint
    {
        RtPoint3 const scatterP; 
        RtNormal3 const scatterN; 
        RtVector3 const scatterV; 
        RixBXEvaluateDomain evalDomain;
    };

    struct RixSamplePoint 
    {
        int const patchIndex;
        RtFloat3 const uvw;
        RtFloat3 const direction;
        float const distance;

        RixSamplePoint (int const& inPatchIndex,
                        RtFloat3 const& inUvw,
                        RtFloat3 const& inDirection,
                        float const& inDistance)
            : patchIndex(inPatchIndex),
              uvw(inUvw),
              direction(inDirection),
              distance(inDistance)
        {
        }

    };

    RixLight(
        RixLightFactory const* lightFactory,
        Type type)
        : m_lightFactory(lightFactory),
          m_type(type)
    {
    }

    virtual ~RixLight()
    {
    }

    bool IsLocal() const { return m_type == k_RixLocal; }
    bool IsInfinite() const { return m_type == k_RixInfinite; }

    // Lights can be queried for general properties.  If a particular property
    // is unsupported, GetProperty() should return k_RixSCInvalidDetail.
    // Otherwise, return k_RixSCUniform or k_RixSCVarying according to the
    // detail of the result.
    enum LightProperty
    {
        k_LightGroupName,      // RtUString
        k_EnableShadows,       // int
        k_ShadowColor,         // RtColorRGB
        k_ShadowDistance,      // float
        k_ShadowFalloff,       // float
        k_ShadowFalloffGamma,  // float
        k_ShadowSubset,        // RtUString
        k_ShadowExcludeSubset, // RtUString
        k_TraceLightPaths,     // int
        k_ThinShadow,          // int
        k_VisibleInRefractionPath, // int
        k_FixedSampleCount,    // int
        k_RixIES,              // RixIES*
        k_Importance,          // float
        // Only flat, single-sided lights should return normals
        k_LightNormal,         // RtVector3
        k_ApproxFocus,         // float
        k_LightName,           // RtUString
        k_numLightProperties   
    };

    virtual RixSCDetail GetProperty(
        LightProperty prop,
        void const** result) const = 0;

    // This methods needs to be implemented for local lights.
    // It can return a single point (i.e. null extent) for infinite lights.
    virtual void GetBounds(int& nPoints, RtPoint3 const*& points) const = 0;

    virtual bool Intersect(
        bool isTransmissionRay,
        float const rayTime,
        RtPoint3 const& rayOrigin,
        RtVector3 const& rayDirection,
        // outputs
        float& hitDistance,
        float& u,
        float& v,
        float& w,
        RtPoint3& hitP,
        RtNormal3& hitNn) const = 0;

    virtual float GetIncidentRadianceEstimate(
        RtPoint3 const& P,
        RtMatrix4x4 const& lightToCurrent,
        RtMatrix4x4 const& currentToLight) const = 0;

    virtual float GetIncidentRadianceEstimate(
        RtPoint3 const& segmentOrigin,
        RtVector3 const& segmentDir,
        float segmentLen,
        RtMatrix4x4 const& lightToCurrent,
        RtMatrix4x4 const& currentToLight,
        RtFloat& minT,
        RtFloat& maxT) const = 0;

    virtual float GetPowerEstimate(RtMatrix4x4 const& xform) const = 0;

    struct GenerateSamplesResults
    {
    public:
        int& patchIndex; // only set by mesh lights
        RtFloat3& UVW;
        RtVector3& direction;
        float& distance;
        float& pdfDirect;
        bool const isBidirectional;
        float& pdfEmit;
        float& pdfEmitDirection;
        float& solidAngleToArea;
        RtColorRGB diffuseColor;
        RtColorRGB specularColor;
        RtNormal3& normal;
    };
    virtual void GenerateSamples(
        RixLightContext const& lCtx,
        RixScatterPoint const& scatter,
        GenerateSamplesResults& results) const = 0;

    struct EvaluateSamplesResults
    {
        float& pdfDirect;
        bool const isBidirectional;
        float& pdfEmit;
        float& pdfEmitDirection;
        float& solidAngleToArea;
        RtColorRGB diffuseColor;
        RtColorRGB specularColor;
        RtNormal3& normal;
    };
    virtual void EvaluateSamples(
        RixLightContext const& lCtx,
        RixSamplePoint const& sample,
        RixScatterPoint const& scatter,
        EvaluateSamplesResults& results) const = 0;

    struct GenerateEmissionResults
    {
        int& patchIndex; // only set by mesh lights
        RtFloat3& UVW;
        RtPoint3& position;
        RtNormal3& normal;
        RtVector3& direction;
        float& distance;
        float& pdfEmit; // area measure
        float& pdfEmitDirection;
    };
    virtual void GenerateEmission(
        RixLightContext const& lCtx,
        GenerateEmissionResults& results) const = 0;

    struct EvaluateEmissionForCameraResults
    {
        RtColorRGB cameraColor;
    };
    virtual void EvaluateEmissionForCamera(
        RixLightContext const& lCtx,
        RixSamplePoint const& sample,
        RixScatterPoint const& scatter,
        EvaluateEmissionForCameraResults& results) const = 0;

    // This method is called when a light has been edited. It is up to
    // the implementation of the light to determine if the edit can be
    // done in place, or if a new light needs to be created. If the edit
    // is done in place, the light returned should be "this".
    virtual RixLight* Edit(
        RixContext& ctx,
        RtUString const name,
        RixParameterList const* pList,
        void* instanceData) = 0;

protected:
    RixLightFactory const* m_lightFactory;

private:
    Type m_type;
};

class RixLightFactory : public RixShadingPlugin
{
public:
    int GetInterface() const override { return k_RixLightFactory; }

    virtual RixLight* CreateLight(
        RixContext& ctx,
        RtUString const name,
        RixParameterList const* pList,
        void* instanceData) = 0;

    virtual void DestroyLight(RixLight const* light) = 0;

protected:
    RixLightFactory() : RixShadingPlugin(k_RixShadingVersion) {}
    ~RixLightFactory() override {}
};

#define RIX_LIGHTFACTORYCREATE \
    extern "C" PRMANEXPORT RixLightFactory* CreateRixLightFactory(RtUString const hint)

#define RIX_LIGHTFACTORYDESTROY \
    extern "C" PRMANEXPORT void DestroyRixLightFactory(RixLightFactory* factory)

#endif