@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/render/scene-pipelines.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Pipeline variants of one scene-pass drawable, keyed on the pass it draws into
+ * (ws/render-10): a variant key (the depth format, or whatever names the drawable's depth
+ * state; null without depth) × the target's aux key (`frame.auxKey`, 0..3). A view into a
+ * target with other aux attachments than the last one gets its own pipeline, built on first
+ * use from `renderer.sceneTargets(blend, aux)`; nothing is rebuilt or allocated after.
+ * Internal to the engine's drawables (fx, ui world panel).
+ */
+export declare class ScenePipelineCache {
+    private readonly rows;
+    /** The pipeline stored for (`key`, `aux`), else undefined. */
+    get(key: unknown, aux: number): GPURenderPipeline | undefined;
+    /** Store `pipeline` for (`key`, `aux`) and return it. */
+    set(key: unknown, aux: number, pipeline: GPURenderPipeline): GPURenderPipeline;
+}
+/** `desc` with its fragment colour targets replaced by `targets` (and `label`, `depthStencil`). */
+export declare function sceneVariant(desc: GPURenderPipelineDescriptor, targets: GPUColorTargetState[], label: string | undefined, depthStencil: GPUDepthStencilState | undefined): GPURenderPipelineDescriptor;
+/** The label suffix of an aux variant: empty for a plain target (labels stay as before). */
+export declare function auxSuffix(aux: number): string;
+/**
+ * Where a drawable that writes its own motion puts it (ws/render-11): the fragment location of
+ * the velocity attachment for aux key `aux` (colour, emissive, rough-metal, velocity), or 0
+ * when the target has no velocity attachment (the drawable keeps its masked pipeline).
+ */
+export declare function velocityLocation(aux: number): number;
+/**
+ * `targets` (a `renderer.sceneTargets` list) with the velocity entry written instead of masked
+ * and blended over what the opaque pass left, by the alpha the fragment writes in `.a` of its
+ * `vec4f(velocity, 0, alpha)` output. A copy, built once per pipeline (not per frame).
+ */
+export declare function velocityTargets(targets: GPUColorTargetState[], aux: number): GPUColorTargetState[];
+/**
+ * WGSL: `engine_motion(frag, prev_clip)`, the screen motion since last frame in uv units
+ * (+x right, +y down, jitter removed) of a fragment at framebuffer position `frag` whose
+ * previous clip position is `prev_clip`; zero when `prev_clip.w <= 0` (unknown). The same
+ * formula as the prelude's `engine_velocity`, for drawables built on `WGSL_GLOBALS` (fx
+ * billboards and world particles). Needs the `camera` block.
+ */
+export declare const WGSL_MOTION = "\nfn engine_motion(frag: vec4f, prev_clip: vec4f) -> vec2f {\n  if (prev_clip.w <= 0.0) { return vec2f(0.0); }\n  let cur = (frag.xy - camera.viewport.xy) / camera.viewport.zw - camera.jitter.xy * vec2f(0.5, -0.5);\n  let pn = prev_clip.xy / prev_clip.w;\n  let prev = vec2f(pn.x * 0.5 + 0.5, 0.5 - pn.y * 0.5);\n  return cur - prev;\n}\n";
+/**
+ * `sceneVariant` for a drawable's motion-writing shader: the same descriptor with `module`
+ * (its velocity build) on both stages and `velocityTargets` as the colour targets.
+ */
+export declare function motionVariant(desc: GPURenderPipelineDescriptor, module: GPUShaderModule, targets: GPUColorTargetState[], aux: number, label: string | undefined, depthStencil: GPUDepthStencilState | undefined): GPURenderPipelineDescriptor;

package/dist/render/scene-pipelines.js

