企业官网建设流程全解析

TiXL 实时渲染分辨率控制指南：深入解析 SetRequestedResolutionCmd 命令算子

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

导读

本文围绕 TiXL（实时动态图形创作软件）中位于Lib.flow.context命名空间的SetRequestedResolutionCmd命令算子展开，讲解如何在 Command 数据流中按需改写渲染上下文（EvaluationContext）的请求分辨率，从而影响输出窗口、相机投影比例与后续渲染算子的实际工作分辨率。读完本文，你将掌握该算子 4 个输入参数的完整语义与默认值、分辨率计算与钳制公式、上下文作用域恢复机制，以及它与 Texture2D 版本SetRequestedResolution的差异与选型方法。

一、算子定位：上下文（Context）家族中的分辨率改写命令

SetRequestedResolutionCmd属于 Lib.flow.context 运算符集合，与SetFloatVar、SetIntVar、GetPosition等算子同属一类——它们不直接生成可见内容，而是对传递中的EvaluationContext（求值上下文）进行读写，从而影响图后续部分的行为。

从类型上看，该算子的输入与输出都是Command（命令），因此它是一段“命令流中的改写节点”：上游传入一个 Command，它在执行时悄悄修改上下文中的RequestedResolution字段，再把 Command 原样向下游传递。

注意：TiXL 仓库中存在两个名字相近的算子——SetRequestedResolutionCmd（本文主角，Command 版本，位于 flow/context）与SetRequestedResolution（Texture2D 版本，位于 render/shading）。两者核心机制一致，但面向的数据类型不同，后文会专门对比。

二、输入参数与输出（继承自官方文档）

输出：

该算子在编辑器中的默认配置见序列化文件 SetRequestedResolutionCmd.t3：

{ "FormatVersion": 3, "Id": "8a104da8-3995-421f-b756-b6fc06953be3", "Inputs": [ { "Id": "58b2a52c-ece7-420b-9730-e3d0406a5616" /*Resolution*/, "DefaultValue": { "X": 0, "Y": 0 } }, { "Id": "a4d09d43-5f81-4b15-85db-e03f917b9764" /*ScaleResolution*/, "DefaultValue": 1.0 }, { "Id": "b05d30d3-3bc4-4517-bd3d-ed2d26f87646" /*StretchResolution*/, "DefaultValue": { "X": 1.0, "Y": 1.0 } }, { "Id": "c59596ca-984f-4682-88d3-808c60665414" /*Texture*/, "DefaultValue": null } ], "Children": [], "Connections": [] }

从默认值可以看出：默认Resolution为(0, 0)（即“不主动改分辨率”），ScaleResolution为1.0，StretchResolution为(1.0, 1.0)——所有参数处于“惰性”状态，此时算子仅透传 Command，不产生任何分辨率改写。

三、底层实现：Update 方法逐行拆解

该算子的核心逻辑位于 SetRequestedResolutionCmd.cs，实现要点如下：

private void Update(EvaluationContext context) { var previousResolution = context.RequestedResolution; var resolutionFactor = ScaleResolution.GetValue(context); var requestedResolution = Resolution.GetValue(context); var resolutionStretch = StretchResolution.GetValue(context); var resolutionUpdate = requestedResolution.X > 0 && requestedResolution.Y > 0 && resolutionStretch.X > 0 && resolutionStretch.Y > 0; var newResolution = resolutionUpdate ? requestedResolution : previousResolution; context.RequestedResolution = new Int2((int)(newResolution.X * resolutionFactor * resolutionStretch.X).Clamp(1, 16384), (int)(newResolution.Y * resolutionFactor * resolutionStretch.Y).Clamp(1, 16384)); Result.Value = Texture.GetValue(context); context.RequestedResolution = previousResolution; }

逐行解读其行为：

1. 暂存旧值：先把context.RequestedResolution保存到局部变量，用于作用域结束时恢复。
2. 读取三个输入：ScaleResolution（缩放系数）、Resolution（目标分辨率）、StretchResolution（拉伸系数）分别从输入槽取值。
3. 有效性判断（关键）：只有Resolution.X > 0 && Resolution.Y > 0 && StretchResolution.X > 0 && StretchResolution.Y > 0同时成立时，才认为“本次要改写分辨率”；否则沿用上下文中原有的分辨率。这解释了默认值(0,0)的惰性语义——不填就不生效。
4. 合成最终分辨率：最终分辨率 =目标分辨率 × 缩放系数 × 拉伸系数，并且每个分量都通过.Clamp(1, 16384)钳制在[1, 16384]像素之间。16384对应 16K 分辨率的上限，这是 TiXL 对渲染目标尺寸的安全边界。
5. 透传命令：把上游Texture（Command）输入的值赋给Result输出槽，完成命令的“原样转发”。
6. 作用域恢复：在 Update 返回前，将context.RequestedResolution恢复为previousResolution——该算子只在自身执行期间临时改写分辨率，不会污染下游无关分支。这也是它被命名为 Command 算子的意义：分辨率改写被封装在一个命令作用域内，随执行结束而撤销。

