@woosh/meep-engine 3.26.0 → 3.28.0

package/src/shade/renderer/geometry/virtual/residency/VGeoResidencyOptions.d.ts

@@ -1,49 +0,0 @@
-/**
- * What a {@link VGeoResidencyManager} is allowed to spend.
- *
- * @author Alex Goldring
- * @copyright Company Named Limited (c) 2026
- */
-export class VGeoResidencyOptions {
-    /**
-     * The RAM tier's budget: decoded page bytes, summed over every registered reader.
-     *
-     * Design §6 pins the tiers — CDN ⊇ RAM ⊇ VRAM — and says residency is a small fraction of the
-     * asset in RAM. What makes a number necessary rather than advisory is scale: a thousand assets
-     * of a hundred million triangles each are several gigabytes of pages *apiece*, so the resident
-     * set has to be a small fraction of *one* of them, and nothing about a single reader can know
-     * that. 512 MiB is a default to be overridden by whoever knows the device, not a measurement.
-     *
-     * It is spent against `VGeoContainerReader.resident_bytes`, which is decoded page images and
-     * not what those pages cost in the heap — the reader's own per-page bookkeeping measured
-     * 6.4–11.9 KB on top of each image, which is 1.2% at the page sizes design §5 targets. A budget
-     * set against unusually small pages should allow for it.
-     *
-     * @type {number}
-     */
-    budget_bytes: number;
-    /**
-     * How many page fetches may be in flight at once, across every registered reader.
-     *
-     * The number that matters to a browser and to a CDN, and the one no reader can set: eight
-     * readers at the per-reader default of 6 were measured issuing 48 concurrent range requests.
-     * Twelve is more than one HTTP/1.1 connection pool will give and less than an H2/H3 multiplex
-     * will happily carry, which is the range this wants to sit in.
-     *
-     * @type {number}
-     */
-    max_concurrent_fetches: number;
-    /**
-     * How many frames a page is protected from eviction after it was last touched.
-     *
-     * Design §6: eviction is LRU on **last-touched**, with a protect window no shorter than the
-     * feedback latency. The window is what stops the classic fallback-chain bug — feedback arrives a
-     * frame or three late, so a page that is on screen right now may not have been reported as
-     * touched yet, and evicting on a stamp that has not caught up evicts exactly what is being
-     * drawn. Three frames is one `mapAsync` round trip's worth of slack.
-     *
-     * @type {number}
-     */
-    protect_frames: number;
-}
-//# sourceMappingURL=VGeoResidencyOptions.d.ts.map

package/src/shade/renderer/geometry/virtual/residency/VGeoResidencyOptions.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"VGeoResidencyOptions.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/residency/VGeoResidencyOptions.js"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH;IACI;;;;;;;;;;;;;;;OAeG;IACH,cAFU,MAAM,CAEiB;IAEjC;;;;;;;;;OASG;IACH,wBAFU,MAAM,CAEY;IAE5B;;;;;;;;;;OAUG;IACH,gBAFU,MAAM,CAEG;CACtB"}

package/src/shade/renderer/geometry/virtual/residency/VGeoResidencyOptions.js

