Back to Details

vvvv-shaders

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

SDSL Shaders for vvvv gamma / Stride

为vvvv gamma / Stride打造的SDSL着色器

What Is SDSL

什么是SDSL

SDSL (Stride Shading Language) is Stride's shader language — a superset of HLSL with four key additions: 
shader
classes with inheritance, multiple inheritance (mixins), the 
streams
system for automatic inter-stage data flow, and 
override
for clean method replacement. Shaders are defined in 
.sdsl
files.
SDSL（Stride着色语言）是Stride的专属着色器语言——它是HLSL的超集，新增了四项关键特性：支持继承的
shader
类、多重继承（混合）、用于实现阶段间自动数据流的
streams
系统，以及用于清晰重写方法的
override
关键字。着色器定义在
.sdsl
文件中。

Streams System

Streams系统

Streams replace manual VS_INPUT/VS_OUTPUT structs. Declare once, access everywhere:
hlsl
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)
Key built-in streams:
  • streams.ShadingPosition
    (SV_Position) — clip-space position
  • streams.ColorTarget
    (SV_Target0) — pixel shader output
  • streams.Position
    (float4) — object-space position
  • streams.TexCoord
    (TEXCOORD0) — texture coordinates
  • streams.normalWS
    — world-space normal
Streams系统替代了手动编写VS_INPUT/VS_OUTPUT结构体的方式。只需声明一次，即可在任意位置访问：
hlsl
stream float4 MyData : TEXCOORD5;      // 声明自定义流变量

// 在顶点着色器中：
streams.MyData = float4(1, 0, 0, 1);   // 写入数据

// 在像素着色器中：
float4 d = streams.MyData;             // 读取数据（自动插值）
关键内置流：
  • streams.ShadingPosition
    (SV_Position) — 裁剪空间位置
  • streams.ColorTarget
    (SV_Target0) — 像素着色器输出
  • streams.Position
    (float4) — 对象空间位置
  • streams.TexCoord
    (TEXCOORD0) — 纹理坐标
  • streams.normalWS
    — 世界空间法线

Base Shader Hierarchy

基础着色器层级

Stride Core (available in both Stride and vvvv)

Stride核心（Stride和vvvv均支持）

ShaderProvides
ShaderBase
VSMain/PSMain entry points
Texturing
Texture0-9, Sampler, PointSampler, LinearSampler, TexCoord
Transformation
World, View, Projection, WorldViewProjection matrices
PositionStream4
Position, PositionWS, DepthVS
NormalStream
meshNormal, normalWS, tangentToWorld
ComputeShaderBase
CSMain entry, Compute() hook, thread groups
ComputeColor
Interface returning float4 via Compute()
ComputeVoid
Interface returning void via Compute()
Global
Time, TimeStep (cbuffer PerFrame)
着色器提供功能
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-Only (NOT available in plain Stride)

仅vvvv支持（Stride原生环境不可用）

ShaderInheritsUse For
VS_PS_Base
ShaderBase, PositionStream4, NormalStream, TransformationDrawFX base
FilterBase
TextureFXPixel-processing texture effects
MixerBase
TextureFXBlending textures
TextureFX
ImageEffectShader, Camera, ShaderUtilsTexture effect base
Important: 
VS_PS_Base
already includes Transformation, NormalStream, and PositionStream4. Do NOT re-inherit them.
着色器继承自适用场景
VS_PS_Base
ShaderBase、PositionStream4、NormalStream、TransformationDrawFX基础
FilterBase
TextureFX像素处理类纹理效果
MixerBase
TextureFX纹理混合
TextureFX
ImageEffectShader、Camera、ShaderUtils纹理效果基础
重要提示：
VS_PS_Base
已包含Transformation、NormalStream和PositionStream4，请勿重复继承。

File Naming → Auto Node Generation

文件命名 → 自动生成节点

vvvv automatically creates nodes from shaders based on filename suffix:
SuffixNode TypeDescription
_TextureFX.sdsl
TextureFXImage processing effects
_DrawFX.sdsl
DrawFXDrawing/rendering shaders
_ComputeFX.sdsl
ComputeFXCompute shaders
_ShaderFX.sdsl
ShaderFXGeneral shader effects
Example: 
MyBlur_TextureFX.sdsl
automatically creates a "MyBlur" TextureFX node.
vvvv会根据文件名后缀自动从着色器创建节点：
后缀节点类型说明
_TextureFX.sdsl
TextureFX图像处理效果
_DrawFX.sdsl
DrawFX绘制/渲染着色器
_ComputeFX.sdsl
ComputeFX计算着色器
_ShaderFX.sdsl
ShaderFX通用着色器效果
示例：
MyBlur_TextureFX.sdsl
会自动创建名为"MyBlur"的TextureFX节点。

