Communitygithub.com

Liquid Glass

Implementação do material, controles e interação completa do Liquid Glass da Apple WWDC25. Use quando o usuário pedir UI de vidro líquido / vidro neumórfico da Apple, botões, cartões, barras de navegação, Dock, menus de vidro translúcido que precisam de clique, expansão, separação/combinação, arrasto e feedback de pressão, ou réplica do material em Web (WebGL/CSS), C++/Qt6, SwiftUI. Cobre refração de lente, deslocamento Snell, borda Fresnel, dispersão RGB, gradiente de espessura, lábio de lente, brilho interno, variantes Regular/Clear, adaptação claro/escuro, desvanecimento de borda de rolagem e arquitetura de desempenho com draw calls independentes por painel. Acompanha o esqueleto mínimo executável starter/glass-starter.html (1 programa, 1 draw, já verificado na prática) – modifique a partir dele, não escreva shaders do zero.

O que é Liquid Glass?

O Liquid Glass é uma skill especializada na implementação do efeito de vidro líquido (Liquid Glass) apresentado pela Apple no WWDC25. Ela fornece materiais, controles e interações completas para recriar o visual vítreo em aplicações web, desktop e mobile. A skill cobre todos os aspectos essenciais: refração Snell com deslocamento lateral ponderado pela espessura, borda Fresnel com brilho e opalescência, dispersão RGB, gradiente de espessura, lábio de lente (edge pinch para ampliação/compressão), brilho especular superior que segue o ponteiro, arco inferior, brilho interno propagante entre painéis, e desvanecimento nas bordas de rolagem. Ela suporta as plataformas WebGL (principal), CSS/SVG (fallback), C++/Qt6 e SwiftUI. O fluxo de trabalho é orientado a um starter funcional de 90 linhas de shader com um único programa e um único draw call, que já inclui todos os efeitos básicos. A partir dele, o usuário ajusta parâmetros como refração, ampliação, borda, dispersão e matiz para obter diferentes variantes (cápsula espessa, lente, texto, padrão). A skill também oferece análise de raio óptico em tempo real, depuração visual com campos de diagnóstico (wireframe), e uma arquitetura de renderização otimizada que processa cada painel de vidro apenas em seu AABB, evitando passes de tela cheia. Inclui ainda um checklist de verificação, orçamento de desempenho, diretrizes de design HIG, e soluções para 8 problemas comuns identificados em testes reais.

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

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Implementação Liquid Glass

0. Caminho Mais Rápido (Siga e Tenha um Vidro Funcional em 10 Minutos)

Não escreva shaders do zero. Escrever 400 linhas de GLSL do zero tem baixíssima taxa de sucesso; a maioria dos resultados "não parece vidro" acontece por causa desse passo.

  1. Copie starter/glass-starter.html para o diretório de entrega.
  2. Altere apenas os cinco números do CONFIG no topo do arquivo (refract / mag / rim / disp / tint). Recarregue e veja as mudanças.
  3. Substitua o conteúdo desenhado em drawBG() pelo conteúdo que o usuário deseja por baixo. Este é o passo mais crítico: 90% do efeito de vidro vem do que está por baixo dele.
  4. Ajuste a largura, altura e raio do canto no PANEL para definir a forma do vidro (r = h/2 resulta em uma cápsula completa).
  5. Para mais vidros, duplique o retângulo e desenhe cada um em uRect dentro do loop (a arquitetura está na seção 3).

O starter tem apenas ~90 linhas de shader, 1 programa, 1 draw, e já inclui: refração Snell, deslocamento lateral ponderado por espessura, borda Fresnel, opalescência nas bordas, faixa de brilho no topo, arco brilhante na parte inferior, dispersão RGB, lábio de lente, e feedback de pressão. Ele foi testado e verificado em execução no Chrome (incluindo SwiftShader de renderização por software).

Para ver o resultado imediatamente: abra starter/glass-starter.html no navegador, arraste o mouse sobre o vidro e observe a barra azul sendo ampliada e deslocada.

