Communitygithub.com

Liquid Glass 实现

Apple WWDC25 Liquid Glass(液态玻璃)材质、控件与全交互的完整实现。支持玻璃拟态 UI、透镜折射、Snell 位移、Fresnel 边缘、RGB 色散等视觉效果,以及点击、拖拽、按压反馈等交互。

Liquid Glass 实现란 무엇인가요?

이 스킬은 Apple WWDC25에서 소개된 Liquid Glass(액체 유리) 재질을 WebGL, CSS, C++/Qt6, SwiftUI 등 다양한 플랫폼에서 재현하기 위한 종합적인 구현 가이드입니다. Snell 굴절, Fresnel 가장자리 효과, RGB 색 분산, 두께 구배, 렌즈 립, 내부 발광 등 핵심 광학 효과를 단계별로 설명하며, 특히 WebGL을 우선 플랫폼으로 삼아 실제 픽셀 단위 굴절을 구현합니다. 'starter/glass-starter.html'이라는 최소 실행 가능한 스켈레톤(90줄 셰이더, 1 program, 1 draw)을 제공하여 10분 안에 바로 사용 가능한 유리를 만들 수 있도록 설계되었습니다. 또한 다중 패널 독립 draw call 아키텍처, 실시간 광로 분석(와이어프레임 진단 + 단면 광로도), 8가지 함정, 디자인 레드라인, 성능 예산 및 단계적 성능 저하 전략까지 포함하여 생산 환경에서도 신뢰할 수 있는 구현을 보장합니다.

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

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

Liquid Glass 구현

0. 최단 경로 (따라 하면 10분 안에 쓸 수 있는 유리 완성)

0부터 셰이더를 작성하지 마세요. 400줄 GLSL을 처음부터 작성하여 성공할 확률은 극히 낮습니다. "만들었는데 안 예쁘다"는 대부분 이 단계에서 잘못된 것입니다.

  1. starter/glass-starter.html을 배포 디렉터리로 복사합니다.
  2. 파일 상단 CONFIG의 다섯 개 숫자(refract / mag / rim / disp / tint)만 변경하고, 새로고침하면 변화를 바로 확인할 수 있습니다.
  3. drawBG()가 그리는 내용을 사용자가 원하는 하단 콘텐츠로 교체합니다. 이 단계가 가장 중요합니다: 유리 효과의 90%는 그 아래에 무엇이 있느냐에 달려 있습니다.
  4. PANEL의 너비, 높이 및 둥근 모서리를 수정하여 유리 형태를 결정합니다 (r = h/2이면 완전한 캡슐).
  5. 더 많은 유리가 필요하면 사각형을 복제하고 반복문에서 uRect별로 한 번씩 그립니다 (아키텍처는 섹션 3 참조).

starter는 약 90줄의 셰이더, 1개의 program, 1회 draw로 구성되어 있으며, 이미 Snell 굴절, 두께 가중 측면 변위, Fresnel 림, 가장자리 유백색, 상단 광택 띠, 하단 밝은 아크, RGB 색 분산, 렌즈 컬, 눌림 피드백을 포함하고 있습니다. Chrome(소프트웨어 렌더링 SwiftShader 포함)에서 실제 실행 및 스크린샷으로 검증되었습니다.

바로 효과를 보고 싶다면: 브라우저에서 starter/glass-starter.html을 열고 유리 위에서 마우스를 드래그하면 파란색 막대가 확대되어 이동하는 것을 확인할 수 있습니다.

0.5 세 가지 엄격한 규칙

  1. 반드시 열어서 확인한 후 인도하세요. 코드만 작성하고 열어보지 않고 인도하는 것은 이 스킬의 가장 큰 실패 원인입니다. GUI가 없으면 headless 스크린샷을 사용하세요:

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

    그리고 실제로 그 이미지를 읽어 유리가 나타났는지 확인하세요. 스크린샷 증거가 없으면 완료라고 주장하지 마세요.

  2. 셰이더 오류는 페이지에 표시되어야 합니다. console.error는 스크린샷에서 볼 수 없으며, 이유도 모른 채 검은 화면만 보게 됩니다. compileShader 직후에 바로:

    if (!gl.getShaderParameter(s, gl.COMPILE_STATUS))
      appendPre("shader 컴파일 실패:\n" + gl.getShaderInfoLog(s));   // appendPre = body에 빨간색 <pre> 추가
    
  3. 적게 만들고 늘리세요. 먼저 한 장의 유리를 올바르게 만든 다음 두 번째 유리를 추가하세요. 굴절 + 상호작용 + 다중 패널 + 애니메이션을 한 번에 적용하면 오류가 발생했을 때 위치를 파악할 수 없습니다.

