📦 Vvvv Shaders — 编写SDSL着色器

# 适用于 vvvv gamma / Stride 的 SDSL Shader ## 什么是 SDSL SDSL（Stride Shading Language）是 Stride 的着色器语言——HLSL 的超集，并新增四大特性：shader 类及其继承、多重继承（mixins）、自动完成阶段间数据流的 streams 系统，以及用于干净方法替换的 override。着色器定义在 .sdsl 文件中。 ## Streams 系统 Streams 取代了手写的 VS_INPUT/VS_OUTPUT 结构体。一次声明，处处可用： ``hlsl stream float4 MyData : TEXCOORD5; // 声明自定义 stream 变量 // 在 vertex shader 中： streams.MyData = float4(1, 0, 0, 1); // 写入 // 在 pixel shader 中： float4 d = streams.MyData; // 读取（自动插值） ` 常用内置 streams： - streams.ShadingPosition (SV_Position) —— 裁剪空间位置 - streams.ColorTarget (SV_Target0) —— 像素着色器输出 - streams.Position (float4) —— 对象空间位置 - streams.TexCoord (TEXCOORD0) —— 纹理坐标 - streams.normalWS —— 世界空间法线 ## 基础 Shader 层级 ### Stride 核心（Stride 与 vvvv 均可用） | Shader | 提供功能 | |---|---| | ShaderBase | VSMain/PSMain 入口 | | Texturing | Texture0-9、Sampler、PointSampler、LinearSampler、TexCoord | | Transformation | World、View、Projection、WorldViewProjection 矩阵 | | PositionStream4 | Position、PositionWS、DepthVS | | NormalStream | meshNormal、normalWS、tangentToWorld | | ComputeShaderBase | CSMain 入口、Compute() 钩子、线程组 | | ComputeColor | 通过 Compute() 返回 float4 的接口 | | ComputeVoid | 通过 Compute() 返回 void 的接口 | | Global | Time、TimeStep（cbuffer PerFrame） | ### 仅 vvvv 可用（纯 Stride 不可用） | Shader | 继承自 | 用途 | |---|---|---| | VS_PS_Base | ShaderBase, PositionStream4, NormalStream, Transformation | DrawFX 基类 | | FilterBase | TextureFX | 像素级纹理处理效果 | | MixerBase | TextureFX | 纹理混合 | | TextureFX | ImageEffectShader, Camera, ShaderUtils | 纹理效果基类 | 重要：VS_PS_Base 已内置 Transformation、NormalStream 和 PositionStream4，切勿重复继承。 ## 文件命名 → 自动节点生成 vvvv 依据文件名后缀自动创建节点： | 后缀 | 节点类型 | 说明 | |---|---|---| | _TextureFX.sdsl | TextureFX | 图像处理效果 | | _DrawFX.sdsl | DrawFX | 绘制/渲染着色器 | | _ComputeFX.sdsl | ComputeFX | 计算着色器 | | _ShaderFX.sdsl | ShaderFX | 通用着色器效果 | 示例：MyBlur_TextureFX.sdsl 自动生成名为“MyBlur”的 TextureFX 节点。 ## 基础 TextureFX 结构 `hlsl shader MyEffect_TextureFX : FilterBase { float Intensity = 1.0; float4 Filter(float4 tex0col) { return tex0col Intensity; } }; ` 注意右大括号后的分号——必须保留。 ## 语法规则 有关 SDSL 关键语法规则（static const 作用域、分号、override、变量初始化、常见错误、分支分歧），请见 syntax-rules.md。 ## 关键字 | 关键字 | 用途 | |---|---| | shader | 定义着色器类 | | override | 重写父方法时必须 | | base | 访问父级实现 | | stage | 确保成员在组合中只定义一次 | | stream | 成员可在各着色器阶段访问 | | static | 无需继承即可调用的静态方法 | | compose | 为 shader mixins 声明组合槽 | | clone | 强制生成组合着色器的独立实例 | | abstract | 无方法体（子级必须实现） | ## 继承与 Mixins `hlsl // 单继承 shader Child : Parent { override float4 Filter(float4 tex0col) { return base.Filter(tex0col) 0.5; } }; // 多重继承（mixins） shader MyShader : FilterBase, ColorUtils, MathUtils { float4 Filter(float4 tex0col) { float3 linear = ColorUtils.GammaToLinear(tex0col.rgb); return float4(linear, tex0col.a); } }; // 静态函数调用（无需继承） float3 result = ColorUtils.LinearToGamma(col.rgb); ` ## 枚举绑定 —— 在 Shader 中使用 C# 枚举 在着色器（.sdsl）中： `hlsl [EnumType("MyNamespace.BlendMode, MyAssembly")] int Mode = 0; ` 在 C#（.cs）中： `csharp namespace MyNamespace; public enum BlendMode { Normal = 0, Add = 1, Multiply = 2, Screen = 3 } ` 要求： - 枚举 DLL 必须预先编译（不能来自动态 csproj） - 程序集名即项目名 - 修改枚举 DLL 后需重启 vvvv ## GPU 最佳实践 ### 防止数学错误 `hlsl float3 safeLog = log2(max(x, 1e-10)); // 避免 log2(0) float3 safe = x / max(y, 0.0001); // 避免除零 float3 safePow = pow(max(x, 0.0), gamma); // 避免负值 pow ` ### 纹理采样 `hlsl // 在 TextureFX 中，tex0col 已从 Texture0 采样 float4 Filter(float4 tex0col) { // 采样额外纹理： float4 tex1 = Texture1.Sample(Texturex1Sampler, streams.TexCoord); return lerp(tex0col, tex1, 0.5); } ` ## ShaderFX / ComputeColor 模式 使用 compose 关键字创建可组合着色器节点： `hlsl shader MyTonemap_ShaderFX : ComputeColor, TonemapOperators { compose ComputeColor ColorIn; [EnumType("MyNamespace.TonemapOp, MyAssembly")] int Operator = 1; float Exposure = 0.0; override float4 Compute() { float4 color = ColorIn.Compute(); color.rgb = exp2(Exposure); color.rgb = ApplyTonemap(color.rgb, Operator); return color; } }; ` 在 vvvv 中，将 ShaderFX 节点连接到 TextureFX 的 compose 输入即可串联处理。 ## Mixin 组合 —— 虚方法派发 基类声明虚方法，由动态组合的 mixins 重写： `hlsl // 基类声明虚方法 shader ColorProcessorBase { float4 ProcessColor(float4 inPixel) { return inPixel; } }; // 宿主着色器使用组合 shader ColorTransform_TextureFX : TextureFX { stage compose ColorProcessorBase Processor; stage override float4 Shading() { float4 col = Texture0.SampleLevel(PointSampler, streams.TexCoord, 0); return Processor.ProcessColor(col); } }; ` ## 模板 / 泛型着色器 `hlsl // 带类型参数的声明 shader ComputeColorWave : ComputeColor, Texturing { override float4 Compute() { return float4(sin(streams.TexCoord.x Frequency), 0, 0, 1); } }; // 通过继承实例化 shader MyEffect : ComputeColorWave<2.0f> { }; ` 支持的模板参数类型：float、int、float2、float3、float4、Texture2D、SamplerState。 ## 组合数组 同类型着色器的多重组合： `hlsl compose ComputeColor lights[]; override float4 Compute() { float4 total = 0; foreach (var light in lights) total += light.Compute(); return total; } ` ## 跨着色器共享结构体类型 定义一次，在 emit/simulate/draw 管线中复用： `hlsl shader ParticleTypes { struct Particle { float3 Position; float3 Velocity; float Life; }; }; shader Emit_ComputeFX : ComputeShaderBase, ParticleTypes { / 填充缓冲区 / }; shader Simulate_ComputeFX : ComputeShaderBase, ParticleTypes { / 物理更新 / }; shader Draw_DrawFX : VS_PS_Base, ParticleTypes { / 渲染 / }; `` 详细 SDSL 语法规则请见 syntax-rules.md。