0.5 Três Regras Rígidas

  1. Você DEVE abrir e verificar antes de entregar. Escrever o código sem abrir e ver é a principal causa de falha desta skill. Sem GUI, use screenshot headless:

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

    E então realmente leia a imagem para confirmar que o vidro apareceu. Sem evidência de screenshot, não declare a tarefa como concluída.

  2. Erros de shader DEVEM ser exibidos na página. console.error não aparece em screenshots; você só verá uma tela preta sem saber o motivo. Imediatamente após compileShader:

    if (!gl.getShaderParameter(s, gl.COMPILE_STATUS))
      appendPre("Falha na compilação do shader:\n" + gl.getShaderInfoLog(s));   // appendPre = insere um <pre> vermelho no body
    
  3. Primeiro faça funcionar com um, depois adicione mais. Deixe um vidro correto primeiro, depois adicione o segundo. Refração + interação + múltiplos painéis + animação tudo ao mesmo tempo impossibilita a localização de erros.

0.6 Não Parece Vidro? Verifique pelos Sintomas

SintomaCausa Mais ProvávelSolução
Tela toda preta, só o fundo apareceO painel não foi desenhadoVerifique se uRect foi passado, se uRad é 0, se o draw é com 4 vértices TRIANGLE_STRIP
Imagem espelhada / texto invertido no vidroEixo Y da textura invertidoSe UNPACK_FLIP_Y estiver ativado, amostre 1.0 - uv.y; caso contrário, use uv.y diretamente
Sem refração visível, apenas desfoqueMagnitude de deslocamento muito pequenaoff = lat * tpx * refract; primeiro verifique se tpx tem dezenas de pixels; aumente refract para 3 temporariamente para ver se há mudança
Borda com anel de arco-íris duroDispersão espalhada por toda a bordaMultiplique a dispersão por eW*eW (atenuação quadrática) para separar canais apenas na borda mais externa
Vidro parece plástico cinzaConteúdo inferior muito monótonoDeve haver conteúdo de alto contraste por baixo (texto, barras coloridas, grade), senão qualquer parâmetro parecerá névoa
Brilho do topo segue o mouse como uma lanternaFaixa de brilho foi estreitada horizontalmenteMantenha a luminosidade base em toda a borda; o ponteiro faz apenas um realce local (0.7 base + 0.3 ganho)
Animação mole e sem energiaUsou easing exponencial de primeira ordemTroque para mola de segunda ordem, amortecimento 0.60.7, permitindo 58% de overshoot (veja seção 6.5)
Queda de FPS para abaixo de 30Muitos painéis / draw de tela cheia por frameRasterize cada vidro apenas em seu próprio AABB; no máximo 10 na mesma tela; reduza a frequência de upload do fundo

Para a versão flagship (múltiplos painéis, interação completa, análise de raio óptico), continue lendo. Para apenas um vidro, o starter é suficiente; leia até a seção 4.

1. Decisão de Plataforma

ObjetivoQual Asset UsarDescrição
Vidro único / Rápido para acertarstarter/glass-starter.html90 linhas de shader, 1 draw, já testado. Modifique a partir deste, não escreva do zero
Web / Demonstração / Protótipo interativo (preferencial)liquid-glass-studio.htmlCanvas WebGL único + 9 vidros + interação completa + análise de raio óptico em tempo real. Refração Snell real, dispersão, gradiente de espessura
Apenas um vidro, sem complicaçõesliquid-glass-webgl.htmlVersão leve de painel único e um passe, deslocamento aproximado, sem camada de interação
Sem WebGL / Precisa de fallbackliquid-glass-css.htmlbackdrop-filter + deslocamento SVG, comportamento aproximado, mas sem refração pixel a pixel
Desktop C++ / Renderizador personalizadocpp/glass_math.h + cpp/qt6/Biblioteca matemática pura + controles Qt6; em produção, mova as fórmulas para GLSL
iOS / macOS nativoswift/LiquidGlassDemo.swiftAPI oficial .glassEffect; para versões mais antigas, use SimulatedGlass como fallback

Por que WebGL é preferencial: A refração precisa amostrar o conteúdo inferior pixel a pixel; CSS só pode fazer deslocamento de bloco inteiro, e o "lábio de lente" nas bordas é impossível de replicar.

2. Ativos e Documentação

