RixInterfaces.h

#ifndef RixInterfaces_h
#define RixInterfaces_h
/* $Revision: #6 $  $Date: 2016/06/14 $ */
/*
# ------------------------------------------------------------------------------
#
# Copyright (c) 2006-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 "ri.h"
#include <stddef.h>     // for size_t


enum RixInterfaceId 
{
    k_RixThreadUtils = 0,  
    k_RixMessages,         
    k_RixStatsV1,          
    k_RixGlobalData,       
    k_RixThreadData,       
    k_RixLocalData,        
    k_RixGlobalTokenData,  
    k_RixSubdivEvalV1,     
    k_RixSessionData = 8,  
    k_RixXcpt,             
    k_RixRIB,              
    k_RixDeepTexture,      
    k_RixSubdivisionSurfaceEvaluation, 
    k_RixRIBParser,        
    k_RixTexture2d,        
    k_RixStats,            
    k_RixTimer,            
    k_RixAreaShadow,       
    k_RixRNGDeprecated,    
    k_RixMemoryPool,       
    k_RixRenderState,      
    k_RixSloInfo,          
    k_RixRiCtl,            
    k_RixSymbolResolver,   
    k_RixLightingServices, 
    k_RixGeoDebugger,      
    k_RixTexture,          
    k_RixShadeFunctions,   
    k_RixTransform,        
    k_RixResourceResolver, 
    k_RixLPEInfo,          
    k_RixCustomLPE,        
};

class RixInterface 
{
public:
    virtual int GetVersion() const { return m_version; }

protected:
    int m_version;

    RixInterface(int version) : m_version(version) { }

    virtual ~RixInterface() { }
};

class RixContext 
{
public:
    virtual RixInterface* GetRixInterface(RixInterfaceId id) const = 0;

    virtual ~RixContext() { }
};


class RixXcpt : public RixInterface
{
public:
    class XcptHandler 
    {
    public:
        virtual void HandleXcpt(int code, int severity, const char *msg) = 0;
        virtual void HandleExitRequest(int code) = 0;

    protected:
        virtual ~XcptHandler() {}
    };

    virtual void Register(XcptHandler *) = 0;

    virtual void Unregister(XcptHandler *) = 0;

protected:
    RixXcpt() : RixInterface(1) { }
};

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

    virtual void Lock() = 0;
    
    virtual void Unlock() = 0;
};


class RixThreadUtils : public RixInterface 
{
public:
    virtual RixMutex* NewMutex() const = 0;

protected:
    RixThreadUtils() : RixInterface(1) { }
};


class RixMessages : public RixInterface 
{
public:
    virtual void Error(const char* format, ...) = 0;

    virtual void ErrorAlways(const char* format, ...) = 0;

    virtual void Warning(const char* format, ...) = 0;

    virtual void WarningAlways(const char* format, ...) = 0;

    virtual void Info(const char* format, ...) = 0;

    virtual void InfoAlways(const char* format, ...) = 0;

protected:
    RixMessages() : RixInterface(1) { }
};

class RixTimer : public RixInterface
{
public:
    virtual RtUInt64 SampleTime() = 0;
    virtual float ConvertIntervalToSeconds(RtUInt64 interval) = 0;

protected:
    RixTimer() : RixInterface(1) {}
};

class RixXmlFile 
{
public:
    virtual void WriteXml(const char* format, ...) = 0;

    virtual void WriteText(const char* format, ...) = 0;

    virtual ~RixXmlFile() { }

    // Helper functions for writings stats.
    void WriteStat(char const *name, char const *desc, int value)
    {
        WriteXml("<int name=\"%s\"", name);
        if (desc) WriteXml(" description=\"%s\"", desc);
        WriteXml("> %i </int>\n", value);
    }

    void WriteStat(char const *name, char const *desc, RtUInt64 value)
    {
        WriteXml("<int name=\"%s\"", name);
        if (desc) WriteXml(" description=\"%s\"", desc);
        WriteXml("> %llu </int>\n", value);
    }

    void WriteStat(char const *name, char const *desc, float value)
    {
        WriteXml("<float name=\"%s\"", name);
        if (desc) WriteXml(" description=\"%s\"", desc);
        WriteXml("> %f </float>\n", value);
    }

    void WriteStat(char const *name, char const *desc, char const *value)
    {
        WriteXml("<string name=\"%s\"", name);
        if (desc) WriteXml(" description=\"%s\"", desc);
        WriteXml("> %s </string>\n", value);
    }

    void WriteTime(char const *name, char const *desc, float time)
    {
        WriteXml("<timer name=\"%s\"", name);
        if (desc) WriteXml(" description=\"%s\"", desc);
        WriteXml("><elapsed>%f</elapsed></timer>\n", time);
    }
};

class RixStats : public RixInterface 
{
public:
    virtual void AddTimerStat(float* seconds, const char* name,
                              const char* description) = 0;

    class SimpleStat
    {
    public:
        enum Fmt
        {
            k_fmtAsTimeInterval,
            k_fmtAsMemory,
            k_fmtAsUInt,
            k_fmtAsInt,
            k_fmtAsFloat
        };
        virtual ~SimpleStat() {}
        virtual void Reset() = 0;
        virtual const char *GetName() = 0;
        virtual const char *GetDescription() = 0;
        virtual void GetResults(RtUInt64 *result, Fmt *fmt) = 0;
    };
    virtual int AddSimpleStat(SimpleStat *)=0;

    virtual void AddMemoryStat(size_t* bytes, const char* name, 
                               const char* description) = 0;

    typedef void (*Reporter)(class RixXmlFile* file);
    typedef void (*ReporterCtx)(void *ctx, class RixXmlFile *);

    virtual void AddReporter(Reporter func) = 0;
    virtual void AddReporterCtx(ReporterCtx func, void *ctx) = 0;

    virtual void AddFileLogStat(const char *filename, const char *path) = 0;

protected:
    RixStats() : RixInterface(3) { }
};

typedef void (*RixCleanupFunc)(RixContext* context, void* data);

class RixStorage : public RixInterface 
{
public:
    virtual void* Get(const char* key) = 0;

    virtual void Set(const char* key, void* data, 
                     RixCleanupFunc cleanup = NULL) = 0;

    virtual void Clear(const char* key) = 0;

    virtual void Lock() = 0;

    virtual void Unlock() = 0;

protected:
    RixStorage() : RixInterface(1) { }
};


class RixTokenStorage : public RixInterface 
{
public:
    virtual const char *GetToken(const char *input) = 0;

protected:
    RixTokenStorage() : RixInterface(1) { }
};

class RixTexture2d : public RixInterface
{
public:
    enum resultType
    {
        k_floatResult,
        k_integerResult,
        k_stringResult,
        k_colorResult,
        k_normalResult,
        k_vectorResult,
        k_pointResult,
        k_hpointResult,
        k_mpointResult,
        k_matrixResult
    };

    virtual int TextureInfo(const RtString filename, const char *query,
                            void *result, int resultlen, 
                            resultType *resulttype, int *resultcount,
                            int faceindex = -1)=0;

    virtual int TexturePoints1V(const RtString filename, RtInt nPoints,
                                RtInt firstchannel, RtInt nchannels, 
                                RtFloat *s, RtFloat *t, RtFloat *result, 
                                RtInt n, RtToken tokens[], RtPointer parms[])=0;

    virtual int TexturePoints4V(const RtString filename, RtInt nPoints,
                                RtInt firstchannel, RtInt nchannels, 
                                RtFloat *s0, RtFloat *t0, 
                                RtFloat *s1, RtFloat *t1,
                                RtFloat *s2, RtFloat *t2, 
                                RtFloat *s3, RtFloat *t3, 
                                RtFloat *result, RtInt n, RtToken tokens[],
                                RtPointer parms[])=0;

    virtual int TexturePointsFrV(const RtString filename, RtInt nPoints,
                                RtInt firstchannel, RtInt nchannels, 
                                RtFloat *fr, RtFloat *result, 
                                RtInt n, RtToken tokens[], RtPointer parms[])=0;

    virtual int PTexturePointsFrV(const RtString filename, RtInt nPoints,
                                  RtInt firstchannel, RtInt nchannels, 
                                  RtFloat *faceId, RtFloat *fr, 
                                  RtFloat *result,
                                  RtInt n, RtToken tokens[], 
                                  RtPointer parms[])=0;

    virtual int PTexturePointsV(const RtString filename, RtInt nPoints,
                                RtInt firstchannel, RtInt nchannels, 
                                RtFloat *faceId, 
                                RtFloat *u, RtFloat *v, 
                                RtFloat *du1, RtFloat *dv1,
                                RtFloat *du2, RtFloat *dv2,
                                RtFloat *result,
                                RtInt n, RtToken tokens[], 
                                RtPointer parms[])=0;

protected:
    RixTexture2d() : RixInterface(3) { }
};

class RixTexture : public RixInterface
{
public:
    enum ErrType {
        Ok = 0,
        FileNotFound,
        PartNotFound,
        InvalidFaceIndex,
        TextureAccessErr,
        InvalidDerivatives,
        InvalidFilter,
        InvalidFile
    };

    struct TxProperties {
    public:
        enum TextureType {
            texture = 0, 
            ptexture,        
            latlong, 
            cubeface,
            shadow,
            deepshadow,
        };

        TxProperties () 
            : version(1),
              fileHandle(NULL),
              nchannels(0),
              channelTypes(NULL),
              nparts(0),
              width(0),
              height(0),
              type(texture)
        { }

        int version;            // Version of this struct
        RtPointer fileHandle;   // If NULL, the file could not be acquired
        int nchannels;          // The # of channels in the texture
        unsigned char *channelTypes; // The types of the channels
                                     // 0 - unknown
                                     // 1 - 8  bit
                                     // 2 - 16 bit
                                     // 3 - 32 bit
                                     // 4 - float
                                     // 5 - half
        int nparts;             // The number of parts present
        int width, height;      // Width and height of texture
        TextureType type;       // What type of texture?
    };

    struct TxParams {
    public:
        enum FilterType {
            Nearest = 0,   // *WARNING* disables MIPMAP! No filtering
            Box,           // Fast "box" like filter
            Bilinear,      // Slower, supports derivatives
            Bspline,       // Slower bicubic filter, supports derivatives
            Mitchell,      // Negative lobed, fast, bicubic filter
            Catmullrom,    // Negative lobed, fast, bicubic filter
            Gaussian,      // Gaussian fast filter
            Lagrangian     // Fastest (SSE based) filter
        };

        TxParams () 
            : version(1),
              nchannels(1),
              firstchannel(0),
              lerp(true),
              filter(Box),
              sblur(NULL),
              tblur(NULL),
              sblurVarying(true),
              tblurVarying(true),
              swidth(1.0f), 
              twidth(1.0f),
              fill(0.0f),
              faceIndex(NULL) 
        { }

        int version;           // Version of this struct
        int nchannels;         // The number of channels to lookup      
        int firstchannel;      // The channel to start the lookup     
        bool lerp;             // Should MIP levels be interpolated
        FilterType filter;     // Which filter should be used 
        const float *sblur;    // Amount of blur to apply to lookup
        const float *tblur;   
        bool sblurVarying;     // Is the blur uniform?
        bool tblurVarying; 
        float swidth;          // Multiplier for filter radius
        float twidth; 
        float fill;            // Color to fill missing channels  
        float *faceIndex;      // a faceIndex to access ptexture
    };

    virtual int AcquireTexture (
                    const char *filename,
                    TxProperties &txProperties,
                    bool persistentFilename = false) = 0; 


    virtual int AcquireTexturePart (
                    int partIndex, 
                    TxProperties const &txProperties,
                    TxProperties &partProperties) = 0; 


    virtual int ReleaseTexture (TxProperties const &txProperties) = 0;


    virtual int Texture (
                    TxProperties const &txProperties, 
                    TxParams const &txParams,
                    RtInt nPoints,
                    RtFloat2 const *st,
                    RtFloat const *stRadius,
                    RtFloat *result, 
                    int *runFlags = NULL) = 0;


    virtual int TextureDerivatives (
                    TxProperties const &txProperties, 
                    TxParams const &txParams,
                    RtInt nPoints,
                    RtFloat2 const *st,
                    RtFloat const *dsdu,
                    RtFloat const *dtdu,
                    RtFloat const *dsdv,
                    RtFloat const *dtdv,
                    RtFloat *result, 
                    RtFloat *dresultds, RtFloat *dresultdt,
                    int *runFlags = NULL) = 0;

    virtual int Ptexture (
                    TxProperties const &txProperties, 
                    TxParams const &txParams,
                    RtInt nPoints,
                    RtFloat2 const *uv,
                    RtFloat const *uWidth,
                    RtFloat const *vWidth,
                    RtFloat *result, 
                    int *runFlags = NULL) = 0;


    //  NOTE: No filtering is applied to the data being read.
    virtual int TextureData (
                    TxProperties const &txProperties,
                    TxParams const &txParams,
                    int mipLevel,
                    int cubeFace,
                    void *result) = 0;

protected:
    RixTexture() : RixInterface(1) { }
};

class RixShadeFunctions : public RixInterface
{
public:
    virtual RtFloat Noise(RtFloat  in) = 0;
    virtual RtFloat Noise(RtFloat2 const &in) = 0;
    virtual RtFloat Noise(RtFloat3 const &in) = 0;
    virtual RtFloat Noise(RtFloat3 const &in, RtFloat inF) = 0;

    virtual RtFloat3 Noise3(RtFloat  in) = 0;
    virtual RtFloat3 Noise3(RtFloat2 const &in) = 0;
    virtual RtFloat3 Noise3(RtFloat3 const &in) = 0;
    virtual RtFloat3 Noise3(RtFloat3 const &in, RtFloat inF) = 0;

    virtual RtFloat PNoise(RtFloat  in, RtFloat period) = 0;
    virtual RtFloat PNoise(RtFloat2 const &in, RtFloat2 const &period) = 0;
    virtual RtFloat PNoise(RtFloat3 const &in, RtFloat3 const &period) = 0;
    virtual RtFloat PNoise(RtFloat3 const &in, RtFloat inF, 
                           RtFloat3 const &period, RtFloat periodF) = 0;

    virtual RtFloat3 PNoise3(RtFloat  in, RtFloat period) = 0;
    virtual RtFloat3 PNoise3(RtFloat2 const &in, RtFloat2 const &period) = 0;
    virtual RtFloat3 PNoise3(RtFloat3 const &in, RtFloat3 const &period) = 0;
    virtual RtFloat3 PNoise3(RtFloat3 const &in, RtFloat inF, 
                             RtFloat3 const &period, RtFloat periodF) = 0;

    virtual RtFloat CellNoise(RtFloat  in) = 0;
    virtual RtFloat CellNoise(RtFloat2 const &in) = 0;
    virtual RtFloat CellNoise(RtFloat3 const &in) = 0;
    virtual RtFloat CellNoise(RtFloat3 const &in, RtFloat inF) = 0;

    virtual RtFloat3 CellNoise3(RtFloat  in) = 0;
    virtual RtFloat3 CellNoise3(RtFloat2 const &in) = 0;
    virtual RtFloat3 CellNoise3(RtFloat3 const &in) = 0;
    virtual RtFloat3 CellNoise3(RtFloat3 const &in, RtFloat inF) = 0;

    enum SplineType {
        Bezier = 0, 
        BSpline,        
        Hermite, 
        Linear,
        Catmullrom
    };

    virtual RtFloat SolveSpline (SplineType type, 
                                 RtFloat const knot[],
                                 RtInt nKnots,
                                 RtFloat a) = 0;
    virtual RtFloat EvalSpline  (SplineType type, 
                                 RtFloat const knot[],
                                 RtInt nKnots,
                                 RtFloat a) = 0;
    virtual RtFloat3 EvalSpline3(SplineType type,
                                 RtFloat3 const knot[],
                                 RtInt nknot,
                                 RtFloat a) = 0;
 
protected:
    RixShadeFunctions() : RixInterface(1) { }
};

class RixTransform : public RixInterface
{
public:
    virtual RtInt TransformPoints(RtConstString fromspace, 
                                  RtConstString tospace,
                                  RtInt n, RtPoint p[], RtFloat time) = 0;

    virtual void  TransformPoints(RtMatrix m, RtInt n, RtPoint p[]) = 0;

    virtual RtInt TransformMatrix(RtConstString fromspace, 
                                  RtConstString tospace,
                                  RtFloat time, RtMatrix m) = 0;
 
protected:
    RixTransform() : RixInterface(1) { }
};


class RixAreaShadow : public RixInterface
{
public:

virtual int AreaShadowFrV(RtInt nMaps, const RtString mapNames[],
                          RtFloat* filterRegions,
                          RtInt nLightSamples,
                          RtPoint*  lightPoints,
                          RtColor*  result,
                          RtColor*  perRayResult,
                          RtVector* perRayL,
                          RtFloat*  perRayLMag,
                          RtInt n, RtToken tokens[], 
                          RtPointer parms[]) = 0;

virtual int AreaShadowPV(RtInt nMaps, const RtString mapNames[],
                         RtFloat* points,
                         RtInt nLightSamples,
                         RtPoint*  lightPoints,
                         RtColor*  result,
                         RtColor*  perRayResult,
                         RtVector* perRayL,
                         RtFloat*  perRayLMag,
                         RtInt n, RtToken tokens[], 
                         RtPointer parms[]) = 0;

protected:
    RixAreaShadow() : RixInterface(1) { }
};

class RixMemoryPool : public RixInterface
{
public:
    enum BlockLifetime
    {
        k_EvaluationLifetime, 
            // The duration of a single evaluation of the invoking plugin
            // function, method or execution block. Usually RixAlloca
            // should be preferred over EvaluationLifetime unless the 
            // memory required exceeds the amounts reasonable for the 
            // stack.
        k_ShadeContextLifetime,
            // the duration of a full shader evaluation
    };

    // Allocate will return 0 either the requested lifetime is not supported
    // in the current context or if the pool is exhausted.  The latter 
    // condition is generally not recoverable. 
    virtual void *Allocate(size_t numbytes, BlockLifetime) = 0;

protected:
    RixMemoryPool() : RixInterface(1) { }
};

class RixRenderState : public RixInterface
{
public:
    struct RendererInfo
    {
        const char *renderer;
        const char *version;
        float _UNUSED;
        RtInt versionCode[4];
        char _reserved[32];
    };
    virtual int GetRendererInfo(RendererInfo *) = 0;

    struct FrameInfo
    {
        FrameInfo() : _vers(2) {}
        enum t_integrationMode
        {
            k_distribution,
            k_pathtrace,
        };

        enum t_displayStyle
        {
            k_partialPixels,
            k_finalPixels
        };

        int frame;
        int pixelSamples[2];
        int nthreads;
        float shutter[2]; // when shutter values are equal, no motion-blur
        t_integrationMode integrationMode;
        bool rerendering;
        struct
        {
            int nDisplays; // indexes for GetDspyInfo
            int resolution[2];
            t_displayStyle displayStyle;
        } displayState;

        int _vers; 

        // added in version 2
        // integrator settings are only non-null in RIS mode
        char const *integratorName; 
        char const *integratorPath;
        class RixIntegratorEnvironment const *integratorEnv;

        char _reserved[32];
    };

    virtual int GetFrameInfo(FrameInfo *) = 0;

    struct DspyInfo
    {
        char const *name;
        char const *type;
        char const *mode;
        char _reserved[32];
    };
    virtual int GetDspyInfo(int dspyId, DspyInfo *) = 0;

    enum RayType
    {
        k_rtInvalid=0,
        k_rtCamera,       /* primary visibility ray from a camera */
        k_rtLight,        /* photon ray directly from a light source */
        k_rtSpecular,     /* specularly reflected ray/photon */
        k_rtDiffuse,      /* diffusely reflected ray/photon */
        k_rtTransmission, /* shadow ray */
        k_rtDirectlight,  /* directlighting ray */
        k_rtNumRayTypes
    };

    enum ShadingIntent
    {
        k_siInvalid=0,
        k_siShadeGrid,
        k_siShadeRay,
        k_siCache,
        k_siNumShadingIntents
    };

    struct RayCtxInfo
    {
        bool rayhit; /* Camera rays can either be reyes or raytraced */
        RayType raytype;
        char const *raylabel;
        int depth, diffusedepth, speculardepth, shadowdepth, subsurfacedepth;
        int integratorIteration; // always 0 when in distribution integration
        int currentDecimation, maxDecimation; // only nonzero during rerendering
        ShadingIntent shadingIntent;
        char _reserved[32];
    };

    virtual int GetRayCtxInfo(RayCtxInfo *) = 0;

    enum Type
    {
        k_Float, 
        k_Integer, 
        k_StringV, 
        k_Color,
        k_Normal, 
        k_Vector, 
        k_Point, 
        k_HPoint,
        k_MPoint, 
        k_Matrix
    };
    virtual int GetOption(const char *name, void *result, int resultlen,
                        Type *resulttype, int *resultcount) = 0;

    virtual int GetAttribute(const char *name, void *result, int resultlen,
                        Type *resulttype, int *resultcount) = 0;

    virtual int GetAttrIdNameStack(char const *idstack[], unsigned maxlen) = 0;



