Leopoldadmin/hms-mediaengine
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity
Files
362e089be0beac781914a660af235826a0e11426
hms-mediaengine/_entwicklung/docs/plugin-sdk/example-walkthrough.md
T

329 lines
11 KiB
Markdown
Raw Normal View History

Phase 3: Plugin-SDK-Dokumentation (docs/plugin-sdk/, 7 Dateien)
2026-09-11 01:57:30 +02:00
# Beispiel: Ein Filter-Plugin von null schreiben
Dieses Dokument führt Schritt für Schritt durch die Erstellung eines neuen Filter-Plugins. Als Vorlage dient das eingebaute Vignette-Plugin (`plugins/builtin/filters/com.hms.fx.vignette/`), das ein GPU-Pass-Filter ist (PLAN.md §15.2).
## Ziel
Wir erstellen ein Plugin `com.hms.fx.vignette` – einen Filter, der die Ränder eines Bildes abdunkelt oder einfärbt. Das Plugin unterstützt drei Backends: D3D11 (HLSL), OpenGL (GLSL) und OpenGL ES (GLES).
## Schritt 1: Verzeichnisstruktur anlegen
Ein Plugin ist ein Verzeichnis mit `plugin.json` und Shader-Unterordnern je Backend:
```text
com.hms.fx.vignette/
├─ plugin.json
└─ shaders/
├─ d3d11/
│ └─ main.hlsl
├─ gl/
│ └─ main.frag
└─ gles/
└─ main.frag
```
## Schritt 2: Manifest schreiben
Lege `plugin.json` an. Die Pflichtfelder sind `schema_version`, `id`, `name`, `version`, `api_version`, `kind`, `vendor`, `entrypoints`, `capabilities`, `failure_mode` (siehe [manifest-reference.md](manifest-reference.md)).
```json
{
"schema_version": 1,
"id": "com.hms.fx.vignette",
"name": "Vignette",
"version": "1.0.0",
"api_version": 1,
"kind": "filter",
"vendor": "HMS",
"entrypoints": {
"d3d11": {
"type": "hlsl",
"passes": [
{"pixel_shader": "shaders/d3d11/main.hlsl"}
]
},
"gl": {
"type": "glsl",
"passes": [
{"fragment": "shaders/gl/main.frag"}
]
},
"gles": {
"type": "glsl_es",
"passes": [
{"fragment": "shaders/gles/main.frag"}
]
}
},
"capabilities": {
"minimum_tier": "PI_LITE",
"requires_input_texture": true,
"supported_backends": ["d3d11", "gl", "gles"]
},
"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": []}
],
"failure_mode": "bypass",
"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"]
}
}
```
Wichtige Punkte:
- `kind: "filter"` – verarbeitet eine Eingangs-Textur.
- `requires_input_texture: true` – der Filter braucht eine Eingangs-Textur.
- `dmx_slots` belegen die Slots 1–8; `mix` belegt keinen Slot (gemeinsamer Effektvertrag, §14.8).
- `failure_mode: "bypass"` – bei Fehler wird der Effekt überbrückt (§3.5).
- `adaptive_quality` deklariert drei Varianten; `semantic_parameters_unchanged: ["mix"]`.
## Schritt 3: HLSL-Shader schreiben (D3D11)
Lege `shaders/d3d11/main.hlsl` an. Der Shader deklariert die Textur, den Sampler und den Konstantenpuffer `hms_params` mit dem Standard-Uniform-Satz (§14.4) und den Pluginparametern:
```hlsl
// HMS MediaEngine - Vignette (PLAN.md §15.2)
// Randabdunklung/-färbung; ein GPU-Pass.
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;
};
float4 mainPS(float4 pos : SV_POSITION, float2 uv : TEXCOORD0) : SV_Target
{
float4 src = u_input_texture.Sample(u_sampler, uv);
float m = saturate(param_mix);
if (m < 0.01)
{
return src; // Mix 0 = kostenloser Bypass (§15.3)
}
float2 c = float2(param_center_x, param_center_y);
float2 d = uv - c;
d.x *= lerp(1.0, u_resolution.x / max(u_resolution.y, 1.0), param_roundness);
float dist = length(d);
float radius = max(param_radius, 0.0001);
float soft = max(param_softness, 0.0001);
float v = smoothstep(radius, radius + soft, dist);
v = saturate(v * param_amount);
if (param_invert > 0.5)
v = 1.0 - v;
float3 vignette = lerp(src.rgb, float3(param_color_r, param_color_g, param_color_b), v);
float3 rgb = lerp(src.rgb, vignette, m);
float4 out_c = float4(rgb, src.a);
out_c.rgb *= u_layer_opacity;
out_c.a *= u_layer_opacity;
return out_c;
}
```
## Schritt 4: GLSL-Shader schreiben (OpenGL)
Lege `shaders/gl/main.frag` an. Die Semantik ist identisch zur HLSL-Variante (§12.6, §15.4), nur die Syntax unterscheidet sich:
```glsl
#version 330 core
// HMS MediaEngine - Vignette (GLSL, Linux x64)
// Semantik identisch zur HLSL-Variante (§12.6, §15.4).
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);
float m = clamp(param_mix, 0.0, 1.0);
if (m < 0.01)
{
fragColor = src;
return;
}
vec2 c = vec2(param_center_x, param_center_y);
vec2 d = v_uv - c;
d.x *= mix(1.0, u_resolution.x / max(u_resolution.y, 1.0), param_roundness);
float dist = length(d);
float radius = max(param_radius, 0.0001);
float soft = max(param_softness, 0.0001);
float v = smoothstep(radius, radius + soft, dist);
v = clamp(v * param_amount, 0.0, 1.0);
if (param_invert > 0.5)
v = 1.0 - v;
vec3 vignette = mix(src.rgb, vec3(param_color_r, param_color_g, param_color_b), v);
vec3 rgb = mix(src.rgb, vignette, m);
vec4 out_c = vec4(rgb, src.a);
out_c.rgb *= u_layer_opacity;
out_c.a *= u_layer_opacity;
fragColor = out_c;
}
```
## Schritt 5: GLES-Shader schreiben (OpenGL ES 2.0)
Lege `shaders/gles/main.frag` an. GLES 2.0 hat eigene Regeln: `#version 100`, `precision mediump float;`, `texture2D` statt `texture`, `varying` statt `in`/`out`, `gl_FragColor` statt `fragColor` (siehe [shader-contract.md](shader-contract.md)):
```glsl
#version 100
// HMS MediaEngine - Vignette (GLES, Raspberry Pi)
// ES 2.0; ein GPU-Pass.
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);
float m = clamp(param_mix, 0.0, 1.0);
if (m < 0.01)
{
gl_FragColor = src;
return;
}
vec2 c = vec2(param_center_x, param_center_y);
vec2 d = v_uv - c;
d.x *= mix(1.0, u_resolution.x / max(u_resolution.y, 1.0), param_roundness);
float dist = length(d);
float radius = max(param_radius, 0.0001);
float soft = max(param_softness, 0.0001);
float v = smoothstep(radius, radius + soft, dist);
v = clamp(v * param_amount, 0.0, 1.0);
if (param_invert > 0.5)
v = 1.0 - v;
vec3 vignette = mix(src.rgb, vec3(param_color_r, param_color_g, param_color_b), v);
vec3 rgb = mix(src.rgb, vignette, m);
vec4 out_c = vec4(rgb, src.a);
out_c.rgb *= u_layer_opacity;
out_c.a *= u_layer_opacity;
gl_FragColor = out_c;
}
```
## Schritt 6: Validieren
Das Plugin wird über den Lifecycle-Manager validiert (`packages/plugin_sdk/hms_plugin_sdk/lifecycle.py`). `discover()` lädt `plugin.json`, validiert es (inkl. Shader-Existenz) und überführt das Plugin in `validated` oder `quarantined`/`incompatible` (siehe [lifecycle.md](lifecycle.md)).
Der Validator prüft unter anderem:
- Manifest-Schema;
- eindeutige Plugin-ID und semantische Version;
- API-Kompatibilität;
- Pfad- und ZIP-Sicherheit;
- erlaubte Dateitypen und Größenlimits;
- Shader-Kompilierung;
- Capability-Prüfung;
- vollständige, vorab kompilierbare Adaptive-Quality-Varianten und unveränderte Parametersemantik;
- Lizenzmetadaten;
- Hash des Pakets.
## Schritt 7: Aktivieren
Nach erfolgreicher Validierung durchläuft das Plugin den Lebenszyklus `validated → installed → enabled → compiled → active`. Der Wechsel der Qualitätsstufe erfolgt atomar an einer Framegrenze (siehe [adaptive-quality.md](adaptive-quality.md)).
## Zusammenfassung
Ein Filter-Plugin besteht aus:
1. `plugin.json` mit Pflichtfeldern, Parametern und Adaptive Quality;
2. je deklariertem Backend eine Shader-Datei mit dem Standard-Uniform-Satz (§14.4);
3. semantisch identischen Implementierungen über alle Backends (§12.6, §15.4).
Reference in New Issue Copy Permalink