@driftengine/core 3.62.0 → 4.0.0

package/dist/render/backend/materialChanges.d.ts

@@ -0,0 +1,41 @@
+/**
+ * What counts as a material change: the rule both backends count their `materials` line by.
+ *
+ * **A material is the shading state a draw reads that is not its own placement**, and the WebGPU
+ * backend keeps it in a ring of per-frame slots: a draw copies the open material into a new slot
+ * when something has changed it since the last draw, and otherwise shares the slot before it. So
+ * the slots a frame takes are its material changes, and that is what the backend's ceiling
+ * rations. WebGL2 sets the same state as loose uniforms and has nothing to run out of — but a
+ * consumer developing there is building the frame the other backend will ration, so it counts the
+ * same changes by the same rule, and draws them all.
+ *
+ * **What changes it**: a material setter; the start of a frame or of a mesh pass, which reopens
+ * the pass's own material; a probe bake, which sets its own and puts the pass's back; and a draw
+ * carrying options of its own (`ownsMaterial`), whose state is written for it and restored after
+ * it, so that it and the draw after it each open one.
+ *
+ * What it gives up: a setter called with the value already set still counts, because it takes a
+ * slot on the backend that keeps slots, and comparing every field would cost more than the slot.
+ */
+/** What of a draw's own options its material carries. */
+export interface DrawMaterialOptions {
+    readonly opacity: number;
+    readonly lit: boolean;
+    readonly fog: boolean;
+    readonly toneMapped: boolean;
+    /** Whether the draw refracts this time, which a backend decides by whether it has a snapshot. */
+    readonly refracting: boolean;
+}
+/** Whether a draw's options differ from the pass's, so it takes a material and leaves one to restore. */
+export declare function ownsMaterial(options: DrawMaterialOptions): boolean;
+/** Whether the next draw shares the open material or opens a new one. */
+export declare class MaterialChanges {
+    /**
+     * The slot the open material occupies on a backend that keeps slots, or -1 when the next draw
+     * opens one. A backend without slots writes 0 when it opens one.
+     */
+    slot: number;
+    get open(): boolean;
+    /** Something the material holds changed, or a pass reopened it: the next draw opens a new one. */
+    dirty(): void;
+}

package/dist/render/backend/materialChanges.js

@@ -0,0 +1,38 @@
+/**
+ * What counts as a material change: the rule both backends count their `materials` line by.
+ *
+ * **A material is the shading state a draw reads that is not its own placement**, and the WebGPU
+ * backend keeps it in a ring of per-frame slots: a draw copies the open material into a new slot
+ * when something has changed it since the last draw, and otherwise shares the slot before it. So
+ * the slots a frame takes are its material changes, and that is what the backend's ceiling
+ * rations. WebGL2 sets the same state as loose uniforms and has nothing to run out of — but a
+ * consumer developing there is building the frame the other backend will ration, so it counts the
+ * same changes by the same rule, and draws them all.
+ *
+ * **What changes it**: a material setter; the start of a frame or of a mesh pass, which reopens
+ * the pass's own material; a probe bake, which sets its own and puts the pass's back; and a draw
+ * carrying options of its own (`ownsMaterial`), whose state is written for it and restored after
+ * it, so that it and the draw after it each open one.
+ *
+ * What it gives up: a setter called with the value already set still counts, because it takes a
+ * slot on the backend that keeps slots, and comparing every field would cost more than the slot.
+ */
+/** Whether a draw's options differ from the pass's, so it takes a material and leaves one to restore. */
+export function ownsMaterial(options) {
+    return (options.opacity < 1 || !options.lit || !options.fog || !options.toneMapped || options.refracting);
+}
+/** Whether the next draw shares the open material or opens a new one. */
+export class MaterialChanges {
+    /**
+     * The slot the open material occupies on a backend that keeps slots, or -1 when the next draw
+     * opens one. A backend without slots writes 0 when it opens one.
+     */
+    slot = -1;
+    get open() {
+        return this.slot >= 0;
+    }
+    /** Something the material holds changed, or a pass reopened it: the next draw opens a new one. */
+    dirty() {
+        this.slot = -1;
+    }
+}

