Files
materialcraft/docs/wires-and-alpha.md

9.9 KiB
Raw Permalink Blame History

Editing wires and viewing alpha in the 3D view

This page documents two editor features: selecting, deleting, swapping and rerouting wires in the graph editor, and the alpha (transparency) support of the 3D view. Both are clean-room implementations; every action is an engine command, so the CLI, the control channel and MCP can do the same as the mouse.

The wood planks material with a Grid Lines opacity output on a sphere in the 3D view: the gaps are see-through and the back of the sphere shows through them; in the graph, a reroute dot bends the wire from Grid Lines to the opacity output
A cut-out material in the 3D view, and a reroute dot pulled out of a wire

Wires in the graph editor

A wire runs from an output port to an input port. Every input takes at most one wire, so a wire is named by the input it feeds: the target node and its input port (to, toPort).

Gestures

Gesture What it does
Hover a wire The wire turns white and the pointer becomes a hand: it can be clicked
Click a wire Selects it alone (drawn thicker, in the accent color); the node selection is cleared
Shift+click a wire Adds it to the wire selection
Ctrl+click a wire Adds it to the wire selection, or removes it when it is already selected
Delete or Backspace with wires selected Deletes every selected wire (one undo step)
X with exactly two wires selected Swaps where the selected wires come from (see below); they stay selected, so X again swaps back
Drag a wire Pulls a reroute Dot out of the wire where it was pressed and moves it with the pointer, in one gesture
Double-click a wire Drops a reroute Dot at that point
Right-click a wire Opens the wire menu: Insert reroute dot, Swap selected links (X) (with exactly two selected), Delete link / Delete selected links. Right-clicking a wire that is already selected keeps the selection
Click anywhere else Drops the wire selection

A wire is hit within 5 points of its curve. Node cards, ports and comments sit on top of wires, so a press there acts on them, not on the wire underneath. Alt+drag and middle-drag still pan the canvas.

Swapping wires

Select any two wires and press X to swap their sources. On a Blend node, select the Foreground and Background wires and press X: what fed the foreground now feeds the background and the other way around, so the two layers trade places without rewiring by hand.

  • Two wires trade sources.
  • The action is hidden unless exactly two wires from different output pins are selected.
  • Output pin identity determines eligibility; equal values from different pins can still swap.
  • In a main graph, both replacement connections must pass the normal image/value input checks.
  • The order you click the wires in does not matter, so the result is predictable.
  • Wires into different nodes can be swapped too. A swap that would feed a node into itself (a cycle) is refused with a message, and nothing changes.
  • The swap is one undo step.

Reroute dots

A Dot is the existing dot node: one input, one output, passing its input through unchanged. It lets a wire bend around other nodes. After a dot is inserted it is selected, so it can be dragged, deleted (Delete removes it with both of its wires; Backspace, Delete and relink, removes it and joins the wire back up) or given more dots. Inserting a dot is one undo step: Ctrl+Z restores the straight wire.

Commands

Command Params Result
graph.wire.insertDot {to, toPort, at?: [x, y]} Splits the wire feeding to.toPort with a Dot centered at at (graph space; default: midway between the two nodes). Returns {"id": <dot id>} and selects the dot. Errors when no wire feeds that input.
graph.wire.swap {wires: [{to, toPort}, ...]} Exchanges the sources of exactly two listed wires. Returns {"swapped": 2}. Rejects a count other than two, repeated or missing wires, wires from the same output pin, incompatible input types, and cycles; nothing changes then.
graph.wire.delete {wires: [{to, toPort}, ...]} Deletes the listed wires in one undo step (what the Delete key and the menu run). Returns {"deleted": n}.
graph.disconnect {to, toPort} Deletes the single wire feeding to.toPort.

Over the control channel (see control-protocol.md), splitting the wire feeding node 12's input with a dot at (240, 80), then deleting the wire from the dot to node 12:

{"id": 1, "method": "command.run", "params": {"id": "graph.wire.insertDot", "params": {"to": 12, "toPort": "input", "at": [240, 80]}}}
{"id": 2, "method": "command.run", "params": {"id": "graph.disconnect", "params": {"to": 12, "toPort": "input"}}}

Swapping the two layers of Blend node 7:

{"id": 3, "method": "command.run", "params": {"id": "graph.wire.swap", "params": {"wires": [{"to": 7, "toPort": "foreground"}, {"to": 7, "toPort": "background"}]}}}

