Communitygithub.com

Liquid Glass

Implementiert das Apple WWDC25 Liquid Glass Material, vollständig interaktiv mit allen Steuerelementen. Für Apple Flüssigglas / Glas-Skeuomorphismus UI, Liquid Glass Buttons, Karten, Navigationsleisten, Docks, Menüs, inkl. Klicken, Auf-/Zuklappen, Trennen/Zusammenführen, Ziehen, Druckrückmeldung, sowie Echtzeit-Lichtstrahlanalyse und Nachbildung in Web (WebGL/CSS), C++/Qt6, SwiftUI.

Was ist Liquid Glass?

Dieses Skill bietet eine vollständige Implementierung des Apple Liquid Glass Effekts aus der WWDC25 Session 219. Es umfasst eine detaillierte Schritt-für-Schritt-Anleitung, eine minimale Startvorlage (`starter/glass-starter.html`) und ein umfassendes Studio-Build (`liquid-glass-studio.html`) mit 9 Glaspanelen, voller Interaktion und Echtzeit-Lichtstrahlanalyse. Der Skill deckt alle physikalischen Effekte ab: Snell-Refraktion, Fresnel-Ränder, RGB-Dispersion, Dickenverlauf, Linsenlippe, innere Leuchteffekte, sowie die Regular/Clear Varianten, adaptive Helligkeit und Scroll-Edge-Fading. Die Architektur ist für Performance optimiert: Jedes Paneel rendert nur sein eigenes AABB (2 Programme, 9 Draw Calls) und nicht die gesamte Leinwand. Das Starter-HTML enthält nur etwa 90 Zeilen Shader, 1 Programm und 1 Draw-Call und ist bereits lauffähig getestet. Zusätzlich gibt es umfangreiches Referenzmaterial (`references/feature-matrix.md`, `optics-model.md`, `interaction-playbook.md`, `swiftui-api.md`), eine Diagnose-Ansicht für Echtzeit-Lichtstrahlanalyse, vordefinierte Parameter-Rezepte (dickes Kapselglas, Linse, Textplatte, Standard), sowie eine explizite Liste der 8 häufigsten Fehler und wie man sie vermeidet. Der Skill ist für Entwickler gedacht, die den exakten Apple-Liquid-Glass-Effekt in Web-, C++- oder SwiftUI-Anwendungen nachbilden möchten, ohne ihn von Grund auf neu schreiben zu müssen.

Funktioniert mit~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Cyt-56/liquid-glass-webgl/tree/main/legacy

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

Liquid Glass Implementierung

0. Schnellster Weg (Bau es nach, 10 Minuten für brauchbares Glas)

Schreibe keinen Shader von Grund auf neu. Die Erfolgsrate, 400 Zeilen GLSL von Null zu schreiben, ist extrem gering. "Sieht nicht aus wie Glas" liegt meist genau daran.

  1. Kopiere starter/glass-starter.html in das Auslieferungsverzeichnis.
  2. Ändere nur die fünf CONFIG-Werte am Anfang der Datei (refract / mag / rim / disp / tint), aktualisiere den Browser und beobachte die Änderungen.
  3. Ersetze den Inhalt von drawBG() durch den gewünschten Hintergrundinhalt. Dies ist der wichtigste Schritt: 90% des Glaseffekts kommen von dem, was darunter liegt.
  4. Ändere Breite, Höhe und Radius von PANEL, um die Glasform zu bestimmen (r = h/2 ergibt eine vollständige Kapsel).
  5. Für mehr Glas kopiere das Rechteck und zeichne jedes im Loop mit eigenem uRect (Architektur siehe Abschnitt 3).

Das starter enthält nur etwa 90 Zeilen Shader, 1 Programm, 1 Draw-Call, bereits enthalten: Snell-Refraktion, dickenabhängige seitliche Verschiebung, Fresnel-Rand, milchiger Rand, oberes Glanzlichtband, unterer Lichtbogen, RGB-Dispersion, Linsenlippe, Druckrückmeldung. Es wurde im Chrome (inkl. Software-Renderer SwiftShader) getestet und per Screenshot verifiziert.

Direktes Testen: Öffne starter/glass-starter.html im Browser, ziehe die Maus über das Glas und sieh, wie der blaue Streifen vergrößert und verschoben wird.

