WebGPU Debugging Guide

Overview

WebGPU is the next-generation graphics API for the web, and rendara provides native support for debugging WebGPU applications—both in browsers and native implementations like wgpu and Dawn.

Browser Setup

Chrome / Chromium

Install the rendara browser extension for seamless capture:

1. Install the rendara Chrome Extension
2. Navigate to your WebGPU application
3. Click the rendara icon and select "Capture Frame"

Alternatively, use the command line:

# Launch Chrome with rendara injection
rendara launch-browser chrome --url "https://your-webgpu-app.com"

Firefox

Firefox WebGPU support requires Nightly with flags enabled:

# Launch Firefox Nightly with WebGPU and rendara
rendara launch-browser firefox-nightly --url "https://your-webgpu-app.com"

Native WebGPU (wgpu / Dawn)

For native WebGPU applications using wgpu-rs or Dawn:

# Launch your wgpu application
rendara launch ./my-wgpu-app

# Or attach to running process
rendara capture --pid $(pgrep my-wgpu-app)

rendara automatically detects the WebGPU backend (Vulkan, Metal, DX12) and captures at the appropriate level.

WGSL Shader Debugging

rendara fully supports WGSL (WebGPU Shading Language) debugging:

• Syntax Highlighting — Full WGSL syntax support in shader viewer
• Variable Inspection — See values of WGSL variables at any point
• Step Debugging — Step through WGSL shaders line by line
• AI Explanations — Ask questions about your WGSL code

rendara ask "why is this WGSL shader outputting NaN?"

Bind Group Inspection

WebGPU uses bind groups instead of descriptor sets. rendara shows:

• All bind group layouts and their entries
• Bound buffers with contents
• Bound textures with full mip/layer inspection
• Samplers and their parameters

Render Bundle Analysis

WebGPU render bundles pre-record commands for efficiency. rendara captures and displays:

• Bundle creation parameters
• Commands within each bundle
• Bundle execution points in the main command stream

Common WebGPU Issues

Validation Errors

WebGPU has strict validation. rendara shows validation errors inline:

⚠ VALIDATION: Bind group layout mismatch
  Pipeline expects: @group(0) @binding(1) var<uniform> Camera
  Bound: @group(0) @binding(1) var<storage> Data

Missing Resources

Check bind group bindings match your shader expectations:

rendara ask "which bindings are missing for the current draw call?"

Performance

WebGPU has different performance characteristics than WebGL:

• Minimize bind group changes between draws
• Use render bundles for repeated command sequences
• Batch buffer updates with writeBuffer

Three.js WebGPU

Three.js now supports WebGPU as a backend. rendara works seamlessly:

// Your Three.js code
const renderer = new THREE.WebGPURenderer();

// Capture with rendara extension or CLI
// All Three.js abstractions are visible as WebGPU calls