@peter.prib/renderengine 0.15.2 → 0.16.0

package/src/compute/WebGpuBackend.js

@@ -0,0 +1,630 @@
+// Copyright 2026 Jaroslav Peter Prib, Purveyor of Excellence
+import { ComputeBackend } from './ComputeBackend.js';
+import { parseKernelExpr, wgslKernelModule } from '../kernelExpr.js';
+
+const GPU_STORAGE  = 0x0080;
+const GPU_UNIFORM  = 0x0040;
+const GPU_COPY_SRC = 0x0004;
+const GPU_COPY_DST = 0x0008;
+const GPU_MAP_READ = 0x0001;
+
+const _align4 = (n) => (n + 3) & ~3;
+
+export const KDE_WGSL = /* wgsl */`
+struct KdeParams {
+  minX: f32,
+  stepX: f32,
+  bandwidth: f32,
+  invTwoBwSq: f32,
+  invBwSqrt2Pi: f32,
+  sampleCount: u32,
+  n: u32,
+  _pad: u32,
+};
+
+@group(0) @binding(0) var<storage, read>       values    : array<f32>;
+@group(0) @binding(1) var<storage, read_write> densities : array<f32>;
+@group(0) @binding(2) var<uniform>             params    : KdeParams;
+
+@compute @workgroup_size(64)
+fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
+  let i = gid.x;
+  if (i >= params.sampleCount) { return; }
+  if (params.n == 0u) {
+    densities[i] = 0.0;
+    return;
+  }
+  let x = params.minX + f32(i) * params.stepX;
+  var acc: f32 = 0.0;
+  for (var j: u32 = 0u; j < params.n; j = j + 1u) {
+    let diff = x - values[j];
+    acc = acc + exp(-diff * diff * params.invTwoBwSq);
+  }
+  densities[i] = (acc * params.invBwSqrt2Pi) / f32(params.n);
+}
+`;
+
+export const FORCE_3D_WGSL = /* wgsl */`
+struct SimParams {
+  nodeCount: u32,
+  edgeCount: u32,
+  K: f32,
+  temp: f32,
+};
+
+@group(0) @binding(0) var<storage, read_write> nodes  : array<vec4<f32>>; // pos: xyz, w=fixed (1.0 or 0.0)
+@group(0) @binding(1) var<storage, read>       edges  : array<vec2<u32>>; // sourceIdx, targetIdx
+@group(0) @binding(2) var<uniform>             params : SimParams;
+
+@compute @workgroup_size(64)
+fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
+  let i = gid.x;
+  if (i >= params.nodeCount) { return; }
+  let self = nodes[i];
+  if (self.w > 0.5) { return; }
+
+  var vx: f32 = 0.0;
+  var vy: f32 = 0.0;
+  var vz: f32 = 0.0;
+  let K = params.K;
+  let K2 = K * K;
+
+  for (var j: u32 = 0u; j < params.nodeCount; j = j + 1u) {
+    if (i == j) { continue; }
+    let other = nodes[j];
+    let dx = other.x - self.x;
+    let dy = other.y - self.y;
+    let dz = other.z - self.z;
+    var dist = sqrt(dx * dx + dy * dy + dz * dz);
+    if (dist < 0.01) { dist = 0.01; }
+    let f = K2 / dist;
+    let ux = dx / dist;
+    let uy = dy / dist;
+    let uz = dz / dist;
+    vx = vx - ux * f;
+    vy = vy - uy * f;
+    vz = vz - uz * f;
+  }
+
+  for (var e: u32 = 0u; e < params.edgeCount; e = e + 1u) {
+    let edge = edges[e];
+    var otherIdx: u32 = 0u;
+    var signVal: f32 = 0.0;
+    if (edge.x == i) {
+      otherIdx = edge.y;
+      signVal = 1.0;
+    } else if (edge.y == i) {
+      otherIdx = edge.x;
+      signVal = 1.0;
+    }
+    if (signVal > 0.0) {
+      let other = nodes[otherIdx];
+      let dx = other.x - self.x;
+      let dy = other.y - self.y;
+      let dz = other.z - self.z;
+      var dist = sqrt(dx * dx + dy * dy + dz * dz);
+      if (dist < 0.01) { dist = 0.01; }
+      let f = (dist * dist) / (K * 1.5);
+      let ux = dx / dist;
+      let uy = dy / dist;
+      let uz = dz / dist;
+      vx = vx + ux * f;
+      vy = vy + uy * f;
+      vz = vz + uz * f;
+    }
+  }
+
+  vx = vx - self.x * 0.02;
+  vy = vy - self.y * 0.02;
+  vz = vz - self.z * 0.02;
+
+  let mag = sqrt(vx * vx + vy * vy + vz * vz);
+  let safeMag = select(mag, 1.0, mag == 0.0);
+  let dt = min(mag, params.temp) / safeMag;
+
+  nodes[i] = vec4<f32>(self.x + vx * dt, self.y + vy * dt, self.z + vz * dt, self.w);
+}
+`;
+
+export const HEXBIN_WGSL = /* wgsl */`
+struct HexParams {
+  r: f32,
+  count: u32,
+  _p1: u32,
+  _p2: u32,
+};
+
+@group(0) @binding(0) var<storage, read>       points    : array<vec2<f32>>;
+@group(0) @binding(1) var<uniform>             params    : HexParams;
+@group(0) @binding(2) var<storage, read_write> hexCoords : array<vec4<f32>>;
+
+@compute @workgroup_size(64)
+fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
+  let i = gid.x;
+  if (i >= params.count) { return; }
+  let pt = points[i];
+  let r = params.r;
+  let sqrt3 = 1.7320508075688772;
+
+  let q = (sqrt3 / 3.0 * pt.x - 1.0 / 3.0 * pt.y) / r;
+  let s = (2.0 / 3.0 * pt.y) / r;
+
+  var rx = round(q);
+  var rz = round(s);
+  var ry = round(-q - s);
+
+  let xDiff = abs(rx - q);
+  let yDiff = abs(ry - (-q - s));
+  let zDiff = abs(rz - s);
+
+  if (xDiff > yDiff && xDiff > zDiff) {
+    rx = -ry - rz;
+  } else if (yDiff > zDiff) {
+    ry = -rx - rz;
+  } else {
+    rz = -rx - ry;
+  }
+
+  let cx = r * (sqrt3 * rx + sqrt3 / 2.0 * rz);
+  let cy = r * (1.5 * rz);
+
+  hexCoords[i] = vec4<f32>(rx, rz, cx, cy);
+}
+`;
+
+/**
+ * WebGpuBackend — hardware-accelerated compute offload via WebGPU.
+ */
+export class WebGpuBackend extends ComputeBackend {
+    constructor({ gpu = null, powerPreference = 'high-performance' } = {}) {
+        super();
+        this._gpu = gpu ?? (typeof navigator !== 'undefined' ? navigator.gpu : null);
+        this._power = powerPreference;
+        this.device = null;
+        this.adapter = null;
+        this._pipelines = new Map();
+    }
+
+    get name() {
+        return 'webgpu';
+    }
+
+    get isSync() {
+        return false;
+    }
+
+    static async isAvailable(gpu = (typeof navigator !== 'undefined' ? navigator.gpu : null)) {
+        if (!gpu?.requestAdapter) return false;
+        try {
+            return Boolean(await gpu.requestAdapter());
+        } catch {
+            return false;
+        }
+    }
+
+    async init() {
+        if (this.device) return this;
+        if (!this._gpu?.requestAdapter) {
+            throw new Error(
+                'WebGpuBackend: navigator.gpu is not available here. Use CpuBackend or selectBackend().'
+            );
+        }
+        this.adapter = await this._gpu.requestAdapter({ powerPreference: this._power });
+        if (!this.adapter) {
+            throw new Error('WebGpuBackend: no GPU adapter was available');
+        }
+        this.device = await this.adapter.requestDevice();
+        return this;
+    }
+
+    _assertReady() {
+        if (!this.device) {
+            throw new Error('WebGpuBackend: device not initialized. Call await backend.init() first.');
+        }
+    }
+
+    _getPipeline(name, wgslCode) {
+        let p = this._pipelines.get(name);
+        if (!p) {
+            const module = this.device.createShaderModule({ code: wgslCode });
+            p = this.device.createComputePipeline({
+                layout: 'auto',
+                compute: { module, entryPoint: 'main' },
+            });
+            this._pipelines.set(name, p);
+        }
+        return p;
+    }
+
+    /**
+     * Compute Gaussian KDE asynchronously using GPU.
+     */
+    async kernelDensityEstimate(values, options = {}) {
+        return this.kernelDensityEstimateAsync(values, options);
+    }
+
+    async kernelDensityEstimateAsync(values, options = {}) {
+        this._assertReady();
+        const n = values.length;
+        const sampleCount = options.sampleCount ?? 60;
+        if (n === 0) {
+            const min = options.min ?? 0, max = options.max ?? 1;
+            const step = (max - min) / Math.max(1, sampleCount - 1);
+            return Array.from({ length: sampleCount }, (_, i) => ({ x: min + i * step, density: 0 }));
+        }
+
+        let sum = 0, sumSq = 0, dataMin = Infinity, dataMax = -Infinity;
+        for (let i = 0; i < n; i++) {
+            const v = values[i];
+            sum += v; sumSq += v * v;
+            if (v < dataMin) dataMin = v;
+            if (v > dataMax) dataMax = v;
+        }
+        const mean = sum / n;
+        const variance = Math.max(0, (sumSq / n) - (mean * mean));
+        const stdev = Math.sqrt(variance);
+        const fallbackBandwidth = (dataMax - dataMin) * 0.1 || 1;
+        const silverman = n >= 2 ? 1.06 * stdev * Math.pow(n, -0.2) : 0;
+        const bandwidth = options.bandwidth ?? (silverman || fallbackBandwidth);
+        const min = options.min ?? (dataMin - 3 * bandwidth);
+        const max = options.max ?? (dataMax + 3 * bandwidth);
+        const step = (max - min) / Math.max(1, sampleCount - 1);
+        const invBwSqrt2Pi = 1 / (bandwidth * Math.sqrt(2 * Math.PI));
+        const invTwoBwSq = 1 / (2 * bandwidth * bandwidth);
+
+        const device = this.device;
+        const pipeline = this._getPipeline('kde', KDE_WGSL);
+
+        const valFloats = new Float32Array(values);
+        const valBuf = device.createBuffer({
+            size: _align4(valFloats.byteLength),
+            usage: GPU_STORAGE | GPU_COPY_DST,
+        });
+        device.queue.writeBuffer(valBuf, 0, valFloats);
+
+        const outBytes = _align4(sampleCount * 4);
+        const outBuf = device.createBuffer({
+            size: outBytes,
+            usage: GPU_STORAGE | GPU_COPY_SRC,
+        });
+        const readBuf = device.createBuffer({
+            size: outBytes,
+            usage: GPU_COPY_DST | GPU_MAP_READ,
+        });
+
+        // struct KdeParams { minX, stepX, bandwidth, invTwoBwSq, invBwSqrt2Pi, sampleCount, n, _pad }
+        const uniformData = new ArrayBuffer(32);
+        const uF32 = new Float32Array(uniformData);
+        const uU32 = new Uint32Array(uniformData);
+        uF32[0] = min;
+        uF32[1] = step;
+        uF32[2] = bandwidth;
+        uF32[3] = invTwoBwSq;
+        uF32[4] = invBwSqrt2Pi;
+        uU32[5] = sampleCount;
+        uU32[6] = n;
+        uU32[7] = 0;
+
+        const uniformBuf = device.createBuffer({
+            size: 32,
+            usage: GPU_UNIFORM | GPU_COPY_DST,
+        });
+        device.queue.writeBuffer(uniformBuf, 0, uniformData);
+
+        const bindGroup = device.createBindGroup({
+            layout: pipeline.getBindGroupLayout(0),
+            entries: [
+                { binding: 0, resource: { buffer: valBuf } },
+                { binding: 1, resource: { buffer: outBuf } },
+                { binding: 2, resource: { buffer: uniformBuf } },
+            ],
+        });
+
+        const encoder = device.createCommandEncoder();
+        const pass = encoder.beginComputePass();
+        pass.setPipeline(pipeline);
+        pass.setBindGroup(0, bindGroup);
+        pass.dispatchWorkgroups(Math.ceil(sampleCount / 64));
+        pass.end();
+
+        encoder.copyBufferToBuffer(outBuf, 0, readBuf, 0, outBytes);
+        device.queue.submit([encoder.finish()]);
+
+        await readBuf.mapAsync(GPU_MAP_READ);
+        const mapped = new Float32Array(readBuf.getMappedRange().slice(0, sampleCount * 4));
+        readBuf.unmap();
+
+        valBuf.destroy?.();
+        outBuf.destroy?.();
+        readBuf.destroy?.();
+        uniformBuf.destroy?.();
+
+        const result = [];
+        for (let i = 0; i < sampleCount; i++) {
+            result.push({ x: min + i * step, density: mapped[i] });
+        }
+        return result;
+    }
+
+    /**
+     * Compute 3D force-directed layout simulation asynchronously on GPU.
+     */
+    async layoutForce3D(nodes, edges, options = {}) {
+        return this.layoutForce3DAsync(nodes, edges, options);
+    }
+
+    async layoutForce3DAsync(nodes, edges, { iterations = 150 } = {}) {
+        this._assertReady();
+        const nodeCount = nodes.length;
+        const edgeCount = edges.length;
+        if (nodeCount === 0) return new Map();
+
+        const idMap = new Map();
+        const fixedMap = new Set(nodes.filter(n => n.x != null || n.y != null || n.z != null).map(n => n.id));
+
+        const nodeData = new Float32Array(nodeCount * 4);
+        for (let i = 0; i < nodeCount; i++) {
+            const n = nodes[i];
+            idMap.set(n.id, i);
+            nodeData[i * 4 + 0] = n.x ?? (Math.random() * 2 - 1);
+            nodeData[i * 4 + 1] = n.y ?? (Math.random() * 2 - 1);
+            nodeData[i * 4 + 2] = n.z ?? (Math.random() * 2 - 1);
+            nodeData[i * 4 + 3] = fixedMap.has(n.id) ? 1.0 : 0.0;
+        }
+
+        const validEdges = edges.filter(e => idMap.has(e.source) && idMap.has(e.target));
+        const edgeData = new Uint32Array(Math.max(1, validEdges.length) * 2);
+        for (let i = 0; i < validEdges.length; i++) {
+            edgeData[i * 2 + 0] = idMap.get(validEdges[i].source);
+            edgeData[i * 2 + 1] = idMap.get(validEdges[i].target);
+        }
+
+        const device = this.device;
+        const pipeline = this._getPipeline('force3d', FORCE_3D_WGSL);
+
+        const nodeBytes = _align4(nodeData.byteLength);
+        const nodeBuf = device.createBuffer({
+            size: nodeBytes,
+            usage: GPU_STORAGE | GPU_COPY_DST | GPU_COPY_SRC,
+        });
+        device.queue.writeBuffer(nodeBuf, 0, nodeData);
+
+        const edgeBytes = _align4(edgeData.byteLength);
+        const edgeBuf = device.createBuffer({
+            size: edgeBytes,
+            usage: GPU_STORAGE | GPU_COPY_DST,
+        });
+        device.queue.writeBuffer(edgeBuf, 0, edgeData);
+
+        const readBuf = device.createBuffer({
+            size: nodeBytes,
+            usage: GPU_COPY_DST | GPU_MAP_READ,
+        });
+
+        const uniformBuf = device.createBuffer({
+            size: 16,
+            usage: GPU_UNIFORM | GPU_COPY_DST,
+        });
+
+        const bindGroup = device.createBindGroup({
+            layout: pipeline.getBindGroupLayout(0),
+            entries: [
+                { binding: 0, resource: { buffer: nodeBuf } },
+                { binding: 1, resource: { buffer: edgeBuf } },
+                { binding: 2, resource: { buffer: uniformBuf } },
+            ],
+        });
+
+        const K = 1 / Math.cbrt(Math.max(nodeCount, 1));
+        let temp = 0.2;
+        const workgroups = Math.ceil(nodeCount / 64);
+
+        // Run simulation iterations on device
+        for (let iter = 0; iter < iterations; iter++) {
+            const uData = new ArrayBuffer(16);
+            new Uint32Array(uData)[0] = nodeCount;
+            new Uint32Array(uData)[1] = validEdges.length;
+            new Float32Array(uData)[2] = K;
+            new Float32Array(uData)[3] = temp;
+            device.queue.writeBuffer(uniformBuf, 0, uData);
+
+            const enc = device.createCommandEncoder();
+            const pass = enc.beginComputePass();
+            pass.setPipeline(pipeline);
+            pass.setBindGroup(0, bindGroup);
+            pass.dispatchWorkgroups(workgroups);
+            pass.end();
+            device.queue.submit([enc.finish()]);
+
+            temp *= 0.97;
+        }
+
+        // Map positions back
+        const copyEnc = device.createCommandEncoder();
+        copyEnc.copyBufferToBuffer(nodeBuf, 0, readBuf, 0, nodeBytes);
+        device.queue.submit([copyEnc.finish()]);
+
+        await readBuf.mapAsync(GPU_MAP_READ);
+        const mapped = new Float32Array(readBuf.getMappedRange().slice(0, nodeCount * 16));
+        readBuf.unmap();
+
+        nodeBuf.destroy?.();
+        edgeBuf.destroy?.();
+        readBuf.destroy?.();
+        uniformBuf.destroy?.();
+
+        const pos = new Map();
+        for (let i = 0; i < nodeCount; i++) {
+            const id = nodes[i].id;
+            pos.set(id, {
+                x: mapped[i * 4 + 0],
+                y: mapped[i * 4 + 1],
+                z: mapped[i * 4 + 2],
+                vx: 0, vy: 0, vz: 0,
+            });
+        }
+        return pos;
+    }
+
+    /**
+     * Compute 2D hexagonal binning coordinates on GPU.
+     */
+    async binHexbins(points, r, options = {}) {
+        return this.binHexbinsAsync(points, r, options);
+    }
+
+    async binHexbinsAsync(points, r, options = {}) {
+        this._assertReady();
+        const count = points.length;
+        if (count === 0) return new Map();
+
+        const ptData = new Float32Array(count * 2);
+        for (let i = 0; i < count; i++) {
+            ptData[i * 2 + 0] = points[i].px;
+            ptData[i * 2 + 1] = points[i].py;
+        }
+
+        const device = this.device;
+        const pipeline = this._getPipeline('hexbin', HEXBIN_WGSL);
+
+        const ptBytes = _align4(ptData.byteLength);
+        const ptBuf = device.createBuffer({
+            size: ptBytes,
+            usage: GPU_STORAGE | GPU_COPY_DST,
+        });
+        device.queue.writeBuffer(ptBuf, 0, ptData);
+
+        const outBytes = _align4(count * 16);
+        const outBuf = device.createBuffer({
+            size: outBytes,
+            usage: GPU_STORAGE | GPU_COPY_SRC,
+        });
+        const readBuf = device.createBuffer({
+            size: outBytes,
+            usage: GPU_COPY_DST | GPU_MAP_READ,
+        });
+
+        const uBuf = device.createBuffer({
+            size: 16,
+            usage: GPU_UNIFORM | GPU_COPY_DST,
+        });
+        const uData = new ArrayBuffer(16);
+        new Float32Array(uData)[0] = r;
+        new Uint32Array(uData)[1] = count;
+        device.queue.writeBuffer(uBuf, 0, uData);
+
+        const bindGroup = device.createBindGroup({
+            layout: pipeline.getBindGroupLayout(0),
+            entries: [
+                { binding: 0, resource: { buffer: ptBuf } },
+                { binding: 1, resource: { buffer: uBuf } },
+                { binding: 2, resource: { buffer: outBuf } },
+            ],
+        });
+
+        const enc = device.createCommandEncoder();
+        const pass = enc.beginComputePass();
+        pass.setPipeline(pipeline);
+        pass.setBindGroup(0, bindGroup);
+        pass.dispatchWorkgroups(Math.ceil(count / 64));
+        pass.end();
+        enc.copyBufferToBuffer(outBuf, 0, readBuf, 0, outBytes);
+        device.queue.submit([enc.finish()]);
+
+        await readBuf.mapAsync(GPU_MAP_READ);
+        const mapped = new Float32Array(readBuf.getMappedRange().slice(0, count * 16));
+        readBuf.unmap();
+
+        ptBuf.destroy?.();
+        outBuf.destroy?.();
+        readBuf.destroy?.();
+        uBuf.destroy?.();
+
+        const bins = new Map();
+        for (let i = 0; i < count; i++) {
+            const rx = Math.round(mapped[i * 4 + 0]);
+            const rz = Math.round(mapped[i * 4 + 1]);
+            const cx = mapped[i * 4 + 2];
+            const cy = mapped[i * 4 + 3];
+            const key = `${rx},${rz}`;
+
+            let bin = bins.get(key);
+            if (!bin) {
+                bin = { key, q: rx, r: rz, cx, cy, count: 0, points: [], value: 0 };
+                bins.set(key, bin);
+            }
+            bin.count++;
+            bin.points.push(points[i]);
+            if (points[i].val != null) bin.value += Number(points[i].val) || 0;
+        }
+        return bins;
+    }
+
+    /**
+     * Evaluate a formula AST or source across input column arrays via WGSL compute shader.
+     */
+    async evaluateFormula(sourceOrAst, params, columns) {
+        return this.evaluateFormulaAsync(sourceOrAst, params, columns);
+    }
+
+    async evaluateFormulaAsync(sourceOrAst, params, columns) {
+        this._assertReady();
+        const { ast } = typeof sourceOrAst === 'string'
+            ? parseKernelExpr(sourceOrAst, params)
+            : { ast: sourceOrAst };
+
+        const count = columns[params[0]]?.length ?? 0;
+        if (count === 0) return new Float32Array(0);
+
+        const wgslCode = wgslKernelModule(ast, params);
+        const pipeline = this._getPipeline(`formula_${params.join('_')}`, wgslCode);
+        const device = this.device;
+
+        const inBuffers = [];
+        const entries = [];
+        for (let i = 0; i < params.length; i++) {
+            const colData = columns[params[i]];
+            const floats = colData instanceof Float32Array ? colData : new Float32Array(colData);
+            const size = _align4(floats.byteLength);
+            const buf = device.createBuffer({ size, usage: GPU_STORAGE | GPU_COPY_DST });
+            device.queue.writeBuffer(buf, 0, floats);
+            inBuffers.push(buf);
+            entries.push({ binding: i, resource: { buffer: buf } });
+        }
+
+        const outBytes = _align4(count * 4);
+        const outBuf = device.createBuffer({ size: outBytes, usage: GPU_STORAGE | GPU_COPY_SRC });
+        const readBuf = device.createBuffer({ size: outBytes, usage: GPU_COPY_DST | GPU_MAP_READ });
+
+        const countBuf = device.createBuffer({ size: 16, usage: GPU_UNIFORM | GPU_COPY_DST });
+        device.queue.writeBuffer(countBuf, 0, new Uint32Array([count, 0, 0, 0]));
+
+        entries.push({ binding: params.length, resource: { buffer: outBuf } });
+        entries.push({ binding: params.length + 1, resource: { buffer: countBuf } });
+
+        const bindGroup = device.createBindGroup({
+            layout: pipeline.getBindGroupLayout(0),
+            entries,
+        });
+
+        const enc = device.createCommandEncoder();
+        const pass = enc.beginComputePass();
+        pass.setPipeline(pipeline);
+        pass.setBindGroup(0, bindGroup);
+        pass.dispatchWorkgroups(Math.ceil(count / 64));
+        pass.end();
+        enc.copyBufferToBuffer(outBuf, 0, readBuf, 0, outBytes);
+        device.queue.submit([enc.finish()]);
+
+        await readBuf.mapAsync(GPU_MAP_READ);
+        const result = new Float32Array(readBuf.getMappedRange().slice(0, count * 4));
+        readBuf.unmap();
+
+        for (const b of inBuffers) b.destroy?.();
+        outBuf.destroy?.();
+        readBuf.destroy?.();
+        countBuf.destroy?.();
+
+        return result;
+    }
+}

package/src/compute/index.js

@@ -0,0 +1,5 @@
+// Copyright 2026 Jaroslav Peter Prib, Purveyor of Excellence
+export { ComputeBackend } from './ComputeBackend.js';
+export { CpuBackend } from './CpuBackend.js';
+export { WebGpuBackend, KDE_WGSL, FORCE_3D_WGSL, HEXBIN_WGSL } from './WebGpuBackend.js';
+export { selectBackend, availableBackends, BACKENDS } from './selectBackend.js';