protected:
    RixRenderState() : RixInterface(2) { }
};

class RixSymbolResolver : public RixInterface
{
public:
    virtual RtToken ResolveToken(char const *nm) = 0;

    enum SymbolGroup
    {
        k_PixelFilter   = 0,
        k_Basis         = 1,
        k_Procedural    = 2,
        k_ErrorHandler  = 3,
        k_RiEntryPoint  = 4
    };
    //
    virtual RtPointer ResolveSymbol(const char *nm, SymbolGroup group) = 0;

protected:
    RixSymbolResolver() : RixInterface(1) {}
};

class RixResourceResolver : public RixInterface
{
public:
    enum ResourceType
    {
        k_Shader=0,
        k_Texture,
        k_Archive,
        k_Display,
        k_Procedural,
        k_RifFilter,
        k_RixPlugin
    };

    virtual char const *GetResourcePaths(ResourceType) = 0;

    virtual int ResolveResource(ResourceType, char const *nm,
                                char result[], int maxlen) = 0;

protected:
    RixResourceResolver() : RixInterface(1) {}
};

class RixGeoDebugger : public RixInterface
{
public:
     virtual void EmitVector(RtVector3 v, RtColorRGB c)=0;
     virtual void EmitPoint(RtPoint3 p, RtColorRGB c)=0;
     virtual void EmitPointNormal(RtPoint3 p, RtNormal3 n, RtColorRGB c)=0;
     virtual void EmitLine(RtPoint3 p1, RtPoint3 p2, RtColorRGB c)=0;
     virtual void EmitBound(RtPoint3 pmin, RtPoint3 pmax, RtColorRGB c)=0;
     virtual void Clear()=0;
     virtual void Flush()=0;

protected:
    RixGeoDebugger() : RixInterface(1) {}
};

