CVEX_Context.h

Go to the documentation of this file.

/*
 * PROPRIETARY INFORMATION.  This software is proprietary to
 * Side Effects Software Inc., and is not to be reproduced,
 * transmitted, or disclosed in any way without written permission.
 *
 * NAME:        CVEX_Context.h ( CVEX Library, C++)
 *
 * COMMENTS:    C++ interface to VEX.  This class defines a parameter to the
 *              VEX function.
 */

#ifndef __CVEX_Context__
#define __CVEX_Context__

#include "CVEX_API.h"
#include "CVEX_Function.h"
#include "CVEX_ValueList.h"
#include "CVEX_Transform.h"
#include <VEX/VEX_PodTypes.h>
#include <UT/UT_NonCopyable.h>
#include <UT/UT_UniquePtr.h>

template <VEX_Precision PREC> class cvex_RunData;
class UT_OpCaller;
template <VEX_Precision PREC> class VEX_AutoInstance;
template <VEX_Precision PREC> class VEX_AutoFoldedCode;
template <VEX_Precision PREC> class VEX_Instance;
class VEX_GeoInputs;
template <VEX_Precision PREC> class VEX_GeoCommandQueue;
class VEX_ChannelCache;
class VEX_FileCache;

/// @brief Per-run data for CVEX execution
///
/// This class is used to set and retrieve data specific to an individual
/// execution run using CVEX_Context::run().
template <VEX_Precision PREC>
class CVEX_API CVEX_RunDataT : public UT_NonCopyable
{
public:
    CVEX_RunDataT();
    ~CVEX_RunDataT();

    /// Resets the run data for re-use.
    void                 clear();

    /// Set the evaluation time.  This is what will be used by op: references
    /// triggered by VEX commands like volumesample.  If not set, the current
    /// channel time is used instead (if an OP_Director is available).
    void                 setTime(fpreal time)
                         {
                             myTimeSpecified = true;
                             myTransform.setTime(time);
                         }

    /// Sets the operator working directory.  This is used by ch() 
    /// style vex functions to determine where the relative path for
    /// path resolution should be.
    /// Use OP_Node::getUniqueId() to pass this in.
    void                 setCWDNodeId(int id)
                         {
                             myTransform.setCwdId(id);
                         }
    /// The world id is the node which defines the transform space for the CWD.
    /// If it's not defined the object containing the CWD will be used (or the
    /// CWD if it's not part of an object network)
    void                setWorldNodeId(int id)
                        {
                            myTransform.setWorldId(id);
                        }

    /// Sets the OP callback. This is used to setup dependencies on any
    /// referenced op: expressions.  Can be applied to the context at any time.
    void                 setOpCaller(UT_OpCaller *caller)
                         {
                             myTransform.setOpCaller(caller);
                         }

    /// Access to the OP_Caller
    UT_OpCaller         *getOpCaller() const { return myTransform.opCaller(); }

    /// Returns true when, after running the CVEX_Context, a ch() function
    /// reported that it was time dependent.
    bool                 isTimeDependent() const { return myTimeDependent; }

    /// Set flag indicating whether there are any time samples involved.
    void                setTimeSampleEncountered(bool v)
                        { 
                            myTimeSampleEncountered = v; 
                        }

    /// Returns true when, after running the CVEX_Context, a usd_attrib() 
    /// function reported that it has some time samples (values at time codes).
    bool                 isTimeSampleEncountered() const 
                         { 
                             return myTimeSampleEncountered; 
                         }

    /// Sets the geo input callback for controlling how opinput: references
    /// are handled
    void                 setGeoInputs(const VEX_GeoInputs *geo)
                         {
                             myGeoInputs = geo;
                         }
    const VEX_GeoInputs *getGeoInputs() const { return myGeoInputs; }

    /// Sets the proc id array.  Owned by the caller.  Must be at least
    /// the length of your size.
    void                setProcId(exint *procid)
                        {
                            myProcId = procid;
                        }
    const exint         *getProcId() const { return myProcId; }

    /// Sets the command queue for this context
    void                 setGeoCommandQueue(VEX_GeoCommandQueue<PREC> *geocmd)
    {
        myGeoCommandQueue = geocmd;
    }
    VEX_GeoCommandQueue<PREC> *getGeoCommandQueue() const
    {
        return myGeoCommandQueue;
    }

    VEX_ChannelCache *getChannelCache() { return myChannelCache; }

    VEX_FileCache* getFileCache() { return myFileCache; }

    /// Every VEX function has a transform context associated with it.  This
    /// transform context is used by VEX functions like ptransform() to provide
    /// ways to transform to other spaces (like "space:world" or
    /// "space:object").  This method allows you to modify the transform
    /// context of this shader.
    CVEX_Transform      &getTransform() { return myTransform; }