liquid-glass/
├── starter/
│   └── glass-starter.html        # Esqueleto mínimo executável: 90 linhas de shader, 1 programa 1 draw, já verificado
├── liquid-glass-studio.html      # Flagship: interação completa + raio óptico em tempo real (principal entrega desta skill)
├── liquid-glass-webgl.html       # Versão leve de painel único
├── liquid-glass-css.html         # Fallback CSS/SVG
├── cpp/
│   ├── glass_math.h              # SDF, squircle, funções puras Snell/Fresnel, dispersão BK7, espessura/lábio/arco rim
│   └── qt6/                      # Projeto CMake
├── swift/LiquidGlassDemo.swift   # API oficial + fallback simulado
└── references/
    ├── feature-matrix.md         # Matriz de 22 recursos da Session 219, cobertura por plataforma, linhas de design
    ├── optics-model.md           # Modelo físico do caminho óptico e faixas de parâmetros (leia antes de escrever shaders)
    ├── interaction-playbook.md   # Máquina de estados para clique/expansão/separação/arrasto e lista de verificação
    └── swiftui-api.md            # Assinaturas da API SwiftUI para vidro e notas importantes

3. Arquitetura de Renderização (versão studio)

Dois programas, 9 draw calls. Nunca coloque vários vidros em um array de uniform de um passe de tela cheia.

Passo 1  pBg   : Quad de tela cheia, amostra diretamente a textura de fundo
Passo 2  pGl   : Mesmo VBO de quad, cada vidro é transladado/escalado para seu AABB, um drawArrays

O shader de vértice mapeia o quad [-1,1] para o painel:

uniform vec2 uC, uH, uRes;          // Centro, meia largura/altura, dimensões do canvas (em pixels de dispositivo)
void main(){
  vec2 cN = (uC/uRes)*2.0 - 1.0;  cN.y = -cN.y;      // Origem topo-esquerda da tela → NDC
  vec2 hN = ((uH + vec2(6.0))/uRes)*2.0;             // Expande 6px para anti-aliasing
  gl_Position = vec4(cN + vec2(aPos.x, -aPos.y)*hN, 0.0, 1.0);
}

O fragmento usa gl_FragCoord para calcular as coordenadas da tela (não varying, que no quad transladado são coordenadas locais):

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;                 // Pixels fora do contorno dentro do AABB são descartados
gl_FragColor = vec4(gcol, 1.0 - aa);    // Borda usa transição alpha

Externamente, habilite gl.enable(BLEND) + blendFunc(SRC_ALPHA, ONE_MINUS_SRC_ALPHA) e desabilite após desenhar.

Dessa forma, cada vidro rasteriza apenas seu próprio retângulo; 8 vidros têm taxa de preenchimento aproximadamente igual a um de tela cheia – uma ordem de magnitude mais rápida que "tela cheia × 8 iterações".

Uniformes escalares que devem ser definidos para cada vidro em um draw (ordem fixa, nenhum pode faltar):

uniformSignificadoOrigem
uC uHCentro / meia largura-altura da tela (pixels de dispositivo, origem topo-esquerda)(g.x+g.w/2)*dpr etc.
uRadRaio do canto (pixels de dispositivo)min(g.radius, min(w,h)/2)*dpr
uVariant uThick uMagMulVariante / material espesso / ampliação por painelAtributos do painel
uHover uPress uGlow uActiveEstado de interação 0~1Valores de mola por frame
uPtrCoordenada do ponteiro normalizada dentro do painel −1~1(cx-c)/(w/2)
uAmbCor ambiente da camada inferior rgbAmostragem getImageData
GlobaisuRes uTex uRefraction uRim uTint uDisp uN uMode uContrast uOpaque uMag uWireDefinidos uma vez por frame

4. Modelo de Caminho Óptico (Leia Esta Seção Antes de Escrever Shaders)

