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.
- Copie
starter/glass-starter.htmlpara o diretório de entrega. - Altere apenas os cinco números do
CONFIGno topo do arquivo (refract / mag / rim / disp / tint). Recarregue e veja as mudanças. - 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. - Ajuste a largura, altura e raio do canto no
PANELpara definir a forma do vidro (r = h/2 resulta em uma cápsula completa). - Para mais vidros, duplique o retângulo e desenhe cada um em
uRectdentro 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
-
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.
-
Erros de shader DEVEM ser exibidos na página.
console.errornão aparece em screenshots; você só verá uma tela preta sem saber o motivo. Imediatamente apóscompileShader: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 -
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
| Sintoma | Causa Mais Provável | Solução |
|---|---|---|
| Tela toda preta, só o fundo aparece | O painel não foi desenhado | Verifique se uRect foi passado, se uRad é 0, se o draw é com 4 vértices TRIANGLE_STRIP |
| Imagem espelhada / texto invertido no vidro | Eixo Y da textura invertido | Se UNPACK_FLIP_Y estiver ativado, amostre 1.0 - uv.y; caso contrário, use uv.y diretamente |
| Sem refração visível, apenas desfoque | Magnitude de deslocamento muito pequena | off = 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 duro | Dispersão espalhada por toda a borda | Multiplique a dispersão por eW*eW (atenuação quadrática) para separar canais apenas na borda mais externa |
| Vidro parece plástico cinza | Conteúdo inferior muito monótono | Deve 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 lanterna | Faixa de brilho foi estreitada horizontalmente | Mantenha 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 energia | Usou easing exponencial de primeira ordem | Troque para mola de segunda ordem, amortecimento 0.6 |
| Queda de FPS para abaixo de 30 | Muitos painéis / draw de tela cheia por frame | Rasterize 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
| Objetivo | Qual Asset Usar | Descrição |
|---|---|---|
| Vidro único / Rápido para acertar | starter/glass-starter.html | 90 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.html | Canvas 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ções | liquid-glass-webgl.html | Versão leve de painel único e um passe, deslocamento aproximado, sem camada de interação |
| Sem WebGL / Precisa de fallback | liquid-glass-css.html | backdrop-filter + deslocamento SVG, comportamento aproximado, mas sem refração pixel a pixel |
| Desktop C++ / Renderizador personalizado | cpp/glass_math.h + cpp/qt6/ | Biblioteca matemática pura + controles Qt6; em produção, mova as fórmulas para GLSL |
| iOS / macOS nativo | swift/LiquidGlassDemo.swift | API 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):
| uniform | Significado | Origem |
|---|---|---|
uC uH | Centro / meia largura-altura da tela (pixels de dispositivo, origem topo-esquerda) | (g.x+g.w/2)*dpr etc. |
uRad | Raio do canto (pixels de dispositivo) | min(g.radius, min(w,h)/2)*dpr |
uVariant uThick uMagMul | Variante / material espesso / ampliação por painel | Atributos do painel |
uHover uPress uGlow uActive | Estado de interação 0~1 | Valores de mola por frame |
uPtr | Coordenada do ponteiro normalizada dentro do painel −1~1 | (cx-c)/(w/2) |
uAmb | Cor ambiente da camada inferior rgb | Amostragem getImageData |
| Globais | uRes uTex uRefraction uRim uTint uDisp uN uMode uContrast uOpaque uMag uWire | Definidos 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:
- Contorno:
sdRoundBoxpara distância com sinald(negativo dentro). Profundidade normalizadax = clamp(-d/band, 0, 1),0 = contorno,1 = centro;band = max(5, min(hx,hy)*0.30). - Campo de altura convexa:
H(x) = sqrt(1 - (1-x)²),H'(x) = v/sqrt(1-v²)(v = clamp(1-x, 0.02, 0.9995)). Usesqrtem vez depow–powé muito mais lento no ANGLE. - Â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. - 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 normal0.1 ~ 0.4 * mdim. Acima de 0.5, há distorção. - 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. Finalmenteoff = clamp(off, -10, 10)– a limitação é a única garantia contra "puxar conteúdo distante para dentro da borda". - 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). Centrofocal > 0→ ponto de amostragem converge para o centro → ampliação; bordafocal < 0→ ponto de amostragem se expande para fora → conteúdo é dobrado para fora, este é o lábio da Apple.1-focaldeve 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 mesmouMagfaria 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 emagMul:lens 1,30,plate 0,55,capsule 0,85,panel 0,60,dock 0,80,nav 0,90. - Amostragem e Composição:
sp = c + rel*(1-focal) - off; três canais são amostrados separadamente com deslocamento±uDisp*7*eWpara dispersão; em seguida, escurecimento porvariant, cor ambienteuAmb0.10, compressão de brilho do matiz0.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":
| Canal | Significado | Leitura |
|---|---|---|
| R | length(off)/mdim*22 | Vermelho = intensidade de curvatura. O centro deve estar quase preto, borda com anel vermelho |
| G | x (profundidade da borda) | Anel verde ao longo do contorno, rapidamente zero para dentro |
| B | focal*2 | Azul = 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 Desejado | refract | mag | rim | disp | tint | thick |
|---|---|---|---|---|---|---|
| Cápsula de vidro espesso (grande, borda brilhante, arco inferior evidente, interior escuro) | 1.20 | 0.35 | 0.95 | 0.22 | 0.24 | ✓ |
| Lente sobre barras coloridas (barras ampliadas e deslocadas, pontos claros laterais) | 1.50 | 0.60 | 1.00 | 0.18 | 0.10 | ✓ |
| Vidro espesso sobre texto pequeno (texto ampliado + distorção nas bordas) | 1.25 | 0.42 | 0.80 | 0.30 | 0.16 | ✓ |
| Barra de navegação no topo (fina, contida) | 0.90 | 0.20 | 0.60 | 0.15 | 0.10 | ✗ |
| Painel de controle (grande, texto legível) | 1.00 | 0.15 | 0.55 | 0.12 | 0.14 | ✗ |
| Padrão 0 | 1.20 | 0.45 | 0.85 | 0.35 | 0.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:
| Escrita | Resultado |
|---|---|
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 (
txsempre igual alay.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 = 1de 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)
-
Array de uniform não é confiável.
uniform vec4 uGeo[12]– no ANGLE/D3D,getUniformLocation("uGeo[0]")retorna não-nulo,uniform4fvnão dá erro, mas os dados não entram no shader – todos os painéis leem 0, são pulados porif(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. -
Loop + branch com uniform pode ser otimizado inteiro.
forcomif(uOpaque > 0.5){...}em alguns drivers descarta o corpo do loop. Dentro do loop, use apenasmix/stepsem branches. Se for "um draw por painel", nem precisa de loop. -
Uniform declarado mas não usado é otimizado,
getUniformLocationretorna null, dando falso positivo de "uniform faltando". Declaração e uso devem andar juntos. -
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. -
Eixo Y da textura (veja seção 4): sem inversão, a imagem fica espelhada e o texto invertido.
-
Apenas vincular
clickperde eventos. Em ambientes automatizados ou alguns hosts,clicknão é sintetizado, e a interação fica muda. Usepointerdown + pointerup + limiar de deslocamentopara detectar clique, eclickapenas como complemento. -
halfé palavra reservada do GLSL ES: escrevervec2 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. Usehbpara meia largura/altura. Outras palavras na zona de risco:filter,input,output,long,short,double,packed. -
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 como1.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
-
FPSestá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
| Item | Orçamento | O que fazer se exceder |
|---|---|---|
| Painéis de vidro na mesma tela | ≤ 10 | Mesclar em um ou reduzir painéis secundários para fallback CSS |
| Área coberta por cada draw | Apenas seu próprio AABB | Não executar passe de vidro em tela cheia |
| Upload de textura de fundo | A cada 5 frames (manchas são lentas) | Reduzir para a cada 8 frames quando parado |
| Proporção de pixels do fundo | min(dpr, 1.5) | Se cair FPS, reduzir para 1.0 |
| Fator de renderização | Adaptativo 0.72 / 1.0 | Se < 42fps, reduz; se > 56fps, aumenta |
Amostragem de brilho inferior getImageData | A cada 10 frames, apenas painéis com w*h > 24000 | É o maior custo síncrono; prefira amostrar menos |
| Diagrama de seção de raio | A cada 4 frames | Pode reduzir para a cada 6 frames quando parado |
| Altura do painel de controle | min(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.2parecerá 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
kcomo 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.hcontém as mesmas funções purasH(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 manualmenteSimulatedGlasse 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).