TiXL 图像颜色运算符 HSE 完全指南：用 HueShift 着色器实时调整色相、饱和度与曝光-育师

TiXL 图像颜色运算符 HSE 完全指南：用 HueShift 着色器实时调整色相、饱和度与曝光

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

导读

HSE 是 TiXL（Lib.image.color 运算符库）中专门用于快速调整 2D 纹理（Texture2D）色相（Hue）、饱和度（Saturation）与曝光（Exposure）的图像处理运算符，常见于实时动态图形的后期调色链中。其独特之处在于：色相不仅可以通过数值参数控制，还能借助一张灰度 Fx Texture（仅读取其绿色通道）逐像素驱动，从而实现按亮度/遮罩区域变化的动态色相偏移。读完本文，你将掌握 HSE 的完整输入输出约定、各参数的取值范围与默认值、底层 HueShift 着色器的数学原理，以及如何将它接入 TiXL 节点图实现实时调色与色相动画。

运算符定位：Lib.image.color 中的快速调色入口

在 TiXL 运算符库中，HSE 属于Lib.image.color分类，该分类统管图像的颜色处理类运算符，分类总览所在的目录下还包含 AdjustColors、ChannelMixer、ColorGrade、ColorGradeDepth、ConvertColors、KeyColor、RemapColor、Tint、ToneMapping 等成员，可参见 Lib.image.color 索引。

文档对 HSE 的定位是"快速"（quickly）：它只暴露 5 个输入参数，聚焦于色相、饱和度、曝光三个最常用的调色维度，适合作为调色链中的第一步或轻量级校正节点；当需要对比度、亮度、暗角、橙青色调（OrangeTeal）、防钳制（PreventClamping）等更多控制项时，文档明确指引使用功能更完整的姊妹运算符 AdjustColors，其底层着色器为img/fx/AdjustColors.hlsl。

输入参数与输出：完整签名与默认值

根据官方文档的输入参数表，并结合 HSE.t3 中记录的默认值与 HSE.t3ui 中记录的 UI 控件范围，可以得到如下完整签名：

名称（相关性与类型）	说明	默认值	UI 范围
Texture2d（Texture2D Required）	输入源纹理，必填	无（必连）	—
Hue（Single）	色相偏移量，0–1 表示绕色环完整旋转一圈	0.0	0.0 – 1.0
FxTexture（Texture2D）	灰度 Fx 纹理，仅绿色通道参与色相控制	无（可选）	—
Saturation（Single）	饱和度增益系数，0 得到灰度，>1 提高饱和	1.0	-2.0 – 2.0
Exposure（Single）	曝光增益系数，1 为原始亮度	1.0	-5.0 – 5.0（步进 0.02）

输出：

名称	类型
Output	T3.Core.DataTypes.Texture2D

以上默认值与范围全部来自仓库中的运算符定义文件：数值默认值记录在 HSE.t3 的Inputs段（Hue=0.0、Exposure=1.0、Saturation=1.0），UI 的 Min/Max/Scale 及分组标题记录在 HSE.t3ui（Hue 归入 "Hue shifting" 组，Saturation 归入 "Extra parameters" 组）。

从 C# 侧看，HSE 的五个输入槽与一个输出槽在 HSE.cs 中通过InputSlot<T>声明：两个InputSlot<T3.Core.DataTypes.Texture2D>（Texture2d、FxTexture）与三个InputSlot<float>（Hue、Saturation、Exposure），输出为Slot<Texture2D>，并带有[Guid]标识符用于图结构序列化。这说明 HSE 是一个纯函数式组合运算符（Instance<HSE>），本身不含渲染逻辑，而是把参数转发给内部的子运算符执行。

底层实现：HSE 其实是一个 HueShift 着色器包装器

从 HSE.t3 的Children段可以看到，HSE 内部实例化了一个名为_multiImageFxSetupStatic的子符号，并将其ShaderPath参数设置为Lib:shaders/img/fx/HueShift.hlsl；图文件中的Connections段把 Texture2d、Hue、FxTexture、Saturation、Exposure 五个输入逐一连接到该子符号的对应槽位，最终结果连回Output。_multiImageFxSetupStatic的宿主实现位于 _multiImageFxSetupStatic.cs，是Lib.image.fx._中用于装配"多图像输入 + 静态着色器"的通用装载器。

真正决定 HSE 行为的核心是 HueShift.hlsl，它接收三路常量参数：

cbuffer ParamConstants : register(b0) { float Hue; float Saturation; float Exposure; }

以及两张纹理输入：inputTexture（register t0，即 Texture2d）与inputFxTexture（register t1，即 FxTexture）。像素着色器psMain的处理流程如下：