0.5 Drei harte Regeln

  1. Du musst es einmal öffnen und anschauen, bevor du es auslieferst. Ohne Öffnen zu liefern, nur basierend auf Code, ist der Hauptgrund für Misserfolge mit diesem Skill. Wenn keine GUI vorhanden ist, verwende einen Headless-Screenshot:

    chrome --headless=new --enable-unsafe-swiftshader --virtual-time-budget=5000 ^
           --window-size=820,700 --screenshot=out.png "file:///<absoluter Pfad>"
    

    Dann lies das Bild wirklich, um sicherzustellen, dass Glas erscheint. Ohne Screenshot-Beweis gilt es nicht als fertig.

  2. Shader-Fehler müssen auf der Seite angezeigt werden. console.error ist im Screenshot nicht sichtbar – du siehst nur einen schwarzen Bildschirm und weißt nicht warum. Direkt nach compileShader:

    if (!gl.getShaderParameter(s, gl.COMPILE_STATUS))
      appendPre("Shader-Kompilierung fehlgeschlagen:\n" + gl.getShaderInfoLog(s));   // appendPre = fügt ein rotes <pre> in den body ein
    
  3. Erst wenig, dann viel. Lass zuerst ein einziges Glas funktionieren, dann füge ein zweites hinzu. Wenn Refraktion, Interaktion, mehrere Paneele und Animationen gleichzeitig aktiviert werden, kann man Fehler nicht lokalisieren.

0.6 Sieht nicht aus wie Glas? Symptom-Checkliste

SymptomWahrscheinlichste UrsacheLösung
Ganzer Bildschirm schwarz, nur Hintergrund sichtbarPaneel wurde nicht gezeichnetPrüfe ob uRect übergeben wird, ob uRad = 0 ist, ob der Draw 4 Eckpunkte als TRIANGLE_STRIP hat
Spiegelbild / umgekehrter Text im GlasY-Achse der Textur ist verkehrtWenn UNPACK_FLIP_Y aktiviert ist, sample 1.0 - uv.y; wenn nicht, verwende direkt uv.y
Keine Refraktion erkennbar, nur unscharfVerschiebung zu geringoff = lat * tpx * refract, stelle zuerst sicher, dass tpx einige Dutzend Pixel hat; setze refract temporär auf 3, um Veränderung zu sehen
Regenbogenband am RandDispersion über den gesamten Rand verteiltMultipliziere Dispersion mit eW*eW quadratischer Dämpfung, trenne Kanäle nur am äußersten Rand
Glas wie graues PlastikHintergrund zu eintönigDarunter muss ein kontrastreicher Inhalt sein (Text, Farbbalken, Raster), sonst sieht alles wie Nebel aus, egal welche Parameter
Oberes Glanzlicht wie eine Taschenlampe, die der Maus folgtGlanzlichtband horizontal zu schmalBehalte die Grundhelligkeit der gesamten Kante, der Zeiger verstärkt nur lokal (0,7 Basis + 0,3 Verstärkung)
Animation lasch, ohne SchwungVerwendung von exponentieller Easing-Funktion erster OrdnungErsetze durch Feder zweiter Ordnung, Dämpfung 0,6–0,7, erlaube 5–8% Überschwingen (siehe Abschnitt 6.5)
Framerate unter 30Zu viele Paneele / Vollbild-Draw pro FrameRasterisiere jedes Glas nur auf seinem eigenen AABB; maximal 10 Paneele gleichzeitig; reduziere Upload-Frequenz des Hintergrunds

Für die Premium-Version (mehrere Paneele, volle Interaktion, Lichtstrahlanalyse) weiterlesen; für ein einzelnes Glas reicht das starter und Abschnitt 4.

1. Plattformentscheidung

ZielWelches Asset verwendenBeschreibung
Einzelnes Glas / Schnell zum Zielstarter/glass-starter.html90 Zeilen Shader, 1 Draw-Call, lauffähig getestet. Ändere diese Datei, schreibe nichts von Null
Web / Demo / Interaktiver Prototyp (bevorzugt)liquid-glass-studio.htmlEinzelner WebGL-Canvas + 9 Gläser + volle Interaktion + Echtzeit-Lichtstrahlanalyse. Echte Snell-Refraktion, Dispersion, Dickenverlauf
Nur ein Glas, kein Aufwandliquid-glass-webgl.htmlLeichtgewichtige Single-Paneel-Single-Pass-Version, approximierte Verschiebung, keine Interaktionsebene
Kein WebGL möglich / Fallback erforderlichliquid-glass-css.htmlbackdrop-filter + SVG-Verschiebung, approximiertes Verhalten aber ohne pixelgenaue Refraktion
Desktop C++ / eigener Renderercpp/glass_math.h + cpp/qt6/Reine Mathematik-Bibliothek + Qt6-Steuerelemente; in Produktion Formeln in GLSL einbauen
iOS / macOS nativswift/LiquidGlassDemo.swiftOffizielle .glassEffect API; für ältere Versionen SimulatedGlass als Fallback

