three.js render targets in/out

The zero-copy integration path: get a three.js render target into the denoiser as a GPUTexture, and get the denoised result out into a texture three.js can sample — no CPU pixels anywhere. Everything here is lifted from the working example (examples/three-pathtracer-webgpu/src/main.ts).

Requires three ≥ r185 (three/webgpu, the WebGPURenderer).

With the default runtime (AutoRuntime: WebNN or hand-written WGSL) the denoiser can adopt an existing device, so the clean order is renderer first, then the denoiser on the renderer's device:

import * as THREE from 'three/webgpu';
import { Denoiser } from 'denoiser';

const renderer = new THREE.WebGPURenderer({ canvas });
await renderer.init();

const denoiser = await Denoiser.create({
  device: (renderer.backend as { device: GPUDevice }).device,
  precision: 'fp16',
});

Or let denoiser/three unwrap the device for you; this works with any runtime that can adopt a device (AutoRuntime, WgslRuntime, WebnnRuntime, KernelsRuntime):

import { createDenoiserForRenderer } from 'denoiser/three';
import { AutoRuntime } from 'denoiser/auto';

const denoiser = await createDenoiserForRenderer(renderer, {
  runtime: (device) => new AutoRuntime({ device }),
  precision: 'fp16',
});

Without a device, the runtime creates one with the adapter's max limits/features, so the shared device can hold whole-frame U-Net intermediates. If your renderer creates the device, request high limits there too (a path tracer's own buffers compete for the same budget); patchWebGPUForMaxLimits() in examples/_shared/stack.ts shows one way.

import { OrtRuntime } from 'denoiser/ort';
const denoiser = await Denoiser.create({ runtime: new OrtRuntime(), precision: 'fp16' });
const renderer = new THREE.WebGPURenderer({ canvas, device: denoiser.device });
await renderer.init();

Lifetime rules:

three.js doesn't expose the backing GPUTexture publicly; it lives in the backend's data map:

const backendGet = (threeTexture: THREE.Texture): GPUTexture | undefined =>
  (renderer.backend as any).get(threeTexture)?.texture;

const colorTex = backendGet(myRenderTarget.texture);

OIDN's guided models dramatically improve low-sample quality. Rasterize the same scene once into an MRT target — albedo = unlit base color, normal = view-space normals in [-1,1]:

import { mrt, diffuseColor, normalView } from 'three/tsl';

const gbuffer = new THREE.RenderTarget(W, H, { count: 2, type: THREE.HalfFloatType });

renderer.setMRT(mrt({ albedo: diffuseColor, normal: normalView }));
renderer.setRenderTarget(gbuffer);
renderer.render(scene, camera);
renderer.setRenderTarget(null);
renderer.setMRT(null);

const albedo = backendGet(gbuffer.textures[0]);
const normal = backendGet(gbuffer.textures[1]);

Rasterized aux is noise-free, so the higher-quality cleanAux (*_calb_cnrm) model is selected automatically when both planes are present. The G-buffer is view-dependent — re-render it when the camera moves. For the full set of conventions (env-pixel normals, HDR albedo clamping, first-hit rules) see Generating aux inputs.

const outTex = await denoiser.denoiseTextures({
  color: colorTex,        // GPUTexture, float, linear
  albedo, normal,         // optional GPUTextures -> guided model
  hdr: true,               // linear-HDR input (path tracer output)
  // inputFlipY / auxInputFlipY default to false: three-gpu-pathtracer >= 0.0.27
  // and raster G-buffers are both top-down. Set true for a bottom-up source.
  transfer: 'linear',      // see output section
  output: myStorageTex,    // optional caller-owned destination
});
if (!outTex) return;      // aborted mid-flight (e.g. camera moved)

Returns GPUTexture — your output if given, else an engine-owned rgba8unorm texture valid until the next call / size change / teardown — or undefined if abort() was called mid-run.

See the API reference for the exhaustive, always-current version of this table.

Call without output; blit or sample the returned rgba8unorm texture. With transfer: 'aces-srgb' it's display-ready — e.g. copy straight to a canvas:

ctx.configure({ device: denoiser.device, format: 'rgba8unorm',
                usage: GPUTextureUsage.COPY_DST | GPUTextureUsage.RENDER_ATTACHMENT });
const enc = denoiser.device.createCommandEncoder();
enc.copyTextureToTexture({ texture: outTex }, { texture: ctx.getCurrentTexture() },
                         { width: outTex.width, height: outTex.height });
denoiser.device.queue.submit([enc.finish()]);

Remember it's reused: copy it out (or render it) before the next denoiseTextures call.

Create a StorageTexture, register it with the renderer, unwrap it, and pass it as output. Then it's an ordinary three.js texture — feed it to materials, post-processing (the example's @pmndrs/upscaler FSR1 pass reads it), anything:

const denoisedTex = new THREE.StorageTexture(W, H);
denoisedTex.type = THREE.HalfFloatType;          // rgba16float: unclamped linear HDR
denoisedTex.colorSpace = THREE.LinearSRGBColorSpace;
denoisedTex.generateMipmaps = false;
renderer.initTexture(denoisedTex);               // materialize the GPU resource

const denoisedGpuTex = backendGet(denoisedTex)!; // pass as `output:`

Pick transfer to match who does color management:

The pattern from the example's live mode:

let busy = false;
async function maybeDenoise() {
  if (busy) return;
  busy = true;
  try { await runDenoise(); } finally { busy = false; }
}
controls.addEventListener('change', () => denoiser.abort()); // stale view -> drop result

abort() doesn't cancel GPU work already submitted; it makes the in-flight call resolve undefined so you never present a result for an outdated camera. denoiser.stats has per-stage timings of the last run for HUDs.

For the TSL nodes (denoise(), ffxShadows(), ffxReflections()) that wrap this flow, see three.js & TSL.

More failure modes (black output from a device mismatch, CORS, device-lost) are covered in Troubleshooting.

Live: three-pathtracer-webgpu · ldraw-eiffel