COP_ApexProgram.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.
 *
 */

#pragma once

#include "COP_API.h"

#include "COP_MicroNode.h"
#include "COP_Signature.h"

#include <IMX/IMX_Layer.h>
#include <IMX/IMX_VDB.h>
#include <IMX/IMX_Attribute.h>
#include <UT/UT_StringMap.h>

class COP_ApexNodeDependencies;
class COP_Block;
class COP_CableStructure;
class COP_GraphProxyDirect;
class COP_Node;
class COP_Request;
class GU_ConstDetailHandle;
class GU_Detail;
class GU_DetailHandle;
class OP_Context;
class UT_ErrorManager;
class UT_StringRef;

namespace apex
{
    class APEX_Graph;
};

/// This class creates an executable program out of a COP block. All parameters
/// are evaluated and hardened in the graph.
class COP_API COP_ApexProgram
{
public:
    enum class SlapCompBuildStatus
    {
        FAIL = 0,
        REBUILD_NOT_NEEDED,
        SUCCESS
    };

    /// This tag can be used with setOutputBlock() and buildFromBlock() methods
    /// to indicate what the block begin's input states are (i.e. which ports
    /// are actually connected).
    enum class BeginBindingsMode
    {
        /// Will assume all inputs are connected non-null data.
        ALL_INPUTS_BOUND,
        /// Will use the network's connections.
        NETWORK_STATE
    };

public:
    /// If harden_parms is true, the parameters will be evaluated and baked into
    /// the built graphs.
    COP_ApexProgram(bool harden_parms = true);
    ~COP_ApexProgram();

    /// Set the block end node for this program, without trying to rebuild.
    /// Returns false if output is a block begin node, in which case the output
    /// node (and the program as a whole) is unchanged. If sigs and input_cables
    /// are provided, they will be used as the authoritative state of inputs to
    /// the block (on the begin side); if one is given, the other must be as
    /// well. If these arguments are nullptr, then the built program will
    /// reflect state of the network.
    bool setOutputBlock(const COP_Block* output,
                        const UT_Array<COP_Signature>* sigs,
                        const UT_Array<COP_CableStructure>* input_cables);
    /// This version of the method assumes that all inputs to the block are
    /// properly bound non-null data when the program gets built.
    bool setOutputBlock(const COP_Block* output, BeginBindingsMode mode);
    /// Builds an executable out of the block end node, containing everything up
    /// to its begin node.
    bool buildFromBlock(const COP_Block* output,
                        const UT_Array<COP_Signature>* sigs,
                        const UT_Array<COP_CableStructure>* cables,
                        const OP_Context& context, UT_ErrorManager& error);
    /// This version of the method assumes that all inputs to the block are
    /// properly bound non-null data when the program gets built.
    bool buildFromBlock(const COP_Block* output, BeginBindingsMode mode,
                        const OP_Context& context, UT_ErrorManager& error);

    /// Builds a program that cooks the specified outputs of a single node. The
    /// node can be a subnetwork or an atomic node.
    bool buildFromSingleNode(COP_Node* output,
                             const UT_Array<COP_Request>& requests,
                             const COP_Signature& signature,
                             const OP_Context& context, UT_ErrorManager& error);

    /// Returns the cable structure of an output of the block this is built
    /// from. 
    COP_CableStructure getBlockOutputCableStructure(OP_OutputIdx port) const;

    /// Saves the graph as geometry.
    void saveToGeometry(GU_Detail* gdp) const;
    /// Loads a graph from geometry.
    bool loadFromGeometry(const GU_Detail* gdp);

    /// Saves the graph to a (geometry) file.
    bool saveToFile(const char* filename) const;
    /// Loads the graph from a geometry file.
    bool loadFromFile(const char* filename);

