PDG_ApplicationShim.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.
 *
 * COMMENTS:
 */

#ifndef __PDG_APPLICATION_SHIM_H__
#define __PDG_APPLICATION_SHIM_H__

#include "PDG_API.h"

#include "PDG_EvaluationContext.h"
#include "PDG_NodeTypes.h"

#include <UT/UT_ConcurrentQueue.h>
#include <UT/UT_NonCopyable.h>
#include <UT/UT_SharedPtr.h>
#include <UT/UT_StringHolder.h>

#include <SYS/SYS_Types.h>

class PDG_FileUtils;
class PDG_GraphContext;
class PDG_Node;
class PDG_Port;
class PDG_WorkItem;

struct PDGE_EvaluationOptions;

class UT_WorkBuffer;

/**
 * Shim class for integrating PDG with another application, e.g. Houdini. A
 * single subclass of this should be installed statically with PDG using
 * PDG_ApplicationShim::setShim.
 */
class PDG_API PDG_ApplicationShim : UT_NonCopyable
{
public:
    /**
     * Geometry class for binding a PDG geometry attribute to an application-
     * specific geometry object
     */
    class PDG_API Geometry
    {
    public:
                                Geometry() {}
        virtual                 ~Geometry() {}
                                UT_NON_COPYABLE(Geometry)

        /// Returns the memory usage of the geometry
        virtual int64           getMemoryUsage(bool inclusive) const = 0;

        /// Clones the object into a new instance
        virtual Geometry*       copy() const = 0;

        /// Returns a brief description of the geometry, for UI display
        virtual UT_StringHolder desc() const = 0;
    };

    /**
     * Node class for binding a PDG node to an application-specific node, such
     * as a TOP node.
     */
    class PDG_API Node
    {
    public:
                                Node() {}
        virtual                 ~Node() {}
                                UT_NON_COPYABLE(Node)

        /// Returns the icon name of the application specific node
        virtual UT_StringHolder iconName() const = 0;

        /// Returns a unique id for the application specific node
        virtual PDG_NodeID      nodeID() const = 0;

        /// Returns true if the app node has cooked at least once, using its
        /// own definition of cooked
        virtual bool            hasCooked() const = 0;

        /// Pushes the application specific node as a the active node, for the
        /// specified thread
        virtual bool            push(int thread) = 0;
        
        /// Pops the application specific active node
        virtual bool            pop(int thread) = 0;


        /// Evaluates an integer parameter on the node
        virtual bool            parmEval(const PDG_Port* port,
                                         const PDG_WorkItem* work_item,
                                         int index,
                                         exint& result,
                                         int thread,
                                         UT_WorkBuffer& errors) const = 0;
 
        /// Evaluates a float parameter on the node
        virtual bool            parmEval(const PDG_Port* port,
                                         const PDG_WorkItem* work_item,
                                         int index,
                                         fpreal& result,
                                         int thread,
                                         UT_WorkBuffer& errors) const = 0;

        /// Evaluates a string parameter on the node
        virtual bool            parmEval(const PDG_Port* port,
                                         const PDG_WorkItem* work_item,
                                         int index,
                                         bool expand,
                                         UT_StringHolder& result,
                                         int thread,
                                         UT_WorkBuffer& errors) const = 0;

        /// Returns the path to the node
        virtual void            path(UT_WorkBuffer& buffer) const = 0;

        /// Expands variables in the string, potentially using local variables
        /// or logic specific to the app node with respect to the specified
        /// parameter.
        virtual UT_StringHolder expandString(
                                    const PDG_Port* port,
                                    const PDG_WorkItem* work_item,
                                    const char* str,
                                    int thread) const = 0;
    };

    /**
     * Graph class for binding a PDG node to an application-specific graph, such
     * as a TOP parent.
     */
    class PDG_API Graph
    {
    public:
                                Graph() {}
        virtual                 ~Graph() {}
                                UT_NON_COPYABLE(Graph)

        /// Called when a graph cook begins
        virtual void            startCook(const PDGE_EvaluationOptions&) = 0;

        /// Called when a graph cook should update progress. Returns true if
        /// a blocking cook should cancel.
        virtual bool            tickCook(const PDGE_EvaluationOptions&) = 0;

        /// Called when a graph cook completes
        virtual void            stopCook(
                                    const PDGE_EvaluationOptions&,
                                    bool canceled) = 0;

        /// Called to determine the default label for a work item
        virtual bool            defaultWorkItemLabel(
                                    UT_StringHolder& label) const = 0;
    };

    /**
     * Base class for a task that can be queued. Should be subclassed to
     * implement a concrete task type that stores data and logic.
     */
    class PDG_API DeferredTask : UT_NonCopyable
    {
    public:
                            DeferredTask(
                                PDG_GraphContext* context,
                                const PDG_Node* node,
                                const PDG_WorkItem* work_item,
                                PDG_EvaluationContext::State state);
        virtual             ~DeferredTask() {} 

