企业官网建设流程全解析

t3（TiXL）ConvertTime 算子详解：在 Bars 与 Seconds 之间换算时间

【免费下载链接】t3TiXL is an open source software to create realtime motion graphics.项目地址: https://gitcode.com/GitHub_Trending/t3/t3

在 t3（TiXL）实时运动图形引擎中，时间体系默认以Bars（小节）为单位——在 120 BPM 下，1 个时间单位即 2 秒。ConvertTime算子是Lib.numbers.anim.time算子库中负责时间单位换算的核心组件，它可以在秒（Seconds）与小节（Bars）之间相互转换，是编写节拍同步动画、跨时间域计算（如把秒级传感器数据换算为节拍驱动的关键帧）时的基础工具。读完本文，你将掌握ConvertTime的输入参数、Mode 枚举取值、底层 BPM 换算公式，以及它在无播放上下文时的状态降级行为。

算子概览：时间单位换算器

ConvertTime的官方描述为：

Converts time between seconds and bars. （在秒与小节之间转换时间。）

它位于 t3 的 Lib 算子库Lib.numbers.anim.time命名空间下，源码实现见 ConvertTime.cs。该算子的 GUID 为0cd18cbb-e138-4b4b-a800-175fc39c61bf，在 ConvertTime.t3ui 中以SymbolTags: "8"注册。

输入参数

两个输入槽在 C# 侧以固定 GUID 声明，保证项目文件的序列化兼容：

[Input(Guid = "DD9B7590-9D1F-4A3A-AFE7-FA37FEFD5798")] public readonly InputSlot<float> Time = new(); [Input(Guid = "3AD320B9-D1BC-4BDB-B5C8-20CAA721621B", MappedType = typeof(Modes))] public readonly InputSlot<int> Mode = new();

注意Mode槽使用了MappedType = typeof(Modes)特性：编辑器会将这个 Int32 输入渲染为下拉枚举控件，枚举成员即为 ConvertTime.cs 中定义的私有枚举：

private enum Modes { BarsToSeconds, // 值 0：把 Bars 值换算为秒 SecondsToBars, // 值 1：把秒换算为 Bars }

因此Mode = 0表示 Bars→Seconds，Mode = 1表示 Seconds→Bars。根据 ConvertTime.t3 中的默认值定义，Mode默认值为0（BarsToSeconds），Time默认值为0.0。

输出

Result是一个Slot<float>，其 GUID 为2ccb0dad-0d47-4169-9351-97b96e55ad26。当Time或Mode任一输入变化时，输出槽的UpdateAction被触发重新求值。

底层换算原理：BPM 与 240 的由来

ConvertTime本身不含换算逻辑，它委托给全局播放上下文的 Playback 单例：

var time = Time.GetValue(context); if (Playback.Current == null) { _lastErrorMessage = "Can't get BPM rate without value playback"; return; } Result.Value = Mode.GetEnumValue<Modes>(context) switch { Modes.BarsToSeconds => (float)Playback.Current.SecondsFromBars(time), Modes.SecondsToBars => (float)Playback.Current.BarsFromSeconds(time), _ => throw new ArgumentOutOfRangeException() };

换算公式定义在 Playback.cs：

public double BarsFromSeconds(double secs) { return secs * Bpm / 240.0; } public double SecondsFromBars(double bars) { return bars * 240.0 / Bpm; }

这里的240是音乐时值体系的经典常数：1 Bar（四四拍小节）包含 4 个四分音符，1 分钟有 60 秒，所以BPM × 4 × 60 / 240 = BPM/60秒每拍，即 1 小节时长为240 / BPM秒。BpmMath.cs 中也封装了同样语义的工具函数：

public static double BarsPerSecond(double bpm) => bpm / 240.0; public static double BarDurationSeconds(double bpm) => 240.0 / bpm;

代入默认Bpm = 120（见 Playback.cs 中Bpm属性默认值），1 Bar = 2 秒，这也与 Playback.cs 顶部注释中给出的示例一致："at 120 BPM a unit of time is 2 seconds"。

关键推论：换算结果随当前 BPM 动态变化。若你希望某个秒级时长恒定对应同样的 Bars 值，需要锁定 BPM；反之，若把秒值通过ConvertTime转成 Bars 后再驱动动画，动画的绝对时长会随 BPM 变化而伸缩——这正是节拍同步设计的意图所在。

无播放上下文时的状态降级

ConvertTime实现了IStatusProvider接口，这是 t3 算子图错误处理机制的一部分。当Playback.Current == null（例如该算子处于脱离播放器的独立求值环境中）时，算子不会抛出异常，而是：

• 记录错误信息"Can't get BPM rate without value playback"；
• 本次求值不更新Result；
• 通过GetStatusLevel()返回Warning级别状态，编辑器中该算子会显示警告图标与消息。

public IStatusProvider.StatusLevel GetStatusLevel() { return string.IsNullOrEmpty(_lastErrorMessage) ? IStatusProvider.StatusLevel.Success : IStatusProvider.StatusLevel.Warning; }

这种"降级为警告而非中断"的设计保证了算子图在部分上下文缺失时仍可继续运行。

与同库算子的配合

ConvertTime不是孤立存在的，它与 Lib.numbers.anim.time 算子库中的其他时间算子构成完整的时间处理链路：

• Time：返回经过模式选择（Local Fx Time / Local Time / Playback Time / Runtime / Frozen）和速度因子缩放后的当前时间，且自带Units（Bars/Secs）选项——它内部同样调用context.Playback.SecondsFromBars做单位换算，与ConvertTime共享同一套 BPM 公式；
• ClipTime：返回当前时间片段（Local Time）的值，通常以 Bars 计，需要秒值时可接ConvertTime完成 Bars→Seconds 转换；
• StopWatch：可停止/保持的秒表，用于测量任意两个时刻间的持续时长。

一个典型用法是：ClipTime（Bars）→ConvertTime (Mode = BarsToSeconds)→ 得到该时刻对应的秒数，再送入期望以秒为单位的时间算子（如DateTimeInSecs语义下的接口）或视频/音频采样相关算子。

使用注意事项小结

1. Mode 是 Int32 枚举槽：0 = Bars→Seconds，1 = Seconds→Bars；传入其他值会在求值时抛出ArgumentOutOfRangeException。
2. 换算依赖实时 BPM：结果不是静态的，Bpm变化时同一输入会得到不同输出；需要恒定换算时应先固定 BPM 来源。
3. 依赖Playback.Current：播放上下文缺失时算子仅输出警告状态（"Can't get BPM rate without value playback"）而不产生数值。
4. 单精度输出：Result为System.Single，长时间线（大量 Bars 的高精度累计）场景下存在 float 精度上限，属于该算子固有约束。

相关文件索引

【免费下载链接】t3TiXL is an open source software to create realtime motion graphics.项目地址: https://gitcode.com/GitHub_Trending/t3/t3