HMS MediaEngine Agent
362e089be0
Der Nutzer hat recht: Der Ordner war voller Entwicklungs-Muell. Jetzt ist sauber getrennt: ROOT (was der Nutzer sieht und braucht): - run.py = das Programm - hms_app/ = der Anwendungscode - HMS MediaEngine.app = macOS Doppelklick-Starter - HMS-Start.vbs = Windows Doppelklick-Starter - HMS-Install.vbs = Windows Erst-Installation - HMS-Mac-Install.command = macOS Homebrew-Installation - HMS-Portable-Install.command = macOS Portable-Installation (16GB-Fix) - installer_gui.py = grafischer Installer - launcher.pyw + launcher_core.py = interne Start-Logik - LIESMICH.txt = 10-Zeilen-Kurzanleitung - .gitignore _entwicklung/ (alles andere, NICHT benoetigt): - packages/ apps/ native/ plugins/ tools/ schemas/ tests/ docs/ build/ fixture_profiles/ - PLAN.md STATUS.md ERRORS.md TEST_REPORT.md CHANGELOG.md README.md - pyproject.toml uv.lock setup_*.sh/ps1 make_mac_app.py Diese Trennung gilt ab sofort fuer alle Commits. Der Nutzer kann _entwicklung/ loeschen wenn er Platz braucht - die App laeuft ohne. Verifiziert: App startet nach Aufraeumen unveraendert (Health 200).
85 lines
3.7 KiB
Markdown
85 lines
3.7 KiB
Markdown
# 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:
|
||
|
||
```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}
|
||
],
|
||
"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):
|
||
|
||
```json
|
||
"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.
|