WebGPU Requirements

Hyperscape requires WebGPU for rendering. This document explains why, what’s required, and how to verify support.

Why WebGPU is Required

TSL Shaders

All materials in Hyperscape use TSL (Three Shading Language), which is Three.js’s node-based shader system. TSL only works with the WebGPU rendering backend. Examples of TSL usage:

Terrain shaders (height-based blending, triplanar mapping)
Water shaders (reflections, refractions, foam)
Vegetation shaders (wind animation, LOD transitions)
Post-processing (bloom, tone mapping, color grading)
Impostor materials (octahedral impostors for distant objects)

No WebGL Fallback

BREAKING CHANGE (Commit 47782ed): All WebGL fallback code was removed. Removed:

RendererFactory.ts - WebGL detection and fallback logic
isWebGLForced, isWebGLFallbackForced, isWebGLFallbackAllowed flags
isWebGLAvailable, isOffscreenCanvasAvailable, canTransferCanvas checks
UniversalRenderer type (now only WebGPURenderer)
forceWebGL and disableWebGPU URL parameters
STREAM_CAPTURE_DISABLE_WEBGPU environment variable
DUEL_FORCE_WEBGL_FALLBACK configuration option

Why removed:

TSL shaders don’t compile to WebGL
Maintaining two rendering paths was causing bugs
WebGPU is now widely supported (Chrome 113+, Edge 113+, Safari 18+)
Simplifies codebase and reduces maintenance burden

Browser Requirements

Desktop

Browser	Minimum Version	Notes
Chrome	113+	✅ Recommended
Edge	113+	✅ Recommended
Safari	18+	⚠️ Requires macOS 15+
Firefox	Nightly	⚠️ Behind flag, not recommended

Mobile

Platform	Browser	Notes
iOS	Safari 18+	Requires iOS 18+
Android	Chrome 113+	Most Android devices

Verification

Check your browser/GPU support at: webgpureport.org Or check chrome://gpu in Chrome/Edge:

Look for “WebGPU: Hardware accelerated”
Verify “WebGPU Status” shows enabled features

Server/Streaming Requirements

GPU Hardware

Required:

NVIDIA GPU with Vulkan support
CUDA capability 3.5+ (most GPUs from 2014+)
Minimum 2GB VRAM (4GB+ recommended)

Verify:

# Check GPU
nvidia-smi

# Check Vulkan support
vulkaninfo --summary

# Check CUDA version
nvcc --version

Software Stack

Required packages:

# NVIDIA drivers
nvidia-driver-XXX              # Match your GPU
nvidia-utils

# Vulkan
mesa-vulkan-drivers
vulkan-tools
libvulkan1

# X Server (for display protocol)
xserver-xorg-core              # For Xorg
xvfb                           # For Xvfb fallback
x11-xserver-utils              # xdpyinfo, etc.

# Chrome
google-chrome-unstable         # Chrome Dev channel

Display Server Setup

Hyperscape streaming requires a display server (Xorg or Xvfb) for Chrome to access WebGPU.

Option 1: Xorg with NVIDIA (Preferred)

Requirements:

DRI/DRM device access (/dev/dri/card0)
NVIDIA X driver installed

Configuration (/etc/X11/xorg-nvidia-headless.conf):

Section "ServerLayout"
    Identifier     "Layout0"
    Screen      0  "Screen0"
EndSection

Section "Device"
    Identifier     "Device0"
    Driver         "nvidia"
    BusID          "PCI:X:Y:Z"                    # Auto-detected from nvidia-smi
    Option         "AllowEmptyInitialConfiguration" "True"
    Option         "UseDisplayDevice" "None"
EndSection

Section "Screen"
    Identifier     "Screen0"
    Device         "Device0"
    DefaultDepth    24
    SubSection     "Display"
        Depth       24
        Virtual    1920 1080
    EndSubSection
EndSection

Start Xorg:

Xorg :99 -config /etc/X11/xorg-nvidia-headless.conf -noreset &
export DISPLAY=:99

Verify:

xdpyinfo -display :99
glxinfo -display :99 | grep "OpenGL renderer"  # Should show NVIDIA GPU

Option 2: Xvfb with NVIDIA Vulkan (Fallback)

When to use:

Container without DRM device access
Xorg fails to initialize NVIDIA driver

How it works:

Xvfb provides X11 protocol (virtual framebuffer)
Chrome uses NVIDIA GPU via ANGLE/Vulkan (not the framebuffer)
CDP captures frames from Chrome’s internal GPU rendering

Start Xvfb:

Xvfb :99 -screen 0 1920x1080x24 -ac +extension GLX +render -noreset &
export DISPLAY=:99
export DUEL_CAPTURE_USE_XVFB=true

Verify:

xdpyinfo -display :99
# Chrome will use Vulkan directly, not the Xvfb framebuffer

Vulkan Configuration

Force NVIDIA ICD (avoid Mesa conflicts):

export VK_ICD_FILENAMES=/usr/share/vulkan/icd.d/nvidia_icd.json

Why this is needed:

Some containers have broken Mesa Vulkan ICDs
Mesa ICDs can conflict with NVIDIA drivers
Forcing NVIDIA-only ICD ensures consistent behavior

Verify Vulkan:

vulkaninfo --summary
# Should show NVIDIA GPU, not llvmpipe/lavapipe

Chrome Configuration

Launch Arguments

Chrome must be launched with specific flags for WebGPU:

# WebGPU essentials
--enable-unsafe-webgpu
--enable-features=Vulkan,UseSkiaRenderer,WebGPU
--ignore-gpu-blocklist
--enable-gpu-rasterization