    /// Binds an input to the program.
    bool setInputLayer(const UT_StringRef& name,
                       const IMX_LayerConstPtr& layer);
    bool setInputGeometry(const UT_StringRef& name,
                          const GU_ConstDetailHandle& geo);
    bool setInputVDB(const UT_StringRef& name,
                       const IMX_VDBConstPtr& vdb);
    bool setInputAttribute(const UT_StringRef& name,
                       const IMX_AttributeConstPtr& attrib);
    /// If as_cable is true, all fields from the port are bound as inputs (based
    /// on the field names).
    bool setInput(const UT_StringRef& name, const COP_PortData& input,
                  bool as_cable = false);
    /// If as_cable is true, all inputs that match name.* are cleared.
    bool clearInput(const UT_StringRef& name, bool as_cable = false);
    
    /// Runs the program after the inputs have been bound.
    void runProgram(const OP_Context& context, UT_ErrorManager& error);

    /// Extracts results after the program has executed.
    IMX_LayerPtr getOutputLayer(const UT_StringRef& name) const;
    GU_ConstDetailHandle getOutputGeometry(const UT_StringRef& name) const;
    IMX_VDBPtr   getOutputVDB(const UT_StringRef& name) const;
    IMX_AttributePtr getOutputAttribute(const UT_StringRef& name) const;
    COP_PortData getOutput(const UT_StringRef& name) const;
    /// Extracts the port data for a single cable output of the given name. The
    /// incoming cable structure is assumed to be correct.
    COP_PortData getOutputCable(const UT_StringRef& name,
                                const COP_CableStructure& cable) const;

    /// Clears all the graph inputs, letting go of the held references.
    void clearInputs();

    /// clears all the graph outputs, letting go of the held references.
    void clearOutputs();

    /// Clears all the buffers internal to this, including inputs and outputs
    void clearBuffers();

    /// Returns a map of all COP inputs to the program. Key of an input is its
    /// name, while the value is its expected type in the program.
    const UT_StringMap<std::pair<COP_Type, bool>>& getProgramInputs() const
    {
        return myProgramInputs;
    }
    /// Returns a map of all COP outputs of the program. Key of an output is its
    /// name, while the value is its type in the program.
    const UT_StringMap<std::pair<COP_Type, UT_StringHolder>>&
        getProgramOutputs() const
    {
        return myProgramOutputs;
    }
    /// Returns type of the given output.
    COP_Type getOutputType(const UT_StringRef& output) const;
    
    /// Returns true if the input of the given name exists but is not used.
    bool isUnusedInput(const UT_StringRef& name) const;
    /// Returns true if the input of the given name exists and is used by the
    /// program. If as_cable is true, this program is scanned for inputs that
    /// match name.*.
    bool isUsedInput(const UT_StringRef& name, bool as_cable = false) const;

    /// Returns the micronode that captures all dependencies for the program.
    COP_MicroNodeWithCallback& getGraphDep()
    {
        return myGraphDep;
    }
    /// Returns the micronode that captures all dynamic runtime dependencies
    /// from the previous program execution.
    COP_MicroNodeWithCallback& getResultsDep()
    {
        return myResultsDep;
    }

    /// When enabled, the registered callback is invoked whenever the program's
    /// results become out of date.
    /// Note that the callback may be invoked more than once when the results
    /// are dirtied!!!
    void enableCallback(bool enable)
    {
        myGraphDep.enableCallback(enable);
        myResultsDep.enableCallback(enable);
    }
    /// Registers the callback that is to run when the program's results become
    /// out of date. Use enableCallback() to control whether or not the callback
    /// is forced to run. The data pointer is passed to the callback function
    /// when it executes.
    /// Note that the callback may be invoked more than once when the results
    /// are dirtied!!!
    void setCallback(void (*callback)(void*), void* data)
    {
        myGraphDep.setCallback(callback, data);
        myResultsDep.setCallback(callback, data);
        myErroredMonitor.setCallback(callback, data);
    }
    
    /// Rebuilds the APEX graph if necessary and returns one of the above status
    /// codes. If reset_deps is false, previous dependencies are retained; this
    /// should be used if running multiple iterations of a program, since the
    /// intent there is to accummulate all the dependencies across all runs.
    SlapCompBuildStatus rebuildIfNeeded(const OP_Context& context,
                                        UT_ErrorManager& error,
                                        bool reset_deps);

