Communitygithub.com

liquid-glass

Implementa el material, los controles y la interacción completa de Liquid Glass (Vidrio Líquido) de Apple WWDC25. Se utiliza cuando el usuario solicita una interfaz de usuario con efecto de vidrio líquido / vidrio esmerilado, botones, tarjetas, barras de navegación, Dock, menús, o enlaces de vidrio transparente y refractivo, que requieren clic, expansión, separación y combinación, arrastre, respuesta a la pulsación, o necesita un análisis de trayectorias de luz en tiempo real, o replicar el material en Web (WebGL/CSS), C++/Qt6, SwiftUI. Cubre refracción de lentes, desplazamiento Snell, bordes Fresnel, dispersión RGB, gradiente de grosor, labio de lente, brillo interno, variantes Regular/Clear, adaptación clara/oscura, desvanecimiento gradual en los bordes de desplazamiento, y una arquitectura de rendimiento de múltiples paneles con llamadas de dibujo independientes. Incluye un esqueleto mínimo ejecutable starter/glass-starter.html (1 programa, 1 dibujo, ya verificado en ejecución). Modifique a partir de él primero, no escriba shaders desde cero.

¿Qué es liquid-glass?

Este skill proporciona una guía completa e instrucciones prácticas para implementar el efecto de material Liquid Glass (Vidrio Líquido) de Apple, introducido en WWDC25, en proyectos web, C++ y SwiftUI. Su propósito principal es ayudar a los desarrolladores y agentes de IA a crear de manera eficiente interfaces de usuario con aspecto de vidrio realista, incluyendo refracción, dispersión de colores (cromatismo), bordes brillantes (efecto Fresnel) y respuestas interactivas como clics, arrastres, expansión y separación de paneles. El skill cubre múltiples plataformas: WebGL (la opción preferida por su precisión de píxeles), CSS/SVG (como alternativa de menor rendimiento), C++/Qt6 y SwiftUI. Destaca por su enfoque en la optimización del rendimiento, con una arquitectura de renderizado que procesa cada panel de vidrio en su propio rectángulo delimitador (AABB) para minimizar la sobrecarga, y proporciona un modelo óptico detallado de 7 pasos (contorno, campo de altura, ángulo de incidencia, grosor, desplazamiento, punto focal/labio de lente, muestreo y composición) que es esencial para escribir shaders correctos. Además, incluye una lista completa de parámetros (refracción, magnificación, borde, dispersión, tinte, grosor) con recetas para diferentes efectos (cápsula gruesa, lente, texto, etc.), herramientas de diagnóstico para el análisis de trayectorias de luz, y una sección de errores comunes y una lista de verificación de aceptación para garantizar una implementación de alta calidad.

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

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Implementación de Liquid Glass (Vidrio Líquido)

0. Ruta más rápida (10 minutos para conseguir un vidrio funcional)

No escribas shaders desde cero. La probabilidad de éxito escribiendo 400 líneas de GLSL desde cero es extremadamente baja. La mayoría de las veces que el resultado "no se ve como vidrio" es porque se desvía en este paso.

  1. Copia starter/glass-starter.html al directorio de entrega.
  2. Solo modifica los cinco números de CONFIG al principio del archivo (refract / mag / rim / disp / tint). Actualiza la página inmediatamente para ver los cambios.
  3. Reemplaza el contenido dibujado por drawBG() por el contenido que el usuario quiera ver debajo. Este es el paso más crítico: el 90% del efecto de vidrio proviene de lo que hay debajo.
  4. Ajusta el ancho, alto y radio de borde de PANEL para definir la forma del vidrio (r = h/2 para una cápsula completa).
  5. Para añadir más vidrios, duplica el rectángulo y dibuja cada uno una vez en el bucle con uRect (la arquitectura se describe en la sección 3).

starter tiene solo unas 90 líneas de shader, 1 programa y 1 dibujo, e incluye: refracción Snell, desplazamiento lateral ponderado por grosor, borde Fresnel, blancura en los bordes, banda de brillo superior, arco brillante inferior, dispersión RGB, labio de lente y respuesta a la presión. Ya se ha verificado y capturado en Chrome (incluyendo el renderizado por software SwiftShader).

