@woosh/meep-engine 3.32.0 → 3.34.0

package/src/engine/graphics3/particles/GPUParticularRenderer.js

@@ -1,627 +0,0 @@
-import { assert } from "../../../core/assert.js";
-import { round_up } from "../../../core/math/round_up.js";
-import { TextureDescriptor } from "../../../shade/descriptor/texture/TextureDescriptor.js";
-import { TextureViewDescriptor } from "../../../shade/descriptor/texture/TextureViewDescriptor.js";
-import { GPUDatabase } from "../../../shade/renderer/buffer/table/GPUDatabase.js";
-import {
-    PARTICLE_DATABASE_INITIAL_SIZE,
-    PARTICLE_DATABASE_SPEC,
-    PARTICLE_EMITTER_TABLE
-} from "../../../shade/renderer/particles/data/PARTICLE_DATABASE_SPEC.js";
-import { PARTICLE_RECORD_WORD_COUNT } from "../../../shade/renderer/particles/ParticleConstants.js";
-import {
-    create_particle_billboard_pipeline,
-    PARTICLE_BILLBOARD_RESOURCES
-} from "../../../shade/renderer/particles/shaders/shader_particle_render.js";
-import { DEFAULT_DEPTH_TEXTURE_VIEW } from "../../../shade/renderer/depth/DEFAULT_DEPTH_TEXTURE_VIEW.js";
-import { SAMPLER_LINEAR_UPSCALE } from "../../../shade/renderer/texture/SAMPLER_LINEAR_UPSCALE.js";
-import { ParticleEmitterFlag } from "../../graphics/particles/particular/engine/emitter/ParticleEmitterFlag.js";
-import {
-    blending_type_to_particle_blend,
-    particle_layer_record,
-    write_particle_records
-} from "./particle_gpu_records.js";
-
-/**
- * Buffers are grown with headroom and never shrunk: an effect's particle count changes every frame
- * by design, and sizing exactly would mean reallocating almost every one.
- *
- * @type {number}
- */
-const GROWTH_FACTOR = 1.5;
-
-/**
- * Vertices in one billboard, as the renderer's vertex stage indexes them.
- *
- * @type {number}
- */
-const QUAD_VERTEX_COUNT = 6;
-
-/**
- * Draws `particular`'s CPU-simulated particles with **Shade's own billboard renderer**.
- *
- * The simulation stays where it is — emission, ageing, parameter tracks, sorting and bounds are
- * meep's and are unchanged — and what crosses to the GPU each frame is the state it produced, in
- * the layout that renderer already reads: a pool of particle records, a list of the slots to draw,
- * and one emitter record per particle *layer* saying where that layer's sprite is in the atlas and
- * how it blends.
- *
- * Nothing here is a shader. The billboard expansion, the atlas lookup, the soft-depth fade and the
- * premultiplied blend that expresses both alpha and additive in one pipeline are Shade's, already
- * written and already tested; this is the packer and the residency that lets them draw somebody
- * else's particles.
- */
-export class GPUParticularRenderer {
-    /**
-     * @type {GPUBuffer|null}
-     */
-    #pool = null;
-
-    /**
-     * @type {number} capacity in particle records
-     */
-    #pool_capacity = 0;
-
-    /**
-     * @type {GPUBuffer|null}
-     */
-    #slots = null;
-
-    /**
-     * @type {number} capacity in slots
-     */
-    #slots_capacity = 0;
-
-    /**
-     * The emitter table the billboard renderer reads a particle's layer record out of.
-     *
-     * A `GPUDatabase` rather than a flat buffer because that is the layout the renderer's generated
-     * reader indexes — the table owns the addressing, the growth and the per-record staging, so
-     * there is nothing here that knows where a record physically lands.
-     *
-     * Built on first use: the device arrives with the frame graph's execution context, not with the
-     * constructor.
-     *
-     * @type {GPUDatabase|null}
-     */
-    #database = null;
-
-    /**
-     * How many layer records the last pack wrote. Rows past it are removed rather than left
-     * resident, so a frame with fewer layers than the last does not keep paying for them.
-     *
-     * @type {number}
-     */
-    #record_count = 0;
-
-    /**
-     * @type {GPUTextureContext|null}
-     */
-    #atlas = null;
-
-    /**
-     * The atlas image the texture was last written from, and its version.
-     *
-     * @type {*}
-     */
-    #atlas_source = null;
-
-    /**
-     * @type {number}
-     */
-    #atlas_version = -1;
-
-    /**
-     * @type {RenderPipelineDescriptor|null}
-     */
-    #pipeline = null;
-
-    /**
-     * @type {string}
-     */
-    #pipeline_key = "";
-
-    /**
-     * CPU staging, two views of one buffer: the renderer reads floats out of a `u32` pool with
-     * `bitcast`, so the packer writes through whichever view fits the field.
-     *
-     * @type {Uint32Array}
-     */
-    #pool_staging = new Uint32Array(0);
-
-    /**
-     * @type {Float32Array}
-     */
-    #pool_staging_f32 = new Float32Array(0);
-
-    /**
-     * Draw order, back to front.
-     *
-     * @type {Uint32Array}
-     */
-    #slot_staging = new Uint32Array(0);
-
-    /**
-     * View depth per slot, the key the draw order is sorted on.
-     *
-     * @type {Float32Array}
-     */
-    #depth_staging = new Float32Array(0);
-
-    /**
-     * How many particles the last {@link update} produced.
-     *
-     * @type {number}
-     */
-    #count = 0;
-
-    /**
-     * How many particles are waiting to be drawn. Read-only, and zero until {@link update} has run.
-     *
-     * @returns {number}
-     */
-    get count() {
-        return this.#count;
-    }
-
-    /**
-     * How many layer records the last pack wrote — the occupied rows of the emitter table.
-     *
-     * @returns {number}
-     */
-    get record_count() {
-        return this.#record_count;
-    }
-
-    /**
-     * Pack this frame's particles and upload them.
-     *
-     * Runs inside the pass rather than beside it, because a `GraphicsContext` — the device, the
-     * texture pool, the samplers — is something the frame graph hands out at execution time and the
-     * frame's pass context does not carry. The pool, the draw order and the atlas go up as queue
-     * writes; the emitter table's rows go up as the database's own upload dispatch, encoded here
-     * ahead of the draw that reads them.
-     *
-     * @param {GraphicsContext} graphics
-     * @param {ShadeGPUCommandContext} encoder the frame's open command context
-     * @param {ParticleEmitter[]} emitters
-     * @param {Sampler2D} atlas the sprite atlas every layer's patch is cut from
-     * @param {number[]|Float32Array} camera_position world space
-     * @param {number[]|Float32Array} camera_right world space
-     * @param {number[]|Float32Array} camera_up world space
-     */
-    #pack(graphics, encoder, emitters, atlas, camera_position, camera_right, camera_up) {
-        assert.defined(graphics, 'graphics');
-
-        this.#count = 0;
-
-        const drawn = [];
-
-        let particle_capacity = 0;
-
-        for (let i = 0; i < emitters.length; i++) {
-            const emitter = emitters[i];
-
-            if (!emitter.getFlag(ParticleEmitterFlag.Built)) {
-                continue;
-            }
-
-            const particles = emitter.particles.size();
-
-            if (particles === 0) {
-                continue;
-            }
-
-            drawn.push(emitter);
-
-            particle_capacity += particles;
-        }
-
-        if (drawn.length === 0) {
-            return;
-        }
-
-        this.#reserve_staging(particle_capacity);
-
-        const pool = this.#pool_staging;
-        const pool_f32 = this.#pool_staging_f32;
-
-        const table = this.#obtain_database(graphics.device).get(PARTICLE_EMITTER_TABLE);
-
-        let record_index = 0;
-        let written = 0;
-
-        const layer_records = [];
-
-        for (let i = 0; i < drawn.length; i++) {
-            const emitter = drawn[i];
-
-            const blend = blending_type_to_particle_blend(emitter.blendingMode);
-            const soft_depth = !emitter.getFlag(ParticleEmitterFlag.DepthSoftDisabled);
-
-            layer_records.length = 0;
-
-            const layers = emitter.layers;
-
-            for (let j = 0; j < layers.length; j++) {
-                // the field is how the emitter itself reads it — `ParticleLayer` publishes a
-                // setter and no getter, and 2.x is frozen
-                const patch = layers.get(j).__atlasPatch;
-
-                if (patch === null || patch === undefined) {
-                    // the sprite has not been fetched yet, so this layer has nothing to draw with
-                    layer_records[j] = undefined;
-
-                    continue;
-                }
-
-                const uv = patch.uv;
-
-                table.set(record_index, particle_layer_record({
-                    atlas_region: [uv.position.x, uv.position.y, uv.size.x, uv.size.y],
-                    blend,
-                    soft_depth
-                }));
-
-                layer_records[j] = record_index;
-
-                record_index++;
-            }
-
-            written += write_particle_records(
-                pool, pool_f32, written, emitter, layer_records, camera_right, camera_up
-            );
-        }
-
-        if (written === 0) {
-            return;
-        }
-
-        // Layers that were drawn last frame and are not this frame: free their rows, so a busy
-        // frame's page count does not become the floor for every quiet frame after it.
-        for (let i = record_index; i < this.#record_count; i++) {
-            table.remove(i);
-        }
-
-        this.#record_count = record_index;
-
-        this.#count = written;
-
-        this.#order(written, camera_position);
-
-        this.#upload(graphics, encoder, written, atlas);
-    }
-
-    /**
-     * The emitter table's database, built on first use.
-     *
-     * @param {GPUDevice} device
-     * @returns {GPUDatabase}
-     */
-    #obtain_database(device) {
-        if (this.#database === null) {
-            this.#database = new GPUDatabase({
-                device,
-                definition: PARTICLE_DATABASE_SPEC,
-                label: "particular/emitters",
-                initial_data_size_bytes: PARTICLE_DATABASE_INITIAL_SIZE,
-            });
-        }
-
-        return this.#database;
-    }
-
-    /**
-     * Sort the draw order back to front.
-     *
-     * Transparency is order-dependent and particles overlap constantly, so what is drawn last has to
-     * be what is nearest. The legacy renderer sorts each emitter's own particles and leaves the
-     * emitters to three's object sort; this sorts every particle in the frame against every other,
-     * which is the ordering that object sort was approximating.
-     *
-     * @param {number} count
-     * @param {number[]|Float32Array} camera_position
-     */
-    #order(count, camera_position) {
-        const pool_f32 = this.#pool_staging_f32;
-
-        const depths = this.#depth_staging;
-        const slots = this.#slot_staging;
-
-        const camera_x = camera_position[0];
-        const camera_y = camera_position[1];
-        const camera_z = camera_position[2];
-
-        for (let i = 0; i < count; i++) {
-            const base = i * PARTICLE_RECORD_WORD_COUNT + 1;
-
-            const dx = pool_f32[base] - camera_x;
-            const dy = pool_f32[base + 1] - camera_y;
-            const dz = pool_f32[base + 2] - camera_z;
-
-            depths[i] = dx * dx + dy * dy + dz * dz;
-            slots[i] = i;
-        }
-
-        const order = Array.prototype.slice.call(slots, 0, count);
-
-        order.sort((a, b) => depths[b] - depths[a]);
-
-        slots.set(order, 0);
-    }
-
-    /**
-     * @param {number} particle_capacity
-     */
-    #reserve_staging(particle_capacity) {
-        const words = particle_capacity * PARTICLE_RECORD_WORD_COUNT;
-
-        if (this.#pool_staging.length < words) {
-            const buffer = new ArrayBuffer(Math.ceil(words * GROWTH_FACTOR) * 4);
-
-            this.#pool_staging = new Uint32Array(buffer);
-            this.#pool_staging_f32 = new Float32Array(buffer);
-        }
-
-        if (this.#slot_staging.length < particle_capacity) {
-            const capacity = Math.ceil(particle_capacity * GROWTH_FACTOR);
-
-            this.#slot_staging = new Uint32Array(capacity);
-            this.#depth_staging = new Float32Array(capacity);
-        }
-    }
-
-    /**
-     * @param {GraphicsContext} graphics
-     * @param {ShadeGPUCommandContext} encoder the frame's open command context
-     * @param {number} count
-     * @param {Sampler2D} atlas
-     */
-    #upload(graphics, encoder, count, atlas) {
-        const device = graphics.device;
-
-        this.#pool = this.#obtain_buffer(
-            device, this.#pool, count * PARTICLE_RECORD_WORD_COUNT * 4, "particular/pool",
-            capacity => this.#pool_capacity = capacity
-        );
-
-        this.#slots = this.#obtain_buffer(
-            device, this.#slots, count * 4, "particular/slots",
-            capacity => this.#slots_capacity = capacity
-        );
-
-        device.queue.writeBuffer(this.#pool, 0, this.#pool_staging, 0, count * PARTICLE_RECORD_WORD_COUNT);
-        device.queue.writeBuffer(this.#slots, 0, this.#slot_staging, 0, count);
-
-        // Rows staged by #pack reach the buffer here, encoded before the draw that reads them.
-        this.#database.update(encoder);
-
-        this.#obtain_atlas(graphics, atlas);
-    }
-
-    /**
-     * @param {GPUDevice} device
-     * @param {GPUBuffer|null} existing
-     * @param {number} bytes
-     * @param {string} label
-     * @param {function(number)} remember
-     * @returns {GPUBuffer}
-     */
-    #obtain_buffer(device, existing, bytes, label, remember) {
-        if (existing !== null && existing.size >= bytes) {
-            return existing;
-        }
-
-        if (existing !== null) {
-            existing.destroy();
-        }
-
-        // a storage binding's size must be a multiple of 4, and the growth factor does not respect
-        // that on its own
-        const capacity = round_up(Math.ceil(bytes * GROWTH_FACTOR), 4);
-
-        remember(capacity);
-
-        return device.createBuffer({
-            size: capacity,
-            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
-            label
-        });
-    }
-
-    /**
-     * The sprite atlas as the GPU holds it.
-     *
-     * **A texture this owns**, for the reason the fog mask is: `TextureManager` keys its cache on an
-     * image's identity and never releases, and this one is repainted whenever an effect brings a new
-     * sprite in.
-     *
-     * @param {GraphicsContext} graphics
-     * @param {Sampler2D} atlas
-     */
-    #obtain_atlas(graphics, atlas) {
-        const width = atlas.width;
-        const height = atlas.height;
-
-        const existing = this.#atlas;
-
-        if (existing === null || existing.descriptor.size[0] !== width || existing.descriptor.size[1] !== height) {
-            if (existing !== null) {
-                existing.destroy();
-            }
-
-            this.#atlas = graphics.textures.contextFromDescriptor(TextureDescriptor.from({
-                label: "particular sprite atlas",
-                size: [width, height],
-                format: "rgba8unorm",
-                mipLevelCount: 1,
-                usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST
-            }));
-
-            this.#atlas_source = null;
-            this.#atlas_version = -1;
-        }
-
-        const data = atlas.data;
-
-        if (this.#atlas_source !== data || this.#atlas_version !== atlas.version) {
-            graphics.device.queue.writeTexture(
-                { texture: this.#atlas.gpu_texture },
-                data,
-                { bytesPerRow: width * 4, rowsPerImage: height },
-                [width, height]
-            );
-
-            this.#atlas_source = data;
-            this.#atlas_version = atlas.version;
-        }
-    }
-
-    /**
-     * Record the billboard draw into `graph`, over the colour it is given.
-     *
-     * @param {object} args
-     * @param {FrameGraph} args.graph
-     * @param {number} args.color colour resource handle to draw over
-     * @param {number} args.depth scene depth — tested against, and sampled for the soft fade
-     * @param {GPUBuffer|GPUTypedBuffer} args.camera
-     * @param {ParticleEmitter[]} args.emitters
-     * @param {Sampler2D} args.atlas
-     * @param {number[]|Float32Array} args.camera_position world space
-     * @param {number[]|Float32Array} args.camera_right world space
-     * @param {number[]|Float32Array} args.camera_up world space
-     * @returns {number} the colour handle after the draw
-     */
-    graph_draw({ graph, color, depth, camera, emitters, atlas, camera_position, camera_right, camera_up }) {
-        assert.defined(graph, 'graph');
-
-        const data = {};
-
-        const pass = graph.add('particles', data, (data, resources, context) => {
-            this.#pack(context.graphics, context.encoder, emitters, atlas, camera_position, camera_right, camera_up);
-
-            this.#execute(data, resources, context, camera);
-        });
-
-        data.depth = pass.read(depth);
-        data.color = pass.write(pass.read(color));
-
-        return data.color;
-    }
-
-    /**
-     * @param data
-     * @param {FramePassResources} resources
-     * @param {GraphicsExecutionContext} context
-     * @param {GPUBuffer|GPUTypedBuffer} camera
-     */
-    #execute(data, resources, context, camera) {
-        const count = this.#count;
-
-        if (count === 0) {
-            return;
-        }
-
-        const encoder = context.encoder;
-        const graphics = context.graphics;
-
-        const color_texture = resources.get(data.color);
-        const depth_texture = resources.get(data.depth);
-
-        const depth_view = depth_texture.obtainView(DEFAULT_DEPTH_TEXTURE_VIEW);
-
-        const pipeline = this.#obtain_pipeline(
-            color_texture.descriptor.format,
-            depth_texture.descriptor.format
-        );
-
-        const bindings = PARTICLE_BILLBOARD_RESOURCES.generateBindings({
-            camera,
-            pool: this.#pool,
-            draw_list: this.#slots,
-            emitter_database: this.#database.buffer,
-            atlas: this.#atlas.obtainView(),
-            atlas_sampler: graphics.samplers.obtain(SAMPLER_LINEAR_UPSCALE),
-            scene_depth: depth_view
-        }, encoder);
-
-        const render_pass = encoder.constructRenderPass({
-            label: "Particles",
-            pipeline,
-            bindings,
-            colorAttachments: [{
-                loadOp: "load",
-                storeOp: "store",
-                view: color_texture.obtainView(TextureViewDescriptor.from({
-                    mipLevelCount: 1,
-                    baseMipLevel: 0
-                }))
-            }],
-            // tested against the scene and never written, and bound as a texture in the same pass
-            // for the soft fade — which is why it is read-only here
-            depthStencilAttachment: {
-                view: depth_view,
-                depthReadOnly: true
-            }
-        });
-
-        render_pass.draw(QUAD_VERTEX_COUNT, count);
-
-        render_pass.end();
-    }
-
-    /**
-     * @param {string} color_format
-     * @param {string} depth_format
-     * @returns {RenderPipelineDescriptor}
-     */
-    #obtain_pipeline(color_format, depth_format) {
-        const key = `${color_format}/${depth_format}`;
-
-        if (this.#pipeline === null || this.#pipeline_key !== key) {
-            this.#pipeline = create_particle_billboard_pipeline({
-                color_format,
-                depth_format,
-                // reverse-Z
-                depth_compare: "greater"
-            });
-
-            this.#pipeline_key = key;
-        }
-
-        return this.#pipeline;
-    }
-
-    /**
-     * Give back everything held on the device. The renderer lives as long as the system that owns
-     * it, and a scene reload builds both again.
-     */
-    destroy() {
-        if (this.#pool !== null) {
-            this.#pool.destroy();
-            this.#pool = null;
-            this.#pool_capacity = 0;
-        }
-
-        if (this.#slots !== null) {
-            this.#slots.destroy();
-            this.#slots = null;
-            this.#slots_capacity = 0;
-        }
-
-        if (this.#database !== null) {
-            this.#database.destroy();
-            this.#database = null;
-            this.#record_count = 0;
-        }
-
-        if (this.#atlas !== null) {
-            this.#atlas.destroy();
-            this.#atlas = null;
-            this.#atlas_source = null;
-            this.#atlas_version = -1;
-        }
-
-        this.#count = 0;
-    }
-}

