@woosh/meep-engine 3.33.0 → 3.34.0

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

@@ -1 +0,0 @@
-{"version":3,"file":"particle_gpu_records.d.ts","sourceRoot":"","sources":["../../../../../src/engine/graphics3/particles/particle_gpu_records.js"],"names":[],"mappings":"AAiDA;;;;;;;;;;;GAWG;AACH,+DAHW,YAAY,GACV,MAAM,CAQlB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IALoC,YAAY,EAArC,UAAU,MAAM,CAAC;IACH,KAAK,EAAnB,MAAM;IACS,UAAU,EAAzB,OAAO;IACL,MAAM,CAwClB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,6CATW,WAAW,YACX,YAAY,cACZ,MAAM,2CAEN,MAAM,EAAE,gBACR,MAAM,EAAE,aACR,MAAM,EAAE,GACN,MAAM,CA4ElB;AA1MD;;;;;;;GAOG;AACH,qCAFU,MAAM,CAEwB;AAExC;;GAEG;AACH,iCAFU,MAAM,CAEoB;AAEpC;;GAEG;AACH,kCAFU,MAAM,CAEqB;AAErC;;GAEG;AACH,qCAFU,MAAM,CAEwB;6BA9CX,gDAAgD"}

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

@@ -1,227 +0,0 @@
-import { assert } from "../../../core/assert.js";
-import { BlendingType } from "../../graphics/texture/sampler/BlendingType.js";
-import {
-    PARTICLE_ATTRIBUTE_COLOR,
-    PARTICLE_ATTRIBUTE_LAYER_POSITION,
-    PARTICLE_ATTRIBUTE_POSITION,
-    PARTICLE_ATTRIBUTE_ROTATION,
-    PARTICLE_ATTRIBUTE_SIZE,
-    PARTICLE_ATTRIBUTE_VELOCITY
-} from "../../graphics/particles/particular/engine/emitter/PARTICLE_ATTRIBUTES.js";
-import { ParticleEmitterFlag } from "../../graphics/particles/particular/engine/emitter/ParticleEmitterFlag.js";
-import {
-    EMITTER_ATTRIBUTE_ABSENT,
-    EMITTER_BLEND,
-    EMITTER_PROJECTION,
-    make_emitter_flags
-} from "../../../shade/renderer/particles/data/PARTICLE_EMITTER_STRUCT.js";
-import { PARTICLE_GENERATION_FIRST } from "../../../shade/renderer/particles/data/particle_header.js";
-import { NODE3D_SCENE_ID } from "../../../shade/renderer/scene/NODE3D_STRUCT.js";
-import {
-    PARTICLE_RECORD_HEADER_EMITTER,
-    PARTICLE_RECORD_WORD_COUNT
-} from "../../../shade/renderer/particles/ParticleConstants.js";
-
-/**
- * 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 = 1;
-
-/**
- * @type {number}
- */
-export const PARTICLE_WORD_SIZE = 4;
-
-/**
- * @type {number}
- */
-export const PARTICLE_WORD_COLOR = 5;
-
-/**
- * @type {number}
- */
-export const PARTICLE_WORD_ROTATION = 9;
-
-/**
- * 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) {
-    if (blending_type === BlendingType.Normal || blending_type === BlendingType.NoBlending) {
-        return EMITTER_BLEND.ALPHA;
-    }
-
-    return EMITTER_BLEND.ADDITIVE;
-}
-
-/**
- * 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 }) {
-    return {
-        // BILLBOARD: the quad faces the camera and the rotation attribute rolls it in the view
-        // plane, which is what the legacy point sprite does. Velocity alignment is folded into that
-        // rotation when the particles are written, rather than being a projection mode of its own.
-        flags: make_emitter_flags({
-            soft_depth,
-            blend,
-            projection: EMITTER_PROJECTION.BILLBOARD,
-        }),
-
-        atlas_region,
-
-        render_position: PARTICLE_WORD_POSITION,
-        render_size: PARTICLE_WORD_SIZE,
-        render_color: PARTICLE_WORD_COLOR,
-        render_rotation: PARTICLE_WORD_ROTATION,
-        render_frame: EMITTER_ATTRIBUTE_ABSENT,
-        render_velocity: EMITTER_ATTRIBUTE_ABSENT,
-
-        // one cell: the sprite sheet animation the flipbook exists for is a later feature, and a
-        // 1x1 grid is the identity of that mapping rather than a disabled branch
-        flipbook: [1, 1],
-
-        // meep simulates these particles on the CPU, so there is no VM program, no seed and no
-        // GPU-side spawning behind this record — only the drawing half of it is ever read. The
-        // node is the scene root, which is as good as any: the particles carry world positions.
-        init_offset: 0,
-        init_count: 0,
-        update_offset: 0,
-        update_count: 0,
-        constant_offset: 0,
-        program_id: 0,
-        seed: 0,
-        spawn_rate: 0,
-        node: NODE3D_SCENE_ID,
-        generation: PARTICLE_GENERATION_FIRST,
-    };
-}
-
-/**
- * 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, pool_f32, first_slot, emitter, layer_records, camera_right, camera_up
-) {
-    const particles = emitter.particles;
-
-    const count = particles.size();
-
-    if (count === 0) {
-        return 0;
-    }
-
-    const positions = particles.attributes[PARTICLE_ATTRIBUTE_POSITION].array;
-    const sizes = particles.attributes[PARTICLE_ATTRIBUTE_SIZE].array;
-    const colors = particles.attributes[PARTICLE_ATTRIBUTE_COLOR].array;
-    const rotations = particles.attributes[PARTICLE_ATTRIBUTE_ROTATION].array;
-    const layers = particles.attributes[PARTICLE_ATTRIBUTE_LAYER_POSITION].array;
-    const velocities = particles.attributes[PARTICLE_ATTRIBUTE_VELOCITY].array;
-
-    const align = emitter.getFlag(ParticleEmitterFlag.AlignOnVelocity);
-
-    let written = 0;
-
-    for (let i = 0; i < count; i++) {
-        const layer = layers[i];
-
-        const record = layer_records[layer];
-
-        if (record === undefined) {
-            // a layer whose sprite has not been fetched yet has nowhere to draw from
-            continue;
-        }
-
-        const base = (first_slot + written) * PARTICLE_RECORD_WORD_COUNT;
-
-        pool[base + PARTICLE_RECORD_HEADER_EMITTER] = record;
-
-        const p = i * 3;
-
-        pool_f32[base + PARTICLE_WORD_POSITION] = positions[p];
-        pool_f32[base + PARTICLE_WORD_POSITION + 1] = positions[p + 1];
-        pool_f32[base + PARTICLE_WORD_POSITION + 2] = positions[p + 2];
-
-        pool_f32[base + PARTICLE_WORD_SIZE] = sizes[i] * 0.5;
-
-        const c = i * 4;
-
-        pool_f32[base + PARTICLE_WORD_COLOR] = colors[c] / 255;
-        pool_f32[base + PARTICLE_WORD_COLOR + 1] = colors[c + 1] / 255;
-        pool_f32[base + PARTICLE_WORD_COLOR + 2] = colors[c + 2] / 255;
-        pool_f32[base + PARTICLE_WORD_COLOR + 3] = colors[c + 3] / 255;
-
-        let rotation = rotations[i];
-
-        if (align) {
-            const v_x = velocities[p];
-            const v_y = velocities[p + 1];
-            const v_z = velocities[p + 2];
-
-            const screen_x = v_x * camera_right[0] + v_y * camera_right[1] + v_z * camera_right[2];
-            const screen_y = v_x * camera_up[0] + v_y * camera_up[1] + v_z * camera_up[2];
-
-            if (screen_x !== 0 || screen_y !== 0) {
-                // the sprite's own up is +Y, so facing the direction of travel is that angle less a
-                // quarter turn — the same correction the legacy vertex shader applies
-                rotation += Math.atan2(screen_y, screen_x) - Math.PI / 2;
-            }
-        }
-
-        pool_f32[base + PARTICLE_WORD_ROTATION] = rotation;
-
-        written++;
-    }
-
-    return written;
-}

package/src/shade/renderer/particles/shaders/shader_particle_render.d.ts

@@ -1,35 +0,0 @@
-/**
- * Build the billboard render pipeline descriptor.
- * @param {object} [options]
- * @param {string} [options.color_format] colour target format
- * @param {string|null} [options.depth_format] scene depth format (test-only, no write); pass null to
- *   render without a depth attachment (e.g. an additive-only prototype with no scene geometry)
- * @param {GPUCompareFunction} [options.depth_compare] depth test — "greater"/"greater-equal" for
- *   reverse-Z scenes (the engine convention), "less"/"less-equal" for a standard-Z scene
- * @returns {RenderPipelineDescriptor}
- */
-export function create_particle_billboard_pipeline({ color_format, depth_format, depth_compare }?: {
-    color_format?: string;
-    depth_format?: string | null;
-    depth_compare?: GPUCompareFunction;
-}): RenderPipelineDescriptor;
-export namespace PARTICLE_BILLBOARD_BLEND {
-    namespace color {
-        let operation: string;
-        let srcFactor: string;
-        let dstFactor: string;
-    }
-    namespace alpha {
-        let operation_1: string;
-        export { operation_1 as operation };
-        let srcFactor_1: string;
-        export { srcFactor_1 as srcFactor };
-        let dstFactor_1: string;
-        export { dstFactor_1 as dstFactor };
-    }
-}
-/** The billboard shader's resource set (for building bind groups + the draw command). */
-export const PARTICLE_BILLBOARD_RESOURCES: ShaderResourceSetDescriptor;
-import { RenderPipelineDescriptor } from "../../../descriptor/pipeline/render/RenderPipelineDescriptor.js";
-import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
-//# sourceMappingURL=shader_particle_render.d.ts.map

