WebGPU and MSL output
Running on the GPU in a browser (WebGPU, experimental)
Section titled “Running on the GPU in a browser (WebGPU, experimental)”This path is experimental and will not be maintained going forward. Kernel features added from now on target only the CPU and Metal, and may not be supported in WGSL (they may be compile errors).
When building for wasm32, dispatched kernels are translated to WGSL (the WebGPU shading language) and embedded in the wasm. instantiate in runtime/host.mjs runs those kernels with WebGPU.
import { instantiate } from './runtime/host.mjs';const exports = await instantiate(wasmBytes, { print: console.log });await exports.main(); // returns a Promise where a GPU is available, so always await it- The automatic choice is simple. If a GPU is available and the element count is at or above a threshold (4096 by default; change it with
gpuThreshold), it runs on the GPU. There is no choice by measurement. - Each dispatch sends the Buffers and reads back those written to, because in WebGPU the CPU and GPU memory are separate. Small jobs, and processing that goes back and forth with the CPU often, are faster on the CPU.
gpu.submitruns the work to completion on the spot and returns ticket 0.- JSPI (a feature that suspends WebAssembly execution to wait for a Promise) is required, because WebGPU readback can only be done asynchronously. Where JSPI or WebGPU is missing, it runs as if there were no GPU, and
dispatchruns on the CPU. It works in desktop Chrome / Edge 137 or later. - What has been checked: it was run once in a Chromium-based browser on Android (Adreno GPU), and 2 of 3 tests matched. The remaining one differed only in an out-of-range float→integer conversion, and the fix for it has not been rechecked on the device. Kernels with 8- and 16-bit integers were checked to match the CPU on Deno’s WebGPU.
- To see the generated WGSL, run
node src/cli.ts build x.um --emit-wgsl.
MSL (Metal Shading Language) output
Section titled “MSL (Metal Shading Language) output”node src/cli.ts build x.um --emit-msl writes the MSL for each kernel to <output>.<kernel>.metal (the same translation that goes into UM_METAL=1 builds).
- Checks with Metal: the MSL of all 51 kernels in the tests and examples was checked to compile with the Metal compiler (Apple M4) (2026-11-15). Running on the GPU is checked on a Mac by confirming that the kernels in
tests/metalgive the same results as the CPU (node tests/run.tsruns this on a Mac). - Checks without Metal: the generated MSL is compiled as C++14 with
clang++together with a stub header (tests/msl/metal_stub.h) (all kernels intests/gpuandexamples), and the kernels intests/msl/kernels.umare run as C++ over every index and their checksums compared with the CPU results (node tests/run.tsdoes this whenclang++is available). Passing as C++ does not mean conforming to the Metal specification, so Metal-specific rules are checked by running on a Mac.