vvvv-fundamentals

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

vvvv gamma Fundamentals

vvvv gamma 基础概念

What Is vvvv gamma

什么是vvvv gamma

vvvv gamma is a visual programming environment for .NET 8. It combines node-based patching with C# code generation, targeting Stride (3D engine) and .NET APIs. Programs are built by connecting nodes with links in a visual editor.

vvvv is a live programming environment — programs run continuously while you build them. Both visual patch edits and C# code changes take effect immediately without restarting. vvvv compiles C# source files itself via Roslyn into in-memory assemblies on every save.

vvvv gamma 是面向.NET 8的视觉编程环境。它将基于节点的视觉编程（Patching）与C#代码生成相结合，目标平台为Stride（3D引擎）和.NET API。程序通过在可视化编辑器中连接节点与连线来构建。

vvvv 是一款实时编程环境——在你构建程序的同时，程序会持续运行。无论是视觉编程补丁的编辑还是C#代码的修改，都会立即生效，无需重启。vvvv会通过Roslyn在每次保存时自行将C#源文件编译为内存程序集。

Document Structure

文档结构

.vl
files — vvvv gamma documents (XML-based, version controlled)
Each document contains Patches (visual programs) and Definitions (types, operations)
Documents can reference NuGet packages and other
```
.vl
```
files
The Patch Explorer shows the document's type hierarchy

.vl
文件 —— vvvv gamma 文档（基于XML，支持版本控制）
每个文档包含补丁（Patches）（视觉程序）和定义（Definitions）（类型、操作）
文档可以引用NuGet包和其他
```
.vl
```
文件
补丁资源管理器（Patch Explorer） 显示文档的类型层次结构

Execution Model

执行模型

Frame-based evaluation — the mainloop evaluates the entire graph every frame (~60 FPS)
Data flows left-to-right, top-to-bottom through links between nodes
Process nodes maintain state between frames (constructor → Update loop → Dispose)
Operation nodes are pure functions evaluated each frame
vvvv evaluates all connected nodes, skips disconnected subgraphs

基于帧的评估 —— 主循环每帧（约60 FPS）评估整个节点图
数据通过节点间的连线从左到右、从上到下流动
进程节点（Process nodes） 在帧之间保持状态（构造函数 → 更新循环 → 释放）
操作节点（Operation nodes） 是纯函数，每帧都会被评估
vvvv 会评估所有已连接的节点，跳过未连接的子图

Live Compilation Model

实时编译模型

vvvv runs your program continuously while you edit it. There is no edit-compile-run cycle for patches and shaders. For C#, live reload depends on how the code is referenced.

vvvv 在你编辑程序的同时持续运行程序。对于视觉编程补丁和着色器，无需经历编辑-编译-运行的循环。对于C#代码，实时重载取决于代码的引用方式。

Patch Changes

补丁修改

Edits to visual patches apply immediately
Node state (instance fields) is preserved across edits
New nodes and links become active on the next frame

对视觉编程补丁的编辑会立即生效
节点状态（实例字段）在编辑过程中会被保留
新添加的节点和连线会在下一帧激活

Shader Changes

着色器修改

```
.sdsl
```
shader files always live-reload when saved
vvvv recompiles shaders in the background and swaps them in the running program

```
.sdsl
```
着色器文件在保存后始终会实时重载
vvvv 会在后台重新编译着色器，并在运行中的程序中替换它们

C# — Two Workflows

C# —— 两种工作流

C# code can be integrated via source project reference or pre-compiled binary. The choice depends on project size and development phase.

Source project reference (live reload):

When a .vl document references a .csproj source project, vvvv compiles .cs files itself via Roslyn into in-memory assemblies. No

dotnet build

or external toolchain is involved.

On .cs file save, vvvv detects the change and recompiles in the background
Status indicator: gray = building symbols, orange = emitting C#
On successful compilation, affected nodes restart their lifecycle:
1. ```
Dispose()
```
  called on old instance
2. New constructor runs (with fresh
```
NodeContext
```
  )
3. ```
Update()
```
  resumes on the next frame
Static fields reset on reload — the entire in-memory assembly is replaced
On compilation error, the program continues running with the last valid code

Binary reference (no live reload):

When a .vl document references a pre-compiled DLL or NuGet package, the assembly is loaded once at startup. To pick up changes, you must rebuild the DLL externally (e.g.,

dotnet build

) and restart vvvv. This workflow is common for larger projects and stable libraries where live reload is not needed.

