hms-mediaengine/_entwicklung/docs/plugin-sdk/shader-contract.md

# Shader-Vertrag

Dieses Dokument beschreibt den verbindlichen Shader-Vertrag für Plugin-Shader. Grundlage sind PLAN.md §14.4 (Standard-Shaderinputs) und die eingebauten Beispiel-Shader des Vignette-Plugins (`plugins/builtin/filters/com.hms.fx.vignette/shaders/`).

## Standard-Uniform-Satz (§14.4)

Jeder Shader erhält nach Bedarf folgende semantische Inputs:

| Semantische ID | Typ | Beschreibung |
| --- | --- | --- |
| `u_input_texture` | Textur | Eingangs-Textur (bei Filtern) |
| `u_resolution` | vec2/float4 | Auflösung in Pixeln (`xy`) |
| `u_time_seconds` | float | Zeit in Sekunden |
| `u_delta_seconds` | float | Zeit seit dem letzten Frame |
| `u_frame_index` | float | Frame-Index |
| `u_layer_opacity` | float | Opazität des Layers |
| `u_audio_rms` | float | Audio-RMS |
| `u_audio_peak` | float | Audio-Peak |
| `u_audio_bass` | float | Audio-Bass |
| `u_audio_mid` | float | Audio-Mid |
| `u_audio_treble` | float | Audio-Treble |
| `u_audio_beat` | float | Audio-Beat |
| deklarierte Pluginparameter | float | Parameter aus `plugin.json` |

Semantische Input-IDs, Typen, Wertebereiche, Farbräume und Texturkonventionen sind Teil der versionierten Plugin-API. Backendadapter binden sie an HLSL-Konstanten beziehungsweise GLSL-Uniforms; Projekte referenzieren niemals konkrete Variablennamen eines Backends (PLAN.md §14.4).

## HLSL (D3D11) – cbuffer-Layout

Im HLSL-Backend liegen die Standard-Uniforms und Pluginparameter in einem Konstantenpuffer (`cbuffer`). Das Vignette-Beispiel (`shaders/d3d11/main.hlsl`) zeigt das Layout:

```hlsl
Texture2D    u_input_texture : register(t0);
SamplerState u_sampler       : register(s0);

cbuffer hms_params : register(b0)
{
    float4 u_resolution;      // xy = Auflösung in Pixeln
    float  u_time_seconds;
    float  u_delta_seconds;
    float  u_frame_index;
    float  u_layer_opacity;
    float  u_audio_rms;
    float  u_audio_peak;
    float  u_audio_bass;
    float  u_audio_mid;
    float  u_audio_treble;
    float  u_audio_beat;
    float  param_amount;
    float  param_radius;
    float  param_softness;
    float  param_roundness;
    float  param_center_x;
    float  param_center_y;
    float  param_color_r;
    float  param_color_g;
    float  param_color_b;
    float  param_invert;      // 0 = abdunkeln, 1 = aufhellen
    float  param_mix;
    float  _pad0;
    float  _pad1;
    float  _pad2;
    float  _pad3;
};
```

### 16-Byte-Alignment

HLSL-Konstantenpuffer werden in 16-Byte-Registern (`float4`) organisiert. Ein `float4` belegt ein Register; einzelne `float`-Werte werden in 16-Byte-Blöcken zusammengefasst. Das Beispiel füllt den Puffer mit `_pad0` bis `_pad3` auf ein Vielfaches von 16 Byte auf, damit das Layout deterministisch bleibt.

### Textur- und Sampler-Bindung

- `u_input_texture` ist an `register(t0)` gebunden.
- Der Sampler `u_sampler` ist an `register(s0)` gebunden.
- Der Konstantenpuffer `hms_params` ist an `register(b0)` gebunden.

## GLSL (OpenGL, Linux x64)

Das GL-Backend (`shaders/gl/main.frag`) deklariert die Uniforms einzeln:

```glsl
#version 330 core

uniform sampler2D u_input_texture;
uniform vec2  u_resolution;
uniform float u_time_seconds;
uniform float u_delta_seconds;
uniform float u_frame_index;
uniform float u_layer_opacity;
uniform float u_audio_rms;
uniform float u_audio_peak;
uniform float u_audio_bass;
uniform float u_audio_mid;
uniform float u_audio_treble;
uniform float u_audio_beat;
uniform float param_amount;
uniform float param_radius;
uniform float param_softness;
uniform float param_roundness;
uniform float param_center_x;
uniform float param_center_y;
uniform float param_color_r;
uniform float param_color_g;
uniform float param_color_b;
uniform float param_invert;
uniform float param_mix;

in  vec2 v_uv;
out vec4 fragColor;

void main()
{
    vec4 src = texture(u_input_texture, v_uv);
    // ...
    fragColor = out_c;
}
```

## GLES (OpenGL ES 2.0, Raspberry Pi)

Das GLES-Backend (`shaders/gles/main.frag`) folgt ES-2.0-Regeln:

```glsl
#version 100
precision mediump float;

uniform sampler2D u_input_texture;
uniform vec2  u_resolution;
uniform float u_time_seconds;
uniform float u_delta_seconds;
uniform float u_frame_index;
uniform float u_layer_opacity;
uniform float u_audio_rms;
uniform float u_audio_peak;
uniform float u_audio_bass;
uniform float u_audio_mid;
uniform float u_audio_treble;
uniform float u_audio_beat;
uniform float param_amount;
uniform float param_radius;
uniform float param_softness;
uniform float param_roundness;
uniform float param_center_x;
uniform float param_center_y;
uniform float param_color_r;
uniform float param_color_g;
uniform float param_color_b;
uniform float param_invert;
uniform float param_mix;

varying vec2 v_uv;

void main()
{
    vec4 src = texture2D(u_input_texture, v_uv);
    // ...
    gl_FragColor = out_c;
}
```

## Backend-Syntaxunterschiede

Die drei Backends müssen semantisch identische Ergebnisse liefern (PLAN.md §12.6, §15.4). Die wichtigsten Syntaxunterschiede:

| Aspekt | HLSL (D3D11) | GLSL (OpenGL) | GLES (ES 2.0) |
| --- | --- | --- | --- |
| Version | `#version` nicht nötig | `#version 330 core` | `#version 100` |
| Texturzugriff | `u_input_texture.Sample(u_sampler, uv)` | `texture(u_input_texture, v_uv)` | `texture2D(u_input_texture, v_uv)` |
| Ausgabe | `return float4(...)` an `SV_Target` | `fragColor = ...` | `gl_FragColor = ...` |
| Eingabe | `float2 uv : TEXCOORD0` | `in vec2 v_uv` | `varying vec2 v_uv` |
| Clamp | `saturate(x)` | `clamp(x, 0.0, 1.0)` | `clamp(x, 0.0, 1.0)` |
| Mischen | `lerp(a, b, t)` | `mix(a, b, t)` | `mix(a, b, t)` |
| Präzision | – | – | `precision mediump float;` erforderlich |

### GLES-spezifische Regeln

- **Konstante Loop-Grenzen:** GLES 2.0 erlaubt nur Schleifen mit konstanten Grenzen. Dynamische Schleifengrenzen sind nicht zulässig.
- **`texture2D` statt `texture`:** In ES 2.0 wird `texture2D` verwendet.
- **Kein `atan2`:** Die Funktion `atan2` ist in ES 2.0 nicht verfügbar; verwende `atan(y, x)` mit zwei Argumenten oder baue die Logik selbst.
- **`precision`-Deklaration:** `precision mediump float;` muss vor den Uniforms stehen.
- **`varying` statt `in`/`out`:** ES 2.0 verwendet `varying` für Vertex-zu-Fragment-Daten.

## Multipass-Regeln

Multipass-Effekte (z. B. Gaussian Blur, PLAN.md §14.3) deklarieren mehrere Pässe im Manifest:

```json
"entrypoints": {
  "d3d11": {
    "type": "hlsl_multipass",
    "passes": [
      {"pixel_shader": "shaders/d3d11/horizontal.hlsl"},
      {"pixel_shader": "shaders/d3d11/vertical.hlsl"}
    ]
  }
}
```

- Jeder Pass ist ein eigener Shader mit eigenem Dateipfad.
- Die Pässe werden in der deklarierten Reihenfolge ausgeführt; der Ausgang eines Passes ist der Eingang des nächsten.
- Jeder Pass erhält denselben Standard-Uniform-Satz.
- Die Semantik muss über alle Backends identisch sein.

## Adaptive-Quality-Varianten-Bindung

Adaptive-Quality-Varianten (PLAN.md §14.3, §15.4) können die interne Auflösung (`internal_scale`) und die Sample-Anzahl (`samples`) ändern. Die Bindung erfolgt über die deklarierten Varianten im Manifest:

```json
"adaptive_quality": {
  "default": "auto",
  "variants": [
    {"id": "low", "internal_scale": 0.25, "samples": 5},
    {"id": "medium", "internal_scale": 0.5, "samples": 9},
    {"id": "high", "internal_scale": 1.0, "samples": 17}
  ]
}
```

Die Engine bindet die Variantenwerte an die Shader-Uniforms. Die Parameterwerte bleiben beim Wechsel der Auto-Qualitätsstufe semantisch identisch (PLAN.md §15.3). Details siehe [adaptive-quality.md](adaptive-quality.md).

## Mix-0-Bypass (§15.3)

Jeder Effekt besitzt einen `mix`-Parameter. `Mix 0` muss den Effekt kostengünstig bypassen. Das Vignette-Beispiel zeigt das Muster:

```hlsl
float m = saturate(param_mix);
if (m < 0.01)
{
    return src; // Mix 0 = kostenloser Bypass (§15.3)
}
```

```glsl
float m = clamp(param_mix, 0.0, 1.0);
if (m < 0.01)
{
    fragColor = src;
    return;
}
```