session.inspect lists every wire under graph.connections and the dot under graph.nodes ("def": "dot"). The wire selection itself is editor state, like hover, and is not part of the session.

Alpha in the 3D view

The 3D view reads OpenGL normal maps by default, matching the Normal node's default format. For a DirectX normal map, enable Display ▸ Flip normal map Y (DirectX), or run view.3d {"normalYFlip": true}. Choose the corresponding format in the Normal node's properties. The setting affects both the interactive view and headless renders, appears as view3d.normalYFlip in session.inspect, and returns to OpenGL when the scene is reset.

The same sphere in the alpha channel view: the opaque grid lines are white and the clear gaps black
The alpha channel view: white is opaque, black is clear

Where the alpha comes from

  1. The output with the Opacity usage, read as grayscale, when the graph has one.
  2. Otherwise the alpha channel of the Base color output, when it is a color image.
  3. Otherwise the material is opaque.

Transparency

Where the alpha is below one, the surface lets light through: each camera ray composites the surfaces it meets front to back (color × alpha, the rest passes on) through up to eight layers, then shows what lies behind: the backdrop, or the environment when Display ▸ Environment background is on. Back faces seen through a clear front are shaded facing the viewer, so a cut-out sphere shows its inside. Every layer is the mesh as the height output displaced it.

Display ▸ Transparency (alpha) turns this off, so the alpha is ignored and the mesh is opaque. It is on by default.

Before this change, the opacity output only mixed each pixel with the flat backdrop color; the back of the mesh and the environment never showed through.

Alpha channel view

Display ▸ Show alpha channel, or the checkerboard button in the 3D view's bottom bar, shows the alpha on the mesh unlit: white is opaque, black is clear, values in between are linear (0.5 shows as 50% gray, without tone mapping). The view is labeled Alpha channel in its top-left corner. It shows the first surface only, so the channel reads clearly.

Commands

view.3d takes two booleans; both are part of the session's view3d state and of session.inspect:

Param Default Meaning
transparency true See through the mesh where the alpha is below one
alphaView false Show the alpha channel instead of the lit material
{"id": 4, "method": "command.run", "params": {"id": "view.3d", "params": {"alphaView": true}}}

Headless renders (materialcraft-cli render, the render RPC) use the same settings.

Implementation notes

  • crates/render/src/preview.rs: alpha() picks the alpha source; shade() returns color, alpha and hit distance; trace() composites the layers (MAX_LAYERS = 8, stops once less than 0.1% of the light gets through); Settings::{transparency, alpha_view}.
  • crates/engine/src/wire_cmds.rs: graph.wire.insertDot, graph.wire.swap (unplugs every listed wire first, then reconnects, so a half-swapped state is never mistaken for a cycle) and graph.wire.delete.
  • crates/ui-egui/src/graph_view.rs: wire hit testing (bezier_points, bezier_at, bezier_distance, wire_at), the WirePress gesture, the multi-wire selection (GraphView::selected_wires), the wire menu, delete_selected_wires and swap_selected_wires; crates/ui-egui/src/menus.rs gives Delete, Backspace and X to selected wires before the node commands and shortcuts.
  • crates/ui-egui/src/view3d.rs: the Display menu toggles and the bottom-bar button.

Tests

  • preview::tests::alpha_shows_what_lies_behind_and_the_alpha_view_shows_the_channel: a clear sphere shows the backdrop, transparency off ignores alpha, the opacity output wins over the base color alpha, the alpha view shows exact values.
  • a_wire_splits_with_a_reroute_dot_and_deletes (engine): insertion, wiring, selection, cooking through the dot, single-step undo, the error with no wire, deletion.
  • selected_wires_swap_their_sources_and_delete_together (engine): two-wire swap in any order, single-step undo, refused requests (one or three wires, duplicates, missing wires), a refused cycle that leaves the graph unchanged, deleting several wires in one step.
  • graph_view::tests::clicked_wires_swap_with_x_and_delete_together: real clicks on a Blend node's two wires (the second with Shift), X swaps, X again swaps back, Delete removes both.
  • every_template_is_opaque_in_the_3d_view (engine): no built-in template turns see-through.
  • graph_view::tests::wires_are_hit_near_their_curve_only: wire hit testing.
  • The snapshots UI test renders both screenshots on this page (alpha-transparency, alpha-channel).