0.6 만들었는데 안 예쁘다? 증상별 진단

증상가장 가능성 있는 원인해결 방법
화면 전체가 검은색, 배경만 보임패널이 전혀 그려지지 않음uRect가 전달되었는지, uRad가 0인지, draw가 4개의 정점 TRIANGLE_STRIP인지 확인
유리 안이 거울/텍스트가 거꾸로텍스처 Y축 방향이 반대UNPACK_FLIP_Y를 켰으면 1.0 - uv.y로 샘플링, 켜지 않았으면 uv.y를 직접 사용
굴절이 보이지 않고 흐릿해짐변위량이 너무 작음off = lat * tpx * refract, tpx가 수십 px인지 먼저 확인; refract를 임시로 3으로 설정하여 변화 확인
가장자리에 무지개색 경직된 띠색 분산이 가장자리 전체에 퍼짐색 분산에 eW*eW 제곱 감쇠를 적용, 최외곽에서만 채널 분리
유리가 회색 플라스틱 같음아래 콘텐츠가 너무 단조로움아래에 고대비 콘텐츠(텍스트, 컬러 바, 그리드)가 반드시 있어야 함, 그렇지 않으면 어떤 매개변수를 조정해도 안개처럼 보임
상단 광택이 마우스를 따라다니는 손전등 같음광택 띠가 가로로 좁아짐전체 가장자리의 기본 밝기를 유지하고, 포인터는 국소 증강만 수행 (0.7 기본 + 0.3 게인)
애니메이션이 푹신푹신하고 힘이 없음1차 지수 완화 사용2차 스프링으로 교체, 감쇠 0.60.7, 58% 오버슈트 허용 (6.5절 참조)
프레임 속도가 30 미만으로 떨어짐패널이 너무 많음 / 매 프레임 전체 화면 draw각 유리는 자체 AABB만 래스터화; 동일 화면 ≤ 10개; 배경 업로드 주기 낮춤

플래그십 버전(다중 패널, 전체 상호작용, 광로 분석)이 필요하면 더 읽으세요; 유리 한 장만 필요하다면 starter로 충분하며, 4절까지 읽으면 됩니다.

1. 플랫폼 결정

대상사용할 자산설명
유리 한 장 / 빠르게 구현starter/glass-starter.html90줄 셰이더, 1회 draw, 실행 검증 완료. 이 파일을 수정하고, 처음부터 작성하지 마세요
웹 / 데모 / 대화형 프로토타입 (우선)liquid-glass-studio.html단일 WebGL 캔버스 + 9개의 유리 + 전체 상호작용 + 실시간 광로 분석. 실제 Snell 굴절, 색 분산, 두께 구배
유리 한 장만 필요, 복잡하지 않음liquid-glass-webgl.html단일 패널 단일 패스 경량 버전, 변위 근사, 상호작용 레이어 없음
WebGL 사용 불가 / 성능 저하 필요liquid-glass-css.htmlbackdrop-filter + SVG 변위, 동작은 유사하지만 픽셀별 굴절 없음
데스크톱 C++ / 자체 렌더러cpp/glass_math.h + cpp/qt6/순수 수학 라이브러리 + Qt6 컨트롤; 프로덕션 환경에서는 공식을 GLSL로 이전
iOS / macOS 네이티브swift/LiquidGlassDemo.swift공식 .glassEffect API; 하위 버전에서는 SimulatedGlass로 폴백

WebGL 우선 이유: 굴절은 픽셀 단위로 하단을 샘플링해야 하며, CSS는 전체 블록 변위만 가능하고 가장자리의 "렌즈 립" 효과를 전혀 만들 수 없습니다.

2. 자산 및 문서

