LOP_Node.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:        LOP Library (C++)
 *
 * COMMENTS:    The base class for all Lighting Operators
 *
 */

#ifndef __LOP_Node_h__
#define __LOP_Node_h__

#include "LOP_API.h"
#include "LOP_Error.h"
#include "LOP_LayerCheckpoints.h"
#include "HUSD/HUSD_Utils.h"

#include <OP/OP_Network.h>
#include <HUSD/HUSD_DataHandle.h>
#include <HUSD/HUSD_PathSet.h>
#include <HUSD/HUSD_TimeCode.h>
#include <HUSD/HUSD_Xform.h>
#include <GU/GU_DetailHandle.h>
#include <UT/UT_AttributeEvaluator.h>
#include <UT/UT_Ramp.h>

class LOP_Network;
class HUSD_PythonConverter;
class HUSD_EditCustomData;
class HUSD_FindPrims;
class HUSD_FindProps;
class HUSD_Info;
class PRM_Template;
class PRM_Name;
class UT_ArrayStringSet;
class UT_StringSet;

extern "C" {
    SYS_VISIBILITY_EXPORT extern void newLopOperator(OP_OperatorTable *table);
};

#define LOP_DEBUG_FLAG          'D'

enum LOP_EditableObject {
    LOP_STAGE, 
    LOP_LAYER,
    LOP_PREEXISTING
};

enum LOP_InputNameVariableId {
    LOP_INPUTNAME_VAR_IIDX,
    LOP_INPUTNAME_MAX_VARIABLES
};

enum LOP_ActivationState {
    LOP_ACTIVATION_ABSENT,
    LOP_ACTIVATION_OFF,
    LOP_ACTIVATION_ON
};

class LOP_LayerReplacementInfo
{
public:
    UT_StringHolder        myReplacementIdentifier;
    HUSD_MakeNewPathFunc   myMakeNewPathFn;
    bool                   myCreateReplacement = false;
    bool                   myReplaceSublayersOnly = false;
    bool                   myClearSource = false;
    bool                   myCreateNewSublayer = false;
    UT_StringHolder        myCreateNewSublayerName;
    int                    myCreateNewSublayerIndex = 0;
};

class LOP_AttributeParmSet
{
public:
                         LOP_AttributeParmSet()
                             : myFrame(1.0),
                               myTime(0.0),
                               myRampBasisIsArray(false),
                               myMultiParmType(PRM_MULTITYPE_NONE),
                               myValueXformStyle(HUSD_XFORM_APPEND),
                               myValueLength(1),
                               myValueIsTimeDep(false),
                               myValueIsOrdered(false),
                               myIsCustom(true), // USD assumes custom attribs
                               myExpandCollection(true),
                               myClearAttrib(false),
                               myCollectionUsePathExpr(false),
                               myCollectionAllowInstanceProxies(false)
                         { }

    fpreal                           myFrame;
    fpreal                           myTime;
    UT_StringHolder                  myPrimPath;
    UT_StringHolder                  myAttrName;
    UT_StringHolder                  myRampCountAttrName;
    UT_StringHolder                  myRampBasisAttrName;
    bool                             myRampBasisIsArray;
    UT_StringHolder                  myRampPosAttrName;
    UT_StringHolder                  myControl;
    UT_StringHolder                  myInterpolation;
    PRM_Type                         myParmType;
    PRM_MultiType                    myMultiParmType;
    UT_StringHolder                  myApiSchema;
    UT_StringHolder                  myXformParmPrefix;
    UT_StringHolder                  myConnection; // path to the source attrib
    UT_StringHolder                  myValueType;
    UT_StringHolder                  myValueStr;
    int                              myValueInt[16];
    fpreal64                         myValueFloat[16];
    UT_Ramp                          myValueRamp;
    HUSD_XformStyle                  myValueXformStyle;
    int                              myValueLength;
    bool                             myValueIsTimeDep;
    bool                             myValueIsOrdered;
    bool                             myIsCustom;
    bool                             myExpandCollection;
    bool                             myClearAttrib;

