功能设计解析:让图中的隐式关系可见化)
TiXL 参考线Reference Lines功能设计解析让图中的隐式关系可见化【免费下载链接】t3TiXL is an open source software to create realtime motion graphics.项目地址: https://gitcode.com/GitHub_Trending/t3/t3TiXLt3是一个开源实时动态图形创作工具其节点图支持显式连线与多种无线的隐式关系。本篇技术指南以 .agentic/Plans/Plan_ReferenceLines.md 为骨架结合仓库源码系统拆解参考线Reference Lines这一图形功能的设计它如何把 Set/Get 变量、音频自动采集、未来的 Send/Receive 等隐式关系统一渲染为虚线段并支持一键显式化。读完本文你将理解该功能的架构决策、匹配器抽象、渲染通道与可撤销的 realize/inline 动作以及它在 TiXL 编辑器中落地的四个实施阶段。概述什么是参考线在 TiXL 的节点图MagGraph中绝大多数关系通过MagGraphConnection这样的真实连线表达。但还有一类关系是无线的wireless两个算子之间没有物理插槽相连却存在语义上的绑定。最典型的是 Set/Get 变量——SetFloatVar与GetFloatVar之间靠字符串名称匹配而非 GUID 对象引用。参考线功能的核心理念是Make invisible relationships visible.它把悬停时才会出现的变量链接原语泛化为一条持久、虚线、独立渲染通道的关系展示机制覆盖图中所有无线关系——Set/Get 变量、音频自动采集以及未来规划中的 Send/Receive——并附带一个可选动作把隐式链接显式化realize成真实连线。该功能被 .agentic/Plans/Plan_AudioProcessingGraph.md 直接消费用于绘制 clip→root 的音频自动采集线。现状盘点今天已有什么计划文档开篇梳理了当前代码库中与该功能相关的既有实现悬停式变量连线OpUi.DrawVariableReferences见 Editor/Gui/OpUis/OpUi.cs#L132-L164在悬停某个 Set/Get 变量算子时向同一 composition 中同名的兄弟算子绘制一条实线颜色为UiColors.StatusAutomated。它只在悬停时出现调用方是各类型的{Get,Set}*VarUi.cs位于 Editor/Gui/OpUis/UIs/。被取代的旧计划.agentic/Plans/Plan_GetVarHoverLink.mdissue #1077v4.2 里程碑是这份计划的窄化前身本计划将其吸收为 Phase A。缺失的基建TiXL 目前没有虚线绘制原语grep dashed/DrawDashed无结果ImGui 也没有原生虚线、没有持久化的关系渲染通道、没有 realize 动作。从源码看OpUi.DrawVariableReferences的匹配逻辑OpUi.cs#L132-L164非常直白空名称直接返回避免把所有空名输入串起来遍历sourceInstance.Parent.Children过滤出Symbol.Id相同的孩子再比较其variableNameInputId对应输入的值与目标变量名是否相等命中则drawList.AddLine。同时注意它对方向无感——只负责把源实例与共享同名变量的兄弟连起来无论谁是 Set 谁是 Get。SetFloatVarUi展示了悬停侧的调用模式Editor/Gui/OpUis/UIs/SetFloatVarUi.cs#L40-L45// Draw reference lines on hover if (area.Contains(ImGui.GetMousePos())) { OpUi.DrawVariableReferences(drawList, canvas, area.GetCenter(), instance, data.VariableName.Value, Guid.Parse(e6072ecf-30d2-4c52-afa1-3b195d61617b), // GetFloatVar 符号 GUID Guid.Parse(015d1ea0-ea51-4038-893a-4af2f8584631)); // GetFloatVar 变量名输入 GUID }同类模式还出现在SetStringVarUi、SetIntVarUi、SetBoolVarUi、SetVec3VarUi中。而Matrix/Object变量类型没有自定义 UI因此今天不绘制任何连线。Set/Get 变量的底层机制参考线要匹配的模型要理解参考线为什么这样设计必须先弄清变量算子的绑定机制成对算子位于Operators/Lib/flow/context/Get/SetFloatVar、…IntVar、…BoolVar、…StringVar、…Vec2/Vec3/Matrix/ObjectVar。绑定靠字符串名VariableName输入是InputSlotstringGet 与 Set 之间没有 GUID/对象引用。值存放在EvaluationContext上见 Core/Operator/EvaluationContext.cs#L155-L169五个类型化字典——BoolVariables、IntVariables、FloatVariables、ObjectVariables、StringVariables每帧清空并按求值调用栈作用域Set 可以在SubGraph周围 push/pop。这带来一个关键推论真正的 Set→Get 配对是运行时且依赖顺序的编辑器只能按名称静态匹配可能多对多。这个限制是固有的悬停链接早已与之共存。参考线设计明确接受了这一点编辑器侧只做名称匹配不做运行时绑定推断。架构决策参考线如何落地计划文档锁定了五个核心架构决策1. 独立渲染通道而非逐节点悬停新增 partial 类Editor/Gui/MagGraph/Ui/MagGraphCanvas.DrawReferenceLines.cs从MagGraphView.DrawGraph调用插入点位于连接循环之后约 Editor/Gui/MagGraph/Ui/MagGraphCanvas.Drawing.cs#L160-L164 的DrawConnection循环之后、DrawOffscreenIndicators/DrawAutoCollectIndicators之前这样参考线会覆盖在真实连线上方、悬浮在各类 overlay 之下。绘制时遍历_context.Layout.Items。2. 轻量模型而非MagGraphConnection参考线没有插槽。MagGraphConnectionEditor/Gui/MagGraph/Model/MagGraphConnection.cs本质上是 slot-backed 的它有SourceOutput/TargetInput/AsSymbolConnection()并且AsSymbolConnection()会产出 4 个 GUID 的Symbol.Connection见 Core/Operator/Symbol.ConnectionSubClasses.cs。因此参考线引入一个独立轻量模型class MagReferenceLink { MagGraphItem Source; MagGraphItem Target; Color; // 虚线颜色 LinkKind; // 链接类型 }3. 两类匹配器喂养链接列表匹配器类型语义覆盖场景Name-keyed按名匹配静态编辑器侧名称匹配多对多Set/Get 变量VariableName相等、未来的 Send/ReceiveScan / singleton扫描/单例无名称链接是消费者 ⟵ 采集根 / 唯一源音频 clip→root 自动采集AudioClipCollector扫描子节点找根的数据源、音频分析→反应静态AudioAnalysis/AudioAnalysisResult单例_SetAudioAnalysis→AudioReaction其中音频自动采集路径在源码中有实据Core/Audio/AudioClipCollector.cs 的RegisterAutoPlayClips正是扫描 composition 的 children收集实现IAudioClipProvider且AutoPlay为真的算子再逐帧注册到AudioEngine——这是无线但存在的典型例子。4. 虚线渲染是全新基建TiXL 没有虚线原语需要新增一个小的分段线辅助函数重复AddLine或短贝塞尔。绘制端点时复用两条既有先例折叠区段的 reroute-to-proxyEditor/Gui/MagGraph/Ui/MagGraphCanvas.DrawConnection.cs#L48-L73当某个端点被折叠隐藏时把线画到区段的代理位置。DrawOffscreenIndicators用于屏幕外的远端端点。颜色建议重度淡化的UiColors.StatusAutomated与今天的链接一致或从TypeUiRegistry取该值类型的类型色。5. Make explicit 按类型而异——关键前提一对被链接的算子通常没有共享插槽可以直连。例如SetFloatVar输出CommandGetFloatVar输出float。因此 realize 动作必须按链接类型区分音频 clip→root干净案例存在真实插槽对——clip 的AudioReference输出 → root 的MultiInput。Realize 在MacroCommand中执行AddConnectionCommand。这是头等案例first-class case。变量无共享插槽有意义的动作是Inline内联变量——把供给SetVar.Value的源直接改接到GetVar.Result的消费者上然后删除两个变量算子。仅当直连在拓扑上可达同一/父 composition时才有效。这是在AddConnectionCommand之上新增的逻辑区别于音频的 realize。Send/Receive未来设计算子时自带参考插槽对从而获得音频那样干净的 realize而不是变量那种 messy 的内联。可撤销性一切动作都进 Undo 栈所有 realize/inline 动作都通过UndoRedoStack.AddAndExecute执行包装AddConnectionCommand可撤销Do→Symbol.AddConnectionUndo→RemoveConnection再加上任何删除命令统一放进MacroCommand。Symbol.Connection是不可变的 4-GUID 模型见 Core/Operator/Symbol.ConnectionSubClasses.cs。所有权边界纯编辑器侧功能参考线是纯创作/可视化辅助——它活在Editor/Gui/MagGraph由消费者注册匹配器不涉及任何Core运行时改动。这意味着它不会影响求值语义纯粹是编辑器层的表现与编辑辅助。消费者一览计划文档给出了一张清晰的能力矩阵消费者匹配器Make-explicitSet/Get 变量name-keyedInline绕线重接 删除音频 clip → rootPlan_AudioProcessingGraph.mdscanRealize →AddConnectionCommand干净音频分析 → 反应_SetAudioAnalysis→AudioReactionsingleton—仅渲染Send/Receive未来VVVV/Houdini 风格name-keyedRealize设计时带插槽对注意一个 affordance多个消费者的设计意图reference / dataflow / direction 的区分对用户保持不可见。实施阶段四个可独立落地的里程碑Phase A — 变量的虚线参考线通道用MagGraphCanvas.DrawReferenceLines.cs中的持久虚线通道取代悬停式DrawVariableReferences为所有 Set/Get 变量类型注册 name-keyed 匹配器包括今天什么都不画的 Matrix/Object实现虚线辅助函数定义可见性策略。产出所有变量类型的链接持久可见、虚线显示取代 .agentic/Plans/Plan_GetVarHoverLink.md。Phase B — 匹配器抽象 音频消费者泛化为匹配器接口name-keyed scan/singleton注册音频 clip→root 与 analysis→reaction 两类链接。产出音频自动采集以参考线形式显示一条通道同时服务两种链接类型。Phase C — Make-explicit 动作音频RealizeAddConnectionCommand干净的插槽对变量Inline绕线重接 删除受可达性保护两者都通过MacroCommand可撤销。产出点击幽灵线即可把它变成真实连线音频内联变量变量。Phase D — Send/Receive 算子待排期实现带参考插槽对的命名无线链接算子使它们免费获得本功能的渲染name-keyed与 realize干净。产出VVVV/Houdini 风格的 Send/Receive可可视化、可显式化。开放问题设计尚未拍板的五个点计划文档如实列出了五个开放问题作为后续决策依据可见性默认值——始终全量显示但淡化还是仅悬停/选中显示 一个全局显示关系开关变量多的图有杂乱风险。多对多——一个 Set 名喂 N 个 Get反之亦然画所有线还是汇成 hub影响渲染与 inline 两方面。Inline 的可达性——当 Get 位于不同子树时无法直连置灰 inline还是提供部分方案跨 composition——变量通过求值栈在嵌套 comp 间作用域化只在当前 composition 内渲染像今天一样还是跨 breadcrumbs 渲染与 #1077 的时序——如果Plan_GetVarHoverLink.md正在 v4.2 的发布流程中本计划是吸收它还是在其后落地由维护者根据 #1077 状态决定。与其他计划的协作关系取代.agentic/Plans/Plan_GetVarHoverLink.md#1077——悬停链接成为本计划的 Phase A。被消费.agentic/Plans/Plan_AudioProcessingGraph.md 使用其 clip→root 参考线并把音频 realize 作为头等案例——该计划中 Phase D 明确写道由独立的 Plan_ReferenceLines 交付音频是其 first-class realize caseclip→root 有真实插槽对虚线可通过AddConnectionCommand变成实际的AudioReference连线且切换过程无杂音。小结从源码看这个设计的价值参考线功能的工程价值在于统一TiXL 图中存在多种无插槽但有语义的关系过去只能靠悬停实线、自动采集行为或纯靠用户记忆去理解。该计划用一条持久虚线通道 两类匹配器 按类型的 realize 动作把散落在OpUi.DrawVariableReferences、AudioClipCollector、静态音频分析单例中的隐式关系全部纳入同一种可视语言并保持编辑器侧零运行时侵入。对于希望为 TiXL 贡献图形编辑体验的开发者.agentic/Plans/ 目录下的这份计划与 Editor/Gui/MagGraph/、Editor/Gui/OpUis/ 的源码互为印证是理解该项目编辑器架构与关系可视化设计的理想入口。【免费下载链接】t3TiXL is an open source software to create realtime motion graphics.项目地址: https://gitcode.com/GitHub_Trending/t3/t3创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考