liquid-glass/
├── starter/
│   └── glass-starter.html        # 최소 실행 가능 스켈레톤: 90줄 셰이더, 1 program 1 draw, 실행 검증 완료
├── liquid-glass-studio.html      # 플래그십: 전체 상호작용 + 실시간 광로 (이 스킬의 주요 인도물)
├── liquid-glass-webgl.html       # 경량 단일 패널 버전
├── liquid-glass-css.html         # CSS/SVG 폴백
├── cpp/
│   ├── glass_math.h              # SDF, squircle, Snell/Fresnel, BK7 색 분산, 두께/립/아크 림 순수 함수
│   └── qt6/                      # CMake 프로젝트
├── swift/LiquidGlassDemo.swift   # 공식 API + 시뮬레이션 폴백
└── references/
    ├── feature-matrix.md         # 22개 Session 219 특성 매트릭스, 각 플랫폼 커버리지, 디자인 레드라인
    ├── optics-model.md           # 광로 물리 모델 및 매개변수 범위 (셰이더 작성 전 필독)
    ├── interaction-playbook.md   # 클릭/확장/분리/드래그 상태 머신 및 검수 목록
    └── swiftui-api.md            # SwiftUI 유리 API 시그니처 및 주의사항

3. 렌더링 아키텍처 (studio 버전)

2개의 program, 9회 draw call, 여러 유리를 단일 풀스크린 패스의 uniform 배열에 절대 넣지 않습니다.

Pass 1  pBg   : 풀스크린 quad, 배경 텍스처 직접 샘플링
Pass 2  pGl   : 동일한 quad VBO, 각 유리를 자체 AABB로 평행 이동/크기 조정, 한 번의 drawArrays

버텍스 셰이더에서 [-1,1] quad를 패널로 매핑:

uniform vec2 uC, uH, uRes;          // 중심, 반 너비/높이, 캔버스 크기 (모두 장치 픽셀)
void main(){
  vec2 cN = (uC/uRes)*2.0 - 1.0;  cN.y = -cN.y;      // 화면 왼쪽 상단 원점 → NDC
  vec2 hN = ((uH + vec2(6.0))/uRes)*2.0;             // 6px 외부 확장 (안티앨리어싱)
  gl_Position = vec4(cN + vec2(aPos.x, -aPos.y)*hN, 0.0, 1.0);
}

픽셀 셰이더는 gl_FragCoord를 사용하여 화면 좌표를 역산합니다 (varying 아님, varying은 평행 이동된 quad 내에서 로컬 좌표입니다):

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;                 // AABB 내에서 윤곽선 밖의 픽셀은 바로 버림
gl_FragColor = vec4(gcol, 1.0 - aa);    // 가장자리는 알파로 전환

외부에서 gl.enable(BLEND) + blendFunc(SRC_ALPHA, ONE_MINUS_SRC_ALPHA)를 켜고, 그린 후 끕니다.

이렇게 하면 각 유리는 자신의 사각형만 래스터화하므로, 8개의 유리 채우기율은 약 하나의 풀스크린과 같습니다 — "풀스크린 × 8회 루프"보다 한 차원 빠릅니다.

각 유리 한 번의 draw에 설정해야 하는 스칼라 uniform (순서 고정, 하나라도 빠지면 안 됨):

uniform의미출처
uC uH화면 중심 / 반 너비/높이 (장치 픽셀, 왼쪽 상단 원점)(g.x+g.w/2)*dpr 등
uRad둥근 모서리 반경 (장치 픽셀)min(g.radius, min(w,h)/2)*dpr
uVariant uThick uMagMul변형 / 두꺼운 재질 / 패널 수준 배율패널 속성
uHover uPress uGlow uActive상호작용 상태 0~1매 프레임 스프링 값
uPtr패널 내 포인터 정규화 좌표 -1~1(cx-c)/(w/2)
uAmb하단 환경색 rgbgetImageData 샘플링
전역uRes uTex uRefraction uRim uTint uDisp uN uMode uContrast uOpaque uMag uWire매 프레임 한 번 설정

4. 광로 모델 (셰이더 작성 시 반드시 읽어야 할 섹션)