Para ver el efecto directamente: abre starter/glass-starter.html en un navegador, arrastra el ratón sobre el vidrio y observa cómo la barra azul se desplaza y amplía.

0.5 Tres reglas estrictas

  1. Debes abrirlo para verlo antes de entregarlo. No abrirlo y solo confiar en el código es la principal causa de fracaso de este skill. Cuando no haya GUI, usa una captura de pantalla headless:

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

    Luego revisa la imagen para confirmar que el vidrio ha aparecido. Sin evidencia de captura de pantalla, no des el skill por completado.

  2. Los errores del shader deben mostrarse en la página. console.error no se ve en las capturas de pantalla, solo verás una pantalla negra sin saber por qué. Inmediatamente después de compileShader:

    if (!gl.getShaderParameter(s, gl.COMPILE_STATUS))
      appendPre("Fallo de compilación del shader:\n" + gl.getShaderInfoLog(s));   // appendPre = inserta un <pre> rojo en el body
    
  3. Menos es más. Primero haz que un vidrio funcione correctamente, luego añade el segundo. Si intentas refracción + interacción + múltiples paneles + animación a la vez, será imposible localizar errores.

0.6 ¿No se ve como vidrio? Consulta por síntomas

SíntomaCausa más probableSolución
Pantalla completamente negra, solo el fondoEl panel no se ha dibujadoComprueba si uRect se pasa, si uRad es 0, si el dibujo usa 4 vértices TRIANGLE_STRIP
Espejo / texto invertido dentro del vidrioEl eje Y de la textura está invertidoSi UNPACK_FLIP_Y está activado, muestra 1.0 - uv.y; si no, usa directamente uv.y
Sin refracción, solo desenfoqueLa cantidad de desplazamiento es demasiado pequeñaoff = lat * tpx * refract. Primero confirma que tpx tenga decenas de píxeles; aumenta refract temporalmente a 3 para ver si hay cambios
Banda de color arcoíris dura alrededor del bordeLa dispersión cubre todo el bordeMultiplica la dispersión por eW*eW (atenuación cuadrática) para separar los canales solo en el borde más externo
El vidrio parece plástico grisEl contenido de abajo es demasiado monótonoDebe haber contenido de alto contraste debajo (texto, barras de colores, cuadrícula), de lo contrario, cualquier parámetro se verá como niebla
El brillo superior sigue al ratón como una linternaLa banda de brillo está demasiado estrecha horizontalmenteMantén la luminosidad base de todo el borde. El puntero solo hace una mejora local (0.7 base + 0.3 ganancia)
Animación lenta y sin energíaSe usa una función de suavizado exponencial de primer ordenCámbiala a un muelle de segundo orden, amortiguación 0.60.7, permite un 58% de sobreimpulso (ver sección 6.5)
La tasa de fotogramas baja de 30Demasiados paneles / dibujo de pantalla completa por fotogramaCada vidrio rasteriza solo su propio AABB; ≤ 10 paneles en la misma pantalla; reduce la frecuencia de subida del fondo

Para la versión insignia (múltiples paneles, interacción completa, análisis de trayectorias de luz), sigue leyendo; para un solo vidrio, starter es suficiente, lee hasta la sección 4.

1. Decisión de plataforma

ObjetivoQué activo usarDescripción
Un solo vidrio / hacerlo rápidostarter/glass-starter.html90 líneas de shader, 1 dibujo, ya verificado en ejecución. Modifica a partir de este, no escribas desde cero
Web / demostraciones / prototipos interactivos (primera opción)liquid-glass-studio.htmlUn canvas WebGL + 9 vidrios + interacción completa + análisis de trayectorias de luz en tiempo real. Refracción Snell real, dispersión, gradiente de grosor
Solo un vidrio, sin complicacionesliquid-glass-webgl.htmlVersión ligera de un solo panel y un solo pase, desplazamiento aproximado, sin capa de interacción
Cuando no se puede usar WebGL / se necesita una degradaciónliquid-glass-css.htmlbackdrop-filter + desplazamiento SVG, comportamiento aproximado pero sin refracción píxel a píxel
C++ de escritorio / renderizador personalizadocpp/glass_math.h + cpp/qt6/Librería matemática pura + controles Qt6. En producción, traslada las fórmulas a GLSL
iOS / macOS nativoswift/LiquidGlassDemo.swiftAPI oficial .glassEffect; para versiones anteriores usa SimulatedGlass como alternativa