采样与预处理：采样输入纹理得到c，将 RGB 钳制到[0.000001, 1000]以保留 HDR 高光信息，Alpha 饱和到[0,1]。
RGB → HSB 转换：调用rgb2hsb()把线性 RGB 变换到色相/饱和度/亮度空间（着色器中使用的是 HSB 模型，亮度轴取q.x * 0.5）。
曝光（Exposure）：hsb.z *= Exposure;直接乘在亮度轴上——值小于 1 压暗、大于 1 提亮，1 保持原样。
色相偏移（Hue + FxTexture 绿色通道）：
```
float hueShift = Hue + fx.g; // 仅取 fx 纹理的绿色通道 hsb.x = mod((hsb.x + hueShift / 1), 1); // 0–1 色环取模
```
注意两点：其一，Hue 的单位是"色环比例"，1.0 代表完整 360° 旋转，因此 UI 范围设为 0–1 恰好覆盖整圈（与 AdjustColors.hlsl 中Hue / 360的度数语义不同）；其二，fx.g正是文档所述"只使用 FxTexture 绿色通道"的出处——rgb2hsb会把彩色 Fx 纹理的灰度亮度换算到其绿色分量附近，因此一张普通灰度图即可直接使用。
饱和度（Saturation）：hsb.y = saturate(hsb.y * Saturation);以乘法增益调整饱和度，0 时完全去饱和（灰度），1 保持原样，大于 1 提高色彩浓度，负值区域被saturate收敛到 0。
HSB → RGB 回写：c.rgb = hsb2rgb(hsb);还原为 RGB 输出，Alpha 通道原样保留。

上述第 4 步与文档中 "The Hue can also be controlled by greyscale Fx Texture (only the green channel is used)" 的描述完全对应，属于可验证的实现事实。

实战用法：静态调色与动态色相动画

在 TiXL 节点图中使用 HSE 的方式非常直接：

基本调色链：将视频/图片纹理接入Texture2d，把Output接到下游显示或合成节点；调节Exposure（默认 1.0）校正明暗，Saturation（默认 1.0）控制色彩浓度，Hue（默认 0.0）做整体色相旋转。三个参数的 UI 范围（Exposure -5~5、Saturation -2~2、Hue 0~1）均在 HSE.t3ui 中定义，可直接在参数面板滑动微调。
按遮罩动态偏色：为FxTexture接入一张灰度遮罩（例如文字、渐变或亮度抠图），使色相偏移量随像素位置变化——遮罩绿色通道越亮处，色相旋转越大，可做出区域化色偏或扫光换色的实时效果。
时间驱动色相循环：将Hue接入 TiXL 的动画曲线或音频节拍同步值，使整个画面色相随时间在 0–1 的色环上循环，是生成循环色调转场的高性价比方案。

相似运算符对比与选型建议

TiXL 在颜色调整领域提供了多个相互补充的运算符（索引见 Lib.image.color README），选型时可参考：

HSE：极简三参数（Hue/Saturation/Exposure），支持 FxTexture 绿色通道驱动色相，适合快速校正与轻量动态色相。
AdjustColors：HSE 的超集，额外提供 Colorize、Contrast、Brightness、Vignette、OrangeTeal、PreventClamping、Background 等控制项（见 AdjustColors.md），对应 AdjustColors.hlsl 中更长的参数缓冲与 S 曲线对比度、防钳制 tone mapping 逻辑。
ColorGrade / ColorGradeDepth：面向 Gain/Gamma/Lift 三段式分级，适合精细的影视级调色，其中 ColorGradeDepth 还能利用深度缓冲实现远近物体的差异化着色。

注意事项与已知限制

HDR 处理：HueShift 着色器在转换前将 RGB 钳制在[1e-6, 1000]，允许一定的 HDR 高光保留，但过曝区域在 HSB 变换后仍可能被saturate收敛，极端亮度下的色相细节有限。
参数语义：Hue是 0–1 色环比例而非角度；Saturation为乘法增益而非百分比；Exposure直接乘在亮度轴上，线性语义下 ±1 约对应一倍/半倍亮度。
FxTexture 通道约定：仅绿色通道生效，彩色纹理接入时请自行换算其绿色分量预期，必要时先用 ConvertColors 等节点预处理成灰度。
必填输入：Texture2d标记为 Required（见 HSE.t3ui 的Relevancy: "Required"），未连接时运算符无法产出有效结果。

小结

HSE 是 TiXL 中"少即是多"的典型代表：它以 5 个输入参数、1 个输出槽的极简接口，封装了 HueShift.hlsl 中 RGB→HSB→RGB 的完整调色流水线，并通过_multiImageFxSetupStatic装配机制与Lib.image.color家族的其他运算符（AdjustColors、ColorGrade 等）形成从快速校正到精细分级的完整调色梯度。理解了它的输入默认值、绿色通道语义与色环比例单位，你就能在实时图形项目中稳定、可预期地使用这枚基础调色节点。