일곱 단계, 순서 변경 불가:

  1. 윤곽선: sdRoundBox로 부호 있는 거리 d를 계산 (내부는 음수). 정규화된 깊이 x = clamp(-d/band, 0, 1), 0 = 윤곽선, 1 = 중심; band = max(5, min(hx,hy)*0.30).
  2. 볼록 높이 필드: H(x) = sqrt(1 - (1-x)²), H'(x) = v/sqrt(1-v²) (v = clamp(1-x, 0.02, 0.9995)). sqrt를 사용하고 pow를 사용하지 마세요 — pow는 ANGLE에서 훨씬 느립니다.
  3. 입사각: sinI = min(H'/sqrt(1+H'²), 0.62), thI = asin(sinI), thT = asin(sinI/n), n = 1.5168 (BK7). 상한 0.62는 하드 제약입니다: 0.93으로 설정하면 가장자리 변위가 200px 수준이 되어 전체 패널이 검은 블록으로 밀려납니다.
  4. 두께: tpx = mdim*(0.05 + 0.28*H)*(1 + 0.40*thick)*vg, vg = 1 + 0.24*(1 - smoothstep(-0.85, 0.35, q.y)) (아래는 두껍고 위는 얇음). tpx는 "픽셀 두께"이며, 정상 범위는 0.1 ~ 0.4 * mdim입니다. 0.5를 초과하면 반드시 왜곡됩니다.
  5. 변위: lat = tan(thI-thT), off = -dir*lat*tpx*uRefraction*Tf, 가장자리에 한 항목 추가 -dir*(1-smoothstep(0,0.28,x))*tpx*0.22. 마지막으로 off = clamp(off, -10, 10) — 제한은 "가장자리가 먼 콘텐츠를 강제로 끌어들이는" 유일한 안전 장치입니다.
  6. 초점/렌즈 립: focal = uMag * uMagMul * (0.50*cW - 0.40*eW), cW = smoothstep(0.10,0.90,x); eW = 1-smoothstep(0,0.62,x). 중심 focal > 0 → 샘플링 점이 중심으로 수축 → 확대; 가장자리 focal < 0 → 샘플링 점이 바깥쪽으로 확장 → 콘텐츠가 바깥쪽으로 굴절, 이것이 Apple의 립입니다. 1-focal은 항상 양수여야 합니다, 그렇지 않으면 국부적으로 180° 뒤집혀 거꾸로 된 텍스트가 나타납니다. uMagMul은 패널 수준 배율입니다 (6절 참조): 작은 유리는 곡률이 커서 많이 확대되고, 큰 유리판은 평판에 가까워 확대가 적습니다. 이 계수가 없으면 동일한 uMag를 사용할 때 214×300 텍스트판이 알아볼 수 없을 정도로 확대되고, 158×126 렌즈는 충분히 확대되지 않습니다. 패널 크기와 magMul의 대응: lens 1.30, plate 0.55, capsule 0.85, panel 0.60, dock 0.80, nav 0.90.
  7. 샘플링 및 합성: sp = c + rel*(1-focal) - off; 세 채널을 ±uDisp*7*eW로 분리 샘플링하여 색 분산 효과; 그다음 순서대로 variant 감광, uAmb 환경 오버플로우 색상 0.10, tint 밝기 압축 0.58*L + 0.133, 암장 보광 +vec3(0.048,0.051,0.058), Fresnel 림 + 유백색 + 상단 스펙큘러 + 하단 밝은 아크 ((1+0.75*press)), 내부 발광.

텍스처 좌표 Y축 반전 필수

배경 캔버스를 업로드할 때 UNPACK_FLIP_Y_WEBGL = true를 켰으므로, 텍스처 v=0은 화면 하단에 해당합니다; 반면 px는 왼쪽 상단 원점입니다. 따라서:

vec2 uv0 = vec2(sp.x/uRes.x, 1.0 - sp.y/uRes.y);   // 이 한 줄이 없으면 유리 전체가 반전된 이미지

이것은 선택 사항이 아닙니다. 증상은: 유리 안에 상하가 뒤집힌 텍스트가 나타나고, 콘텐츠가 화면 반대쪽에서 가져와집니다.

5. 실시간 광로 분석

두 가지 세트를 제공하며, 서로 대체되지 않습니다:

A. 진단 필드 (params.wire = 1) — 셰이더의 중간 값을 직접 그려서 "굴절이 실제로 일어나고 있는지" 판단합니다:

채널의미해석
Rlength(off)/mdim*22빨간색 = 굴절 강도. 중심은 검은색에 가깝고, 가장자리는 빨간색 원
Gx (가장자리 깊이)녹색 원이 윤곽선을 따라가며, 안쪽으로 빠르게 0으로 수렴
Bfocal*2파란색 = 배율, 중심은 밝고 가장자리는 어두움

세 가지가 동시에 나타나고 영역이 뚜렷하면 광로가 성립한 것입니다; 전체가 검은색은 일반적으로 uniform이 전달되지 않은 경우입니다 (7절 함정 1 참조).

B. 단면 광로도 (오른쪽 아래 308×150 캔버스) — 11개의 광선이 볼록 유리를 통과하는 입사/내부/출사를 그리고, 가장자리 광선의 θi / θt / Δx와 두께 단위(thin/thick)를 표시합니다. 초점 패널은 포인터 호버에 따라 전환됩니다.

두 곡선(셰이더와 2D 그림)은 동일한 공식 세트와 동일한 sinI 상한을 사용해야 합니다. 그렇지 않으면 그림에는 68°라고 쓰여 있지만 화면은 38°로 계산되어 매개변수 조정 시 오해를 불러일으킵니다.

6. 매개변수 레시피 (참조 이미지와 대조)

원하는 효과refractmagrimdisptintthick
두꺼운 유리 캡슐 (크고, 가장자리 밝고, 하단 아크 뚜렷, 내부는 어둡게 투과)1.200.350.950.220.24✓
컬러 바 위의 렌즈 (막대가 확대되어 변위, 좌우에 밝은 점)1.500.601.000.180.10✓
작은 글자 위의 두꺼운 유리 (글자가 확대되고 가장자리 왜곡)1.250.420.800.300.16✓
상단 내비게이션 바 (얇고, 절제됨)0.900.200.600.150.10✗
컨트롤 패널 (크고, 글자를 읽을 수 있어야 함)1.000.150.550.120.14✗
0번 기본값1.200.450.850.350.20—

조정 순서: 먼저 refract로 변위 크기 결정 → 그다음 mag로 립 강도 결정 → 그다음 rim으로 가장자리 밝기 결정 → 마지막으로 disp/tint로 질감 결정. 반대로 조정하면 항상 서로 상충됩니다.

세 가지 레시피 원클릭 전환 (studio 버전에 내장)

컨트롤 패널 상단에는 '두꺼운 캡슐 / 렌즈 / 텍스트 / 기본값' 네 개의 버튼이 있으며, 한 번 클릭하면 두 가지 작업이 동시에 수행됩니다: 다섯 개의 슬라이더를 위 표의 값으로 설정하고, 해당 패널에 한 번의 flash 내부 발광을 제공합니다(눈에 "이 부분을 보세요"라고 알려줌).

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

프로그램에서 params를 변경해도 슬라이더의 input 이벤트가 트리거되지 않으므로, 슬라이더 위치와 값 레이블을 다시 쓰기 위해 수동으로 syncUI()를 호출해야 합니다. 그렇지 않으면 슬라이더와 실제 매개변수가 분리됩니다.