extern "C" {
    PRMANAPI class RixContext *RixGetContext();
    PRMANAPI class RixContext *RixGetContextViaRMANTREE(const char*rmantree=0L,
                                                        bool printerror=true);
}

typedef RtInt RixLPEToken;

class RixLPEInfo : public RixInterface 
{
  public:
    virtual int GetLpeIdByName(bool discrete, bool specular,
                               bool reflect, bool user,
                               unsigned char lobeId, char const *name) = 0;

    virtual int GetNumPotentialDiffuseLobes() = 0;
    virtual int GetNumPotentialSpecularLobes() = 0;
    virtual int GetNumPotentialUserLobes() = 0;
    virtual RixLPEToken StringToToken(char const *str) = 0;

protected:
    RixLPEInfo() : RixInterface(1) {}
};

class RixLPEState;
class RixShadingContext;

// This is a callback routine for use with the 
// RixCustomLPE::RegisterScatterCallback() and 
// RixCustomLPE::InvokeScatterCallbacks(), described in more detail below.
typedef void (*RixLPECallback)(void *userData,
                               RixLPEState *lpeState, 
                               RixShadingContext const *sCtx, 
                               int sCtxIndex,
                               RtColorRGB const &thruput,
                               RtColorRGB const *lgtTrans, 
                               bool firstContribution);