# ANGLE/Vulkan backend
--use-gl=angle
--use-angle=vulkan

# Headless mode (if using Xvfb)
--headless=new                 # Chrome's new headless mode with GPU support

# Sandbox & stability
--no-sandbox
--disable-dev-shm-usage
--disable-web-security

Playwright Configuration

const browser = await chromium.launch({
  headless: false,              // Must be false for Xorg/Xvfb
  channel: 'chrome-dev',        // Use Chrome Dev channel
  args: [
    '--use-gl=angle',
    '--use-angle=vulkan',
    '--enable-unsafe-webgpu',
    '--enable-features=Vulkan,UseSkiaRenderer,WebGPU',
    '--ignore-gpu-blocklist',
    '--enable-gpu-rasterization',
    '--no-sandbox',
    '--disable-dev-shm-usage',
  ],
  env: {
    DISPLAY: ':99',
    VK_ICD_FILENAMES: '/usr/share/vulkan/icd.d/nvidia_icd.json',
  },
});

Troubleshooting

”WebGPU not supported” Error

Cause: Chrome cannot access WebGPU API Solutions:

Verify browser version: google-chrome-unstable --version (should be 113+)
Check chrome://gpu - WebGPU should show “Hardware accelerated”
Verify Vulkan works: vulkaninfo --summary
Check display server: xdpyinfo -display $DISPLAY
Verify VK_ICD_FILENAMES is set correctly

Black Screen / No Rendering

Cause: WebGPU initialized but rendering failed Solutions:

Check browser console for WebGPU errors
Verify shaders compiled: Look for TSL compilation errors
Check GPU memory: nvidia-smi (should have free VRAM)
Verify display server is using GPU: glxinfo | grep renderer

Xorg Falls Back to Software Rendering

Symptoms:

Xorg starts but uses swrast (software rendering)
/var/log/Xorg.99.log shows “IGLX: Loaded and initialized swrast”

Cause: NVIDIA driver failed to initialize Solutions:

Check NVIDIA driver is installed: nvidia-smi
Verify DRI devices exist: ls -la /dev/dri/
Check Xorg config has correct BusID
Review Xorg errors: grep "(EE)" /var/log/Xorg.99.log
Try Xvfb fallback instead

Vulkan Initialization Failed

Symptoms:

vulkaninfo fails or shows no devices
Chrome shows “Vulkan: Disabled”

Cause: Vulkan ICD not found or broken Solutions:

Install Vulkan packages: apt install mesa-vulkan-drivers vulkan-tools libvulkan1
Verify ICD file exists: ls -la /usr/share/vulkan/icd.d/nvidia_icd.json
Check ICD points to valid library: cat /usr/share/vulkan/icd.d/nvidia_icd.json
Force NVIDIA ICD: export VK_ICD_FILENAMES=/usr/share/vulkan/icd.d/nvidia_icd.json

Deployment Checklist

Before deploying to a GPU server (Vast.ai, etc.):

NVIDIA GPU with Vulkan support
NVIDIA drivers installed (nvidia-smi works)
Vulkan tools installed (vulkaninfo works)
X server packages installed (Xorg or Xvfb)
Chrome Dev channel installed (google-chrome-unstable)
Display server starts successfully (xdpyinfo -display :99)
Vulkan ICD configured (VK_ICD_FILENAMES set)
WebGPU works in Chrome (chrome://gpu shows hardware accelerated)

Configuration

Operations

Webgpu requirements

WebGPU Requirements

Why WebGPU is Required

TSL Shaders

No WebGL Fallback

Browser Requirements

Desktop

Mobile

Verification

Server/Streaming Requirements

GPU Hardware

Software Stack

Display Server Setup

Option 1: Xorg with NVIDIA (Preferred)

Option 2: Xvfb with NVIDIA Vulkan (Fallback)

Vulkan Configuration

Chrome Configuration

Launch Arguments

Playwright Configuration

Troubleshooting

”WebGPU not supported” Error

Black Screen / No Rendering

Xorg Falls Back to Software Rendering

Vulkan Initialization Failed

Deployment Checklist

See Also

​WebGPU Requirements

​Why WebGPU is Required

​TSL Shaders

​No WebGL Fallback

​Browser Requirements

​Desktop

​Mobile

​Verification

​Server/Streaming Requirements

​GPU Hardware

​Software Stack

​Display Server Setup

​Option 1: Xorg with NVIDIA (Preferred)

​Option 2: Xvfb with NVIDIA Vulkan (Fallback)

​Vulkan Configuration

​Chrome Configuration

​Launch Arguments

​Playwright Configuration

​Troubleshooting

​”WebGPU not supported” Error

​Black Screen / No Rendering

​Xorg Falls Back to Software Rendering

​Vulkan Initialization Failed

​Deployment Checklist

​See Also

WebGPU Requirements

Why WebGPU is Required

TSL Shaders

No WebGL Fallback

Browser Requirements

Desktop

Mobile

Verification

Server/Streaming Requirements

GPU Hardware

Software Stack

Display Server Setup

Option 1: Xorg with NVIDIA (Preferred)

Option 2: Xvfb with NVIDIA Vulkan (Fallback)

Vulkan Configuration

Chrome Configuration

Launch Arguments

Playwright Configuration

Troubleshooting

”WebGPU not supported” Error

Black Screen / No Rendering

Xorg Falls Back to Software Rendering

Vulkan Initialization Failed

Deployment Checklist

See Also