Three.js WebGPURenderer vs WebGLRenderer

Decision rule

Use WebGPURenderer when the application needs TSL node materials, WebGPU compute or storage, or its RenderPipeline and the team can absorb migration and compatibility risk. Keep WebGLRenderer when pure WebGL 2 is sufficient, an established GLSL and EffectComposer stack owns the product, or the target workload has not proved a benefit from migration.

WebGPURenderer can use a WebGL 2 fallback backend. The renderer object's name is therefore not proof of native WebGPU execution. Verify the actual backend before making a WebGPU claim.

This page assumes Three.js 0.185.1 and a browser application. It makes no universal performance claim.

Architecture comparison

Most familiar renderer methods have equivalents, but that does not make the migration mechanical. Custom shaders and post-processing are the largest architectural boundaries.

Choose WebGPURenderer when

• A required feature uses TSL compute, storage resources, node materials, or RenderPipeline.
• The project is investing in the current Three.js WebGPU architecture rather than preserving a WebGL-only design.
• Custom materials can be ported from GLSL or onBeforeCompile to NodeMaterial channels.
• Target browsers, devices, and deployment conditions can be tested with explicit backend reporting.
• The team can validate missing features, performance behavior, and fallback conditions per release.

WebGPURenderer is also the relevant path when one TSL graph should generate code for its available backend. That portability should not be confused with a guarantee that the native WebGPU backend is active.

Keep WebGLRenderer when

• The application is intentionally a pure WebGL 2 product.
• Existing ShaderMaterial, RawShaderMaterial, onBeforeCompile, or EffectComposer code is large and stable.
• A required addon or feature is not ready on the WebGPU path.
• Current target devices behave better on the established WebGL renderer for the measured workload.
• The migration would consume engineering time without enabling a required product capability.

The official manual states that WebGLRenderer remains maintained and recommended for pure WebGL 2 applications. It also notes that no large new features are planned there. Those facts create a planning tradeoff, not an automatic deadline to migrate.

Backend identity and fallback

A correct backend check distinguishes at least three states:

1. WebGPURenderer with a native WebGPU backend.
2. WebGPURenderer using its WebGL 2 fallback backend.
3. WebGLRenderer.

Report the renderer, backend, adapter or device evidence available to the harness, and any force-fallback setting. If native WebGPU is required and unavailable, do not silently present fallback output as proof of WebGPU execution. The native backend FAQ gives the exact verification route.

Cost and performance

Do not compare renderer names with one headline FPS number. Hold scene content, camera, resolution, pixel ratio, output format, effects, warm-up, and measurement interval constant. Record the actual backend and device.

Relevant costs include:

• draw calls, geometry, material variants, and CPU submission;
• render and compute passes;
• attachment formats, samples, storage, and bandwidth;
• history buffers and invalidation;
• shader compilation and pipeline warm-up;
• readback and diagnostic overhead;
• fallback-specific behavior.

WebGPU can enable compute and pipeline designs that are unavailable through WebGLRenderer. It can also lose for a particular scene, browser, driver, or immature feature path. Only measured workload evidence resolves the choice.

Migration sequence

1. Inventory renderer imports, initialization, materials, onBeforeCompile, post passes, render targets, readbacks, and browser requirements.
2. Capture a WebGL baseline with final and diagnostic views.
3. Establish a minimal WebGPURenderer path and prove the active backend.
4. Port one bounded custom material or effect to TSL.
5. Rebuild post-processing under one RenderPipeline output owner.
6. Compare correctness, failure conditions, and measured resource cost.
7. Expand only after the target device matrix passes.

Use the complete WebGLRenderer to WebGPURenderer migration guide before changing a production renderer.

Limitations

The upstream WebGPU path evolves quickly, so every claim must be rechecked after r185. Automatic WebGL 2 fallback improves reach but can conceal an unmet native-WebGPU requirement. Conversely, rejecting WebGPURenderer because one feature is incomplete can overlook workloads where its node, compute, or post architecture is already the better fit.

Neither renderer repairs poor scene architecture, incorrect color management, duplicate output transforms, leaks, or unbounded effects. Those must be verified separately.