Basic TextureFX Structure

基础TextureFX结构

hlsl
shader MyEffect_TextureFX : FilterBase
{
    float Intensity = 1.0;

    float4 Filter(float4 tex0col)
    {
        return tex0col * Intensity;
    }
};
Note the semicolon after the closing brace — this is required.
hlsl
shader MyEffect_TextureFX : FilterBase
{
    float Intensity = 1.0;

    float4 Filter(float4 tex0col)
    {
        return tex0col * Intensity;
    }
};
注意闭合大括号后的分号——这是必填项。

Syntax Rules

语法规则

For critical SDSL syntax rules (
static const
scope, semicolons, 
override
, variable initialization, common mistakes, branch divergence), see syntax-rules.md.
关于SDSL的关键语法规则（
static const
作用域、分号、
override
、变量初始化、常见错误、分支发散），请查看syntax-rules.md。

Keywords

关键字

KeywordPurpose
shader
Defines a shader class
override
Required when overriding parent methods
base
Access parent implementation
stage
Ensures member defined once across compositions
stream
Member accessible at every shader stage
static
Static methods callable without inheritance
compose
Declare a composition slot for shader mixins
clone
Force separate instance of a composed shader
abstract
Method without body (child must implement)
关键字用途
shader
定义着色器类
override
重写父类方法时必填
base
访问父类实现
stage
确保成员在组合中仅定义一次
stream
可在每个着色器阶段访问的成员
static
无需继承即可调用的静态方法
compose
声明着色器混合的组合槽
clone
强制为组合的着色器创建独立实例
abstract
无方法体的抽象方法（子类必须实现）

Inheritance & Mixins

继承与混合

hlsl
// 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);
hlsl
// 单继承
shader Child : Parent
{
    override float4 Filter(float4 tex0col)
    {
        return base.Filter(tex0col) * 0.5;
    }
};

// 多重继承（混合）
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);

Enum Binding — C# Enum in Shaders

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

In the shader (
.sdsl
):
hlsl
[EnumType("MyNamespace.BlendMode, MyAssembly")]
int Mode = 0;
In C# (
.cs
):
csharp
namespace MyNamespace;
public enum BlendMode
{
    Normal = 0,
    Add = 1,
    Multiply = 2,
    Screen = 3
}
Requirements:
  • The enum DLL must be pre-compiled (not from dynamic csproj)
  • Assembly name is the project name
  • vvvv must be restarted after enum DLL changes
在着色器（
.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 Best Practices

GPU最佳实践

Protect Against Math Errors

避免数学错误

hlsl
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)
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);  // 避免对负数取幂

Texture Sampling

纹理采样

hlsl
// 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);
}
hlsl
// 在TextureFX中，tex0col已从Texture0采样得到
float4 Filter(float4 tex0col)
{
    // 采样额外纹理：
    float4 tex1 = Texture1.Sample(Texturex1Sampler, streams.TexCoord);
    return lerp(tex0col, tex1, 0.5);
}

ShaderFX / ComputeColor Pattern

ShaderFX / ComputeColor模式

Composable shader nodes using 
compose
keyword:
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;
    }
};
In vvvv patching, connect a ShaderFX node to a TextureFX's 
compose
input to chain processing.
使用
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 Composition — Virtual Method Dispatch

混合组合——虚方法分发

Base shader with a virtual method, overridden by dynamically composed mixins:
hlsl
// 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);
    }
};
包含虚方法的基础着色器，可被动态组合的混合重写：
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);
    }
};

Template / Generic Shaders

模板/通用着色器

hlsl
// 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> { };
Supported template parameter types: 
float
, 
int
, 
float2
, 
float3
, 
float4
, 
Texture2D
, 
SamplerState
.
hlsl
// 带类型参数的声明
shader ComputeColorWave<float Frequency> : 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
。

Composition Arrays

跨着色器共享结构体类型

Multiple composed shaders of the same type:
hlsl
compose ComputeColor lights[];

override float4 Compute()
{
    float4 total = 0;
    foreach (var light in lights)
        total += light.Compute();
    return total;
}
只需定义一次，即可在发射/模拟/绘制管线中使用：
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。

Shared Struct Types Across Shaders

—
Define once, use in emit/simulate/draw pipeline:
hlsl
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 */ };
For detailed SDSL syntax rules, see syntax-rules.md.
—