Warum WebGL bevorzugt wird: Refraktion erfordert pixelgenaues Abtasten des darunterliegenden Inhalts, CSS kann nur ganze Blöcke verschieben; der "Linsenlippen"-Effekt am Rand ist mit CSS nicht machbar.

2. Assets und Dokumentation

liquid-glass/
├── starter/
│   └── glass-starter.html        # Minimal lauffähiges Gerüst: 90 Zeilen Shader, 1 Programm, 1 Draw, getestet
├── liquid-glass-studio.html      # Premium: volle Interaktion + Echtzeit-Lichtstrahlanalyse (Hauptauslieferung dieses Skills)
├── liquid-glass-webgl.html       # Leichtgewichtige Single-Paneel-Version
├── liquid-glass-css.html         # CSS/SVG Fallback
├── cpp/
│   ├── glass_math.h              # SDF, Squircle, Snell/Fresnel, BK7-Dispersion, Dicke/Lippe/Bogen-Rim reine Funktionen
│   └── qt6/                      # CMake-Projekt
├── swift/LiquidGlassDemo.swift   # Offizielle API + Simulierter Fallback
└── references/
    ├── feature-matrix.md         # 22-Punkte-Matrix der Session-219-Features, Abdeckung pro Plattform, Design-Richtlinien
    ├── optics-model.md           # Physikalisches Modell des Lichtwegs und Parameterbereiche (vor dem Shader-Schreiben lesen)
    ├── interaction-playbook.md   # Zustandsautomat für Klick/Aufklappen/Trennen/Ziehen und Abnahmekriterien
    └── swiftui-api.md            # SwiftUI-Glas-API-Signaturen und Hinweise

3. Rendering-Architektur (Studio-Version)

Zwei Programme, 9 Draw-Calls, niemals mehrere Gläser in ein Full-Pass-Uniform-Array packen.

Pass 1  pBg   : Fullscreen-Quad, sampelt direkt die Hintergrundtextur
Pass 2  pGl   : Gleiches Quad-VBO, jedes Glas wird in sein AABB verschoben/skaliert, ein drawArrays

Vertex-Shader bildet das [-1,1] Quad auf das Paneel ab:

uniform vec2 uC, uH, uRes;          // Zentrum, halbe Breite/Höhe, Canvas-Größe (alle in Gerätepixeln)
void main(){
  vec2 cN = (uC/uRes)*2.0 - 1.0;  cN.y = -cN.y;      // Bildschirm-Ursprung oben links → NDC
  vec2 hN = ((uH + vec2(6.0))/uRes)*2.0;             // 6px zum Entfernen von Aliasing
  gl_Position = vec4(cN + vec2(aPos.x, -aPos.y)*hN, 0.0, 1.0);
}

Der Fragment-Shader verwendet gl_FragCoord um die Bildschirmkoordinaten zurückzurechnen (nicht varying, da varying im verschobenen Quad lokale Koordinaten wären):

vec2 px = vec2(gl_FragCoord.x, uRes.y - gl_FragCoord.y);
float d  = sdRoundBox(px - uC, uH, uRad);
float aa = smoothstep(-1.0, 1.4, d);
if(aa > 0.995) discard;                 // Pixel außerhalb der Kontur im AABB direkt verwerfen
gl_FragColor = vec4(gcol, 1.0 - aa);    // Rand mit Alpha-Übergang

Äußerlich: gl.enable(BLEND) + blendFunc(SRC_ALPHA, ONE_MINUS_SRC_ALPHA), nach dem Zeichnen deaktivieren.

So rasterisiert jedes Glas nur sein eigenes Rechteck – die Füllrate von 8 Gläsern entspricht ungefähr einer Vollbildfläche – um eine Größenordnung schneller als "Vollbild × 8 Schleifendurchläufe".

Uniforms, die pro Glas pro Draw gesetzt werden müssen (feste Reihenfolge, kein Fehlen erlaubt):

UniformBedeutungQuelle
uC uHBildschirmzentrum / halbe Breite/Höhe (Gerätepixel, Ursprung oben links)(g.x+g.w/2)*dpr etc.
uRadEckenradius (Gerätepixel)min(g.radius, min(w,h)/2)*dpr
uVariant uThick uMagMulVariante / dickes Material / paneelspezifische VergrößerungPaneel-Eigenschaften
uHover uPress uGlow uActiveInteraktionszustand 0–1Federwerte pro Frame
uPtrZeigerposition normalisiert im Paneel −1 bis 1(cx-c)/(w/2)
uAmbUmgebungsfarbe des darunter liegenden Inhalts rgbgetImageData Sampling
GlobaluRes uTex uRefraction uRim uTint uDisp uN uMode uContrast uOpaque uMag uWireEinmal pro Frame

