Run WebGPU on Older Devices: Understanding Compatibility Mode

WebGPU compatibility mode is designed to allow your applications to run on a wider range of devices, especially older ones, by adhering to certain limitations. This article will guide you through the specifics of compatibility mode, its restrictions, and how to adapt your code to make the most of it.

What is WebGPU Compatibility Mode and Why Use It?

WebGPU compatibility mode enables your WebGPU applications to function on devices that might not fully support the core WebGPU specifications.

Expanded Reach: By developing with compatibility mode in mind, you can target a broader audience, including users with older hardware.
Nearly Universal WebGL2 Conversion: Most WebGL2 programs can be converted to run in this mode.

To enable compatibility mode in Chrome Canary (version 136.0.7063.0 or newer), activate the “enable-unsafe-webgpu” flag in chrome://flags/#enable-unsafe-webgpu.

const adapter = await navigator.gpu.requestAdapter({
 featureLevel: 'compatibility',
});
const device = await adapter.requestDevice();

Adhering to compatibility mode limits ensures your app is also a valid "core" WebGPU application

Major Restrictions in Compatibility Mode

One of the primary limitations is the restricted use of storage buffers in vertex shaders.

Limited Storage Buffers: Approximately 45% of older devices do not support storage buffers in vertex shaders.

If you're using storage buffers for vertex data, consider alternative solutions like vertex buffers, which are universally supported.

Medium-Level Restrictions: Texture Management

Compatibility mode imposes constraints on texture usage, specifically in how textures are viewed and manipulated.

Single ViewDimension Requirement

In standard WebGPU, a texture can have multiple view dimensions. For example:

const myTexture = device.createTexture({
 size: [width, height, 6],
 usage: ...,
 format: ...
});

// Valid in core WebGPU, but NOT in compatibility mode if mixed
const as2DArray = myTexture.createView();
const as2D = myTexture.createView({ viewDimension: '2d', baseArrayLayer: 3, arrayLayerCount: 1 });
const asCube = myTexture.createView({ viewDimension: 'cube' });

Compatibility mode restricts you to a single viewDimension per texture. A 2D texture with one layer defaults to a '2d' view, while multiple layers default to a '2d-array' view. For cubemaps, specify the textureBindingViewDimension when creating the texture:

const cubeTexture = device.createTexture({
 size: [width, height, 6],
 usage: ...,
 format: ...,
 textureBindingViewDimension: 'cube',
});

Attempting to use a different view type will result in a validation error. For example:

const bindGroup = device.createBindGroup({
 ...
 entries: [
 {
 binding,
 // ERROR in compatibility mode: texture is a cubemap not a 2d-array
 resource: cubeTexture.createView(),
 },
 ],
})

No Layer Subsets in BindGroups

Core WebGPU allows selecting subsets of texture layers, but compatibility mode restricts this:

const texture = device.createTexture({
 size: [64, 128, 8], // 8 layers,
 ...
});

const bindGroup = device.createBindGroup({
 ...
 entries: [
 {
 binding,
 // ERROR in compatibility mode - select layers 3 and 4
 resource: cubeTexture.createView({
 baseArrayLayer: 3,
 arrayLayerCount: 2,
 }),
 },
 ],
});

These restrictions, while present, rarely impact most programs directly.

Generating Mipmaps in Compatibility Mode: A Detailed Example

Mipmap generation, a common use case, requires adaptation due to the aforementioned restrictions. The standard approach of using different view dimensions for each layer won’t work. Instead, you need to work with textures using their original view dimension and select layers within the shader.

Adapting the WGSL Shader

Here's the modified WGSL code that supports different texture types:

struct VSOutput {
 @builtin(position) position: vec4f,
 @location(0) texcoord: vec2f,
 @location(1) @interpolate(flat, either) baseArrayLayer: u32,
};

