hanez/xtc
2
1
Fork 1
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Phase 4: Add modular graph editor and transactional graph edits

Browse source
This commit is contained in:
Johannes Findeisen 2026-10-26 23:55:35 +01:00
commit 5c41d7f6da
27 changed files with 1023 additions and 64 deletions
Download patch file Download diff file Expand all files Collapse all files

45
docs/GUI.md
View file

@ -20,10 +20,10 @@ not energyXT's exact artwork or proprietary resources.
## Phase 3 shell
The shell opens JACK on startup through `xtc_backend.h`. It never accesses
backend structures, processes samples, creates domain objects, or calls JACK
itself. All backend control calls run on the GUI thread; FLTK is never called
backend structures, processes samples, or calls JACK itself. Graph domain
data is owned by opaque C objects, manipulated only through the C API. All backend control calls run on the GUI thread; FLTK is never called
from an audio callback. No server is started and no audio ports are connected
by the GUI. With no graph submitted, the running backend produces silence.
by the GUI. The initially empty graph produces silence.
- **Play / F5:** start the engine. **Stop / F8:** deactivate it. **Space:** toggle.
These are engine controls, not timeline playback or transport positioning.
@ -32,7 +32,7 @@ by the GUI. With no graph submitted, the running backend produces silence.
the handle and reports the failure instead of opening another client.
- **View menu / Ctrl+1, Ctrl+2, Ctrl+3:** switch between sequencer, mixer and
modular graph. Tabs provide the same view switching. Editors remain clearly
labeled placeholders; no project editing is implied.
labeled placeholders for sequencer/mixer; Modular Graph is implemented below.
- **File / Quit / Ctrl+Q** or the window close button: close the backend and
synchronize audio callbacks before hiding/destroying widgets. A failed close
leaves the window open for a retry. Unsupported New/Open/Save actions are
@ -62,3 +62,40 @@ removal. `make test-gui-jack` additionally requires a running JACK-compatible
server, tests repeated start/stop, reconnect and active-client close, and creates
no routes. Physical playback is outside this shell. See BUILD.md and the
integration test README for sanitizer limitations and keyboard smoke results.
## Phase 4 modular editor
Open **Modular Graph** or press **Ctrl+3**. Add oscillator (440 Hz), gain (0.10),
pass-through meter or output nodes with the toolbar. Their parameters are fixed
presets in this milestone and are drawn on each node; parameter editing and
live meter display are not implemented. Connect oscillator → gain → meter →
output for a simple test chain. No sound reaches hardware until ports are
explicitly connected outside the GUI. Output nodes are required to render;
isolated sources and an empty graph produce silence.
Drag a node body/title to move it. Drag a circular output port to an input port
to connect. Click a node or wire to select it (yellow outline/wire), then press
Delete/Backspace or **Delete selection**. Deleting a node deletes its incident
wires. Escape cancels a drag preview. Canvas scrollbars pan the view; positions
are retained across edits/reconnect but not across application restart. There
is no zoom, multiselection, undo, project persistence or external routing UI yet.
The editor supports 64 nodes on a fixed 2000x4000 canvas.
Every semantic action becomes a C graph command. The window owns the graph
handle and publishes the C-created candidate through the backend. Cycle,
invalid-direction, duplicate connection, missing-port, capacity and backend
failures are shown below the canvas; failed edits leave the graph unchanged.
Capacity feedback distinguishes the possible node limit/pending edit condition
and allows retry. Editing while stopped replaces the prepared plan without
starting playback. Editing with a disconnected startup backend stays local
until reconnect. A lost or changed live backend requires reconnect before
further semantic edits. Moving/selecting nodes does not touch the engine.
The graph state line distinguishes offline, prepared, queued and active states.
Queued explicitly means the drawing represents the next submitted graph while
the engine finishes the previous plan. The 100 ms GUI timer observes audio
adoption revisions and then shows active. Graphs are not edited in place on the
audio thread. There is no automatic retry/hidden edit queue; users retry a
rejected capacity edit. Plan replacement can reset oscillator phase and is not
crossfaded. Render validation and active replacement tests are described in
tests/integration/README.md.