@driftengine/core 4.8.5 → 4.8.7

package/dist/render/backend/webgpu/particlePass.js

@@ -2,6 +2,9 @@ import { DEPTH_COMPARE } from '../../depthConvention.js';
 import { particleShaders } from '../../particleMaterial.js';
 import { PARTICLE_BINDINGS } from '../../shaders/generated/particle.wgsl.js';
 import { PARTICLE_BLADES, PARTICLE_INDICES, PARTICLE_VERTS } from '../../shaders/particle.js';
+import { DEVICE_PARTICLE_FLOATS } from '../../particlePool.js';
+import { packSpriteStream } from '../../particleBatch.js';
+import { createParticleSort } from '../../particleSort.js';
 import { DEPTH_FORMAT } from './flatPass.js';
 import { shaderModule } from './shaderModules.js';
 import { SCENE_ALPHA_COVERS } from '../../sceneCoverage.js';
@@ -22,7 +25,9 @@ export function particleFragBindings(material) {
         ? PARTICLE_BINDINGS.PARTICLE_SPARK_FRAG
         : material === 'mote'
             ? PARTICLE_BINDINGS.PARTICLE_MOTE_FRAG
-            : PARTICLE_BINDINGS.PARTICLE_SMOKE_FRAG;
+            : material === 'sprite'
+                ? PARTICLE_BINDINGS.PARTICLE_SPRITE_FRAG
+                : PARTICLE_BINDINGS.PARTICLE_SMOKE_FRAG;
     return { fields: stage.fields, size: stage.uniformSize };
 }
 const VISIBILITY_VERTEX = 0x1;
@@ -31,17 +36,17 @@ const USAGE_VERTEX = 0x0020 | 0x0008;
 const USAGE_INDEX = 0x0010 | 0x0008;
 const USAGE_UNIFORM_DST = 0x0040 | 0x0008;
 /**
- * Ten attributes and eight slots, so the per-instance eight share one buffer.
+ * Eleven attributes and eight slots, so the per-instance nine share one buffer.
  *
- * **`maxVertexBuffers` is eight and this shader declares ten inputs**, so something has to
- * interleave. The per-instance streams are the ones that do: the engine holds them as eight
- * separate arrays and they are packed into one interleaved buffer per frame, which is a copy
- * the upload was already paying per stream rather than new work.
+ * **`maxVertexBuffers` is eight and this shader declares eleven inputs**, so something has to
+ * interleave. The per-instance streams are the ones that do: the engine holds them as separate
+ * arrays and they are packed into one interleaved buffer per frame, which is a copy the upload
+ * was already paying per stream rather than new work.
  *
  * Floats per instance, in the order they are packed: position 3, size 1, spin 1, colour 3,
- * alpha 1, age 1, seed 1, velocity 3.
+ * alpha 1, age 1, seed 1, velocity 3, and a sprite's frame and half-height 2.
  */