Sete passos, a ordem não pode ser alterada:

  1. Contorno: sdRoundBox para distância com sinal d (negativo dentro). Profundidade normalizada x = clamp(-d/band, 0, 1), 0 = contorno, 1 = centro; band = max(5, min(hx,hy)*0.30).
  2. Campo de altura convexa: H(x) = sqrt(1 - (1-x)²), H'(x) = v/sqrt(1-v²) (v = clamp(1-x, 0.02, 0.9995)). Use sqrt em vez de pow – pow é muito mais lento no ANGLE.
  3. Ângulo de incidência: sinI = min(H'/sqrt(1+H'²), 0.62), thI = asin(sinI), thT = asin(sinI/n), n = 1.5168 (BK7). Limite superior de 0.62 é uma restrição rígida: se for para 0.93, o deslocamento da borda chega a 200px, empurrando todo o painel para um bloco preto.
  4. Espessura: tpx = mdim*(0.05 + 0.28*H)*(1 + 0.40*thick)*vg, vg = 1 + 0.24*(1 - smoothstep(-0.85, 0.35, q.y)) (mais espesso embaixo, mais fino em cima). tpx é a "espessura em pixels", faixa normal 0.1 ~ 0.4 * mdim. Acima de 0.5, há distorção.
  5. Deslocamento: lat = tan(thI-thT), off = -dir*lat*tpx*uRefraction*Tf, mais um termo de borda -dir*(1-smoothstep(0,0.28,x))*tpx*0.22. Finalmente off = clamp(off, -10, 10) – a limitação é a única garantia contra "puxar conteúdo distante para dentro da borda".
  6. Foco / Lábio 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 → ponto de amostragem converge para o centro → ampliação; borda focal < 0 → ponto de amostragem se expande para fora → conteúdo é dobrado para fora, este é o lábio da Apple. 1-focal deve ser sempre positivo, caso contrário ocorre inversão local de 180° e texto aparece de cabeça para baixo. uMagMul é a ampliação por painel (veja seção 6): vidros pequenos têm curvatura maior e ampliam mais; painéis grandes são quase planos e ampliam menos. Sem esse coeficiente, usar o mesmo uMag faria com que um painel de texto 214×300 fosse amplificado a ponto de ficar ilegível, enquanto uma lente 158×126 não teria ampliação suficiente. Correspondência entre tamanho do painel e magMul: lens 1,30, plate 0,55, capsule 0,85, panel 0,60, dock 0,80, nav 0,90.
  7. Amostragem e Composição: sp = c + rel*(1-focal) - off; três canais são amostrados separadamente com deslocamento ±uDisp*7*eW para dispersão; em seguida, escurecimento por variant, cor ambiente uAmb 0.10, compressão de brilho do matiz 0.58*L + 0.133, preenchimento de campo escuro +vec3(0.048,0.051,0.058), borda Fresnel + opalescência + especular superior + arco inferior ((1+0.75*press)), brilho interno.

A Coordenada de Textura DEVE Ter Inversão Y

O canvas de fundo é enviado com UNPACK_FLIP_Y_WEBGL = true, então v=0 na textura corresponde à parte inferior da tela; enquanto px tem origem no topo. Portanto:

vec2 uv0 = vec2(sp.x/uRes.x, 1.0 - sp.y/uRes.y);   // Faltar esta linha = vidro capturando imagem espelhada

Isso não é opcional. O sintoma é: texto invertido dentro do vidro e conteúdo vindo do lado oposto da tela.

5. Análise de Raio Óptico em Tempo Real

Dois sistemas, não substituíveis entre si:

A. Campo de Diagnóstico (params.wire = 1) – Desenha as grandezas intermediárias do shader diretamente, para saber "se está realmente refratando":

CanalSignificadoLeitura
Rlength(off)/mdim*22Vermelho = intensidade de curvatura. O centro deve estar quase preto, borda com anel vermelho
Gx (profundidade da borda)Anel verde ao longo do contorno, rapidamente zero para dentro
Bfocal*2Azul = ampliação, centro claro, borda escura

Quando os três aparecem juntos e com regiões distintas, o caminho óptico está funcionando; tudo preto geralmente significa que os uniforms não foram passados (veja armadilha 1 da seção 7).

B. Diagrama de Seção de Raio (canvas 308×150 no canto inferior direito) – Desenha 11 raios de luz atravessando o vidro convexo (incidência / interior / emergência), anotando θi / θt / Δx para raios de borda e o nível de espessura (thin/thick). O painel de foco alterna conforme o ponteiro passa.

As duas curvas (shader e diagrama 2D) DEVEM usar as mesmas fórmulas e o mesmo limite superior de sinI; caso contrário, o diagrama pode mostrar 68° enquanto a tela calcula 38°, enganando o ajuste de parâmetros.

6. Receitas de Parâmetros (Ajuste com Base na Imagem de Referência)

