@woosh/meep-engine 3.29.0 → 3.31.0

package/src/engine/graphics3/terrain/GPUTerrainSplatRenderer.js

@@ -1,481 +0,0 @@
-import { assert } from "../../../core/assert.js";
-import { GBufferTextures } from "../../../shade/renderer/extension/GBufferTextures.js";
-import { ViewTextures } from "../../../shade/renderer/extension/ViewTextures.js";
-import { round_up } from "../../../core/math/round_up.js";
-import { SamplerDescriptor } from "../../../shade/descriptor/texture/SamplerDescriptor.js";
-import { TextureDescriptor } from "../../../shade/descriptor/texture/TextureDescriptor.js";
-import { TextureViewDescriptor } from "../../../shade/descriptor/texture/TextureViewDescriptor.js";
-import { TextureResourceDescriptor } from "../../../shade/device/graph/TextureResourceDescriptor.js";
-import { G_BUFFER_ALBEDO_FORMAT } from "../../../shade/renderer/gbuffer/G_BUFFER_ALBEDO_FORMAT.js";
-import { TextureFilterType } from "../../../shade/renderer/texture/TextureFilterType.js";
-import { shader_terrain_splat, TERRAIN_SPLAT_SETTINGS } from "./shader_terrain_splat.js";
-
-/**
- * Buffers grow with headroom and never shrink — the row table is sized by the highest mesh row a
- * tile occupies, and rows move as the scene streams.
- *
- * @type {number}
- */
-const GROWTH_FACTOR = 1.5;
-
-/**
- * What the legacy weight texture declared: linear magnification, no mip chain, edges clamped.
- */
-const SAMPLER_SPLAT_WEIGHTS = Object.freeze(SamplerDescriptor.from({
-    magFilter: "linear",
-    minFilter: "nearest",
-    addressModeU: "clamp-to-edge",
-    addressModeV: "clamp-to-edge"
-}));
-
-/**
- * What the legacy layer array declared: trilinear over a full mip chain, repeat wrap — the layers
- * tile — and the same anisotropy.
- */
-const SAMPLER_TERRAIN_LAYERS = Object.freeze(SamplerDescriptor.from({
-    magFilter: "linear",
-    minFilter: "linear",
-    mipmapFilter: "linear",
-    addressModeU: "repeat",
-    addressModeV: "repeat",
-    maxAnisotropy: 8
-}));
-
-const SAMPLER_OVERLAY_SPRITE = Object.freeze(SamplerDescriptor.from({
-    magFilter: "linear",
-    minFilter: "linear",
-    addressModeU: "clamp-to-edge",
-    addressModeV: "clamp-to-edge"
-}));
-
-/**
- * The whole-array view, said explicitly: a one-layer terrain would otherwise get the "2d" default
- * view of its depth-1 texture, which does not bind against a `texture_2d_array` declaration.
- */
-const VIEW_2D_ARRAY = TextureViewDescriptor.from({ dimension: "2d-array" });
-
-/**
- * One CPU image as the GPU holds it — the array the texture was last written from and its version
- * together say whether the texture still agrees with the source.
- */
-class TextureResidency {
-    /**
-     * @type {GPUTextureContext|null}
-     */
-    texture = null;
-
-    /**
-     * @type {number}
-     */
-    version = -1;
-
-    /**
-     * @type {*}
-     */
-    source = null;
-}
-
-/**
- * Draws one terrain's splat and grid overlay into the G-buffer's albedo.
- *
- * Two passes: this frame's tables and any changed textures are uploaded, and the composite reads
- * the albedo the material pass wrote and writes a replacement — publishing into
- * {@link GBufferTextures} (D23) is what carries it downstream. One renderer per terrain, owned by the system's
- * entry for it, because every texture here is the terrain's own.
- */
-export class GPUTerrainSplatRenderer {
-    /**
-     * @type {{buffer: GPUBuffer|null}}
-     */
-    #rows = { buffer: null };
-
-    /**
-     * @type {number} capacity in bytes
-     */
-    #rows_capacity = 0;
-
-    /**
-     * @type {{buffer: GPUBuffer|null}}
-     */
-    #scales = { buffer: null };
-
-    /**
-     * @type {number} capacity in bytes
-     */
-    #scales_capacity = 0;
-
-    /**
-     * @type {TextureResidency}
-     */
-    #weights = new TextureResidency();
-
-    /**
-     * @type {TextureResidency}
-     */
-    #layers = new TextureResidency();
-
-    /**
-     * @type {TextureResidency}
-     */
-    #overlay = new TextureResidency();
-
-    /**
-     * @type {TextureResidency}
-     */
-    #sprite = new TextureResidency();
-
-    /**
-     * Record this terrain's splat into the frame and hand the replacement albedo back through the
-     * context.
-     *
-     * @param {object} args
-     * @param {FrameContext} args.frame
-     * @param {Uint32Array} args.rows 1 where a mesh row belongs to this terrain
-     * @param {number} args.row_count rows in use — one past the highest row marked
-     * @param {Float32Array} args.scales two floats per layer, the legacy `materialScalesMap`
-     * @param {number} args.layer_count
-     * @param {Float32Array} args.world_to_terrain inverse of the terrain entity's world matrix
-     * @param {number[]} args.inv_world_size `1 / (size × gridScale)` per axis
-     * @param {number[]} args.grid_transform scale xy, offset zw
-     * @param {number[]} args.grid_resolution the terrain's size in cells
-     * @param {{data: Uint8Array, width: number, height: number, depth: number, version: number}} args.weights
-     * @param {{data: Uint8Array, width: number, height: number, depth: number, version: number}} args.layer_image
-     * @param {Sampler2D} args.overlay the per-cell rgba map
-     * @param {Sampler2D} args.sprite the cell sprite, rgba
-     */
-    graph_draw({
-        frame,
-        rows, row_count,
-        scales, layer_count,
-        world_to_terrain,
-        inv_world_size,
-        grid_transform,
-        grid_resolution,
-        weights,
-        layer_image,
-        overlay,
-        sprite
-    }) {
-        assert.defined(frame, 'frame');
-        assert.isNonNegativeInteger(row_count, 'row_count');
-        assert.isNonNegativeInteger(layer_count, 'layer_count');
-
-        const graph = frame.graph;
-        const gbuffer = frame.get(GBufferTextures);
-        const resolution = frame.resolution;
-
-        const upload = {};
-
-        graph.add('terrain / upload', upload, (data, resources, execution) => {
-            this.#upload(execution.graphics, rows, row_count, scales, layer_count, weights, layer_image, overlay, sprite);
-        }).make_side_effect();
-
-        const data = {};
-
-        const pass = graph.add('terrain / splat', data, (data, resources, execution) => {
-            this.#execute(data, resources, execution, {
-                camera: frame.view.camera,
-                resolution,
-                row_count,
-                layer_count,
-                world_to_terrain,
-                inv_world_size,
-                grid_transform,
-                grid_resolution
-            });
-        });
-
-        const view_textures = frame.get(ViewTextures);
-
-        data.depth = pass.read(view_textures.depth);
-        data.viz_mesh = pass.read(view_textures.visibility_mesh);
-
-        data.in_albedo = pass.read(gbuffer.albedo);
-        data.in_normal = pass.read(gbuffer.normal);
-
-        data.out_albedo = pass.create("g-buffer / Albedo + terrain", TextureResourceDescriptor.from({
-            format: G_BUFFER_ALBEDO_FORMAT,
-            resolution,
-            usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING,
-        }));
-
-        /*
-         Everything downstream — decals included, because they declare themselves after this — now
-         reads the textured ground, and the graph knows it does. Only the albedo moves; the other
-         three channels were already what the terrain means them to be.
-        */
-        gbuffer.albedo = data.out_albedo;
-    }
-
-    /**
-     * @param data
-     * @param {FramePassResources} resources
-     * @param {GraphicsExecutionContext} context
-     * @param {object} frame
-     */
-    #execute(data, resources, context, frame) {
-        const encoder = context.encoder;
-        const graphics = context.graphics;
-
-        const settings = encoder.allocateTransientValueBuffer(TERRAIN_SPLAT_SETTINGS, {
-            world_to_terrain: frame.world_to_terrain,
-            grid_transform: frame.grid_transform,
-            inv_world_size: frame.inv_world_size,
-            grid_resolution: frame.grid_resolution,
-            screen_resolution: frame.resolution,
-            layer_count: frame.layer_count,
-            row_table_size: frame.row_count,
-        });
-
-        /**
-         * @param {number} handle
-         * @returns {GPUTextureView}
-         */
-        const view = handle => resources.get(handle).obtainView();
-
-        shader_terrain_splat.draw({
-            encoder,
-            bindings: {
-                camera: frame.camera.buffer,
-                settings,
-                gBufferAlbedo: view(data.in_albedo),
-                gBufferNormal: view(data.in_normal),
-                scene_depth: view(data.depth),
-                viz_mesh: view(data.viz_mesh),
-                terrain_rows: this.#rows.buffer,
-                layer_scales: this.#scales.buffer,
-                splat_weights: this.#weights.texture.obtainView(VIEW_2D_ARRAY),
-                splat_sampler: graphics.samplers.obtain(SAMPLER_SPLAT_WEIGHTS),
-                layer_diffuse: this.#layers.texture.obtainView(VIEW_2D_ARRAY),
-                layer_sampler: graphics.samplers.obtain(SAMPLER_TERRAIN_LAYERS),
-                overlay_map: this.#overlay.texture.obtainView(),
-                overlay_sprite: this.#sprite.texture.obtainView(),
-                sprite_sampler: graphics.samplers.obtain(SAMPLER_OVERLAY_SPRITE),
-            },
-            colorAttachments: [{
-                loadOp: "clear",
-                storeOp: "store",
-                view: resources.get(data.out_albedo).obtainView(TextureViewDescriptor.from({
-                    mipLevelCount: 1,
-                    baseMipLevel: 0
-                }))
-            }],
-            color_formats: [G_BUFFER_ALBEDO_FORMAT]
-        });
-    }
-
-    /**
-     * @param {GraphicsContext} graphics
-     * @param {Uint32Array} rows
-     * @param {number} row_count
-     * @param {Float32Array} scales
-     * @param {number} layer_count
-     * @param {{data: Uint8Array, width: number, height: number, depth: number, version: number}} weights
-     * @param {{data: Uint8Array, width: number, height: number, depth: number, version: number}} layer_image
-     * @param {Sampler2D} overlay
-     * @param {Sampler2D} sprite
-     */
-    #upload(graphics, rows, row_count, scales, layer_count, weights, layer_image, overlay, sprite) {
-        const device = graphics.device;
-
-        this.#rows.buffer = upload_buffer(
-            device, this.#rows.buffer, this.#rows_capacity, rows, row_count, "terrain/rows"
-        );
-        this.#rows_capacity = Math.max(this.#rows_capacity, this.#rows.buffer.size);
-
-        this.#scales.buffer = upload_buffer(
-            device, this.#scales.buffer, this.#scales_capacity, scales, layer_count * 2, "terrain/layer_scales"
-        );
-        this.#scales_capacity = Math.max(this.#scales_capacity, this.#scales.buffer.size);
-
-        /*
-         The weight array has no mip chain — the legacy texture never generated one — and one byte
-         per texel per layer keeps the upload the size of the authored data.
-        */
-        this.#upload_texture(graphics, this.#weights, {
-            data: weights.data,
-            width: weights.width,
-            height: weights.height,
-            depth: weights.depth,
-            version: weights.version,
-            format: "r8unorm",
-            bytes_per_pixel: 1,
-            mips: false,
-            label: "terrain/splat_weights"
-        });
-
-        /*
-         The layers are authored sRGB, and uploading them as such is what makes the shader's mix
-         linear without a decode of its own — the sampler decodes each texel before filtering,
-         which is the lesson §U3 carries forward. The mip chain is generated exactly as the decal
-         atlas generates its own, per array layer.
-        */
-        this.#upload_texture(graphics, this.#layers, {
-            data: layer_image.data,
-            width: layer_image.width,
-            height: layer_image.height,
-            depth: layer_image.depth,
-            version: layer_image.version,
-            format: `${G_BUFFER_ALBEDO_FORMAT}-srgb`,
-            bytes_per_pixel: 4,
-            mips: true,
-            label: "terrain/layers"
-        });
-
-        /*
-         Both overlay textures are sRGB for the same reason the layers are: the sprite is an
-         authored image and the cell map holds authored colours, and the grid overlay's mix in
-         gamma space is one of the two defects §U3 says to fix here rather than reproduce.
-        */
-        this.#upload_texture(graphics, this.#overlay, {
-            data: overlay.data,
-            width: overlay.width,
-            height: overlay.height,
-            depth: 1,
-            version: overlay.version,
-            format: `${G_BUFFER_ALBEDO_FORMAT}-srgb`,
-            bytes_per_pixel: 4,
-            mips: false,
-            label: "terrain/overlay_map"
-        });
-
-        this.#upload_texture(graphics, this.#sprite, {
-            data: sprite.data,
-            width: sprite.width,
-            height: sprite.height,
-            depth: 1,
-            version: sprite.version,
-            format: `${G_BUFFER_ALBEDO_FORMAT}-srgb`,
-            bytes_per_pixel: 4,
-            mips: false,
-            label: "terrain/overlay_sprite"
-        });
-    }
-
-    /**
-     * Put one image on the GPU, rewriting in place when its source moved and reallocating when its
-     * shape did.
-     *
-     * @param {GraphicsContext} graphics
-     * @param {TextureResidency} residency
-     * @param {object} image
-     */
-    #upload_texture(graphics, residency, image) {
-        const existing = residency.texture;
-
-        if (
-            existing === null
-            || existing.descriptor.size[0] !== image.width
-            || existing.descriptor.size[1] !== image.height
-            || existing.descriptor.size[2] !== image.depth
-        ) {
-            const mip_levels = image.mips ? 1 + Math.floor(Math.log2(Math.max(image.width, image.height))) : 1;
-
-            residency.texture = graphics.textures.contextFromDescriptor(TextureDescriptor.from({
-                label: image.label,
-                size: [image.width, image.height, image.depth],
-                format: image.format,
-                mipLevelCount: mip_levels,
-                /*
-                 `COPY_SRC` and `RENDER_ATTACHMENT` are the mip generator's, not this pass's: an
-                 sRGB source is decoded by copying the whole texture into a linear one before its
-                 levels can be averaged, and each level is rendered. Without them the copy fails
-                 validation and the frame it was encoded into is dropped whole — the decal atlas
-                 carries the same flags for the same reason.
-                */
-                usage: image.mips
-                    ? GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST | GPUTextureUsage.COPY_SRC | GPUTextureUsage.RENDER_ATTACHMENT
-                    : GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST
-            }));
-
-            residency.version = -1;
-            residency.source = null;
-        }
-
-        if (residency.source === image.data && residency.version === image.version) {
-            return;
-        }
-
-        graphics.device.queue.writeTexture(
-            { texture: residency.texture.gpu_texture },
-            image.data,
-            { bytesPerRow: image.width * image.bytes_per_pixel, rowsPerImage: image.height },
-            [image.width, image.height, image.depth]
-        );
-
-        if (image.mips) {
-            graphics.textures.mipmaps.generateMipmap(
-                residency.texture.gpu_texture,
-                residency.texture.descriptor,
-                TextureFilterType.Linear
-            );
-        }
-
-        residency.source = image.data;
-        residency.version = image.version;
-    }
-
-    destroy() {
-        if (this.#rows.buffer !== null) {
-            this.#rows.buffer.destroy();
-            this.#rows.buffer = null;
-        }
-
-        this.#rows_capacity = 0;
-
-        if (this.#scales.buffer !== null) {
-            this.#scales.buffer.destroy();
-            this.#scales.buffer = null;
-        }
-
-        this.#scales_capacity = 0;
-
-        for (const residency of [this.#weights, this.#layers, this.#overlay, this.#sprite]) {
-            if (residency.texture !== null) {
-                residency.texture.destroy();
-            }
-
-            residency.texture = null;
-            residency.version = -1;
-            residency.source = null;
-        }
-    }
-}
-
-/**
- * Write a typed array into a grow-with-headroom storage buffer, reallocating when it no longer
- * fits. Returns the buffer to keep — the caller tracks capacity off its `size`.
- *
- * @param {GPUDevice} device
- * @param {GPUBuffer|null} buffer
- * @param {number} capacity in bytes
- * @param {Float32Array|Uint32Array} data
- * @param {number} element_count
- * @param {string} label
- * @returns {GPUBuffer}
- */
-function upload_buffer(device, buffer, capacity, data, element_count, label) {
-    // a zero-length storage buffer is not a legal binding, and a terrain with no rows yet skips
-    // drawing anyway — the floor keeps the binding legal, not meaningful
-    const bytes = Math.max(4, element_count * data.BYTES_PER_ELEMENT);
-
-    let result = buffer;
-
-    if (capacity < bytes) {
-        if (result !== null) {
-            result.destroy();
-        }
-
-        result = device.createBuffer({
-            size: round_up(Math.ceil(bytes * GROWTH_FACTOR), 4),
-            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
-            label
-        });
-    }
-
-    if (element_count > 0) {
-        device.queue.writeBuffer(result, 0, data, 0, element_count);
-    }
-
-    return result;
-}

