TiXL PickFloatList 算子详解:多路 FloatList 输入的选择切换与 Index 索引控制

原创2026-09-20 22:48:301,902 阅读
文章标签:音视频图形学桌面应用

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`,FloatList)

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),可以作为一个真实的接线参考。

接线要点:

  1. 将多路 FloatList 数据源分别连接到 Input 端口(同一端口多次连线即可);
  2. 将整数信号(常量、动画曲线、表达式或外部输入)连接到 Index 端口;
  3. 从 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 是一个实现极简但行为稳健的多路列表选择器:借助 MultiInputSlot 的多路收集、索引取模的越界保护和整路列表的引用透传,它能够安全、高效地在多路 FloatList 数据流之间进行切换,是 TiXL 数值逻辑类算子库中值得掌握的基础构件之一。

登录后查看全文
t3