Skip to content

Code-first video & image, rendered natively on WebGPU.

11.8 KB
Raw Blame
import { createHash } from "node:crypto";
import { statSync } from "node:fs";
import {
	type DecodedHdrImage,
	decodeHdrSource,
	downsampleEquirect,
	floatRgbaToHalf16,
	projectIrradianceSh,
} from "../loaders/hdr-loader.js";

/** A captured panorama, ready for image-based lighting. */
export interface HdrEnvironment {
	/**
	 * GGX-prefiltered radiance cubemap: mip `m` holds the panorama as a surface
	 * of perceptual roughness `m / (mipLevelCount - 1)` reflects it.
	 */
	cube: GPUTexture;
	faceSize: number;
	mipLevelCount: number;
	/** Diffuse irradiance as 9 L2 SH coefficients (`projectIrradianceSh`). */
	sh: Float32Array;
}

/** Most environments kept resident per device; the least recently used is destroyed. */
export const MAX_HDR_CACHE_ENTRIES = 8;
/** Largest cube face; finer than this adds memory, not visible detail. */
const MAX_FACE_SIZE = 256;
/** Roughest level is 4×4: GGX at roughness 1 has nothing finer to show. */
const MAX_CUBE_MIPS = 7;
/** Importance samples per texel for every rough level. */
const PREFILTER_SAMPLES = 256;

const deviceCaches = new WeakMap<GPUDevice, Map<string, HdrEnvironment>>();
/** Stable keys for in-memory sources, so the same object never hashes twice. */
const objectKeys = new WeakMap<object, string>();

export const hdrPrefilterWgsl = /* wgsl */ `
const PI = 3.14159265359;

struct Params {
    faceSize : u32,
    sampleCount : u32,
    roughness : f32,
    srcMaxLod : f32,
    srcTexelSolidAngle : f32,
    cubeTexelSolidAngle : f32,
};

@group(0) @binding(0) var src : texture_2d<f32>;
@group(0) @binding(1) var srcSampler : sampler;
@group(0) @binding(2) var dst : texture_storage_2d_array<rgba16float, write>;
@group(0) @binding(3) var<uniform> params : Params;

// WebGPU cube face orientation: s right, t down, both in -1..1.
fn faceDirection(face : u32, s : f32, t : f32) -> vec3<f32> {
    switch face {
        case 0u: { return vec3<f32>(1.0, -t, -s); }
        case 1u: { return vec3<f32>(-1.0, -t, s); }
        case 2u: { return vec3<f32>(s, 1.0, t); }
        case 3u: { return vec3<f32>(s, -1.0, -t); }
        case 4u: { return vec3<f32>(s, -t, 1.0); }
        default: { return vec3<f32>(-s, -t, -1.0); }
    }
}

// Same mapping as equirectDirection (y down, u = 0.5 looks down -z).
fn equirectUv(d : vec3<f32>) -> vec2<f32> {
    let u = fract(atan2(d.x, -d.z) / (2.0 * PI) + 0.5);
    let v = acos(clamp(-d.y, -1.0, 1.0)) / PI;
    return vec2<f32>(u, v);
}

fn sampleSource(d : vec3<f32>, lod : f32) -> vec3<f32> {
    return textureSampleLevel(src, srcSampler, equirectUv(d), clamp(lod, 0.0, params.srcMaxLod)).rgb;
}

fn radicalInverse(i : u32) -> f32 {
    var b = (i << 16u) | (i >> 16u);
    b = ((b & 0x55555555u) << 1u) | ((b & 0xAAAAAAAAu) >> 1u);
    b = ((b & 0x33333333u) << 2u) | ((b & 0xCCCCCCCCu) >> 2u);
    b = ((b & 0x0F0F0F0Fu) << 4u) | ((b & 0xF0F0F0F0u) >> 4u);
    b = ((b & 0x00FF00FFu) << 8u) | ((b & 0xFF00FF00u) >> 8u);
    return f32(b) * 2.3283064365386963e-10;
}

@compute @workgroup_size(8, 8, 1)
fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
    let size = params.faceSize;
    if (gid.x >= size || gid.y >= size) {
        return;
    }
    let st = (vec2<f32>(gid.xy) + 0.5) / f32(size) * 2.0 - 1.0;
    let N = normalize(faceDirection(gid.z, st.x, st.y));
    // A mirror level resamples the panorama at the cube's own footprint.
    let mirrorLod = 0.5 * log2(params.cubeTexelSolidAngle / params.srcTexelSolidAngle);
    if (params.roughness <= 0.0) {
        textureStore(dst, gid.xy, gid.z, vec4<f32>(sampleSource(N, mirrorLod), 1.0));
        return;
    }

    // Split-sum prefilter (Karis 2013) with view = normal, filtered importance
    // sampling (Krivanek & Colbert 2008) to keep few samples noise-free.
    let a = params.roughness * params.roughness;
    let a2 = a * a;
    let up = select(vec3<f32>(1.0, 0.0, 0.0), vec3<f32>(0.0, 1.0, 0.0), abs(N.y) < 0.999);
    let T = normalize(cross(up, N));
    let B = cross(N, T);
    var sum = vec3<f32>(0.0);
    var weight = 0.0;
    let n = params.sampleCount;
    for (var i = 0u; i < n; i++) {
        let xi = vec2<f32>(f32(i) / f32(n), radicalInverse(i));
        let phi = 2.0 * PI * xi.x;
        let cosTheta = sqrt((1.0 - xi.y) / (1.0 + (a2 - 1.0) * xi.y));
        let sinTheta = sqrt(1.0 - cosTheta * cosTheta);
        let H = normalize(T * (sinTheta * cos(phi)) + B * (sinTheta * sin(phi)) + N * cosTheta);
        let L = 2.0 * dot(N, H) * H - N;
        let nDotL = dot(N, L);
        if (nDotL <= 0.0) {
            continue;
        }
        let nDotH = max(dot(N, H), 0.0);
        let dDen = nDotH * nDotH * (a2 - 1.0) + 1.0;
        let D = a2 / (PI * dDen * dDen);
        // pdf(L) = D * nDotH / (4 vDotH), and vDotH = nDotH with V = N.
        let pdf = max(D * 0.25, 1e-6);
        let sampleSolidAngle = 1.0 / (f32(n) * pdf);
        let lod = 0.5 * log2(sampleSolidAngle / params.srcTexelSolidAngle) + 1.0;
        sum += sampleSource(L, lod) * nDotL;
        weight += nDotL;
    }
    textureStore(dst, gid.xy, gid.z, vec4<f32>(sum / max(weight, 1e-6), 1.0));
}
`;

