@woosh/meep-engine 3.30.0 → 3.32.0

package/src/shade/renderer/material/GPUMaterialContext.js

@@ -1,390 +1,255 @@
-import { assert } from "../../../core/assert.js";
-import { isDefined } from "../../../core/process/matcher/isDefined.js";
-import { RenderPipelineDescriptor } from "../../descriptor/pipeline/render/RenderPipelineDescriptor.js";
-import { write_gpu_typed_buffer } from "../shader/type/serde/write_gpu_typed_buffer.js";
-import { G_BUFFER_COLOR_TARGETS } from "../gbuffer/G_BUFFER_COLOR_TARGETS.js";
-import { sampler_descriptor_from_shade_texture } from "../texture/sampler_descriptor_from_shade_texture.js";
-import { MATERIAL_METADATA_STRUCT } from "./MATERIAL_METADATA_STRUCT.js";
-import {
-    g_buffer_scene_resources,
-    g_buffer_shader_resources,
-    g_buffer_viz_resources,
-    gbuffer_shader
-} from "./standard/fragment_gbuffer.js";
-import { SHADING_MATERIAL_VT_RESOURCE_GROUP } from "./standard/fragment_gbuffer_vt.js";
-import { material_gbuffer_vertex_shader_code } from "./standard/material_gbuffer_vertex.js";
-import { SHADING_MATERIAL_RESOURCE_GROUP } from "./standard/SHADING_MATERIAL_RESOURCE_GROUP.js";
-import { standard_material_to_struct } from "./standard_material_to_struct.js";
-
-/**
- * @typedef {import("../../device/pipeline/RenderPipelineManager.js").RenderPipelineManager} RenderPipelineManager
- * @typedef {import("../texture/GPUTextureContext.js").GPUTextureContext} GPUTextureContext
- * @typedef {import("../texture/ShadeTexture.js").ShadeTexture} ShadeTexture
- * @typedef {import("../texture/TextureManager.js").TextureManager} TextureManager
- * @typedef {import("../texture/virtual/VirtualTextureManager.js").VirtualTextureManager} VirtualTextureManager
- * @typedef {import("./ShadeMaterial.js").ShadeMaterial} ShadeMaterial
- * @typedef {import("./StandardShadeMaterial.js").StandardShadeMaterial} StandardShadeMaterial
- */
-
-export const MATERIAL_BIND_GROUP_VIZ_BUFFER = g_buffer_viz_resources.generateBindGroupLayoutDescriptor();
-
-export const MATERIAL_BIND_GROUP_SCENE_DATA = g_buffer_scene_resources.generateBindGroupLayoutDescriptor();
-
-const STANDARD_MATERIAL_PIPELINE_DESCRIPTOR = RenderPipelineDescriptor.from({
-    label: "Standard material / Viz-Buffer to G-Buffer laydown",
-    layout: g_buffer_shader_resources.generatePipelineLayoutDescriptor(),
-    vertex: {
-        module: {
-            code: material_gbuffer_vertex_shader_code
-        }
-    },
-    fragment: {
-        module: {
-            code: gbuffer_shader.source,
-        },
-        targets: G_BUFFER_COLOR_TARGETS
-
-    },
-    depthStencil: {
-        // depth is actually a material mask, we use trick from Unreal to mask materials using depth
-        depthCompare: 'equal',
-        format: 'depth32float',
-        depthWriteEnabled: false
-    },
-    primitive: {
-        topology: 'triangle-list',
-        cullMode: 'none',
-    }
-});
-
-let id_counter = 0;
-
-class GPUSampledTexture {
-    /**
-     * @type {GPUTextureContext}
-     */
-    texture
-
-    /**
-     * @type {GPUSampler}
-     */
-    sampler
-
-    /**
-     *
-     * @param {GPUTextureContext} texture
-     * @param {GPUSampler} sampler
-     */
-    constructor(texture, sampler) {
-        this.texture = texture;
-        this.sampler = sampler;
-    }
-}
-
-/**
- * Represents material variations for standard material for indirect draw
- */
-export class GPUMaterialContext {
-    #id = id_counter++;
-
-    /**
-     * @type {GPUDevice}
-     */
-    #device;
-
-
-    /**
-     * @type {StandardShadeMaterial}
-     */
-    #source
-
-    /**
-     *
-     * @return {StandardShadeMaterial}
-     */
-    get source() {
-        return this.#source;
-    }
-
-    /**
-     * @type {GPURenderPipeline}
-     */
-    pipeline;
-
-    /**
-     *
-     * @type {Map<ShadeTexture,GPUTextureContext>}
-     */
-    textures = new Map();
-
-
-    /**
-     * @type {GPUBuffer}
-     */
-    #uniform_buffer;
-
-    /**
-     *
-     * @return {GPUBuffer}
-     */
-    get uniform_buffer() {
-        return this.#uniform_buffer;
-    }
-
-    /**
-     * @type {GPUBindGroup}
-     */
-    #material_binding;
-
-    /**
-     *
-     * @return {GPUBindGroup}
-     */
-    get material_binding() {
-        return this.#material_binding;
-    }
-
-    /**
-     *
-     * @type {{}}
-     */
-    binding_data = {}
-
-    /**
-     *
-     * @return {boolean}
-     */
-    get is_built() {
-        return this.#material_binding !== undefined;
-    }
-
-
-    /**
-     * Bind group for the virtual-texture material variant: the VT globals
-     * (page table, stack info, cache layers) plus the regular emissive
-     * texture. Identical resources for every VT material — only
-     * material_info differs.
-     *
-     * @param {MaterialGPUDefaults} material_defaults
-     * @returns {GPUBindGroup}
-     */
-    #build_material_binding_vt(material_defaults) {
-        const device = this.#device;
-
-        const vt = material_defaults.virtual_textures;
-
-        assert.defined(vt, 'material uses a vt_stack but no VirtualTextureManager is wired');
-
-        const textures = this.textures;
-
-        let texture_emissive = {
-            texture: material_defaults.texture_pixel_white,
-            sampler: material_defaults.sampler
-        };
-
-        const source_emissive = this.#source.texture_emissive;
-
-        if (source_emissive !== undefined) {
-            texture_emissive = new GPUSampledTexture(
-                textures.get(source_emissive),
-                device.createSampler(sampler_descriptor_from_shade_texture(source_emissive))
-            );
-        }
-
-        const binding_data = {
-            material_info: { buffer: this.#uniform_buffer },
-
-            texture_emissive: texture_emissive.texture.obtainView(),
-            texture_emissive_sampler: texture_emissive.sampler,
-
-            vt_page_table: vt.page_table_view,
-            vt_stacks: { buffer: vt.stack_info_buffer },
-            vt_cache_albedo: vt.cache.views[0],
-            vt_cache_normal: vt.cache.views[1],
-            vt_cache_orm: vt.cache.views[2],
-            vt_cache_sampler: vt.cache_sampler,
-        };
-
-        this.binding_data = binding_data;
-
-        return device.createBindGroup({
-            layout: this.pipeline.getBindGroupLayout(0),
-            entries: SHADING_MATERIAL_VT_RESOURCE_GROUP.generateGPUBindGroupEntryArray(binding_data)
-        });
-    }
-
-    /**
-     *
-     * @param {MaterialGPUDefaults} material_defaults
-     * @returns {GPUBindGroup}
-     */
-    #build_material_binding(material_defaults) {
-        if (this.#source.vt_stack != null) {
-            return this.#build_material_binding_vt(material_defaults);
-        }
-
-        const device = this.#device;
-
-        const textures = this.textures;
-
-        /**
-         *
-         * @param {ShadeTexture} [source]
-         * @param {{texture:GPUTextureContext, sampler:GPUSampler}} defaults
-         * @returns {{texture:GPUTextureContext, sampler:GPUSampler}}}
-         */
-        function prepare_gpu_texture(source, defaults) {
-            if (source === undefined) {
-                return defaults;
-            }
-
-            const texture = textures.get(source);
-
-            const descriptor = sampler_descriptor_from_shade_texture(source);
-
-            const sampler = device.createSampler(descriptor);
-
-            return new GPUSampledTexture(
-                texture,
-                sampler
-            );
-        }
-
-        const texture_diffuse = prepare_gpu_texture(this.#source.texture_albedo, {
-            texture: material_defaults.texture_pixel_white,
-            sampler: material_defaults.sampler
-        });
-
-        const texture_normal = prepare_gpu_texture(this.#source.texture_normal, {
-            texture: material_defaults.texture_pixel_normal,
-            sampler: material_defaults.sampler
-        });
-
-        const texture_orm = prepare_gpu_texture(this.#source.texture_orm, {
-            texture: material_defaults.texture_orm,
-            sampler: material_defaults.sampler
-        });
-
-        const texture_emissive = prepare_gpu_texture(this.#source.texture_emissive, {
-            texture: material_defaults.texture_pixel_white,
-            sampler: material_defaults.sampler
-        });
-
-        const binding_data = {
-            material_info: { buffer: this.#uniform_buffer },
-
-            texture_diffuse: texture_diffuse.texture.obtainView(),
-            texture_diffuse_sampler: texture_diffuse.sampler,
-
-            texture_normal: texture_normal.texture.obtainView(),
-            texture_normal_sampler: texture_normal.sampler,
-
-            texture_orm: texture_orm.texture.obtainView(),
-            texture_orm_sampler: texture_orm.sampler,
-
-            texture_emissive: texture_emissive.texture.obtainView(),
-            texture_emissive_sampler: texture_emissive.sampler
-        };
-
-        this.binding_data = binding_data;
-
-        return device.createBindGroup({
-            layout: this.pipeline.getBindGroupLayout(0),
-            entries: SHADING_MATERIAL_RESOURCE_GROUP.generateGPUBindGroupEntryArray(binding_data)
-        });
-    }
-
-    /**
-     *
-     * @param {GPUDevice} device
-     * @param {ShadeMaterial|StandardShadeMaterial} source
-     */
-    constructor(device, source) {
-        assert.defined(device, 'device');
-        assert.defined(source, 'source');
-
-        this.#device = device;
-        this.#source = source;
-
-        this.#uniform_buffer = device.createBuffer({
-            label: 'uniforms',
-            usage: GPUBufferUsage.UNIFORM,
-            size: MATERIAL_METADATA_STRUCT.size,
-            mappedAtCreation: true,
-        });
-
-        const uniform_data = this.#uniform_buffer.getMappedRange();
-
-        write_gpu_typed_buffer(
-            standard_material_to_struct(source),
-            MATERIAL_METADATA_STRUCT,
-            uniform_data
-        );
-
-        this.#uniform_buffer.unmap();
-    }
-
-    /**
-     *
-     * @param {TextureManager} textures
-     * @param {RenderPipelineManager} render_pipelines
-     * @param {VirtualTextureManager} [virtual_textures]
-     */
-    build(textures, render_pipelines, virtual_textures) {
-        const material = this.#source;
-
-        if (material.vt_stack != null) {
-            // virtual-texture variant: albedo/normal/ORM stream through the
-            // stack; only emissive remains a resident texture
-            assert.defined(virtual_textures, 'material uses a vt_stack but no VirtualTextureManager is wired');
-
-            if (material.texture_emissive !== undefined) {
-                this.textures.set(material.texture_emissive, textures.obtain(material.texture_emissive));
-            }
-
-            this.pipeline = render_pipelines.obtain(virtual_textures.material_pipeline_descriptor);
-
-            return;
-        }
-
-        const material_textures = [
-            material.texture_albedo,
-            material.texture_normal,
-            material.texture_orm,
-            material.texture_emissive,
-        ].filter(isDefined);
-
-        // bind textures
-        for (let i = 0; i < material_textures.length; i++) {
-            const texture = material_textures[i];
-
-            const gpu_texture = textures.obtain(texture);
-
-            this.textures.set(texture, gpu_texture);
-        }
-
-        // build pipeline
-
-        this.pipeline = render_pipelines.obtain(STANDARD_MATERIAL_PIPELINE_DESCRIPTOR);
-    }
-
-
-    destroy() {
-        this.#uniform_buffer.destroy();
-    }
-
-    /**
-     *
-     * @param {MaterialGPUDefaults} defaults
-     * @returns {GPUBindGroup}
-     */
-    obtainMaterialBindGroup(defaults) {
-
-        if (this.#material_binding === undefined) {
-            this.#material_binding = this.#build_material_binding(defaults);
-        }
-
-        return this.#material_binding;
-    }
-
-}
+import { assert } from "../../../core/assert.js";
+import { queue_write_typed_buffer_data } from "../shader/type/queue_typed_buffer_update.js";
+import { write_gpu_typed_buffer } from "../shader/type/serde/write_gpu_typed_buffer.js";
+import { g_buffer_scene_resources, g_buffer_viz_resources } from "./standard/fragment_gbuffer.js";
+
+/**
+ * @typedef {import("../texture/GPUTextureContext.js").GPUTextureContext} GPUTextureContext
+ * @typedef {import("../texture/ShadeTexture.js").ShadeTexture} ShadeTexture
+ * @typedef {import("./ShadeMaterial.js").ShadeMaterial} ShadeMaterial
+ * @typedef {import("./template/GPUMaterialServices.js").GPUMaterialServices} GPUMaterialServices
+ * @typedef {import("./template/ShadeMaterialTemplate.js").ShadeMaterialTemplate} ShadeMaterialTemplate
+ */
+
+export const MATERIAL_BIND_GROUP_VIZ_BUFFER = g_buffer_viz_resources.generateBindGroupLayoutDescriptor();
+
+export const MATERIAL_BIND_GROUP_SCENE_DATA = g_buffer_scene_resources.generateBindGroupLayoutDescriptor();
+
+let id_counter = 0;
+
+/**
+ * One material as the GPU holds it: its uniform buffer, its group-0 bind group and the G-buffer
+ * pipeline of its template. What those contain is the template's to say — this is the same object
+ * for every template.
+ */
+export class GPUMaterialContext {
+    #id = id_counter++;
+
+    /**
+     * @type {GPUDevice}
+     */
+    #device;
+
+    /**
+     * @type {ShadeMaterial}
+     */
+    #source;
+
+    /**
+     * @return {ShadeMaterial}
+     */
+    get source() {
+        return this.#source;
+    }
+
+    /**
+     * The material's id, held here so the material pass reads a field rather than a getter per draw.
+     *
+     * @readonly
+     * @type {number}
+     */
+    material_id;
+
+    /**
+     * @type {ShadeMaterialTemplate}
+     */
+    #template;
+
+    /**
+     * @returns {ShadeMaterialTemplate}
+     */
+    get template() {
+        return this.#template;
+    }
+
+    /**
+     * @type {GPUMaterialServices|null}
+     */
+    #services = null;
+
+    /**
+     * The template's G-buffer pipeline.
+     *
+     * @type {GPURenderPipeline}
+     */
+    pipeline;
+
+    /**
+     * Textures the template obtained for this material, by source.
+     *
+     * @type {Map<ShadeTexture,GPUTextureContext>}
+     */
+    textures = new Map();
+
+    /**
+     * Whatever the template keeps per material beyond the above — terrain's texture residencies.
+     *
+     * @type {*}
+     */
+    state = null;
+
+    /**
+     * The material version the metadata row and the uniform were last written at.
+     *
+     * @type {number}
+     */
+    staged_version = -1;
+
+    /**
+     * The transparency mode at that version — whether the G-buffer pass draws the material.
+     *
+     * @type {number}
+     */
+    staged_transparency_mode = -1;
+
+    /**
+     * @type {GPUBuffer|null}
+     */
+    #uniform_buffer = null;
+
+    /**
+     * @return {GPUBuffer|null}
+     */
+    get uniform_buffer() {
+        return this.#uniform_buffer;
+    }
+
+    /**
+     * @type {GPUBindGroup|undefined}
+     */
+    #material_binding = undefined;
+
+    /**
+     * Group 0. Valid whenever {@link is_built}: a template that replaces a resource the group names
+     * has it rebuilt in the same update that replaced it.
+     *
+     * @return {GPUBindGroup|undefined}
+     */
+    get material_binding() {
+        return this.#material_binding;
+    }
+
+    /**
+     *
+     * @return {boolean}
+     */
+    get is_built() {
+        return this.#material_binding !== undefined;
+    }
+
+    /**
+     *
+     * @param {GPUDevice} device
+     * @param {ShadeMaterial} source
+     * @param {ShadeMaterialTemplate} template
+     */
+    constructor(device, source, template) {
+        assert.defined(device, 'device');
+        assert.defined(source, 'source');
+        assert.defined(template, 'template');
+        assert.equal(template.isShadeMaterialTemplate, true, 'template.isShadeMaterialTemplate !== true');
+
+        this.#device = device;
+        this.#source = source;
+        this.#template = template;
+        this.material_id = source.id;
+    }
+
+    /**
+     * Let the template obtain and upload what it binds, write the uniform, and take the template's
+     * G-buffer pipeline. The template goes first because what it registers can be part of the
+     * uniform — a virtual-texture stack's id.
+     *
+     * @param {GPUMaterialServices} services
+     */
+    build(services) {
+        const template = this.#template;
+
+        this.#services = services;
+
+        template.build(this, services);
+
+        const uniform_type = template.uniform_type;
+
+        if (uniform_type !== null) {
+            this.#uniform_buffer = this.#device.createBuffer({
+                label: `${template.name} material uniforms`,
+                // COPY_DST so a material whose version moves is rewritten in place — the bind group
+                // stays valid because the buffer is the same one
+                usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+                size: uniform_type.size,
+                mappedAtCreation: true,
+            });
+
+            write_gpu_typed_buffer(
+                template.uniform_value(this.#source),
+                uniform_type,
+                this.#uniform_buffer.getMappedRange()
+            );
+
+            this.#uniform_buffer.unmap();
+        }
+
+        this.pipeline = services.render_pipelines.obtain(template.gbuffer_pipeline_descriptor(services));
+    }
+
+    /**
+     * Rewrite the uniform from the material as it is now.
+     *
+     * @param {GPUQueue} queue
+     * @param {Object} [metadata] the metadata row just written for this version, see
+     *        {@link ShadeMaterialTemplate#uniform_value}
+     */
+    write_uniform(queue, metadata) {
+        const uniform_type = this.#template.uniform_type;
+
+        if (uniform_type === null) {
+            return;
+        }
+
+        queue_write_typed_buffer_data(
+            queue,
+            this.#uniform_buffer,
+            0,
+            uniform_type,
+            this.#template.uniform_value(this.#source, metadata)
+        );
+    }
+
+    /**
+     * Drop group 0 and build it again from what the template binds now.
+     */
+    rebuild_bind_group() {
+        this.#material_binding = undefined;
+
+        this.obtainMaterialBindGroup();
+    }
+
+    /**
+     * @returns {GPUBindGroup}
+     */
+    obtainMaterialBindGroup() {
+
+        if (this.#material_binding === undefined) {
+            this.#material_binding = this.#template.create_bind_group(
+                this,
+                this.pipeline.getBindGroupLayout(0),
+                this.#services
+            );
+        }
+
+        return this.#material_binding;
+    }
+
+    destroy() {
+        this.#template.destroy(this, this.#services);
+
+        if (this.#uniform_buffer !== null) {
+            this.#uniform_buffer.destroy();
+            this.#uniform_buffer = null;
+        }
+
+        this.#material_binding = undefined;
+    }
+
+}