4. Lichtweg-Modell (Vor dem Shader-Schreiben diesen Abschnitt lesen)

Sieben Schritte, Reihenfolge nicht veränderbar:

  1. Kontur: sdRoundBox liefert die vorzeichenbehaftete Distanz d (innen negativ). Normalisierte Tiefe x = clamp(-d/band, 0, 1), 0 = Kontur, 1 = Zentrum; band = max(5, min(hx,hy)*0.30).
  2. Konvexes Höhenfeld: H(x) = sqrt(1 - (1-x)²), H'(x) = v/sqrt(1-v²) (v = clamp(1-x, 0.02, 0.9995)). sqrt statt pow verwenden – pow ist auf ANGLE deutlich langsamer.
  3. Einfallswinkel: sinI = min(H'/sqrt(1+H'²), 0.62), thI = asin(sinI), thT = asin(sinI/n), n = 1.5168 (BK7). Grenze 0.62 ist eine harte Einschränkung: Bei 0.93 würde die Verschiebung am Rand 200px betragen, das gesamte Paneel wird zu einem schwarzen Block verschoben.
  4. Dicke: tpx = mdim*(0.05 + 0.28*H)*(1 + 0.40*thick)*vg, vg = 1 + 0.24*(1 - smoothstep(-0.85, 0.35, q.y)) (unten dick, oben dünn). tpx ist die "Pixel-Dicke", normaler Bereich 0.1 ~ 0.4 * mdim. Über 0.5 führt zu Verzerrungen.
  5. Verschiebung: lat = tan(thI-thT), off = -dir*lat*tpx*uRefraction*Tf, plus eine zusätzliche randnahe Komponente -dir*(1-smoothstep(0,0.28,x))*tpx*0.22. Abschließend off = clamp(off, -10, 10) – die Begrenzung ist die einzige Sicherung gegen "Rand zieht weit entfernten Inhalt herein".
  6. Fokus / Linsenlippe: focal = uMag * uMagMul * (0.50*cW - 0.40*eW), cW = smoothstep(0.10,0.90,x), eW = 1-smoothstep(0,0.62,x). Zentrum focal > 0 → Samplepunkt zum Zentrum hin → Vergrößerung; Rand focal < 0 → Samplepunkt nach außen → Inhalt wird nach außen gebogen, das ist Apples Lippe. 1-focal muss immer positiv sein, sonst lokale 180°-Umkehrung, umgekehrter Text. uMagMul ist die paneelspezifische Vergrößerung (siehe Abschnitt 6): Kleine Gläser haben eine stärkere Krümmung und vergrößern mehr, große Platten sind nahezu flach und vergrößern weniger. Ohne diesen Koeffizienten würde derselbe uMag die 214×300 Textplatte zu einem unleserlichen Durcheinander vergrößern, während die 158×126 Linse nicht genug Effekt hätte. Korrespondenz zwischen Panelgröße und magMul: lens 1.30, plate 0.55, capsule 0.85, panel 0.60, dock 0.80, nav 0.90.
  7. Sampling und Synthese: sp = c + rel*(1-focal) - off; drei Kanäle werden mit ±uDisp*7*eW getrennt gesampelt für Dispersion; dann nacheinander: variant abdunkeln, uAmb Umgebungsfarbe 0,10, Helligkeitskompression für Tint 0.58*L + 0.133, Dunkelfeld-Aufhellung +vec3(0.048,0.051,0.058), Fresnel-Rand + Milchigkeit + oberes Glanzlicht + unterer Lichtbogen ((1+0.75*press)), innerer Leuchteffekt.

Textur-Y-Achse muss umgekehrt werden

Beim Upload des Hintergrund-Canvas wurde UNPACK_FLIP_Y_WEBGL = true gesetzt, daher entspricht Textur v=0 dem unteren Bildschirmrand; px hingegen hat den Ursprung oben links. Also:

vec2 uv0 = vec2(sp.x/uRes.x, 1.0 - sp.y/uRes.y);   // Fehlt diese Zeile = das gesamte Glas zeigt ein gespiegeltes Bild

Dies ist optional. Symptom: Im Glas erscheint umgekehrter Text und der Inhalt stammt von der anderen Seite des Bildschirms.

5. Echtzeit-Lichtstrahlanalyse

Bietet zwei Ansätze, die sich nicht gegenseitig ersetzen:

A. Diagnosefeld (params.wire = 1) – Zeichnet Zwischenwerte aus dem Shader direkt, um zu beurteilen, "ob überhaupt gebrochen wird":

