Liquid Glass Studio

Core Tech Stack

• Framework: React 19 + Vite 6
• Language: TypeScript (Strict mode, ES2020)
• Rendering: WebGL2 (GLSL ES 3.0) / WebGPU (WGSL)
• Animation: @react-spring/web
• Styling: SCSS Modules, clsx
• Package Manager: pnpm

Architecture Patterns

• State Management: Uses stateRef (ref-based state) for data within the render loop to avoid triggering React re-renders every frame.
• Rendering Loop: A single requestAnimationFrame loop managed in src/App.tsx.
• Shaders: All programs share a common vertex shader (fullscreen quad). Shape rendering uses SDF-based (Signed Distance Function) logic with smin (smooth min) for blob/merge effects.

The primary shape's position and deformation are driven by pointer movement using spring-based physics.

Position Following

• The primary shape follows the pointer location on the canvas.
• Movement uses spring-based easing for smoothness.
• The system tracks spring velocity to drive animation morph effects.

Size and Morph Animation

You can deform the shape's size based on pointer movement speed using the animation morph factor:

• Animation Morph Factor: A value between 0 and 50.
• Behavior: When the factor is greater than 0, fast pointer movement causes the shape to stretch in the direction of movement, proportional to the speed and the morph factor.

The WebGPU implementation relies on several internal orchestration objects:

• GPUFrameBuffer: Manages GPUTexture resources, specifically using rgba16float for color and depth24plus for depth, with built-in resize support.
• GPURenderPassObj: Handles the creation of the render pipeline, manages bind groups for uniforms and textures/samplers, and manages the fullscreen quad vertex buffer.
• GPUMultiPassRenderer: The primary implementation of IMultiPassRenderer. It orchestrates multiple rendering passes, manages global and per-pass uniforms, and resolves dependencies between textures used in different passes.

To maintain sharpness on high-density displays (like Retina screens), the system uses Device Pixel Ratio (DPR) aware rendering.

• The canvas backing store is scaled by the DPR.
• All SDF and shape computations account for a DPR uniform to ensure geometry remains accurate at higher resolutions.

The glass effect is rendered using a four-pass pipeline to achieve high-quality visual results. This pipeline is implemented by both the WebGL2 (MultiPassRenderer) and WebGPU (GPUMultiPassRenderer) backends, which both adhere to the IMultiPassRenderer interface.

The four passes are:

1. Background pass: Renders the initial background.
2. Vertical blur pass: Applies vertical blurring.
3. Horizontal blur pass: Applies horizontal blurring.
4. Main composite pass: Combines all previous passes into the final visual output.

During each animation frame, the active renderer executes these passes in order, passing global and per-pass uniforms. Intermediate pass outputs are connected as texture inputs to subsequent passes.

Liquid Glass Studio uses a multi-pass rendering pipeline to achieve high-performance glass effects. The process follows these specific stages:

1. bgPass: Renders the background (using procedural patterns, textures, or video) and applies shadows.
2. vBlurPass: Performs a vertical Gaussian blur on the output of the bgPass.
3. hBlurPass: Performs a horizontal Gaussian blur on the output of the vBlurPass (this two-pass approach is a separable Gaussian blur used for performance).
4. mainPass: The final composite stage. It applies the glass effect—including refraction, dispersion, Fresnel, and glare—on top of the blurred and unblurred background layers.

Debugging Tip: You can use the STEP uniform (values 0-9) to visualize these intermediate rendering stages during development.

The background system supports four primary categories of backgrounds, which are rendered behind the glass effect:

1. Procedural Backgrounds: Built-in patterns including checkerboard grid, directional bars, and half-tone split.
2. Image Backgrounds: Bundled images (e.g., Tahoe light, buildings, text, Tim Cook, UI mockup) loaded as WebGL textures with cover-fit UV mapping.
3. Video Backgrounds: Bundled looping videos (e.g., fish, traffic, flower) that update the GPU texture every frame. Videos play muted and inline.
4. Custom Media: Users can upload custom images or videos via a file picker to be used as textures.

The project uses Leva as the primary UI for parameter control.

• Direct Uniform Mapping: Shader uniforms are driven directly by Leva control values every frame within the rendering loop.
• Custom Components: In addition to standard Leva controls, the project utilizes custom components for specialized inputs:
  • LevaContainer
  • LevaCheckButtons
  • LevaVectorNew
  • LevaButton

All parameter definitions are centralized in src/Controls.tsx.

The system supports three languages: English (en-US), Simplified Chinese (zh-CN), and Uzbek (uz-UZ).

Automatic Detection

On application load, the UI language is determined by the browser language:

• zh* $\rightarrow$ Simplified Chinese
• uz* $\rightarrow$ Uzbek
• All others $\rightarrow$ English

Manual Switching

Users can manually select a different language, which triggers an immediate update of all control labels and UI strings.