Efeito Desejadorefractmagrimdisptintthick
Cápsula de vidro espesso (grande, borda brilhante, arco inferior evidente, interior escuro)1.200.350.950.220.24✓
Lente sobre barras coloridas (barras ampliadas e deslocadas, pontos claros laterais)1.500.601.000.180.10✓
Vidro espesso sobre texto pequeno (texto ampliado + distorção nas bordas)1.250.420.800.300.16✓
Barra de navegação no topo (fina, contida)0.900.200.600.150.10✗
Painel de controle (grande, texto legível)1.000.150.550.120.14✗
Padrão 01.200.450.850.350.20—

Ordem de ajuste: primeiro refract define a magnitude do deslocamento → depois mag define a força do lábio → depois rim define o brilho da borda → finalmente disp/tint definem a textura. Fazer ao contrário resulta em conflitos constantes.

Alternância Rápida de Três Receitas (já embutida na versão studio)

No topo do painel de controle, há quatro botões: "Cápsula Espessa / Lente / Texto / Padrão". Clicar faz duas coisas simultaneamente: define os cinco sliders com os valores da tabela acima e aplica um flash de brilho interno ao painel correspondente (para indicar visualmente "olhe para 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 }
};

Alterar params no código não dispara o evento input do slider; portanto, é necessário chamar syncUI() manualmente para atualizar as posições e rótulos dos sliders, caso contrário eles ficarão dessincronizados dos parâmetros reais.

O decaimento do flash é escrito dentro de step() e deve ser incorporado ao glow em vez de substituí-lo (senão o brilho de pressionar e segurar será anulado pelo 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 Quatro Detalhes da Apple Mais Frequentemente Esquecidos

Esses três itens aparecem na Session 219, mas são facilmente ignorados ao assistir a demo; sem eles, o "aspecto de vidro" perde qualidade instantaneamente.

① Brilho do topo segue o ponteiro (especular se move, mas não deve correr atrás do ponteiro)

Uma linha brilhante fixa no topo é um "adesivo"; mas fazer o brilho "decair a partir do ponteiro" transforma-o em uma lanterna varrendo o vidro – este é o erro mais comum. O correto é: toda a borda superior brilha constantemente, o ponteiro faz apenas um realce local.

float tx       = q.x - uPtr.x*0.30;                    // Deslocamento do ponteiro deve ser pequeno (0.3, não 0.55)
float baseTop  = 1.0 - smoothstep(-0.92, -0.30, q.y);  // Luminosidade base de toda a borda
float boostTop = 1.0 - smoothstep(0.12, 1.00, abs(tx)); // Ganho extra na posição do ponteiro
float topW     = baseTop * (0.70 + 0.30*boostTop);      // Mínimo 0.70, máximo 1.0

Compare com a escrita errada e suas consequências:

EscritaResultado
smoothstep(-0.30,-0.92,q.y) * (1-smoothstep(0.06,0.72,abs(tx)))Quando o ponteiro se move, apenas um pequeno segmento brilha, o resto fica preto → lanterna
baseTop * (0.70 + 0.30*boostTop)A borda sempre forma uma linha contínua, ligeiramente mais clara no ponteiro → espelho real

Além disso, não escreva smoothstep com ordem inversa: smoothstep(1.0, -1.0, d) e smoothstep(-0.30, -0.92, x) com edge0 > edge1 são comportamento indefinido na especificação GLSL, e algumas implementações podem falhar. Use sempre 1.0 - smoothstep(pequeno, grande, x).

O especular na direção do ponteiro (spec calculado por dot(dir, pdir)) só recebe intensidade quando pressionado; hover não adiciona nada; caso contrário, um ponto brilhante minúsculo persegue a borda ao mover o mouse.

② Brilho interno se propaga para vidros vizinhos (cerca de 12%) Ao pressionar A, o vidro vizinho B também acende ligeiramente, dando a sensação de que "a luz flui entre os vidros".

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

Não ultrapasse 0.15, senão a tela inteira acende, quebrando a linha de design de "brilho controlado".

③ Efeito de desvanecimento na borda de rolagem (Scroll edge effect) O conteúdo atrás do vidro, ao rolar até a borda, deve "se fundir ao fundo", não cortar abruptamente. Use máscara alpha, e apenas quando ainda houver conteúdo:

var st   = el.scrollTop;
var rest = el.scrollHeight - el.clientHeight - st;
var top  = st > 3 ? 28 : 0;              // Se rolou até o topo, não mascara; senão, sempre haverá uma 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%)";

Ponto crucial: mask lê o canal alpha; use rgba(0,0,0,0) em vez de transparent (em algumas implementações antigas, transparent é preto transparente, o comportamento é o mesmo, mas a semântica é mais clara). O container de rolagem deve ter pointer-events:auto para permitir rolagem; mas isso impede que o vidro inteiro receba arrasto – vidros que precisam ser arrastados não devem ter o container de rolagem preenchendo todo o espaço.

④ Separação / Combinação: Deve "esticar", não "deslizar"

Easing exponencial de primeira ordem x += (tx - x)*0.19 nunca ultrapassa, a parada é sempre mole e sem força. Substitua por mola de segunda ordem:

// dt = 1/60 por frame
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; }   // Se encolher demais, vira largura negativa, desenhando errado

