企业官网建设流程全解析

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

AnimValue 是 TiXL 开源实时视觉合成工具中 Lib.numbers.anim.animators 算子库的核心成员，它根据当前 BPM 节拍生成循环往复的 LFO 式信号，并支持多种波形、模式与形态。阅读本文后，你将掌握 AnimValue 全部 9 个输入参数与 2 个输出的含义和默认值、13 种波形的数学本质、Bias/Ratio 的塑形原理，以及如何借助 SpeedFactor 系统让动画在 VJ 现场始终保持节拍同步。

AnimValue 是什么

AnimValue 是一个单值（Single）动画生成算子，其核心定位由官方文档概括为："Generates a repetitive LFO-like signal synced to the current BPM rate. It supports various shapes, modes and forms."——即产生一个与当前 BPM 速率同步的循环 LFO 信号，并支持多种波形、模式与形态。

在节点图中它表现为一个自带迷你波形预览的节点：节点标题显示Anim + 当前波形名，右侧绘制了波形曲线的实时缩略图。由于输出被标记为DirtyFlagTrigger.Animated（见 AnimValue.cs），其输出会随每一帧自动求值刷新，无需手动触发脏标记。

核心计算模型：归一化时间与波形映射

AnimValue 的全部行为浓缩在 AnimValue.cs 的Update()方法中，核心是两行公式：

_normalizedTime = time * rateFactorFromContext * rate + phase; Result.Value = AnimMath.CalcValueForNormalizedTime(_shape, _normalizedTime, 0, bias, ratio) * amplitude + offset;

• 时间源time：若OverrideTime存在输入连接，则使用其值；否则使用context.LocalFxTime（节点图上下文中与 BPM 同步的本地时间）。这解释了文档中 "synced to the current BPM rate" 的含义——默认情况下信号由引擎的节拍化本地时间驱动，rate决定每单位时间完成多少个波形周期。
• rateFactorFromContext：来自 SpeedFactor 系统的速率系数，由AllowSpeedFactor参数控制（详见下文）。
• 波形求值：CalcValueForNormalizedTime（位于 AnimMath.cs）接收波形类型、归一化时间、组件索引、bias 与 ratio，返回-1~1或0~1范围内的原始波形值，最后乘以Amplitude并加上Offset得到最终结果。

也就是说：Phase 平移时间轴 → Rate 缩放周期 → Bias/Ratio 重塑波形形状 → Amplitude/Offset 缩放和平移数值，每个参数职责单一、可叠加。

输入参数详解（含默认值）

以下参数默认值取自算子的实际定义文件 AnimValue.t3，类型与描述依据官方文档并辅以源码注释：

注意OverrideTime在 AnimValue.cs 中通过HasInputConnections判断是否接管时间；未连接时其默认值 0.0 不参与计算，因此该默认值仅在有连接时才有意义。

13 种波形（Shape）的本质

Shape参数映射到 AnimMath.cs 中的AnimMath.Shapes枚举。波形函数在_mapShapes数组（AnimMath.cs）中定义，输入为(Fmod(time,1)/ratio).Clamp(0,1)的周期内归一化比例f：

其中Random/RandomSigned使用MathUtils.XxHash对时间取哈希（AnimMath.cs），保证同一归一化时间在任意帧求值都得到确定值；Steps输出的是周期计数的整数部分，适合做节拍步进计数器。切换Shape时可观察节点自带迷你曲线图的实时变化，直观对照每种波形。

Bias 与 Ratio：塑造波形细节

这两个参数共同决定波形的"形状细节"，底层实现在 AnimMath.cs：

• Ratio：决定周期内上升段占用的比例，源码中波形输入为(Fmod(time,1)/ratio).Clamp(0,1)。Ratio 越小，单个周期内波形被"压缩"到更短时间完成，例如把 Ramps 的 Ratio 降到 0.25，即可得到 1/4 周期上升、其余时间保持末值的节奏感。
• Bias：通过 Schlick 偏置函数重塑曲线，SchlickBias(x, bias) = x / ((1/bias - 2)·(1-x) + 1)；对双极性波形则先归一化再偏置最后还原（SchlickBiasWithNegative）。bias = 0.5时函数退化为线性，小于 0.5 偏向"早期快速到达"，大于 0.5 偏向"后期陡峭爬升"。

