RixShadingParam.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 RixShadingParam_h
#define RixShadingParam_h

#include <cassert>                      // for assert
#include <cstddef>                      // for NULL
#include "RixPattern.h"                 // for RixPattern::OutputSpec, etc
#include "RixShading.h"                 // for RixSCDetail::k_RixSCUniform, etc
#include "RixShadingUtils.h"            // for k_ZeroF3, k_ZeroRGB
#include "RiTypesHelper.h"              // for RtFloat, int, RtColorRGB, etc

// RixShadingParam is a convenience class to encapsulate the type, detail and 
// value(s) associated with an individual POD parameter of a RixShadingPlugin.
// Client is expected to know/define the types of its paramters and can use
// this class to initialize and invoke EvalParam on them.
//
// Usage --
//
// InitEval: initialize a parameter by invoking Eval.  Optionally promote
//      to varying, to simplify coding logic.
//
// InitEmpty: initialize to invalid or valid-but-uniform-default state.
//
// InitReserve: reserve space for varying parameter but start as 
//      uniform in an attempt to express minimum computational requirements.
//      Usually called to initialize an output or target parameter.
//
// Bind: exposes our internal state as standard RixPattern output.
//
// GetValue: retrieves the value of the parameter at shading point i.
//
// To-do --
//      * smooth rough edges for detail promotion of RtFloat3 and friends.
//      * fill-in SetValue implementations if called for.
//      * transition PxrLM/lmParam.h to here.
//      * add support for array parameters.
//

// Bxdf clients: 
//  #define RIX_SHADING_PARAM_MEMCATEGORY RixShadingContext::k_BxdfMem
// Pattern clients:
//  #define RIX_SHADING_PARAM_MEMCATEGORY RixShadingContext::k_PatternMem

#ifndef RIX_SHADING_PARAM_MEMCATEGORY
#error RIX_SHADING_PARAM_MEMCATEGORY must be defined prior to inclusion
#endif

class RixShadingParam
{
public:
    RixShadingParam()
    {
        type = k_RixSCInvalidType;
        detail = k_RixSCInvalidDetail;
        data.f1 = NULL;
    }

    // publicly visible member variables ..... (we're struct-like)
    union
    {
        int *i1;
        float *f1;
        RtFloat3 *f3;
        RtColorRGB *rgb;
    } data;
    RixSCDetail detail;
    RixSCType type;

    bool IsValid() const { return detail != k_RixSCInvalidDetail; }

    // InitEval:
    //  initialize a parmeter by invoking Eval.  We don't promote
    //  to varying to preserve the detail of the upstream data.
    void InitEvalF(
        RixShadingContext const *sCtx,
        int paramId,
        float *dflt,
        bool promoteToVarying = false)
    {
        type = k_RixSCFloat;
        detail = sCtx->EvalParam(
            paramId, -1, const_cast<float const **>(&data.f1), dflt, promoteToVarying);
        // returned detail is that of real connection
        if(promoteToVarying)
            detail = k_RixSCVarying;
    }

    void InitEvalV(
        RixShadingContext const *sCtx,
        int paramId,
        RtFloat3 *dflt,
        bool promoteToVarying = false)
    {
        type = k_RixSCFloat3;
        detail = sCtx->EvalParam(
            paramId, -1, const_cast<RtFloat3 const **>(&data.f3), dflt, promoteToVarying);
        if(detail != k_RixSCVarying)
            detail = k_RixSCInvalidDetail;
    }

    void InitEvalC(
        RixShadingContext const *sCtx,
        int paramId,
        RtColorRGB *dflt,
        bool promoteToVarying = false)
    {
        type = k_RixSCColor;
        detail = sCtx->EvalParam(
            paramId, -1, const_cast<RtColorRGB const **>(&data.rgb), dflt, promoteToVarying);
        // returned detail is that of real connection
        if(promoteToVarying)
            detail = k_RixSCVarying;
    }

    void InitEvalI(
        RixShadingContext const *sCtx,
        int paramId,
        int *dflt,
        bool promoteToVarying = false)
    {
        type = k_RixSCInteger;
        detail = sCtx->EvalParam(
            paramId, -1, const_cast<int const **>(&data.i1), dflt, promoteToVarying);
        // returned detail is that of real connection
        if(promoteToVarying)
            detail = k_RixSCVarying;
    }


    // InitEmpty: initialize to invalid or valid-but-uniform-default state.
    void InitEmptyF(float const *dflt=NULL)
    {
        type = k_RixSCFloat;
        if(!dflt)
        {
            detail = k_RixSCInvalidDetail;
        }
        else
        {
            detail = k_RixSCUniform;
        }
        data.f1 = const_cast<float *>(dflt);
    }

    void InitEmptyI(int const *dflt=NULL)
    {
        type = k_RixSCInteger;
        if(!dflt)
        {
            detail = k_RixSCInvalidDetail;
        }
        else
        {
            detail = k_RixSCUniform;
        }
        data.i1 = const_cast<int *>(dflt);
    }

    void InitEmptyV(RtFloat3 *dflt=NULL)
    {
        type = k_RixSCFloat3;
        if(!dflt)
        {
            detail = k_RixSCInvalidDetail;
        }
        else
        {
            detail = k_RixSCUniform;
        }
        data.f3 = const_cast<RtFloat3 *>(dflt);
    }

    void InitEmptyC(RtColorRGB const *dflt=NULL)
    {
        type = k_RixSCColor;
        if(!dflt)
        {
            detail = k_RixSCInvalidDetail;
        }
        else
        {
            detail = k_RixSCUniform;
        }
        data.rgb = const_cast<RtColorRGB *>(dflt);
    }