package/src/shade/renderer/particles/shaders/shader_particle_render.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"shader_particle_render.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/shader_particle_render.js"],"names":[],"mappings":"AAgGA;;;;;;;;;GASG;AACH;IAP4B,YAAY,GAA7B,MAAM;IACgB,YAAY,GAAlC,MAAM,GAAC,IAAI;IAEkB,aAAa;IAExC,wBAAwB,CA2BpC;;;;;;;;;;;;;;;;AAED,yFAAyF;AACzF,uEAAsD;yCAtIb,iEAAiE;4CAO9D,sDAAsD"}

package/src/shade/renderer/particles/shaders/shader_particle_render.js

@@ -1,135 +0,0 @@
-import { RenderPipelineDescriptor } from "../../../descriptor/pipeline/render/RenderPipelineDescriptor.js";
-import { ColorTargetState } from "../../../descriptor/pipeline/render/ColorTargetState.js";
-import { DepthStencilState } from "../../../descriptor/pipeline/render/DepthStencilState.js";
-import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
-import { CAMERA_UNIFORM_STRUCT } from "../../camera/CAMERA_UNIFORM_STRUCT.js";
-import { ShaderDescriptor } from "../../shader/ShaderDescriptor.js";
-import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
-import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
-import { EMITTER_FLAG } from "../data/PARTICLE_EMITTER_STRUCT.js";
-import { PARTICLE_SOFT_FADE_RANGE } from "../ParticleConstants.js";
-import { chunk_particle_billboard_vertex } from "./chunk_particle_billboard_vertex.js";
-import { chunk_particle_lighting_unlit } from "./chunk_particle_lighting.js";
-import { chunk_particle_scene_view_depth } from "./chunk_particle_scene_view_depth.js";
-
-/**
- * Blended billboards drawn straight over a colour target with fixed-function blending, in whatever
- * order the caller's draw list happens to be in.
- *
- * Its one consumer is
- * {@link ../../../../engine/graphics3/particles/GPUParticularRenderer.js GPUParticularRenderer},
- * which draws `particular`'s CPU-simulated particles: it sorts every live particle back to front on
- * the CPU and hands that order in as `draw_list`, which is what makes an order-dependent blend
- * correct here. The GPU particle system does not use this pipeline — its particles go through
- * AVBOIT (`../graph_particles_avboit.js`), where the accumulators are sums and no ordering exists
- * or is needed.
- *
- * One instanced draw covers every particle: `instance_index` indexes `draw_list`, `vertex_index`
- * (0..5) picks a quad corner. The vertex stage is `chunk_particle_billboard_vertex`, shared with the
- * AVBOIT particle passes. The fragment stage samples the atlas sub-rect + flipbook cell, applies an
- * optional soft-depth fade against the scene depth, runs the pluggable lighting hook (unlit by
- * default; a caller swaps in the shading-chunk-backed one when an emitter enables lighting), and
- * emits premultiplied colour.
- *
- * A single blend state — `src*1 + dst*(1-srcAlpha)` on both channels — expresses alpha and additive
- * blending; the shader chooses per particle by how it premultiplies (see `particle_premultiply`), so
- * the whole draw stays GPU-driven with no pipeline switches.
- *
- * The math (billboard expansion, atlas/flipbook UV, soft fade, premultiply) is unit-tested in
- * {@link ./chunk_particle_render_math.spec.js}; this module assembles it into a render pipeline.
- */
-
-/** Premultiplied blend: additive when a=0 (dst preserved, colour adds), over-blend when a=srcAlpha. */
-export const PARTICLE_BILLBOARD_BLEND = {
-    color: { operation: "add", srcFactor: "one", dstFactor: "one-minus-src-alpha" },
-    alpha: { operation: "add", srcFactor: "one", dstFactor: "one-minus-src-alpha" },
-};
-
-const resources = new ShaderResourceSetDescriptor();
-resources.createGroup()
-    .addUniform("camera", CAMERA_UNIFORM_STRUCT)
-    .addStorageBuffer("pool", WebGPUArray.u32, false)
-    .addStorageBuffer("draw_list", WebGPUArray.u32, false)
-    .addStorageBuffer("emitter_database", WebGPUArray.u32, false)
-    // Sampled with a filtering sampler, so the atlas must be a filterable float texture.
-    .addTexture("atlas", "float")
-    .addSampler("atlas_sampler", "filtering")
-    // Only textureLoad-ed (soft depth), so it can be unfilterable — matches an r32float scene depth.
-    .addTexture("scene_depth", "unfilterable-float");
-
-const body = CodeChunk.from(
-    /* language=wgsl */ `
-const PARTICLE_FLAG_SOFT_DEPTH : u32 = ${EMITTER_FLAG.SOFT_DEPTH}u;
-const PARTICLE_FLAG_LIGHTING : u32 = ${EMITTER_FLAG.LIGHTING}u;
-const PARTICLE_SOFT_FADE_RANGE : f32 = ${PARTICLE_SOFT_FADE_RANGE};
-
-@vertex
-fn vs_main(@builtin(vertex_index) vi : u32, @builtin(instance_index) ii : u32) -> ParticleVertexOut {
-    return particle_billboard_vertex(vi, ii);
-}
-
-@fragment
-fn fs_main(in : ParticleVertexOut) -> @location(0) vec4<f32> {
-    let sampled = textureSample(atlas, atlas_sampler, in.uv);
-    var color = sampled * in.color;
-
-    if ((in.flags & PARTICLE_FLAG_SOFT_DEPTH) != 0u) {
-        let scene_vd = particle_scene_view_depth(textureLoad(scene_depth, vec2<i32>(in.clip.xy), 0).r, camera);
-        color = particle_fade_color(color, in.blend, particle_soft_fade(scene_vd, in.view_depth, PARTICLE_SOFT_FADE_RANGE));
-    }
-
-    if ((in.flags & PARTICLE_FLAG_LIGHTING) != 0u) {
-        color = particle_apply_lighting(color, in.world_position, normalize(in.normal));
-    }
-
-    return particle_premultiply(color, in.blend);
-}
-`, [chunk_particle_billboard_vertex, chunk_particle_lighting_unlit, chunk_particle_scene_view_depth]);
-
-/**
- * The shader itself. One compilation, shared by every pipeline built from it — the options below
- * vary the pipeline state, never the WGSL.
- *
- * @type {ShaderDescriptor}
- */
-const descriptor = ShaderDescriptor.from({ label: "Particle Billboard", body, resources });
-
-/**
- * Build the billboard render pipeline descriptor.
- * @param {object} [options]
- * @param {string} [options.color_format] colour target format
- * @param {string|null} [options.depth_format] scene depth format (test-only, no write); pass null to
- *   render without a depth attachment (e.g. an additive-only prototype with no scene geometry)
- * @param {GPUCompareFunction} [options.depth_compare] depth test — "greater"/"greater-equal" for
- *   reverse-Z scenes (the engine convention), "less"/"less-equal" for a standard-Z scene
- * @returns {RenderPipelineDescriptor}
- */
-export function create_particle_billboard_pipeline({
-                                                       color_format = "rgba16float",
-                                                       depth_format = "depth32float",
-                                                       depth_compare = "greater"
-} = {}) {
-
-    const code = descriptor.source;
-
-    return RenderPipelineDescriptor.from({
-        label: "Particle Billboard",
-        layout: resources.generatePipelineLayout(GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT),
-        vertex: { module: { code }, entryPoint: "vs_main" },
-        fragment: {
-            module: { code },
-            entryPoint: "fs_main",
-            targets: [ColorTargetState.from({ format: color_format, blend: PARTICLE_BILLBOARD_BLEND })],
-        },
-        // Depth-test against the scene, but never write (transparent). Omitted entirely when no depth
-        // attachment is bound.
-        depthStencil: depth_format == null
-            ? undefined
-            : DepthStencilState.from({ format: depth_format, depthWriteEnabled: false, depthCompare: depth_compare }),
-        primitive: { topology: "triangle-list", cullMode: "none" },
-    });
-
-}
-
-/** The billboard shader's resource set (for building bind groups + the draw command). */
-export const PARTICLE_BILLBOARD_RESOURCES = resources;