    // Data members specific to authoring a collection from parms. This
    // data is used if myValueType == HUSD_PROPERTY_VALUETYPE_COLLECTION.
    UT_StringHolder                  myCollectionParmPrefix;
    UT_StringHolder                  myCollectionName;
    UT_StringHolder                  myCollectionIncludePattern;
    UT_StringHolder                  myCollectionExcludePattern;
    UT_StringHolder                  myCollectionExpansionRule;
    UT_StringHolder                  myCollectionIcon;
    bool                             myCollectionUsePathExpr;
    bool                             myCollectionAllowInstanceProxies;
};
typedef UT_Array<LOP_AttributeParmSet> LOP_AttributeParms;

class LOP_API LOP_Node : public OP_Network
{
public:
    // Standard OP_Network stuff:
    static const char   *theChildTableName;
    const char          *getChildType() const override;
    const char          *getOpType() const override;

    OP_OpTypeId          getChildTypeID() const override;
    OP_OpTypeId          getOpTypeID() const override;
    OP_DataType          getCookedDataType() const override;

    static void          buildOperatorTable(OP_OperatorTable &table);
    static OP_Operator  *getManagementOperator();
    static void          initializeExpressions();

    // Get a LOP node from the provided path. If the path is a LOP node path,
    // return that LOP node. If it is a LOP network path, return the path to
    // that LOP network's viewer node.
    static LOP_Node     *getLopNodeFromLopOrNetworkPath(const char *path,
                                bool default_to_stage = true);

    // Local variables that can be used by nodes which allow user-specifiable
    // names on inputs (such as merge into and add variant).
    static CH_LocalVariable theInputNameLocalVariables[];

    void                 opChanged(OP_EventType reason, void *data=0) override;
    void                 onCreated() override;

    fpreal               getW() const override;
    fpreal               getH() const override;

    // Gets/sets the value of the debug flag on this node.
    bool                 getDebug() const override;
    bool                 setDebug(bool state) override;
    void                 setFlag(char flag, int8 val) override;
    bool                 getNestedDebug() const;

    // Overrides the current node pointer method to ensure that we always
    // find a current node when the old current node is deleted, even in the
    // absence of a display node.
    OP_Node             *getCurrentNodePtr() override;
    // Overrides the display node pointer method because a LOP node with LOP
    // children doesn't need to have a display node, and will return the
    // display node of the parent LOP network if it doesn't have its own.
    OP_Node             *getDisplayNodePtr() override;
    void                 childFlagChange(OP_Node *nodeptr) override;
    virtual LOP_Node    *getViewerLop();

    // Gets the output child node corresponding to the specified output index.
    LOP_Node            *getOutputLop(int outputidx) const;

    // Override the function that determines whether this node should be
    // drawn in the network editor with a "bypass" look. LOPs have an optional
    // "bypass" spare parameter that makes the node act like it is bypassed,
    // so it should also be drawn like it's bypassed.
    bool                 getUseBypassLook(
                                const OP_EditorContext &ctx) const override;

    // Cook this node and return a data handle for the resulting stage.
    const HUSD_DataHandle &getCookedDataHandle(OP_Context &context,
                                int outidx = 0,
                                bool use_last_cook_context_options = false,
                                const UT_StringSet *protect_options = nullptr);
    // Cook this node and return a data handle for the resulting stage. If
    // the cook leaves this node in an error state, go to this node's first
    // connected input, and try to return the cooked data handle for that
    // node, and so on. This method is useful for the scene graph tree and
    // similar panels, where it's much more useful to show something than
    // nothing in the case of an error. Returns the data handle and a
    // pointer to the node whose data is actually returned.
    const HUSD_DataHandle &getCookedDataHandleBypassingErrors(
                                LOP_Node *&owner_node,
                                int &owner_outidx,
                                OP_Context &context,
                                int outidx = 0,
                                bool use_last_cook_context_options = false,
                                const UT_StringSet *protect_options = nullptr);
    // Return true if this node was the most recent node to create a lock
    // on the stage we may be sharing with many other nodes.
    bool                 isMostRecentStageLock() const;

    // Get the badge clor we should use for this LOP node do indicate which
    // active layer is modified by this node.
    bool                 hasLayerColorIndex(int &clridx) const;

    // Return true if this node is in an Edit Layer Block, otherwise false.
    bool                 inEditLayerBlock(OP_Context &context);