interface PrefilterResources {
	pipeline: GPUComputePipeline;
	layout: GPUBindGroupLayout;
	sampler: GPUSampler;
}

const prefilterResources = new WeakMap<GPUDevice, PrefilterResources>();

function getPrefilterResources(device: GPUDevice): PrefilterResources {
	const cached = prefilterResources.get(device);
	if (cached) return cached;
	const layout = device.createBindGroupLayout({
		label: "HdrPrefilterLayout",
		entries: [
			{
				binding: 0,
				visibility: GPUShaderStage.COMPUTE,
				texture: { sampleType: "float" },
			},
			{
				binding: 1,
				visibility: GPUShaderStage.COMPUTE,
				sampler: { type: "filtering" },
			},
			{
				binding: 2,
				visibility: GPUShaderStage.COMPUTE,
				storageTexture: {
					access: "write-only",
					format: "rgba16float",
					viewDimension: "2d-array",
				},
			},
			{
				binding: 3,
				visibility: GPUShaderStage.COMPUTE,
				buffer: { type: "uniform" },
			},
		],
	});
	const pipeline = device.createComputePipeline({
		label: "HdrPrefilterPipeline",
		layout: device.createPipelineLayout({ bindGroupLayouts: [layout] }),
		compute: {
			module: device.createShaderModule({
				label: "HdrPrefilterShader",
				code: hdrPrefilterWgsl,
			}),
			entryPoint: "main",
		},
	});
	const sampler = device.createSampler({
		label: "HdrPrefilterSampler",
		magFilter: "linear",
		minFilter: "linear",
		mipmapFilter: "linear",
		addressModeU: "repeat",
		addressModeV: "clamp-to-edge",
	});
	const res = { pipeline, layout, sampler };
	prefilterResources.set(device, res);
	return res;
}

/** Uploads the panorama with a full mip chain, the prefilter's sampling source. */
function uploadEquirect(device: GPUDevice, image: DecodedHdrImage): GPUTexture {
	const mipLevelCount =
		Math.floor(Math.log2(Math.max(image.width, image.height))) + 1;
	const texture = device.createTexture({
		label: "HdrEquirectSource",
		size: { width: image.width, height: image.height },
		mipLevelCount,
		format: "rgba16float",
		usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST,
	});
	let level = image;
	for (let mip = 0; mip < mipLevelCount; mip++) {
		device.queue.writeTexture(
			{ texture, mipLevel: mip },
			floatRgbaToHalf16(level.data),
			{ bytesPerRow: level.width * 8, rowsPerImage: level.height },
			{ width: level.width, height: level.height },
		);
		if (mip + 1 < mipLevelCount) level = downsampleEquirect(level);
	}
	return texture;
}

/** Cube face size for a panorama: about a quarter of its width, a power of two. */
export function cubeFaceSize(panoramaWidth: number): number {
	const quarter = Math.max(1, panoramaWidth / 4);
	return Math.max(
		8,
		Math.min(MAX_FACE_SIZE, 2 ** Math.floor(Math.log2(quarter))),
	);
}

