TiXL animators 动画算子家族：基于 BPM 的 LFO 信号、序列器与触发动画实战指南

• 音视频
• 图形学
• 桌面应用

导读

TiXL（开源实时动态图形软件）的Lib.numbers.anim.animators是一组专门用于生成时间驱动动画信号的算子集合，覆盖布尔触发、整数循环、浮点 LFO、二维/三维向量振荡与逐拍序列器。阅读本文后，你将掌握每个算子的输入输出含义、底层波形计算原理（AnimMath波形函数与 Schlick Bias 算法）、如何在图中通过 Ctrl+左键拖拽调节动画，以及如何结合SetSpeedFactors、GetBpm等 VJ 工具实现与 BPM 严格同步的实时演出动画。

本文主体对应仓库文档 .help/docs/operators/lib/numbers/anim/animators/README.md，并深入到 AnimMath.cs、AnimValue.cs、TriggerAnim.cs、SequenceAnim.cs 等源码实现。

一、animators 家族总览

Lib.numbers.anim.animators位于 TiXL 算子库的numbers/anim命名空间下，是动画算子体系中最常用的子集之一。与其并行的还有time（时间/节拍工具）、utils（关键帧工具）和vj（BPM 与速度因子工具）三个子命名空间，共同构成完整的节拍动画解决方案。

该命名空间共包含 9 个算子，按其功能可分成四组：

注：上方索引文档为自动从算子库生成，每个算子均配有独立页面（如 AnimValue.md），部分页面的描述由 TiXL 编辑器内的算子描述自动填充，未填写的算子会显示占位提示。

二、AnimValue：核心 LFO 信号发生器

AnimValue 是整个家族的"发动机"——生成一个与当前 BPM 严格同步的重复 LFO 类信号，支持多种波形（shapes）、模式（modes）与形式（forms）。

2.1 关键特性

• BPM 同步：信号频率与当前 BPM 速率挂钩，动画天然贴合音乐节拍；
• 图形化编辑：在节点图中按住Ctrl + 鼠标左键拖拽，即可直接操纵信号的 Rate（速率）与 Shape（波形），无需手动输入参数；
• 速度因子覆盖：可通过 SetSpeedFactors 覆盖传入的 Rate，这在现场 VJ 演出中非常实用；
• 示例资源：官方提示可参考HowToAnimate演示工程查看应用场景。

2.2 输入参数详解

2.3 输出

其中WasHit在归一化时间的整数部分发生变化时置位，可视为"每个周期触发一次"的节拍脉冲信号，常用于驱动触发类效果。

2.4 源码级原理解析

从 AnimValue.cs 可以看到其核心计算流程：

var time = OverrideTime.HasInputConnections ? OverrideTime.GetValue(context) : context.LocalFxTime; _normalizedTime = (time) * rateFactorFromContext * rate + phase; Result.Value = AnimMath.CalcValueForNormalizedTime(_shape, _normalizedTime, 0, bias, ratio) * amplitude + offset;

几个关键实现事实：

1. 时间源选择：当OverrideTime有输入连接时使用其值，否则回退到context.LocalFxTime（本地特效时间）。
2. 速度因子：AnimMath.GetSpeedOverrideFromContext(context, AllowSpeedFactor)会从求值上下文读取 SpeedFactorA/B 并乘入速率，这正是"与 BPM 保持节拍同步"的实现基础。
3. 波形映射：归一化时间交给AnimMath.CalcValueForNormalizedTime，先对时间取模（MathUtils.Fmod(time, 1)）再除以 Ratio 并 Clamp 到 [0,1]，得到周期内的归一化位置。

WasHit的判定逻辑（AnimValue.cs）：

if (Math.Abs(context.LocalFxTime - _lastUpdateTime) > double.Epsilon) { _lastUpdateTime = context.LocalFxTime; WasHit.Value = (int)originalTime != (int)_normalizedTime; }

即归一化时间的整数部分发生跳变（跨过整数边界）时输出 true，等价于"每拍/每周期命中一次"。

2.5 波形形状与 Schlick Bias

波形枚举定义在 AnimMath.cs：

Endless, Ramps, Saws, KickSaws, Square, ZigZag, Wave, Sin, PerlinNoise, PerlinNoiseSigned, Random, RandomSigned, Steps

每种波形的归一化位置到输出值的映射函数（AnimMath.cs）：

所有波形（除 Sin、RandomSigned、PerlinNoiseSigned 外）均经过Schlick Bias整形（AnimMath.cs）：

return x / ((1 / bias - 2) * (1 - x) + 1);

Bias 参数可平滑地将曲线"压向"两端（bias 越接近 0 曲线越早饱和，越接近 1 曲线越晚抬升），而带负值的波形使用SchlickBiasWithNegative在 [-1,1] 区间内做对称整形。这就是Bias输入参数在底层的作用原理。