    // InitReserve: reserve space for varying parameter but start as 
    //  uniform in an attempt to express minimum computational requirements.
    //  Usually called to initialize an output or target parameter.
    void InitReserveF(
        RixShadingContext::Allocator &pool,
        int numPts, 
        float dflt)
    {
        RixShadingContext::MemCategory memcat = RIX_SHADING_PARAM_MEMCATEGORY;
        assert(numPts != 0);
        type = k_RixSCFloat;
        detail = k_RixSCUniform;
        data.f1 = pool.AllocFor<RtFloat>(memcat, numPts);
        data.f1[0] = dflt;
    }

    void InitReserveI(
        RixShadingContext::Allocator &pool,
        int numPts,
        int dflt)
    {
        RixShadingContext::MemCategory memcat = RIX_SHADING_PARAM_MEMCATEGORY;
        assert(numPts != 0);
        type = k_RixSCInteger;
        detail = k_RixSCUniform;
        data.i1 = pool.AllocFor<int>(memcat, numPts);
        data.i1[0] = dflt;
    }

    void InitReserveC(
        RixShadingContext::Allocator &pool,
        int numPts,
        RtColorRGB const &dflt)
    {
        RixShadingContext::MemCategory memcat = RIX_SHADING_PARAM_MEMCATEGORY;
        assert(numPts != 0);
        type = k_RixSCColor;
        detail = k_RixSCUniform;
        data.rgb = pool.AllocFor<RtColorRGB>(memcat, numPts);
        data.rgb[0] = dflt;
    }

    void InitReserveV(RixShadingContext::Allocator &pool, int numPts)
    {
        RixShadingContext::MemCategory memcat = RIX_SHADING_PARAM_MEMCATEGORY;
        assert(numPts != 0);
        type = k_RixSCFloat3;
        detail = k_RixSCInvalidDetail;
        data.f3 = pool.AllocFor<RtFloat3>(memcat, numPts);
    }

    // GetValue:
    //  return value handling detail
    int GetValueI() const
    {
        assert(type == k_RixSCInteger && detail == k_RixSCUniform);
        return data.i1[0];
    }

    int GetValueI(int i) const
    {
        if(detail == k_RixSCUniform)
        {
            return data.i1[0];
        }
        else if(detail == k_RixSCVarying)
        {
            return data.i1[i];
        }
        else
        {
            return 0;
        }
    }

    float GetValueF() const
    {
        assert(type == k_RixSCFloat && detail == k_RixSCUniform);
        return data.f1[0];
    }

    float GetValueF(int i) const
    {
        if(detail == k_RixSCUniform)
        {
            return data.f1[0];
        }
        else if(detail == k_RixSCVarying)
        {
            return data.f1[i];
        }
        else
        {
            return 0.f;
        }
    }

    RtFloat3 const&GetValueV() const
    {
        assert(type == k_RixSCFloat3 && detail == k_RixSCUniform);
        return data.f3[0];
    }

    RtFloat3 const &GetValueV(int i) const
    {
        if(detail == k_RixSCUniform)
        {
            return data.f3[0];
        }
        else if(detail == k_RixSCVarying)
        {
            return data.f3[i];
        }
        else
        {
            return RixConstants::k_ZeroF3;
        }
    }

    RtColorRGB const &GetValueC() const
    {
        assert(type == k_RixSCColor && detail == k_RixSCUniform);
        return data.rgb[0];
    }

    RtColorRGB const &GetValueC(int i) const
    {
        if(detail == k_RixSCUniform)
        {
            return data.rgb[0];
        }
        else if(detail == k_RixSCVarying)
        {
            return data.rgb[i];
        }
        else
        {
            return RixConstants::k_ZeroRGB;
        }
    }

    // SetValue
    void SetValue(int i, float v)
    {
        if(detail == k_RixSCUniform)
        {
            if(i==0) { data.f1[0] = v; }
        }
        else if(detail == k_RixSCVarying)
        {
            data.f1[i] = v;
        }
    }

    // Bind: 
    //  exposes our internal state as standard RixPattern output
    void Bind(RixPattern::OutputSpec &o, int paramId)
    {
        o.paramId = paramId;
        o.detail = detail;
        o.value = (void const*) data.f1; // f1 works for all types
    }

    // PromoteToVarying: convert uniform to varying. NB: this assumes that 
    // data has been allocated for worse-case (via InitReserve). Tread carefully.
    void PromoteToVarying(int numPts)
    {
        if(this->detail != k_RixSCUniform)
        {
            return; // can't do it
        }
        else
        {
            // "smear" our uniform result into all elements.
            switch(type)
            {
            case k_RixSCFloat:
                this->detail = k_RixSCVarying;
                for(int i = 1; i < numPts; i++)
                {
                    data.f1[i] = data.f1[0];
                }
                break;
            case k_RixSCColor:
                this->detail = k_RixSCVarying;
                for(int i = 1; i < numPts; i++)
                {
                    data.rgb[i] = data.rgb[0];
                }
                break;
            case k_RixSCNormal:
            case k_RixSCPoint:
            case k_RixSCVector:
            case k_RixSCFloat3:
                for(int i = 1; i < numPts; i++)
                {
                    data.f3[i] = data.f3[0];
                }
                break;
            case k_RixSCInteger:
            default:
                assert(0); // unexpected
                break;
            }
        }
    }

}; // end of RixShadingParam definition

#endif