    // Override this for nodes that want to allow python code to edit their
    // stage or active layer directly.
    virtual HUSD_PythonConverter *getEditableObject(LOP_EditableObject obj);

    // Create a new HUSD_LoadMasks object using parameters on the creator
    // LOP Network to set variant selection fallback values.
    HUSD_LoadMasksPtr    createNewLoadMasks();

    // Evaluate a simplified adhoc collection parm and use it to fill in an
    // HUSD_FindPrims object.
    static bool          getSimplifiedCollection(OP_Node *node,
                                const UT_StringRef &primpattern,
                                HUSD_FindPrims &findprims);
    // Evaluate a simplified adhoc collection parm and use it to fill in an
    // HUSD_FindProps object.
    static bool          getSimplifiedCollection(OP_Node *node,
                                const UT_StringRef &primpattern,
                                const UT_StringRef &proppattern,
                                HUSD_FindProps &findprops);
    // Evaluate a pattern string using an HUSD_FindPrims against a LOP node's
    // editableDataHandle, and return an array of matching paths. Isolates
    // the locking of the stage to this function.
    static bool          getPathsFromPattern(LOP_Node &lop,
                                const UT_StringRef &pattern,
                                UT_StringArray &paths,
                                bool allow_missing_explicit_prims = false,
                                HUSD_PrimTraversalDemands demands =
                                    HUSD_TRAVERSAL_DEFAULT_DEMANDS);
    // Tests if the provided primitive is editable. Adds the result to the
    // provided map so the next call with the same path can return the cached
    // result immediately. The first time each non-editable prim is found,
    // a warning is added to this node.
    bool                 isPrimitiveEditable(
                                UT_StringMap<bool> alloweditmap,
                                const HUSD_Info &info,
                                const UT_StringHolder &path,
                                bool ignoreeditableflag,
                                LOP_ErrorCodes non_editable_error_code =
                                    LOP_PRIM_NOT_EDITABLE);

    // Return the number of layers in our data handle.
    int                  layerCount() const;

    // Track the set of primitives modified by the most recent cook of
    // this node.
    const HUSD_PathSet  &lastModifiedPrims() const;
    void                 setLastModifiedPrims(const UT_StringRef &path,
                                bool add_to_existing = false);
    void                 setLastModifiedPrims(const UT_StringArray &paths,
                                bool add_to_existing = false);
    void                 setLastModifiedPrims(const UT_ArrayStringSet &paths,
                                bool add_to_existing = false);
    void                 setLastModifiedPrims(const HUSD_FindPrims &findprims,
                                bool add_to_existing = false);
    void                 setLastModifiedPrims(const HUSD_PathSet &paths,
                                bool add_to_existing = false);
    void                 setLastModifiedPrimsWithPathExpression(
                                HUSD_AutoAnyLock &lock,
                                const UT_StringRef &path_expr,
                                bool add_to_existing = false);
    void                 clearLastModifiedPrims();

    // Tests if this node has an active layer that is large enough that we
    // want output nodes to always start a new active layer. The default
    // implementation looks at the number of lastModifiedPrims. This method
    // is const and should never trigger a cook - it should always look at
    // data from the most recent cook (and return false if the node has
    // never been cooked).
    virtual bool         hasLargeActiveLayer() const;

    // For a new stage being authored by this node, these methods allow the
    // node to control the asset path or url/string pairs used to configure
    // the stage's asset resolver context. Individual node types can provide
    // custom implementations.
    virtual bool         getResolverContextAssetPath(UT_String &assetpath);
    virtual bool         getResolverContextStrings(
                                UT_StringMap<UT_StringHolder> &resolverstrings);

    // Code for tracking convex hulls around context option "blocks" in the
    // network editor.
    virtual bool         showConvexHull() const
                         { return false; }
    virtual int          contextOptionsStackEffect(int input) const
                         { return 0; }
    virtual void         findEnclosedItems(OP_EnclosedItems &items) const;

    // Evaluate local variables common to multiple LOP node types.
    bool                 evalVariableValue(fpreal &val, int var_id, 
                                int thread) override;
    bool                 evalVariableValue(UT_String &val, int var_id, 
                                int thread) override;
    UT_AttributeEvaluator *createAttributeEvaluator(
                                const char *name) override;
    void                 getAttributeEvaluatorNames(
                                UT_StringArray &names) override;

