vvvv-shaders

vvvv gamma / Stride 的 SDSL 着色器

什么是 SDSL

SDSL（Stride Shading Language）是 Stride 的着色器语言，是 HLSL 的超集，并增加了四项关键功能：支持继承的 shader 类、多重继承（混入）、用于自动实现阶段间数据流的 streams 系统，以及用于简洁替换方法的 override。着色器定义在 .sdsl 文件中。

Streams 系统

Streams 取代了手动定义的 VS_INPUT/VS_OUTPUT 结构体。只需声明一次，即可在任何地方访问：

stream float4 MyData : TEXCOORD5;      // Declare a custom stream variable

// In vertex shader:
streams.MyData = float4(1, 0, 0, 1);   // Write

// In pixel shader:
float4 d = streams.MyData;             // Read (auto-interpolated)

主要内置 streams：

• streams.ShadingPosition (SV_Position) — 裁剪空间位置
• streams.ColorTarget (SV_Target0) — 像素着色器输出
• streams.Position (float4) — 对象空间位置
• streams.TexCoord (TEXCOORD0) — 纹理坐标
• streams.normalWS — 世界空间法线

基础着色器层级

Stride 核心（Stride 和 vvvv 均可用）

着色器	提供的内容
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 中不可用）

着色器	继承自	用途
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 结构

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	为着色器混入声明组合槽位
clone	强制为组合的着色器创建单独实例
abstract	不含主体的方法（子类必须实现）

继承与混入

// Single inheritance
shader Child : Parent
{
    override float4 Filter(float4 tex0col)
    {
        return base.Filter(tex0col) * 0.5;
    }
};

// Multiple inheritance (mixins)
shader MyShader : FilterBase, ColorUtils, MathUtils
{
    float4 Filter(float4 tex0col)
    {
        float3 linear = ColorUtils.GammaToLinear(tex0col.rgb);
        return float4(linear, tex0col.a);
    }
};

// Static function calls (no inheritance needed)
float3 result = ColorUtils.LinearToGamma(col.rgb);

枚举绑定 — 在着色器中使用 C# 枚举

在着色器（.sdsl）中：

[EnumType("MyNamespace.BlendMode, MyAssembly")]
int Mode = 0;

在 C#（.cs）中：

namespace MyNamespace;
public enum BlendMode
{
    Normal = 0,
    Add = 1,
    Multiply = 2,
    Screen = 3
}

要求：

• 枚举 DLL 必须预先编译（不能来自动态 csproj）
• 程序集名称就是项目名称
• 枚举 DLL 发生更改后必须重启 vvvv

GPU 最佳实践

防止数学错误

float3 safeLog = log2(max(x, 1e-10));     // Avoid log2(0)
float3 safe = x / max(y, 0.0001);          // Avoid div by zero
float3 safePow = pow(max(x, 0.0), gamma);  // Avoid pow(negative)

纹理采样

// In TextureFX, tex0col is already sampled from Texture0
float4 Filter(float4 tex0col)
{
    // Sample additional textures:
    float4 tex1 = Texture1.Sample(Texturex1Sampler, streams.TexCoord);
    return lerp(tex0col, tex1, 0.5);
}

ShaderFX / ComputeColor 模式

使用 compose 关键字组合着色器节点：

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 输入，以串联处理过程。

混入组合 — 虚方法分派

包含虚方法的基类着色器，由动态组合的混入覆盖该方法：

// Base shader declares the virtual method
shader ColorProcessorBase
{
    float4 ProcessColor(float4 inPixel) { return inPixel; }
};

// Host shader uses composition
shader ColorTransform_TextureFX : TextureFX
{
    stage compose ColorProcessorBase Processor;

    stage override float4 Shading()
    {
        float4 col = Texture0.SampleLevel(PointSampler, streams.TexCoord, 0);
        return Processor.ProcessColor(col);
    }
};

模板 / 通用着色器

// Declaration with type parameter
shader ComputeColorWave<float Frequency> : ComputeColor, Texturing
{
    override float4 Compute()
    {
        return float4(sin(streams.TexCoord.x * Frequency), 0, 0, 1);
    }
};

// Instantiation via inheritance
shader MyEffect : ComputeColorWave<2.0f> { };

支持的模板参数类型：float、int、float2、float3、float4、Texture2D、SamplerState。

组合数组

多个相同类型的组合着色器：

compose ComputeColor lights[];

override float4 Compute()
{
    float4 total = 0;
    foreach (var light in lights)
        total += light.Compute();
    return total;
}

着色器间共享结构体类型

定义一次，在 emit/simulate/draw 流水线中使用：

shader ParticleTypes
{
    struct Particle { float3 Position; float3 Velocity; float Life; };
};

shader Emit_ComputeFX : ComputeShaderBase, ParticleTypes { /* fills buffer */ };
shader Simulate_ComputeFX : ComputeShaderBase, ParticleTypes { /* physics */ };
shader Draw_DrawFX : VS_PS_Base, ParticleTypes { /* renders */ };

有关详细的 SDSL 语法规则，请参阅 syntax-rules.md。

让这些知识不断增长

让下一位 patcher 少一个疑问。首次使用本集合中的任意技能时，如果过去七天内没有成功检查记录，请对照 tebjan/vvvv-skills。如果没有记录，只需检查一次。 在这些技能间共享一个本地检查时间戳/修订版本；不要每次调用都轮询。 保留本地扩展和固定的项目版本；检查不代表获准安装更新。如果处于离线状态，请记录延期检查并继续任务。

实际工作发现知识缺口时，请记录经过测试的 vvvv/软件包版本、最小复现案例或权威来源，以及观察到的结果。将其他用户的报告视为线索，在验证前不要当作事实。改进最相关的最小范围说明；不要把单个示例变成通用规则。提交上游前，请删除私人数据并获得发布授权。请参阅贡献政策。 合并的改进会通过用户的安装程序/更新工作流传达给用户，而不是通过本地编辑或自动覆盖所有人的技能。