[NodeExecute] is documented as the method that performs a node's work, but nothing in either library ever calls it. Raised while investigating #437.
What the docs say
ImGui.NodeEditor/README.md presents this as the example of a node built from attributes:
[Node("Add")]
public class AddNode
{
[InputPin("A")] public double A { get; set; }
[InputPin("B")] public double B { get; set; }
[OutputPin("Sum")] public double Sum { get; private set; }
[NodeExecute]
public void Execute() => Sum = A + B;
}NodeGraph/README.md is more direct still: "A node is an ordinary type with attributes. Inputs and outputs are properties; the work happens in the method marked [NodeExecute]." The attribute table lists it as "The method that performs the node's work".
What is there
NodeExecuteAttribute (NodeGraph/NodeBehaviorAttributes.cs:87) is a marker carrying Order and IsAsync. Nothing reads either. AttributeBasedNodeFactory does not scan for it, and NodeDefinition has no field for it. There is no evaluator, scheduler or dispatcher anywhere in ktsu.NodeGraph or ktsu.ImGui.NodeEditor, and no call site that would reach a node's method: a search for Activator.CreateInstance and .Invoke( across both projects returns nothing.
The same applies to [NodeValidate] and to the whole of [NodeBehavior]. ExecutionMode, SupportsAsyncExecution, IsDeterministic and IsCacheable are read off the attributes into NodeDefinition and then only ever displayed.
Why it matters
Both READMEs read as though registering a type gives you a graph that runs. It gives you a graph that draws. Someone evaluating the library for real work reasonably concludes that execution is included, and finds out otherwise only after building against it. That is what happened in #437.
The metadata is genuinely useful without an evaluator, and declaring intent that a host implements is a legitimate design. The problem is that nothing says so.
Options
- Document the boundary. Say plainly in both READMEs that
ktsu.NodeGraph is metadata and that executing a graph is the host's job, and change the AddNode example so it does not imply a call that never comes.
- Ship a reference evaluator, as a separate package so that
ktsu.ImGui.NodeEditor keeps its current weight.
These are not exclusive. Option 1 is worth doing whatever happens to option 2.
Related
[NodeExecute]is documented as the method that performs a node's work, but nothing in either library ever calls it. Raised while investigating #437.What the docs say
ImGui.NodeEditor/README.mdpresents this as the example of a node built from attributes:NodeGraph/README.mdis more direct still: "A node is an ordinary type with attributes. Inputs and outputs are properties; the work happens in the method marked[NodeExecute]." The attribute table lists it as "The method that performs the node's work".What is there
NodeExecuteAttribute(NodeGraph/NodeBehaviorAttributes.cs:87) is a marker carryingOrderandIsAsync. Nothing reads either.AttributeBasedNodeFactorydoes not scan for it, andNodeDefinitionhas no field for it. There is no evaluator, scheduler or dispatcher anywhere inktsu.NodeGraphorktsu.ImGui.NodeEditor, and no call site that would reach a node's method: a search forActivator.CreateInstanceand.Invoke(across both projects returns nothing.The same applies to
[NodeValidate]and to the whole of[NodeBehavior].ExecutionMode,SupportsAsyncExecution,IsDeterministicandIsCacheableare read off the attributes intoNodeDefinitionand then only ever displayed.Why it matters
Both READMEs read as though registering a type gives you a graph that runs. It gives you a graph that draws. Someone evaluating the library for real work reasonably concludes that execution is included, and finds out otherwise only after building against it. That is what happened in #437.
The metadata is genuinely useful without an evaluator, and declaring intent that a host implements is a legitimate design. The problem is that nothing says so.
Options
ktsu.NodeGraphis metadata and that executing a graph is the host's job, and change theAddNodeexample so it does not imply a call that never comes.ktsu.ImGui.NodeEditorkeeps its current weight.These are not exclusive. Option 1 is worth doing whatever happens to option 2.
Related