    /// @{
    /// Accessors
    bool                 timeSpecified() const  { return myTimeSpecified; }
    bool                 timeDependent() const  { return myTimeDependent; }
    int                  cwdId() const          { return myTransform.cwdId(); }
    int                  worldId() const        { return myTransform.worldId();}
    fpreal               time() const           { return myTransform.time(); }
    /// @}
    /// Set as time dependent flag
    void                setTimeDependent(bool v)        { myTimeDependent = v; }

    /// Get the cached VEX_Instance, which can be reused for multiple runs
    /// until clear() is called.
    /// This ensures that local word data (e.g. geometry bindings) remain the
    /// same between runs.
    VEX_Instance<PREC> *getOrCreateInstance(
            const VEX_AssemblePtr &assemble,
            const UT_SharedPtr<VEX_AutoFoldedCode<PREC>> &code);

private:
    CVEX_Transform       myTransform;
    const VEX_GeoInputs *myGeoInputs;
    VEX_GeoCommandQueue<PREC> *myGeoCommandQueue;
    exint               *myProcId;
    bool                 myTimeSpecified;
    bool                 myTimeDependent;
    bool                 myTimeSampleEncountered;
    VEX_ChannelCache    *myChannelCache;
    VEX_FileCache       *myFileCache;

    // The VEX_AutoInstance depends on the lifetime of the VEX_Assemble and
    // VEX_AutoFoldedCode.
    VEX_AssemblePtr myAssemble;
    UT_SharedPtr<VEX_AutoFoldedCode<PREC>> myCode;
    UT_UniquePtr<VEX_AutoInstance<PREC>> myInstance;
};

using CVEX_RunData = CVEX_RunDataT<VEX_32>;

CVEX_EXTERN_TEMPLATE(CVEX_RunDataT<VEX_32>);
CVEX_EXTERN_TEMPLATE(CVEX_RunDataT<VEX_64>);

/// These methods return the meta count and unique id of the global
/// cvex function cache.  This isn't for this particular context, thus
/// is static.  If these change, all your contexts allocated before
/// will be invalid.
CVEX_API exint CVEXgetGlobalContextUniqueId();
CVEX_API exint CVEXgetGlobalContextClearCount();

enum class CVEX_ProbeResult
{
    PROBE_ERROR,        // Shader hasn't been loaded or there were errors
    NOT_ASSIGNED,       // Variable is not assigned any value
    CONSTANT_0,         // Variable is always set to 0
    CONSTANT_1,         // Variable is always set to 1
    CONSTANT_VALUE,     // Variable is a constant value (not 0 or 1)
    NOT_CONSTANT,       // Variable is not-constant
};

/// @brief Call VEX from C++
///
/// The CVEX_Context class provides the main interface to let C++ code call VEX
/// to perform computations.  This allows users to modify algorithms by
/// performing computations in VEX.
/// - VEX automatically takes advantage of SSE
/// - VEX can perform run-time optimization
template <VEX_Precision PREC>
class CVEX_API CVEX_ContextT : public UT_NonCopyable 
{
public:
     CVEX_ContextT();
    ~CVEX_ContextT();

    /// clearing the context will allow you to set up the input and output
    /// parameters again.
    /// @note load() must be called again before you can run the VEX code.
    void        clear();

    /// calling clearAllFunctions() will force all CVEX object code to be
    /// flushed out of memory and to be reloaded.  Be cautioned that this may
    /// have side-effects, and should only be called at a safe time.
    /// @note This will also cause *all* functions to be cleared (see clear()).
    static void clearAllFunctions();

    /// Removes the given function from the CVEX context.
    static void clearFunction(const UT_StringRef &fn_name);

    /// This method will return true if the code referenced by the context has
    /// been deleted (see @clearAllFunctions()).  If you've cached a
    /// CVEX_Context, then this can be used to see if it's still valid.
    bool        isValid() const;

    /// Add possible input parameters to the function.  These are parameters
    /// whose values are overridden by values you pass in.  If the user's VEX
    /// function has these parameters the C++ code should assign the values
    /// after calling load(), but before calling run().
    ///
    /// Calling this version of addInput() allows you to defer computing the
    /// value of the variable until you know whether it will actually be used
    /// by the VEX function.
    bool        addInput(const UT_StringHolder &name,
                         CVEX_Type type, bool varying);

    /// If you know the value beforehand, you can add the symbol and it's
    /// value at the same time.
    /// Note: The data is referenced, not copied, so keep it live until after
    /// run() has been called.
    bool        addInput(const UT_StringHolder &name,
                         CVEX_Type type, 
                         void *data, int array_size);