package/dist/render/backend/select.js

@@ -160,11 +160,19 @@ async function acquireWebGpu(gpu, wantsGpuTiming, shaders, stage) {
          * the default still refuses the model, and `WebGPURenderer.createMesh` says so in one line
          * rather than letting the driver say it a hundred times.
          */
+        /*
+         * **And the storage binding ceiling, for the same reason one level down.** A buffer that can be
+         * created is not a buffer that can be bound: `maxStorageBufferBindingSize` defaults to 128 MiB
+         * against this machine's 4 GiB, and the GPU-driven pipeline binds its whole vertex buffer as
+         * one storage binding. The voxel sandbox's port at a radius of ten asked for 262,807,200 bytes
+         * and came back as a hundred device warnings and a world with no terrain.
+         */
         const required = {};
         for (const limit of [
             'maxSampledTexturesPerShaderStage',
             'maxSamplersPerShaderStage',
             'maxBufferSize',
+            'maxStorageBufferBindingSize',
         ]) {
             const ceiling = adapter.limits[limit];
             if (typeof ceiling === 'number' && ceiling > 0)

package/dist/render/backend/webgl2/renderer.d.ts

@@ -4,6 +4,7 @@ import type { Camera } from '../../camera.ts';
 import type { PickHit, PickableSource } from '../../pickable.ts';
 import type { ReflectiveSurface } from '../../screenSpaceReflection.ts';
 import type { DecalProjector } from '../../decalProjector.ts';
+import type { FieldSource } from '../../gi/globalField.ts';
 import type { Bounds } from '../../../math/bounds.ts';
 import type { ComputeDefinition, ComputeHandle } from '../../compute.ts';
 import type { PassDefinition, PassHandle } from '../../pass.ts';
@@ -1067,6 +1068,13 @@ export declare class WebGL2Renderer implements RendererApi {
     reversedDepth: boolean;
     /** `GL_DEPTH_REMAP * camera.viewProjection`, rebuilt once a frame. */
     private readonly sceneViewProj;
+    /**
+     * The same matrix with clip y negated, for the six faces of a probe.
+     *
+     * Its own buffer rather than `sceneViewProj`, because `cubeFaceProjection` reads what
+     * `sceneMatrix` just wrote and the two would be the same array.
+     */
+    private readonly cubeFaceViewProj;
     /**
      * One buffer per shadow matrix that outlives a call, and that is not fussiness.
      *
@@ -1210,6 +1218,29 @@ export declare class WebGL2Renderer implements RendererApi {
      * visible, which is a hole in the world. `OcclusionBuffer` carries the rest of the reasoning.
      */
     addOccluder(min: ArrayLike<number>, max: ArrayLike<number>, model: ReadonlyMat4): void;
+    /**
+     * Declare a baked distance field that indirect light may be traced against.
+     *
+     * **Recorded by nothing on this backend, and that is the refusal rather than an oversight.**
+     * Composing the world's field and marching probes through it is compute, and WebGL2 has no
+     * compute stage — `INDIRECT_LIGHT_WEBGL2_REFUSAL` says so once a frame-loop when
+     * `quality.indirectLight` is on. The method exists here because `RendererApi` is this class's
+     * shape, and a consumer that declares its fields unconditionally must not have to ask which
+     * backend it got: this is a no-op for the same reason `addOccluder` is one when the profile
+     * asked for no occlusion buffer.
+     *
+     * The field is in the model matrix's own space and the matrix must carry uniform scale only.
+     * `composeGlobalField` gives the reason: a distance is not preserved by a non-uniform scale.
+     */
+    addDistanceField(_field: FieldSource, _model: ReadonlyMat4, _albedo?: ArrayLike<number>): void;
+    /** Forget the fields declared this frame. A no-op here, as `addDistanceField` is. */
+    clearDistanceFields(): void;
+    /** Never measured here, because nothing is composed. See `addDistanceField`. */
+    get distanceFieldMs(): number | null;
+    /** Never traced here either, so there is no refresh to time. See `addDistanceField`. */
+    get indirectBakeMs(): number | null;
+    /** Nothing to read, for the same reason. A consumer may call it unconditionally. */
+    readDistanceFieldTimings(): void;
     /**
      * Whether a mesh is entirely behind the occluders declared this frame.
      *
@@ -2052,6 +2083,17 @@ export declare class WebGL2Renderer implements RendererApi {
     beginPlanarReflection(source: Camera, planeY: number, clearColor: Vec3): Camera | null;
     endPlanarReflection(): void;
     get aspect(): number;
+    /**
+     * The size the world is drawn at, which on this backend is always the drawing buffer.
+     *
+     * **Here so that a contributed pass has one question to ask on both backends.** WebGPU can draw
+     * the world smaller than the canvas and let its composite enlarge it — `quality.reconstruction`
+     * — and a pass filling a target of its own has to follow that size or draw a picture the frame
+     * pass clips. This backend has no compute stage and no reconstruction, so the answer never moves;
+     * a pass that reads it is correct on both, and one that reads `canvas.width` is correct on one.
+     */
+    get sceneWidth(): number;
+    get sceneHeight(): number;
     /**
      * Point rendering back at the frame's own target, whole.
      *
@@ -2609,6 +2651,20 @@ export declare class WebGL2Renderer implements RendererApi {
      */
     private readonly budget;
     private readonly drawBudget;
+    /**
+     * Every line the other backend declares, in its order and with none of its ceilings.
+     *
+     * **Counted after the same guards**, so one scene reports one number on both: the verbs each
+     * ask once they are past the checks that make them draw nothing on either backend — a panel
+     * with no alpha, a string with no glyphs, a beam with no strength, a calm wind — and a material
+     * change is counted by the rule both share (`materialChanges.ts`). `webgpu/renderer.test.ts`
+     * runs one scene through both and compares every line.
+     */
+    private readonly materialBudget;
+    /** Whether the next mesh draw shares the open material or opens one, by the rule both count. */
+    private readonly materials;
+    /** A mesh draw: counted as a material change when something has changed the material since. */
+    private takeMaterial;
     /**
      * Declared here and never asked, because this backend builds none.
      *
@@ -2620,6 +2676,19 @@ export declare class WebGL2Renderer implements RendererApi {
      * being compared against should also be zero once the other backend's cache is warm.
      */
     private readonly bindGroupBudget;
+    private readonly shadowDrawBudget;
+    private readonly scatterDepthBudget;
+    private readonly waterBudget;
+    private readonly lightVolumeBudget;
+    private readonly windStreakBudget;
+    private readonly flockBudget;
+    private readonly boltBudget;
+    private readonly causticsBudget;
+    private readonly textBudget;
+    private readonly sdfTextBudget;
+    private readonly lineBudget;
+    /** The other backend's panel ceiling, reported here as a count with none. */
+    private readonly panelBudget;
     /** What the frame just drawn asked for. See `budget.ts`, and the note on `budget` above. */
     get frameBudget(): FrameBudget;
     /**
@@ -2677,6 +2746,8 @@ export declare class WebGL2Renderer implements RendererApi {
      * from one `RenderQuality` — see `OIT_MULTISAMPLE_REFUSAL` for why it is a constant and not two
      * literals kept in step by hand.
      */
+    /** Said once rather than every frame, as the translucent set's own refusal is. */
+    private indirectLightRefused;
     private refuseOitMultisampled;
     beginFrame(clearColor: Vec3): void;
     /**
@@ -2794,7 +2865,15 @@ export declare class WebGL2Renderer implements RendererApi {
      * rebuilding vertex data every frame. Reset to white after the call, so a caller that
      * passes one cannot leak it into the next draw.
      */
-    tint?: Vec3 | null): void;
+    tint?: Vec3 | null, 
+    /**
+     * Where the mesh was last frame, which this backend takes and ignores.
+     *
+     * Accepted rather than absent so that one scene draws through both renderers unchanged — the
+     * parity rule this repository is built on. Reconstruction is WebGPU's, having no compute stage
+     * here, so there is no motion target for this to be written into.
+     */
+    _previousModel?: ReadonlyMat4 | null): void;
     /**
      * Draw a mesh you can see through, in the same material as everything else by default.
      *