omX = 15, omW = 18.5, z = 0.66 → cerca de 6% de overshoot, ~0.45s de período. A rigidez da largura deve ser maior que a do deslocamento (18.5 > 15), resultando em "primeiro deforma, depois retorna"; se forem iguais, o bloco inteiro se move, voltando à sensação de madeira.

Duas chaves para a separação não parecer "duas placas sendo empurradas":

  • Posição da peça direita fixa (tx sempre igual a lay.x + lay.w - largura de uma peça), apenas a largura varia entre 0 ↔ 140 → visualmente parece "rachadura no meio", não "uma encolhe e a outra estica, puxando lateralmente"
  • No instante de abrir / fechar, aplique um flash = 1 de brilho interno em cada peça, para que o movimento tenha peso

Não importa o quanto se aumente o coeficiente de easing de primeira ordem, nunca se consegue o "esticar"; é um problema de formato da curva, não de velocidade.

7. Oito Armadilhas Certas (Testadas em Máquina Real)

  1. Array de uniform não é confiável. uniform vec4 uGeo[12] – no ANGLE/D3D, getUniformLocation("uGeo[0]") retorna não-nulo, uniform4fv não dá erro, mas os dados não entram no shader – todos os painéis leem 0, são pulados por if(hh.x < 1.5) continue, e a página fica apenas com fundo escuro. Conclusão: nunca use array de uniform para passar geometria de múltiplos painéis; use um draw call por painel.

  2. Loop + branch com uniform pode ser otimizado inteiro. for com if(uOpaque > 0.5){...} em alguns drivers descarta o corpo do loop. Dentro do loop, use apenas mix/step sem branches. Se for "um draw por painel", nem precisa de loop.

  3. Uniform declarado mas não usado é otimizado, getUniformLocation retorna null, dando falso positivo de "uniform faltando". Declaração e uso devem andar juntos.

  4. gl.getUniform(prog, null) lança TypeError, que pula todo o código seguinte do mesmo frame (FPS, probes não atualizam), parecendo que "a página travou". Sempre verifique se o location não é nulo.

  5. Eixo Y da textura (veja seção 4): sem inversão, a imagem fica espelhada e o texto invertido.

  6. Apenas vincular click perde eventos. Em ambientes automatizados ou alguns hosts, click não é sintetizado, e a interação fica muda. Use pointerdown + pointerup + limiar de deslocamento para detectar clique, e click apenas como complemento.

  7. half é palavra reservada do GLSL ES: escrever vec2 half = uRect.zw*0.5; faz o shader inteiro falhar na compilação, e o log só dirá syntax error, extremamente difícil de localizar. Use hb para meia largura/altura. Outras palavras na zona de risco: filter, input, output, long, short, double, packed.

  8. smoothstep com ordem inversa é comportamento indefinido: smoothstep(1.0, -1.0, d), smoothstep(-0.30, -0.92, y) com edge0 > edge1 podem funcionar no navegador que você testa, mas em outro podem produzir lixo. Reescreva sempre como 1.0 - smoothstep(-1.0, 1.0, d).

8. Lista de Verificação (Execute Após Cada Alteração)