@@ -0,0 +1,92 @@
+/**
+ * Pipeline variants of one scene-pass drawable, keyed on the pass it draws into
+ * (ws/render-10): a variant key (the depth format, or whatever names the drawable's depth
+ * state; null without depth) × the target's aux key (`frame.auxKey`, 0..3). A view into a
+ * target with other aux attachments than the last one gets its own pipeline, built on first
+ * use from `renderer.sceneTargets(blend, aux)`; nothing is rebuilt or allocated after.
+ * Internal to the engine's drawables (fx, ui world panel).
+ */
+export class ScenePipelineCache {
+    rows = new Map();
+    /** The pipeline stored for (`key`, `aux`), else undefined. */
+    get(key, aux) {
+        return this.rows.get(key)?.[aux & 3];
+    }
+    /** Store `pipeline` for (`key`, `aux`) and return it. */
+    set(key, aux, pipeline) {
+        let row = this.rows.get(key);
+        if (!row) {
+            row = [undefined, undefined, undefined, undefined];
+            this.rows.set(key, row);
+        }
+        row[aux & 3] = pipeline;
+        return pipeline;
+    }
+}
+/** `desc` with its fragment colour targets replaced by `targets` (and `label`, `depthStencil`). */
+export function sceneVariant(desc, targets, label, depthStencil) {
+    const out = {
+        ...desc,
+        label,
+        fragment: { ...desc.fragment, targets },
+    };
+    if (depthStencil)
+        out.depthStencil = depthStencil;
+    return out;
+}
+/** The label suffix of an aux variant: empty for a plain target (labels stay as before). */
+export function auxSuffix(aux) {
+    return aux === 0 ? '' : `:aux${aux}`;
+}
+/**
+ * Where a drawable that writes its own motion puts it (ws/render-11): the fragment location of
+ * the velocity attachment for aux key `aux` (colour, emissive, rough-metal, velocity), or 0
+ * when the target has no velocity attachment (the drawable keeps its masked pipeline).
+ */
+export function velocityLocation(aux) {
+    return aux & 2 ? (aux & 1 ? 3 : 2) : 0;
+}
+/** Straight-alpha over: a translucent quad's motion is weighted by its coverage. */
+const VELOCITY_BLEND = {
+    color: { srcFactor: 'src-alpha', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+    alpha: { srcFactor: 'zero', dstFactor: 'one', operation: 'add' },
+};
+/**
+ * `targets` (a `renderer.sceneTargets` list) with the velocity entry written instead of masked
+ * and blended over what the opaque pass left, by the alpha the fragment writes in `.a` of its
+ * `vec4f(velocity, 0, alpha)` output. A copy, built once per pipeline (not per frame).
+ */
+export function velocityTargets(targets, aux) {
+    const at = velocityLocation(aux);
+    if (at === 0)
+        return targets;
+    const out = targets.slice();
+    out[at] = { format: targets[at].format, blend: VELOCITY_BLEND };
+    return out;
+}
+/**
+ * WGSL: `engine_motion(frag, prev_clip)`, the screen motion since last frame in uv units
+ * (+x right, +y down, jitter removed) of a fragment at framebuffer position `frag` whose
+ * previous clip position is `prev_clip`; zero when `prev_clip.w <= 0` (unknown). The same
+ * formula as the prelude's `engine_velocity`, for drawables built on `WGSL_GLOBALS` (fx
+ * billboards and world particles). Needs the `camera` block.
+ */
+export const WGSL_MOTION = /* wgsl */ `
+fn engine_motion(frag: vec4f, prev_clip: vec4f) -> vec2f {
+  if (prev_clip.w <= 0.0) { return vec2f(0.0); }
+  let cur = (frag.xy - camera.viewport.xy) / camera.viewport.zw - camera.jitter.xy * vec2f(0.5, -0.5);
+  let pn = prev_clip.xy / prev_clip.w;
+  let prev = vec2f(pn.x * 0.5 + 0.5, 0.5 - pn.y * 0.5);
+  return cur - prev;
+}
+`;
+/**
+ * `sceneVariant` for a drawable's motion-writing shader: the same descriptor with `module`
+ * (its velocity build) on both stages and `velocityTargets` as the colour targets.
+ */
+export function motionVariant(desc, module, targets, aux, label, depthStencil) {
+    const out = sceneVariant(desc, velocityTargets(targets, aux), label, depthStencil);
+    out.vertex = { ...desc.vertex, module };
+    out.fragment = { ...out.fragment, module };
+    return out;
+}

package/dist/render/scene-target.d.ts

@@ -0,0 +1,170 @@
+import { Texture } from './texture.js';
+/** HDR scene targets: [0] colour, [1] emissive (feeds bloom). */
+export declare const SCENE_FORMAT: GPUTextureFormat;
+/** Shared external emissive textures alive on `device` (tests). */
+export declare function sharedEmissiveCount(device: GPUDevice): number;
+/**
+ * Extra attachments a scene target carries beside colour and emissive (ws/render-4), what a
+ * screen-space post pass (SSR, TAA, motion blur) reads through `PostInputs.roughMetal` /
+ * `PostInputs.velocity`: `roughMetal` an `rg8unorm` (roughness, metalness) target,
+ * `velocity` an `rg16float` screen-space motion target (uv units since last frame). Materials
+ * declaring `aux` (the standard material) write them; others leave them cleared.
+ */
+export interface SceneTargetAux {
+    roughMetal?: boolean;
+    velocity?: boolean;
+}
+/** Format of the `roughMetal` aux attachment. */
+export declare const ROUGH_METAL_FORMAT: GPUTextureFormat;
+/** Format of the `velocity` aux attachment. */
+export declare const VELOCITY_FORMAT: GPUTextureFormat;
+export interface SceneTargetDesc {
+    width: number;
+    height: number;
+    /** Prefix of the texture labels. Default `scene`. */
+    label?: string;
+    /** Aux attachments; none by default (the target writes identical bytes to before). */
+    aux?: SceneTargetAux;
+}
+/** A rect in texture pixels, origin top-left. */
+export interface SceneTargetViewport {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * Textures a `SceneTarget.external` target adopts instead of allocating (ws/xr): the colour
+ * texture an `XRProjectionLayer` hands out per eye per frame and, when the layer has one, its
+ * depth texture. The target never destroys them. `color` must be `SCENE_FORMAT`, since every
+ * material's pipeline writes it, and `depth` `DEPTH_FORMAT`; `view` is the view descriptor
+ * (array layer, mip) both are read through, for a texture-array layer. `viewport` is the part
+ * of the texture these views draw into, recorded on the target for its caller (the renderer
+ * takes the viewport from `camera.screen`).
+ */
+export interface SceneTargetExternal {
+    device: GPUDevice;
+    color: GPUTexture;
+    depth?: GPUTexture | null;
+    view?: GPUTextureViewDescriptor;
+    viewport?: SceneTargetViewport;
+    /** Prefix of the labels of what the target still allocates (emissive, depth). Default `external`. */
+    label?: string;
+    /** Aux attachments, allocated at the adopted size (`SceneTargetDesc.aux`). */
+    aux?: SceneTargetAux;
+}
+/**
+ * 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 declare class SceneTarget {
+    private readonly device;
+    color: Texture;
+    emissive: Texture;
+    /** The `rg8unorm` roughness/metalness attachment (`aux.roughMetal`), else null. */
+    roughMetal: Texture | null;
+    /** The `rg16float` screen-space velocity attachment (`aux.velocity`), else null. */
+    velocity: Texture | null;
+    /** Bit 0: has `roughMetal`; bit 1: has `velocity`. Keys material pipeline variants. */
+    readonly auxKey: number;
+    width: number;
+    height: number;
+    /**
+     * 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: SceneTargetViewport | null;
+    /** The scene pass descriptor for this target; the renderer sets its load ops per view. */
+    readonly passDesc: GPURenderPassDescriptor;
+    readonly colorAtt: GPURenderPassColorAttachment;
+    readonly emissiveAtt: GPURenderPassColorAttachment;
+    readonly depthAtt: GPURenderPassDepthStencilAttachment;
+    /** The blended half of a split view: the same attachments, every load op `load`. */
+    readonly blendPassDesc: GPURenderPassDescriptor;
+    private readonly blendColorAtt;
+    private readonly blendEmissiveAtt;
+    /** Aux attachments in order (rough-metal, velocity), for the clear and the blend pass. */
+    private readonly auxAtts;
+    private readonly blendAuxAtts;
+    private readonly blendDepthAtt;
+    private depthTex;
+    private depthCopyTex;
+    /** `copyDepth`'s reused copy descriptors (no allocation per frame). */
+    private readonly copySrc;
+    private readonly copyDst;
+    private readonly copySize;
+    private readonly label;
+    /** The adopted colour texture of an external target; null for an allocated one. */
+    private externalColor;
+    /** The adopted depth texture of an external target, when its layer has one. */
+    private externalDepth;
+    private adoptedLayer;
+    /** `external`: internal, set by `SceneTarget.external`; the textures then come from `adopt`. */
+    constructor(device: GPUDevice, desc: SceneTargetDesc, external?: boolean);
+    /** A target over textures owned by someone else (an XR layer's); see `SceneTargetExternal`. */
+    static external(desc: SceneTargetExternal): SceneTarget;
+    /** True for a target made by `SceneTarget.external`. */
+    get isExternal(): boolean;
+    /** The adopted colour texture of an external target; null for an allocated one. */
+    get adoptedColor(): GPUTexture | null;
+    /**
+     * 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(): Texture | null;
+    /**
+     * 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(): Texture | null;
+    /** Whether `depth` can be the source of a copy (an adopted texture may lack `COPY_SRC`). */
+    get canCopyDepth(): boolean;
+    /**
+     * 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: Omit<SceneTargetExternal, 'device' | 'label'>): void;
+    /** Recreate the textures at a new size (no-op when unchanged). Returns whether they changed. */
+    resize(width: number, height: number): boolean;
+    /** Load op of the aux attachments for the next scene pass (the renderer: clear on first view). */
+    setAuxLoadOp(op: GPULoadOp): void;
+    /** (Re)create the aux attachments at `w × h`. */
+    private resizeAux;
+    /**
+     * 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(): GPURenderPassDepthStencilAttachment;
+    /**
+     * `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(): Texture | null;
+    /**
+     * 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: GPUCommandEncoder): Texture | null;
+    destroy(): void;
+}