    /// Adds a constant input.  You should still maintain the reference
    /// but the data may be constant folded into the assemble, so the
    /// values *must* be set ahead of time and possibly will not update
    /// if you change the original.
    bool        addConstantInput(const UT_StringHolder &name,
                         CVEX_Type type,
                         void *data, int array_size);
    bool        addConstantInput(const UT_StringHolder &name, CVEX_StringArray &strings);

    /// Add an "string <name>" input.  An array length of 1 makes the variable
    /// uniform.
    /// Note: The strings are referenced, not copied, so keep it live until
    /// after run() has been called.
    bool        addInput(const UT_StringHolder &name, CVEX_StringArray &strings);

    /// Add a required output. If no required output is specified, all
    /// exports/outputs are computed.
    /// Note: Due to the varying/uniform state of an output depending
    /// significantly on the inputs' varying/uniform state -- and operations
    /// performed -- then, unlike addInput, no storage can be allocated until
    /// after load.
    /// Note: If no storage is allocated, the output is still computed but
    /// the result is thrown away.
    bool        addRequiredOutput(const UT_StringHolder &name, CVEX_Type type);

    /// Checks if the VEX function by the given name already exists.
    bool        hasFunction(const UT_StringRef &name) const;

    /// Load the definition of the VEX function.
    /// Usually VEX functions are loaded from compiled VEX code stored
    /// in files on the search path. But, callers can  use this method  to  
    /// define a VEX function from the stream.
    /// The module name can be optionally overriden with a name argument (if
    /// it's NULL, the name in the stream is used implicitly).
    /// The final name of the module is returned in actual_name (if not NULL).
    /// If override_old is true, if the old function by that name is found,
    /// then it will be overriden and updated with the new one.
    bool        preloadFile(UT_IStream &is, const char *name, 
                    UT_String *actual_name, bool override_old);

    /// Loads the given file.  Instead of registering the loaded
    /// function in the global function table, returns it as a CVEX_Function
    CVEX_Function       preloadFunction(const UT_StringHolder &snippet);
    CVEX_Function       preloadFunction(UT_IStream &is);

    /// Loads the functin form the global function table.
    CVEX_Function       preloadGlobalFunction(const char *funcname);

    /// Load the VEX function.
    /// Inputs must be specified @b before this function is called.  After
    /// loading, the input list will have flags set telling you whether the
    /// input parameter is used.  At this point, you should set the data for
    /// all used inputs.
    ///
    /// The list of outputs will also be defined, meaning that you can figure
    /// out what's going to be written by the VEX function.
    bool        load(int argc, const char *const argv[]);

    /// With load function we already have pre-loaded the CVEX_Function
    /// so the argv[0] is ignored.
    bool        loadFunction(CVEX_Function function, int argc, const char *const argv[]);

    /// Quick test to see if the function has been loaded.
    bool        isLoaded() const;

    /// The list of input parameters to the function.  It's possible that
    /// these values may be shared between the input and output lists.
    CVEX_ValueListT<PREC>       &getInputList()         { return myInputs; }
    const CVEX_ValueListT<PREC> &getInputList() const   { return myInputs; }
    
    /// Find an input by name/type.
    const CVEX_ValueT<PREC>     *findInput(const UT_StringRef &name, CVEX_Type type) const
                         { return myInputs.getValue(name, type); }
    CVEX_ValueT<PREC>           *findInput(const UT_StringRef &name, CVEX_Type type)
                         { return myInputs.getValue(name, type); }
    
    /// Find an input by name.
    const CVEX_ValueT<PREC>     *findInput(const UT_StringRef &name) const
                         { return myInputs.getValue(name, CVEX_TYPE_INVALID); }
    CVEX_ValueT<PREC>           *findInput(const UT_StringRef &name)
                         { return myInputs.getValue(name, CVEX_TYPE_INVALID); }

    /// The list of output parameters from the function.  After the function
    /// has been run, the output parameters will have their values written to
    /// by VEX.
    ///
    /// If the output has not had CVEX_Value::setData() called, then the data
    /// will have been written to internal storage and can be retrieved calling
    /// CVEX_Value::getData().
    const CVEX_ValueListT<PREC> &getOutputList() const  { return myOutputs; }
    CVEX_ValueListT<PREC> &getOutputList()              { return myOutputs; }

    /// Find an output by name/type.
    const CVEX_ValueT<PREC>     *findOutput(const UT_StringRef &name, CVEX_Type type) const
                         { return myOutputs.getValue(name, type); }
    CVEX_ValueT<PREC>           *findOutput(const UT_StringRef &name, CVEX_Type type)
                         { return myOutputs.getValue(name, type); }

    /// Find and output by name.
    const CVEX_ValueT<PREC>     *findOutput(const UT_StringRef &name) const
                         { return myOutputs.getValue(name, CVEX_TYPE_INVALID); }
    CVEX_ValueT<PREC>           *findOutput(const UT_StringRef &name)
                         { return myOutputs.getValue(name, CVEX_TYPE_INVALID); }