KanalBedeutungInterpretation
Rlength(off)/mdim*22Rot = Stärke der Ablenkung. Zentrum sollte nahezu schwarz sein, Rand rot
Gx (Randtiefe)Grüner Ring entlang der Kontur, geht nach innen schnell auf null
Bfocal*2Blau = Vergrößerung, Zentrum hell, Rand dunkel

Wenn alle drei gleichzeitig sichtbar sind und klar getrennte Zonen haben, funktioniert der Lichtweg; alles schwarz bedeutet normalerweise, dass die Uniforms nicht übergeben wurden (siehe Abschnitt 7, Falle 1).

B. Schnitt-Lichtweg-Diagramm (rechts unten, 308×150 Canvas) – Zeichnet 11 Lichtstrahlen durch konvexes Glas (Eintritt/Inneres/Austritt), beschriftet die Randstrahlen mit θi / θt / Δx und der Dickenstufe (thin/thick). Das Fokus-Paneel wechselt beim Hovern des Zeigers.

Beide Kurven (Shader und 2D-Diagramm) müssen die gleichen Formeln und die gleiche sinI-Obergrenze verwenden, sonst steht im Diagramm 68°, während die Darstellung mit 38° rechnet, was bei der Parameterabstimmung irreführend ist.

6. Parameter-Rezepte (Abstimmen mit Referenzbildern)

Gewünschter Effektrefractmagrimdisptintthick
Dickes Kapselglas (groß, heller Rand, deutlicher unterer Bogen, innen dunkel)1.200.350.950.220.24✓
Linse über farbigen Streifen (Streifen vergrößert/verschoben, helle Punkte links/rechts)1.500.601.000.180.10✓
Dickes Glas über kleinem Text (Text vergrößert + Randverzerrung)1.250.420.800.300.16✓
Obere Navigationsleiste (dünn, zurückhaltend)0.900.200.600.150.10✗
Steuerungspaneel (groß, lesbarer Text)1.000.150.550.120.14✗
Standard 01.200.450.850.350.20—

Reihenfolge zum Einstellen: zuerst refract für den Grad der Verschiebung → dann mag für die Stärke der Lippe → dann rim für die Helligkeit des Randes → zuletzt disp/tint für die Textur. In umgekehrter Reihenfolge kommt es zu Wechselwirkungen.

Drei Rezepte mit einem Klick (in der Studio-Version integriert)

Im Steuerungspaneel oben gibt es vier Schaltflächen: „Dicke Kapsel / Linse / Text / Standard". Ein Klick bewirkt zwei Dinge gleichzeitig: Setzt die fünf Schieberegler auf die Werte der obigen Tabelle und gibt dem entsprechenden Paneel ein flash (innerer Leuchteffekt), um das Auge darauf zu lenken.

var PRESETS = {
  capsule: { refract:1.20, mag:0.35, rim:0.95, disp:0.22, tint:0.24, focus:"capsule" },
  lens:    { refract:1.50, mag:0.60, rim:1.00, disp:0.18, tint:0.10, focus:"lens" },
  text:    { refract:1.25, mag:0.42, rim:0.80, disp:0.30, tint:0.16, focus:"plate" },
  reset:   { refract:1.20, mag:0.45, rim:0.85, disp:0.35, tint:0.20, focus:null }
};

Wenn das Programm params ändert, löst es keine input-Events der Schieberegler aus. Daher muss syncUI() manuell aufgerufen werden, um die Schieberegler-Positionen und numerischen Labels zurückzuschreiben, sonst entkoppeln Schieberegler und tatsächliche Parameter.

Der flash-Abfall wird in step() geschrieben und muss in glow integriert werden, nicht überschreiben (sonst wird das Leuchten beim Halten durch Flash verdrängt):

if(g.flash > 0.002) g.flash *= 0.90; else g.flash = 0;
var gl = Math.max(g.active ? 1 : 0, g.flash*0.85);
g.glow += (gl - g.glow)*k;

6.5 Vier am häufigsten übersehene Apple-Details

Diese drei Punkte treten in Session 219 auf, werden beim Ansehen der Demo aber leicht übersehen; Fehlen sie, verliert das Glas sofort an Qualität.

① Oberes Glanzlicht folgt dem Zeiger (Specular bewegt sich, darf aber nicht mit dem Zeiger mitlaufen)

Ein feststehendes helles Band oben ist ein "Aufkleber"; das Glanzlicht jedoch so zu gestalten, dass es „vom Zeigerzentrum aus nach beiden Seiten abfällt", verwandelt es in eine Taschenlampe, die über das Glas streicht – das ist der häufigste Fehler. Die richtige Methode: Die gesamte Oberkante leuchtet konstant, der Zeiger verstärkt nur lokal.