    bool                 lastCookActivationState() const
                         { return myLastCookActivation; }
    HUSD_TimeCode        getTimeCode(const OP_Context &context,
                                bool timedep) const;
    HUSD_LoadMasksPtr    getLastCookLoadMasks(int outidx = 0);

    // Public functions for adding warnings and errors, so that utility
    // methods in LOP_PRMShared and elsewhere can add errors directly to
    // LOP nodes.
    void                 addSystemError(const char *msg = 0)
                         { getLockedErrorManager()->systemError(msg); }
    void                 addError(int code, const char *msg = 0)
                         { getLockedErrorManager()->
                             addError(LOP_OPTYPE_NAME, code, msg); }
    void                 addWarning(int code, const char *msg = 0)
                         { getLockedErrorManager()->
                             addWarning(LOP_OPTYPE_NAME, code, msg); }
    void                 addMessage(int code, const char *msg = 0)
                         { getLockedErrorManager()->
                             addMessage(LOP_OPTYPE_NAME, code, msg); }

    const char          *inputLabel(OP_InputIdx idx) const override;
    const char          *outputLabel(OP_OutputIdx idx) const override;

    void                 fillInfoTreeNodeSpecific(UT_InfoTree &tree,
                                const OP_NodeInfoTreeParms &parms) override;

    // Guide geometry for display in the viewport, but which does not appear
    // in the USD stage anywhere.
    virtual int          getNumGuides() const;
    virtual const char  *getGuideColorName(int idx) const;
    GU_DetailHandle      cookGuide(int idx, OP_Context &context);
    
    // For transforming between LOP and OBJ spaces.
    int                 getRelativeTransform(OP_Node &to, 
                                UT_Matrix4 &xform,
                                OP_Context &context) override;
    int                 getRelativeTransform(OP_Node &to, 
                                UT_DMatrix4 &xform,
                                OP_Context &context)  override;

    // Extracting camera info directly from a LOP stage.
    bool                getCameraInfo(const UT_StringRef &camid,
                                const OP_Context &context,
                                DEP_MicroNode *depnode,
                                UT_StringHolder &foundcamid,
                                UT_CameraParms &camparms) override;
    bool                getWorldTransformFromData(const UT_StringRef &id,
                                const OP_Context &context,
                                bool get_inverse_xform,
                                DEP_MicroNode *depnode,
                                UT_DMatrix4 &xform) override;

    // Called on any parm that gets evaluated while in getAttributeParmSet.
    virtual void         handleParmEvaluatedForParmSet(PRM_Parm *parm);

    // For C++ nodes that want to support multiple outputs, override this
    // method to return true. The output index will be supplied to the cook
    // method as a context option.
    virtual bool         supportMultipleOutputsAsContextOption() const;

    // Returns the name of the context option into which we put the "output
    // index" to cook for a node that returns true from
    // supportMultipleOutputsAsContextOption.
    static const UT_StringHolder &getOutputIndexContextOption();

protected:
             LOP_Node(OP_Network *parent, const char *name,
                       OP_Operator *entry);
            ~LOP_Node() override;