@@ -1,50 +0,0 @@
-/**
- * What a {@link VGeoResidencyManager} is allowed to spend.
- *
- * @author Alex Goldring
- * @copyright Company Named Limited (c) 2026
- */
-export class VGeoResidencyOptions {
-    /**
-     * The RAM tier's budget: decoded page bytes, summed over every registered reader.
-     *
-     * Design §6 pins the tiers — CDN ⊇ RAM ⊇ VRAM — and says residency is a small fraction of the
-     * asset in RAM. What makes a number necessary rather than advisory is scale: a thousand assets
-     * of a hundred million triangles each are several gigabytes of pages *apiece*, so the resident
-     * set has to be a small fraction of *one* of them, and nothing about a single reader can know
-     * that. 512 MiB is a default to be overridden by whoever knows the device, not a measurement.
-     *
-     * It is spent against `VGeoContainerReader.resident_bytes`, which is decoded page images and
-     * not what those pages cost in the heap — the reader's own per-page bookkeeping measured
-     * 6.4–11.9 KB on top of each image, which is 1.2% at the page sizes design §5 targets. A budget
-     * set against unusually small pages should allow for it.
-     *
-     * @type {number}
-     */
-    budget_bytes = 512 * 1024 * 1024;
-
-    /**
-     * How many page fetches may be in flight at once, across every registered reader.
-     *
-     * The number that matters to a browser and to a CDN, and the one no reader can set: eight
-     * readers at the per-reader default of 6 were measured issuing 48 concurrent range requests.
-     * Twelve is more than one HTTP/1.1 connection pool will give and less than an H2/H3 multiplex
-     * will happily carry, which is the range this wants to sit in.
-     *
-     * @type {number}
-     */
-    max_concurrent_fetches = 12;
-
-    /**
-     * How many frames a page is protected from eviction after it was last touched.
-     *
-     * Design §6: eviction is LRU on **last-touched**, with a protect window no shorter than the
-     * feedback latency. The window is what stops the classic fallback-chain bug — feedback arrives a
-     * frame or three late, so a page that is on screen right now may not have been reported as
-     * touched yet, and evicting on a stamp that has not caught up evicts exactly what is being
-     * drawn. Three frames is one `mapAsync` round trip's worth of slack.
-     *
-     * @type {number}
-     */
-    protect_frames = 3;
-}

package/src/shade/renderer/loader/gltf/fix_up_material_sides.js

@@ -1,109 +0,0 @@
-import { assert } from "../../../../core/assert.js";
-import { geometry_flip_normals } from "../../geometry/util/geometry_flip_normals.js";
-
-import { ShadeDrawSide } from "../../material/ShadeDrawSide.js";
-
-/**
- *
- * @param {Mesh[]} meshes
- * @returns {{geometries_modified:number, primitives_delta: number}}
- */
-export function fix_up_material_sides(meshes) {
-
-    /**
-     *
-     * @type {Map<ShadeDrawSide, Set<MeshletGeometry>>}
-     */
-    const material_bindings_forward = new Map();
-
-    /**
-     *
-     * @type {Map<MeshletGeometry, Set<ShadeDrawSide>>}
-     */
-    const material_bindings_backward = new Map();
-
-    // build indices
-    for (let i = 0; i < meshes.length; i++) {
-        const mesh = meshes[i];
-
-        const geometry = mesh.geometry;
-        const material = mesh.material;
-
-        const side = material.draw_side;
-
-        let material_set = material_bindings_backward.get(geometry);
-        if (material_set === undefined) {
-            material_set = new Set();
-            material_bindings_backward.set(geometry, material_set);
-        }
-
-        let geometry_set = material_bindings_forward.get(side);
-        if (geometry_set === undefined) {
-            geometry_set = new Set();
-            material_bindings_forward.set(side, geometry_set);
-        }
-
-
-        material_set.add(side);
-        geometry_set.add(geometry);
-
-    }
-
-    /**
-     * Number of primitives added/removed
-     * @type {number}
-     */
-    let primitives_delta = 0;
-
-    /**
-     *
-     * @type {Set<Geometry>}
-     */
-    const failed_to_fix = new Set();
-    const fixed = new Set();
-
-    const back_set = material_bindings_forward.get(ShadeDrawSide.Back);
-    if (back_set !== undefined) {
-        for (const geometry of back_set) {
-            assert.equal(fixed.has(geometry), false, 'geometry already fixed');
-
-            const draw_set = material_bindings_backward.get(geometry);
-
-            if (draw_set.size !== 1) {
-                // more than one sidedness usage, can't fix
-
-                failed_to_fix.add(geometry);
-
-                continue;
-            }
-
-
-            geometry_flip_normals(geometry);
-            fixed.add(geometry);
-        }
-    }
-
-    if (failed_to_fix.size > 0) {
-        console.warn(`Failed to fix up ${failed_to_fix.size} materials with sidedness`);
-    }
-
-    // set all material sides to front
-    for (const mesh of meshes) {
-        if (mesh.material.draw_side === ShadeDrawSide.Back) {
-            if (failed_to_fix.has(mesh.geometry)) {
-                // geometry was never flipped — rewriting the
-                // material to Front would draw the unflipped
-                // geometry inside-out
-                continue;
-            }
-
-            // side was flipped
-            mesh.material.draw_side = ShadeDrawSide.Front;
-        }
-    }
-
-    return {
-        geometries_modified: fixed.size,
-        primitives_delta,
-    };
-}

