Liquid Glass · 전 기능 구현은(는) 무엇을 하나요?
단일 파일 WebGL 구현, 유리의 굴절/두께/Fresnel/분산/림/내부 발광을 모두 프래그먼트 셰이더에서 계산하며, DOM은 텍스트, 버튼 및 그림자만 렌더링합니다.
셰이더를 처음부터 직접 작성하지 마세요: 90줄이면 실행되지만, 400줄을 처음부터 작성하면 성공률이 매우 낮습니다. liquid-glass-all.html에서 수정하세요.
0. 가장 빠른 경로 (1분 안에 효과 확인)
- Chrome / Edge로
liquid-glass-all.html을 엽니다. - 오른쪽 제어판에 5개의 슬라이더(refract / mag / rim / disp / tint) + 4개의 레시피 키가 있으며, 수정 즉시 변경 사항을 확인할 수 있습니다.
- 모든 동작이 포함되어 있습니다: 캡슐 클릭하여 펼치기, 길게 눌러 드래그, 길게 누르면 버블 생성, 우클릭으로 다른 메뉴, 더블클릭으로 들어올리기, Dock 분리 키, 키보드 Space/S/W/Esc.
- 내장 자체 테스트로 검증: 주소 뒤에
?selftest=1을 추가하면 페이지 왼쪽 상단에 13개의PASS / FAIL이 직접 출력됩니다. - 스크린샷 촬영:
?pose=1로 '펼치기 + 분리 + 버블'을 한 번에 배치하고,?pose&wire=1로 광로 진단 필드를 겹칩니다.
chrome --headless=new --enable-unsafe-swiftshader --virtual-time-budget=6000 ^
--window-size=1280,800 --screenshot=out.png "file:///<absolute-path>/liquid-glass-all.html?selftest=1"
스크린샷을 찍은 후 실제로 이미지를 읽어서 왼쪽 상단이 FAIL 0인지 확인하세요. 코드만 보고 완료했다고 판단하지 마세요.
1. 자산
liquid-glass-all/
├── SKILL.md # 이 파일: 경로, 동작, 광로, 함정, 검증
├── liquid-glass-all.html # 전 기능 구현 (유일한 실행 산출물)
└── references/
├── action-matrix.md # 82개 동작 전체 표 (트리거 / 변경 사항 / 매개변수 / 역동작)
├── feature-matrix.md # 26개 재질 특성 × 본 구현의 적용 범위
├── optics-model.md # 광로 물리 모델과 상수 (셰이더 작성 전 필독)
└── interaction-playbook.md # 상태 기계, 타이밍, 히트 테스트, 검증
2. 82개 동작 빠른 참조 (9개 범주)
전체 표는 references/action-matrix.md를 참조하세요. 여기서는 골격만 제공합니다.
| 범주 | 개수 | 내용 |
|---|---|---|
| A 포인터 | 13 | 호버 진입/이동/이탈, 주변 감쇠, press, release, 클릭, 드래그 시작/추종/탄성 복귀, 경계 clamp, 우클릭 메뉴, 길게 누르기 메뉴 |
| B 드래그 관성 | 6 | 방향 스트레칭, 탄성 평행 이동, 변형 감쇠, 관성 슬라이드, 드래그 들어올리기, 지연 잔상 |
| C 형태 Morph | 10 | 펼치기/접기, 메뉴 항목 페이드 인, 모서리 둥글기 추종, 분리/오른쪽 조각 생성/합치기, 분열 강세, 너비 0 건너뛰기, 융합 연결 목 |
| D 누름 반응 | 8 | 수축, 굴절 강화, 두께 증가, 내부 발광, 이웃 패널 전파, 하단 아치 밝아짐, 방향 하이라이트, flash 길 안내 |
| E 광학 애니메이션 | 8 | 3가지 굴절 모드, 변형 전환, tint 매핑, 명암 반전, 환경 오버플로 색상, 적응형 그림자, 초점 흐려짐 퇴장, 배경 광점 표류 |
| F 적응형 | 7 | 밝기/주 색상 샘플링, 배경 업로드, 적응형 해상도, 광로 갱신, DPR 상한, 성능 저하 체인 |
| G 시스템 및 접근성 | 8 | resize 재배치, 스크롤 soft/hard, 3개 접근성 스위치, 창 포커스 상실, Tab 포커스 링, 스크린 리더 시맨틱 |
| H 컨트롤 | 8 | 주 작업 버튼, 5개 슬라이더, 변형 세그먼트, 모드 3키, 4개 스위치, 4개 레시피, 분리 키, 펼치기 헤더 |
| K 키보드 | 7 | Space / S / W / Esc / Tab / ↑↓ / Enter |
동작 모니터 막대가 페이지 하단에 있습니다: 각 동작을 기록하고 최근 4개를 표시하여 '이 동작이 실제로 트리거되었는지' 확인합니다.
3. 광로 7단계 (순서 변경 불가)
- 윤곽:
sdRoundBox로 부호 있는 거리d를 구합니다.x = clamp(-d/band, 0, 1),0=윤곽,1=중심,band = max(5, min(hx,hy)*0.30). - 볼록 높이 필드:
H(x)=sqrt(1-(1-x)²),H'(x)=v/sqrt(1-v²)(v=clamp(1-x,0.02,0.9995)). pow 대신 sqrt를 사용합니다. - 입사각:
sinI = min(H'/sqrt(1+H'²), 0.62),thT = asin(sinI/1.5168). 0.62는 하드 상한이며, 0.93으로 올리면 가장자리가 200px 수준으로 밀려나 전체가 검게 변합니다. - 두께:
tpx = mdim*(0.05+0.28*H)*(1+0.40*thick)*vg,vg = 1+0.24*(1-smoothstep(-0.85,0.35,q.y))(아래는 두껍고 위는 얇음). - 변위:
off = -dir*tan(thI-thT)*tpx*refract*Tf, 가장자리 항 추가; 마지막으로clamp(off,-10,10). - 초점/림:
focal = mag*magMul*(0.50*cW - 0.40*eW);1-focal은 항상 양수여야 합니다. 그렇지 않으면 국소적으로 180° 뒤집혀 글자가 거꾸로 보입니다.magMul은 패널 수준: lens 1.30 / capsule 0.85 / plate 0.55 / nav 0.90 / dock 0.80. - 합성:
sp = c + rel*(1-focal) - off; RGB를±disp*7*eW로 분리 샘플링; tint 밝기 압축0.58*L+0.133, 환경 오버플로 색상 0.10, Fresnel rim, 유백색, 상단 거울, 하단 아치, 내부 발광.
텍스처 Y는 뒤집어야 합니다: uv0 = vec2(sp.x/uRes.x, 1.0 - sp.y/uRes.y), 이 한 줄이 없으면 이미지가 미러링되고 글자가 거꾸로 표시됩니다.
4. 상태 기계 및 주요 임계값
| 동작 | 임계값 / 매개변수 |
|---|---|
| hover | 패널 내부; 패널 외부 180px 내에서 fade 감쇠 |
| press | press→1(k=0.19/프레임), scale 0.965, 굴절 ×1.3, 하단 아치 ×1.75 |
| 클릭 | pointerup 및 변위 ≤4px → 240ms 지연 후 트리거, 더블클릭과 충돌 방지 |
| 더블클릭 | 두 번의 pointerdown 간격 <300ms, 두 번째 down에서 즉시 클릭 타이머 취소 |
| 길게 누르기 | pointerdown 후 500ms, 이동 >4px이면 취소; 진행 점이 터치 포인트에서 확대 |
| 드래그 | 변위 >4px여야 드래그로 전환; clamp 8px 내부 여백 |
| 관성 | 손을 놓은 속도 >6px/이벤트 → v*1.05 시작, 프레임당 ×0.94, <1px에서 종료 및 고정 |
| 펼치기 | 136×48 → 236×296, 아래쪽 가장자리 고정: ty = lay.y + lay.h - 296; 메뉴 항목은 높이 110→250으로 페이드 인, 절반 이상에서 pointerEvents 활성화 |
| 분리 | Dock 300 → 왼쪽 140; 오른쪽 조각 tx를 lay.x + lay.w - 140에 고정, 너비 0→140 |
| 합치기 | 오른쪽 조각이 먼저 너비를 줄이고 위치는 고정('미끄러짐' 방지) |
| 융합 | 분리 후 두 조각 사이에 20px 간격 유지, rim이 서로 반응; 실제 메타볼 합집합은 SDF smooth-min이 필요하며 Web 단일 패스 버전에서는 구현되지 않음 |
| 스프링 | 위치 ω=15, 너비 ω=18.5, ζ=0.66, dt=1/60 → 약 0.45초, 6% 오버슈트 |
5. 매개변수 레시피
| 원하는 효과 | refract | mag | rim | disp | tint | thick |
|---|---|---|---|---|---|---|
| 두꺼운 유리 캡슐 | 1.20 | 0.35 | 0.95 | 0.22 | 0.24 | ✓ |
| 렌즈 아래 색띠 | 1.50 | 0.60 | 1.00 | 0.18 | 0.10 | ✓ |
| 두꺼운 유리 덮개 작은 글자 | 1.25 | 0.42 | 0.80 | 0.30 | 0.16 | ✓ |
| 상단 내비게이션(절제) | 0.90 | 0.20 | 0.60 | 0.15 | 0.10 | ✗ |
| 제어판(가독성) | 1.00 | 0.15 | 0.55 | 0.12 | 0.14 | ✗ |
조정 순서: refract로 변위 설정 → mag로 림 설정 → rim으로 가장자리 설정 → disp/tint로 질감 설정, 순서를 뒤집으면 항상 서로 충돌합니다.
6. 반드시 겪는 8가지 함정
- uniform 배열은 신뢰할 수 없음: ANGLE/D3D에서
uGeo[12]에 값을 할당해도 오류가 발생하지 않지만 적용되지 않음 → 패널당 한 번의 draw call. - 루프 내부의 uniform 분기는 최적화되어 제거됨: 루프 내에서는
mix/step을 사용한 분기 없는 작성 방식 사용. - 선언되었지만 사용되지 않은 uniform이 최적화되어 제거됨:
getUniformLocation이 null을 반환하여 uniform 누락으로 잘못 보고됨. gl.getUniform(prog, null)이 TypeError를 발생시킴: 전체 프레임의 이후 코드가 모두 건너뛰어짐(마치 멈춘 것처럼 보임).- 텍스처 Y축: 뒤집지 않으면 이미지가 미러링되고 글자가 거꾸로 표시됨.
click만 바인딩하면 이벤트가 손실됨:pointerdown + pointerup + 변위 임계값사용.half는 GLSL ES 예약어:vec2 half를 작성하면 전체 컴파일이 실패하고, 로그에는 구문 오류만 표시됨. 유사한 위험 단어:filter/input/output/long/short/packed.- 역순 smoothstep은 정의되지 않은 동작:
smoothstep(1.0,-1.0,d)는 머신에 따라 실패하므로 항상1.0 - smoothstep(작은값, 큰값, x)로 작성.
추가로 동작 레이어 전용 함정:
- 길게 누른 후 손을 떼면 클릭으로 간주하면 안 됨(
longFired플래그로 표시). 그렇지 않으면 길게 누르기 메뉴가 열리자마자 펼치기가 바로 이어짐. - 우클릭은
pointerdown보다 먼저 차단해야 함(e.button !== 0일 때 바로 return). 그렇지 않으면 우클릭이 드래그를 시작함.
7. 검증 (수정할 때마다 실행)
?selftest=1은 13개 항목을 테스트합니다: 클릭으로 펼치기/접기, 길게 눌러 버블, Esc로 버블 닫기, 우클릭으로 다른 메뉴, Dock 분리와 합치기, 융합 목, 방향키 선택, Esc 전체 접기, 더블클릭 들어올리기, 관성, W 광로 필드.
추가로 수동 확인:
- 유리 안의 콘텐츠 방향이 올바름(거꾸로 또는 미러링 없음)
- 가장자리 둘레의 rim, 상단 거울, 하단 밝은 아치가 모두 있음
- 어두운 배경에서 유리 내부가 완전히 검지 않음(안개 낀 회색이 있음)
- 드래그 시 잔상이 지연되고, 손을 놓으면 관성이 있다가 고정됨
- 분리 시 두 조각이 '찢어지는' 것이지 '서로 당기는' 것이 아님
- 스크롤 텍스트가 가장자리에서 점차 사라지고, 끝점에 도달하면 hard로 전환되어 가는 선 표시
- 3가지 접근성 스위치가 모두 작동(투명도 낮춤/대비 강화/동작 줄임)
8. 성능 예산
| 항목 | 예산 |
|---|---|
| 동시 화면 유리 조각 | ≤10개(본 구현 10개, 필요에 따라 나타나는 0 너비 버블/브리지 포함) |
| draw call | 2개 program + 조각당 1회 AABB draw |
| 배경 업로드 | 5프레임마다; 정지 시 8프레임 가능 |
| 밝기 샘플링 | 10프레임마다, w*h>24000인 패널만 샘플링 |
| 렌더링 배율 | <42fps → 0.72, >56fps → 1.0, DPR 상한 2 |
| 성능 저하 체인 | 패널 감소 → 배율 감소 → 업로드 감소 → 색 분산 끄기 → CSS 버전으로 후퇴 |
9. 레드라인 및 플랫폼 경계
- 유리는 내비게이션 레이어에만 적용됨; 콘텐츠 레이어에는 유리를 깔지 않음.
- 유리를 겹쳐서 사용하지 않음(굴절 참조를 잃어 더러운 얼룩처럼 보임); Regular와 Clear를 같은 화면에 혼용하지 않음.
- tint는 주 작업에만 사용; 하이라이트는 절제하며,
rim > 1.2이면 가짜처럼 보임. - Web에서 구현 불가능한 것: 유리 위의 텍스트/아이콘이 자체 굴절되는 것(iOS 26 시스템 합성 파이프라인에 해당); CSS 폴백은 픽셀 단위 렌즈 림과 색 분산을 구현할 수 없음.
- 자체 렌더링 버전에서 미포함: 실제 메타볼 합집합(본 구현은 좁은 목 근사치 사용), 기기 기울기 조명, 실시간 비디오의 프레임별 주 색상 통계.