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_Signature.h"

#include <DEP/DEP_TimedMicroNode.h>
#include <IMX/IMX_Layer.h>
#include <UT/UT_StringMap.h>

class COP_Block;
class GU_ConstDetailHandle;
class GU_Detail;
class GU_DetailHandle;
class OP_Context;
class UT_ErrorManager;
class UT_StringRef;

namespace apex
{
    class APEX_Graph;
};

/// This micronode can invoke a callback when it becomes dirty. It's used by
/// COP_ApexProgram's callback registration, to make sure a function runs when
/// the program's results are changed.
class COP_API COP_MicroNodeWithCallback : public DEP_TimedMicroNode
{
public:
    COP_MicroNodeWithCallback() :
        DEP_TimedMicroNode(), myCallback(nullptr), myEnabled(false)
    {
    }

    /// Controls whether or not the callback runs when the micronode is dirtied.
    void enableCallback(bool enable)
    {
        myEnabled = enable;
    }

    /// Returns true if the callback is enabled (even if not set).
    bool callbackEnabled() const
    {
        return myEnabled;
    }

    /// Set the callback to run when the micronode is dirtied. The callback will
    /// only be invoked if enableCallback(true) was previously called. The data
    /// pointer is passed to the callback function when it's executed.
    void setCallback(void (*callback)(void*), void* data)
    {
        myCallback = callback;
        myData = data;
    }

    void becameDirty(DEP_MicroNode& src, const DEP_PropagateData& propdata)
        override;

private:
    void                          (*myCallback)(void*);
    void*                           myData;
    bool                            myEnabled;
};

/// 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 SlapcompBuildStatus
    {
        FAIL = 0,
        REBUILD_NOT_NEEDED,
        SUCCESS
    };

public:
    COP_ApexProgram();
    ~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.
    bool setOutputNode(COP_Block* output);

    /// Builds an executable out of the block end node, containing everything up
    /// to its begin node.
    bool buildFromNode(COP_Block* output, const OP_Context& context,
                       UT_ErrorManager& error);

    /// 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 setInput(const UT_StringRef& name, const COP_PortData& input);
    
    /// 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_DetailHandle getOutputGeometry(const UT_StringRef& name) const;
    COP_PortData getOutput(const UT_StringRef& name) const;

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

    /// 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 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.
    bool isUsedInput(const UT_StringRef& name) const;

    /// Returns the micronode that captures all dependencies for the program.
    DEP_TimedMicroNode& getGraphDep()
    {
        return myGraphDep;
    }
    /// Returns the micronode that captures all dynamic runtime dependencies
    /// from the previous program execution.
    DEP_TimedMicroNode& 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.
    SlapcompBuildStatus rebuildIfNeeded(const OP_Context& context,
                                        UT_ErrorManager& error);

    /// 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;
    }

    /// Returns the Block End node this program is built for.
    COP_Block                           *getOutputNode() const;
    /// Returns if the block end is registered for a slapcomp
    bool                                 isOutputNodeSlapComp() const;

protected:
    void addBlockDeps(DEP_MicroNode& dep, COP_Block* begin, COP_Block* end);

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;
    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;

    /// 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;
};