C#代码可以通过源项目引用或预编译二进制文件两种方式集成。选择哪种方式取决于项目规模和开发阶段。

源项目引用（支持实时重载）：

当

.vl

文档引用

.csproj

源项目时，vvvv会通过Roslyn自行将

.cs

文件编译为内存程序集，无需

dotnet build

或外部工具链。

保存
```
.cs
```
文件时，vvvv会检测到变化并在后台重新编译
状态指示器：灰色 = 正在构建符号，橙色 = 正在生成C#代码
编译成功后，受影响的节点会重启其生命周期：
1. 调用旧实例的
```
Dispose()
```
  方法
2. 运行新的构造函数（使用新的
```
NodeContext
```
  ）
3. 在下一帧恢复
```
Update()
```
  方法的执行
静态字段会在重载时重置——整个内存程序集会被替换
编译出错时，程序会继续使用最后一次有效的代码运行

二进制引用（不支持实时重载）：

当

.vl

文档引用预编译的DLL或NuGet包时，程序集会在启动时加载一次。要获取代码变更，你必须在外部重新构建DLL（例如

dotnet build

）并重启vvvv。这种工作流常用于大型项目和稳定库，这些场景中实时重载并非必需。

Node Categories

节点类别

Process Nodes

进程节点

Have Create (constructor), Update (per-frame), and Dispose lifecycle
Written in C# with
```
[ProcessNode]
```
attribute
Maintain internal state between frames
Use change detection to avoid redundant work

拥有创建（构造函数）、更新（每帧）和释放的生命周期
使用
```
[ProcessNode]
```
特性在C#中编写
在帧之间维护内部状态
使用变更检测避免冗余工作

Operation Nodes

操作节点

Pure functions: same input always produces same output
Written as static C# methods (auto-discovered by vvvv)
No state between frames
No
```
[ProcessNode]
```
attribute needed

纯函数：相同输入始终产生相同输出
以静态C#方法的形式编写（vvvv会自动发现）
帧之间无状态
无需
```
[ProcessNode]
```
特性

Adaptive Nodes

自适应节点

Nodes that adapt their implementation based on connected input types
Example:
```
+
```
works with int, float, Vector3, string, etc.
Resolved at link-time, not runtime

会根据连接的输入类型调整实现的节点
示例：
```
+
```
节点可处理int、float、Vector3、string等类型
在连线时解析，而非运行时

Pins, Pads, and Links

引脚（Pins）、焊盘（Pads）与连线（Links）

Pins — inputs and outputs on nodes and regions
Pads — visual nodes for reading/writing Properties inside operation patches; all pads with the same name refer to the same property
Links — connections between pins that define data flow and execution order
Spreading — when a
```
Spread<T>
```
connects to a single-value input, the node auto-iterates

引脚（Pins） —— 节点和区域的输入与输出
焊盘（Pads） —— 用于在操作补丁中读写属性的可视化节点；所有同名焊盘都指向同一个属性
连线（Links） —— 引脚之间的连接，定义了数据流和执行顺序
扩展（Spreading） —— 当
```
Spread<T>
```
连接到单值输入时，节点会自动迭代处理

When to Patch vs Write C#

何时使用视觉编程（Patching）何时编写C#代码

Use Patching	Use C# Code
Prototyping, data flow	Custom nodes, performance-critical code
Visual connections, UI composition	Complex algorithms
Real-time parameter tweaking	.NET library interop
Dataflow routing and spreading	Native/unmanaged resource management

使用视觉编程	使用C#代码
原型开发、数据流处理	自定义节点、性能关键型代码
可视化连接、UI组合	复杂算法
实时参数调整	.NET库互操作
数据流路由与扩展	原生/非托管资源管理

Channels — Reactive Data Flow

通道（Channels）—— 响应式数据流

```
IChannel<T>
```
— observable value container
```
IChannel<T>.Value
```
— read/write the current value
```
Channel.IsValid()
```
— check if connected
Channels persist state across sessions
Enable two-way data binding between UI and patch

For C# channel integration patterns (IChannelHub, PublicChannelHelper, [CanBePublished]), see vvvv-channels.

```
IChannel<T>
```
—— 可观察的值容器
```
IChannel<T>.Value
```
—— 读写当前值
```
Channel.IsValid()
```
—— 检查是否已连接
通道会在会话之间保留状态
支持UI与视觉编程补丁之间的双向数据绑定