package/src/engine/graphics3/terrain/pack_terrain_row_table.js

@@ -1,48 +0,0 @@
-import { row_of_entity } from "../../../shade/renderer/scene/rows/GPUSceneRows.js";
-
-/**
- * The lookup the splat pass reads a visibility-buffer mesh row through: one word per row, 1 for a
- * row that is a tile of this terrain, 0 for anything else.
- *
- * A tile is an entity, and its row is the entity's, one on — so the table is sized by the highest
- * tile entity and the rows in between belong to whatever else the level holds. Whether a row has
- * been written yet is not this table's business: a row the scene has not placed is in no pixel of
- * the visibility buffer, and marking it costs nothing.
- *
- * @param {object} args
- * @param {Map<*, number>} args.tiles the terrain's tile entities, by whatever spawned them
- * @param {Uint32Array} args.table the previous frame's table, reused when it is long enough
- * @returns {{table: Uint32Array, size: number}} the table and how much of it is meaningful
- */
-export function pack_terrain_row_table({ tiles, table }) {
-    let highest = -1;
-
-    /*
-     Two sweeps, because the table has to be as long as the highest row before anything can be
-     written into it. Asking twice is cheaper than growing a typed array mid-walk — and is why this
-     takes the map rather than an iterator, which would be spent by the first.
-    */
-    for (const tile of tiles.values()) {
-        const row = row_of_entity(tile);
-
-        if (row > highest) {
-            highest = row;
-        }
-    }
-
-    const size = highest + 1;
-
-    let result = table;
-
-    if (result.length < size) {
-        result = new Uint32Array(size);
-    } else {
-        result.fill(0, 0, size);
-    }
-
-    for (const tile of tiles.values()) {
-        result[row_of_entity(tile)] = 1;
-    }
-
-    return { table: result, size };
-}