    /// Query the assignment status of an output.  This must be called after
    /// the code has been loaded.
    CVEX_ProbeResult    probeOutput(const UT_StringRef &name,
                                CVEX_Type type) const;

    /// Initializes the values array with the defaults of the given parameter.
    /// Leaves values empty if it can't find the parameter.
    void                 getParameterDefaults(const UT_StringRef &name,
                                CVEX_Type ctype,
                                UT_DoubleArray &values) const;

    /// Run the VEX function given a list of input variables and a list of
    /// output parameters.  Each input/output parameter under your control
    /// should have an array size of either 1 or at least the array_size given
    /// to the run() method.  It's possible to run on fewer array elements
    /// than have been allocated, but an error will be returned if there are
    /// input parameters which don't have enough allocation.
    ///
    /// Pass in true for interruptable when running from within Houdini.
    ///
    /// The run() function may be called multiple times, provided that the
    /// input parameters don't change.  So, if you need to evaluate the data
    /// in chunks, you can do this by re-initializing the input parameter data
    /// between calls to run().  However, you should not change the
    /// uniform/varying state of any input parameters without doing a re-load
    /// of the VEX function.
    /// @param array_size The size of varying arrays.  All varying arrays must
    ///   be this size.
    /// @param interruptable If true, VEX will check the state of the
    ///   UT_Interrupt.  This should be enabled when called from within
    ///   Houdini.  If interruptable is false, then the user will @b not be
    ///   able to break out of endless loops in VEX.  It's better to leave it
    ///   true if you are unsure.
    /// @param rundata Data that matches the precision PREC.
    bool        run(int array_size, bool interruptable,
            CVEX_RunDataT<PREC> *rundata = nullptr);

    /// If load() or run() return false, this will return the error that
    /// triggered the CVEX failure. Note that this is distinct from errors
    // and warnings occurring when running VEX.
    const char *getLastError() const { return myError; }

    /// If load() or run() failed or reported warnings, these methods will
    /// return the errors reported by VEX.
    /// {
    const UT_String     &getVexErrors() const;
    const UT_String     &getVexWarnings() const;
    /// }

    /// Clear the errors reported by getVexErrors() / getVexWarnings().
    void                 clearVexErrors();

    /// Add Constant Integer 32 Arrays
    bool        addConstantInput(const UT_StringHolder &name, UT_PackedArrayOfArrays<VEXint<PREC> > &intdata);

private:
    struct cvex_BoundValue
    {
        cvex_BoundValue()
            : myValue(nullptr)
            , myBindPtr(nullptr)
            , myStoragePtr(nullptr)
        {}
        CVEX_ValueT<PREC>*myValue;
        void            *myBindPtr;
        void            *myStoragePtr;
    };

    bool                 validateValue(const CVEX_ValueT<PREC> &value,
                                VEX_Instance<PREC> &state, int nproc);
    void                 copyBoundData(cvex_BoundValue &bound,
                                VEX_Instance<PREC> &state,
                                int start, int nproc);
    bool                 bindValues(UT_Array<cvex_BoundValue> &bound_vals,
                                VEX_Instance<PREC> &state, int nproc);
    void                 extractStrings(CVEX_ValueT<PREC> &value,
                                VEX_Instance<PREC> &state,
                                int start, int nproc);
    void                 extractDicts(CVEX_ValueT<PREC> &value,
                                VEX_Instance<PREC> &state,
                                int start, int nproc);
    void                 extractArrays(CVEX_ValueT<PREC> &value,
                                VEX_Instance<PREC> &state,
                                int start, int nproc);
    void                 extractUniform(CVEX_ValueT<PREC> &value,
                                VEX_Instance<PREC> &state);

    bool        loadPrivate(const VEX_AssemblePtr &as,
                        int argc, const char *const argv[]);

    CVEX_ValueListT<PREC>       myInputs;
    CVEX_ValueListT<PREC>       myOutputs;
    UT_UniquePtr<cvex_RunData<PREC> >   myRunData;
    UT_String                   myError;

    UT_Array<cvex_BoundValue>   myBoundVals;

    UT_Array<VEXint<PREC>*> &getTempI() { myTempI.clear(); return myTempI; }
    UT_Array<VEXfloat<PREC>*> &getTempF() { myTempF.clear(); return myTempF; }

    UT_Array<VEXfloat<PREC>*> myTempF;
    UT_Array<VEXint<PREC>*> myTempI;
};

using CVEX_Context = CVEX_ContextT<VEX_32>;

CVEX_EXTERN_TEMPLATE(CVEX_ContextT<VEX_32>);
CVEX_EXTERN_TEMPLATE(CVEX_ContextT<VEX_64>);

#endif