3D engine that AI agents drive
Trace the subsurface block in the GPU path tracer, compiled in only for scenes that use it (part of #302)
Nguyen Xuan Anb1b9e0100aa2
diff --git a/changes/283-gpu-tracer.md b/changes/283-gpu-tracer.mdnew file mode 100644index 00000000..f16b5820--- /dev/null+++ b/changes/283-gpu-tracer.md@@ -0,0 +1 @@+- The GPU path tracer traces the material `subsurface` block (issue #283 follow-up, part of #302): the same bounded random walk as the CPU tracer, compiled into the kernel only for a scene with a part whose weight is above 0, with the block in its own two-texel-per-material table. A scene without one compiles and renders the kernel it always did. Scored against the Cycles render of `subsurface`, see `docs/path-tracer.md`.diff --git a/changes/283-gpu-tracer.size.md b/changes/283-gpu-tracer.size.mdnew file mode 100644index 00000000..0adc5e97--- /dev/null+++ b/changes/283-gpu-tracer.size.md@@ -0,0 +1,2 @@+- entry:path-tracer: grows by about 460 bytes gzip for the GPU subsurface kernel pieces (path-tracer-gpu-subsurface.js) and the block packing; the GPU tracer is a dynamic import of the path-tracer addon and no core entry grows.+- entry:path-tracer+lazy: the same bytes.diff --git a/src/path-tracer-gpu-pack.js b/src/path-tracer-gpu-pack.jsindex 9f67454d..e231ba44 100644--- a/src/path-tracer-gpu-pack.js+++ b/src/path-tracer-gpu-pack.js@@ -1,4 +1,5 @@import { DATA_TEXTURE_WIDTH, TRIANGLE_TEXELS, MATERIAL_TEXELS, LIGHT_TEXELS } from './path-tracer-gpu-shader.js';+import { SUBSURFACE_TEXELS } from './path-tracer-gpu-subsurface.js';// Lays a traced scene (path-tracer-scene.js) out as the float textures the GPU kernel reads. Everything here is plain// typed arrays, so it runs and is tested without a GPU. Each table is a run of RGBA texels, DATA_TEXTURE_WIDTH to a row.@@ -130,6 +131,28 @@ export function packMaterials(materials, atlas) {return table;}+/** True when a part has a subsurface weight above 0, which is when the kernel needs the random walk. */+export function sceneUsesSubsurface(materials) {+ return materials.some(material => material.subsurface);+}++/**+ * Two texels per material: (weight, mean free path in metres for red, green and blue) and (colour, unused). The colour red is+ * -1 for the base colour. A material without a block packs a weight of 0, which the kernel treats as the unchanged path.+ */+export function packSubsurface(materials) {+ const table = createTable(materials.length * SUBSURFACE_TEXELS);+ const { data } = table;+ materials.forEach((material, index) => {+ const base = index * SUBSURFACE_TEXELS * 4;+ const block = material.subsurface;+ if (!block) return;+ data.set([block.weight, ...block.meanFreePath], base);+ data.set([...(block.color ?? [-1, -1, -1]), 0], base + 4);+ });+ return table;+}+const LIGHT_TYPES = { point: 0, spot: 1, area: 2 };/** Six texels per point, spot or area light, in the order the tracer samples them. */diff --git a/src/path-tracer-gpu-shader.js b/src/path-tracer-gpu-shader.jsindex 98303599..78fb4f3d 100644--- a/src/path-tracer-gpu-shader.js+++ b/src/path-tracer-gpu-shader.js@@ -1,3 +1,5 @@+import { SUBSURFACE_FUNCTIONS, SUBSURFACE_LOBE, SUBSURFACE_SPLIT, SUBSURFACE_UNIFORM } from './path-tracer-gpu-subsurface.js';+// The GPU path tracer kernel: a WebGL2 fragment shader that follows the same paths as the CPU tracer in// path-tracer.js. It reads the BVH, triangles, materials, lights and environment from float textures// (path-tracer-gpu-pack.js), draws the same random numbers in the same order, and writes one sample per pixel into four@@ -15,7 +17,7 @@ void main() {gl_Position = vec4(corner * 2.0 - 1.0, 0.0, 1.0);}`;-const SHARED_SOURCE = `#version 300 es+const buildSource = hasSubsurface => `#version 300 esprecision highp float;precision highp int;precision highp sampler2D;@@ -69,7 +71,7 @@ uniform vec3 uVolumeMinimum;uniform vec3 uVolumeMaximum;uniform vec3 uVolumeAlbedo;uniform vec3 uVolumeShape;-+${hasSubsurface ? SUBSURFACE_UNIFORM : ''}layout(location = 0) out vec4 outRadiance;layout(location = 1) out vec4 outAlbedo;layout(location = 2) out vec4 outNormal;@@ -217,6 +219,7 @@ float hitClearcoatRoughness;float hitTransmission;float hitIor;float hitCutoff;+int hitMaterialIndex;uint hitMask;vec3 srgbToLinear(vec3 encoded) {@@ -301,7 +304,8 @@ float fillHit(vec3 origin, vec3 direction, float distance) {hitNormal = normal / (normalLength == 0.0 ? 1.0 : normalLength);vec3 vertexColor = firstWeight * colorOneData.xyz + secondWeight * colorTwoData.xyz + thirdWeight * colorThreeData.xyz;vec2 uv = firstWeight * vec2(normalOneData.w, colorOneData.w) + secondWeight * vec2(normalTwoData.w, colorTwoData.w) + thirdWeight * vec2(normalThreeData.w, colorThreeData.w);- int material = int(cornerData.w) * MATERIAL_TEXELS;+ hitMaterialIndex = int(cornerData.w);+ int material = hitMaterialIndex * MATERIAL_TEXELS;vec4 colorMetallic = fetchData(uMaterials, material);vec4 emissionRoughness = fetchData(uMaterials, material + 1);vec4 coating = fetchData(uMaterials, material + 2);@@ -549,6 +553,7 @@ float surfaceCoatChance;bool surfaceSampledCoat;float surfaceCoatAlpha;float surfaceDiffuseChance;+float surfaceDiffuseShare;float surfaceSpecularChance;vec3 surfaceValue;float surfacePdf;@@ -573,6 +578,7 @@ void prepareSurface(vec3 normal, vec3 view) {float underCoat = 1.0 - surfaceCoatWeight;float diffuseShare = (1.0 - hitMetallic) * (1.0 - dielectricFresnel) * underCoat;surfaceDiffuse = hitColor * diffuseShare;+ surfaceDiffuseShare = diffuseShare;surfaceSpecularNormal = vec3(dielectricNormalReflectance * (1.0 - hitMetallic)) + hitColor * hitMetallic;float specularLuminance = luminance(surfaceSpecularNormal);surfaceSpecularWeight = underCoat;@@ -928,6 +934,7 @@ bool scatterInFog(vec3 origin, float segmentLength) {return true;}+${hasSubsurface ? SUBSURFACE_FUNCTIONS : ''}void tracePath(vec3 origin, vec3 startDirection, uint pixel, uint sampleIndex) {resetRandom(pixel, sampleIndex, uSeed);radiance = vec3(0.0);@@ -966,7 +973,10 @@ void tracePath(vec3 origin, vec3 startDirection, uint pixel, uint sampleIndex) {}addRadiance(depth, throughput * hitEmission);needsLights = !isGlass;- if (needsLights) prepareSurface(normal, -direction);+ if (needsLights) {+ prepareSurface(normal, -direction);+${hasSubsurface ? SUBSURFACE_SPLIT : ''}+ }}if (needsLights) addLights(depth, normal);inMedium = false;@@ -994,6 +1004,7 @@ void tracePath(vec3 origin, vec3 startDirection, uint pixel, uint sampleIndex) {afterMirror = true;} else {float lobeUnit = nextRandom();+${hasSubsurface ? SUBSURFACE_LOBE : ''}float firstUnit = nextRandom();float secondUnit = nextRandom();vec3 sampledDirection;@@ -1042,4 +1053,9 @@ void main() {}`;-export const FRAGMENT_SOURCE = SHARED_SOURCE;+/** The kernel; `hasSubsurface` compiles in the random walk, which only scenes with a subsurface part need. */+export function buildFragmentSource({ hasSubsurface = false } = {}) {+ return buildSource(hasSubsurface);+}++export const FRAGMENT_SOURCE = buildFragmentSource();diff --git a/src/path-tracer-gpu-subsurface.js b/src/path-tracer-gpu-subsurface.jsnew file mode 100644index 00000000..c9750f66--- /dev/null+++ b/src/path-tracer-gpu-subsurface.js@@ -0,0 +1,135 @@+import { SUBSURFACE_WALK_STEPS } from './path-tracer-subsurface.js';++// The subsurface random walk of the CPU tracer (path-tracer-subsurface.js and enterSubsurface in path-tracer.js) as GLSL+// pieces. path-tracer-gpu-shader.js splices them into the kernel only for a scene with a part whose subsurface weight is+// above 0, so every other scene compiles the kernel it always did. The per-material block sits in the uSubsurface table+// (path-tracer-gpu-pack.js): two texels per material, (weight, mean free path red, green, blue) and (colour, unused), where+// a colour red of -1 means the base colour.++export const SUBSURFACE_TEXELS = 2;++export const SUBSURFACE_UNIFORM = `+uniform sampler2D uSubsurface;+`;++// Runs right after prepareSurface() and before addLights(), as splitSubsurface() does on the CPU.+export const SUBSURFACE_SPLIT = `+ subsurfaceWeight = splitSubsurface();`;++// Runs right after the lobe unit is drawn, as the subsurface branch of trace() does on the CPU.+export const SUBSURFACE_LOBE = `+ if (subsurfaceWeight > 0.0) {+ if (lobeUnit < surfaceSubsurfaceChance) {+ if (!enterSubsurface(depth, normal)) break;+ lobeUnit = 0.0;+ } else {+ lobeUnit -= surfaceSubsurfaceChance;+ }+ }`;++export const SUBSURFACE_FUNCTIONS = `+// ---- Subsurface random walk ----++const int WALK_STEPS = ${SUBSURFACE_WALK_STEPS};+const int WALK_EXIT = 0;+const int WALK_THIN = 1;+const int WALK_LOST = 2;+const int SUBSURFACE_TEXELS = ${SUBSURFACE_TEXELS};++float subsurfaceWeight = 0.0;+float surfaceSubsurfaceChance = 0.0;+vec3 walkWeight;+vec3 walkDirection;++/** Moves the subsurface share of the diffuse lobe to the walk; returns the material's weight. */+float splitSubsurface() {+ float weight = fetchData(uSubsurface, hitMaterialIndex * SUBSURFACE_TEXELS).x;+ surfaceSubsurfaceChance = surfaceDiffuseChance * weight;+ surfaceDiffuseChance -= surfaceSubsurfaceChance;+ surfaceDiffuse *= 1.0 - weight;+ return weight;+}++float singleScatterAlbedo(float multipleScatterAlbedo) {+ float albedo = clamp(multipleScatterAlbedo, 0.0, 1.0);+ float root = sqrt(9.59217 + 41.6808 * albedo + 17.7126 * albedo * albedo);+ float offset = 4.09712 + 4.20863 * albedo - root;+ return clamp(1.0 - offset * offset, 0.0, 1.0);+}++/** Walks inward from the entry point until the walk meets the part's own surface; leaves its throughput in walkWeight. */+int randomWalk(vec3 point, vec3 normal, vec3 meanFreePath, vec3 color, int material) {+ vec3 extinction = 1.0 / meanFreePath;+ vec3 albedo = vec3(singleScatterAlbedo(color.r), singleScatterAlbedo(color.g), singleScatterAlbedo(color.b));+ vec3 position = point - normal * uSurfaceOffset;+ mat3 frame = buildFrame(normal);+ float radius = sqrt(nextRandom());+ float angle = TWO_PI * nextRandom();+ float height = sqrt(max(0.0, 1.0 - radius * radius));+ walkDirection = frame[0] * (radius * cos(angle)) + frame[1] * (radius * sin(angle)) - normal * height;+ for (int scatters = 0; scatters <= WALK_STEPS; scatters++) {+ bool found = intersectScene(position, walkDirection);+ if (!found || hitMaterialIndex != material) return scatters == 0 ? WALK_THIN : WALK_LOST;+ // One channel draws the distance; weighting by the mean density over the three channels keeps every channel unbiased.+ int hero = min(2, int(floor(nextRandom() * 3.0)));+ float distance = -log(1.0 - nextRandom()) / extinction[hero];+ if (distance >= hitDistance) {+ vec3 attenuation = exp(-extinction * hitDistance);+ float survival = (attenuation.x + attenuation.y + attenuation.z) / 3.0;+ if (!(survival > 0.0)) return WALK_LOST;+ walkWeight *= attenuation / survival;+ return WALK_EXIT;+ }+ if (scatters == WALK_STEPS) return WALK_LOST;+ vec3 falloff = exp(-extinction * distance);+ vec3 scatterDensity = extinction * falloff;+ float density = (scatterDensity.x + scatterDensity.y + scatterDensity.z) / 3.0;+ if (!(density > 0.0)) return WALK_LOST;+ walkWeight *= albedo * scatterDensity / density;+ position += walkDirection * distance;+ float up = 2.0 * nextRandom() - 1.0;+ float azimuth = TWO_PI * nextRandom();+ float ring = sqrt(max(0.0, 1.0 - up * up));+ walkDirection = vec3(ring * cos(azimuth), up, ring * sin(azimuth));+ }+ return WALK_LOST;+}++/**+ * Sends the diffuse light of the hit through its walk. On success the path stands where the walk left (or, for a card with+ * nothing behind it, on the near or far face), normal faces out of that point, the surface is white diffuse there with its+ * lights added, and the throughput carries the walk. False when the walk ended inside the part.+ */+bool enterSubsurface(int depth, inout vec3 normal) {+ vec4 block = fetchData(uSubsurface, hitMaterialIndex * SUBSURFACE_TEXELS);+ vec4 colorBlock = fetchData(uSubsurface, hitMaterialIndex * SUBSURFACE_TEXELS + 1);+ vec3 color = colorBlock.x < 0.0 ? hitColor : colorBlock.rgb;+ int material = hitMaterialIndex;+ vec3 entryPoint = hitPoint;+ uint entryMask = hitMask;+ float entryScale = surfaceDiffuseShare * block.x / surfaceSubsurfaceChance;+ walkWeight = vec3(1.0);+ int outcome = randomWalk(entryPoint, normal, block.yzw, color, material);+ if (outcome == WALK_LOST) return false;+ if (outcome == WALK_EXIT) {+ // The exit hit is the tracer's hit now: its point and (flipped to face out of the part) its normal.+ normal = hitNormal * (dot(hitNormal, walkDirection) < 0.0 ? -1.0 : 1.0);+ throughput *= walkWeight * entryScale;+ } else {+ // A card: half of the colour is reflected on the side the ray came from and half is transmitted diffusely through it.+ hitPoint = entryPoint;+ hitMask = entryMask;+ if (nextRandom() < 0.5) normal = -normal;+ throughput *= color * entryScale;+ }+ surfaceFrame = buildFrame(normal);+ surfaceDiffuse = vec3(1.0);+ surfaceDiffuseChance = 1.0;+ surfaceSubsurfaceChance = 0.0;+ surfaceSpecularChance = 0.0;+ surfaceCoatChance = 0.0;+ surfaceCoatWeight = 0.0;+ addLights(depth, normal);+ return true;+}+`;diff --git a/src/path-tracer-gpu.js b/src/path-tracer-gpu.jsindex c05ccf2a..daa3f003 100644--- a/src/path-tracer-gpu.js+++ b/src/path-tracer-gpu.js@@ -1,5 +1,5 @@-import { FRAGMENT_SOURCE, VERTEX_SOURCE } from './path-tracer-gpu-shader.js';-import { packAtlas, packEnvironment, packLights, packMaterials, packNodes, packTriangles } from './path-tracer-gpu-pack.js';+import { buildFragmentSource, VERTEX_SOURCE } from './path-tracer-gpu-shader.js';+import { packAtlas, packEnvironment, packLights, packMaterials, packNodes, packSubsurface, packTriangles, sceneUsesSubsurface } from './path-tracer-gpu-pack.js';// The GPU backend of the path tracer: one WebGL2 fragment pass per sample draws every pixel of a band, and four float// targets add the samples up. It needs a page with WebGL2 (a canvas), EXT_color_buffer_float and EXT_float_blend. The@@ -34,10 +34,10 @@ function compileShader(gl, type, source) {return shader;}-function createProgram(gl) {+function createProgram(gl, hasSubsurface) {const program = gl.createProgram();gl.attachShader(program, compileShader(gl, gl.VERTEX_SHADER, VERTEX_SOURCE));- gl.attachShader(program, compileShader(gl, gl.FRAGMENT_SHADER, FRAGMENT_SOURCE));+ gl.attachShader(program, compileShader(gl, gl.FRAGMENT_SHADER, buildFragmentSource({ hasSubsurface })));gl.linkProgram(program);if (!gl.getProgramParameter(program, gl.LINK_STATUS)) throw new Error(`The GPU path tracer program did not link: ${gl.getProgramInfoLog(program)}`);return program;@@ -69,6 +69,8 @@ function uploadScene(gl, program, scene) {const triangles = packTriangles(scene);const materials = packMaterials(scene.materials, atlas);const floatTables = [['uNodes', nodes], ['uTriangles', triangles], ['uMaterials', materials], ['uLights', lights.table]];+ if (sceneUsesSubsurface(scene.materials)) floatTables.push(['uSubsurface', packSubsurface(scene.materials)]);+ if (sceneUsesSubsurface(scene.materials)) floatTables.push(['uSubsurface', packSubsurface(scene.materials)]);let unit = 0;const bind = (name) => gl.uniform1i(gl.getUniformLocation(program, name), unit++);for (const [name, table] of floatTables) {@@ -179,20 +181,29 @@ const nextTask = () => new Promise(resolve => setTimeout(resolve, 0));* (color, albedo, normal, depth, variance, samplesTaken) plus a `gpu` note. `noiseThreshold` is not used: every pixel* draws all its samples. `shouldStop` throws when the time limit passes.*/-function getSession() {+function getContext() {if (session) return session;const canvas = createCanvas();const gl = canvas?.getContext('webgl2', { antialias: false, depth: false, stencil: false, alpha: false, powerPreference: 'high-performance' });if (!gl) throw new Error('The GPU path tracer needs WebGL2.');if (!gl.getExtension('EXT_color_buffer_float') || !gl.getExtension('EXT_float_blend')) throw new Error('The GPU path tracer needs float render targets with blending.');- const started = performance.now();- const program = createProgram(gl);- gl.getProgramParameter(program, gl.LINK_STATUS);const debugInfo = gl.getExtension('WEBGL_debug_renderer_info');- session = { gl, program, compileSeconds: (performance.now() - started) / 1000, gpu: debugInfo ? gl.getParameter(debugInfo.UNMASKED_RENDERER_WEBGL) : 'unknown' };+ session = { gl, programs: new Map(), gpu: debugInfo ? gl.getParameter(debugInfo.UNMASKED_RENDERER_WEBGL) : 'unknown' };return session;}+/** The kernel for a scene, compiled once per variant: a scene with a subsurface part gets the random walk, any other scene the plain kernel. */+function getKernel(hasSubsurface) {+ const { gl, programs } = getContext();+ if (!programs.has(hasSubsurface)) {+ const started = performance.now();+ const program = createProgram(gl, hasSubsurface);+ gl.getProgramParameter(program, gl.LINK_STATUS);+ programs.set(hasSubsurface, { program, compileSeconds: (performance.now() - started) / 1000 });+ }+ return programs.get(hasSubsurface);+}+function releaseResources(gl) {for (const resource of resources) {if (resource instanceof WebGLFramebuffer) gl.deleteFramebuffer(resource);@@ -202,7 +213,8 @@ function releaseResources(gl) {}export async function traceOnGpu(scene, camera, options, shouldStop) {- const { gl, program, compileSeconds, gpu } = getSession();+ const { gl, gpu } = getContext();+ const { program, compileSeconds } = getKernel(sceneUsesSubsurface(scene.materials));const { width, height, samples } = options;gl.useProgram(program);const { lightCount } = uploadScene(gl, program, scene);diff --git a/tests/path-tracer-gpu-pack.test.js b/tests/path-tracer-gpu-pack.test.jsindex 7dd460e8..de81fb99 100644--- a/tests/path-tracer-gpu-pack.test.js+++ b/tests/path-tracer-gpu-pack.test.js@@ -2,8 +2,9 @@ import assert from 'node:assert/strict';import test from 'node:test';import { buildTraceScene } from '../src/path-tracer-scene.js';-import { packAtlas, packLights, packMaterials, packNodes, packTriangles } from '../src/path-tracer-gpu-pack.js';-import { LIGHT_TEXELS, MATERIAL_TEXELS, TRIANGLE_TEXELS } from '../src/path-tracer-gpu-shader.js';+import { packAtlas, packLights, packMaterials, packNodes, packSubsurface, packTriangles, sceneUsesSubsurface } from '../src/path-tracer-gpu-pack.js';+import { buildFragmentSource, FRAGMENT_SOURCE, LIGHT_TEXELS, MATERIAL_TEXELS, TRIANGLE_TEXELS } from '../src/path-tracer-gpu-shader.js';+import { SUBSURFACE_TEXELS } from '../src/path-tracer-gpu-subsurface.js';function quad(offset) {return {@@ -90,3 +91,39 @@ test('lights are packed as points, then spots, then areas', () => {assert.equal(table.data[LIGHT_TEXELS * 4 + 11], 0.5, 'area width');assert.equal(table.data[20], 4, 'point intensity');});++function subsurfaceScene(weight) {+ const parts = [+ { name: 'wax', geometry: quad(0), material: { color: [0.8, 0.6, 0.4], subsurface: { weight, radius: [1, 0.5, 0.25], scale: 0.02, color: [0.9, 0.5, 0.2] } } },+ { name: 'stone', geometry: quad(2), material: { color: [0.5, 0.5, 0.5], subsurface: { weight, radius: [1, 1, 1], scale: 0.1 } } },+ { name: 'plain', geometry: quad(3), material: { color: [1, 1, 1] } },+ ];+ return buildTraceScene(parts, { keyColor: [1, 1, 1], lightDirection: [0, 1, 0] });+}++test('the subsurface block is packed as two texels per material, with -1 for the base colour', () => {+ const scene = subsurfaceScene(0.75);+ assert.equal(sceneUsesSubsurface(scene.materials), true);+ const table = packSubsurface(scene.materials);+ const wax = scene.materials.findIndex(material => material.subsurface?.color);+ const stone = scene.materials.findIndex(material => material.subsurface && !material.subsurface.color);+ const plain = scene.materials.findIndex(material => !material.subsurface);+ const waxBase = wax * SUBSURFACE_TEXELS * 4;+ assert.deepEqual([...table.data.subarray(waxBase, waxBase + 4)].map(value => Number(value.toFixed(5))), [0.75, 0.02, 0.01, 0.005]);+ assert.deepEqual([...table.data.subarray(waxBase + 4, waxBase + 8)].map(value => Number(value.toFixed(5))), [0.9, 0.5, 0.2, 0]);+ assert.equal(table.data[stone * SUBSURFACE_TEXELS * 4 + 4], -1, 'no colour means the base colour');+ assert.equal(table.data[plain * SUBSURFACE_TEXELS * 4], 0, 'a part without a block has weight 0');+});++test('weight 0 and no block both leave the kernel without the random walk', () => {+ assert.equal(sceneUsesSubsurface(subsurfaceScene(0).materials), false);+ assert.equal(sceneUsesSubsurface(sampleScene().materials), false);+ assert.equal(buildFragmentSource({ hasSubsurface: false }), FRAGMENT_SOURCE);+ assert.equal(FRAGMENT_SOURCE.includes('uSubsurface'), false);+ assert.equal(FRAGMENT_SOURCE.includes('randomWalk'), false);+ const withWalk = buildFragmentSource({ hasSubsurface: true });+ for (const name of ['uniform sampler2D uSubsurface', 'int randomWalk(', 'bool enterSubsurface(', 'subsurfaceWeight = splitSubsurface()']) {+ assert.equal(withWalk.includes(name), true, name);+ }+ assert.equal(withWalk.includes('const int WALK_STEPS = 32;'), true);+});