flash 감쇠는 step()에 작성되며, glow에 병합되어야 하고 덮어쓰면 안 됩니다 (그렇지 않으면 누르고 있을 때의 발광이 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 가장 놓치기 쉬운 네 가지 Apple 디테일

이 세 항목은 Session 219에 등장하지만 데모를 볼 때 매우 간과하기 쉽습니다. 이것들이 없으면 "유리 같다"는 느낌이 순간적으로 떨어집니다.

① 상단 광택이 포인터를 따라감 (specular는 이동하지만, 포인터를 따라다니면 안 됨)

고정된 상단 가장자리 밝은 선은 "스티커"입니다. 그러나 광택을 "포인터를 중심으로 양쪽으로 감쇠"로 만들면 유리 위를 스캔하는 손전등이 됩니다 — 이것이 가장 자주 잘못 구현되는 부분입니다. 올바른 방법은: 전체 상단 가장자리는 항상 밝고, 포인터는 국소 증강만 수행입니다.

float tx       = q.x - uPtr.x*0.30;                    // 포인터 오프셋은 작아야 함 (0.3, 0.55 아님)
float baseTop  = 1.0 - smoothstep(-0.92, -0.30, q.y);  // 전체 가장자리의 기본 밝기
float boostTop = 1.0 - smoothstep(0.12, 1.00, abs(tx)); // 포인터 위치의 추가 게인
float topW     = baseTop * (0.70 + 0.30*boostTop);      // 최소 0.70, 최대 1.0

잘못된 작성법과 그 결과를 비교해 보세요:

작성법표현
smoothstep(-0.30,-0.92,q.y) * (1-smoothstep(0.06,0.72,abs(tx)))포인터가 움직이면 밝은 부분이 작은 조각만 남고 나머지는 모두 검게 → 손전등
baseTop * (0.70 + 0.30*boostTop)가장자리가 항상 하나의 선으로 연결되고, 포인터 위치만 약간 밝아짐 → 실제 거울

또한 역순 smoothstep을 작성하지 마세요: smoothstep(1.0, -1.0, d) 및 smoothstep(-0.30, -0.92, x)의 edge0 > edge1은 GLSL 사양에서 정의되지 않은 동작이며, 일부 구현에서는 오작동합니다. 항상 1.0 - smoothstep(작은값, 큰값, x)를 사용하세요.

포인터 방향의 스펙큘러 (dot(dir, pdir)로 계산된 spec)는 눌렀을 때만 강도를 주고, 호버 시에는 전혀 추가하지 마세요; 그렇지 않으면 마우스를 슬라이딩할 때 작은 밝은 점이 가장자리를 따라 움직입니다.

② 내부 발광이 인접한 유리로 퍼짐 (약 12%) A를 눌렀을 때 옆에 있는 B도 약간 빛나며, "빛이 유리 사이를 흐른다"는 느낌을 줍니다.

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

계수가 0.15를 넘지 않도록 하세요. 그렇지 않으면 전체 화면이 함께 빛나서 "고광택 절제"라는 레드라인이 무너집니다.

③ 스크롤 가장자리 점진적 페이드 (Scroll edge effect) 유리 뒤의 콘텐츠가 가장자리까지 스크롤되면 배경에 "녹아들어야" 하며, 단단한 선으로 잘리면 안 됩니다. 알파 마스크를 사용하고, 콘텐츠가 있을 때만 마스크합니다:

var st   = el.scrollTop;
var rest = el.scrollHeight - el.clientHeight - st;
var top  = st > 3 ? 28 : 0;              // 맨 위로 스크롤되면 마스크하지 않음, 그렇지 않으면 항상 가짜 그림자가 있음
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%)";

핵심: mask는 알파 채널을 읽으므로, rgba(0,0,0,0)를 사용하고 transparent를 사용하지 마세요 (일부 오래된 구현에서 transparent는 투명 검정으로, 동작은 같지만 의미가 더 명확함). 스크롤 컨테이너 자체는 pointer-events:auto여야 합니다. 그렇지 않으면 스크롤되지 않습니다. 단, 이로 인해 전체 유리가 더 이상 드래그를 수신하지 않게 되므로, 드래그가 필요한 유리는 스크롤 컨테이너를 완전히 채우지 마세요.

④ 분리 / 병합: "슬라이딩"이 아닌 "튕김"이어야 함

1차 지수 완화 x += (tx - x)*0.19는 결코 오버슈트하지 않으며, 수렴이 항상 푹신하게 멈춥니다. 2차 스프링으로 교체:

// 매 프레임 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; }   // 너무 좁아지면 너비가 음수가 되어 바로 그려짐

omX = 15, omW = 18.5, z = 0.66 → 약 6% 오버슈트, ~0.45초 주기. 너비 강성은 변위보다 커야 함 (18.5 > 15), 그래야 "먼저 변형되고, 그다음 제자리로"가 됩니다; 둘이 같으면 전체가 평행 이동하여 다시 나무 판자 느낌이 됩니다.

분리가 "두 개의 판이 밀려나는 것처럼" 보이게 하는 두 가지 핵심:

  • 오른쪽 조각 위치 고정 (tx는 항상 lay.x + lay.w - 한 조각 너비), 너비만 0 ↔ 140 사이에서 변경 → 시각적으로 "중앙에서 갈라짐"이지 "하나는 줄고 하나는 늘어나며 수평으로 당겨짐"이 아님
  • 갈라짐 / 합쳐지는 순간에 각 조각에 한 번씩 flash = 1 내부 발광 악센트를 주어야 동작이 확실해짐

