Vvvv Shaders

---
name: vvvv-shaders
description: "Helps write SDSL shaders for Stride and vvvv gamma — TextureFX, shader mixins, compute shaders, and ShaderFX composition. SDSL is a superset of HLSL, so use this skill when writing or debugging .sdsl shader files, GPU shaders, visual effects, HLSL code for vvvv, working with the Stride rendering pipeline, composing shader mixins, or any GPU/compute work. Trigger even if the user says 'HLSL', 'shader', 'GPU effect', 'render pass', or 'compute' in a vvvv context."
license: CC-BY-SA-4.0
compatibility: Designed for coding AI agents assisting with vvvv gamma development
metadata:
  author: Tebjan Halm
  version: "1.1"
---

# SDSL Shaders for vvvv gamma / Stride

## What Is 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.

## Streams System

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

## Base Shader Hierarchy

### Stride Core (available in both Stride and vvvv)

| Shader | Provides |
|---|---|
| `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) |

### vvvv-Only (NOT available in plain Stride)

| Shader | Inherits | Use For |
|---|---|---|
| `VS_PS_Base` | ShaderBase, PositionStream4, NormalStream, Transformation | DrawFX base |
| `FilterBase` | TextureFX | Pixel-processing texture effects |
| `MixerBase` | TextureFX | Blending textures |
| `TextureFX` | ImageEffectShader, Camera, ShaderUtils | Texture effect base |

**Important**: `VS_PS_Base` already includes Transformation, NormalStream, and PositionStream4. Do NOT re-inherit them.

## File Naming → Auto Node Generation

vvvv automatically creates nodes from shaders based on filename suffix:

| Suffix | Node Type | Description |
|---|---|---|
| `_TextureFX.sdsl` | TextureFX | Image processing effects |
| `_DrawFX.sdsl` | DrawFX | Drawing/rendering shaders |
| `_ComputeFX.sdsl` | ComputeFX | Compute shaders |
| `_ShaderFX.sdsl` | ShaderFX | General shader effects |

Example: `MyBlur_TextureFX.sdsl` automatically creates a "MyBlur" TextureFX node.

## Basic TextureFX Structure

```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.

## Syntax Rules

For critical SDSL syntax rules (`static const` scope, semicolons, `override`, variable initialization, common mistakes, branch divergence), see [syntax-rules.md](syntax-rules.md).

## Keywords

| Keyword | Purpose |
|---|---|
| `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) |

## 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);
```

## Enum Binding — C# Enum in Shaders

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

## GPU Best Practices

### 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)
```

### 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);
}
```

## ShaderFX / ComputeColor Pattern

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.

## 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);
    }
};
```

## 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`.

## 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;
}
```

## 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](syntax-rules.md).