关于C#通道集成模式（IChannelHub、PublicChannelHelper、[CanBePublished]），请参考vvvv-channels文档。

Key Data Types

核心数据类型

Type	C# Equivalent	Usage
`Spread<T>`	`ImmutableArray<T>`	vvvv's immutable collection
`SpreadBuilder<T>`	`ImmutableArray<T>.Builder`	Build spreads efficiently
Float32, Int32, etc.	`float` , `int`	Primitives
`Vector2/3/4`	`Stride.Core.Mathematics`	Spatial math
`Color4`	`Stride.Core.Mathematics`	RGBA color

类型	C# 等效类型	用途
`Spread<T>`	`ImmutableArray<T>`	vvvv的不可变集合
`SpreadBuilder<T>`	`ImmutableArray<T>.Builder`	高效构建Spread集合
Float32、Int32等	`float` 、 `int`	基本类型
`Vector2/3/4`	`Stride.Core.Mathematics`	空间数学计算
`Color4`	`Stride.Core.Mathematics`	RGBA颜色

File Types

文件类型

Extension	Purpose
`.vl`	vvvv gamma documents (XML-based)
`.sdsl`	Stride shader files (SDSL language)
`.cs`	C# source files for custom nodes
`.csproj`	.NET project files
`.nuspec`	NuGet package spec

扩展名	用途
`.vl`	vvvv gamma 文档（基于XML）
`.sdsl`	Stride着色器文件（SDSL语言）
`.cs`	自定义节点的C#源文件
`.csproj`	.NET项目文件
`.nuspec`	NuGet包规范文件

Ecosystem Overview

生态系统概览

vvvv's functionality extends through NuGet packages that bundle .vl documents, C# nodes, and shaders.

Domain	Key Packages
3D Rendering	VL.Stride (Stride engine), VL.Fuse (GPU visual programming)
2D Rendering	VL.Skia, ImGui, Avalonia, CEF/HTML
Hardware I/O	DMX/Art-Net, ILDA lasers, depth cameras (Azure Kinect, ZED), robotics (KUKA, Spot), Ultraleap, LiDAR
Networking	OSC, MIDI, MQTT, Redis, WebSocket, HTTP, TCP/UDP, ZeroMQ, Modbus, Ableton Link
Computer Vision	OpenCV, MediaPipe, YOLO (v8–v11), ONNX Runtime
Audio	NAudio, VST hosting, SuperCollider bridge
General .NET	Any of 100,000+ standard NuGet packages via .csproj reference

To add a package: reference it in your

.vl

document's Dependencies, or add a

<PackageReference>

to your

.csproj

. See vvvv-dotnet for .csproj details.

vvvv 的功能可通过NuGet包扩展，这些包包含

.vl

文档、C#节点和着色器。

领域	核心包
3D渲染	VL.Stride（Stride引擎）、VL.Fuse（GPU视觉编程）
2D渲染	VL.Skia、ImGui、Avalonia、CEF/HTML
硬件I/O	DMX/Art-Net、ILDA激光、深度相机（Azure Kinect、ZED）、机器人（KUKA、Spot）、Ultraleap、激光雷达（LiDAR）
网络	OSC、MIDI、MQTT、Redis、WebSocket、HTTP、TCP/UDP、ZeroMQ、Modbus、Ableton Link
计算机视觉	OpenCV、MediaPipe、YOLO（v8–v11）、ONNX Runtime
音频	NAudio、VST宿主、SuperCollider桥接
通用.NET	超过10万个标准NuGet包中的任意一个，通过 `.csproj` 引用

添加包的方式：在

.vl

文档的依赖项中引用，或在

.csproj

中添加

<PackageReference>

。有关

.csproj

的详细信息，请参考vvvv-dotnet文档。

AppHost & Runtime Detection

AppHost 与运行时检测

csharp

// Detect if running as exported .exe vs editor
bool isExported = nodeContext.AppHost.IsExported;

// Register per-app singleton services
nodeContext.AppHost.Services.RegisterService(myService);

For detailed reference, see reference.md.

csharp

// 检测当前是作为导出的.exe运行还是在编辑器中运行
bool isExported = nodeContext.AppHost.IsExported;

// 注册每个应用的单例服务
nodeContext.AppHost.Services.RegisterService(myService);

有关详细参考，请查看reference.md。