Razón para priorizar WebGL: la refracción requiere muestrear el píxel de abajo. CSS solo puede hacer un desplazamiento de todo el bloque; el "labio de lente" en los bordes simplemente no se consigue.

2. Activos y documentación

liquid-glass/
├── starter/
│   └── glass-starter.html        # Esqueleto mínimo ejecutable: 90 líneas de shader, 1 programa, 1 dibujo, ya verificado
├── liquid-glass-studio.html      # Insignia: interacción completa + trayectoria de luz en tiempo real (principal entrega de este skill)
├── liquid-glass-webgl.html       # Versión ligera de un solo panel
├── liquid-glass-css.html         # CSS/SVG como alternativa
├── cpp/
│   ├── glass_math.h              # Funciones puras SDF, squircle, Snell/Fresnel, dispersión BK7, gradiente de grosor/labio/arco rim
│   └── qt6/                      # Proyecto CMake
├── swift/LiquidGlassDemo.swift   # API oficial + alternativa simulada
└── references/
    ├── feature-matrix.md         # Matriz de 22 características de la Sesión 219, cobertura por extremo, líneas rojas de diseño
    ├── optics-model.md           # Modelo físico de la trayectoria de la luz y rangos de parámetros (lectura obligatoria antes de escribir shaders)
    ├── interaction-playbook.md   # Máquina de estados para clic/expansión/separación/arrastre y lista de verificación de aceptación
    └── swiftui-api.md            # Firma de la API de vidrio de SwiftUI y notas importantes

3. Arquitectura de renderizado (versión studio)

Dos programas, 9 llamadas de dibujo. Nunca metas varios vidrios en un array uniform de un pase de pantalla completa.

Pass 1  pBg   : quad de pantalla completa, muestrea directamente la textura de fondo
Pass 2  pGl   : el mismo VBO de quad para todos. Cada vidrio se traslada/redimensiona a su propio AABB, una vez drawArrays

El vertex shader mapea el quad [-1,1] al panel:

uniform vec2 uC, uH, uRes;          // Centro, semi-ancho/alto, tamaño del canvas (todo en píxeles del dispositivo)
void main(){
  vec2 cN = (uC/uRes)*2.0 - 1.0;  cN.y = -cN.y;      // Origen esquina superior izquierda de la pantalla → NDC
  vec2 hN = ((uH + vec2(6.0))/uRes)*2.0;             // Expansión de 6px para antialiasing
  gl_Position = vec4(cN + vec2(aPos.x, -aPos.y)*hN, 0.0, 1.0);
}

El fragment shader usa gl_FragCoord para deducir la coordenada de pantalla (no usa varying, porque en el quad trasladado el varying es coordenada local):

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;                 // Los píxeles fuera del contorno dentro del AABB se descartan directamente
gl_FragColor = vec4(gcol, 1.0 - aa);    // El borde usa transición alfa

En el exterior, activa gl.enable(BLEND) + blendFunc(SRC_ALPHA, ONE_MINUS_SRC_ALPHA), y desactívalo después de dibujar.

De esta manera, cada vidrio rasteriza solo su propio rectángulo. La tasa de llenado de 8 vidrios equivale aproximadamente a una pantalla completa, un orden de magnitud más rápido que "pantalla completa × 8 iteraciones".

Los uniform escalares que se deben establecer para cada vidrio en un solo draw (orden fijo, no puede faltar ninguno):

