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:

"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:

{
  "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:

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

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