TiXL 关键帧编程实战深入解析 Lib.numbers.anim.utils 的 FindKeyframes 与 SetKeyframes 运算符【免费下载链接】t3TiXL is an open source software to create realtime motion graphics.项目地址: https://gitcode.com/GitHub_Trending/t3/t3导读TiXLt3是一款开源实时动态图形创作软件其运算符库中的Lib.numbers.anim.utils模块提供了两个实验性运算符FindKeyframes读取其他运算符实例的关键帧时间与数值与SetKeyframes向已连接的动画运算符写入关键帧。本文基于 .help/docs/operators/lib/numbers/anim/utils/README.md 展开并结合仓库源码逐层剖析两者的输入输出参数、内部实现原理与底层 Curve 数据结构帮助你掌握在 TiXL 中构建由程序驱动关键帧、再由关键帧驱动动画的交互式工作流。一、模块概览两个运算符的分工Lib.numbers.anim.utils是整个运算符库中专门处理关键帧元操作的工具模块仅包含两个运算符运算符定位核心能力FindKeyframes实验性读取访问另一个运算符实例的关键帧时间keyframe times便于构建依赖设置播放时间的交互场景SetKeyframes实验性写入将关键帧录制record到已连接的动画运算符上官方 README 对两个运算符的定位非常明确FindKeyframes 解决读——把某个动画曲线上的关键帧信息暴露出来供其他逻辑使用SetKeyframes 解决写——程序化地向动画曲线追加或清除关键帧。两者组合即可实现动画数据在运算符之间流转的闭环。详细文档见 FindKeyframes 说明 与 SetKeyframes 说明对应源码位于 FindKeyframes.cs 与 SetKeyframes.cs。二、FindKeyframes读取他人动画的关键帧数据2.1 输入参数名称类型说明ModeInt32取值模式映射为Index/Nearest/SampleAndDistance三种枚举IndexOrTimeSingle在Index模式下为关键帧下标在Nearest与SampleAndDistance模式下为时间值WrapIndexBoolean是否回绕下标取模开启后越界下标会循环回到曲线开头OpIndexInt32从AnimatedOp的多输入连接中选择第几个运算符实例CurveIndexInt32在被选中的运算符实例中选择第几条动画曲线AnimatedOpSingle Required要读取的动画运算符引用必须连接一个已动画化的输出2.2 输出名称类型含义TimeSystem.Single命中的关键帧时间U 值ValueSystem.Single命中的关键帧数值KeyframeCountSystem.Int32目标曲线上的关键帧总数2.3 三种模式的工作方式从 FindKeyframes.cs 的Update()方法可以看出Mode枚举定义了三种完全不同的读取策略1) Index按下标取将IndexOrTime视为关键帧下标。若WrapIndex为真则执行(int)indexOrTime % _keyframes.Count的取模回绕否则执行Math.Abs((int)indexOrTime) % _keyframes.Count即对越界下标取绝对值后再取模保证不会越界。命中后输出该关键帧的U时间与Value数值。该模式适合按顺序轮询整条曲线配合计数器递增即可逐帧遍历关键帧。2) Nearest最近邻将IndexOrTime视为时间值调用TryFindClosestKey()找到距离该时间最近的关键帧。核心算法见 FindKeyframes.cs利用Curve.TryGetPreviousKey()与Curve.TryGetNextKey()分别取得给定时间前后的关键帧再比较两者与目标时间差的绝对值取更近者。适合做吸附类交互——例如把当前播放时间吸附到最近的节拍/关键帧上。3) SampleAndDistance采样 距离这是最另类的模式Time输出的是最近关键帧时间与目标时间的差值closestKey.U - indexOrTimeValue输出的是曲线在目标时间处的采样值通过_curve.GetSampledValue(indexOrTime)插值得到。换句话说它同时给出曲线在该时刻的实际值和该时刻距离最近关键帧的偏移量可用于检测播放头是否贴近某个关键帧或计算关键帧前后的距离差。2.4 关键帧的定位机制TryFindCurveWithIndex()见 FindKeyframes.cs揭示了如何从运算符引用找到曲线的完整链路从AnimatedOp.CollectedInputs[opIndex]取出目标槽位其UpdateAction.Target即被连接的运算符实例通过target.Parent.Symbol.Animator拿到该符号的动画器遍历该实例的全部输入target.Inputs用animator.IsAnimated(symbolChildId, inputId)判断哪些输入被动画化对动画化的输入调用animator.TryGetCurvesForInputSlot()取回其关联曲线集合按CurveIndex计数定位到具体某条曲线。注意OpIndex在读取时会执行Clamp(0, AnimatedOp.CollectedInputs.Count)保证多输入场景下索引安全。同时该运算符实现了IStatusProvider当AnimatedOp未连接时会输出状态消息No animated operator connected to reference并以 Warning 级别呈现见 FindKeyframes.cs帮助你在 UI 上快速定位接线错误。三、SetKeyframes向动画运算符录制关键帧3.1 输入参数名称类型说明TriggerSetBoolean置真时写入关键帧官方文档建议搭配AudioReaction.WasHit使用实现音符/节拍命中即打点TriggerClearBoolean置真时清除目标曲线上的全部关键帧ValueSingle Relevant要写入关键帧的数值OpIndexInt32从AnimatedOp多输入中选择目标运算符实例CurveIndexInt32选择目标曲线AnimatedOpSingle Required目标动画运算符引用文档明确标注这些输入必须是动画化的3.2 输出名称类型含义CurrentValueSystem.Single最近一次写入关键帧的数值3.3 触发与写入逻辑从 SetKeyframes.cs 的实现看写入是边沿触发而非电平触发使用MathUtils.WasTriggered(newState, ref current)见 MathUtils.cs判断TriggerSet/TriggerClear是否从false跳变为true只有发生上升沿的帧才会真正执行写入/清除当TriggerSet.Value为真且该输入未被接线时运算符会自动将其复位为false见 SetKeyframes.cs避免用户手动勾选后忘记取消导致反复触发触发写入时以当前本地时间context.LocalFxTime为关键帧时间调用_curve.AddOrUpdateV(time, new VDefinition { Value value })同时将CurrentValue输出为本次写入的值触发清除时遍历曲线全部VDefinition自后向前逐个调用_curve.RemoveKeyframeAt(vDef.U)移除。与 FindKeyframes 相同SetKeyframes 复用同一套TryFindCurveWithIndex()曲线定位逻辑与IStatusProvider错误提示机制并同样对OpIndex执行 Clamp 保护。四、底层数据结构Curve 与 VDefinition两个运算符之所以能读关键帧、写关键帧依赖的是 Core/DataTypes/Curve.cs 中Curve类对关键帧集合的封装关键帧模型曲线上的每个关键帧是一个VDefinition包含时间U与数值Value等属性FindKeyframes通过_curve.GetVDefinitions().ToList()一次性取出关键帧列表KeyframeCount输出即其数量写入/更新AddOrUpdateV(u, key)Curve.cs会将时间按TimePrecision精度取整后写入若该时间已存在关键帧则更新否则新增同时递增ChangeCount使动画缓存失效并重算——这正是 SetKeyframes 运行时曲线能立刻在编辑器里看到变化的原因删除RemoveKeyframeAt(u)Curve.cs同样按精度取整后移除对应时间的关键帧邻近查询TryGetPreviousKey/TryGetNextKeyCurve.cs基于FindIndexBefore二分定位支撑 FindKeyframes 的 Nearest 模式插值采样GetSampledValue(u)Curve.cs在关键帧之间按插值方式求值支撑 SampleAndDistance 模式若曲线为空或时间非法NaN / 无穷安全返回 0.0。此外动画化的判定由符号级动画器Symbol.Animator完成——只有被动画化的输入槽位才会拥有曲线集合这也是文档强调AnimatedOp必须是动画化的的原因未接动画的运算符引用无法解析出任何曲线。五、实战场景与注意事项5.1 推荐使用方式节奏驱动的关键帧录制官方示例将SetKeyframes.TriggerSet接入AudioReaction.WasHit把AnimatedOp连接到某个被动画化的数值输出上Value输入需要记录的数值——这样每次节拍命中都会在当前播放时间处打下一个关键帧自动构建一条由音乐节奏采样的动画曲线。交互式播放时间控制将FindKeyframes的输出Time作为另一个运算符的播放时间输入文档指出这正是 FindKeyframes 设计初衷——构建依赖设置播放时间的交互场景。例如用 Nearest 模式把播放头吸附到最近的节拍关键帧实现回放对齐。遍历与回绕需要循环步进播放某条曲线时使用Index模式配合计数器递增并开启WrapIndex让下标越界后自动回到曲线开头天然形成循环。5.2 注意事项必须连接动画引用两个运算符的AnimatedOp都是Required且要求目标输入已动画化否则曲线解析失败运算符以 Warning 状态提示No animated operator connected to reference多实例多曲线选择当AnimatedOp连接了多个输出MultiInputSlot用OpIndex选择实例每个实例内部可能有多条动画曲线用CurveIndex逐条挑选两者均从 0 开始计数边沿触发语义SetKeyframes 的写入/清除是上升沿触发反复给TriggerSet接布尔值时应保证其存在 0→1 的跳变而不是持续为真实验性定位README 与源码均标注两个运算符为 Experimental实验性接口与行为可能在后续版本调整引用时请关注仓库更新。结语Lib.numbers.anim.utils以两个小巧但内功扎实的运算符把 TiXL 的动画曲线从编辑器里手动画扩展为程序可读写的数据通道FindKeyframes负责把关键帧的时空信息暴露为可路由的输出SetKeyframes负责把运行时的数值按触发写入曲线。二者加上Curve/VDefinition/Animator组成的底层动画数据层构成了 TiXL 中构建节拍同步、交互吸附、程序化动画等高级玩法的基础设施。从 模块 README 出发对照 FindKeyframes.cs 与 SetKeyframes.cs 源码阅读即可彻底掌握这套关键帧编程机制。【免费下载链接】t3TiXL is an open source software to create realtime motion graphics.项目地址: https://gitcode.com/GitHub_Trending/t3/t3创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 TiXL 关键帧编程实战：深入解析 Lib.numbers.anim.utils 的 FindKeyframes 与 SetKeyframes 运算符
TiXL 关键帧编程实战深入解析 Lib.numbers.anim.utils 的 FindKeyframes 与 SetKeyframes 运算符【免费下载链接】t3TiXL is an open source software to create realtime motion graphics.项目地址: https://gitcode.com/GitHub_Trending/t3/t3导读TiXLt3是一款开源实时动态图形创作软件其运算符库中的Lib.numbers.anim.utils模块提供了两个实验性运算符FindKeyframes读取其他运算符实例的关键帧时间与数值与SetKeyframes向已连接的动画运算符写入关键帧。本文基于 .help/docs/operators/lib/numbers/anim/utils/README.md 展开并结合仓库源码逐层剖析两者的输入输出参数、内部实现原理与底层 Curve 数据结构帮助你掌握在 TiXL 中构建由程序驱动关键帧、再由关键帧驱动动画的交互式工作流。一、模块概览两个运算符的分工Lib.numbers.anim.utils是整个运算符库中专门处理关键帧元操作的工具模块仅包含两个运算符运算符定位核心能力FindKeyframes实验性读取访问另一个运算符实例的关键帧时间keyframe times便于构建依赖设置播放时间的交互场景SetKeyframes实验性写入将关键帧录制record到已连接的动画运算符上官方 README 对两个运算符的定位非常明确FindKeyframes 解决读——把某个动画曲线上的关键帧信息暴露出来供其他逻辑使用SetKeyframes 解决写——程序化地向动画曲线追加或清除关键帧。两者组合即可实现动画数据在运算符之间流转的闭环。详细文档见 FindKeyframes 说明 与 SetKeyframes 说明对应源码位于 FindKeyframes.cs 与 SetKeyframes.cs。二、FindKeyframes读取他人动画的关键帧数据2.1 输入参数名称类型说明ModeInt32取值模式映射为Index/Nearest/SampleAndDistance三种枚举IndexOrTimeSingle在Index模式下为关键帧下标在Nearest与SampleAndDistance模式下为时间值WrapIndexBoolean是否回绕下标取模开启后越界下标会循环回到曲线开头OpIndexInt32从AnimatedOp的多输入连接中选择第几个运算符实例CurveIndexInt32在被选中的运算符实例中选择第几条动画曲线AnimatedOpSingle Required要读取的动画运算符引用必须连接一个已动画化的输出2.2 输出名称类型含义TimeSystem.Single命中的关键帧时间U 值ValueSystem.Single命中的关键帧数值KeyframeCountSystem.Int32目标曲线上的关键帧总数2.3 三种模式的工作方式从 FindKeyframes.cs 的Update()方法可以看出Mode枚举定义了三种完全不同的读取策略1) Index按下标取将IndexOrTime视为关键帧下标。若WrapIndex为真则执行(int)indexOrTime % _keyframes.Count的取模回绕否则执行Math.Abs((int)indexOrTime) % _keyframes.Count即对越界下标取绝对值后再取模保证不会越界。命中后输出该关键帧的U时间与Value数值。该模式适合按顺序轮询整条曲线配合计数器递增即可逐帧遍历关键帧。2) Nearest最近邻将IndexOrTime视为时间值调用TryFindClosestKey()找到距离该时间最近的关键帧。核心算法见 FindKeyframes.cs利用Curve.TryGetPreviousKey()与Curve.TryGetNextKey()分别取得给定时间前后的关键帧再比较两者与目标时间差的绝对值取更近者。适合做吸附类交互——例如把当前播放时间吸附到最近的节拍/关键帧上。3) SampleAndDistance采样 距离这是最另类的模式Time输出的是最近关键帧时间与目标时间的差值closestKey.U - indexOrTimeValue输出的是曲线在目标时间处的采样值通过_curve.GetSampledValue(indexOrTime)插值得到。换句话说它同时给出曲线在该时刻的实际值和该时刻距离最近关键帧的偏移量可用于检测播放头是否贴近某个关键帧或计算关键帧前后的距离差。2.4 关键帧的定位机制TryFindCurveWithIndex()见 FindKeyframes.cs揭示了如何从运算符引用找到曲线的完整链路从AnimatedOp.CollectedInputs[opIndex]取出目标槽位其UpdateAction.Target即被连接的运算符实例通过target.Parent.Symbol.Animator拿到该符号的动画器遍历该实例的全部输入target.Inputs用animator.IsAnimated(symbolChildId, inputId)判断哪些输入被动画化对动画化的输入调用animator.TryGetCurvesForInputSlot()取回其关联曲线集合按CurveIndex计数定位到具体某条曲线。注意OpIndex在读取时会执行Clamp(0, AnimatedOp.CollectedInputs.Count)保证多输入场景下索引安全。同时该运算符实现了IStatusProvider当AnimatedOp未连接时会输出状态消息No animated operator connected to reference并以 Warning 级别呈现见 FindKeyframes.cs帮助你在 UI 上快速定位接线错误。三、SetKeyframes向动画运算符录制关键帧3.1 输入参数名称类型说明TriggerSetBoolean置真时写入关键帧官方文档建议搭配AudioReaction.WasHit使用实现音符/节拍命中即打点TriggerClearBoolean置真时清除目标曲线上的全部关键帧ValueSingle Relevant要写入关键帧的数值OpIndexInt32从AnimatedOp多输入中选择目标运算符实例CurveIndexInt32选择目标曲线AnimatedOpSingle Required目标动画运算符引用文档明确标注这些输入必须是动画化的3.2 输出名称类型含义CurrentValueSystem.Single最近一次写入关键帧的数值3.3 触发与写入逻辑从 SetKeyframes.cs 的实现看写入是边沿触发而非电平触发使用MathUtils.WasTriggered(newState, ref current)见 MathUtils.cs判断TriggerSet/TriggerClear是否从false跳变为true只有发生上升沿的帧才会真正执行写入/清除当TriggerSet.Value为真且该输入未被接线时运算符会自动将其复位为false见 SetKeyframes.cs避免用户手动勾选后忘记取消导致反复触发触发写入时以当前本地时间context.LocalFxTime为关键帧时间调用_curve.AddOrUpdateV(time, new VDefinition { Value value })同时将CurrentValue输出为本次写入的值触发清除时遍历曲线全部VDefinition自后向前逐个调用_curve.RemoveKeyframeAt(vDef.U)移除。与 FindKeyframes 相同SetKeyframes 复用同一套TryFindCurveWithIndex()曲线定位逻辑与IStatusProvider错误提示机制并同样对OpIndex执行 Clamp 保护。四、底层数据结构Curve 与 VDefinition两个运算符之所以能读关键帧、写关键帧依赖的是 Core/DataTypes/Curve.cs 中Curve类对关键帧集合的封装关键帧模型曲线上的每个关键帧是一个VDefinition包含时间U与数值Value等属性FindKeyframes通过_curve.GetVDefinitions().ToList()一次性取出关键帧列表KeyframeCount输出即其数量写入/更新AddOrUpdateV(u, key)Curve.cs会将时间按TimePrecision精度取整后写入若该时间已存在关键帧则更新否则新增同时递增ChangeCount使动画缓存失效并重算——这正是 SetKeyframes 运行时曲线能立刻在编辑器里看到变化的原因删除RemoveKeyframeAt(u)Curve.cs同样按精度取整后移除对应时间的关键帧邻近查询TryGetPreviousKey/TryGetNextKeyCurve.cs基于FindIndexBefore二分定位支撑 FindKeyframes 的 Nearest 模式插值采样GetSampledValue(u)Curve.cs在关键帧之间按插值方式求值支撑 SampleAndDistance 模式若曲线为空或时间非法NaN / 无穷安全返回 0.0。此外动画化的判定由符号级动画器Symbol.Animator完成——只有被动画化的输入槽位才会拥有曲线集合这也是文档强调AnimatedOp必须是动画化的的原因未接动画的运算符引用无法解析出任何曲线。五、实战场景与注意事项5.1 推荐使用方式节奏驱动的关键帧录制官方示例将SetKeyframes.TriggerSet接入AudioReaction.WasHit把AnimatedOp连接到某个被动画化的数值输出上Value输入需要记录的数值——这样每次节拍命中都会在当前播放时间处打下一个关键帧自动构建一条由音乐节奏采样的动画曲线。交互式播放时间控制将FindKeyframes的输出Time作为另一个运算符的播放时间输入文档指出这正是 FindKeyframes 设计初衷——构建依赖设置播放时间的交互场景。例如用 Nearest 模式把播放头吸附到最近的节拍关键帧实现回放对齐。遍历与回绕需要循环步进播放某条曲线时使用Index模式配合计数器递增并开启WrapIndex让下标越界后自动回到曲线开头天然形成循环。5.2 注意事项必须连接动画引用两个运算符的AnimatedOp都是Required且要求目标输入已动画化否则曲线解析失败运算符以 Warning 状态提示No animated operator connected to reference多实例多曲线选择当AnimatedOp连接了多个输出MultiInputSlot用OpIndex选择实例每个实例内部可能有多条动画曲线用CurveIndex逐条挑选两者均从 0 开始计数边沿触发语义SetKeyframes 的写入/清除是上升沿触发反复给TriggerSet接布尔值时应保证其存在 0→1 的跳变而不是持续为真实验性定位README 与源码均标注两个运算符为 Experimental实验性接口与行为可能在后续版本调整引用时请关注仓库更新。结语Lib.numbers.anim.utils以两个小巧但内功扎实的运算符把 TiXL 的动画曲线从编辑器里手动画扩展为程序可读写的数据通道FindKeyframes负责把关键帧的时空信息暴露为可路由的输出SetKeyframes负责把运行时的数值按触发写入曲线。二者加上Curve/VDefinition/Animator组成的底层动画数据层构成了 TiXL 中构建节拍同步、交互吸附、程序化动画等高级玩法的基础设施。从 模块 README 出发对照 FindKeyframes.cs 与 SetKeyframes.cs 源码阅读即可彻底掌握这套关键帧编程机制。【免费下载链接】t3TiXL is an open source software to create realtime motion graphics.项目地址: https://gitcode.com/GitHub_Trending/t3/t3创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考