LiquidGlass

LiquidGlass란?

LiquidGlass는 WebGL 셰이더를 사용해 임의의 HTML 요소 위에 사실적인 유리 효과를 렌더링하는 경량 JavaScript/TypeScript 라이브러리입니다. 각 유리 요소 뒤의 DOM 콘텐츠를 캡처해 실시간으로 합성하며, 굴절, 블러, 크로마틱 어버레이션, 반사 하이라이트 및 관련 조명 효과를 적용합니다.

이 라이브러리는 임의의 페이지 배경(이미지, 비디오, 캔버스 또는 일반 HTML)과 함께 작동하도록 설계되었습니다. 다중 패스 렌더링 파이프라인을 사용하며, 여러 유리 레이어, 요소별 설정, 페이지 동적 업데이트를 처리할 수 있습니다.

주요 기능

• HTML 요소를 위한 WebGL 셰이더 기반 유리 렌더링: 유리 요소 뒤의 DOM 콘텐츠를 처리해 셰이더 출력으로 합성하며 유리 외관을 생성합니다.
• 실시간 다중 패스 파이프라인: 굴절, 블러 강도 제어, 크로마틱 에지 프린징, 반사/림 조명 효과를 지원합니다.
• 요소별 및 전역 설정: data-config (JSON)으로 각 유리 요소를 개별 설정하거나 defaults 옵션으로 전역 기본값을 지정합니다.
• 레이어드 유리 합성: 합성 방식을 통해 유리 위 유리 구성을 지원합니다.
• 인터랙티브 위치 옵션: 활성화 시(floating: true 등) 드래그 가능한 “플로팅” 패널 동작을 주입하며, 호버/프레스 셰이더 피드백을 위한 button 모드를 포함합니다.
• 사실적인 표면 제어: cornerRadius, zRadius (베벨 깊이), bevelMode (모양 곡률 모드), brightness, saturation, shadowOpacity, fresnel 반사 등의 매개변수를 제공합니다.

LiquidGlass 사용법

1. 설치 또는 가져오기: npm으로 설치(npm install @ybouane/liquidglass)하거나 CDN에서 직접 가져오기(https://cdn.jsdelivr.net/npm/@ybouane/liquidglass/dist/index.js).
2. 위치 지정된 루트 컨테이너 생성: LiquidGlass.init()에 전달되는 root 요소는 position: relative를 가진 컨테이너여야 합니다.
3. 루트 내부에 유리 요소 추가: 각 유리 요소는 루트의 직접 자식이어야 합니다. 초기화 시 LiquidGlass가 셰이더 출력을 위해 유리 요소의 첫 번째 자식으로 <canvas>를 주입합니다.
4. 초기화: LiquidGlass.init({ root: document.querySelector('#my-root'), glassElements: document.querySelectorAll('.glass') })로 인스턴스를 생성하고, 나중에 instance.destroy()로 정리합니다.
5. 효과 설정: element.dataset.config = JSON.stringify({ ... })로 요소별 설정(예: 블러 양, 굴절, 코너 반경)을 제공합니다. 플레이그라운드 패턴으로 매개변수를 시각적으로 조정하세요.

사용 사례

• 커스텀 “유리” 카드 및 패널: blurAmount, brightness, cornerRadius, zRadius를 조정해 카드 요소에 프로스티드, 다크 또는 일반 유리 스타일을 적용합니다.
• 인터랙티브 돋보기 스타일 렌즈: bevelMode: 1과 일치하는 cornerRadius, zRadius를 사용해 반구/돔 렌즈 효과를 얻고(선택적으로 floating 활성화), 돋보기 효과를 구현합니다.
• 호버/프레스 UI 피드백: button: true로 설정하면 유리 요소가 사용자 상호작용에 반응—호버 시 밝아지고 프레스 시 베벨이 평평해지며 그림자가 깊어집니다.
• 레이어드 유리 위 유리 구성: LiquidGlass 합성을 활용해 서로 겹치는 다른 유리 요소로 다층 UI를 구축합니다.
• 풍부한 배경 위 유리: 이미지, 비디오, 캔버스 또는 일반 HTML 콘텐츠인 배경 위에 유리 요소를 배치하며, 해당 배경을 루트의 샘플링된 자식 내에 유지합니다.

자주 묻는 질문

특정 DOM 구조가 필요하나요? 네. root는 위치 지정된 컨테이너(position: relative)여야 하며, 각 유리 요소는 루트의 직접 자식 이어야 합니다. 중첩된 유리 요소는 초기화 시 콘솔 경고와 함께 거부됩니다.

LiquidGlass가 유리 효과에 어떤 것을 캡처하나요? 셰이더는 루트의 자식을 샘플링하므로, 배경 이미지는 루트 내부 형제 요소에 있어야 합니다. 루트 자체는 캡처되지 않습니다.

LiquidGlass가 DOM 요소를 생성하나요? 유리 요소의 첫 번째 자식으로 셰이더 출력을 렌더링하는 <canvas>를 주입합니다. 따라서 유리 요소에 :first-child CSS 선택자를 의존하지 마세요.

같은 페이지에 여러 LiquidGlass 루트를 사용할 수 있나요? 제한 사항에 따라 여러 LiquidGlass 루트는 굴절을 공유할 수 없습니다. 또한 한 루트의 유리 요소는 다른 루트의 유리 요소 렌더링을 볼 수 없습니다.

성능 고려사항이 있나요? 네. 라이브러리는 실시간 DOM 래스터화와 다중 패스 WebGL 파이프라인에 의존하며, DOM을 캔버스로 캡처하는 것은 비용이 많이 듭니다.

대안

• CSS 전용 유리 효과 (backdrop-filter / 블러 기반 기법): 더 간단하고 순수 CSS 기반 접근법으로 서리 유리를 근사할 수 있지만, 일반적으로 굴절/크로마틱 어버레이션/반사 파이프라인 동작을 제공하지 않습니다.
• WebGL 셰이더 프레임워크 또는 커스텀 Three.js/WebGL 구현: 완전한 제어가 필요하다면 직접 커스텀 셰이더 패스를 구현할 수 있습니다; 이는 라이브러리 추상화에서 자신의 렌더링 파이프라인으로 작업을 옮기는 것입니다.
• 기타 DOM-to-canvas/실시간 효과 파이프라인: DOM을 텍스처로 래스터화하는 인접 솔루션으로 화면 공간 효과를 만들 수 있지만, 워크플로와 설정은 LiquidGlass의 DOM 기반 유리 요소 설정과 다릅니다.
• 정적 디자인 자산: 상호작용과 실시간 업데이트가 필요 없는 경우, 사전 렌더링된 유리 이미지나 내보낸 컴포넌트로 런타임 비용을 줄일 수 있지만, 동적 굴절/매개변수 변경을 희생합니다.