uniformSignificadoOrigen
uC uHCentro / semi-ancho/alto de la pantalla (píxeles del dispositivo, origen esquina superior izquierda)(g.x+g.w/2)*dpr etc.
uRadRadio de borde (píxeles del dispositivo)min(g.radius, min(w,h)/2)*dpr
uVariant uThick uMagMulVariante / material grueso / aumento a nivel de panelPropiedades del panel
uHover uPress uGlow uActiveEstados de interacción 0~1Valor del muelle por fotograma
uPtrCoordenada normalizada del puntero dentro del panel −1~1(cx-c)/(w/2)
uAmbColor ambiental de la capa inferior rgbgetImageData sampleo
GlobaluRes uTex uRefraction uRim uTint uDisp uN uMode uContrast uOpaque uMag uWireSe establecen una vez por fotograma

4. Modelo de trayectoria de la luz (lectura obligatoria de esta sección antes de escribir shaders)

Siete pasos, el orden no se puede cambiar:

  1. Contorno: sdRoundBox para obtener la distancia con signo d (negativa en el interior). Profundidad normalizada x = clamp(-d/band, 0, 1), 0 = contorno, 1 = centro; band = max(5, min(hx,hy)*0.30).
  2. Campo de altura convexo: H(x) = sqrt(1 - (1-x)²), H'(x) = v/sqrt(1-v²) (v = clamp(1-x, 0.02, 0.9995)). Usa sqrt, no pow; pow es mucho más lento en ANGLE.
  3. Ángulo de incidencia: sinI = min(H'/sqrt(1+H'²), 0.62), thI = asin(sinI), thT = asin(sinI/n), n = 1.5168 (BK7). El límite superior 0.62 es una restricción estricta: si se sube a 0.93, el desplazamiento del borde llegaría a 200 píxeles, y todo el panel se vería como un bloque negro.
  4. Grosor: tpx = mdim*(0.05 + 0.28*H)*(1 + 0.40*thick)*vg, vg = 1 + 0.24*(1 - smoothstep(-0.85, 0.35, q.y)) (más grueso abajo, más fino arriba). tpx es el "grosor en píxeles", rango normal 0.1 ~ 0.4 * mdim. Si supera 0.5, hay distorsión segura.
  5. Desplazamiento: lat = tan(thI-thT), off = -dir*lat*tpx*uRefraction*Tf, más un término adicional para el borde: -dir*(1-smoothstep(0,0.28,x))*tpx*0.22. Finalmente, off = clamp(off, -10, 10); esta limitación es el único seguro para evitar que el borde "arrastre violentamente el contenido lejano".
  6. Punto focal / labio de lente: focal = uMag * uMagMul * (0.50*cW - 0.40*eW), cW = smoothstep(0.10,0.90,x), eW = 1-smoothstep(0,0.62,x). Centro: focal > 0 → el punto de muestreo se acerca al centro → ampliación. Borde: focal < 0 → el punto de muestreo se expande hacia el exterior → el contenido se dobla hacia afuera. Este es el labio de Apple. 1-focal debe ser siempre positivo; de lo contrario, se produce un giro local de 180°, dando lugar a texto invertido. uMagMul es la tasa de aumento a nivel de panel (ver sección 6): el vidrio pequeño tiene mayor curvatura y amplía más; el panel grande es casi plano y amplía menos. Sin este coeficiente, usar el mismo uMag haría que un panel de texto de 214×300 se amplíe hasta volverse ilegible, mientras que una lente de 158×126 no sería suficiente. Correspondencia entre tamaño del panel y magMul: lens 1.30, plate 0.55, capsule 0.85, panel 0.60, dock 0.80, nav 0.90.
  7. Muestreo y composición: sp = c + rel*(1-focal) - off; separa los tres canales ±uDisp*7*eW para hacer dispersión; luego, en orden: oscurecimiento por variant, color ambiental uAmb (0.10), compresión de brillo de tinte 0.58*L + 0.133, relleno de campo oscuro +vec3(0.048,0.051,0.058), borde Fresnel + blancura + especular superior + arco inferior ((1+0.75*press)), brillo interno.

