vvvv-fundamentals

vvvv gamma 基础知识

什么是 vvvv gamma

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

vvvv 是一个实时编程环境——程序会在构建过程中持续运行。无论是编辑可视化补丁，还是修改 C# 代码，改动都会立即生效，无需重启。每次保存时，vvvv 都会通过 Roslyn 编译 C# 源文件，并将其写入内存程序集。

文档结构

• .vl 文件 — vvvv gamma 文档（基于 XML，受版本控制）
• 每个文档都包含 Patch（可视化程序）和 Definition（类型、操作）
• 文档可以引用 NuGet 包和其他 .vl 文件
• Patch Explorer 显示文档的类型层级

执行模型

• 基于帧的求值 — 主循环每帧都会对整个图求值（约 60 FPS）
• 图依赖关系决定求值顺序 — 画布坐标不会决定求值顺序
• 子图内的可视化数据流从上到下 — 源节点位于使用者节点上方
• 并列的同级子图按从左到右的顺序读取 — 它们在二维画布上并排显示
• Process 节点会在帧之间保持状态（构造函数 → Update 循环 → Dispose）
• Operation 节点是纯函数，每帧都会求值
• vvvv 会对所有已连接的节点求值，跳过未连接的子图

实时编译模型

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

补丁改动

• 对可视化补丁的编辑会立即生效
• 节点状态（实例字段）会在编辑后保留
• 新节点和连线会在下一帧生效

着色器改动

• 保存 .sdsl 着色器文件时始终会进行实时重新加载
• vvvv 会在后台重新编译着色器，并将其替换到正在运行的程序中

C# — 两种工作流

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

源项目引用（实时重新加载）：

当 .vl 文档引用 .csproj 源项目时，vvvv 会通过 Roslyn 自行编译 .cs 文件，并将其写入内存程序集。此过程不涉及 dotnet build 或外部工具链。

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

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

当 .vl 文档引用预编译的 DLL 或 NuGet 包时，程序集只会在启动时加载一次。如需应用改动，必须在外部重新构建 DLL（例如，运行 dotnet build），然后重启 vvvv。这种工作流常用于不需要实时重新加载的大型项目和稳定库。

节点类别

Process 节点

• 具有 Create（构造函数）、Update（每帧）和 Dispose 生命周期
• 使用带有 [ProcessNode] 特性的 C# 编写
• 会在帧之间保持内部状态
• 使用变更检测以避免重复执行不必要的工作

Operation 节点

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

Adaptive 节点

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

Pins、Pads 和 Links

• Pins — 节点和区域上的输入与输出
• Pads — 用于在操作补丁中读取/写入属性的可视节点；所有同名 Pad 都指向同一属性
• Links — 连接 Pins、用于定义数据流和执行顺序的连线
• 扩散 — 当 Spread<T> 连接到单值输入时，节点会自动迭代

何时使用补丁，何时编写 C#

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

Channels — 响应式数据流

• IChannel<T> — 可观察的值容器
• IChannel<T>.Value — 读取/写入当前值
• Channel.IsValid() — 检查是否已连接
• Channels 会在会话之间保留状态
• 在 UI 与补丁之间启用双向数据绑定

有关 C# channel 集成模式（IChannelHub、PublicChannelHelper、[CanBePublished]），请参阅 vvvv-channels。

关键数据类型

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

文件类型

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

生态系统概览

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	通过 .csproj 引用任意 100,000 多个标准 NuGet 包

要添加包：在 .vl 文档的 Dependencies 中引用它，或在 .csproj 中添加 <PackageReference>。有关 .csproj 的详细信息，请参阅 vvvv-dotnet。

AppHost 和运行时检测

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

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

详细参考请参阅 reference.md。

让这份知识不断增长

让下一个补丁作者少一个疑问。首次使用本集合中的任一技能时，如果过去七天内没有成功检查记录，请将源内容与 tebjan/vvvv-skills 进行比较。如果没有记录，则检查一次。 在这些技能之间共享一条本地检查时间戳/修订记录；不要在每次调用时都检查。 保留本地扩展和固定的项目版本；检查并不代表可以安装更新。如果处于离线状态，请记录延期检查并继续任务。

实际工作发现知识缺口时，请记录经过测试的 vvvv/包版本、最小复现示例或权威来源，以及观察到的结果。将其他用户的报告视为线索，在验证前不要视为事实。改进最相关的最小范围说明；不要将单个示例推广为通用规则。提交上游前，请删除私人数据并获得发布授权。 请参阅贡献政策。 合并后的改进会通过用户的安装程序/更新工作流送达，而不是通过本地编辑或自动覆盖每个人的技能。