package/src/engine/graphics3/particles/particle_gpu_records.d.ts

@@ -1,85 +0,0 @@
-/**
- * How a meep blending mode is drawn by the billboard renderer, which expresses every mode it has
- * through one premultiplied blend state.
- *
- * **Subtract and Multiply arrive as additive**, which is what the legacy renderer does with them:
- * its shader tests `blending > 0.1` and treats everything above that as additive. Neither renderer
- * can express them in a single pass, the content was authored against what the game shows, and
- * exactly one emitter in the game asks for Multiply.
- *
- * @param {BlendingType} blending_type
- * @returns {number} a member of {@link EMITTER_BLEND}
- */
-export function blending_type_to_particle_blend(blending_type: BlendingType): number;
-/**
- * One particle layer as a row of the emitter table
- * ({@link ../../../shade/renderer/particles/data/PARTICLE_EMITTER_STRUCT.js}).
- *
- * **A record per layer, not per emitter.** The renderer reads the sprite's atlas rectangle from the
- * emitter record, and in meep the sprite belongs to the *layer* — one emitter's particles can come
- * from several layers with different sprites. Since every particle names its own record, splitting
- * this way costs nothing and keeps the draw a single one.
- *
- * Every field of the struct is filled, including the ones a CPU-simulated layer has no use for (the
- * VM program offsets, the seed, the spawn rate). A field left out is not written as zero — the
- * serializer skips it and the table's page buffers are recycled, so an omitted field would show
- * whatever the slot's previous tenant left behind.
- *
- * @param {object} layer
- * @param {ArrayLike<number>} layer.atlas_region uv offset x, y and uv scale x, y
- * @param {number} layer.blend a member of {@link EMITTER_BLEND}
- * @param {boolean} layer.soft_depth
- * @returns {object} the value to store in the emitter table
- */
-export function particle_layer_record({ atlas_region, blend, soft_depth }: {
-    atlas_region: ArrayLike<number>;
-    blend: number;
-    soft_depth: boolean;
-}): object;
-/**
- * Write one emitter's live particles into the shared pool.
- *
- * The pool is compacted by `ParticleEmitter.update`, so the live particles are `[0, size)` and this
- * runs straight down them.
- *
- * **Size is halved on the way in.** meep's `size` is the sprite's full width; the renderer expands a
- * corner of ±1 by `size`, so what it wants is the half-extent — the same `radius = size * 0.5` the
- * legacy vertex shader computes.
- *
- * **Velocity alignment is resolved here**, into the rotation the renderer reads: the legacy shader
- * turns the sprite to face the screen-space direction of travel, and the camera basis is what says
- * which direction that is.
- *
- * @param {Uint32Array} pool
- * @param {Float32Array} pool_f32 the same buffer, viewed as floats
- * @param {number} first_slot record index to start writing at
- * @param {ParticleEmitter} emitter
- * @param {number[]} layer_records the layer record index for each of the emitter's layers
- * @param {number[]} camera_right world-space camera right
- * @param {number[]} camera_up world-space camera up
- * @returns {number} how many particles were written
- */
-export function write_particle_records(pool: Uint32Array, pool_f32: Float32Array, first_slot: number, emitter: ParticleEmitter, layer_records: number[], camera_right: number[], camera_up: number[]): number;
-/**
- * Where each attribute the billboard renderer reads sits inside a particle record, in words.
- *
- * The record is 32 words and the renderer is told where to find what, so these are ours to choose;
- * word 0 is the header the renderer reads the owning emitter from.
- *
- * @type {number}
- */
-export const PARTICLE_WORD_POSITION: number;
-/**
- * @type {number}
- */
-export const PARTICLE_WORD_SIZE: number;
-/**
- * @type {number}
- */
-export const PARTICLE_WORD_COLOR: number;
-/**
- * @type {number}
- */
-export const PARTICLE_WORD_ROTATION: number;
-import { BlendingType } from "../../graphics/texture/sampler/BlendingType.js";
-//# sourceMappingURL=particle_gpu_records.d.ts.map