TiXL PickFloatList 算子详解:多路 FloatList 输入的选择切换与 Index 索引控制
TiXL PickFloatList 算子详解:多路 FloatList 输入的选择切换与 Index 索引控制
PickFloatList 是 TiXL 运算符库 Lib.numbers.floats.logic 中负责"多路选择"的算子:它接收一个或多个 FloatList 输入,并通过整数索引 Index 从中挑选出其中一路作为输出。在实时动态图形(realtime motion graphics)项目中,它常被用于音频分析数据、传感器数据等多路列表数据间的切换;阅读本文后,你将掌握它的输入输出语义、底层源码实现原理、边界行为以及与其他相关算子的区分方法。
功能概述
PickFloatList 的中文语义即"拾取一个浮点列表":它本身不产生新的列表数据,而是作为一个选择器,把多路 List<float>(FloatList)中的某一整路原样透传出去。官方文档的定义为:
Picks a FloatList from the connected list inputs.
它属于 Lib.numbers.floats.logic 目录下的逻辑类算子。该目录下与它功能相近的还有 PickFloatFromList,二者的区别会在后文专门说明。
从源码结构看,PickFloatList 对应的实现文件为 PickFloatList.cs,同时仓库中还包含它的符号定义文件 PickFloatList.t3 与界面布局文件 PickFloatList.t3ui,说明它是随 TiXL 运算符库一起预置、可直接在图元编辑器中拖拽使用的标准算子。
输入输出参数详解
官方文档给出了该算子的完整参数表,以下是其内容及结合实现文件的进一步说明:
输入参数
| 名称(类型) | 说明 |
|---|---|
Input(List1 Required,多路输入) |
用于连接一个或多个 FloatList 数据源。类型为 List<float>,必须连接(Required) |
Index(Int32) |
决定使用已连接列表中的哪一路作为输出。默认值为 0,即默认输出第一路 |
补充说明:
- Input 是多路输入(Multi-Input):在 TiXL 的图元编辑器中,这个端口可以反复从同一端口拖出多条连线,每一条连线代表一路独立的
List<float>数据源。源码中它被声明为MultiInputSlot<List<float>>,这决定了它天生支持"一对多"的连接方式。 - Index 默认值为 0:在 PickFloatList.t3 的符号定义中可以看到,
Index的DefaultValue被初始化为0,因此即使不连接任何索引信号,算子也会默认输出第一路输入。 - Input 默认值为空列表:
Input的默认值是{"Values": []},即空列表数组;在实际使用中只有连接了数据源后它才会产生有效输出。
输出参数
| 名称 | 类型 |
|---|---|
| Selected | System.Collections.Generic.List1[System.Single](即 List |
Selected 的输出是整路列表的引用透传,而不是列表中的某个元素。也就是说,PickFloatList 改变的是"选哪一路",被选中那一路列表内部的元素数量与取值都保持原样。
源码实现剖析
PickFloatList 的实现非常精简,核心逻辑集中在 PickFloatList.cs 的 Update 方法中:
[Guid("6832d272-e63f-4ab2-b48c-85466b4ede1b")]
internal sealed class PickFloatList : Instance<PickFloatList>
{
[Output(Guid = "32A7D943-E6AF-4186-9E1A-0800A62523C2")]
public readonly Slot<List<float>> Selected = new();
public PickFloatList()
{
Selected.UpdateAction += Update;
}
private void Update(EvaluationContext context)
{
var connections = Input.GetCollectedTypedInputs();
if (connections == null || connections.Count == 0)
return;
var index = Index.GetValue(context).Mod(connections.Count);
Selected.Value = connections[index].GetValue(context);
}
[Input(Guid = "5A70A1AF-D6C5-43BF-ACB8-FCE2C9A2DE3C")]
public readonly MultiInputSlot<List<float>> Input = new();
[Input(Guid = "b22e2055-ccfd-4379-a3ef-d9b21d347f3d")]
public readonly InputSlot<int> Index = new(0);
}
这段代码体现了以下几个关键实现事实:
1. 多路输入的收集机制。 Input.GetCollectedTypedInputs() 负责把所有已连接输入收集为有序列表。其底层实现在 Core/Operator/Slots/MultiInputSlot.cs 中:它遍历 InputConnections,如果某个连接本身也是多路输入(Multi-Input),会递归展开后并入收集结果(multiInput.GetCollectedTypedInputs()),否则直接将单个连接加入集合。这意味着即使你把多个 PickFloatList 串接,或把别的多路端口直接连进来,收集到的连接顺序依然是确定、可预期的,索引语义不会混乱。
2. 无连接时的空安全处理。 当 connections 为 null 或长度为 0 时,Update 直接返回,Selected 保持上一次的值不变。因此即使输入被断开,算子也不会崩溃或产生非法数据。
3. 索引的循环取模(Mod)行为。 Index.GetValue(context).Mod(connections.Count) 会对索引值做取模运算。这意味着:
- 当
Index超出有效范围(大于等于连接数)时,会自动回绕到有效区间内。例如有 3 路输入,Index = 5时实际选择第5 % 3 = 2路; - 当
Index为负数时,取模同样会映射回合法范围,从而保证任何整数输入都不会导致越界访问; - 这种"永远合法"的特性使
Index特别适合直接连接由时间、动画曲线或外部设备(如 OSC / MIDI)驱动的整数信号,无需额外做 Clamp 处理。
4. 惰性求值与求值上下文。 Update 接收 EvaluationContext context,这是 TiXL 运算符求值系统的标准上下文参数;Selected.UpdateAction += Update 将更新逻辑挂接到输出槽上,符合 TiXL 中"输出槽按需求值"的算子编写约定。
典型使用场景与接线方式
PickFloatList 的典型应用场景包括:
- 多方案数据切换:同时接入多个音频分析结果(如各频段能量列表),用一个随时间变化的
Index在不同的分析结果之间轮换展示; - 状态选择:根据逻辑判断(例如布尔量映射出的 0/1 索引)在两路 FloatList 之间二选一,实现条件化数据流;
- 数组池索引:将多路传感器或录制数据作为列表池,配合动画曲线对
Index进行驱动,实现有序或随机跳变。
仓库中的示例项目 _AnalyzeSound.t3 便在实际的音符分析图中使用了 PickFloatList(子节点 ID 900e52f4-4ebd-4b83-bc4d-51d726ea57a8),可以作为一个真实的接线参考。
接线要点:
- 将多路 FloatList 数据源分别连接到
Input端口(同一端口多次连线即可); - 将整数信号(常量、动画曲线、表达式或外部输入)连接到
Index端口; - 从
Selected输出端口继续引出下游节点。
与 PickFloatFromList 的对比
同样位于 Lib.numbers.floats.logic 下的 PickFloatFromList 与 PickFloatList 名称相似但职责不同,使用时容易混淆:
| 维度 | PickFloatList | PickFloatFromList |
|---|---|---|
| 输出类型 | List<float>(整路列表) |
float(单个浮点值) |
| 选择维度 | 在多路列表之间选一路 | 在单个列表的内部元素之间选一个 |
| 核心语义 | 切换数据源 | 索引取值 |
| 实现位置 | PickFloatList.cs | PickFloatFromList.cs |
从 PickFloatFromList.cs 的源码可以看到,它读取的是单一 Input 列表,再用 Index.GetValue(context).Mod(list.Count) 取出其中的单个元素(Selected.Value = list[index]),与 PickFloatList 的"多路整表切换"在数据粒度上有本质区别。在实际项目里,二者可以组合使用:先用 PickFloatList 选中某一路列表,再交给 PickFloatFromList 或其它算子处理列表内部数据。
相关文件索引
- 官方文档:PickFloatList.md、Lib.numbers.floats.logic 目录索引
- 源码实现:PickFloatList.cs、PickFloatFromList.cs
- 符号定义:PickFloatList.t3
- 底层多路输入机制:MultiInputSlot.cs
- 实际使用示例:_AnalyzeSound.t3
综上,PickFloatList 是一个实现极简但行为稳健的多路列表选择器:借助 MultiInputSlot 的多路收集、索引取模的越界保护和整路列表的引用透传,它能够安全、高效地在多路 FloatList 数据流之间进行切换,是 TiXL 数值逻辑类算子库中值得掌握的基础构件之一。