SOP: Initialize WebGPU

Fresh 🌱

Version: 1.0 | Chrome: 113+

Overview

This SOP covers the complete initialization sequence for WebGPU: checking availability, requesting a GPU adapter, creating a device, and configuring a canvas context.

Flowchart

Prerequisites

• Chrome 113+ (desktop) or Chrome 121+ (Android)
• HTTPS or localhost context
• Hardware acceleration enabled in chrome://settings/system

Step-by-Step

Step 1 — Check WebGPU Availability

if (!navigator.gpu) {
  console.error('WebGPU not supported in this browser');
  // Show user-facing fallback
  return;
}

Step 2 — Request GPU Adapter

const adapter = await navigator.gpu.requestAdapter({
  powerPreference: 'high-performance' // or 'low-power'
});

if (!adapter) {
  console.error('No GPU adapter found. Check chrome://gpu');
  return;
}

// Optional: log adapter info
console.log('GPU:', adapter.info.description);

Power Preference

On most systems, powerPreference is advisory only. On Windows, Chrome always uses the same adapter for all workloads. Use chrome://flags/#force-high-performance-gpu to override.

Step 3 — Request GPU Device

const device = await adapter.requestDevice({
  requiredLimits: {
    maxStorageBufferBindingSize: adapter.limits.maxStorageBufferBindingSize,
  }
});

// Handle device loss
device.lost.then((info) => {
  console.error('GPU device lost:', info.message, info.reason);
  // Re-initialize if needed
});

Device Limits

By default, requestDevice() returns a device with minimum guaranteed limits — NOT your full hardware capabilities. Explicitly request limits you need.

Step 4 — Configure Canvas Context

const canvas = document.querySelector('canvas');
const context = canvas.getContext('webgpu');

const format = navigator.gpu.getPreferredCanvasFormat();

context.configure({
  device,
  format,
  alphaMode: 'premultiplied' // or 'opaque'
});

Step 5 — Full Initialization Template

async function initWebGPU() {
  // Check support
  if (!navigator.gpu) throw new Error('WebGPU not supported');

  // Adapter
  const adapter = await navigator.gpu.requestAdapter();
  if (!adapter) throw new Error('No GPU adapter available');

  // Device
  const device = await adapter.requestDevice();
  device.lost.then(info => console.error('Device lost:', info.message));

  // Canvas
  const canvas = document.querySelector('canvas');
  const context = canvas.getContext('webgpu');
  const format = navigator.gpu.getPreferredCanvasFormat();
  context.configure({ device, format });

  return { adapter, device, context, format };
}

// Usage
const { adapter, device, context, format } = await initWebGPU();

Verification Checklist

• [ ] No console errors on requestAdapter()
• [ ] adapter is not null
• [ ] device created without errors
• [ ] Canvas context configured
• [ ] device.lost handler registered
• [ ] chrome://gpu shows "WebGPU: Hardware accelerated"

Troubleshooting

Error	Cause	Fix
navigator.gpu is undefined	Chrome < 113, or HTTP context	Update Chrome; use HTTPS or localhost
adapter is null	HW acceleration off, blocked, no GPU	See Troubleshooting guide
Device lost immediately	GPU process crash	Reload page; check chrome://gpu

See Also

• Create Render Pipeline
• GPU Compute Setup
• Troubleshooting Guide