The renderer#

createRenderer returns an initialized three.js WebGPURenderer set up the way Radix expects: WebGPU when the browser has it and the WebGL2 backend otherwise, with the device limits that about 95% of devices support. This page also covers getGpuCaps, HDR output (Hdr), and GPU timing (GpuProfiler).

Code: src/gpu/createRenderer.ts, baseline.ts, hdr.ts, and GpuProfiler.ts.

const renderer = await createRenderer({ antialias: false });
const caps = getGpuCaps(renderer);
console.log(caps.backend); // "webgpu" or "webgpu-gl"

Shaders in Radix are written in TSL (three.js Shading Language) only, with no raw WGSL or GLSL, so the same code runs on both backends (Shaders).

createRenderer#

An option passed to the call takes precedence over its URL parameter. An option left out comes from its URL parameter, or else from its default. A page that wants its own default and still wants the URL to override it reads the parameter and passes the value itself.

• If WebGPU was asked for (?gpu=webgpu) and device creation fails, three falls back to WebGL2 by itself and Radix logs a warning.
• On WebGL2, timer queries cannot nest, so only profile keeps them (its phases render outside the frame's passes); timing alone has no effect there.
• On WebGL2, createRenderer enables EXT_color_buffer_float (float render targets and readback; it warns when the extension is missing) and EXT_float_blend, and logs which parameters fall below the WebGL2 baseline.

Device baselines#

On WebGPU, createRenderer asks for these limits above WebGPU's defaults. Each is capped at what the adapter offers, so the request never fails. Each value is met by about 95% of devices or more (web3dsurvey.com, Sep 2026). Design WebGPU code against these, not against the development machine.

Kept at the default because the next tier is under 95%: 4 storage textures per stage, 256 compute invocations per workgroup, 16 sampled textures per stage, 16 inter-stage variables, 4 bind groups. Optional features at or above 95%: timestamp-query, indirect-first-instance, depth32float-stencil8, rg11b10ufloat-renderable, depth-clip-control, and bgra8unorm-storage; shader-f16, float32-filterable, float32-blendable, subgroups, and texture compression need a fallback.

WebGL2 parameters to design against: 8192 texture size, 512 array layers, 4 draw buffers, 16 texture units per stage, 16 KiB uniform blocks, 15 varying vectors, 16 vertex attributes, and 4 MSAA samples. snorm8 is not renderable there (EXT_render_snorm is at 80%).

getGpuCaps#

getGpuCaps(renderer) returns a GpuCaps:

Types: GpuBackend ("webgpu" | "webgpu-gl"), CreateRendererOptions, LimitRequest, and GpuCaps.

HDR output#

HDR output has two independent parts:

• The HDR canvas (WebGPU only): createRenderer({ hdr }) configures an rgba16float canvas with extended tone mapping, so values above 1 show brighter than SDR white on HDR displays (Chrome 129+). The canvas stays sRGB-encoded, so colors drawn to it blend as on an SDR canvas.
• Headroom tone mapping (both backends): Hdr.useToneMapping(renderer) renders into three's float frame target and compresses the finished frame into [0, headroom] in its output pass. Values below the knee are unchanged, values above it follow a smooth shoulder, and colors past the headroom fade to white instead of clipping per channel. Headroom 1 is SDR tone mapping.

const renderer = await createRenderer({ hdr: "auto" });
// Headroom 4 on an HDR canvas, else 1
const tone = Hdr.useToneMapping(renderer);

// Uniforms: change them any time
tone.headroom.value = settings.headroom;
// Restores three's tone mapping
tone.enabled = false;

Splats blend sRGB-encoded colors, as they were trained. The tone mapping pass decodes them first, and three encodes its result, so below the knee the frame is the same as without tone mapping. There is no web API for a display's actual headroom yet; pick one (about 2 to 8 on current HDR laptops and monitors) or make it a setting.

GpuProfiler#

GpuProfiler records GPU and CPU milliseconds per named phase. GPU times come from three's timestamp queries (WebGPU timestamp-query, or EXT_disjoint_timer_query_webgl2 on WebGL2); CPU times wrap the phase's code. createRenderer({ profile: true }) installs one as renderer.inspector.

const profiler = renderer.inspector as GpuProfiler;
// "project" and "sort" get their own rows
splatRenderer.phase = (name, run) => profiler.phase(name, run);

renderer.setAnimationLoop(async () => {
  profiler.beginFrame();
  profiler.label = "draw";
  renderer.render(scene, camera);
  // ms per phase, averaged; undefined if nothing resolved
  const report = await profiler.collect();
  // "GPU draw 2.31, project 0.09 | CPU ... ms"
  if (report) console.log(GpuProfiler.format(report));
});

Timestamps resolve a frame or two late. Chrome quantizes them to 100 µs unless WebGPU developer features are on (--enable-webgpu-developer-features).

Source: docs/renderer.md