企业官网建设流程全解析

• 音视频
• 图形学
• 桌面应用

ValuesToTexture 是 TiXL（tooll3）运算符库 Lib.numbers.floats.process 中用于把数值列表实时编码为纹理像素的核心操作符。它最常见的实战场景，是把音频频谱（如 FFT 输出）逐帧写入一张单通道浮点纹理，再交给点采样、着色器等下游节点驱动动画，从而构建音频反应型可视化。读完本文，你将掌握该操作符全部输入参数的含义与取值范围、底层像素公式与纹理布局规则，并能基于 [PlaybackFFT] 与 [LinearSamplePointAttributes] 搭建一套完整的音频可视化管线。

一、操作符定位：为什么需要把"数值"放进"纹理"

在实时图形编程中，数据往往需要从 CPU 侧的普通列表（List<float>）转换为 GPU 可以采样的资源，才能在着色器或缓冲区采样阶段被高效使用。ValuesToTexture 正是这一"数据上屏"环节的桥梁：它接收一个或多个float列表，在每一帧把列表中的数值映射为纹理中对应像素的 R 通道值，输出一张 Texture2D（具体类型为T3.Core.DataTypes.Texture2D）。

官方文档明确给出了一条典型链路：与 PlaybackFFT（返回配乐播放期间的 FFT 频谱缓冲）和 LinearSamplePointAttributes（按点索引而非 UV 采样纹理）组合，即可制作音频反应可视化——FFT 频段能量 → 纹理像素 → 点云亮度/颜色，一气呵成。

二、输入参数详解

官方文档给出的输入参数如下表，下面结合源码逐项展开：

1. Values：多路输入与自动对齐

从源码 ValuesToTexture.cs 可以看到，Values是一个MultiInputSlot<List<float>>，因此可以接入多条数据源：

• 当有连接时，收集所有输入列表，丢弃空列表（Count == 0）；
• 无连接时视为单路输入；
• 最终纹理宽度/高度以最长的列表为基准（sampleCount = max(list.Count)），短列表不足的位置在填充阶段补0f。

这意味着多条长度不一的频谱数据（例如不同频段组的能量）可以自动对齐到同一张纹理上，无需手动补齐。

2. Offset / Gain / Pow：逐像素的数值整形

每个像素值按如下公式计算（源码 L84/L95）：

value = Pow( (list[i] + Offset) * Gain, Pow )

• Offset：先做加法，适合把双极性的音频数据（如 -1~1）平移到正区间；
• Gain：整体缩放，用于放大微弱的频谱能量或压低调门；
• Pow：非线性整形。源码在|Pow| < 0.001f时直接提前返回（L62-L63），避免产生无意义的全 0/全 1 纹理。示例工程中将 Pow 设为3.0以压缩低频大能量、突出高频细节。注意Pow(负数, 非整数幂)会产生 NaN，实际使用时建议先经 Offset 保证底数非负。

3. Direction：控制数据在纹理中的排布方向

Direction为Int32，源码中通过MappedType = typeof(Directions)映射为枚举（L156-L163）：

• Horizontal（0）：每个输入列表占一行，第 i 个数值落在第 i 列；纹理宽 = 最长列表长度，高 = 列表数量；
• Vertical（1）：每个输入列表占一列，第 i 个数值落在第 i 行；纹理宽 = 列表数量，高 = 最长列表长度。

即width/height = (sampleCount, listCount)或(listCount, sampleCount)，具体见 L101-L102。

三、输出：单通道 32 位浮点纹理

输出的纹理具备以下特征（L111-L123）：

• 格式：R32_Float，单通道、每像素 32 位浮点，完整保留数值精度，不做 8 位量化；
• 尺寸：随输入数据逐帧变化——当列表数量或最长长度改变时，操作符会自动销毁旧纹理并按新尺寸重建（ValuesTexture.Value.Description.Width/Height不匹配即重建）；
• 用途：BindFlags.ShaderResource，仅作为着色器输入资源，无 Mip 链（MipLevels = 1）、无 CPU 回读（Usage = Default、CpuAccessFlags.None）。

四、底层实现：每帧上屏的内存与性能设计

从源码可以观察到几个值得借鉴的工程细节：

1. 固定大小的上传缓冲池：_uploadBuffer是复用数组，只有在新数据规模（listCount * sampleCount）超出当前缓冲长度时才重新分配并GCHandle.Alloc固定内存（L65-L74），避免逐帧 GC 分配；
2. 行优先填充 + 一次上传：无论是水平还是垂直模式，数据都以行优先顺序写入缓冲，随后通过UpdateSubresource一次性提交整张纹理（L127-L132），rowPitch = width * sizeof(float)；
3. 脏标记管理：更新完成后调用Values.DirtyFlag.Clear()，避免同一帧重复计算。

这种"CPU 数组 → 固定缓冲 → 整张上传"的模式，保证了每帧都能以极低开销把成百上千个浮点值送入 GPU。

五、实战：构建音频反应可视化管线

官方示例工程 ValuesToTextureExample.t3（对应实现 ValuesToTextureExample.cs）给出了完整的参考接线，核心链路如下：

1. PlaybackFFT：在配乐播放期间输出低频 FFT 频谱列表（示例中InputBand = 4），将Result连接到 ValuesToTexture 的Values；
2. ValuesToTexture：将频谱列表编码为纹理（示例中Pow = 3.0，对频谱做指数整形），输出ValuesTexture；
3. LinearSamplePointAttributes：接收该纹理，并按点索引而非 UV 坐标逐点采样（示例中Red = 2取 R 通道、RedFactor = 0.2控制振幅），把频谱能量映射到点云的红亮度属性上；
4. DrawPoints + Camera + RenderTarget：按属性绘制点，形成可视化的频谱柱状/粒子效果，再叠加Glow辉光增强视觉冲击。

在编辑器中使用时，可以搜索ValuesToTexture直接拖入 Graph 画布（其符号定义位于 ValuesToTexture.t3，UI 布局见 ValuesToTexture.t3ui），并按上述步骤接线、调节参数即可实时看到波形驱动的画面。

六、升级版 ValuesToTexture2：归一化与范围重映射

若需要更精细的数值控制，同一目录下还提供升级版 ValuesToTexture2，其实现见 ValuesToTexture2.cs，额外提供四个参数：

• InputRange（Vector2）：输入值的最小/最大范围，用于归一化；
• Clamp（Boolean）：是否将归一化结果限制在 0~1；
• GainAndBias（Vector2）：对归一化值应用 Gain（增益）与 Bias（偏置），底层调用 MathUtils.ApplyGainAndBias 实现的 Schlick-Bias 曲线塑形；
• OutputRange（Vector2）：最终输出值的目标范围。

其像素映射流程为：归一化 = (原值 - InputRange.X) / (InputRange.Y - InputRange.X)→ 可选Clamp与ApplyGainAndBias→映射到 OutputRange。相比 ValuesToTexture 的Offset/Gain/Pow线性整形，ValuesToTexture2 更适合需要精确范围控制、避免越界的场景，两者可依据数据特征选用。

七、相关资源

• 运算符目录：Lib.numbers.floats.process README
• 源码实现：ValuesToTexture.cs、ValuesToTexture2.cs
• 示例工程：ValuesToTextureExample.t3
• 配套操作符：PlaybackFFT、LinearSamplePointAttributes
• 基础设施：Texture2D 封装、ApplyGainAndBias 数学实现

• 音视频
• 图形学
• 桌面应用