    // Common cook method for all LOP nodes. Calls cookMyLop.
    OP_ERROR             cookMe(OP_Context &context) override;
    // Specific cook method for each LOP node, must be overridden.
    virtual OP_ERROR     cookMyLop(OP_Context &context) = 0;
    // Specific guide cook method for each LOP node.
    virtual GU_DetailHandle cookMyGuide(int idx, OP_Context &context);
    // Clears any cached data for this node. In the case of a LOP node, this
    // means clearing our locked stage pointer from the GusdStageCache.
    void                 clearCache() override;
    // Makes our own data handle reference or copy the data handle of another
    // node. Should be used to reference nodes that are not inputs to this
    // node.
    OP_ERROR             cookReferenceNode(OP_Context &context,
                                LOP_Node *source_lop,
                                int outidx = 0,
                                bool copy_data_handle = false,
                                bool add_extra_input = true,
                                const HUSD_LoadMasksPtr &load_masks =
                                    HUSD_LoadMasksPtr());
    // Makes our own data handle reference or copy the data handle of one
    // of our input nodes.
    OP_ERROR             cookReferenceInput(OP_Context &context,
                                int which_input = 0,
                                bool require_input = false,
                                bool copy_data_handle = false,
                                const HUSD_LoadMasksPtr &load_masks =
                                    HUSD_LoadMasksPtr());
    // Wrapper to call copyReferenceInput with the copy_data_handle
    // parameter set to true.
    OP_ERROR             cookModifyInput(OP_Context &context,
                                int which_input = 0,
                                bool require_input = false,
                                const HUSD_LoadMasksPtr &load_masks =
                                    HUSD_LoadMasksPtr());
    // Makes our own data handle reference or copy the data handle of another
    // node, but replace one layer in the source stage with another layer.
    // Should be used to reference nodes that are not inputs to this
    // node.
    OP_ERROR             cookReferenceNodeWithReplacement(OP_Context &context,
                                LOP_Node *source_lop,
                                const UT_StringRef &from_path_pattern,
                                const LOP_LayerReplacementInfo &replacement_info,
                                UT_StringSet &replaced_layers,
                                bool add_extra_input);
    // Makes our own data handle reference or copy the data handle of one
    // of our input nodes, but replace one layer in the source stage with
    // another layer.
    OP_ERROR             cookReferenceInputWithReplacement(OP_Context &context,
                                const UT_StringRef &from_path_pattern,
                                const LOP_LayerReplacementInfo &replacement_info,
                                UT_StringSet &replaced_layers,
                                int which_input,
                                bool require_input);
    // Access the data handle of one of our inputs, that must have been
    // locked already to ensure the data is cooked for the current context.
    const HUSD_DataHandle &lockedInputData(OP_Context &context,
                                int which_input);
    // Access our own data handle for modification. Should only be called
    // from within cookMyLop.
    HUSD_DataHandle     &editableDataHandle();

    // For subnet nodes, this method will return the contained node that
    // corresponds to specified output connector index. For all other nodes
    // with will return nullptr. This will trigger a call to syncDelayedOTL
    // if outidx > 0.
    LOP_Node            *getNodeForSubnetOutput(int outidx);

    // For nodes with editable input names, this function evaluates all the
    // input names, assigning any dependencies to the specified parameter.
    OP_ERROR             getInputStrings(const UT_StringRef &key_parm_name,
                                fpreal t,
                                UT_StringArray &input_names,
                                bool allow_empty_strings = false);

    // Functions for controlling checkpoints created during a cook operation.
    void                 setClearCheckpointsOnInputChange(bool clear);
    void                 createCheckpoint(const HUSD_AutoAnyLock &lock,
                                const UT_StringHolder &id);
    void                 removeCheckpoint(const UT_StringRef &id);
    void                 removeAllCheckpoints();

    // Functions for accessing existing checkpoitns during a cook operation.
    void                 getAvailableCheckpoints(UT_StringArray &ids) const;
    bool                 restoreCheckpoint(const HUSD_AutoLayerLock &layerlock,
                                const UT_StringRef &id);

    OP_ERROR             bypassMe(OP_Context &context,
                                int &copied_input) override;
    void                 deleteCookedData() override;
    int                  saveCookedData(const char *, OP_Context &) override;
    int                  saveCookedData(std::ostream &os, OP_Context &,
                                int binary = 0) override;
    const char          *getFileExtension(int bin) const override;

    // Specifically fills in the ramp attribute names from the spare tags on
    // a parameter. Used by getAttributeParmSet, but can be called separately
    // from that function for blocking attributes for a ramp parameter.
    static void          getRampAttributeNamesForParmSet(
                                const PRM_Template *tplate,
                                LOP_AttributeParmSet &pset);
    // Populates a LOP_AttributeParmSet data structure from a parameter, using
    // all the USD-specific information in the parameter's spare tags.
    void                 getAttributeParmSet(OP_Node *node,
                                const PRM_Template *tplate,
                                LOP_AttributeParmSet &pset,
                                fpreal t);
    // Applies any API schema mentioned in the LOP_AttributeParmSet. This
    // method can be called in a change block before calling
    // setAttributeFromParmSet for a bunch of LOP_AttributeParmSets.
    // Applying the schemas first in a change block can greatly reduce the
    // amount of recomposition done as a result of adding an API schema to
    // a large number of primitives.
    bool                 applySchemaFromParmSet(
                                HUSD_AutoWriteLock &writelock,
                                LOP_AttributeParmSet &pset,
                                UT_StringSet *failedapis = nullptr);
    // Sets a USD attribute or relationship on a USD primitive based on the
    // current value of a node parameter. Use getAttributeParmSet to populate
    // the LOP_AttributeParmSet data structure from the parm first.
    bool                 setAttributeFromParmSet(
                                HUSD_AutoWriteLock &writelock,
                                LOP_AttributeParmSet &pset,
                                fpreal t,
                                UT_StringSet *failedapis = nullptr);

