@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/render/scene-target.js

@@ -0,0 +1,450 @@
+import { DEPTH_FORMAT } from './material.js';
+import { Texture } from './texture.js';
+/** HDR scene targets: [0] colour, [1] emissive (feeds bloom). */
+export const SCENE_FORMAT = 'rgba16float';
+const sharedEmissive = new WeakMap();
+function acquireSharedEmissive(device, w, h, label) {
+    let bySize = sharedEmissive.get(device);
+    if (!bySize) {
+        bySize = new Map();
+        sharedEmissive.set(device, bySize);
+    }
+    const key = `${w}x${h}`;
+    let e = bySize.get(key);
+    if (!e) {
+        e = {
+            tex: new Texture(device, {
+                width: w,
+                height: h,
+                format: SCENE_FORMAT,
+                usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING,
+                label: `${label}-emissive`,
+            }),
+            refs: 0,
+        };
+        bySize.set(key, e);
+    }
+    e.refs++;
+    return e.tex;
+}
+function releaseSharedEmissive(device, tex) {
+    const bySize = sharedEmissive.get(device);
+    if (!bySize)
+        return;
+    const key = `${tex.width}x${tex.height}`;
+    const e = bySize.get(key);
+    if (!e || e.tex !== tex)
+        return;
+    if (--e.refs > 0)
+        return;
+    bySize.delete(key);
+    tex.destroy();
+}
+/** Shared external emissive textures alive on `device` (tests). */
+export function sharedEmissiveCount(device) {
+    return sharedEmissive.get(device)?.size ?? 0;
+}
+/** Format of the `roughMetal` aux attachment. */
+export const ROUGH_METAL_FORMAT = 'rg8unorm';
+/** Format of the `velocity` aux attachment. */
+export const VELOCITY_FORMAT = 'rg16float';
+/** A texture owned by someone else, in the shape of `Texture` (its `destroy` does nothing). */
+class AdoptedTexture {
+    texture;
+    view;
+    width;
+    height;
+    format;
+    /** One layer, one mip, a `'2d'` view: the adopted view is a single eye's layer. */
+    layers = 1;
+    mipLevels = 1;
+    viewDimension = '2d';
+    constructor(texture, view) {
+        this.texture = texture;
+        this.view = texture.createView(view);
+        this.width = texture.width;
+        this.height = texture.height;
+        this.format = texture.format;
+    }
+    destroy() { }
+}
+/**
+ * What `Renderer.render` draws into: the two HDR colour targets the scene pass writes
+ * (`color`, `emissive`, both `SCENE_FORMAT`) and, when a camera asks for depth, a
+ * `depth24plus` attachment made at the same size on first use. The renderer owns one at the
+ * scene resolution (`renderer.target`, what the post stack reads and the surface shows);
+ * `renderer.createSceneTarget(desc)` makes more for offscreen views (a portal, a minimap),
+ * whose `color` and `emissive` are sampleable like any `Texture`.
+ *
+ * `SceneTarget.external(desc)` adopts a colour (and depth) texture owned by someone else, an
+ * XR layer's eye textures; `adopt(desc)` re-points it at the next frame's. Its emissive
+ * attachment (every pipeline writes two targets) is one texture per device and size shared by
+ * all external targets, stored with `'discard'`: the post stack does not run on an external
+ * target, so its emissive is written and dropped, and two eyes allocate one, not two.
+ *
+ * Depth hooks (ws/render-hooks): when a view splits its scene pass for a `readsDepth` drawable
+ * the renderer copies `depth` into `depthCopy` (same format and size, `COPY_DST` +
+ * `TEXTURE_BINDING`, made on first use, recreated with `depth`) between the opaque pass
+ * (`passDesc`, label `scene`) and the blended pass (`blendPassDesc`, label `scene-blend`,
+ * which loads every attachment). An allocated depth texture carries `COPY_SRC`; an adopted one
+ * (an XR layer's) can be copied only if its owner gave it `COPY_SRC` (`canCopyDepth`).
+ */
+export class SceneTarget {
+    device;
+    color;
+    emissive;
+    /** The `rg8unorm` roughness/metalness attachment (`aux.roughMetal`), else null. */
+    roughMetal = null;
+    /** The `rg16float` screen-space velocity attachment (`aux.velocity`), else null. */
+    velocity = null;
+    /** Bit 0: has `roughMetal`; bit 1: has `velocity`. Keys material pipeline variants. */
+    auxKey;
+    width = 0;
+    height = 0;
+    /**
+     * For an external target, the part of `color` its views draw into (texture px), or null
+     * when the whole texture is the view; always null for an allocated target.
+     */
+    viewport = null;
+    /** The scene pass descriptor for this target; the renderer sets its load ops per view. */
+    passDesc;
+    colorAtt;
+    emissiveAtt;
+    depthAtt = {
+        view: undefined,
+        depthClearValue: 1,
+        depthLoadOp: 'clear',
+        depthStoreOp: 'store',
+    };
+    /** The blended half of a split view: the same attachments, every load op `load`. */
+    blendPassDesc;
+    blendColorAtt;
+    blendEmissiveAtt;
+    /** Aux attachments in order (rough-metal, velocity), for the clear and the blend pass. */
+    auxAtts = [];
+    blendAuxAtts = [];
+    blendDepthAtt = {
+        view: undefined,
+        depthLoadOp: 'load',
+        depthStoreOp: 'store',
+    };
+    depthTex = null;
+    depthCopyTex = null;
+    /** `copyDepth`'s reused copy descriptors (no allocation per frame). */
+    copySrc = {
+        texture: undefined,
+        origin: { x: 0, y: 0, z: 0 },
+    };
+    copyDst = {
+        texture: undefined,
+    };
+    copySize = { width: 0, height: 0, depthOrArrayLayers: 1 };
+    label;
+    /** The adopted colour texture of an external target; null for an allocated one. */
+    externalColor = null;
+    /** The adopted depth texture of an external target, when its layer has one. */
+    externalDepth = null;
+    adoptedLayer = 0;
+    /** `external`: internal, set by `SceneTarget.external`; the textures then come from `adopt`. */
+    constructor(device, desc, external = false) {
+        this.device = device;
+        this.label = desc.label ?? 'scene';
+        this.auxKey = (desc.aux?.roughMetal ? 1 : 0) | (desc.aux?.velocity ? 2 : 0);
+        this.colorAtt = {
+            view: undefined,
+            loadOp: 'clear',
+            storeOp: 'store',
+            clearValue: { r: 0, g: 0, b: 0, a: 1 },
+        };
+        this.emissiveAtt = {
+            view: undefined,
+            loadOp: 'clear',
+            storeOp: 'store',
+            clearValue: { r: 0, g: 0, b: 0, a: 0 },
+        };
+        const colorAttachments = [this.colorAtt, this.emissiveAtt];
+        const blendAttachments = [];
+        for (let k = 0; k < 2; k++) {
+            if (!(this.auxKey & (1 << k)))
+                continue;
+            const att = {
+                view: undefined,
+                loadOp: 'clear',
+                storeOp: 'store',
+                clearValue: { r: 0, g: 0, b: 0, a: 0 },
+            };
+            const blendAtt = {
+                view: undefined,
+                loadOp: 'load',
+                storeOp: 'store',
+            };
+            this.auxAtts.push(att);
+            this.blendAuxAtts.push(blendAtt);
+            colorAttachments.push(att);
+            blendAttachments.push(blendAtt);
+        }
+        this.passDesc = { label: 'scene', colorAttachments };
+        this.blendColorAtt = {
+            view: undefined,
+            loadOp: 'load',
+            storeOp: 'store',
+        };
+        this.blendEmissiveAtt = {
+            view: undefined,
+            loadOp: 'load',
+            storeOp: 'store',
+        };
+        this.blendPassDesc = {
+            label: 'scene-blend',
+            colorAttachments: [this.blendColorAtt, this.blendEmissiveAtt, ...blendAttachments],
+            depthStencilAttachment: this.blendDepthAtt,
+        };
+        if (external) {
+            // Written and dropped: see the shared emissive note above (ws/ergo-3d).
+            this.emissiveAtt.storeOp = 'discard';
+            this.blendEmissiveAtt.storeOp = 'discard';
+        }
+        else
+            this.resize(desc.width, desc.height);
+    }
+    /** A target over textures owned by someone else (an XR layer's); see `SceneTargetExternal`. */
+    static external(desc) {
+        const t = new SceneTarget(desc.device, { width: 0, height: 0, label: desc.label ?? 'external', aux: desc.aux }, true);
+        t.adopt(desc);
+        return t;
+    }
+    /** True for a target made by `SceneTarget.external`. */
+    get isExternal() {
+        return this.externalColor !== null;
+    }
+    /** The adopted colour texture of an external target; null for an allocated one. */
+    get adoptedColor() {
+        return this.externalColor;
+    }
+    /**
+     * The depth texture, once a depth camera has rendered here; null before. Sampleable
+     * (`texture_depth_2d`) outside the scene pass that writes it.
+     */
+    get depth() {
+        return this.depthTex;
+    }
+    /**
+     * The sampleable copy of `depth` a split view fills before its blended pass
+     * (`Drawable.afterOpaque`); null until the first view that split here. Same format and
+     * size as `depth`, recreated with it.
+     */
+    get depthCopy() {
+        return this.depthCopyTex;
+    }
+    /** Whether `depth` can be the source of a copy (an adopted texture may lack `COPY_SRC`). */
+    get canCopyDepth() {
+        return this.depthTex !== null && (this.depthTex.texture.usage & GPUTextureUsage.COPY_SRC) !== 0;
+    }
+    /**
+     * Point an external target at this frame's textures (an XR layer rotates them). A no-op
+     * when `color`, `depth` and the view's array layer are the ones already adopted; otherwise
+     * new views are made and, if the size changed, the shared emissive is swapped for one of the
+     * new size and the own depth texture dropped.
+     */
+    adopt(desc) {
+        const depth = desc.depth ?? null;
+        const layer = desc.view?.baseArrayLayer ?? 0;
+        const same = desc.color === this.externalColor &&
+            depth === this.externalDepth &&
+            layer === this.adoptedLayer;
+        this.viewport = desc.viewport ?? null;
+        if (same)
+            return;
+        this.externalColor = desc.color;
+        this.externalDepth = depth;
+        this.adoptedLayer = layer;
+        const w = desc.color.width;
+        const h = desc.color.height;
+        if (w !== this.width || h !== this.height) {
+            this.width = w;
+            this.height = h;
+            if (this.emissive)
+                releaseSharedEmissive(this.device, this.emissive);
+            this.emissive = acquireSharedEmissive(this.device, w, h, this.label);
+            this.emissiveAtt.view = this.emissive.view;
+            this.blendEmissiveAtt.view = this.emissive.view;
+            this.depthTex?.destroy();
+            this.depthTex = null;
+            this.depthCopyTex?.destroy();
+            this.depthCopyTex = null;
+            this.resizeAux(w, h);
+        }
+        this.color = new AdoptedTexture(desc.color, desc.view);
+        this.colorAtt.view = this.color.view;
+        this.blendColorAtt.view = this.color.view;
+        if (depth) {
+            this.depthTex = new AdoptedTexture(depth, desc.view);
+            this.depthAtt.view = this.depthTex.view;
+            this.blendDepthAtt.view = this.depthTex.view;
+        }
+        else if (this.depthTex && this.depthTex instanceof AdoptedTexture) {
+            this.depthTex = null;
+        }
+    }
+    /** Recreate the textures at a new size (no-op when unchanged). Returns whether they changed. */
+    resize(width, height) {
+        if (this.externalColor)
+            throw new Error('SceneTarget.resize: an external target is sized by its textures');
+        const w = Math.max(1, Math.floor(width));
+        const h = Math.max(1, Math.floor(height));
+        if (this.color && w === this.width && h === this.height)
+            return false;
+        this.width = w;
+        this.height = h;
+        this.color?.destroy();
+        this.emissive?.destroy();
+        // The depth target (only ever made for a depth camera) is rebuilt at the new size lazily.
+        this.depthTex?.destroy();
+        this.depthTex = null;
+        this.depthCopyTex?.destroy();
+        this.depthCopyTex = null;
+        const usage = GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING;
+        this.color = new Texture(this.device, {
+            width: w,
+            height: h,
+            format: SCENE_FORMAT,
+            usage,
+            label: `${this.label}-color`,
+        });
+        this.emissive = new Texture(this.device, {
+            width: w,
+            height: h,
+            format: SCENE_FORMAT,
+            usage,
+            label: `${this.label}-emissive`,
+        });
+        this.colorAtt.view = this.color.view;
+        this.emissiveAtt.view = this.emissive.view;
+        this.blendColorAtt.view = this.color.view;
+        this.blendEmissiveAtt.view = this.emissive.view;
+        this.resizeAux(w, h);
+        return true;
+    }
+    /** Load op of the aux attachments for the next scene pass (the renderer: clear on first view). */
+    setAuxLoadOp(op) {
+        for (const a of this.auxAtts)
+            a.loadOp = op;
+    }
+    /** (Re)create the aux attachments at `w × h`. */
+    resizeAux(w, h) {
+        if (this.auxKey === 0)
+            return;
+        const usage = GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING;
+        this.roughMetal?.destroy();
+        this.velocity?.destroy();
+        this.roughMetal = null;
+        this.velocity = null;
+        let i = 0;
+        if (this.auxKey & 1) {
+            this.roughMetal = new Texture(this.device, {
+                width: w,
+                height: h,
+                format: ROUGH_METAL_FORMAT,
+                usage,
+                label: `${this.label}-rough-metal`,
+            });
+            this.auxAtts[i].view = this.roughMetal.view;
+            this.blendAuxAtts[i].view = this.roughMetal.view;
+            i++;
+        }
+        if (this.auxKey & 2) {
+            this.velocity = new Texture(this.device, {
+                width: w,
+                height: h,
+                format: VELOCITY_FORMAT,
+                usage,
+                label: `${this.label}-velocity`,
+            });
+            this.auxAtts[i].view = this.velocity.view;
+            this.blendAuxAtts[i].view = this.velocity.view;
+        }
+    }
+    /**
+     * The depth attachment, allocating the `depth24plus` texture at this size on first use (an
+     * external target with an adopted depth texture uses that instead).
+     */
+    depthAttachment() {
+        if (!this.depthTex) {
+            this.depthTex = new Texture(this.device, {
+                width: this.width,
+                height: this.height,
+                format: DEPTH_FORMAT,
+                // TEXTURE_BINDING: world-space particles copy it for their soft fade (`depth`).
+                // COPY_SRC: a split view copies it into `depthCopy` (ws/render-hooks).
+                usage: GPUTextureUsage.RENDER_ATTACHMENT |
+                    GPUTextureUsage.TEXTURE_BINDING |
+                    GPUTextureUsage.COPY_SRC,
+                label: `${this.label}-depth`,
+            });
+            this.depthAtt.view = this.depthTex.view;
+            this.blendDepthAtt.view = this.depthTex.view;
+        }
+        return this.depthAtt;
+    }
+    /**
+     * `depthCopy`, allocated at `depth`'s size and format on first use (the renderer calls this
+     * when a view splits; `depth` exists by then). Null when `depth` is not copyable.
+     */
+    depthCopyTexture() {
+        if (!this.depthTex || !this.canCopyDepth)
+            return null;
+        const d = this.depthTex;
+        if (this.depthCopyTex &&
+            (this.depthCopyTex.width !== d.width ||
+                this.depthCopyTex.height !== d.height ||
+                this.depthCopyTex.format !== d.format)) {
+            this.depthCopyTex.destroy();
+            this.depthCopyTex = null;
+        }
+        if (!this.depthCopyTex) {
+            this.depthCopyTex = new Texture(this.device, {
+                width: d.width,
+                height: d.height,
+                format: d.format,
+                usage: GPUTextureUsage.COPY_DST | GPUTextureUsage.TEXTURE_BINDING,
+                label: `${this.label}-depth-copy`,
+            });
+        }
+        return this.depthCopyTex;
+    }
+    /**
+     * Encode a copy of `depth` (the adopted layer of an external one) into `depthCopy`, making
+     * the copy texture first; returns it, or null when `depth` is missing or not copyable.
+     * Nothing is allocated per call once the copy texture exists.
+     */
+    copyDepth(encoder) {
+        const copy = this.depthCopyTexture();
+        const d = this.depthTex;
+        if (!copy || !d)
+            return null;
+        this.copySrc.texture = d.texture;
+        this.copySrc.origin.z = this.externalDepth ? this.adoptedLayer : 0;
+        this.copyDst.texture = copy.texture;
+        this.copySize.width = d.width;
+        this.copySize.height = d.height;
+        encoder.copyTextureToTexture(this.copySrc, this.copyDst, this.copySize);
+        return copy;
+    }
+    destroy() {
+        this.color?.destroy();
+        this.roughMetal?.destroy();
+        this.velocity?.destroy();
+        this.roughMetal = null;
+        this.velocity = null;
+        if (this.externalColor) {
+            if (this.emissive)
+                releaseSharedEmissive(this.device, this.emissive);
+        }
+        else
+            this.emissive?.destroy();
+        this.depthTex?.destroy();
+        this.depthTex = null;
+        this.depthCopyTex?.destroy();
+        this.depthCopyTex = null;
+    }
+}