La coordenada de textura debe invertir Y

El canvas de fondo se sube con UNPACK_FLIP_Y_WEBGL = true, por lo que la textura v=0 corresponde a la parte inferior de la pantalla; mientras que px tiene el origen en la esquina superior izquierda. Por lo tanto:

vec2 uv0 = vec2(sp.x/uRes.x, 1.0 - sp.y/uRes.y);   // Sin esta línea, todo el vidrio muestrea una imagen reflejada

Esto no es opcional. El síntoma es: texto invertido verticalmente dentro del vidrio, y el contenido proviene del lado opuesto de la pantalla.

5. Análisis de trayectorias de luz en tiempo real

Se proporcionan dos conjuntos, no se sustituyen mutuamente:

A. Campo de diagnóstico (params.wire = 1): dibuja directamente los valores intermedios del shader para determinar "si realmente está refractando":

CanalSignificadoInterpretación
Rlength(off)/mdim*22Rojo = intensidad de la refracción. El centro debe estar casi negro, el borde rojo
Gx (profundidad del borde)Un anillo verde que sigue el contorno, se desvanece rápidamente hacia el interior
Bfocal*2Azul = tasa de aumento, el centro brillante, el borde oscuro

Si aparecen los tres al mismo tiempo y las zonas se distinguen claramente, la trayectoria de la luz es correcta; si está completamente negro, suele significar que el uniform no ha llegado al shader (ver error 1 de la sección 7).

B. Diagrama de trayectorias de luz en sección transversal (canvas de 308×150 en la esquina inferior derecha): dibuja 11 rayos de luz que atraviesan una lente convexa, mostrando la incidencia/interior/emergencia. Etiqueta θi / θt / Δx y la configuración de grosor (thin/thick) para los rayos del borde. El panel de distancia focal cambia según la posición del puntero.

Ambas curvas (shader y gráfico 2D) deben usar la misma fórmula y el mismo límite superior de sinI. De lo contrario, el gráfico puede mostrar 68° mientras la imagen se calcula con 38°, lo que engañará al ajustar los parámetros.

6. Recetas de parámetros (ajusta con una imagen de referencia)

Efecto deseadorefractmagrimdisptintthick
Cápsula de vidrio grueso (grande, borde brillante, arco inferior evidente, interior oscuro y transparente)1.200.350.950.220.24✓
Lente sobre barras de colores (las barras se desplazan y amplían, puntos brillantes a los lados)1.500.601.000.180.10✓
Vidrio grueso sobre texto pequeño (texto ampliado + distorsión en los bordes)1.250.420.800.300.16✓
Barra de navegación superior (fina, discreta)0.900.200.600.150.10✗
Panel de control (grande, debe poder leerse el texto)1.000.150.550.120.14✗
0 por defecto1.200.450.850.350.20—

Orden de ajuste: primero refract para definir la magnitud del desplazamiento → luego mag para la intensidad del labio → luego rim para el brillo del borde → finalmente disp/tint para la textura. Si se invierte el orden, los parámetros se contradecirán.

Tres recetas con un solo clic (incorporado en la versión studio)

En la parte superior del panel de control hay cuatro botones: «Cápsula gruesa / Lente / Texto / Por defecto». Al hacer clic, se hacen dos cosas simultáneamente: se establecen los cinco sliders según los valores de la tabla anterior, y se aplica un flash de brillo interno al panel correspondiente (para indicarle al ojo "mira este").

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 }
};

Cuando el programa modifica params, no se dispara el evento input de los sliders. Por lo tanto, se debe llamar manualmente a syncUI() para actualizar las posiciones y los valores de las etiquetas; de lo contrario, los sliders y los parámetros reales se desincronizarán.

El decaimiento de flash se escribe dentro de step(), y se debe fusionar con glow, no sobrescribirlo (de lo contrario, el brillo al mantener pulsado se verá desplazado por el flash):

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 Los cuatro detalles de Apple que más se olvidan