1차 완화 계수를 아무리 크게 조정해도 "튕김"은 만들 수 없습니다. 그것은 속도의 문제가 아니라 곡선 모양의 문제입니다.

7. 반드시 밟는 여덟 가지 함정 (본 기기에서 실제 테스트 완료)

  1. 배열 uniform은 신뢰할 수 없음. uniform vec4 uGeo[12]에서 ANGLE/D3D의 getUniformLocation("uGeo[0]")은 null이 아닌 값을 반환하고, uniform4fv는 오류를 보고하지 않지만 데이터가 셰이더에 들어가지 않습니다 — 모든 패널이 0을 읽고, if(hh.x < 1.5) continue에 의해 모두 건너뛰어 페이지에 어두운 배경만 남습니다. 결론: 다중 패널 지오메트리를 전달하는 데 uniform 배열을 절대 사용하지 말고, 패널당 한 번의 draw call로 대체하세요.
  2. 루프 + uniform 분기는 전체가 최적화될 수 있음. for 루프 안에 if(uOpaque > 0.5){...}를 작성하면 일부 드라이버에서 루프 본문이 버려집니다. 루프 내에서는 항상 mix/step을 사용한 분기 없는 작성법을 사용하세요. "패널당 한 번 draw"라면 루프조차 필요하지 않습니다.
  3. 선언되었지만 사용되지 않은 uniform은 최적화되어 제거되며, getUniformLocation이 null을 반환하여 "uniform 부족"을 잘못 보고합니다. 선언과 사용은 항상 쌍으로 나타나야 합니다.
  4. gl.getUniform(prog, null)은 TypeError를 발생시키며, 동일한 프레임의 이후 코드(FPS, 프로브 모두 업데이트되지 않음)를 모두 건너뛰게 하여 "페이지가 멈춘 것"처럼 보입니다. location을 가져온 후에는 먼저 null인지 확인하세요.
  5. 텍스처 Y축 (4절 참조): 뒤집지 않으면 반전된 이미지 + 거꾸로 된 텍스트가 나타납니다.
  6. click만 바인딩하면 이벤트가 손실됨. 자동화 환경, 일부 호스트에서 click이 합성되지 않아 상호작용이 모두 무시됩니다. pointerdown + pointerup + 변위 임계값을 사용하여 클릭을 판단하고, click은 보충으로만 사용하세요.
  7. half는 GLSL ES 예약어입니다: vec2 half = uRect.zw*0.5;로 작성하면 전체 셰이더가 컴파일 실패하고, 로그에는 syntax error만 표시되어 위치를 찾기 매우 어렵습니다. 반 너비/높이는 hb를 사용하세요. 유사한 함정으로 filter, input, output, long, short, double, packed 등이 있습니다.
  8. 역순 smoothstep은 정의되지 않은 동작입니다: smoothstep(1.0, -1.0, d), smoothstep(-0.30, -0.92, y)와 같이 edge0 > edge1인 작성법은 테스트한 브라우저에서는 정상일 수 있지만, 다른 브라우저에서는 쓰레기 값이 됩니다. 항상 1.0 - smoothstep(-1.0, 1.0, d)로 다시 작성하세요.

8. 검수 목록 (매번 수정 후 실행)

렌더링

  • 8개의 유리가 모두 보이고 위치가 레이아웃 테이블과 일치함
  • 유리 안에 하단 콘텐츠(텍스트/파란 막대/그리드)가 보이고, 단색 블록이 아님
  • 유리 안의 콘텐츠 방향이 올바름 (거꾸로 또는 좌우 반전되지 않음)
  • 가장자리에 밝은 림이 있고, 상단에 스펙큘러 하이라이트, 하단에 밝은 아크가 있음
  • 어두운 배경의 유리 내부가 완전히 검지 않음 (약간의 안개 낀 회색)
  • 윤곽선 가장자리 안티앨리어싱이 깨끗하고, 단단한 가장자리나 흰색 테두리가 없음

