v148 · WebGPU

Portable WGSL

Compatibility mode imposes restrictions on WGSL — the WebGPU shader language — because it targets OpenGL ES 3.1 and D3D11 backends that lack some modern GPU features. This guide shows each restriction with a before/after code pair so you can audit and fix existing shaders.

Feature detection: checking…

Quick compat-safety checklist

✗No textureStore() in vertex shaders — GLES 3.1 doesn't allow storage writes from vertex stage
✗No textureSampleLevel() / textureGather() in vertex shaders — vertex texture fetch is limited
✗No cube array textures (texture_cube_array) — not supported in GLES 3.1
✗No 2D array storage textures — storage image arrays require extensions not in core GLES 3.1
~Fine derivatives (dpdxFine, dpdyFine) always equal coarse derivatives in compat — avoid for precision-sensitive effects
~Multi-sample textures (texture_multisampled_2d) — only readable, not writable, in compat
✓var<storage> in fragment + compute shaders — fine in compat (GLES 3.1 SSBOs)
✓All standard WGSL arithmetic, control flow, structs — fully portable
✓Uniform buffers (var<uniform>) everywhere — fully portable

Restrictions with code examples

Click a card to expand the before / after code pair.

// Feature-detect compat mode before choosing shader variant
const adapter = await navigator.gpu.requestAdapter({
  featureLevel: 'compatibility',  // explicit opt-in
});

const isCompat = adapter.info?.featureLevel === 'compatibility';

const shaderModule = device.createShaderModule({
  code: isCompat ? COMPAT_WGSL : CORE_WGSL,
});

// Or detect at runtime for shader defines (not yet in WGSL spec but
// the pattern: compile two pipelines, choose by adapter.featureLevel)
const pipeline = device.createRenderPipeline({
  ...pipelineDesc,
  vertex:   { module: shaderModule, entryPoint: 'vs' },
  fragment: { module: shaderModule, entryPoint: 'fs', targets: [{ format }] },
});

see also

implementation reference

Need the exact API surface, compatibility boundaries, errors, lifecycle, and source links? Read the matching gendn reference ↗