从实现细节看，(int)强转意味着分辨率必须为整数像素，这与 Int2 类型的输入约束一致。

四、RequestedResolution 的作用域与影响面

被改写的context.RequestedResolution定义在 EvaluationContext.cs（public Int2 RequestedResolution { get; set; }），它属于 TiXL 求值上下文的核心字段之一，直接影响：

• 相机投影矩阵的宽高比：在 EvaluationContext.cs 的SetViewFromCamera与SetDefaultCamera中，aspectRatio = RequestedResolution.Width / RequestedResolution.Height被用来构造透视投影矩阵（PerspectiveFovRH）。因此，改分辨率会同步改变后续渲染的宽高比与视锥体形状。
• 抗锯齿/抖动偏移量：CameraJitter.cs 使用RequestedResolution.Width/Height将像素级抖动偏移换算为裁剪空间偏移（M31/M32），以支撑 TXAA 等抖动采样方案。分辨率不同，抖动换算结果不同。
• 下游渲染算子：许多纹理输出算子会依据上下文中的请求分辨率创建或调整渲染目标，因此把本算子放在渲染节点之前，即可控制该渲染的实际输出尺寸。

关于作用域：SetRequestedResolutionCmd的执行模型是“在执行期间临时修改、结束后恢复”，与SetRequestedResolution（Texture2D 版本）在 SetRequestedResolution.cs 中的实现完全一致（后者同样保存previousResolution并在末尾恢复）。这种模式确保多个分辨率改写节点串联时互不干扰。

五、与 SetRequestedResolution（Texture2D 版）的差异与选型

选型建议：

• 若你的下游是一个Command 驱动的渲染流程（例如在命令图分支中临时切换输出规格），使用SetRequestedResolutionCmd，其额外的StretchResolution能独立地拉伸宽与高，适合非等比变形、像素风格化等场景。
• 若你处理的是Texture2D 数据流，且只需简单的“指定分辨率 + 可选缩放”，可使用 SetRequestedResolution.md 所描述的 Texture2D 版本。

六、典型使用场景

1. 局部高分辨率渲染：在渲染某个细节算子前插入本节点，设置Resolution为(3840, 2160)、ScaleResolution = 1.0，即可让该段渲染以 4K 分辨率执行，而整体输出窗口仍保持原始规格。
2. 非等比像素拉伸：利用StretchResolution（如(0.5, 1.0)）单独压缩 X 方向，配合下游纹理采样制造 CRT、复古像素风效果。
3. 分辨率缩放链：用ScaleResolution作为统一缩放旋钮（0.25 / 0.5 / 1.0），在性能与质量之间快速切换；结合Clamp(1, 16384)的边界，可放心接受任意倍率输入而不会产生非法渲染目标。
4. 相机宽高比联动：由于 EvaluationContext.cs 会用该字段计算相机投影宽高比，改变分辨率也会同步改变渲染视口的画面比例，适合在同一场景内切换竖屏/横屏构图。

七、使用注意事项

• 惰性生效规则：Resolution任一分量 ≤ 0 时不会改写分辨率（沿用原值），因此未配置时算子等同于“命令透传节点”。
• 边界钳制：最终宽高被强制钳制在1 ~ 16384之间，超出 16K 的请求会被截断。
• 作用域即时性：分辨率改写只在算子执行瞬间生效，执行完毕后恢复原值；若希望分辨率在较长渲染链中持续生效，需要将整条链置于该命令的作用域内（即把本算子放在该链的输入端）。
• 文档状态说明：官方自动生成的算子文档页（即本文依据的 SetRequestedResolutionCmd.md）目前尚无描述文本，本文的参数语义与行为细节均来自仓库源码 SetRequestedResolutionCmd.cs 与序列化默认值文件 SetRequestedResolutionCmd.t3，读者如需更深层的分辨率传递机制，可继续阅读 EvaluationContext.cs 中RequestedResolution的全部引用位置。

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