TiXL 时间轴 source extent来源范围深入指南时间片段的创作内容跨度、滑动剪辑与自动收集【免费下载链接】t3TiXL is an open source software to create realtime motion graphics.项目地址: https://gitcode.com/GitHub_Trending/t3/t3导读本文围绕 TiXL开源实时动态图形软件时间轴Timeline中时间片段Time Clip的authorized source extent创作来源范围展开它定义了组合composition内部有意义内容的节拍跨度bars并在父级时间线上以“footage region素材区域”的形式呈现。读完本文你将掌握如何通过Combine into New Type...自动初始化来源范围、在标尺上用手柄拖拽并撤销、在父时间线执行滑动剪辑slip edit、通过Reset Source to Extent一键复位以及利用[TimeClipPlayer]的 AutoCollect 让未接线的命令片段自动渲染。本文内容以.tests-manual/source-extent.md手动测试规范为骨架并结合 Editor 与 Operators 仓库源码逐条印证。背景什么是 source extent在 TiXL 4.3 之前一个组合被当作时间片段使用时其内容“有多长”是隐式的父时间线上片段的默认来源范围SourceRange往往需要手工调整。从 4.3 起组合型时间片段算子combined time-clip operators可以携带一个创作出的 source extent——即其有意义内容在 bars 单位下的跨度。从源码看这个值被持久化在每个符号的.t3ui文件 Settings 块中名为Timeline的字段里见 TimelineState.cs。TimelineState.SourceExtent是编辑器元数据它承担两个职责新片段实例的默认 SourceRange父时间线上**footage region素材区域**的显示。TimelineState还刻意说明当SourceExtentStart/SourceExtentEnd任一缺失即从未创作过时返回null消费者会回退到派生范围。JSON 序列化时以两个 float 存储避免TimeRange计算属性的干扰并使用NullValueHandling.Ignore保证未创作时文件干净。4.3 的行为变更文档明确指出一个破坏性变更片段内部旧的 Alt-拖动范围操作被移除。橙色阴影shaded range在源范围之外仍会绘制但不再出现拖动手柄Alt 拖动不再产生任何效果——范围编辑改由两个入口完成进入符号后在标尺上拖动extent handles在父时间线上拖动footage region滑动剪辑。Step 1Combine 自动初始化 extent操作在组合中于 bar 2 到 bar 6 之间给两个算子制作关键帧动画。选中两者右键 →Combine into New Type...勾选Combine as time clip命名为MyTransition。双击时间线上的新片段进入其内部。预期结果标尺显示一条深色带在 bar 2 和 bar 6 各有一个细竖手柄即合并关键帧的并集父时间线上的片段实例恰好以该范围作为其来源范围创建。源码印证CombineAsNewType在生成新符号后调用InitSourceExtentFromContent(newSymbolUi)见 Combine.cs。该函数遍历新符号的所有子算子对每个子算子的每个输入定义通过Animator.TryGetCurvesForChildInput取曲线再遍历所有VDefinition.U把关键帧时间并入范围对每个输出若OutputData是TimeClip则把其TimeRange并入范围嵌套片段也参与并集。最终以TimeRange.Undefined起算做Unite若结果无效或时长为 0例如纯静态算子则跳过、不写 extent见 Combine.cs。这正是“深色带 合并内容并集”的底层来源。Step 2拖动 extent 手柄并撤销操作进入MyTransition将鼠标悬停在标尺上 bar 6 的右端手柄。预期结果鼠标光标变为水平调整大小光标ResizeEW手柄提亮为纯白。源码印证SourceExtentEditor.EmitHandle使用ImGui.InvisibleButton创建一个命中区域半宽5 * scale悬停时调用ImGui.SetMouseCursor(ImGuiMouseCursor.ResizeEW)并通过hovered || active控制手柄颜色未激活时淡化为 0.8 透明度悬停/激活时全亮见 SourceExtentEditor.cs。操作把右手柄拖到 bar 8 后松开然后按CtrlZ。预期结果拖动过程中深色带跟随鼠标并对齐到栅格值按住Shift可绕过吸附松开后深色带结束于 bar 8CtrlZ后回到 bar 6CtrlShiftZ恢复 bar 8父时间线上已有的片段实例保持其当前的 in/out——修改 extent 永远不会重定时已放置的片段。源码印证吸附逻辑在EmitHandle的拖动分支非 Shift 时调用_canvas.SnapHandlerForU.TryCheckForSnapping(...)获取吸附后的值SourceExtentEditor自身实现IValueSnapAttractor把 extent 的 Start/End 作为吸附锚点提供给其他元素见 SourceExtentEditor.cs。拖动时设置symbolUi.TimelineState.SourceExtent _dragExtent并约束最小时长minDuration 0.01f避免 start 越过 end。松开时构造ChangeSourceExtentCommand原始值与新值各存一份通过UndoRedoStack.AddAndExecute入栈因此 CtrlZ / CtrlShiftZ 可往返。该命令用符号 ID 而非引用解析符号能安全跨越算子包重载见 ChangeSourceExtentCommand.cs。“不重定时已放置片段”SourceExtentEditor只写入符号 UI 的TimelineState.SourceExtent从不触碰父时间线上任何TimeClip的SourceRange/TimeRange——两个数据域彼此隔离。Step 3父时间线的 Footage 区域操作离开MyTransition将鼠标悬停在父时间线的片段上。预期结果提示框tooltip显示一行Footage: 2.00 ... 8.00与创作的 extent 一致标尺在选择范围条后方显示素材区域尺寸对应 extent——与视频片段获得的显示一致。源码印证TimeClipItem.DrawClip在 body 悬停时构建 tooltip。TryGetContentExtent的解析顺序为先尝试媒体素材视频/音频的时长缓存再回退到片段符号 UI 的TimelineState.SourceExtent见 TimeClipItem.cs。可见 extent 赋予了组合型片段“像媒体素材一样有明确内容边界”的能力。tooltip 中Visible、Source、Footage、Speed各行依次输出当片段被时间拉伸timeRemapped时才显示Source行这与文档中“tooltip Source 与 Footage 不同”的检查点对应。操作拖动片段的结束手柄使其比 extent 映射到的长度更长。预期结果tooltip 的 footage 行追加(reads past end — loops/freezes)。源码印证TryGetContentExtent拿到 extent 后DrawClip用容差比较SourceRange与 extent 的边界±0.001f一旦读取超出素材范围就显示该提示见 TimeClipItem.cs。操作在片段选中状态下把标尺中的 footage 区域左右拖动slip edit。预期结果片段的来源范围发生位移内容在固定的片段窗口下滑动撤销可恢复。源码印证SourceRegionIndicator负责绘制并交互 footage 区域。它计算footageStart/footageEnd由TimeRange.Start (contentExtent - SourceRange) / rate推导在选择范围条左/右/上方发射三个 slip 按钮拖动时以_pressU为基准计算位移d同步平移SourceRange.Start/End乘以_dragRate保持速度并仅吸附到片段自身的边界。拖完通过MoveTimeClipsCommand.StoreCurrentValuesUndoRedoStack.Add入栈见 SourceRegionIndicator.cs。类注释还说明该实现取代了旧版“片段上的 footage 轮廓线”因为后者在相邻片段间难以辨认。Step 4Reset Source to Extent操作在父时间线中滑动MyTransition的 footage 区域使其来源范围不再匹配 extenttooltip 中Source与Footage不同。右键点击片段。预期结果上下文菜单在Clear Time Stretch下方显示Reset Source to Extent对符号没有创作 extent 的片段例如纯[TimeClip]该菜单项不出现。源码印证TimeClipInteractions.DrawContextMenuItems仅在AnySelectedClipHasSourceExtent(compositionOp)为真时才绘制该项见 TimeClipInteractions.cs。判定条件TryGetSourceExtentForClip要求子实例存在、其符号 UI 的SourceExtent非空且时长大于 0。操作点击该项悬停片段然后按CtrlZ。预期结果点击后 tooltip 的Source行与Footage行完全一致CtrlZ恢复滑动后的来源范围。源码印证ResetSourceToExtentOfSelectedClips对每个选中的、有 extent 的片段执行clip.SourceRange extent然后通过MoveTimeClipsCommand记录原始值并入撤销栈见 TimeClipInteractions.cs。这是 extent 创作之前就已放置、其 SourceRange 指向内容之外的实例的恢复路径。Step 5[TimeClipPlayer] 自动收集未接线的命令片段操作在一个通过[Group]渲染的组合中添加[TimeClipPlayer]并把其输出接入 Group。在时间线上添加一个[TimeClip]算子或放置MyTransition不连接其输出。将播放头移到片段范围内。预期结果即使片段未接线其内容也正常渲染图中出现一条淡品红色command 颜色曲线从片段通向[TimeClipPlayer]悬停或选中任一算子时曲线变亮。源码印证TimeClipPlayer的Update在AutoCollect开启时扫描父组合的同级子算子收集所有“TimeClipSlot类型且没有出向连接”的片段输出排除自身和IAudioClipProvider避免与音频图重复驱动并对其调用InvalidateGraph()后执行见 TimeClipPlayer.cs。类注释明确指出这镜像了[AudioClipPlayer]自动收集[AudioClip]的机制实现“把片段拖到时间线它就会渲染”的图形无关路径。片段自身的 time-range 门控与 source 重映射仍然生效。操作把片段的输出直接接入 Group 作为第二个输入。然后关闭播放器的AutoCollect再次移除连线。预期结果接线时指示线消失片段恰好渲染一次经由连线无双重绘制AutoCollect 关闭且未接线时片段停止渲染不绘制任何指示线。源码印证自动收集的判定条件是“time-clip 输出无出向连接”——接线后该片段不再满足条件因此只会经Clips.CollectedInputs或连线执行一次。AutoCollect是InputSlotbool默认关闭见 TimeClipPlayer.cs。扫描缓存只在 Parent 变化重载或Symbol.VersionCounter变化任何编辑时重建避免每帧重扫。操作在不同时间行放置两个未接线、时间重叠、内容不同的片段。预期结果上行片段绘制在下行片段之上。源码印证自动收集列表按执行顺序排序——byLayer b.TimeClip.LayerIndex.CompareTo(a.TimeClip.LayerIndex)让高 LayerIndex更上方的行先执行平局时按 TimeRange.Start 从左到右见 TimeClipPlayer.cs。先执行的命令后绘制因此上行片段覆盖下行与可视堆叠顺序一致。Step 6片段内部 Alt-拖动不再编辑操作再次进入MyTransition按住Alt尝试在时间线底部的阴影范围边界附近拖动4.3 之前的范围编辑交互。预期结果源范围之外的橙色阴影仍会绘制但不再出现拖动手柄按住 Alt 不产生任何变化——范围编辑请使用 extent 手柄或父时间线的滑动拖动。源码印证SourceExtentEditor只对手柄区域发射可交互按钮阴影带本身由AddRectFilled/AddRect纯绘制无任何命中测试见 SourceExtentEditor.csTimeClipInteractions的拖动分支只处理 Body/Start/End 手柄与 CtrlAlt 滑动Alt 单独按下不触发范围编辑。数据模型与序列化小结TimelineState落在.t3ui的Settings.Timeline节点其中与本主题相关的字段为字段类型含义SourceExtentStart/SourceExtentEndfloat?创作来源范围的起止bars任一为空即视为未创作SourceExtentTimeRange?JsonIgnore运行时便捷视图由上面两个 float 组合该状态是每个符号一份、仅编辑器使用的元数据渲染端不直接依赖它父时间线通过TimeClip的SourceRange来自片段实例获得实际来源区间extent 仅作为默认值与 footage 显示依据。因此拖动 extent 手柄不会影响任何已放置片段这正是本特性最值得注意的设计点。延伸阅读手动测试规范原文.tests-manual/source-extent.mdextent 的标尺编辑器带吸附、撤销SourceExtentEditor.cs撤销命令实现ChangeSourceExtentCommand.cs状态持久化TimelineState.csCombine 时自动初始化Combine.csFootage tooltip 与内容范围解析TimeClipItem.cs滑动剪辑交互SourceRegionIndicator.cs上下文菜单与复位命令TimeClipInteractions.cs自动收集未接线片段TimeClipPlayer.cs【免费下载链接】t3TiXL is an open source software to create realtime motion graphics.项目地址: https://gitcode.com/GitHub_Trending/t3/t3创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考