float tx       = q.x - uPtr.x*0.30;                    // Zeiger-Offset klein (0.3, nicht 0.55)
float baseTop  = 1.0 - smoothstep(-0.92, -0.30, q.y);  // Grundhelligkeit der gesamten Kante
float boostTop = 1.0 - smoothstep(0.12, 1.00, abs(tx)); // Zusätzliche Verstärkung am Zeiger
float topW     = baseTop * (0.70 + 0.30*boostTop);      // Minimum 0.70, Maximum 1.0

Vergleiche die falsche Schreibweise mit den Konsequenzen:

SchreibweiseErgebnis
smoothstep(-0.30,-0.92,q.y) * (1-smoothstep(0.06,0.72,abs(tx)))Zeiger bewegt sich, nur ein kurzer Abschnitt bleibt hell, Rest schwarz → Taschenlampe
baseTop * (0.70 + 0.30*boostTop)Kante bleibt durchgehend eine Linie, am Zeiger etwas heller → echter Spiegelglanz

Schreibe außerdem niemals reverse smoothstep: smoothstep(1.0, -1.0, d) und smoothstep(-0.30, -0.92, x) haben edge0 > edge1, was laut GLSL-Spezifikation undefiniertes Verhalten ist und auf manchen Implementierungen fehlschlägt. Verwende stattdessen immer 1.0 - smoothstep(klein, groß, x).

Das specular Highlight in Zeigerrichtung (spec berechnet aus dot(dir, pdir)) erhält nur beim Drücken Stärke, beim Hovern gar nicht; sonst folgt ein kleiner heller Punkt der Kante, wenn die Maus bewegt wird.

② Innerer Leuchteffekt breitet sich auf benachbarte Gläser aus (ca. 12%) Wenn A gedrückt wird, leuchtet das benachbarte B ebenfalls leicht auf, suggerierend, dass „Licht zwischen den Gläsern fließt".

var maxGlow = 0;
G.forEach(g => { if(g.glow > maxGlow) maxGlow = g.glow; });
if(maxGlow > 0.02)
  G.forEach(g => { if(!g.active) g.glow = Math.max(g.glow, maxGlow*0.12); });

Faktor nicht über 0,15, sonst leuchtet der gesamte Bildschirm auf, was gegen die „Zurückhaltung bei Glanzlichtern"-Richtlinie verstößt.

③ Scroll-Rand-Effekt (Scroll edge effect) Inhalt hinter dem Glas, der an den Rand scrollt, sollte „in den Hintergrund einfließen", nicht mit einer harten Linie enden. Verwende einen Alpha-Mask und maskiere nur, solange noch Inhalt vorhanden ist:

var st   = el.scrollTop;
var rest = el.scrollHeight - el.clientHeight - st;
var top  = st > 3 ? 28 : 0;              // Ganz oben nicht maskieren, sonst immer ein falscher Schatten
var bot  = rest > 3 ? 28 : 0;
el.style.webkitMaskImage =
  "linear-gradient(to bottom, rgba(0,0,0,0) 0px, #000 "+top+"px, " +
  "#000 calc(100% - "+bot+"px), rgba(0,0,0,0) 100%)";

Wichtig: mask liest den Alpha-Kanal, verwende rgba(0,0,0,0), nicht transparent (in manchen alten Implementierungen ist transparent transparentes Schwarz, das Verhalten ist gleich, aber semantisch klarer). Der scrollbare Container selbst muss pointer-events:auto haben, sonst kann man nicht scrollen; aber das verhindert, dass das gesamte Glas ziehbar ist – Gläser, die gezogen werden sollen, sollten den scrollbaren Container nicht vollständig ausfüllen.

④ Trennen / Zusammenführen: „Federnd", nicht „gleitend"

Die exponentielle Easing-Funktion erster Ordnung x += (tx - x)*0.19 überschwingt nie, bleibt immer weich und lasch. Ersetze sie durch eine Feder zweiter Ordnung:

// Pro Frame dt = 1/60
g.vx += ((g.tx - g.x)*omX*omX - 2*z*omX*g.vx)*dt;
g.x  += g.vx*dt;
g.vw += ((g.tw - g.w)*omW*omW - 2*z*omW*g.vw)*dt;
g.w  += g.vw*dt;
if (g.w < 0){ g.w = 0; g.vw = 0; }   // Wenn zu schmal, negative Breite → falsche Darstellung

