Support for WebGPU Compatibility Mode

[greggman]

Description

WebGPU has an upcoming compatibility mode that allows it to run on older devices. Maybe three.js has an interest in supporting it?

It's available as of 2025-03-11 in Chrome Canary with the chrome://flags/#enable-unsafe-webgpu feature turned on.

Solution

There are many limits and restrictions for compatibility mode. You can read about them here.

The most common one, and semi easily fixed, is that code that generates mipmaps usually needs to be updated to work around some of the compatibility mode restrictions. There's an example of how to deal with generating mipmaps in compatibility mode in this article

Making that change in three.js alone will probably make the majority of three.js WebGPU examples run in compatibility mode.

I looked into trying to write a PR for three.js but it requires knowing how the texture will be used (2d, 2d-array, cube) and it wasn't clear if that info is available in the WebGPU backend at the moment. In any case, you can look at the solution linked and decide if you want to adapt three.js using a similar solution.

Alternatives

??? Fall back to WebGL2 like three.js does already? Compatibility mode, when it actually ships in a few months, should run on the majority of devices that currently run WebGL2. > 90% of them? Plus, you get compute shaders in WebGPU.

Additional context

The feature has been being worked on for 2 years and is close to shipping for some definition of close. It would be nice if three.js could support it.

[Makio64]

@greggman Its very nice, and an important point to convince clients with large user base to use WebGPU.

Here the List of restrictions based on WebGPUFundamentals's article

Restriction	Description
Storage Buffers in Vertex Shaders	~45% older devices don't support storage buffers in vertex shaders.
Single Texture View Dimension	Textures limited to one view dimension set at creation.
Subset of Layers in Texture Views	Cannot select subset of texture layers when creating views.
Mipmap Generation	Requires special handling due to texture view restrictions.
Uniform Color Blending	Blending settings must be identical across all color targets.
Copy Operations with Compressed Textures	copyTextureToBuffer and copyTextureToTexture don't support compressed textures.
Multisampled Textures	copyTextureToTexture does not support multisampled textures.
Cube-Array Textures	Cube-array textures are unsupported.
Texture View Consistency	Texture views within a draw/dispatch call must have identical aspects/mip levels.
Sample Mask and Index	@builtin(sample_mask) and @builtin(sample_index) unsupported.
Storage Texture Formats	rg32uint, rg32sint, rg32float formats unsupported as storage textures.
Depth Clamp Bias	Must be set to 0.
Interpolation Modes	@interpolation(linear), @interpolation(sample), @interpolate(flat), @interpolate(flat, first) unsupported; use @interpolate(flat, either) instead.
Texture Format Reinterpretation	Cannot reinterpret textures between formats (e.g., rgba8unorm ↔ rgba8unorm-srgb).
Unsupported Texture Formats	bgra8unorm-srgb is not supported.
Multisampled Texture Restrictions	rgba16float, r32float, and integer formats cannot be multisampled.
Texture Dimension Compatibility	depthOrArrayLayers must match textureBindingViewDimension.
Depth Textures	No textureLoad or non-comparison samplers on depth textures.
Texture-Sampler Combinations	Limited to 16 combinations per shader stage.
Default Limits	Lower defaults, e.g., maxColorAttachments (4), maxComputeInvocationsPerWorkgroup (128), maxTextureDimension2D (4096).
New Limits	Defaults to 0: maxStorageBuffersInVertexStage, maxStorageTexturesInVertexStage, maxStorageBuffersInFragmentStage, maxStorageTexturesInFragmentStage.

[greggman]

I was talking to @mrdoob and it sounds like something that was not clear is that you can request compat and get core.

const adapter = await navigator.gpu.requestAdapter({ featureLevel: 'compatibility' });
const hasCore = adapter.features.has('core-features-and-limits');
const device = await adapter.requestDevice({
  requiredFeatures: [
    ...(hasCore ? ['core-features-and-limits'] : []),
  ],
});

At this point, if hasCore is true you have a "core" WebGPU device. If hasCore is false, you have a compatibility device (so the comapt restrictions apply)

Note: This requires Chrome 137 but after that, all browsers should support this code (works in Chrome 136 but only with --enable-webgpu-developer-features)

[greggman]

Also, maxStorageBuffersInFragmentStage and maxStorageTexturesInFragmentStage were upgraded to default to 4 in compat (not 0). 🎉

[mrdoob]

Hmm.... What happens if the user runs that code in an older version of Chrome?

Should we do a version check of Chrome before running that code path?

[greggman]

That a judgement call. Apparently 90% of users upgrade within 2 weeks

https://timotijhof.net/posts/2023/browser-adoption/

So if it was me, I'd use the code above in a version of three.js that shipped 2-4 weeks after v137 and not worry about the stragglers

but that's what i'd choose.

[greggman]

I'm going to change my answer. I'd suggest writing this code but not shipping it until compatibility mode actually ships to stable with no flags in some browser. not sure when that will be. but, there isn't much point in shipping compatibility mode checking and support until end users can use it. That would give even more time for the issue above to disappear