    // Helps with convex hull generation by looking at the context option
    // stack information implemented by the virtual contextOptionsStackEffect.
    void                 encloseInputs(OP_EnclosedItems &items,
                                int stackdepth) const;

    // Map of attribute names to evaluator objects.
    UT_StringMap<UT_UniquePtr<UT_AttributeEvaluator> > myEvaluators;
    int                  myEvaluatingInputNameIndex;

    // Helper class to determine whether nodes with multiple inputs will be
    // composing stages with differing time-codes-per-second (TCPS) metadata.
    //
    // As of USD 20.08, if you reference/sublayer (i.e., compose) a 60tcps stage
    // into a 24tcps stage (for example), any time sample data within will be
    // automatically time-scaled (1.0 -> 0.4, ..., 60.0 -> 24.0, etc).
    //
    // If the data for the stage is driven by Houdini expressions/keyframes and
    // not by cached time samples, this time-scaling is not applied, which might
    // be unexpected for the user. This class can help warn them.
    //
    // Expected usage in `cookMyLop()`:
    // - sometime after `cookModifyInput(context);`, instantiate a checker:
    //   `DifferingTimeCodesPerSecChecker tcpsChecker(this);`
    // - whenever you first get your secondary inputs via
    //   `const HUSD_DataHandle &datahandle = lockedInputData(context, i);`,
    //   add this data handle to the checker:
    //   `tcpsChecker.addInput(datahandle, context);`
    // - whenever you first get your primary input via
    //   `const HUSD_DataHandle &datahandle = editableDataHandle();`
    //   also add this data handle to the checker, with `false`:
    //   `tcpsChecker.addInput(datahandle, context, false);`
    // - after all the inputs (primary & secondary) have been added to the
    //   checker, check to see if there's an issue:
    //   `tcpsChecker.checkForDifferingTCPS();`
    //
    class DifferingTimeCodesPerSecChecker
    {
    public:
        explicit DifferingTimeCodesPerSecChecker(LOP_Node *lop) : myLop(lop) {}
        void addInput(
                const HUSD_DataHandle &handle,
                OP_Context &context,
                bool onlyTimeDep = true);
        // Returns `true` if there are differing values; `false` otherwise
        bool checkForDifferingTCPS(bool emitWarning = true);

    private:
        LOP_Node *myLop;
        std::set<fpreal64> myTCPSEntries;
    };

private:
    // Resolves a node path pointing to a LOP node into an HUSD_LockedStagePtr.
    // This is used by husdLopStageResolver in HUSD_Utils.C to help the
    // GusdStageCache convert "op:/" USD file names into a stage generated
    // by a LOP node.
    static HUSD_LockedStagePtr resolveStage(const UT_StringRef &path);

    // Helper function used by cookReferenceNodeWithReplacement methods.
    OP_ERROR             copyDataWithReplacement(
                                HUSD_DataHandle &data_handle,
                                const UT_StringRef &from_path_pattern,
                                const LOP_LayerReplacementInfo &replacement_info,
                                UT_StringSet &replaced_layers);
      void               setDebugDirtyRecursive(
                                void *change_data, bool top_level);
    void                 resetDataHandle();

    HUSD_DataHandle      myDataHandle;
    LOP_LayerCheckpoints myCheckpoints;
    HUSD_PathSet         myLastModifiedPrims;
    bool                 myLastCookActivation;
    bool                 myHasActivationParameter;
    bool                 myHasShotActivationParameter;
};

#endif