/** Prefilters an equirectangular panorama into a GGX radiance cubemap on the GPU. */
function prefilterCube(
	device: GPUDevice,
	image: DecodedHdrImage,
	label: string,
): { cube: GPUTexture; faceSize: number; mipLevelCount: number } {
	const { pipeline, layout, sampler } = getPrefilterResources(device);
	const source = uploadEquirect(device, image);
	const faceSize = cubeFaceSize(image.width);
	const mipLevelCount = Math.min(
		MAX_CUBE_MIPS,
		Math.floor(Math.log2(faceSize)) - 1,
	);
	const cube = device.createTexture({
		label: `HdrEnvironmentCube:${label}`,
		size: { width: faceSize, height: faceSize, depthOrArrayLayers: 6 },
		mipLevelCount,
		format: "rgba16float",
		// COPY_SRC lets tools and tests read the prefiltered levels back.
		usage:
			GPUTextureUsage.TEXTURE_BINDING |
			GPUTextureUsage.STORAGE_BINDING |
			GPUTextureUsage.COPY_SRC,
	});
	const srcTexelSolidAngle = (4 * Math.PI) / (image.width * image.height);
	const sourceView = source.createView();
	const buffers: GPUBuffer[] = [];
	const encoder = device.createCommandEncoder({ label: "HdrPrefilter" });
	const pass = encoder.beginComputePass({ label: "HdrPrefilterPass" });
	pass.setPipeline(pipeline);
	for (let mip = 0; mip < mipLevelCount; mip++) {
		const size = Math.max(1, faceSize >> mip);
		const params = new ArrayBuffer(32);
		const u32 = new Uint32Array(params);
		const f32 = new Float32Array(params);
		u32[0] = size;
		u32[1] = PREFILTER_SAMPLES;
		f32[2] = mipLevelCount > 1 ? mip / (mipLevelCount - 1) : 0;
		f32[3] = source.mipLevelCount - 1;
		f32[4] = srcTexelSolidAngle;
		f32[5] = (4 * Math.PI) / (6 * size * size);
		const buffer = device.createBuffer({
			label: `HdrPrefilterParams${mip}`,
			size: params.byteLength,
			usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
		});
		device.queue.writeBuffer(buffer, 0, params);
		buffers.push(buffer);
		pass.setBindGroup(
			0,
			device.createBindGroup({
				layout,
				entries: [
					{ binding: 0, resource: sourceView },
					{ binding: 1, resource: sampler },
					{
						binding: 2,
						resource: cube.createView({
							dimension: "2d-array",
							baseMipLevel: mip,
							mipLevelCount: 1,
						}),
					},
					{ binding: 3, resource: { buffer } },
				],
			}),
		);
		const groups = Math.ceil(size / 8);
		pass.dispatchWorkgroups(groups, groups, 6);
	}
	pass.end();
	device.queue.submit([encoder.finish()]);
	// Freed once the submitted prefilter has run.
	source.destroy();
	for (const b of buffers) b.destroy();
	return { cube, faceSize, mipLevelCount };
}

function contentKey(source: Uint8Array | DecodedHdrImage): string {
	const known = objectKeys.get(source);
	if (known) return known;
	const hash = createHash("sha1");
	if (source instanceof Uint8Array) {
		hash.update(source);
	} else {
		hash.update(`${source.width}x${source.height}`);
		hash.update(
			new Uint8Array(
				source.data.buffer,
				source.data.byteOffset,
				source.data.byteLength,
			),
		);
	}
	const key = `sha1:${hash.digest("hex")}`;
	objectKeys.set(source, key);
	return key;
}

/**
 * The prefiltered cubemap and irradiance SH for a `.hdr` path, its bytes or a
 * decoded panorama, built once per device. A bounded LRU destroys evicted
 * cubemaps so long renders never leak VRAM; a path keys on its modification
 * time too, so an edited panorama reloads.
 */
export function getOrCreateHdrEnvironment(
	device: GPUDevice,
	source: string | Uint8Array | DecodedHdrImage,
	cacheKey?: string,
): HdrEnvironment {
	const key =
		cacheKey ??
		(typeof source === "string"
			? `${source}@${statSync(source).mtimeMs}`
			: contentKey(source));
	let map = deviceCaches.get(device);
	if (!map) {
		map = new Map();
		deviceCaches.set(device, map);
	}
	const existing = map.get(key);
	if (existing) {
		map.delete(key);
		map.set(key, existing);
		return existing;
	}
	const image =
		typeof source === "string" || source instanceof Uint8Array
			? decodeHdrSource(source)
			: source;
	const entry: HdrEnvironment = {
		...prefilterCube(device, image, key),
		sh: projectIrradianceSh(image),
	};
	if (map.size >= MAX_HDR_CACHE_ENTRIES) {
		const oldest = map.keys().next().value;
		if (oldest !== undefined) {
			map.get(oldest)?.cube.destroy();
			map.delete(oldest);
		}
	}
	map.set(key, entry);
	return entry;
}