package/dist/render/shadow.d.ts

@@ -0,0 +1,74 @@
+import { Camera } from './camera.js';
+import { type ShadowUniforms, type SunShadow } from './lights.js';
+import type { VertexLayout } from './mesh.js';
+/** Depth format of the sun's shadow map (and of the 1×1 placeholder bound without one). */
+export declare const SHADOW_FORMAT: GPUTextureFormat;
+/** Shadow map side in texels when `SunShadow.size` is not given. */
+export declare const DEFAULT_SHADOW_SIZE = 2048;
+/**
+ * The sun's shadow map: one `depth32float` texture, a comparison sampler, a 1×1 placeholder
+ * depth texture (what every view binds at `@group(0) @binding(3)` until a shadow pass has
+ * rendered) and a depth-only pipeline per vertex layout. The renderer owns one and, for each
+ * `render` whose `frame.lights.sun.shadow` is set, encodes a shadow pass through `sunCamera`
+ * (an orthographic `Camera` placed by `place`) over the view's opaque shadow-casting draws. A
+ * caster whose material has a `shadowFragmentEntry` (alpha mask, dissolve) draws through that
+ * material's `shadowPipelineFor` instead, so its holes show in the shadow.
+ * Engine-internal; games set `Lights.sun.shadow`.
+ */
+export declare class ShadowMap {
+    /** Comparison sampler (`less-equal`: a receiver at or in front of the stored depth is lit). */
+    readonly sampler: GPUSampler;
+    /** 1×1 depth view bound in place of the map (and in the shadow pass itself). */
+    readonly placeholder: GPUTextureView;
+    /** The orthographic camera the shadow pass renders through; `place` sets it. */
+    readonly sunCamera: Camera;
+    /** What `Lights.writeBlock` needs for the view this map was rendered for. */
+    readonly uniforms: ShadowUniforms;
+    /** Side of the current map in texels, 0 before the first shadow pass. */
+    size: number;
+    /** Bumped every time the map texture is (re)created, so bind groups can follow it. */
+    generation: number;
+    private texture;
+    /** Maps replaced this frame (passes already encoded may still read them); see `flush`. */
+    private readonly retired;
+    private mapView;
+    private readonly placeholderTex;
+    private readonly device;
+    private readonly pipelineLayout;
+    private readonly pipelines;
+    /** Skinned layouts: one pipeline per material bind group layout (the palette is group 1). */
+    private readonly skinnedPipelines;
+    private readonly globalsLayout;
+    private readonly viewM;
+    private readonly projM;
+    private readonly eye;
+    private readonly target;
+    private readonly depthAtt;
+    /** The shadow pass descriptor; its attachment view follows `view`. */
+    readonly passDesc: GPURenderPassDescriptor;
+    constructor(device: GPUDevice, globalsLayout: GPUBindGroupLayout);
+    /** The map's view when one has been rendered, else `placeholder`. */
+    get view(): GPUTextureView;
+    /**
+     * Make sure the map is `size` texels square (creating or replacing the texture; bumps
+     * `generation` when it does). Returns whether the texture changed.
+     */
+    ensure(size: number): boolean;
+    /**
+     * Point `sunCamera` along `sunDir` through an orthographic box centred on `center` (the
+     * rendering camera's position): half-width `shadow.extent`, depth `near..far` along the
+     * light measured from `center` (defaults `-extent..extent`). Fills `uniforms` for a map of
+     * `size` texels. No allocation.
+     */
+    place(center: ArrayLike<number>, sunDir: ArrayLike<number>, shadow: SunShadow, size: number): void;
+    /**
+     * The depth-only pipeline for meshes in `layout`: the engine prelude's `vs_main` (so the same
+     * `engine_vertex` path as the scene pass), no fragment stage, `SHADOW_FORMAT` depth with
+     * writes on. Built on first use and cached. A skinned layout with `bindingsLayout` (the
+     * material's group 1, which holds the joint palette) gets a pipeline layout of both groups.
+     */
+    pipelineFor(layout: VertexLayout, bindingsLayout?: GPUBindGroupLayout): GPURenderPipeline;
+    /** Destroy maps replaced since the last call; the renderer calls it after each submit. */
+    flush(): void;
+    destroy(): void;
+}