package/src/shade/renderer/rasterize/expand/graph_triangles_filter_by_material_side.js

@@ -1,78 +0,0 @@
-import { BufferResourceDescriptor } from "../../../device/graph/BufferResourceDescriptor.js";
-import { STRUCT_DISPATCH_COMPUTE_COMMAND } from "../../gpu_primitive/indirect/STRUCT_DISPATCH_COMPUTE_COMMAND.js";
-import { build_indirect_compute_dispatch_command } from "../../gpu_primitive/indirect/IndirectComputeCommandBuildPass.js";
-import { shader_filter_triangle_by_material_side } from "./shader_filter_triangle_by_material_side.js";
-
-/**
- *
- * @param {Object} options
- * @param {FrameGraph} options.graph
- * @param {GPUCameraContext} options.camera
- * @param {GPUSceneContext} options.scene
- * @param {number} options.input
- * @param {number} options.output_size
- */
-export function graph_triangles_filter_by_material_side({
-                                                            graph,
-                                                            camera,
-                                                            scene,
-                                                            input,
-                                                            output_size
-                                                        }) {
-
-    /**
-     *
-     * @param data
-     * @param {FramePassResources} resources
-     * @param {GraphicsExecutionContext} context
-     */
-    function execute(data, resources, context) {
-        const input = resources.get(data.input);
-        const output = resources.get(data.output);
-        const command = resources.get(data.command);
-
-        const encoder = context.encoder;
-
-        build_indirect_compute_dispatch_command(
-            256,
-            encoder,
-            input,
-            0,
-            command,
-            0
-        );
-
-        shader_filter_triangle_by_material_side.dispatchIndirect({
-            encoder,
-            command,
-            bindings: {
-                input,
-                output,
-                camera: camera.buffer.buffer,
-
-                geometries: scene.geometries.buffer_metadata,
-
-                scene_database: scene.scene_database_buffer,
-                materials: scene.materials.metadata_table.buffer
-            }
-        });
-    }
-
-    const data = {};
-
-    const pass = graph.add("filter triangles by material side", data, execute);
-    data.input = pass.read(input);
-    data.output = pass.create("output",
-        BufferResourceDescriptor.from(
-            output_size,
-            GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC,
-            0, 16
-        )
-    );
-    data.command = pass.create("command", BufferResourceDescriptor.from(
-        STRUCT_DISPATCH_COMPUTE_COMMAND.aligned_size,
-        GPUBufferUsage.INDIRECT | GPUBufferUsage.STORAGE,
-    ));
-
-    return data.output;
-}

package/src/shade/renderer/rasterize/expand/shader_filter_triangle_by_material_side.js