-const INSTANCE_FLOATS = 14;
+const INSTANCE_FLOATS = DEVICE_PARTICLE_FLOATS;
 const INSTANCE_ATTRIBUTES = [
     { shaderLocation: 2, offset: 0, format: 'float32x3' },
     { shaderLocation: 3, offset: 12, format: 'float32' },
@@ -51,6 +56,7 @@ const INSTANCE_ATTRIBUTES = [
     { shaderLocation: 7, offset: 36, format: 'float32' },
     { shaderLocation: 8, offset: 40, format: 'float32' },
     { shaderLocation: 9, offset: 44, format: 'float32x3' },
+    { shaderLocation: 10, offset: 56, format: 'float32x2' },
 ];
 export function particleVertexLayouts() {
     return [
@@ -87,7 +93,7 @@ export function particleVertexLayouts() {
  * written last. `layout` still comes from the caller and is shared per material: it is
  * structural, not data, so nothing about sharing it can go stale mid-frame.
  */
-export function createGpuParticles(device, capacity, material, blend, stretchSec, facing, erosion, coreGain, fog, layout, fragFields, fragSize) {
+export function createGpuParticles(device, capacity, material, blend, stretchSec, facing, erosion, coreGain, fog, layout, fragFields, fragSize, sprite = null) {
     /* The cross, built once: two blades of four corners, interleaved with the blade index. */
     const corners = new Float32Array(PARTICLE_VERTS * 3);
     const CORNERS = [
@@ -158,7 +164,17 @@ export function createGpuParticles(device, capacity, material, blend, stretchSec
         erosion,
         coreGain,
         fog,
+        texture: sprite?.texture ?? null,
+        cells: sprite?.cells ?? [1, 1],
+        blendCells: sprite?.blendCells ?? false,
+        softDepth: sprite?.softDepth ?? 0,
+        cameraFade: sprite?.cameraFade ?? 0,
+        cameraOffset: sprite?.cameraOffset ?? 0,
+        order: sprite?.sort === true ? createParticleSort(capacity) : null,
+        spriteGroup: null,
+        spriteGroupDepth: null,
         staging: new Float32Array(capacity * INSTANCE_FLOATS),
+        spriteStaging: new Float32Array(capacity * 2),
         vertUniforms,
         fragUniforms,
         vertStaging,
@@ -167,7 +183,9 @@ export function createGpuParticles(device, capacity, material, blend, stretchSec
         fragFloats: new Float32Array(fragStaging),
         fragInts: new Int32Array(fragStaging),
         fields: fragFields,
-        bindGroup: createParticleBindGroup(device, layout, vertUniforms, fragUniforms, fragSize),
+        bindGroup: material === 'sprite'
+            ? null
+            : createParticleBindGroup(device, layout, vertUniforms, fragUniforms, fragSize),
         dispose() {
             cornerBuffer.destroy();
             instances.destroy();
@@ -186,6 +204,8 @@ export function createGpuParticles(device, capacity, material, blend, stretchSec
 export function packInstances(batch, data) {
     const n = Math.min(data.count, batch.capacity);
     const out = batch.staging;
+    /* The sprite's frame and half-height, two floats a particle, woven in below. */
+    packSpriteStream(data, n, batch.spriteStaging);
     for (let i = 0; i < n; i++) {
         const o = i * INSTANCE_FLOATS;
         const p = i * 3;
@@ -203,12 +223,17 @@ export function packInstances(batch, data) {
         out[o + 11] = data.velocities[p];
         out[o + 12] = data.velocities[p + 1];
         out[o + 13] = data.velocities[p + 2];
+        out[o + 14] = batch.spriteStaging[i * 2];
+        out[o + 15] = batch.spriteStaging[i * 2 + 1];
     }
     return n;
 }
-export function createParticleBindGroupLayout(device, fragSize) {
+/** The floats `packInstances` writes per particle, for the caller's upload. */
+export const PARTICLE_INSTANCE_FLOATS = INSTANCE_FLOATS;
+export function createParticleBindGroupLayout(device, fragSize, sprite = false) {
+    const textures = PARTICLE_BINDINGS.PARTICLE_SPRITE_FRAG.textures;
     return device.createBindGroupLayout({
-        label: 'particle.layout',
+        label: sprite ? 'particle.layout:sprite' : 'particle.layout',
         entries: [
             {
                 binding: VERT_BINDING,
@@ -220,6 +245,50 @@ export function createParticleBindGroupLayout(device, fragSize) {
                 visibility: VISIBILITY_FRAGMENT,
                 buffer: { type: 'uniform', minBindingSize: fragSize },
             },
+            /* The image, filtered, and the frame's depth copy, read texel for texel. */
+            ...(sprite
+                ? [
+                    {
+                        binding: textures.uSprite.texture,
+                        visibility: VISIBILITY_FRAGMENT,
+                        texture: { sampleType: 'float', viewDimension: '2d-array' },
+                    },
+                    {
+                        binding: textures.uSprite.sampler,
+                        visibility: VISIBILITY_FRAGMENT,
+                        sampler: { type: 'filtering' },
+                    },
+                    {
+                        binding: textures.uDepth.texture,
+                        visibility: VISIBILITY_FRAGMENT,
+                        texture: { sampleType: 'unfilterable-float' },
+                    },
+                    {
+                        binding: textures.uDepth.sampler,
+                        visibility: VISIBILITY_FRAGMENT,
+                        sampler: { type: 'non-filtering' },
+                    },
+                ]
+                : []),
+        ],
+    });
+}
+/**
+ * A sprite batch's bind group: its uniforms, its image, and the frame's depth copy — or any
+ * single-sample float texture standing in, where the batch asks for no soft edge.
+ */
+export function createSpriteBindGroup(device, layout, batch, fragSize, depth, linear, nearest) {
+    const textures = PARTICLE_BINDINGS.PARTICLE_SPRITE_FRAG.textures;
+    return device.createBindGroup({
+        label: 'particle.bindGroup:sprite',
+        layout,
+        entries: [
+            { binding: VERT_BINDING, resource: { buffer: batch.vertUniforms, size: PARTICLE_VERT_SIZE } },
+            { binding: FRAG_BINDING, resource: { buffer: batch.fragUniforms, size: fragSize } },
+            { binding: textures.uSprite.texture, resource: batch.texture },
+            { binding: textures.uSprite.sampler, resource: linear },
+            { binding: textures.uDepth.texture, resource: depth },
+            { binding: textures.uDepth.sampler, resource: nearest },
         ],
     });
 }

package/dist/render/backend/webgpu/postPass.d.ts

@@ -180,7 +180,12 @@ export declare const PREMULTIPLIED_OVER_BLEND: GPUBlendState;
  * the reflection's own and its alpha is the coverage this resolve reads.
  */
 export declare const REFLECTION_OVER_BLEND: GPUBlendState;
-export declare const ADDITIVE_BLEND: GPUBlendState;
+/**
+ * The bloom pyramid's way back up: an octave added onto a level that the blend multiplies by that
+ * level's tint first — the blend constant, which white makes `one, one` exactly. Into the pyramid's
+ * own levels, never the scene. See `BloomResponse`.
+ */
+export declare const TINTED_ADD_BLEND: GPUBlendState;
 /** A fullscreen pass over one or more inputs, writing to one colour target. */
 export declare function postPipeline(cache: PipelineCache, device: GPUDevice, layout: GPUBindGroupLayout, key: string, fragment: string, format: GPUTextureFormat, blend?: GPUBlendState): GPURenderPipeline;
 /**

package/dist/render/backend/webgpu/postPass.js

@@ -252,8 +252,13 @@ export const REFLECTION_OVER_BLEND = {
     color: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
     alpha: SCENE_ALPHA_KEEPS,
 };
-export const ADDITIVE_BLEND = {
-    color: { srcFactor: 'one', dstFactor: 'one', operation: 'add' },
+/**
+ * The bloom pyramid's way back up: an octave added onto a level that the blend multiplies by that
+ * level's tint first — the blend constant, which white makes `one, one` exactly. Into the pyramid's
+ * own levels, never the scene. See `BloomResponse`.
+ */
+export const TINTED_ADD_BLEND = {
+    color: { srcFactor: 'one', dstFactor: 'constant', operation: 'add' },
     alpha: { srcFactor: 'one', dstFactor: 'one', operation: 'add' },
 };
 /** A fullscreen pass over one or more inputs, writing to one colour target. */

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

@@ -8,6 +8,8 @@ import type { RendererApi } from '../api.ts';
 import { GpuTimestamps } from './gpuTimestamps.ts';
 import type { Environment, FilmOptions, InsetRect, LightVolumeDrawOptions, SkyColors, TranslucentMeshOptions } from '../webgl2/renderer.ts';
 import type { IncrementalMeshHandle, MeshOptions } from '../api.ts';
+import type { LightmapPage } from '../../lightmap.ts';
+import { type BloomResponse } from '../../bloomChain.ts';
 import type { WaterBody } from '../../waterRenderer.ts';
 import type { WindStreakOptions } from '../../windStreakRenderer.ts';
 import type { WindField } from '../../windField.ts';
@@ -33,8 +35,8 @@ import type { CausticSheet } from '../../causticsRenderer.ts';
 import { type GpuCaustics } from './causticsPass.ts';
 import type { BoltSegments } from '../../boltPool.ts';
 import type { LineSegments } from '../../linePoints.ts';
-import type { ParticleBatchOptions } from '../../particleBatch.ts';
-import type { ParticleInstances } from '../../particlePool.ts';
+import { type ParticleBatchOptions } from '../../particleBatch.ts';
+import type { DeviceParticles, ParticleInstances } from '../../particlePool.ts';
 import type { PlumeOptions, PlumePlacement } from '../../plumeRenderer.ts';
 import type { InstanceData } from '../../instancedMesh.ts';
 import { type RenderQuality } from '../../renderQuality.ts';
@@ -518,6 +520,17 @@ export declare class WebGPURenderer implements RendererApi {
     /** Whether this frame has spread its skin: once, at its first blended draw or before its end. */
     private skinScattered;
     private readonly skinInverseProjection;
+    /** Scratch for a sprite's depth conversion, so a particle draw allocates nothing. */
+    private readonly spriteInverseProjection;
+    /** Said once: a sprite asked for a soft edge where no depth copy could be had. */
+    private warnedSpriteDepth;
+    /** Said once: more rectangles than the fixed arm shades, and no froxel table for the rest. */
+    private warnedAreaOverflow;
+    /** What a sprite's depth binding holds where no copy was taken. See `spriteDepthStandIn`. */
+    private spriteDepthEmpty;
+    /** The samplers every sprite batch binds: its image filtered, the depth copy texel for texel. */
+    private spriteLinearSampler;
+    private spriteNearestSampler;
     private sceneColorView;
     /** The multisampled twin, when the profile asks for samples. Resolved into `sceneColor`. */
     private sceneColorMsaa;
@@ -1171,6 +1184,29 @@ export declare class WebGPURenderer implements RendererApi {
     get compressedFormats(): readonly CompressedTextureFormat[];
     /** Several images of one size as an array's layers. See `RendererApi.createSurfaceTextureArray`. */
     createSurfaceTextureArray(sources: readonly SurfaceSource[], options?: SurfaceTextureOptions): GpuSurfaceTexture;
+    /** A baked lightmap page, as a `lightmapModel` material's `modelMap`. See `RendererApi`. */
+    createLightmap(page: LightmapPage): GpuSurfaceTexture;
+    /**
+     * A texture the scene can be drawn into, for a material to show. See `RendererApi` and
+     * `sceneCapture.ts`. At the world's own format, which under `hdrScene` is half floats.
+     */
+    createSceneCapture(width: number, height: number): GpuSurfaceTexture;
+    /** Each capture's attachments, beside the texture a material binds. */
+    private readonly captureTargets;
+    /**
+     * Whether a scene capture is being drawn: an off-screen pass as a probe bake is, so the frame's
+     * camera, jitter, motion, refraction copy, skin's spread and late routing are left alone, but
+     * lit by the probes and DriftLight as the frame is. See `captureScene`.
+     */
+    private capturePassActive;
+    /**
+     * Draw the scene into a capture from `camera`. See `RendererApi.captureScene`.
+     *
+     * **Its own encoder, as a probe bake's**: the frame's pass is set aside and restored, the rings
+     * are marked and rewound around the submit, and the frame graph is flushed at both boundaries so
+     * no recorded draw crosses one. **Radiance**: the output transform and exposure are held off.
+     */
+    captureScene(capture: GpuSurfaceTexture, camera: Camera, clearColor: Vec3, draw: (camera: Camera) => void): boolean;
     /**
      * GPU textures an `updateSurfaceTexture` replaced, destroyed when the next frame begins.
      *
@@ -1278,6 +1314,11 @@ export declare class WebGPURenderer implements RendererApi {
      * it is on the public surface and removing it would break four repositories to save a method.
      */
     setEnvironmentAmbient(_amount: number): void;
+    /**
+     * The ambient the following draws take, nine spherical-harmonic coefficients or null for the
+     * frame's. See `Renderer.setAmbientSH`: material state, so the next draw takes a slot of its own.
+     */
+    setAmbientSH(coefficients: ArrayLike<number> | null): void;
     /** How reflective the surfaces drawn next are. Clamped, as `renderer.ts` clamps it. */
     setSurfaceReflectivity(amount: number): void;
     /** How bright the environment the surfaces drawn next reflect is. See `renderer.ts`. */
@@ -1428,6 +1469,31 @@ export declare class WebGPURenderer implements RendererApi {
     private gradeCode;
     private gradeExposure;
     drawParticles(batch: GpuParticles, data: ParticleInstances, camera: Camera, env: Environment, timeSeconds: number): void;
+    /**
+     * Draw particles a caller's own compute wrote, where they lie. See `DeviceParticles`.
+     *
+     * **The pool's draw with its instance stream swapped**: the same material, blend, flipbook, soft
+     * edge and fog, reading the caller's buffer in place of the one the pool uploads into — so nothing
+     * crosses back to the CPU. Not sorted, and a count past what the buffer holds is cut to it rather
+     * than handed to a draw the device would refuse with the frame.
+     */
+    drawDeviceParticles(batch: GpuParticles, particles: DeviceParticles, camera: Camera, env: Environment, timeSeconds: number): void;
+    /** A pool's uniforms for this view, and its draw from `instances`: both entry points' tail. */
+    private drawParticleInstances;
+    /**
+     * A sprite's flipbook and fades into its fragment block `f`, and the bind group holding the
+     * frame's depth copy its soft edge reads — built again only when that copy is replaced.
+     *
+     * **The copy is the volume's**: `takeVolumeDepth` ends the frame's pass, resolves the opaque
+     * depth and reopens, once a frame whoever asks. Only in the frame's own picture: in a mirror or
+     * a probe's face it would be another view's depth, and the edge stays hard there, as on WebGL2.
+     * Without a composite there is no copy, and the renderer says so once.
+     */
+    private spriteFades;
+    /** A sprite's image sampler, repeating nothing and filtered, or its depth's, nearest. */
+    private spriteSampler;
+    /** A one-texel `r32float` for a sprite's depth binding where no copy was taken. */
+    private spriteDepthStandIn;
     /**
      * The bind group layout for one particle material, built on first use.
      *
@@ -1733,6 +1799,8 @@ export declare class WebGPURenderer implements RendererApi {
     private writeWind;
     /** Refilled per frame rather than allocated; see `resolvePointLights`. */
     private readonly lights;
+    /** The fixed arm's rectangles as `uAreaLightSize` holds them. See `packAreaSizesAndDoors`. */
+    private readonly areaSizesAndDoors;
     /** Refilled per frame rather than allocated; see `resolveAtmosphere`. */
     private readonly medium;
     private readonly panelLayout;
@@ -2159,7 +2227,7 @@ export declare class WebGPURenderer implements RendererApi {
      * drawn. It also handed the caller a different object from the one the upload was filling.
      */
     private keyed;
-    createMesh(data: MeshData, options?: MeshOptions): GpuMesh;
+    createMesh(given: MeshData, options?: MeshOptions): GpuMesh;
     /**
      * Geometry in, handle out — but the geometry lands over as many frames as the caller gives it.
      *
@@ -2169,7 +2237,7 @@ export declare class WebGPURenderer implements RendererApi {
      * straddle one, and going on writing to a dead device would raise validation errors a consumer
      * can do nothing about. Done with `complete` still false is the signal that it was abandoned.
      */
-    createMeshIncremental(data: MeshData, options?: MeshOptions): IncrementalMeshHandle;
+    createMeshIncremental(given: MeshData, options?: MeshOptions): IncrementalMeshHandle;
     /**
      * Rewrite a mesh's positions, and its normals where the caller has them.
      *
@@ -2943,9 +3011,10 @@ export declare class WebGPURenderer implements RendererApi {
      */
     private skinSplits;
     /**
-     * A skin draw's diffuse half, kept for the spread: the frame's draw again, with the same slots,
-     * buffers and bind group, through the pipeline that writes the diffuse alone into the blur's
-     * target and tests for the depth its frame half wrote.
+     * A skin draw's diffuse and colour halves, kept for the spread: the frame's draw again, twice,
+     * with the same slots, buffers and bind group, through the pipelines that write the diffuse's
+     * light alone and its colour alone into the blur's targets and test for the depth its frame half
+     * wrote.
      */
     private keepSkinDiffuse;
     /**
@@ -3516,6 +3585,14 @@ export declare class WebGPURenderer implements RendererApi {
     /** This frame's exposure into the tone curve. Starts at the profile's own. */
     private exposure;
     private bloomScale;
+    /** The draw's own ambient, as `packAmbientSH` writes it; zeros are the frame's. */
+    private readonly ambientSH;
+    /** The ramp and each level's tint, as `resolveBloomResponse` writes them; the subtraction and white. */
+    private readonly bloomResponse;
+    /** The response before the last `setBloom`, to tell whether the blocks need writing again. */
+    private readonly bloomResponseNext;
+    /** Each level's tint as a blend constant, rewritten in place: `setBlendConstant` takes a colour. */
+    private readonly bloomConstants;
     /** In scene units, once `setBloom` has moved it; null reads the profile's. */
     private bloomThresholdSet;
     private rushStrength;
@@ -3579,7 +3656,7 @@ export declare class WebGPURenderer implements RendererApi {
      * a 3D write needs both and a wrong one silently shears the cube.
      */
     private uploadGrade;
-    setBloom(scale: number, threshold?: number): void;
+    setBloom(scale: number, threshold?: number, response?: BloomResponse | null): void;
     /**
      * How thick the air is, this frame: a global participating medium filling the whole frustum.
      *
@@ -3883,6 +3960,14 @@ export declare class WebGPURenderer implements RendererApi {
         readonly height: number;
         readonly data: Float32Array;
     }, options?: ProbeBakeOptions): boolean;
+    /** One layer of the declared grid from an image. See `Renderer.setProbeLayerImage`. */
+    setProbeLayerImage(layer: number, image: {
+        readonly width: number;
+        readonly height: number;
+        readonly data: Float32Array;
+    }, options?: ProbeBakeOptions): boolean;
+    /** An equirectangular image onto the capture cube's six faces, in the cube's own format. */
+    private uploadProbeFaces;
     /**
      * Upload the photometric profiles a consumer loaded, and rebuild the bind group that holds them.
      *