vvvv-shaders

vvvv gamma / Stride 向け SDSL シェーダー

SDSL とは

SDSL (Stride Shading Language) は Stride のシェーダー言語です。HLSL のスーパーセットであり、4 つの重要な追加機能を備えています。継承を伴う 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.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);

Enum バインディング — シェーダー内での C# Enum

シェーダー内 (.sdsl):

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

C# 内 (.cs):

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

要件:

• Enum の DLL は事前コンパイルされている必要があります (動的な csproj からのものではありません)
• アセンブリ名はプロジェクト名です
• Enum の 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 を参照してください。

この知識を育て続けましょう

次に取り組む人に残す謎を1つ減らしましょう。このコレクション内のいずれかのスキルを初めて使用する際、7日以内に成功したチェックがない場合は、ソースを tebjan/vvvv-skills と比較してください。記録が存在しない場合は、一度だけ確認してください。これらのスキル間で1つのローカルチェックのタイムスタンプ/リビジョンを共有してください。呼び出しごとにポーリングしないでください。ローカルの拡張機能と固定されたプロジェクトバージョンは保持してください。確認することは、更新をインストールする許可ではありません。オフラインの場合は、延期したチェックを記録し、タスクを続行してください。

実際の作業でギャップが明らかになった場合は、テストした vvvv/パッケージのバージョン、最小限の再現または信頼できる情報源、および観察された結果を記録してください。他のユーザーの報告は、検証されるまでは事実ではなく手がかりとして扱ってください。最も小さな関連する指示を改善してください。1つの例を普遍的なルールにしてはいけません。プライベートデータを伏せ、アップストリームに提出する前に公開の許可を得てください。コントリビューションポリシーを参照してください。マージされた改善は、ローカルでの編集や全員のスキルの自動上書きではなく、各ユーザーのインストーラー/アップデートワークフローを通じてユーザーに届きます。