三、向量与浮点列表动画：AnimVec2 / AnimVec3 / AnimFloatList

3.1 AnimVec2 / AnimVec3

AnimVec2 与 AnimVec3 是 AnimValue 的向量版本，输出System.Numerics.Vector2/Vector3，常用于直接驱动位置、缩放、颜色分量等多轴属性。二者同样：

• 生成与 BPM 同步的重复 LFO 信号，支持各种形状、模式与形式；
• 支持Ctrl + 左键在图中直接拖拽调节速率与形状；
• 可通过 SetSpeedFactors 覆盖速率，适合现场 VJ 场景。

输入参数上，向量版将标量替换为向量，并额外提供统一缩放因子：

其中RateFactor、AmplitudeFactor可对各轴速率/振幅做统一缩放，便于整体调节而不破坏各轴的相对关系。

3.2 OscillateVec2 / OscillateVec3

OscillateVec2 与 OscillateVec3 是更轻量的正弦辅助算子——"将 2/3 条正弦波组合成一个向量"，本质上是用正弦波驱动各轴分量。它们与 AnimVec 系列、AnimValue 互为参考算子。

参数语义（以 OscillateVec2 为准）：

使用建议：当需要纯粹的"平滑正弦摆动"（如摆动、呼吸、漂浮效果）时，Oscillate 系列比 AnimValue 更直观；当需要方波、锯齿、噪声等更丰富波形或 BPM 速度因子时，应选择 AnimValue / AnimVec 系列。

3.3 AnimFloatList

AnimFloatList 将 LFO 信号扩展为浮点列表输出（List<System.Single>），输入参数覆盖 AnimValue 全部参数（OverrideTime、Shape、Bias、Ratio、AllowSpeedFactor、Rate、Amplitude、Phase、Offset），并额外提供：

它适合需要批量驱动多个同构参数（如粒子系统、渐变取色列表）的场景，每个列表元素独立携带相位/周期偏移。

四、AnimInt 与 AnimBoolean：整数循环与布尔脉冲

4.1 AnimInt

AnimInt 用于"动画化一个整数值"，即产生随时间循环的整数序列。输入参数：

输出：

典型用途：驱动色板索引切换、纹理帧选择、序列步骤跳转等需要离散值的场景。WasHit与 AnimValue 语义一致，用于在每次整数跳变时给出脉冲。

4.2 AnimBoolean

AnimBoolean 生成按节拍循环的布尔脉冲信号，输出TriggerOutput（System.Boolean），输入仅三个参数：Rate（速度）、Phase（相位）、AllowSpeedFactor（速度因子切换）。它适合将节拍转化为开关信号，例如按拍闪烁的灯光、节拍触发的图层显隐。

注意：该算子的文档描述尚未在编辑器内填写（显示占位提示），但参数与输出结构完整，可直接在图中使用；如需补充描述可在 TiXL 编辑器中编辑该算子。

五、SequenceAnim：可视化数字序列器

SequenceAnim 创建一个可视化序列器，通过一串数字字符串控制其行为，是制作节拍图案、视觉步进序列的核心工具。

5.1 核心概念

序列以数字字符串形式定义，例如"0123"或跨行的多行序列；SequenceIndex参数可在多行序列中选定某一行的序号（按行首行号为 0 计数）。从 SequenceAnim.cs 可见其内部以字符数组维护序列定义，并可通过SetStepValue在运行时把某个步进值写回序列字符串（'0' + (int)(normalizedValue * 9)），这正是可视化编辑与录制的基础。

5.2 输入参数

5.3 实时录制节奏

根据文档说明，RecordingMode与RecordValue的组合非常适合在演出中用手动敲击（tap）录制节奏：当有输入（如 MidiInput）连接到RecordValue时，算子会检测命中并将其写入当前周期；录制模式可选择连续叠加，或在录制开始时清空完整周期。

从 SequenceAnim.cs 可以看到其对时间回跳的鲁棒性处理：当检测到时间大幅回跳（context.LocalFxTime < _lastUpdateTime - 0.1，即导出/播放重启场景）时，会重置步进索引，保证重新播放时第一个步进能正确触发。

5.4 输出

WasStep在每执行一个新步进时输出脉冲，适合级联驱动其他步进动画或切换效果。

六、TriggerAnim：布尔触发的交互动画

TriggerAnim 用于生成可由布尔值触发的交互式动画值，提供多种形状（Shape）与模式（AnimMode），适合按钮点击、键盘触发、音高检测等交互驱动的过渡动画。

6.1 官方示例接线

文档给出的典型配置：

[HasValueIIncreased]->[TriggerAnim]->[SampleGradient]->[Blob]

即"数值增加检测 → 触发动画 → 采样渐变色 → 输出到 Blob"，将触发信号转化为一条随时间变化的动画曲线并驱动颜色/形状。