class RixCustomLPE : public RixInterface 
{
  public:

    // Use this method to return an integer identifier that corresponds to
    // a given Light Path Expression (LPE).
    virtual int LookupLPE(char const *lpeExpr) = 0;

    // This method returns true if the 'customLpe' integer identifier
    // (which should be obtained by calling LookupLPE()) matches the current
    // ray hit, returning true or false along with the cumulative path 
    // throughput corresponding to the custom LPE. This method should typically
    // be called from within a registered "transition" callback routine 
    // (see RegisterScatterCallback() below).
    virtual bool MatchesLPE(int customLpe, 
                            RixLPEState *lpeState, 
                            RtColorRGB &thruput) = 0;

    // Use this method to register a "scatter" callback. Each scattering
    // event along the ray path counts as a "scatter" event (that is, each 
    // ray-geometry intersection hit point that results in light being 
    // scattered throughout the scene). Ater registering a scatter callback,
    // the callback routine will be invoked at each scattering event. Within
    // a scatter callback routine one might make a call to the MatchesLPE()
    // method in order to determine whether a particular custom LPE matches
    // the current ray path history.
    virtual void RegisterScatterCallback(RixLPECallback callbackFunc, 
                                         void *userData = NULL) = 0;

    // Calling this method will invoke all registered scatter callback routines.
    // Typically this method is only called internally by the core rendering
    // code (and typically end-user code would not need to call this method 
    // directly). Instead this routine is called indirectly via the RixLPE 
    // interface whenever there is a scattering event.
    virtual void InvokeScatterCallbacks(RixLPEState *lpeState,
                                        RixShadingContext const *sCtx,
                                        int sCtxIndex,
                                        RtColorRGB const &thruput,
                                        RtColorRGB const *lgtTrans, 
                                        bool firstContribution) = 0;

protected:
    RixCustomLPE() : RixInterface(1) {}
};

#endif  // RIX_INTERFACE_H