节点图内直接拖拽编辑

文档提到"可以用 CTRL+ 鼠标左键在图中直接拖拽调整"。从 AnimValueUi.cs 的实现看，按住CTRL后在波形预览区域拖拽：

• 水平拖拽调整Ratio，范围被Clamp(0.001f, 1f)限制；
• 垂直拖拽调整Bias，范围被Clamp(0.01f, 0.99f)限制。

拖拽时曲线图实时重绘（80 个采样点折线，含上一个周期的 1/4 段预览），并高亮为悬停色提示可编辑状态；节点标题处的Rate标签同样支持拖拽修改速率。这一设计让 VJ 在演出中无需打开参数面板即可快速塑形。

输出：Result 与 WasHit

WasHit的判定逻辑见 AnimValue.cs：比较更新前后的(int)originalTime != (int)_normalizedTime，即每当动画进入新的一拍/周期时触发一次脉冲。它天然适合驱动触发器类逻辑——例如节拍闪白、同步粒子爆发；且该判定以实际求值的context.LocalFxTime变化为前提，避免同一时间点的重复求值产生误触发。

与节拍系统的联动：SpeedFactor 与 SetSpeedFactors

AnimValue 的速率可被外部全局系数覆盖，这是文档重点推荐的 VJ 用法。AllowSpeedFactor映射到 AnimMath.cs 的SpeedFactors枚举：

• None：不使用任何系数，rateFactorFromContext = 1；
• FactorA：从求值上下文的FloatVariables["SpeedFactorA"]读取系数；
• FactorB：从FloatVariables["SpeedFactorB"]读取系数（AnimValue 默认使用此项）。

读取逻辑见 AnimMath.GetSpeedOverrideFromContext：上下文不存在对应变量时回退为 1，因此未接入任何 SpeedFactor 源时动画不受影响。

配合 SetSpeedFactors 算子即可实时改速：SpeedFactorB 专门作用于 AnimValue、AnimVec2、AnimVec3（FactorA 作用于 Counter）。其"归一化速率"语义非常直观：

• 0.5表示中性（系数 1，维持原速）；
• 小于 0.5 表示减速：1/2、1/4、1/8、1/16，直到冻结；
• 大于 0.5 表示加速：×2、×4、×8、×16、×32。

由于系数直接乘入归一化时间（time * rateFactorFromContext * rate），减速/加速永远保持与 BPM 的整数倍对齐关系，这正是"在不破坏节拍同步的前提下调整视觉节奏"的核心机制。

实用技巧与相关算子

1. 用 OverrideTime 接管时间：接入 [time] 算子可将 AnimValue 从 BPM 时钟切换为任意时间轴，用于倒放、伸缩、循环采样等特殊效果（AnimValue.cs）。
2. 多值动画：需要 2D/3D 输出时改用 AnimVec2 与 AnimVec3，二者共享同一套波形与参数体系；OscillateVec2 / OscillateVec3 则是组合多路正弦波的轻量替代。
3. 交互触发：TriggerAnim 用布尔信号触发动画，适合与WasHit或控制器输入联动。
4. 学习示例：官方文档推荐查看HowToAnimateplayground 项目中的实际应用；现场演出时配合 SetSpeedFactors 覆盖传入速率是文档明确强调的高效做法。

默认配置一览（来自 AnimValue.t3）：Rate=1.0、Shape=1(Ramps)、Phase=0、Ratio=1、Amplitude=1、Offset=0、Bias=0.5、AllowSpeedFactor=1(FactorB)。将此节点接入任意 Single 输入（如旋转、透明度、缩放），即可在数秒内获得一个节拍同步、可现场塑形的动画信号。

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