6.2 输入参数

6.3 输出

HasCompleted在动画完成后置位，可串联触发链（一个动画完成后再启动下一个）。

6.4 源码级原理解析

从 TriggerAnim.cs 可看到几个关键实现细节：

1. 方向枚举：内部使用Forward / Backwards / None三种方向，配合AnimModes.ForwardAndBackwards（正反播放，触发为正向、释放为反向）和OnlyOnTrue（仅在触发时正向播放一次）等模式。
2. 时间模式（TimeMode）可选择：

Times.PlayTime => context.Playback.TimeInBars, // 播放时间（小节） Times.AppRunTime => Playback.RunTimeInSecs, // 应用运行时间（秒） _ => context.LocalFxTime // 本地特效时间

3. 触发源扩展：除Trigger输入外，当 Trigger 无输入连接时，可通过UseTriggerVar指定的系统变量名触发——读取context.IntVariables中该变量是否为 1。这为 MIDI、OSC 等系统级触发提供了统一入口。
4. 防重复求值：通过比较LocalFxTime与上次更新时间，避免同一帧内重复触发导致输出不一致。

与 AnimValue 类似，也可按住Ctrl在图中直接操纵速率与形状（官方提示 "Hold CTRL to directly manipulate rate and shape in the graph"）。

七、与 VJ 工具的协同：SetSpeedFactors 与 BPM 生态

动画算子家族的强大之处在于与Lib.numbers.anim.vj子命名空间的深度协同。其中最重要的是 SetSpeedFactors：

• 速度因子会乘算到大多数动画算子（如 AnimValue 和 Counter）上，是"保持节拍同步的同时调整视觉节奏"的极强手段；
• 在NormalizedRates 模式下，0.5表示中性（因子 1）；更小代表更慢（1/2、1/4、1/8、1/16、冻结）；更大代表更快（×2、×4、×8、×16、×32）；
• SpeedFactorA作用于 [Counter]；SpeedFactorB作用于 AnimValue、AnimVec2、AnimVec3；
• 为保持灵活性，它同时支持 Image（纹理）与 Commands 类型输出（但二者不可交叉混用）；
• 其输入包括：Commands（Command 必需）、Texture（Texture2D）、SpeedFactorA、SpeedFactorB、ApplyAs。

AllowSpeedFactor参数在动画算子上的取值（None / FactorA / FactorB，见 AnimMath.cs）正是用来声明"本算子接受哪个速度因子通道"，从而让 SetSpeedFactors 的输出能正确路由到对应的动画算子。

此外，vj子命名空间还提供 GetBpm、SetBpm、ForwardBeatTaps 等工具，配合 time 子命名空间中的节拍/时间算子，可搭建完整的"BPM 驱动 → 速度因子调制 → LFO/序列/触发动画 → 视觉输出"链路。这套组合是 TiXL 现场 VJ 与音乐可视化工作流的核心骨架。

八、实战接线建议与常见模式

结合上述算子，以下是在 TiXL 节点图中常用的组合模式：

1. 节拍驱动的循环运动：GetBpm → SetSpeedFactors → AnimVec2（AllowSpeedFactor=FactorB）→ 位置/位移输入，实现严格跟拍的往复运动；
2. 拍点闪烁/显隐：AnimBoolean（Rate 对拍）→ 布尔开关/图层显隐，或用AnimValue → WasHit → 触发闪烁效果；
3. 步进视觉序列：SequenceAnim（Sequence="0123..."，Rate 对拍）→ 步进值驱动色板/形状切换，WasStep可级联下一级动画；
4. 交互式过渡：键盘/OSC → TriggerAnim（AnimMode 选择正反或仅正向）→ SampleGradient → 颜色过渡；
5. 演出中实时变速：SetSpeedFactors的 NormalizedRates 模式可在保持节拍同步的前提下将视觉节奏整体放慢或加快（0.5 中性，向下冻结，向上加速至 ×32）；
6. 节奏录制：MidiInput → SequenceAnim.RecordValue，用RecordingMode控制叠加录制或清空重录，现场即兴编排步进图案。

在搭建以上链路时，记得大部分 LFO 类算子支持Ctrl + 左键拖拽直接在图上调节速率与波形，调试体验更加直观。

九、参考资料

• 命名空间索引：animators/README.md、anim/README.md
• 各算子文档：AnimValue.md、AnimVec2.md、AnimVec3.md、OscillateVec2.md、OscillateVec3.md、SequenceAnim.md、TriggerAnim.md
• 底层波形与速度因子实现：AnimMath.cs
• 算子源码：AnimValue.cs、TriggerAnim.cs、SequenceAnim.cs、OscillateVec2.cs
• VJ 协同工具：SetSpeedFactors.md、GetBpm.md

• 音视频
• 图形学
• 桌面应用