omX = 15, omW = 18.5, z = 0.66 → ca. 6% Überschwingen, ~0,45s Periode. Die Breitensteifigkeit muss größer sein als die der Position (18.5 > 15), damit es „erst verformt, dann zurückkehrt"; sind beide gleich, bewegt sich das Ganze als Block und fühlt sich wieder wie ein Brett an.

Zwei Schlüssel, damit das Trennen nicht aussieht wie „zwei Bretter, die auseinandergeschoben werden":

  • Die Position des rechten Teils ist fixiert (tx ist immer lay.x + lay.w - eine Teilebreite), nur die Breite ändert sich zwischen 0 und 140 → optisch „von der Mitte aufreißen", nicht „eins schrumpft, eins wächst, auseinanderziehen"
  • Im Moment des Aufreißens/Zusammenführens erhält jeder Teil einmal flash = 1 innerer Leuchteffekt, damit die Aktion spürbar ist

Egal wie groß der Koeffizient der Easing-Funktion erster Ordnung ist, sie wird nie federn – das ist ein Problem der Kurvenform, nicht der Geschwindigkeit.

7. Acht garantiert auftretende Fallen (lokal getestet)

  1. Array-Uniforms sind unzuverlässig. uniform vec4 uGeo[12] liefert unter ANGLE/D3D für getUniformLocation("uGeo[0]") einen nicht-null Wert, uniform4fv gibt keinen Fehler, aber die Daten gelangen nicht in den Shader – alle Paneele lesen 0, werden von if(hh.x < 1.5) continue alle übersprungen, die Seite zeigt nur einen dunklen Hintergrund. Fazit: Verwende niemals Uniform-Arrays, um die Geometrie mehrerer Paneele zu übergeben; stattdessen ein Draw-Call pro Paneel.

  2. Schleifen + Uniform-Verzweigungen können komplett wegoptimiert werden. for mit if(uOpaque > 0.5){...} führt auf manchen Treibern dazu, dass der Schleifenkörper verworfen wird. Verwende innerhalb von Schleifen immer die verzweigungsfreie mix/step-Schreibweise. Bei "ein Draw pro Paneel" wird die Schleife sogar überflüssig.

  3. Deklarierte, aber ungenutzte Uniforms werden wegoptimiert, getUniformLocation gibt null zurück, fälschlicherweise wird "Fehlendes Uniform" gemeldet. Deklaration und Nutzung müssen paarweise auftreten.

  4. gl.getUniform(prog, null) wirft einen TypeError, der den gesamten nachfolgenden Code im selben Frame überspringt (FPS, Sonden werden nicht aktualisiert), sieht aus wie "Seite hängt". Prüfe die Location zuerst auf null.

  5. Y-Achse der Textur (siehe Abschnitt 4): Nicht umgekehrt → gespiegeltes Bild + umgekehrter Text.

  6. Nur click zu binden, verliert Events. In Automatisierungsumgebungen und manchen Hosts wird click nicht synthetisiert, die Interaktion bleibt stumm. Verwende pointerdown + pointerup + Verschiebungsschwellwert für die Klickerkennung, click nur als Ergänzung.

  7. half ist ein reserviertes Wort in GLSL ES: vec2 half = uRect.zw*0.5; führt zu einem Kompilierungsfehler des gesamten Shaders, die Fehlermeldung zeigt nur syntax error, schwer zu lokalisieren. Verwende hb für halbe Breite/Höhe. Weitere gefährliche Wörter: filter, input, output, long, short, double, packed.

  8. Reverse smoothstep ist undefiniertes Verhalten: Schreibweisen wie smoothstep(1.0, -1.0, d), smoothstep(-0.30, -0.92, y) mit edge0 > edge1 können in Ihrem getesteten Browser funktionieren, auf einem anderen jedoch Müll liefern. Schreibe immer um zu 1.0 - smoothstep(-1.0, 1.0, d).

8. Abnahmeliste (nach jeder Änderung ausführen)

Rendering

  • Alle 8 Gläser sichtbar, Positionen stimmen mit dem Layout überein
  • Im Glas ist der darunterliegende Inhalt sichtbar (Text/Blauer Streifen/Raster), nicht nur einfarbige Blöcke
  • Der Inhalt im Glas ist richtig ausgerichtet (kein umgekehrter Text, kein seitlich gespiegeltes Bild)
  • Am Rand ein heller Rim, oben ein Spiegelglanzlicht, unten ein heller Lichtbogen
  • In dunklen Bereichen ist das Glas innen nicht totschwarz (leichter nebliger Grauton)
  • Konturränder sind sauber antialiasiert, keine harten Kanten oder weiße Ränder