@@ -1,100 +0,0 @@
-import { atomic_u32, u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
-import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
-import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
-import { CAMERA_UNIFORM_STRUCT } from "../../camera/CAMERA_UNIFORM_STRUCT.js";
-import { MATERIAL_METADATA_STRUCT } from "../../material/MATERIAL_METADATA_STRUCT.js";
-import { chunk_scene_database_access } from "../../scene/chunk_scene_database_access.js";
-import {
-    chunk_geometry_read_triangle_positions
-} from "../../shader/chunk/geometry/format/chunk_geometry_read_triangle_positions.js";
-import {
-    chunk_compute_triangle_face_normal
-} from "../../shader/chunk/geometry/normal/chunk_compute_triangle_face_normal.js";
-import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
-import { ComputeShader } from "../../shader/ComputeShader.js";
-import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
-import { GEOMETRY_METADATA_STRUCT } from "../../geometry/GEOMETRY_METADATA_STRUCT.js";
-import { MESH_TRIANGLE_REFERENCE_STRUCT } from "../../geometry/meshlet/MESH_TRIANGLE_REFERENCE_STRUCT.js";
-import { chunk_material_side_should_draw } from "../forward/chunk_material_side_should_draw.js";
-
-const resources = new ShaderResourceSetDescriptor();
-resources.createGroup()
-    .addUniform('camera', CAMERA_UNIFORM_STRUCT)
-    .addStorageBuffer('input', WebGPUStruct.from({
-        count: u32,
-        elements: WebGPUArray.from(MESH_TRIANGLE_REFERENCE_STRUCT)
-    }))
-    .addStorageBuffer('output', WebGPUStruct.from({
-        count: atomic_u32,
-        elements: WebGPUArray.from(MESH_TRIANGLE_REFERENCE_STRUCT)
-    }), true)
-    .addStorageBuffer('geometries', WebGPUArray.from(GEOMETRY_METADATA_STRUCT))
-    .addStorageBuffer('scene_database', WebGPUArray.from(u32))
-    .addStorageBuffer("materials", WebGPUArray.from(MATERIAL_METADATA_STRUCT))
-
-
-const body = CodeChunk.from(
-    //language=WGSL
-    `
-@compute @workgroup_size(256, 1, 1)
-fn main(
-    @builtin(global_invocation_id) global_id : vec3<u32>
-){
-    let i = global_id.x;
-
-    if(i >= input.count){
-        return;
-    }
-    
-    let triangle_def = input.elements[i];
-
-    let instance = scene_read_mesh(&scene_database, triangle_def.mesh);
-    let node = scene_read_node(&scene_database, instance.node);
-
-    let material = materials[instance.material];
-
-    let geometry = geometries[instance.geometry];
-
-    var v0:vec3f;
-    var v1:vec3f;
-    var v2:vec3f;
-
-    geometry_read_triangle_positions(&v0, &v1, &v2, geometry, triangle_def.index);
-
-
-    // compute model-view-projection matrix
-    let mvp = camera.view_projection_matrix * node.global;
-    
-    let p_v0 = mvp * vec4( v0, 1.0 );
-    let p_v1 = mvp * vec4( v1, 1.0 );
-    let p_v2 = mvp * vec4( v2, 1.0 );
-    
-    var clip_v0 = vec3(p_v0.xyz/ p_v0.w);
-    var clip_v1 = vec3(p_v1.xyz/ p_v1.w);
-    var clip_v2 = vec3(p_v2.xyz/ p_v2.w);
-        
-    
-    // Compute normal in view space
-    let normal_ndc = compute_triangle_face_normal(clip_v0, clip_v1, clip_v2);
-    
-    let triangle_front_facing = normal_ndc.z > 0.0;
-    
-    if(!material_side_should_draw(triangle_front_facing, material.draw_side)){
-        return;
-    }
-    
-    output.elements[atomicAdd(&output.count, 1u)] = triangle_def;
-}
-    `, [
-        chunk_geometry_read_triangle_positions,
-        chunk_compute_triangle_face_normal,
-        chunk_material_side_should_draw,
-        chunk_scene_database_access,
-    ]
-)
-
-export const shader_filter_triangle_by_material_side = ComputeShader.from({
-    label: "Filter triangle by material's side",
-    body,
-    resources
-})

package/src/shade/renderer/rasterize/forward/chunk_material_side_should_draw.js

@@ -1,26 +0,0 @@
-import { ShadeDrawSide } from "../../material/ShadeDrawSide.js";
-import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
-
-/**
- * NOTE: draw_side is a {@link ShadeDrawSide} enum value, not a bitmask.
- * @see ShadeDrawSide
- * @type {CodeChunk}
- */
-export const chunk_material_side_should_draw = CodeChunk.from(
-    //language=WGSL
-    `
-fn material_side_should_draw( front_facing:bool, draw_side: u32) -> bool{
-
-    if (draw_side == ${ShadeDrawSide.Double}u) {
-        return true;
-    }
-
-    if (draw_side == ${ShadeDrawSide.Back}u) {
-        return !front_facing;
-    }
-
-    // ShadeDrawSide.Front
-    return front_facing;
-}
-    `
-)

package/src/shade/renderer/shader/chunk/jobs/NOTES.md

@@ -1,47 +0,0 @@
-see https://youtu.be/nWgPtCDXlPc?si=QcFQ62Wz3I6W4FEE&t=1881
-
-Original code from Capcom:
-
-```hlsl
-bool JobScattering(uint job) {
-    if (job != JOB_EMPTY) {
-        uint counts = WaveActiveCountBits(1);
-        uint writeoffset = 0;
-        if (WaveIsFirstLane()) {
-            RingBuffer.InterlockedAdd(JOB_RING_TAIL, counts, writeoffset);
-        }
-
-        writeoffset = WaveReadLaneFirst(writeoffset) + WavePrefixCountBits(1);
-        writeoffset &= WORK_BUFFER_SIZE_IN_DWORD - 1;
-        uint ret;
-        RingBuffer.InterlockedCompareExchange(writeoffset * 4, JOB_EMPTY, job, ret);
-        if (ret == JOB_EMPTY) {
-            uint counts = WaveActiveCountBits(1);
-            if (WaveIsFirstLane()) {
-                RingBuffer.InterlockedAdd(JOB_COUNT, counts);
-            }
-            return true;
-        }
-    }
-    return false;
-}
-
-bool JobGathering(out uint job) {
-    uint counts = WaveActiveCountBits(1);
-    uint readoffset = 0;
-    if (WaveIsFirstLane()) {
-        RingBuffer.InterlockedAdd(JOB_RING_HEAD, counts, readoffset);
-    }
-    readoffset = WaveReadLaneFirst(readoffset) + WavePrefixCountBits(1);
-    readoffset &= WORK_BUFFER_SIZE_IN_DWORD - 1;
-    RingBuffer.InterlockedMin(readoffset * 4, JOB_EMPTY, job);
-    if (job != JOB_EMPTY) {
-        int counts = (int)WaveActiveCountBits(1);
-        if (WaveIsFirstLane()) {
-            RingBuffer.InterlockedAdd(JOB_COUNT, -counts);
-        }
-        return true;
-    }
-    return false;
-}
-```

package/src/shade/renderer/shader/chunk/jobs/chunk_job_system.d.ts

@@ -1,3 +0,0 @@
-export const chunk_job_system: CodeChunk;
-import { CodeChunk } from "../../compiler/CodeChunk.js";
-//# sourceMappingURL=chunk_job_system.d.ts.map

package/src/shade/renderer/shader/chunk/jobs/chunk_job_system.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"chunk_job_system.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shader/chunk/jobs/chunk_job_system.js"],"names":[],"mappings":"AAEA,yCAmGC;0BArGyB,6BAA6B"}