Estos tres elementos aparecen en la Sesión 219, pero son muy fáciles de pasar por alto al ver la demo. Si faltan, el "aspecto de vidrio" pierde calidad instantáneamente.

① El brillo superior sigue al puntero (el specular se mueve, pero no persigue al puntero)

Una línea brillante fija en el borde superior es una "pegatina"; pero si el brillo se hace "decaer desde el puntero hacia los lados", se convierte en una linterna que barre el vidrio, que es el error más común. La forma correcta es: todo el borde superior brilla constantemente, y el puntero solo hace una mejora local.

float tx       = q.x - uPtr.x*0.30;                    // El desplazamiento del puntero debe ser pequeño (0.3, no 0.55)
float baseTop  = 1.0 - smoothstep(-0.92, -0.30, q.y);  // Brillo base de todo el borde
float boostTop = 1.0 - smoothstep(0.12, 1.00, abs(tx)); // Ganancia adicional en la posición del puntero
float topW     = baseTop * (0.70 + 0.30*boostTop);      // Mínimo 0.70, máximo 1.0

Compara la escritura incorrecta con sus consecuencias:

EscrituraComportamiento
smoothstep(-0.30,-0.92,q.y) * (1-smoothstep(0.06,0.72,abs(tx)))Al mover el puntero, solo queda brillante un pequeño segmento, el resto se oscurece → linterna
baseTop * (0.70 + 0.30*boostTop)El borde siempre forma una línea continua, ligeramente más brillante en el puntero → espejo real

Además, no escribas smoothstep en orden inverso: smoothstep(1.0, -1.0, d) y smoothstep(-0.30, -0.92, x) con edge0 > edge1 son un comportamiento indefinido según la especificación GLSL, y algunas implementaciones pueden fallar. Siempre usa 1.0 - smoothstep(pequeño, grande, x).

El especular en la dirección del puntero (el spec calculado por dot(dir, pdir)) solo se aplica cuando se pulsa, no cuando se pasa el ratón por encima; de lo contrario, al deslizar el ratón, habrá un pequeño punto brillante que persigue el borde.

② El brillo interno se extiende a los vidrios vecinos (aproximadamente 12%) Cuando se pulsa A, el B cercano también se ilumina ligeramente, dando la sensación de que "la luz fluye entre los vidrios".

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); });

El coeficiente no debe superar 0.15; de lo contrario, toda la pantalla se iluminará, rompiendo la línea roja de "brillo contenido".

③ Efecto de desvanecimiento gradual del borde de desplazamiento (Scroll edge effect) Cuando el contenido detrás del vidrio se desplaza hasta el borde, debe "fusionarse con el fondo", no cortarse en una línea dura. Usa una máscara alfa, y solo cuando aún haya contenido:

var st   = el.scrollTop;
var rest = el.scrollHeight - el.clientHeight - st;
var top  = st > 3 ? 28 : 0;              // Si se ha desplazado hasta arriba, no hay máscara; de lo contrario, siempre habrá una sombra falsa
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%)";

Punto clave: mask lee el canal alfa, usa rgba(0,0,0,0) en lugar de transparent (en algunas implementaciones antiguas, transparent es negro transparente, el comportamiento es el mismo pero la semántica es más clara). El contenedor de desplazamiento debe tener pointer-events:auto, de lo contrario no se puede desplazar; pero ten en cuenta que hará que todo el vidrio no reciba arrastres, por lo que los vidrios que necesiten arrastrarse no deben llenar el contenedor de desplazamiento.

④ Separación / combinación: debe "rebotar", no "deslizarse"

El suavizado exponencial de primer orden x += (tx - x)*0.19 nunca sobrepasa el objetivo, siempre se detiene suavemente. Cámbialo a un muelle de segundo orden:

// Por fotograma 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; }   // Si se estrecha demasiado, el ancho se vuelve negativo y se dibuja mal

omX = 15, omW = 18.5, z = 0.66 → aproximadamente 6% de sobreimpulso, período de ~0.45s. La rigidez del ancho debe ser mayor que la del desplazamiento (18.5 > 15); de lo contrario, es "primero se deforma, luego vuelve"; si ambas son iguales, es un desplazamiento de todo el bloque, volviendo a la sensación de madera.