Renderização

  • Todos os 8 vidros estão visíveis, posições consistentes com a tabela de layout
  • O interior do vidro mostra o conteúdo inferior (texto/barras azuis/grid), não um bloco de cor sólida
  • O conteúdo dentro do vidro tem orientação correta (não invertido, não espelhado)
  • Há um anel brilhante na borda, brilho especular no topo, arco brilhante na parte inferior
  • Em fundo escuro, o interior do vidro não é preto total (tem uma leve névoa acinzentada)
  • Anti-aliasing limpo nas bordas do contorno, sem arestas duras ou bordas brancas

Interação (versão detalhada em references/interaction-playbook.md)

  • Clicar na cápsula → menu cresce para cima, borda inferior fixa; clicar novamente recolhe
  • Arrastar cápsula → segue, solta e volta; é limitado na borda
  • Clicar no botão de separação do Dock → duas peças se abrem; clicar novamente se fecham
  • Pressionar qualquer painel → leve encolhimento + brilho interno; soltar retorna ao normal
  • Hover → brilho desloca em direção ao ponteiro
  • Teclas Espaço / S / W têm efeito
  • Clicar nos quatro botões "Cápsula Espessa / Lente / Texto / Padrão": posições dos cinco sliders e valores numéricos mudam sincronizadamente, o painel alvo pisca com brilho interno
  • Após redimensionamento, os estados de expansão e separação são mantidos

Desempenho

  • FPS estável, sem quedas periódicas
  • Após alterar o número de painéis, reavalie o número de draw calls

9. Orçamento de Desempenho e Degradação

ItemOrçamentoO que fazer se exceder
Painéis de vidro na mesma tela≤ 10Mesclar em um ou reduzir painéis secundários para fallback CSS
Área coberta por cada drawApenas seu próprio AABBNão executar passe de vidro em tela cheia
Upload de textura de fundoA cada 5 frames (manchas são lentas)Reduzir para a cada 8 frames quando parado
Proporção de pixels do fundomin(dpr, 1.5)Se cair FPS, reduzir para 1.0
Fator de renderizaçãoAdaptativo 0.72 / 1.0Se < 42fps, reduz; se > 56fps, aumenta
Amostragem de brilho inferior getImageDataA cada 10 frames, apenas painéis com w*h > 24000É o maior custo síncrono; prefira amostrar menos
Diagrama de seção de raioA cada 4 framesPode reduzir para a cada 6 frames quando parado
Altura do painel de controlemin(520, VH*0.62, VH-250)Deixar 240px para o diagrama de raio no canto inferior direito, senão janelas pequenas sobrepõem

Ordem de degradação: Reduzir número de painéis → Reduzir fator de renderização → Reduzir frequência de upload do fundo → Desligar dispersão → Página inteira cai para versão CSS.

10. Linhas de Design (HIG da Apple)

  • Vidro apenas na camada de navegação: a camada de conteúdo não deve ser coberta por vidro.
  • Não empilhe vidro: dois vidros sobrepostos perdem a referência de refração e parecem manchas sujas.
  • Não misture variantes: Regular e Clear não devem aparecer na mesma tela.
  • tint apenas para ação principal e em área pequena; tingir o vidro inteiro não é mais vidro.
  • Brilho controlado: rim é "um anel", não "uma faixa branca inteira". uRim > 1.2 parecerá falso.
  • Três chaves de acessibilidade devem ser mantidas: reduzir transparência, aumentar contraste, reduzir movimento. A primeira substitui o conteúdo de fundo por opaco, a última define a mola k como 1.
  • Quando texto estiver sobre vidro, o conteúdo DOM deve ter text-shadow; caso contrário, texto branco em vidro claro não será legível.

11. Migração para C++ / SwiftUI

  • C++: cpp/glass_math.h contém as mesmas funções puras H(x), H'(x), fres(), gradiente de espessura, lábio, arco rim – mova diretamente para o shader de fragmento; o exemplo Qt6 demonstra apenas a forma da interface; em produção, não use CPU para pixel a pixel.
  • SwiftUI: Prefira .glassEffect(.regular, in: shape) que usa a implementação do sistema; apenas se precisar de forma personalizada ou refração personalizada, desenhe manualmente SimulatedGlass e documente nos comentários as diferenças em relação ao efeito do sistema (a versão do sistema tem amostragem de fundo entre processos e brilho dinâmico real).

Habilidades Relacionadas