hms-mediaengine/docs/plugin-sdk/adaptive-quality.md

Adaptive Quality

Dieses Dokument beschreibt Adaptive Quality (AQ) für Plugins. Grundlage sind PLAN.md §14.3 (Beispielmanifest), §15.3 (Bedien- und Presetpflichten), §15.4 (Abnahme) und das JSON-Schema schemas/plugin/plugin_manifest_v1.schema.json.

Zweck

Adaptive Quality erlaubt es einem Effekt, die interne Rechenlast an die verfügbare Hardware anzupassen, ohne die semantische Wirkung der Parameter zu verändern. Die Engine wählt automatisch eine Variante oder der Bediener setzt eine feste Qualitätsstufe (Quality: Auto oder fest, PLAN.md §14.8).

Varianten-Deklaration

AQ-Varianten werden im Manifest unter adaptive_quality deklariert:

"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}
  ],
  "transition_ms": 180,
  "semantic_parameters_unchanged": ["radius", "mix"]
}

Felder

Feld	Typ	Pflicht	Beschreibung
default	string	ja	Standard-Variante, z. B. auto
variants	array, minItems 1	ja	Liste der Varianten
transition_ms	number, minimum 0	nein	Übergangszeit in Millisekunden
semantic_parameters_unchanged	array of string	nein	Parameter, deren Semantik beim Wechsel unverändert bleibt

Jede Variante ist ein Objekt mit:

Feld	Typ	Pflicht	Beschreibung
id	string	ja	Varianten-ID, z. B. low, medium, high
internal_scale	number, exclusiveMinimum 0, maximum 1	nein	Interne Auflösungsskala
samples	integer, minimum 1	nein	Sample-Anzahl

semantic_parameters_unchanged

Dieses Feld listet Parameter, deren semantische Bedeutung beim Wechsel der Qualitätsstufe unverändert bleibt. Ein Parameterwert wie radius oder mix muss auf allen Varianten dasselbe visuelle Ergebnis liefern; nur die interne Abtastung (Auflösung, Sample-Anzahl) darf variieren (PLAN.md §15.3).

Kompilierung vor Aktivierung

Die Validierung verlangt vollständige, vorab kompilierbare Adaptive-Quality-Varianten (PLAN.md §14.5). Jede deklarierte Variante muss vor der Aktivierung kompilierbar sein. Ein Plugin, dessen Varianten nicht vollständig kompilierbar sind, wird nicht aktiviert.

Wechsel nur an der Framegrenze

Der Wechsel der Qualitätsstufe erfolgt atomar an einer Framegrenze (PLAN.md §14.8). Verschieben, Bypass, Kopieren und Presetwechsel müssen ebenfalls atomar an einer Framegrenze erfolgen. Dadurch wird verhindert, dass ein halber Frame mit gemischten Qualitätsstufen gerendert wird.

Beispiel: Vignette

Das eingebaute Vignette-Plugin deklariert drei Varianten, die alle dieselbe interne Auflösung und Sample-Anzahl verwenden (ein GPU-Pass, PLAN.md §15.2):

"adaptive_quality": {
  "default": "auto",
  "variants": [
    {"id": "low", "internal_scale": 1.0, "samples": 1},
    {"id": "medium", "internal_scale": 1.0, "samples": 1},
    {"id": "high", "internal_scale": 1.0, "samples": 1}
  ],
  "transition_ms": 180,
  "semantic_parameters_unchanged": ["mix"]
}

Abnahme (§15.4)

Für jedes eingebaute Plugin sind verpflichtend:

• HLSL-Implementierung für D3D11 sowie GLSL/GLES-Varianten gemäß Capability;
• Golden Images bei mindestens drei Parametersätzen;
• zeitabhängige Tests mit festem Seed und festem Frameindex;
• Alpha-/Premultiplication-Test und definierter Farbraum;
• Test für Extremwerte, NaN/Infinity und Auflösung 1 × 1;
• atomarer Bypass-, Preset- und Quality-Wechsel;
• dokumentierte GPU-Zeit bei 1080p und, sofern Tier erlaubt, 4K;
• Layer-, Adjustment-/Group- und Master-Scope-Test;
• P1–P8-/G1–G8-Kanalbelegung im generierten Fixture-Handbuch.