Dos claves para que la separación no parezca "dos bloques empujados":

  • La posición del lado derecho está fija (tx siempre es lay.x + lay.w - un_ancho), solo el ancho varía entre 0 ↔ 140 → visualmente es "se parte desde el centro", no "uno se encoge y el otro se estira, tirando horizontalmente"
  • En el momento de la separación / unión, aplica un flash = 1 de brillo interno a cada pieza, para que la acción tenga peso

Por mucho que se ajuste el coeficiente del suavizado de primer orden, nunca se conseguirá un "rebote". Es un problema de la forma de la curva, no de la velocidad.

7. Ocho errores garantizados (probados en local)

  1. Los uniform tipo array no son fiables. uniform vec4 uGeo[12] hace que getUniformLocation("uGeo[0]") devuelva no nulo en ANGLE/D3D, y uniform4fv no da error, pero los datos no llegan al shader: todos los paneles leen 0, y if(hh.x < 1.5) continue los salta a todos, dejando solo el fondo oscuro. Conclusión: nunca uses arrays uniform para pasar la geometría de varios paneles. En su lugar, haz una llamada de dibujo por panel.

  2. Las ramas en un bucle + uniform pueden ser optimizadas por completo. Escribir if(uOpaque > 0.5){...} dentro de un for puede hacer que el cuerpo del bucle se descarte en algunos drivers. Dentro del bucle, usa siempre mix/step sin ramas. Si es "un dibujo por panel", ni siquiera necesitas el bucle.

  3. Los uniform declarados pero no usados se optimizan, y getUniformLocation devuelve null, dando un falso positivo de "falta uniform". La declaración y el uso deben ir emparejados.

  4. gl.getUniform(prog, null) lanza TypeError, que salta todo el código posterior del mismo fotograma (FPS, sondas no se actualizan), pareciendo que "la página se cuelga". Comprueba si el location es nulo antes de usarlo.

  5. Eje Y de la textura (ver sección 4): si no se invierte, se obtiene una imagen reflejada + texto invertido.

  6. Solo enlazar click provoca pérdida de eventos. En entornos automatizados y algunos hosts, click no se sintetiza, y toda la interacción se queda muda. Usa pointerdown + pointerup + umbral de desplazamiento para detectar clics, y click solo como complemento.

  7. half es una palabra reservada de GLSL ES: escribir vec2 half = uRect.zw*0.5; hace que todo el shader falle, y el registro solo dirá syntax error, siendo muy difícil de localizar. Usa hb para semi-ancho/alto. Otras trampas similares: filter, input, output, long, short, double, packed.

  8. Un smoothstep en orden inverso es un comportamiento indefinido: escrituras como smoothstep(1.0, -1.0, d), smoothstep(-0.30, -0.92, y) con edge0 > edge1 pueden funcionar en el navegador de prueba, pero dar valores basura en otro. Siempre reescribe como 1.0 - smoothstep(-1.0, 1.0, d).

8. Lista de verificación de aceptación (ejecutar después de cada modificación)

Renderizado

  • Los 8 vidrios son visibles, coincidiendo su posición con la tabla de diseño
  • Dentro del vidrio se ve el contenido inferior (texto/barras azules/cuadrícula), no un bloque de color
  • El contenido dentro del vidrio está orientado correctamente (no invertido verticalmente, ni reflejado horizontalmente)
  • Hay un borde brillante alrededor, un especular en la parte superior, un arco brillante en la inferior
  • El interior del vidrio sobre fondo oscuro no es negro muerto (tiene una ligera neblina grisácea)
  • El antialiasing del borde del contorno está limpio, sin bordes duros ni bordes blancos

