Chapter 21
Visual graphs and 3D
Visual Graph edits the production graph for the selected video or generator layer. Open it inside Video Editor, select the layer, and use Nodes, Recipes and Modules to build or reuse its processing. Opening the panel alone does not alter the project.
This draft describes controls checked against the application source. Native app workflows and platform behavior have not been verified for this manual edition.
Your first layer graph #
Select a layer, open the Recipes tab, filter for Editable Layer and click Apply. This creates an editable production chain for the layer. Inspect Source, Transform, FX, Mask, Blend and Output to see how the frame reaches the composite.
Nodes lists available node kinds. Drag compatible typed sockets to change processing. Image, mask, linear depth, normal, geometry, scene, material and motion-vector values have different contracts. A generic Frame label does not make a depth or motion input interchangeable with an image.
Selected Node Diagnostics reports the selected type, compilation state and graph errors. Keep an output connection while editing. F or Home fits the canvas; arrow keys select nodes. In HTML preview, select a Transform node in the root layer graph. Enter Scale from 0.01 to 8, X or Y from -4 to 4, or Rotation from -360 to 360, then click Apply for that value. To add a cable in the same graph, select an authored node with an output, choose Source output and Destination input, then click Connect. DonutStudio checks the current endpoints before accepting the connection. Incompatible or stale requests are refused. The browser adds cables in the root graph only; use the native editor to remove cables, edit nested graphs, insert adapters and edit other parameters. Switch back with Native editor. If the embedded browser is unavailable, continue in the native editor. Draft: these limited controls are source-reviewed; native browser and rendering acceptance remain unverified.
Recipes and reusable modules #
Recipes offers Apply, Preview and More.... Built-in recipes replace the entire layer graph; saved recipe fragments paste selected processing into it. More... includes Save Selected Nodes, Import Recipe, Duplicate and Export. Recipe files use the .visual-recipe.xml extension.
Modules has Search modules, Place, Preview, Convert Selection to Module, More... and Refresh. Place inserts the selected package as an instance. Place and Edit opens its interior. Route the instance's external typed sockets to the surrounding graph.
Convert Selection to Module wraps selected nodes as one reusable transaction and saves a library package. More... also imports, exports, duplicates, deletes, saves the selected instance back to a module, updates the selected instance or updates all linked instances. Built-in packages cannot be deleted or overwritten through the saved-instance action. Module files use .visual-module.xml.
A linked instance remembers its module identity and version. Use the explicit update action after changing the library definition. A duplicate is a separate package. Refresh rescans saved modules and bundled shader packages. Read Selected visual module availability before placement. Preview needs the production renderer and dependencies; a catalogue row without a rendered thumbnail is not a rendered preview.
Select a clip and a module, then choose Modules Preview to render the module with the selected clip's captured project context. Preview requires the production renderer, the module's dependencies and supported captured inputs and history. If Preview reports unsupported captured automation or Event destinations, Score/Event history or feedback history, inspect that error before changing the graph. A successful Preview does not verify full playback or export. This native workflow remains unverified for this manual edition.
Water in Modules Preview requires an initialized captured Score and supports replay from project zero through 10 seconds. Its sources must share the project clock from zero, with no offsets, speed changes, retiming or transitions. Custom reset or history settings are unsupported in this preview path. These limits apply to Modules Preview, not to all Water playback.
Draft: the following HTML preview actions still need installed-app and file-dialog verification.
In the root Visual Graph HTML preview, choose an available module from Update All Linked Instances. This updates matching linked instances from the current library package. Return to the root graph to use this action from a child graph.
Read the library status after an update. If it reports Graph edit saved. Visual preview publication failed., the graph edit was accepted but the preview was not delivered. Check the preview status before relying on the displayed result.
To export from the root Visual Graph HTML preview, choose Export Module for an available module in the catalog. In the native Save dialog, choose the destination and save the .visual-module.xml file.
Opening the dialog starts the request. Check the export status after choosing a destination. Cancelling leaves the export unsaved. If the module catalog or editor context has changed, the request may be refused. Return to the current root graph and start again.
Export Module is unavailable inside a child graph. An unavailable package can display a reason in the catalog.
Select a clip, return to the root Visual Graph and choose Import Module. Use the native Open dialog to choose a .visual-module.xml file. Import Module is available even when the user module library is empty.
Opening the dialog starts the request. Read the import status after choosing a file. Cancelling leaves the package unimported. If the editor, selection, project or module catalog has changed, return to the current root graph and start again.
Import stores a validated package in the module library. Successful import does not guarantee that the package can be placed or previewed. Read its availability message before placement.
Import Module is unavailable inside a child graph. Return to the root Visual Graph to import from the HTML preview.
Catalogue and authoring permissions #
The built-in catalogue includes image transforms, masks, compositing, trails, depth effects, imported scenes, reactive geometry and original 3D starters. Some shader, transition and material modules appear only when their exact dependencies are available. Saved or imported modules add further rows, so the browser does not have a universal fixed count.
Bundled visualizers and everyday graph modules have Free use paths. Custom shader, raymarch, particle, script and music-source-to-parameter authoring require the corresponding Pro authority and enabled add-on. A built-in starter's availability does not grant every specialist authoring operation inside it.
Imported programmable content must pass its trust and dependency checks. Treat unavailable module status as a reason to inspect the package and missing dependency, not as an invitation to replace the renderer or bypass a feature gate.
Importing GLB and glTF scenes #
Drop a GLB or glTF model into the selected Visual Graph to create an imported model source. Use the model asset controls to replace or relink that source when necessary. Changing the file can invalidate stored object, mesh, animation or material selections.
Select Imported Animated Model to expose Imported Scene, Imported Mesh, Pose Object, Imported Animation, Crossfade Animation, Imported Bone, Imported Morph Target and Imported Light. Whole scene renders the admitted scene selection; a mesh selection narrows it. Pose Object chooses the exact object that receives pose controls.
Draft: the Local Transform Target row selects an imported object for metadata inspection. Parent inspects its direct parent when available. These inspection choices are independent of Pose Object and the Render 3D Object and Material Slot choices. The row has no numeric transform fields, Reset or Apply controls, and selecting a target or parent does not edit the scene. Availability and the complete installed-app workflow remain unverified.
Connect Apply Imported Animation to the model's mesh, skeleton, morph targets and animation as required by the patch, then route the deformed mesh toward Render 3D. Timeline Seconds, Speed, Time Offset, trim, Clamp/Loop playback, combination mode and Clip Crossfade control playback. Selected Bone Control adjusts the chosen bone after animation; Selected Morph Control overrides the chosen target weight.
Imported light intensity adjusts the selected imported light in its scene instances. Connecting a Render 3D Light replaces imported lighting; restore imported intensity multipliers to one before making that replacement. For materials, select Render 3D and choose the exact Object and Material Slot target. A missing stored selection must be repaired explicitly.
Combining imported and procedural scenes #
In the selected layer's Visual Graph, use Nodes to add Scene 3D Compose. Connect one Imported Animated Model scene output and one Primitive Scene or Geometry Scene output to separate scene inputs. Connect the combined scene output to Render 3D. Use at least two scene inputs and one enabled Render 3D node.
For animation, connect the same model's mesh, skeleton, morph targets and animation outputs to Apply Imported Animation. Connect its deformed mesh output to Render 3D's deformation input. Connect a Perspective Camera and Directional Light to Render 3D's camera and light inputs. Each needs a Transform 3D input.
Use one imported scene and leave the Parent Scene controls off for branches containing it. Use Surface for the imported material. This route does not admit Diffraction Grating Material, Diffractive Foil Material or note-reactive lighting for the imported scene. An imported Surface override cannot be combined with procedural Surface programs in the same composition. Native Preview and Export remain unverified.
Geometry and fields #
Geometry, points, curves and instances are distinct typed paths. Use the matching node family to build a mesh, distribute points, resample or trim a curve, construct instances and turn the result into a scene. Imported Mesh Geometry extracts an admitted static mesh selection for geometry processing. It is separate from the animated skinning/morph render route.
Fields compute a value across a declared domain such as vertices, faces, points, curve points, splines or instances. Float, Vector, Color, Integer and Boolean fields have different uses. Choose the domain and value type that the receiving operation declares.
Useful field operations include math, vector math, comparison, range mapping, clamp, noise, gradient, identity-based random, falloff, proximity and surface distance. Named attributes include selection, UV, normal, color, emission, opacity, metallic and roughness. Timeline Field provides time, loop phase, sine or cosine.
Audio Deformer chooses Master, Track or Group analysis, selected spectrum bands, normalization, strength and a deformation mode such as normal/vector displacement, ripple, twist, bend or attraction. Audio Effector adds falloff, analysis delay, gate, peak hold and smoothing. Spectrum Instancer maps bands to a line, ring, grid or admitted mesh/point/curve arrangement.
Score Field maps notes to spatial measurements using onset, log frequency, velocity, duration or track. It can measure distance, velocity influence, pitch spacing, prime-lattice coordinates or harmonic links. Set Influence Radius, Gain and Bias before connecting it to geometry. Score-driven imported-mesh starters have bounded static geometry and do not imply imported skinning on that path.
Score Field #
In Video Editor, select a video or generator layer, open Visual Graph and use Nodes to place Score Note Collection and Score Field. Connect the collection's notes output to Score Field and connect the source Geometry3D to its geometry input. For mesh displacement, connect that same geometry to Set Position and connect the field to its vertex offset, then route the result through Geometry Scene and Render 3D. The field supports at most 2,048 geometry samples.
Measurement offers Closest Note Distance, Velocity Influence, Pitch Spacing in Semitones, Prime Lattice Coordinates, Harmonic Link Distance, Pitch Bend in Semitones, Note Age in Beats, Remaining Duration in Beats, Root Flag, MIDI Note Number, Resolved Frequency in Hz and Harmonic Link Ratio. Velocity Influence is the default. Root Flag is zero or one; the pitch, age, duration and frequency choices use the units in their names.
Score Field needs available unmuted notes at the requested preview or export time. The harmonic-link measurements also need a valid link between available notes. Place other geometry operations before Score Field. Score-driven static imported geometry does not provide animated skinning.
Instance Score Field Vector takes Instances3D and the same Score Note Collection input. It produces an instance-domain Vector field for compatible instance field math or appearance controls before Instances Scene. It uses the same measurement and mapping controls and supports at most 2,048 instance samples. These instructions are source reviewed; native preview and export remain unverified.
- Note X, Y and Z Axis map note positions using Onset, Log Frequency, Velocity, Duration or Track. Defaults are Onset, Log Frequency and Track. Each Note Axis Scale defaults to 1 and accepts -10,000 to 10,000.
- Influence Radius defaults to 1 and accepts 0.000001 to 10,000 in the geometry coordinate scale. Gain defaults to 1 and Bias to 0; each accepts -1,000 to 1,000.
- Output X, Y and Z Scale multiply the result after Gain and Bias. Defaults are 0, 0 and 1; each accepts -1,000 to 1,000. X, Y and Z Prime choose 2, 3, 5, 7, 11 or 13 for Prime Lattice Coordinates, defaulting to 2, 3 and 5.
Note instancing and harmonic links #
Use Nodes in the selected layer's Visual Graph to add Note Instanced Mesh. Connect Imported Animated Model's mesh output to its mesh input and Score Note Collection's notes output to its notes input. Connect the instanced mesh output to Render 3D's deformation input, and connect the same imported model's scene output to Render 3D's scene input.
Harmonic Link Geometry offers the same axis choices and defaults. Connect Score Note Collection to its notes input and its scene output to Render 3D's scene input. Ribbon Width controls the link width.
Score Field keeps its separate five-choice Note X Axis, Note Y Axis and Note Z Axis controls. Native Preview and Export remain unverified.
X Axis, Y Axis and Z Axis each offer the following choices. The defaults are Onset for X, Log Frequency for Y and Track for Z.
- Onset, Log Frequency, Velocity, Duration and Track.
- Pitch Bend Semitones, Note Age Beats and Remaining Duration Beats.
- Root Flag, MIDI Note and Resolved Frequency Hz.
- Prime 2 Exponent, Prime 3 Exponent, Prime 5 Exponent, Prime 7 Exponent, Prime 11 Exponent and Prime 13 Exponent.
Spectral History Field #
Spectral History Field samples earlier audio-analysis rows as a field across geometry. The mesh node outputs a vertex Vector field. Point, Curve and Instance Spectral History Field each offer Float, Vector and Color variants. Choose the family matching your source and connect its output to a consumer that accepts that field domain and value type.
Choose Project Baked Analysis for reproducible history and export. Master, Track and Group sources use the saved project analysis; choose the project track or group when needed. If analysis is missing, open Video Editor and stop playback to bake the project mix.
Live, Resets on Seek is Master-only and requires Use Timeline Time. Live history resets on backward time, seeks, loops or source changes. Live Spectral History cannot be exported; switch to Project Baked Analysis and bake the mix first. Native preview and export remain unverified for this manual edition.
- Analysis Source defaults to Master. First Band and Last Band select whole bands 0 to 63, defaulting to the full range. Lowest Frequency Hz and Highest Frequency Hz accept 30 to 18,000 Hz.
- Sample By selects element index, a position axis or frequency range. Additional UV or stable point/instance identity choices depend on the typed node. Interpolate Bands defaults on; Normalize Selected Bands defaults off.
- Gain and Bias default to 1 and 0 and accept -1,000 to 1,000. Attack Seconds and Release Seconds accept 0 to 2 and default to 0. Position Minimum and Position Maximum default to 0 and 1; each accepts -1,000,000 to 1,000,000.
- Vector fields expose direction or offset X, Y and Z controls, defaulting to 0, 0 and 1. Color variants name them Red, Green and Blue Multiplier. Each accepts -1,000 to 1,000. Float variants omit these controls.
- Use Timeline Time defaults on. Turn it off only with baked analysis to use Current Time Seconds, which accepts 0 to 1,000,000,000.
- History Samples accepts whole values 2 to 128 and defaults to 32. Sample Spacing Seconds accepts 1/60 to 20 seconds and defaults to 0.1. The oldest-to-current span, sample count minus one multiplied by spacing, must not exceed 20 seconds.
- History Coordinate selects element index or Position X, Y or Z, defaulting to Position Y. Current Row Position and Oldest Row Position default to -1 and 1 and accept -1,000,000 to 1,000,000. Current must be less than oldest; coordinates outside that interval clamp to its ends.
SDF shapes and text #
SDF nodes define implicit shapes and operations rather than imported triangles. Combine admitted primitives, transforms, Boolean blends, repeats and domain warps, then use the matching raymarch or surface-extraction route. A source graph can contain several operations; it is not limited to one primitive.
SDF Text / Extrusion uses embedded vector font outlines. Select the text node, edit the single-line SDF text field and click Apply text; Cancel restores the edit. The input limit is 256 UTF-8 bytes and 128 glyphs. Embedded Font and Text Size select the outline and scale.
Surface extraction has a bounded domain and grid. Under-resolved, ambiguous or excessive work is refused rather than silently generating a different mesh. Text raymarch and extraction also have glyph and evaluation budgets; ordinary full-resolution text rendering remains an experimental limit in this edition. A valid text edit does not prove that every resolution can render it.
Materials, lights and environments #
Render 3D combines admitted geometry or an imported scene with material, camera and light inputs. Use Perspective Camera and Transform 3D for framing. Directional Light, Point Light and Environment Light supply different lighting. A chosen material target identifies one imported object and primitive slot.
Surface material nodes provide base color, opacity, metallic, roughness, emission and supported field-driven shading. Vertex modifiers change geometry before the image is drawn. Check the active material and geometry path before expecting a field connected elsewhere to affect the mesh.
Select Environment Light and choose Import HDR environment... to add a .hdr image. Environment image chooses the stored asset; Image orientation and Image exposure stops adjust it. Constant or analytic environment remains available without an image. The image route supports background and opaque reflections; it does not establish general indirect lighting for every scene.
Video on 3D Screen and image-tinted foil starters accept the current media clip's direct Video Source. Clip trim and retiming drive that source. Generated, filtered and other-layer images are unavailable on those routes. The screen uses a 16:9 surface and stretches other aspect ratios.
Diffraction, foil, glass and water #
Diffraction and foil are physical-material experiments with explicit light, geometry and work limits. Foil Corners and Analytic Grating choose different groove geometry. Groove period, depth, profile, coating, roughness, mask and field controls affect the admitted optical operation. Keep discrete lattice, profile and coating modes fixed while modulating continuous controls.
A physical diffraction setup requires the admitted white key light. Adjust its direction and intensity, or turn Direct Intensity off, rather than applying a colored key that the operation rejects. The holographic card starter can use current-clip imagery for print tint and coverage.
Smooth dispersive glass and rough-glass transport use bounded spectral and scene data. They are experimental routes, not a promise of general path tracing, arbitrary multi-bounce glass, all material mixtures or unrestricted caustics. A starter's source implementation does not establish native rendered acceptance.
Lighthouse and Ocean uses one untextured, nondispersive water interface and diffuse receivers with flat face normals. Wave amplitude, direction, speed, loop, roughness and IOR affect it. Change speed or wavelength after setting loop period to zero, or choose a complete wave cycle. Foam, general fluid simulation, volumetric atmosphere and general indirect lighting are unavailable in that starter. Strong masking or grazing roughness can exceed its transport limit.
Render passes and HDR #
Render Passes exposes a typed output selection such as Color, Depth, Normal, Motion, Emission, Material ID or Object ID. Match that output to the downstream consumer. Render 3D data passes and linear HDR images are separate from the SDR reference video.
Use Depth Fog or Depth Relight with a connected image and linear depth. A depth-dependent node needs an admitted depth source; a color image cannot stand in for one. Volume and multipass operations have bounded source arrangements and do not admit every temporal or shader combination.
For HDR movie delivery, use the restricted opaque Render 3D route documented in Video editing. Preview stays SDR. Mixed video, transitions and overlays are unsupported for PQ/HLG movie export.
Reactive starters and simulation #
The catalogue includes audio-deformed imported models, an audio-reactive character, stem-reactive scene rigs, score/timbre scenes, harmonic-link sculpture, spectrum instancing and looping fields. Choose the starter that matches the data you actually have, then adjust its analysis source or note mapping.
Particle and physics starters use deterministic seeds, timeline evaluation and bounded geometry. Replaying a project needs the same retained source and configuration. Particle Halo, Deterministic Reactive Physics and Note-Driven Particle and Light Rig cover specific arrangements; they do not imply unrestricted coupling between particles, water, deforming topology and all field domains.
Water Surface Simulation operates on one static retained XY rest grid. Propagation Speed in Units per Second, Damping per Second, Score Impulse Gain and Audio Onset Gain control its response. It needs the admitted project history for reactive input. Particle-water coupling is unavailable; the directional wave used by Lighthouse and Ocean is a different operation.
Field work on static mesh, points, curve points and instances does not make every legacy post-draw instancer or changing particle topology compatible. Follow the selected node diagnostics and the starter's own constraints before combining them.
Optical flow and current limits #
Optical Flow requires both ordered image inputs and two distinct source clips. Swapping the pair changes the motion direction. Wiring the same source twice does not supply an admitted two-source operation. A Render Passes Motion output alone does not create the required image pair.
The generic Optical Flow node preserves authoring and validates typed sources. Native execution uses a specialist source-pair worker with an exact field terminal or the admitted Motion View or Motion Blur image layout. General node execution remains authoring-only. Keep this separate from Speed Warp, which uses a retiming-specific interpolation path. The specialist native workflow has not been verified for this manual edition.
Full-resolution physical optics, SDF text, volume, advanced passes, simulations, preview/export parity and cross-platform performance remain experimental or unverified where the selected operation refuses them. Source-backed controls and passing-looking thumbnails cannot establish full acceptance of these workflows.