hms-mediaengine/docs/plugin-sdk/parameters-and-dmx.md

# Parameter und DMX

Dieses Dokument beschreibt Parameter-Definitionen, DMX-Slots, Kurven und den gemeinsamen Effektvertrag. Grundlage sind PLAN.md §14.7 (DMX-Parameter-Slots), §14.8 (Gemeinsamer Effektvertrag), das JSON-Schema und der Validator `packages/plugin_sdk/hms_plugin_sdk/manifest.py`.

## Parameter-Definitionen

Parameter werden im Manifest unter `parameters` als Liste von Objekten deklariert. Jeder Parameter besitzt folgende Felder:

| Feld | Typ | Pflicht | Beschreibung |
| --- | --- | --- | --- |
| `id` | string | ja | Eindeutige Parameter-ID |
| `label` | string | ja | Anzeigename |
| `type` | enum | ja | `float`, `int`, `enum`, `bool`, `color` |
| `default` | beliebig | ja | Standardwert |
| `minimum` | number | nein | Untergrenze (für `float`/`int`) |
| `maximum` | number | nein | Obergrenze (für `float`/`int`) |
| `values` | array | nein | Werte für `enum` |
| `dmx_slots` | array | nein | DMX-Slot-Belegung (1–8) |
| `curve` | string | nein | Kurvenform, z. B. `quadratic` |

### Parametertypen

Der Validator (`manifest.py`) erlaubt genau fünf Typen:

- `float` – Gleitkommawert; `minimum`, `maximum` und `default` sind Pflicht.
- `int` – Ganzzahl.
- `enum` – Aufzählung; `values` listet die erlaubten Werte.
- `bool` – Wahrheitswert (`0`/`1`).
- `color` – Farbe, als RGB-Array (z. B. `[0, 0, 0]`).

### Validator-Regeln

- `id` muss vorhanden und ein String sein; doppelte IDs sind Fehler.
- `type` muss einer der fünf erlaubten Typen sein.
- Für `float` müssen `minimum`, `maximum` und `default` vorhanden sein.
- `dmx_slots` muss eine Liste von Ganzzahlen sein.
- Die Summe aller `dmx_slots` über alle Parameter darf **8 nicht überschreiten** (PLAN.md §14.7).

## DMX-Slots (§14.7)

Ein Effekt besitzt maximal **acht generische DMX-Slots pro Effektinstanz**. Das Manifest bildet reale Parameter darauf ab:

- acht 8-Bit-Parameter; oder
- vier 16-Bit-Parameter; oder
- eine gemischte, manifestdefinierte Belegung.

Der DMX-Footprint des Layer-Fixtures bleibt dadurch stabil, auch wenn neue Plugins installiert werden.

### Slot-Belegung im Manifest

Jeder Parameter kann über `dmx_slots` auf einen oder mehrere Slots (1–8) abgebildet werden. Das Vignette-Beispiel belegt die Slots 1–8:

```json
"parameters": [
  {"id": "amount",   "label": "Amount",   "type": "float", "minimum": 0, "maximum": 1, "default": 0.5, "dmx_slots": [1]},
  {"id": "radius",   "label": "Radius",   "type": "float", "minimum": 0, "maximum": 2, "default": 0.5, "dmx_slots": [2]},
  {"id": "softness", "label": "Softness", "type": "float", "minimum": 0, "maximum": 1, "default": 0.4, "dmx_slots": [3]},
  {"id": "roundness","label": "Roundness","type": "float", "minimum": 0, "maximum": 1, "default": 0.5, "dmx_slots": [4]},
  {"id": "center_x", "label": "Center X", "type": "float", "minimum": 0, "maximum": 1, "default": 0.5, "dmx_slots": [5]},
  {"id": "center_y", "label": "Center Y", "type": "float", "minimum": 0, "maximum": 1, "default": 0.5, "dmx_slots": [6]},
  {"id": "color",    "label": "Color",    "type": "color", "default": [0, 0, 0], "dmx_slots": [7]},
  {"id": "invert",   "label": "Invert",   "type": "bool",  "default": 0, "dmx_slots": [8]},
  {"id": "mix",      "label": "Mix",      "type": "float", "minimum": 0, "maximum": 1, "default": 1, "dmx_slots": []}
]
```

Der `mix`-Parameter belegt keinen DMX-Slot (`dmx_slots: []`), da er Teil des gemeinsamen Effektvertrags ist.

### 16-Bit-Werte

Ein Parameter kann über zwei DMX-Slots als 16-Bit-Wert abgebildet werden (vier 16-Bit-Parameter pro Effektinstanz). Die genaue Belegung ist manifestdefiniert. Der Validator zählt jeden Slot in `dmx_slots` einzeln; die Gesamtsumme darf 8 nicht überschreiten.

## Kurven

Parameter können eine Kurvenform über `curve` deklarieren. Das Schema erlaubt einen beliebigen String; das Beispiel aus PLAN.md §14.3 verwendet `quadratic`:

```json
{
  "id": "radius",
  "label": "Radius",
  "type": "float",
  "minimum": 0.0,
  "maximum": 40.0,
  "default": 0.0,
  "dmx_slots": [1],
  "curve": "quadratic"
}
```

Unterstützte Kurvenformen:

- `linear` – lineare Abbildung des DMX-/Control-Werts auf den Parameterbereich.
- `quadratic` – quadratische Abbildung, die feine Abstufungen in einem Teilbereich begünstigt.

## Gemeinsamer Effektvertrag (§14.8)

Jede Filterinstanz besitzt unabhängig vom konkreten Effekt:

- Enable/Bypass;
- Mix beziehungsweise Effect Opacity von 0 bis 1;
- eigenen Blend-Modus gegenüber dem unveränderten Eingang;
- deterministische Position in der Effektkette;
- Reset auf Default;
- speicher-, umbenenn- und kopierbares Preset;
- `Quality: Auto` oder feste Qualitätsstufe;
- acht stabile generische DMX-Parameter-Slots `P1` bis `P8`;
- modulatable Parameter über denselben Parameterpfad wie Browser, Art-Net und spätere Automation.

### `mix`

Der `mix`-Parameter (Effect Opacity) liegt zwischen 0 und 1. `Mix 0` muss den Effekt kostengünstig bypassen (PLAN.md §15.3). Das Vignette-Beispiel implementiert das im Shader:

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

### `blend_mode`

Jeder Effekt besitzt einen eigenen Blend-Modus gegenüber dem unveränderten Eingang. Der Blend-Modus ist Teil des Effektvertrags und wird pro Instanz gesetzt.

### `quality`

Jeder Effekt besitzt `Quality: Auto` oder eine feste Qualitätsstufe. Die Qualitätsstufe wählt eine Adaptive-Quality-Variante (siehe [adaptive-quality.md](adaptive-quality.md)).

### Instanzierungs-Scope

Filterplugins dürfen – sofern im Manifest freigegeben – auf Source/Clip, Layer, Group, Adjustment Layer, Master oder Output instanziert werden. V1 muss mindestens Layer, Group/Adjustment und Master unterstützen. Die Kettenreihenfolge ist fachlich relevant und wird strikt von oben nach unten ausgewertet. Verschieben, Bypass, Kopieren und Presetwechsel müssen atomar an einer Framegrenze erfolgen (PLAN.md §14.8).