Interacción (versión detallada en references/interaction-playbook.md)

  • Al hacer clic en la cápsula → el menú crece hacia arriba, el borde inferior no se mueve; otro clic lo oculta
  • Arrastrar la cápsula → sigue el puntero, al soltarlo rebota; al llegar al borde, se limita
  • Al hacer clic en la tecla de separación del Dock → las dos piezas se separan; otro clic se unen
  • Mantener pulsado cualquier panel → se contrae ligeramente + brillo interno; al soltar, vuelve a cero
  • Al pasar el ratón por encima → el brillo se desplaza hacia la dirección del puntero
  • Las teclas Espacio / S / W funcionan (equivalente a la interacción táctil)
  • Al hacer clic en los cuatro botones «Cápsula gruesa / Lente / Texto / Por defecto»: los cinco sliders cambian de posición y valor sincronizadamente, el panel de destino parpadea con un brillo interno
  • Después de cambiar el tamaño de la ventana, los estados de expansión y separación se mantienen

Rendimiento

  • FPS estable, sin caídas periódicas
  • Al cambiar el número de paneles, se reevalúa el número de llamadas de dibujo

9. Presupuesto de rendimiento y degradación

ÍtemPresupuestoQué hacer si se excede
Paneles de vidrio en pantalla≤ 10Combinarlos en uno, o degradar los paneles secundarios a CSS
Área cubierta por cada dibujoSolo cubrir su propio AABBNo ejecutar el pase de vidrio en pantalla completa
Subida de textura de fondoCada 5 fotogramas (las manchas de luz son lentas)Reducir a cada 8 fotogramas cuando esté estático
Relación de píxeles de fondomin(dpr, 1.5)Bajar a 1.0 si hay caídas de fotogramas
Multiplicador de renderizadoAdaptativo 0.72 / 1.0Bajar si < 42fps, subir si > 56fps
Muestreo de brillo inferior getImageDataCada 10 fotogramas, solo para paneles con w*h > 24000Es la mayor sobrecarga síncrona; mejor muestrear menos
Diagrama de trayectorias de luzCada 4 fotogramasReducir a cada 6 fotogramas cuando esté estático
Altura del panel de controlmin(520, VH*0.62, VH-250)Dejar 240px para el diagrama de trayectorias en la esquina inferior derecha; de lo contrario, las ventanas pequeñas se solaparán

Orden de degradación: Reducir el número de paneles → Bajar el multiplicador de renderizado → Reducir la frecuencia de subida del fondo → Desactivar la dispersión → Degradar toda la página a la versión CSS.

10. Líneas rojas de diseño (Apple HIG)

  • El vidrio solo está en la capa de navegación: no cubras la capa de contenido con vidrio.
  • No apiles vidrio: dos vidrios superpuestos pierden la referencia de refracción y parecen manchas sucias.
  • No mezcles variantes: no mezcles Regular y Clear en la misma pantalla.
  • tint solo se aplica a la acción principal, y en un área pequeña; si se tiñe todo, deja de ser vidrio.
  • Brillo contenido: rim es "un borde", no "una línea blanca entera". uRim > 1.2 parece falsa.
  • Deben conservarse tres interruptores de accesibilidad: reducir la transparencia, aumentar el contraste, reducir el movimiento. El primero reemplaza el fondo con un fondo opaco, el último establece el muelle k a 1.
  • Cuando el texto está presionado sobre el vidrio, el contenido DOM debe tener text-shadow; de lo contrario, el texto blanco sobre vidrio brillante no se leerá.

11. Migración a C++ / SwiftUI

  • C++: cpp/glass_math.h contiene las funciones puras H(x), H'(x), fres(), gradiente de grosor, labio, arco rim. Cópialas directamente al fragment shader; el ejemplo de Qt6 solo demuestra la interfaz, no uses la CPU para píxel a píxel en producción.
  • SwiftUI: Prioriza .glassEffect(.regular, in: shape) que usa la implementación del sistema. Solo cuando necesites formas personalizadas o refracción personalizada, dibuja tú mismo SimulatedGlass, y especifica en los comentarios la diferencia con el efecto del sistema (la versión del sistema tiene muestreo de fondo entre procesos y brillo dinámico real).

Skills relacionados