Interaktion (ausführliche Version in references/interaction-playbook.md)

  • Klick auf Kapsel → Menü wächst nach oben, untere Kante bleibt; erneuter Klick schließt es
  • Ziehen der Kapsel → folgt, beim Loslassen Rückfederung; am Rand wird es clamped
  • Klick auf Dock-Trenntaste → zwei Teile öffnen sich; erneuter Klick schließt sie
  • Drücken eines beliebigen Panels → leichtes Einfedern + innerer Leuchteffekt; Loslassen setzt zurück
  • Hovern → Glanzlicht verschiebt sich in Richtung des Zeigers
  • Leertaste / S / W Tastaturkürzel funktionieren
  • Klick auf die vier Schaltflächen „Dicke Kapsel / Linse / Text / Standard": Fünf Schiebereglerpositionen und deren numerische Werte synchronisieren sich, das Zielpaneel blinkt einmal innerlich auf
  • Nach Größenänderung (resize) bleiben die Zustände „Ausgeklappt" und „Getrennt" erhalten

Performance

  • FPS stabil, keine periodischen Einbrüche
  • Nach Änderung der Anzahl der Paneele wird die Anzahl der Draw-Calls neu bewertet

9. Leistungsbudget und Herabstufung

PunktBudgetWas tun bei Überschreitung
Gleichzeitige Glaspaneele auf dem Bildschirm≤ 10Zusammenfassen oder untergeordnete Paneele auf CSS-Fallback reduzieren
Abgedeckte Fläche pro DrawNur das eigene AABBNicht den Glass-Pass über den gesamten Bildschirm laufen lassen
Hochladen der HintergrundtexturAlle 5 Frames (Lichtflecken sind langsam)Im Stillstand auf alle 8 Frames reduzieren
Hintergrund-Pixelverhältnismin(dpr, 1.5)Bei Frameeinbrüchen auf 1.0 reduzieren
Rendering-SkalierungAdaptiv 0.72 / 1.0Bei < 42fps herabstufen, bei > 56fps hochstufen
Sampling der unteren Helligkeit getImageDataAlle 10 Frames, nur Paneele mit w*h > 24000Die größte synchrone Operation; lieber seltener samplen
Schnitt-Lichtweg-DiagrammAlle 4 FramesIm Stillstand auf alle 6 Frames reduzieren
Höhe des Steuerungspanelsmin(520, VH*0.62, VH-250)Dem Lichtweg-Diagramm unten rechts 240px lassen, sonst überlappen sich Elemente in kleinen Fenstern

Reihenfolge der Herabstufung: Anzahl der Paneele reduzieren → Rendering-Skalierung reduzieren → Upload-Frequenz des Hintergrunds reduzieren → Dispersion deaktivieren → Ganze Seite auf CSS-Version zurückfallen.

10. Design-Richtlinien (Apple HIG)

  • Glas nur auf der Navigationsebene: Die Inhaltsebene sollte nicht mit Glas bedeckt werden.
  • Kein überlappendes Glas: Zwei überlappende Gläser verlieren ihren Refraktionsbezug und sehen aus wie Schmutzflecken.
  • Varianten nicht mischen: Innerhalb eines Bildschirms sollten Regular und Clear nicht gemischt werden.
  • Tint nur für die Hauptaktion und kleine Flächen; ein komplett getöntes Glas ist kein Glas mehr.
  • Glanzlichter zurückhaltend: Rim ist „ein Ring", nicht „ein durchgehend weißer Rand". uRim > 1.2 wirkt unecht.
  • Drei Barrierefreiheit-Schalter müssen vorhanden sein: Transparenz reduzieren, Kontrast erhöhen, Bewegung reduzieren. Ersteres ersetzt den Hintergrundinhalt durch einen undurchsichtigen Hintergrund, letzteres setzt die Feder k auf 1.
  • Wenn Text auf Glas liegt, muss der DOM-Inhalt text-shadow haben, sonst ist weißer Text auf hellem Glas nicht lesbar.

11. Migration zu C++ / SwiftUI

  • C++: cpp/glass_math.h enthält die exakt gleichen reinen Funktionen H(x), H'(x), fres(), Dickenverlauf, Lippe, Bogen-Rim – direkt in den Fragment-Shader einfügen; das Qt6-Beispiel dient nur zur Demonstration der Schnittstelle, in Produktion nicht pixelweise auf der CPU berechnen.
  • SwiftUI: Bevorzugt .glassEffect(.regular, in: shape) für die Systemimplementierung; nur wenn benutzerdefinierte Form/Refraktion benötigt wird, SimulatedGlass selbst zeichnen und im Kommentar die Abweichungen zum Systemeffekt vermerken (die Systemversion hat plattformübergreifendes Hintergrund-Sampling und echte dynamische Glanzlichter).

Verwandte Skills