package/src/shade/renderer/shader/chunk/jobs/chunk_job_system.js

@@ -1,102 +0,0 @@
-import { CodeChunk } from "../../compiler/CodeChunk.js";
-
-export const chunk_job_system = CodeChunk.from(
-    //language=WGSL
-    `
-
-const JOB_RING_TAIL: u32 = 0u;
-const JOB_RING_HEAD: u32 = 1u;
-const JOB_COUNT: u32 = 2u;
-
-const JOB_EMPTY: u32 = 0u;
-const WORK_BUFFER_SIZE: u32 = 512u; 
-
-var<workgroup> jobs_ring_buffer: array<atomic<u32>, WORK_BUFFER_SIZE>;
-
-// --- Helper function for WaveActiveCountBits ---
-// HLSL's WaveActiveCountBits(1) counts all active invocations (lanes) in the wave.
-// In WGSL, we can achieve this by getting a bitmask of all active invocations
-// with subgroupBallot(true) and then counting the set bits (1s).
-fn subgroup_active_count() -> u32 {
-    let ballot = subgroupBallot(true); // Returns vec4<u32> bitmask
-    return countOneBits(ballot.x) + countOneBits(ballot.y) +
-           countOneBits(ballot.z) + countOneBits(ballot.w);
-}
-
-
-// --- Translated Functions ---
-
-/// @brief Scatters a job into the ring buffer.
-/// Corresponds to the HLSL \`JobScattering\` function.
-fn jobScattering(job: u32) -> bool {
-    if (job != JOB_EMPTY) {
-        // WaveActiveCountBits(1) -> Get the total number of active invocations.
-        let counts = subgroup_active_count();
-        var writeoffset: u32 = 0u;
-
-        // WaveIsFirstLane() -> subgroupElect()
-        // The first active invocation atomically reserves a block of 'counts' size.
-        if (subgroupElect()) {
-            // InterlockedAdd -> atomicAdd. Returns the original value before the addition.
-            writeoffset = atomicAdd(&jobs_ring_buffer[JOB_RING_TAIL], counts);
-        }
-
-        // WaveReadLaneFirst -> subgroupBroadcastFirst
-        // Broadcast the base offset from the first lane to all others.
-        // WavePrefixCountBits -> subgroupExclusiveAdd(1u)
-        // Each active lane gets a unique index within the reserved block.
-        writeoffset = subgroupBroadcastFirst(writeoffset) + subgroupExclusiveAdd(1u);
-        writeoffset = writeoffset & (WORK_BUFFER_SIZE - 1u);
-
-        // InterlockedCompareExchange -> atomicCompareExchangeWeak
-        // Attempt to write the job into the slot if it's empty.
-        // We use .old_value as the HLSL function returns the original value.
-        let result = atomicCompareExchangeWeak(&jobs_ring_buffer[writeoffset], JOB_EMPTY, job);
-
-        if (result.old_value == JOB_EMPTY) {
-            // If the write was successful (the slot was empty), update the total job count.
-            let final_counts = subgroup_active_count();
-            if (subgroupElect()) {
-                // The '_' ignores the return value of atomicAdd, as we don't need it here.
-                _ = atomicAdd(&jobs_ring_buffer[JOB_COUNT], final_counts);
-            }
-            return true;
-        }
-    }
-    return false;
-}
-
-/// @brief Gathers a job from the ring buffer.
-/// Corresponds to the HLSL \`JobGathering\` function.
-/// WGSL uses pointers for 'out' parameters.
-fn jobGathering(job_out: ptr<function, u32>) -> bool {
-    let counts = subgroup_active_count();
-    var readoffset: u32 = 0u;
-
-    if (subgroupElect()) {
-        readoffset = atomicAdd(&jobs_ring_buffer[JOB_RING_HEAD], counts);
-    }
-
-    readoffset = subgroupBroadcastFirst(readoffset) + subgroupExclusiveAdd(1u);
-    readoffset = readoffset & (WORK_BUFFER_SIZE - 1u);
-
-    // InterlockedMin -> atomicMin
-    // Atomically read the job and replace it with JOB_EMPTY.
-    // This effectively "takes" the job from the queue.
-    *job_out = atomicMin(&jobs_ring_buffer[readoffset], JOB_EMPTY);
-
-    if (*job_out != JOB_EMPTY) {
-        // If a valid job was successfully gathered, decrement the total job count.
-        let final_counts = subgroup_active_count();
-        if (subgroupElect()) {
-            // WGSL's atomicAdd on a u32 wraps around, which is equivalent
-            // to subtraction when using two's complement representation.
-            _ = atomicAdd(&jobs_ring_buffer[JOB_COUNT], u32(-i32(final_counts)));
-        }
-        return true;
-    }
-    return false;
-}
-
-`
-)