@vertex fn vs(
 @builtin(vertex_index) vertexIndex : u32,
 @builtin(instance_index) baseArrayLayer: u32,
) -> VSOutput {
 var pos = array<vec2f, 3>(
 vec2f(-1.0, -1.0),
 vec2f(-1.0, 3.0),
 vec2f( 3.0, -1.0),
 );
 var vsOutput: VSOutput;
 let xy = pos[vertexIndex];
 vsOutput.position = vec4f(xy, 0.0, 1.0);
 vsOutput.texcoord = xy * vec2f(0.5, -0.5) + vec2f(0.5);
 vsOutput.baseArrayLayer = baseArrayLayer;
 return vsOutput;
}

@group(0) @binding(0) var ourSampler: sampler;
@group(0) @binding(1) var ourTexture2d: texture_2d<f32>;
@fragment fn fs2d(fsInput: VSOutput) -> @location(0) vec4f {
 return textureSample(ourTexture2d, ourSampler, fsInput.texcoord);
}

@group(0) @binding(1) var ourTexture2dArray: texture_2d_array<f32>;
@fragment fn fs2darray(fsInput: VSOutput) -> @location(0) vec4f {
 return textureSample(
 ourTexture2dArray,
 ourSampler,
 fsInput.texcoord,
 fsInput.baseArrayLayer);
}

@group(0) @binding(1) var ourTextureCube: texture_cube<f32>;
@fragment fn fscube(fsInput: VSOutput) -> @location(0) vec4f {
 return textureSample(
 ourTextureCube,
 ourSampler,
 faceMat[fsInput.baseArrayLayer] * vec3f(fract(fsInput.texcoord), 1));
}

@group(0) @binding(1) var ourTextureCubeArray: texture_cube_array<f32>;
@fragment fn fscubearray(fsInput: VSOutput) -> @location(0) vec4f {
 return textureSample(
 ourTextureCubeArray,
 ourSampler,
 faceMat[fsInput.baseArrayLayer] * vec3f(fract(fsInput.texcoord), 1), fsInput.baseArrayLayer);
}

Key points:

Multiple Fragment Shaders: The code uses different fragment shaders for 2D, 2D-array, cube, and cube-array textures.
Instance Indexing: @builtin(instance_index) passes the layer index to the shader.
Cubemap Conversion: The cubemap code converts UV coordinates into a 3D cubemap coordinate, ensuring compatibility.

JavaScript Adjustments

In your JavaScript code, you'll need to:

Determine Texture View Dimension: If the user doesn't provide a textureBindingViewDimension, guess it based on the texture’s properties.
Select the Appropriate Fragment Shader: Based on the textureBindingViewDimension.

/**
* Get the default viewDimension
*/
function getDefaultViewDimensionForTexture(dimension, depthOrArrayLayers) {
 switch (dimension) {
  case '1d':
   return '1d';
  default:
  case '2d':
   return depthOrArrayLayers > 1 ? '2d-array' : '2d';
  case '3d':
   return '3d';
 }
}

generateMips(device, texture, textureBindingViewDimension);

Alter the generateMips function

const generateMips = (() => {
 let sampler;
 let module;
 const pipelineByFormatAndView = {};
 return function generateMips(device, texture, textureBindingViewDimension) {
 // If the user doesn't pass in a textureBindingViewDimension then guess
 textureBindingViewDimension = textureBindingViewDimension ??
 getDefaultViewDimensionForTexture(texture);
 let module = moduleByViewDimension[textureBindingViewDimension];
 if (!module) {
 ...
 }
const id = `${texture.format}.${textureBindingViewDimension}`;
 if (!pipelineByFormatAndView[id]) {
  // chose an fragment shader based on the viewDimension (removes the '-' from 2d-array and cube-array)
  const entryPoint = `fs${textureBindingViewDimension.replace(/[\W]/, '')}`;
  pipelineByFormatAndView[id] = device.createRenderPipeline({
  label: `mip level generator pipeline for ${textureBindingViewDimens

Conclusion

WebGPU compatibility mode offers a pathway to support a wider array of devices, particularly older ones. By understanding and adapting to its restrictions, like those concerning storage buffers and texture management, you can ensure your WebGPU applications reach a broader audience without sacrificing functionality.