DAGs and ImGui node graphs research

2026-06-28 13:51:16 +01:00
parent 2f837048d0
commit 832b60356b
2 changed files with 396 additions and 0 deletions
@@ -0,0 +1,184 @@
+# DAGs for Node-Based Compositing
+
+## What is a DAG?
+
+A **Directed Acyclic Graph (DAG)** is a graph where:
+
+- **Directed** — every edge has a direction (A → B means "A feeds into B")
+- **Acyclic** — no path forms a cycle; you cannot loop back to a node you've already visited
+
+In compositing, nodes are the vertices and image/data flow defines the edges. A **Read** node feeds into a **Blur** node, which feeds into a **Merge** node, etc.
+
+## Why DAGs for Compositing
+
+| Property | Benefit |
+|---|---|
+| Non-linear | Any node can be tweaked without rebuilding the whole comp |
+| Dependency-driven | Only re-evaluate nodes whose inputs changed ("dirty propagation") |
+| Parallelism | Independent branches can run concurrently |
+| Modular | Nodes are self-contained; easy to add new types |
+
+### Real-world examples
+
+- **Nuke** (Foundry) — the industry standard; everything is a DAG
+- **Fusion** (Blackmagic) — same concept, node graph as the primary interface
+- **Blender Compositor** — uses a dependency graph internally
+- **Shadertoy / MaterialX** — similar DAG concepts for shader/node graphs
+
+## Core Algorithms
+
+**BFS** (Breadth-First Search) explores a graph level by level — you visit all neighbours of a node before moving to their neighbours. Useful for shortest paths and spreading outward.
+
+**DFS** (Depth-First Search) goes deep first — you follow one path as far as it goes, then backtrack. Useful for cycle detection, pathfinding, and topological sort.
+
+### Topological Sort
+
+A **topological ordering** of a DAG is a linear sequence of all vertices such that for every edge u → v, u appears before v. This is the evaluation order for a node graph — you must process a node's inputs before processing the node itself.
+
+There are two standard approaches, one based on each traversal strategy:
+
+### 1. Kahn's Algorithm (BFS-based)
+
+Uses **in-degree** (number of incoming edges) to determine which nodes are ready to execute.
+
+```
+1. Compute in-degree for every node
+2. Queue all nodes with in-degree == 0 (no dependencies)
+3. While queue is not empty:
+   a. Dequeue node n, add to result order
+   b. For each downstream node m of n:
+      - Decrement m's in-degree
+      - If m's in-degree reaches 0, enqueue m
+4. If result count != node count → there is a cycle
+```
+
+**Why Kahn's for compositing:**
+- Naturally detects cycles (a graph editor must prevent the user from creating cycles)
+- Gives you ready-to-evaluate layers (all in-degree-0 nodes at a given step can run in parallel)
+- O(V + E) time, O(V) space
+- Easy to implement with arrays
+
+### 2. DFS-based (Post-order)
+
+```
+1. For each unvisited node, run DFS
+2. After visiting all descendants of a node, prepend it to the result
+```
+
+Simpler to code but less practical for incremental / parallel evaluation. Used more for DAG verification in build systems.
+
+## Data Structures for a DAG
+
+### Adjacency List (recommended for Prism)
+
+Store the graph as two flat arrays:
+
+```c
+// Node i's outgoing edges are adjacency[i] .. adjacency[i + 1]
+u32 *adjacency;       // flat list of edge destinations
+u32 *adjacency_begin; // start index into adjacency for each node
+u32  node_count;
+u32  edge_count;
+```
+
+Or simpler: each node stores its outputs:
+
+```c
+typedef struct PrNode PrNode;
+struct PrNode {
+    u32          id;
+    PrNodeType   type;
+    u32          input_count;     // number of inputs (incoming edges)
+    u32          input_nodes[4];  // fixed-size or pointer to array
+    u32          output_count;    // number of downstream nodes
+    u32         *output_nodes;    // allocated with arena
+    // ... data for this node type
+};
+```
+
+For a **data-oriented** approach in hot paths (graph evaluation), pack fields into parallel arrays:
+
+```c
+// SoA layout for evaluation
+u8          *node_types;     // PrNodeType for each node
+u32         *in_degrees;     // current in-degree (Kahn's state)
+u32         *topo_order;     // result of topological sort
+```
+
+### Struct-of-Arrays (SoA) Layout
+
+For the graph evaluation hot path, you can use parallel arrays instead of an array of structs:
+
+```c
+struct PrGraphEvalState {
+    u32   node_count;
+    u32  *topo_order;        // [0..node_count-1] in eval order
+    u32  *in_degrees;        // temp space for Kahn's
+    u8   *dirty_flags;       // per-node dirty bit
+    u32  *output_counts;
+    u32 **output_lists;      // adjacency
+};
+```
+
+This keeps only the data needed for traversal in cache-friendly contiguous memory.
+
+## Incremental / Dirty Evaluation
+
+For interactive use, re-running the full topological sort every frame is wasteful. Instead:
+
+1. When a node's parameter changes, mark it **dirty**
+2. Propagate the dirty flag downstream (BFS along edges)
+3. Only re-evaluate dirty nodes in topological order
+
+Alternatively, skip dirty propagation and just always eval in topo order — each node checks if its inputs are dirty or if its own parameters changed. Simpler, but does more work.
+
+## Cycles in a Graph Editor
+
+A graph editor must **prevent** the user from creating cycles in real time. Approaches:
+
+1. **Check on each edge creation:** before adding edge A → B, check if there's already a path from B to A (DFS from B). O(V + E) per edge add.
+2. **Incremental cycle detection:** more sophisticated data structures for dynamic graphs. Probably overkill for V1.
+3. **Kahn's validation:** Run Kahn's after every edit; if it doesn't produce a full ordering, reject the edit.
+
+Approach 1 (DFS reachability test) is the simplest for V1.
+
+## Evaluation Pipeline
+
+```
+User edits graph
+        │
+        ▼
+Validate no cycles  ← (reject edit if cycle detected)
+        │
+        ▼
+Topological sort    ← (Kahn's algorithm → list of node IDs)
+        │
+        ▼
+Mark dirty nodes    ← (only nodes downstream of changes)
+        │
+        ▼
+For each node in topo order:
+    If node is dirty:
+        Gather input images (from upstream node outputs)
+        Execute node (CPU or dispatch GPU shader)
+        Store output image
+        │
+        ▼
+Render final output → display
+```
+
+## Key Takeaways for Prism
+
+1. **Kahn's algorithm** is the right choice — simple, O(V+E), built-in cycle detection, parallel-layer grouping
+2. **Adjacency list** with flat arrays for the graph structure
+3. **Evaluate in topological order**; skip clean nodes for efficiency
+4. **Cycle check on edge creation** via DFS from the target node
+5. **SoA layout** for evaluation state if profiling shows cache misses on the hot path
+6. Node types (Read, Blur, Merge, etc.) can use a `PrNodeType` enum with a function dispatch table, or a union of type-specific data in the node struct
+
+## References
+
+- Kahn, A. B. (1962). "Topological sorting of large networks." *Communications of the ACM*
+- Cormen et al., *Introduction to Algorithms*, 3rd ed., Ch. 22.4 (Topological Sort)
+- Foundry Nuke documentation: [https://learn.foundry.com/nuke](https://learn.foundry.com/nuke)
+- Taskflow C++ library: [https://taskflow.github.io](https://taskflow.github.io)
@@ -0,0 +1,212 @@
+# Node Graph UI with DearImGui — Research
+
+## Overview
+
+Three main approaches exist for building a node graph UI with DearImGui:
+1. Use a standalone library like **ImNodes** or **imgui-node-editor**
+2. Build from scratch using ImGui's draw list API
+3. Use a hybrid — custom canvas with ImGui widgets
+
+---
+
+## 1. Existing Libraries
+
+### 1.1 imnodes (Nelarius)
+
+- **Stars**: ~2.4k | **License**: MIT | **Status**: Active (last push 2024)
+- **Files**: `imnodes.h`, `imnodes_internal.h`, `imnodes.cpp` — drop-in, no deps beyond ImGui
+- **API style**: Immediate-mode, mirrors ImGui idioms
+
+```cpp
+imnodes::BeginNodeEditor();
+imnodes::BeginNode(node_id);
+imnodes::BeginNodeTitleBar();
+ImGui::Text("Node Name");
+imnodes::EndNodeTitleBar();
+imnodes::BeginInputAttribute(pin_id);
+ImGui::Text("input");
+imnodes::EndAttribute();
+imnodes::BeginOutputAttribute(pin_id);
+ImGui::Text("output");
+imnodes::EndAttribute();
+imnodes::EndNode();
+imnodes::EndNodeEditor();
+```
+
+**Strengths:**
+- Minimal, dependency-free, easy to vendor
+- True immediate-mode — user owns all state
+- Pins auto-align with embedded ImGui widgets
+- Simple `ImNodes::Link(id, from, to)` API
+
+**Weaknesses:**
+- Less feature-rich (no built-in minimap, no grouping, limited theming)
+- No built-in serialization of layout
+- Slower development velocity
+
+**Under the hood:**
+- Uses `ImDrawList::ChannelsSplit()` to layer node backgrounds behind UI
+- Pins are detected via `ImGui::BeginGroup` bounding box capture
+- Link picking uses hierarchical bezier subdivision
+
+### 1.2 imgui-node-editor (thedmd / Michal Cichon)
+
+- **Stars**: ~4.4k | **License**: MIT | **Status**: Active
+- **Files**: `imgui_node_editor.h/.cpp` + `imgui_canvas.h/.cpp` — also drop-in
+- **API style**: retained-state editor context, user draws content
+
+```cpp
+ax::NodeEditor::Begin("Editor");
+ax::NodeEditor::BeginNode(node_id);
+ax::NodeEditor::BeginPin(pin_id, ax::NodeEditor::PinKind::Input);
+ImGui::Text("input");
+ax::NodeEditor::EndPin();
+ax::NodeEditor::EndNode();
+ax::NodeEditor::End();
+```
+
+**Strengths:**
+- Rich feature set: zoom/pan, minimap, selection, context menus, copy/paste
+- Blueprint-UE4-inspired default theme
+- Bézier curve links with flow animation
+- Configurable zoom levels, drag/navigate/select button mapping
+- `ImGuiEx::Canvas` can be used independently for custom infinite-workspace UIs
+- Built-in serialization callbacks (`SaveSettings`/`LoadSettings`)
+
+**Weaknesses:**
+- Heavier than imnodes — more code, larger API surface
+- Editor context is a retained object (less "pure" immediate mode)
+- Can conflict with ImGui's own ID stack during complex widget embedding
+
+**Key API patterns:**
+
+| Concern | API |
+|---|---|
+| Create link | `BeginCreate()` / `QueryNewLink()` / `AcceptNewItem()` / `EndCreate()` |
+| Delete | `BeginDelete()` / `QueryDeletedLink()` / `AcceptDeletedItem()` / `EndDelete()` |
+| Suspend for popups | `Suspend()` / `Resume()` — pops out of canvas coordinate space |
+| Styling | `PushStyleColor()` / `PushStyleVar()` — 20+ style variables |
+
+### 1.3 ImNodeFlow (Fattorino)
+
+- **Stars**: Newer (2024–2025) | **License**: MIT
+- Even more feature-packed: node categories, commenting, layout algorithms
+- Still maturing; less battle-tested than the two above
+
+> **Recommendation for Prism**: start with **imgui-node-editor** if we want a polished editor quickly, or **imnodes** if we want minimal deps and full state control. The custom approach (next section) is best if we have very specific rendering needs.
+
+---
+
+## 2. Custom Node Graph from Scratch
+
+Building a node graph manually using `ImDrawList` gives maximum control but requires handling:
+
+### 2.1 Canvas / Coordinate System
+
+An infinite-zoom canvas requires:
+- An offset (`ImVec2`) and scale (`float`) transform
+- Conversion functions between screen ↔ canvas space
+- Clipping to the parent ImGui window
+
+The `imgui-node-editor` library includes an `ImGuiEx::Canvas` utility that handles this standalone — it can be extracted and reused.
+
+### 2.2 Rendering Nodes (DrawList)
+
+Nodes are typically rendered in layers:
+1. **Background layer**: grid dots/lines, selection rectangle
+2. **Node bodies**: rounded rectangles (`AddRectFilled`)
+3. **Node borders**: rect strokes, optionally thicker on hover/select
+4. **Pins**: small circles or squares on left/right edges
+5. **Links**: cubic Bézier curves between pin centers
+6. **UI overlay**: selection handles, context menus
+
+Use `ImDrawList::ChannelsSplit()` for correct z-ordering when mixing drawn shapes with ImGui widgets.
+
+### 2.3 Interaction Handling
+
+| Interaction | Implementation |
+|---|---|
+| Pan | Track middle-mouse drag → modify canvas offset |
+| Zoom | Mouse wheel → modify scale (clamp to range, center on cursor) |
+| Drag node | Hit-test node bodies (invis buttons or rect test), track delta → update node position |
+| Select | Rectangular marquee — track shift+drag → compute selection rect → test intersection with node rects |
+| Create link | Detect drag from pin, draw preview bezier, test against other pins on release |
+| Delete | Keyboard shortcut, query selection, or context menu |
+
+### 2.4 Link-Picking (Bezier Hit Test)
+
+Cubic Bézier curves require a hierarchical hit test:
+1. Subdivide curve into N segments
+2. Find segment closest to mouse cursor
+3. Recursively subdivide that segment
+4. Return hit if distance < threshold
+
+## 3. Architecture Patterns
+
+### 3.1 Data Model vs. View Separation
+
+From Guillaume Boissé's RogueEngine post:
+- Define a **data model** independent of UI: `PrNode`, `PrGraph`, `PrPin`
+- The data model is used both by the runtime (graph evaluation) and the editor (UI rendering)
+- This enables easy serialization, undo/redo, and multi-context editing
+
+### 3.2 Immediate-Mode Node Rendering Loop
+
+```
+For each node in graph:
+    BeginNode(node.id)
+        Render node title bar (colored rect + text)
+        For each input pin:
+            BeginInputPin(pin.id)
+            Render ImGui widget (e.g. DragFloat, ColorEdit)
+            EndInputPin()
+        For each output pin:
+            BeginOutputPin(pin.id)
+            Render ImGui widget
+            EndOutputPin()
+    EndNode()
+
+For each link in graph:
+    DrawBezierLink(from_pos, to_pos, color, thickness)
+```
+
+Positions are stored per-node in user state and updated on drag.
+
+### 3.3 DrawList Channels (Z-Order)
+
+```cpp
+draw_list->ChannelsSplit(3);
+draw_list->ChannelsSetCurrent(0); // Background: grid, selection rect
+// ... draw nodes, pins, links
+draw_list->ChannelsSetCurrent(1); // UI: ImGui widgets inside nodes
+// ... BeginNode/EndNode calls
+draw_list->ChannelsSetCurrent(2); // Foreground: tooltips, drag previews
+draw_list->ChannelsMerge();
+```
+
+### 3.4 Undo/Redo
+
+Simplest viable approach (from RogueEngine / @voxagonlabs): serialize the entire project state on every change. Store snapshots in an undo stack. Works well for small-to-medium projects (node graphs are typically small data).
+
+## 4. Summary Comparison
+
+| Criteria | imnodes | imgui-node-editor | Custom |
+|---|---|---|---|
+| Integration effort | Copy 3 files | Copy 6-8 files | Full implementation |
+| Feature depth | Basic | Rich (minimap, flow, groups, copy/paste) | Whatever you build |
+| Immediate mode | Yes | Partial (retained context) | Yes |
+| Performance | High | High | Depends on impl |
+| Styling control | Minimal | Extensive | Full control |
+| Serialization | None | Built-in callbacks | Build your own |
+| Community / maturity | Mature, stable | Mature, active | N/A |
+
+## 5. References
+
+- **imnodes**: https://github.com/Nelarius/imnodes
+- **imgui-node-editor**: https://github.com/thedmd/imgui-node-editor
+- **ImNodeFlow**: https://github.com/Fattorino/ImNodeFlow
+- **Blog post — Visual node graph with ImGui**: https://gboisse.github.io/posts/node-graph/
+- **Blog post — Writing imnodes**: https://nelari.us/post/imnodes
+- **ImGui issue #306** (node editor discussion): https://github.com/ocornut/imgui/issues/306
+- **ImGui useful extensions wiki**: https://github.com/ocornut/imgui/wiki/Useful-Extensions
+- **Voxagon undo/redo**: https://blog.voxagon.se/2018/07/10/undo-for-lazy-programmers.html