    /// Returns true if the user should bind input layers that have correct
    /// camera metadata. If this is false, then the input layers are expected to
    /// use the default transformation.
    bool expectsLayerCameras() const
    {
        return myExpectInputCameras;
    }

    /// Signature evaluation context override ID seen by this program.
    int getGraphProxyOverrideId() const;

    /// Returns the Block End node this program is built for; if the program was
    /// built for a single node, this returns nullptr.
    COP_Block                           *getOutputBlock() const;
    /// Returns the id of the node this program was built from, if it was built
    /// from a block or a single node.
    int                                  getOutputNodeId() const;
    /// Returns the node this program was built from, if it was built from a
    /// block or a single node, and if that node still exists.
    COP_Node                            *getOutputNode() const;
    /// Returns if this program is for a block that is registered for slap comp.
    bool                                 isOutputBlockSlapComp() const;

protected:
    /// What the program is built for.
    enum class BuildTarget
    {
        BLOCK,
        SINGLE_NODE,
        INVALID
    };

protected:
    /// Helper function to register dependencies on the signature and port names
    /// of the block nodes.
    void addBlockDeps(DEP_MicroNode& dep, COP_Block* begin, COP_Block* end);
    /// Sets the target output node for the program, possibly marking the graph
    /// dirty if it's different from a built program's.
    void setOutputNodeInternal(const COP_Node* output, BuildTarget target,
                               const UT_Array<COP_Signature>* sigs,
                               const UT_Array<COP_CableStructure>* cables,
                               const UT_Array<COP_Request>* requests);
    /// Returns this program's graph proxy, allocating it if it's not yet
    /// created.
    COP_GraphProxyDirect* getGraphProxy();

protected:
    UT_UniquePtr<apex::APEX_Graph>  myGraph;
    /// Map of all inputs used by the program.
    UT_StringMap<std::pair<COP_Type, bool>>
                                    myProgramInputs;
    /// Map of all inputs that are not used by the program. These are saved as
    /// they are part of the program's signature.
    UT_StringMap<std::pair<COP_Type, bool>>
                                    myUnusedInputs;
    UT_StringMap<std::pair<COP_Type, UT_StringHolder>>
                                    myProgramOutputs;
    /// Mapping of bound passthrough outputs (by their name) to the bound input
    /// that they correspond to.
    UT_StringMap<COP_PortData>      myPassthroughOutputs;
    int                             myOutputNodeId = -1;
    BuildTarget                     myBuildTarget = BuildTarget::INVALID;
    UT_Array<COP_Request>           myOutputRequests;

    // Marks us as invalid forcing a rebuild
    bool                            myForceRebuild = false;
    
    COP_MicroNodeWithCallback       myGraphDep;
    COP_MicroNodeWithCallback       myResultsDep;
    /// This micronode is used only when the build fails. It gets notified when
    /// a relevant node is rewired or changed.
    COP_MicroNodeWithCallback       myErroredMonitor;

    /// Contains all the dependency-tracking data for node parameters (if built
    /// from a node).
    UT_UniquePtr<COP_ApexNodeDependencies>
                                    myParameterDep;

    /// This program's graph proxy that might have registered overrides (if
    /// building from a node).
    UT_UniquePtr<COP_GraphProxyDirect>
                                    myGraphProxy;

    /// This flag controls how the graph is built from a node. If true, all
    /// parameters are evaluated and baked into the graph; otherwise, they're
    /// made into graph inputs.
    bool                            myHardenParameters;
    /// This flag indicates to the user whether they should place the input
    /// layers at the correct 3D locations or use default transforms.
    bool                            myExpectInputCameras = true;
};

// Not trivially movable because tbb::concurrent_vector
// DEP_MicroNode::myExplicitOutputs is not trivially movable
SYS_DECLARE_IS_NOT_TR(COP_ApexProgram)