vvvv Spreads

什么是 Spreads

Spread 是 vvvv 的不可变集合类型，概念上类似于 ImmutableArray。它是在节点之间传递集合的主要方式。

关键属性：

• - 不可变 — 永远不要原地修改，始终创建新的 spreads
• 值语义 — 具有相同元素的两个 spreads 被视为相等
• 循环索引 — 在可视化补丁中，索引会循环（C# API 中不会）
• 永不为 null — 使用 Spread.Empty 代替 null

创建 Spreads

SpreadBuilder（主要方法）

csharp
var builder = new SpreadBuilder(expectedCount);
for (int i = 0; i < count; i++)
builder.Add(ComputeValue(i));
Spread result = builder.ToSpread();

从现有数据创建

csharp
// 从数组（扩展方法）
Spread fromArray = new int[] { 1, 2, 3 }.ToSpread();

// 从数组（静态工厂）
Spread fromResult = Spread.Create(resultArray);

// 空 spread（永远不要使用 null）
Spread empty = Spread.Empty;

// 单个元素
var single = new SpreadBuilder(1);
single.Add(42f);
Spread one = single.ToSpread();

访问元素

csharp
// 在索引前始终检查 Count
if (spread.Count > 0)
{
float first = spread[0];
float last = spread[spread.Count - 1];
}

// 迭代（推荐 — 无内存分配）
foreach (var item in spread)
Process(item);

// 循环中的索引访问
for (int i = 0; i < spread.Count; i++)
Process(spread[i]);

C# 中的常见模式

映射（转换每个元素）

csharp
public static Spread Scale(Spread input, float factor = 1f)
{
var builder = new SpreadBuilder(input.Count);
foreach (var value in input)
builder.Add(value * factor);
return builder.ToSpread();
}

过滤

csharp
public static Spread FilterAbove(Spread input, float threshold = 0.5f)
{
var builder = new SpreadBuilder();
foreach (var value in input)
{
if (value > threshold)
builder.Add(value);
}
return builder.ToSpread();
}

合并（同时处理两个 Spreads）

csharp
public static Spread Add(Spread a, Spread b)
{
int count = Math.Max(a.Count, b.Count);
var builder = new SpreadBuilder(count);
for (int i = 0; i < count; i++)
{
float va = a.Count > 0 ? a[i % a.Count] : 0f;
float vb = b.Count > 0 ? b[i % b.Count] : 0f;
builder.Add(va + vb);
}
return builder.ToSpread();
}

累加（运行总和）

csharp
public static Spread RunningSum(Spread input)
{
var builder = new SpreadBuilder(input.Count);
float sum = 0f;
foreach (var value in input)
{
sum += value;
builder.Add(sum);
}
return builder.ToSpread();
}

ReadOnlySpan 作为高性能替代方案

对于热路径输出（例如，每帧模拟数据），ReadOnlySpan 完全避免了内存分配：

csharp
[ProcessNode]
public class ParticleSimulator
{
private ParticleState[] _states;

public ReadOnlySpan Update(SimulationConfig config, float deltaTime)
{
// 模拟到预分配的数组 — 零分配
Simulate(_states, config, deltaTime);
return _states.AsSpan();
}
}

对于不频繁的配置输入使用 Spread；对于高频帧数据使用 ReadOnlySpan。

性能规则

• - 预分配 builder：当 count 已知时使用 new SpreadBuilder(expectedCount)
• 热路径中避免 LINQ：.Where()、.Select()、.ToList() 会创建隐藏的内存分配
• 缓存 spreads：如果输出不变，返回缓存的 spread 引用
• 避免重复调用 .ToSpread()：构建一次，输出结果
• 对于大型 spreads：内部考虑使用 Span，在 API 边界转换为 Spread
• Spread 变化检测：由于 Spreads 是不可变的，引用相等性（!= 或 ReferenceEquals）就足够了 — 如果引用变了，内容就变了

ProcessNodes 中的 Spreads

csharp
[ProcessNode]
public class SpreadProcessor
{
private Spread _lastInput = Spread.Empty;
private Spread _cachedOutput = Spread.Empty;

public void Update(
out Spread output,
Spread input = default)
{
input ??= Spread.Empty;

if (!ReferenceEquals(input, _lastInput))
{
var builder = new SpreadBuilder(input.Count);
foreach (var v in input)
builder.Add(v * 2f);
_cachedOutput = builder.ToSpread();
_lastInput = input;
}

output = _cachedOutput;
}
}

更多代码示例，请参见 examples.md。