상호작용 (자세한 버전은 references/interaction-playbook.md 참조)

  • 캡슐 클릭 → 메뉴가 위로 자라나고, 하단 가장자리는 고정; 다시 클릭하면 접힘
  • 캡슐 드래그 → 따라가고, 손을 놓으면 되튐; 가장자리에서 clamp됨
  • Dock 분리 키 클릭 → 두 조각이 벌어짐; 다시 클릭하면 합쳐짐
  • 패널 누르고 있음 → 약간 수축 + 내부 발광; 손을 놓으면 0으로 돌아감
  • 호버 → 하이라이트가 포인터 방향으로 이동
  • 스페이스바 / S / W 키보드 단축키 동작 확인
  • '두꺼운 캡슐 / 렌즈 / 텍스트 / 기본값' 네 개의 키 클릭: 다섯 개의 슬라이더 위치와 값이 동기화되어 변경되고, 대상 패널이 내부 발광으로 깜빡임
  • resize 후 확장 및 분리 상태 유지

성능

  • FPS 안정적, 주기적인 프레임 드롭 없음
  • 패널 수 변경 후 draw call 수 재평가

9. 성능 예산 및 단계적 성능 저하

항목예산초과 시 대처
동일 화면 유리 패널≤ 10개하나로 병합하거나, 보조 패널을 CSS 폴백으로 낮춤
각 draw 커버 영역자체 AABB만 커버풀스크린에서 유리 패스 실행 금지
배경 텍스처 업로드5프레임당 한 번 (광점은 느림)정지 시 8프레임당으로 감소
배경 픽셀 비율min(dpr, 1.5)프레임 드롭 시 1.0으로 감소
렌더링 배율적응형 0.72 / 1.0< 42fps에서 하향, > 56fps에서 상향
하단 밝기 샘플링 getImageData10프레임당, w*h > 24000인 패널만가장 큰 동기화 오버헤드이므로, 적게 샘플링하는 것이 나음
광로 단면도4프레임당정지 시 6프레임당으로 감소 가능
컨트롤 패널 높이min(520, VH*0.62, VH-250)오른쪽 아래 광로도에 240px을 남겨야 함, 그렇지 않으면 작은 창에서 겹침

성능 저하 순서: 패널 수 감소 → 렌더링 배율 감소 → 배경 업로드 빈도 감소 → 색 분산 끄기 → 전체 페이지 CSS 버전으로 전환.

10. 디자인 레드라인 (Apple HIG)

  • 유리는 내비게이션 레이어에만 사용: 콘텐츠 레이어는 유리로 덮지 마세요.
  • 유리를 겹치지 마세요: 두 개의 유리가 겹치면 굴절 참조를 잃어 더러운 반점처럼 보입니다.
  • 변형을 혼용하지 마세요: 한 화면에서 Regular와 Clear를 혼용하지 마세요.
  • 틴트는 주요 작업에만, 면적이 작아야 함; 전체를 염색하면 유리가 아닙니다.
  • 고광택 절제: rim은 "한 바퀴"이지 "하나의 흰색 테두리"가 아닙니다. uRim > 1.2는 가짜처럼 보입니다.
  • 세 가지 접근성 스위치를 반드시 유지: 투명도 감소, 대비 향상, 동작 감소. 전자는 배경 콘텐츠를 불투명한 바탕으로 바꾸고, 후자는 스프링 k를 1로 설정합니다.
  • 유리 위에 텍스트가 있을 때 DOM 콘텐츠에는 text-shadow가 있어야 합니다. 그렇지 않으면 밝은 유리 위에서 흰색 텍스트를 읽을 수 없습니다.

11. C++ / SwiftUI로 마이그레이션

  • C++: cpp/glass_math.h에는 동일한 H(x), H'(x), fres(), 두께 구배, 립, 아크 rim의 순수 함수가 있으며, 픽셀 셰이더로 직접 이전하면 됩니다; Qt6 예제는 인터페이스 형태만 보여주며, 프로덕션 환경에서는 CPU로 픽셀 단위 처리를 하지 마세요.
  • SwiftUI: 우선 .glassEffect(.regular, in: shape)를 사용하여 시스템 구현을 사용하세요; 사용자 정의 모양이나 사용자 정의 굴절이 필요한 경우에만 직접 SimulatedGlass를 그리고, 주석에 시스템 효과와의 차이점을 명시하세요 (시스템 버전은 프로세스 간 배경 샘플링과 실제 동적 하이라이트가 있습니다).

관련 스킬