        /// Evaluates the task
        void                execute();

        /// Waits for the task to execute. Returns true if the task completed,
        /// or false if it was interupted for some reason.
        bool                wait();

    protected:
        /// Called when the task is evaluated
        virtual void        evaluate() = 0;

    protected:
        PDG_GraphContext*   myContext;
        const PDG_Node*     myNode;
        const PDG_WorkItem* myWorkItem;

        PDG_EvaluationContext::State
                            myState;
        int                 myCookId;
        bool                myHasExecuted;
    };

    /// Managed pointer to a deferred task
    using TaskPtr           = UT_SharedPtr<DeferredTask>;
    using DeferredQueue     = UT_ConcurrentQueue<TaskPtr>;

public:
    /// Adds a new Python search path to the PDG type system
    static void     addPythonPath(const UT_StringHolder& path);

    /// Returns true if the integration is allowed to use farm schedulers
    static bool     canUseFarm();

    /// Returns true if the application-specific work item dependency  is
    /// dirty
    static bool     areDependenciesDirty(fpreal t);

    /// Notifies the application that the global PDG work item has been changed
    static void     dirtyDependencies(fpreal t, const UT_StringHolder& name);

    /// Adds a dependency on the global PDG work item for the specified thread
    static void     addDependency(int thread, const UT_StringHolder& name);

    /// Queries the name of the evaluating channel for the specified thread
    static bool     evaluatingChannel(UT_WorkBuffer& buffer,
                                      bool full_path,
                                      int thread);

    /// Queries the value of a global variable
    static bool     getVariable(const char* name, UT_StringHolder& value);

    /// Sets the value of a global variable
    static void     setVariable(const char* name, const UT_StringHolder& value);

    /// Returns true if the file in the specified path is cached
    static bool     checkCached(const PDG_FileUtils& file_utils,
                                const UT_StringHolder& path,
                                const UT_StringHolder& tag);

    /// Queue a task with the deferred processing queue, to be run on the 
    /// main thread.
    template <typename Task, typename... Args>
    static TaskPtr  pushDeferred(Args&&... args)
                        {
                            TaskPtr new_task = UTmakeShared<Task>(
                                std::forward<Args>(args)...);
                            pushDeferredTask(new_task);
                            return new_task;
                        }

    /// Runs a functor with the application unlocked.
    template <typename Func>
    static void     unlockedExecute(const Func& func)
                        {
                            bool did_unlock = false;
                            if (theAppShim)
                                did_unlock = theAppShim->unlockApp();

                            func();

                            if (did_unlock)
                                theAppShim->lockApp();
                        }

    /// Runs the application shims logic for a main thread event tick. The
    /// base application instance will drain pending deferred events from the
    /// queue and run some of them.
    static bool     tickMainThread();

    /// Enable experimental features
    static bool     isExperimental();

    /// Saves the current application scene. Returns false if the application
    /// wants to abort the current operationi because of save conflict or a
    /// request to cancel, otherwise returns true.
    static bool     trySaveScene();

    /// Sets the shared static shim instance. This can only be called once
    /// during the lifetime of the program.
    static void     setShim(PDG_ApplicationShim* shim);

    /// Constructs a new application shim and caches configuration vars
                    PDG_ApplicationShim();
    virtual         ~PDG_ApplicationShim() {}

protected:
    virtual void    addAppPythonPath(const UT_StringHolder& path) const = 0;

    virtual bool    canAppUseFarm() const = 0;
    virtual bool    areAppDependenciesDirty(fpreal t) const = 0;
    virtual void    dirtyAppDependencies(fpreal t,
                                         const UT_StringHolder& name) = 0;
    virtual void    addAppDependency(int thread,
                                     const UT_StringHolder& name) = 0;
    virtual bool    evaluatingAppChannel(UT_WorkBuffer& buffer,
                                         bool full_path,
                                         int thread) = 0;
    virtual bool    getAppVariable(const char* name,
                                   UT_StringHolder& value) const = 0;
    virtual void    setAppVariable(const char* name,
                                   const UT_StringHolder& value) = 0;
    virtual bool    checkAppCached(const PDG_FileUtils& file_utils,
                                   const UT_StringHolder& path,
                                   const UT_StringHolder& tag) const = 0;
    virtual bool    tickAppMainThread();

    virtual bool    unlockApp() const = 0;
    virtual bool    lockApp() const = 0;

    virtual bool    trySaveAppScene() const = 0;

private:
    static void     pushDeferredTask(TaskPtr& ptr);

private:
    static PDG_ApplicationShim* theAppShim;

    DeferredQueue           myDeferredTasks;
    bool                    myIsExperimental;
};

#endif