@woosh/meep-engine 3.30.0 → 3.31.0

package/src/shade/renderer/material/GPUMaterialManager.d.ts

@@ -6,8 +6,9 @@ export class GPUMaterialManager {
      * @param {RenderPipelineManager} render_pipelines
      * @param {BindGroupManager} bindings
      * @param {VirtualTextureManager} [virtual_textures]
+     * @param {GPUSamplerManager} [samplers] required by templates that bind shared samplers — terrain's
      */
-    constructor(device: GPUDevice, textures: TextureManager, render_pipelines: RenderPipelineManager, bindings: BindGroupManager, virtual_textures?: VirtualTextureManager);
+    constructor(device: GPUDevice, textures: TextureManager, render_pipelines: RenderPipelineManager, bindings: BindGroupManager, virtual_textures?: VirtualTextureManager, samplers?: GPUSamplerManager);
     /**
      *
      * @type {Map<ShadeMaterial, GPUMaterialContext>}
@@ -49,6 +50,53 @@ export class GPUMaterialManager {
      * @returns {GPUMaterialContext}
      */
     obtain(material: ShadeMaterial): GPUMaterialContext;
+    /**
+     * Let a material's GPU side go: its uniform, its bind group, and whatever its template owns —
+     * terrain's textures. Nothing else releases a context, so a template that owns resources relies
+     * on its owner calling this when the material is done with.
+     *
+     * Release a material once nothing draws it — the terrain system drops its tiles first. One that
+     * is still drawn gets a new context from whatever next obtains it — the scene rows when its mesh
+     * row is rewritten, an alpha-tested or transparent pass — and the G-buffer pass, which does not
+     * create contexts, leaves it out until then.
+     *
+     * @param {ShadeMaterial} material
+     * @returns {boolean} whether there was a context to release
+     */
+    release(material: ShadeMaterial): boolean;
+    /**
+     * Give back every context's GPU side, the way {@link release} does for one — for the graphics
+     * context going away. A template's own resources, terrain's textures above all, are not owned
+     * by anything else that would free them.
+     */
+    destroy(): void;
+    /**
+     * Build a template's G-buffer pipeline now, rather than on the frame its first material is
+     * drawn. Pipeline creation is synchronous, so a template that first appears mid-game compiles
+     * on that frame; this lets its owner pay for it at a moment of its choosing — a level load.
+     *
+     * The alpha-tested pipelines of a template that can cut out are built on the first alpha-tested
+     * pass that meets one of its materials, as they always have been.
+     *
+     * @param {ShadeMaterialTemplate} template
+     */
+    prewarm(template: ShadeMaterialTemplate): void;
+    /**
+     * A scene's drawn materials grouped by template — the alpha-tested passes filter from this.
+     * Derived once per drawn set; the same array as `drawn` when it is already grouped.
+     *
+     * @param {ShadeMaterial[]} drawn a scene's {@link GPUSceneContext#drawn_materials}
+     * @returns {ShadeMaterial[]}
+     */
+    sorted_by_template(drawn: ShadeMaterial[]): ShadeMaterial[];
+    /**
+     * A scene's drawn materials that the transparent passes can draw, grouped by template. Derived
+     * once per drawn set; the same array as `drawn` when that is all of them and they are grouped.
+     *
+     * @param {ShadeMaterial[]} drawn a scene's {@link GPUSceneContext#drawn_materials}
+     * @returns {ShadeMaterial[]}
+     */
+    forward_drawable(drawn: ShadeMaterial[]): ShadeMaterial[];
     /**
      *
      * @param {ShadeGPUCommandContext} ctx
@@ -61,9 +109,11 @@ export type FrameGraph = import("../../../engine/graphics/render/frame_graph/Fra
 export type ShadeGPUCommandContext = import("../../device/ShadeGPUCommandContext.js").ShadeGPUCommandContext;
 export type RenderPipelineManager = import("../../device/pipeline/RenderPipelineManager.js").RenderPipelineManager;
 export type BindGroupManager = import("../binding/BindGroupManager.js").BindGroupManager;
+export type GPUSamplerManager = import("../GPUSamplerManager.js").GPUSamplerManager;
 export type TextureManager = import("../texture/TextureManager.js").TextureManager;
 export type VirtualTextureManager = import("../texture/virtual/VirtualTextureManager.js").VirtualTextureManager;
 export type ShadeMaterial = import("./ShadeMaterial.js").ShadeMaterial;
+export type ShadeMaterialTemplate = import("./template/ShadeMaterialTemplate.js").ShadeMaterialTemplate;
 import { GPUMaterialContext } from "./GPUMaterialContext.js";
 import { GPUSingleTypeTable } from "../buffer/table/single/GPUSingleTypeTable.js";
 //# sourceMappingURL=GPUMaterialManager.d.ts.map

package/src/shade/renderer/material/GPUMaterialManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUMaterialManager.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/material/GPUMaterialManager.js"],"names":[],"mappings":"AA4KA;IAmEI;;;;;;;OAOG;IACH,yCALW,cAAc,oBACd,qBAAqB,YACrB,gBAAgB,qBAChB,qBAAqB,EA0C/B;IA5GD;;;OAGG;IACH,UAFU,IAAI,aAAa,EAAE,kBAAkB,CAAC,CAE3B;IA2BrB;;;OAGG;IACH,yCAEC;IAID;;;OAGG;IACH,sBAEC;IA8JD;;;;;;;;OAQG;IACH;QAN+B,KAAK,EAAzB,UAAU;QACc,IAAI,EAA5B,cAAc;QACE,gBAAgB,EAAhC,MAAM;QACU,oBAAoB,EAApC,MAAM;QACJ;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAC,CAqNnF;IAED;;;;OAIG;IACH,iBAHW,aAAa,GACX,kBAAkB,CAqB9B;IAED;;;OAGG;IACH,YAFW,sBAAsB,QAIhC;;CAEJ;6BA/lBY,OAAO,2BAA2B,EAAE,cAAc;yBAIlD,OAAO,2DAA2D,EAAE,UAAU;qCAC9E,OAAO,wCAAwC,EAAE,sBAAsB;oCACvE,OAAO,gDAAgD,EAAE,qBAAqB;+BAC9E,OAAO,gCAAgC,EAAE,gBAAgB;6BACzD,OAAO,8BAA8B,EAAE,cAAc;oCACrD,OAAO,6CAA6C,EAAE,qBAAqB;4BAC3E,OAAO,oBAAoB,EAAE,aAAa;mCAjBhD,yBAAyB;mCAjBG,8CAA8C"}
+{"version":3,"file":"GPUMaterialManager.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/material/GPUMaterialManager.js"],"names":[],"mappings":"AAyNA;IAiFI;;;;;;;;OAQG;IACH,yCANW,cAAc,oBACd,qBAAqB,YACrB,gBAAgB,qBAChB,qBAAqB,aACrB,iBAAiB,EAmD3B;IApID;;;OAGG;IACH,UAFU,IAAI,aAAa,EAAE,kBAAkB,CAAC,CAE3B;IAsBrB;;;OAGG;IACH,yCAEC;IAID;;;OAGG;IACH,sBAEC;IAoLD;;;;;;;;OAQG;IACH;QAN+B,KAAK,EAAzB,UAAU;QACc,IAAI,EAA5B,cAAc;QACE,gBAAgB,EAAhC,MAAM;QACU,oBAAoB,EAApC,MAAM;QACJ;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAC,CAiMnF;IAED;;;;OAIG;IACH,iBAHW,aAAa,GACX,kBAAkB,CAqB9B;IAED;;;;;;;;;;;;OAYG;IACH,kBAHW,aAAa,GACX,OAAO,CAyBnB;IAED;;;;OAIG;IACH,gBAWC;IAED;;;;;;;;;OASG;IACH,kBAFW,qBAAqB,QAM/B;IAsBD;;;;;;OAMG;IACH,0BAHW,aAAa,EAAE,GACb,aAAa,EAAE,CAI3B;IAED;;;;;;OAMG;IACH,wBAHW,aAAa,EAAE,GACb,aAAa,EAAE,CAI3B;IAuED;;;OAGG;IACH,YAFW,sBAAsB,QAiChC;;CAEJ;6BA51BY,OAAO,2BAA2B,EAAE,cAAc;yBAIlD,OAAO,2DAA2D,EAAE,UAAU;qCAC9E,OAAO,wCAAwC,EAAE,sBAAsB;oCACvE,OAAO,gDAAgD,EAAE,qBAAqB;+BAC9E,OAAO,gCAAgC,EAAE,gBAAgB;gCACzD,OAAO,yBAAyB,EAAE,iBAAiB;6BACnD,OAAO,8BAA8B,EAAE,cAAc;oCACrD,OAAO,6CAA6C,EAAE,qBAAqB;4BAC3E,OAAO,oBAAoB,EAAE,aAAa;oCAC1C,OAAO,qCAAqC,EAAE,qBAAqB;mCApBzE,yBAAyB;mCAjBG,8CAA8C"}

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

@@ -27,7 +27,8 @@ import {
 } from "./GPUMaterialContext.js";
 import { MATERIAL_METADATA_STRUCT } from "./MATERIAL_METADATA_STRUCT.js";
 import { PIXEL_TEXTURE_ORM } from "./PIXEL_TEXTURE_ORM.js";
-import { standard_material_to_struct } from "./standard_material_to_struct.js";
+import { GPUMaterialServices, MaterialGPUDefaults } from "./template/GPUMaterialServices.js";
+import { material_template_of } from "./template/material_template_of.js";
 import { TransparencyMode } from "./TransparencyMode.js";
 
 /**
@@ -39,47 +40,91 @@ import { TransparencyMode } from "./TransparencyMode.js";
  * @typedef {import("../../device/ShadeGPUCommandContext.js").ShadeGPUCommandContext} ShadeGPUCommandContext
  * @typedef {import("../../device/pipeline/RenderPipelineManager.js").RenderPipelineManager} RenderPipelineManager
  * @typedef {import("../binding/BindGroupManager.js").BindGroupManager} BindGroupManager
+ * @typedef {import("../GPUSamplerManager.js").GPUSamplerManager} GPUSamplerManager
  * @typedef {import("../texture/TextureManager.js").TextureManager} TextureManager
  * @typedef {import("../texture/virtual/VirtualTextureManager.js").VirtualTextureManager} VirtualTextureManager
  * @typedef {import("./ShadeMaterial.js").ShadeMaterial} ShadeMaterial
+ * @typedef {import("./template/ShadeMaterialTemplate.js").ShadeMaterialTemplate} ShadeMaterialTemplate
  */
 
-class MaterialGPUDefaults {
+/**
+ * What the passes draw one scene's materials from, derived from the scene's drawn list and kept
+ * until that list is replaced — which is what the scene does when a material enters or leaves it.
+ */
+class DrawnMaterialLists {
     /**
-     * Wired when the graphics context carries a virtual texture system;
-     * consulted by VT material bind groups.
-     * @type {VirtualTextureManager|undefined}
+     * The drawn materials grouped by template — the list itself when it already is. The
+     * alpha-tested passes filter from this, before their draw commands are built, so command `i`
+     * still belongs to material `i` and pipeline switches are one per template.
+     *
+     * @type {ShadeMaterial[]}
      */
-    virtual_textures;
+    sorted;
 
     /**
-     * @type {GPUTextureContext}
+     * The drawn materials the transparent passes can draw, grouped by template — {@link sorted}
+     * itself when that is all of them.
+     *
+     * @type {ShadeMaterial[]}
      */
-    texture;
+    forward;
 
     /**
-     * @type {GPUTextureContext}
-     */
-    texture_pixel_white;
-    /**
-     * @type {GPUTextureContext}
+     * The G-buffer pass's contexts: the drawn materials that are not transparent, grouped by
+     * template.
+     *
+     * @type {GPUMaterialContext[]}
      */
-    texture_pixel_black;
+    gbuffer = [];
 
     /**
-     * @type {GPUTextureContext}
+     * The manager's list version {@link gbuffer} was built at.
+     *
+     * @type {number}
      */
-    texture_pixel_normal;
+    gbuffer_version = -1;
+}
 
-    /**
-     * @type {GPUTextureContext}
-     */
-    texture_orm;
+/**
+ * @param {ShadeMaterial} a
+ * @param {ShadeMaterial} b
+ * @returns {number}
+ */
+function compare_by_template(a, b) {
+    return material_template_of(a).ordinal - material_template_of(b).ordinal;
+}
 
-    /**
-     * @type {GPUSampler}
-     */
-    sampler
+/**
+ * @param {ShadeMaterial[]} drawn
+ * @returns {ShadeMaterial[]} `drawn` itself when it is already grouped by template
+ */
+function sort_by_template(drawn) {
+    const n = drawn.length;
+
+    for (let i = 1; i < n; i++) {
+        if (compare_by_template(drawn[i - 1], drawn[i]) > 0) {
+            // Array#sort is stable, so each template keeps the order the scene drew in
+            return drawn.slice().sort(compare_by_template);
+        }
+    }
+
+    return drawn;
+}
+
+/**
+ * @param {ShadeMaterial[]} drawn
+ * @returns {ShadeMaterial[]} `drawn` itself when every material in it can be drawn forward
+ */
+function filter_forward(drawn) {
+    const n = drawn.length;
+
+    for (let i = 0; i < n; i++) {
+        if (!material_template_of(drawn[i]).forward) {
+            return drawn.filter(material => material_template_of(material).forward);
+        }
+    }
+
+    return drawn;
 }
 
 const MATERIAL_BUFFER_BIND_GROUP_0_LAYOUT_DESCRIPTOR = BindGroupLayoutDescriptor.fromJSON({
@@ -183,11 +228,6 @@ export class GPUMaterialManager {
      */
     contexts = new Map();
 
-    /**
-     * @type {TextureManager}
-     */
-    #textures;
-
     /**
      * @type {RenderPipelineManager}
      */
@@ -227,15 +267,34 @@ export class GPUMaterialManager {
     }
 
     /**
+     * What every template's hooks are handed.
+     *
+     * @type {GPUMaterialServices}
+     */
+    #services;
+
+    /**
+     * Contexts of templates that update every frame — terrain's.
      *
-     * @type {MaterialGPUDefaults}
+     * @type {GPUMaterialContext[]}
      */
-    #material_defaults;
+    #dynamic_contexts = [];
 
     /**
-     * @type {VirtualTextureManager}
+     * Moves when something the G-buffer pass's list depends on changes other than the drawn set
+     * itself: a context created or released, a material that changed its transparency mode.
+     *
+     * @type {number}
      */
-    #virtual_textures;
+    #list_version = 0;
+
+    /**
+     * Per drawn list — the scene replaces the array when its set changes, so the array is the key.
+     * Weak, because a list the scene let go of is garbage.
+     *
+     * @type {WeakMap<ShadeMaterial[], DrawnMaterialLists>}
+     */
+    #drawn_lists = new WeakMap();
 
     /**
      *
@@ -244,13 +303,12 @@ export class GPUMaterialManager {
      * @param {RenderPipelineManager} render_pipelines
      * @param {BindGroupManager} bindings
      * @param {VirtualTextureManager} [virtual_textures]
+     * @param {GPUSamplerManager} [samplers] required by templates that bind shared samplers — terrain's
      */
-    constructor(device, textures, render_pipelines, bindings, virtual_textures) {
+    constructor(device, textures, render_pipelines, bindings, virtual_textures, samplers) {
         this.#device = device;
-        this.#textures = textures;
         this.#render_pipelines = render_pipelines;
         this.#bindings = bindings;
-        this.#virtual_textures = virtual_textures;
 
         this.#metadata_table = new GPUSingleTypeTable({
             device,
@@ -260,22 +318,33 @@ export class GPUMaterialManager {
         this.#material_buffer_pipeline = render_pipelines.obtain(material_buffer_pipeline_descriptor);
 
         // initialize defaults
-        this.#material_defaults = new MaterialGPUDefaults();
-        this.#material_defaults.virtual_textures = virtual_textures;
-        this.#material_defaults.texture = textures.contextFromDescriptor(TextureDescriptor.from({
+        const defaults = new MaterialGPUDefaults();
+
+        defaults.texture = textures.contextFromDescriptor(TextureDescriptor.from({
             format: 'rgba8unorm',
             size: [1, 1],
             usage: GPUTextureUsage.TEXTURE_BINDING
         }));
-        this.#material_defaults.texture_pixel_white = textures.obtain(WHITE_PIXEL_TEXTURE);
-        this.#material_defaults.texture_pixel_black = textures.obtain(BLACK_PIXEL_TEXTURE);
-        this.#material_defaults.texture_pixel_normal = textures.obtain(PIXEL_TEXTURE_NORMAL);
-        this.#material_defaults.texture_orm = textures.obtain(PIXEL_TEXTURE_ORM);
+        defaults.texture_pixel_white = textures.obtain(WHITE_PIXEL_TEXTURE);
+        defaults.texture_pixel_black = textures.obtain(BLACK_PIXEL_TEXTURE);
+        defaults.texture_pixel_normal = textures.obtain(PIXEL_TEXTURE_NORMAL);
+        defaults.texture_orm = textures.obtain(PIXEL_TEXTURE_ORM);
 
-        this.#material_defaults.sampler = device.createSampler(SamplerDescriptor.from({}));
+        defaults.sampler = device.createSampler(SamplerDescriptor.from({}));
 
         // freeze defaults
-        Object.freeze(this.#material_defaults);
+        Object.freeze(defaults);
+
+        const services = new GPUMaterialServices();
+
+        services.device = device;
+        services.textures = textures;
+        services.samplers = samplers;
+        services.render_pipelines = render_pipelines;
+        services.virtual_textures = virtual_textures;
+        services.defaults = defaults;
+
+        this.#services = Object.freeze(services);
 
         /**
          * DEBUG — `globalThis` rather than `window` so constructing a manager outside a browser is
@@ -298,29 +367,22 @@ export class GPUMaterialManager {
         assert.notNull(material, 'material');
         assert.equal(material.isShadeMaterial, true, 'material.isShadeMaterial !== true');
 
-        // console.log('GPUMaterialManager#create');
-
-        if (material.vt_stack != null) {
-            assert.defined(this.#virtual_textures, 'material uses a vt_stack but no VirtualTextureManager is wired');
-            // alpha-tested rasterization and OIT sample the regular albedo
-            // texture during the visibility/transparency passes — VT albedo
-            // isn't resident-guaranteed there, so v1 is opaque-only
-            assert.equal(material.transparency_mode, TransparencyMode.Opaque, 'virtual textures require an opaque material (v1)');
-
-            // must precede any standard_material_to_struct conversion — the
-            // struct captures the stack id assigned here
-            this.#virtual_textures.register_stack(material.vt_stack);
-        }
+        const template = material_template_of(material);
 
         const ctx = new GPUMaterialContext(
             this.#device,
-            material
+            material,
+            template
         );
 
-        ctx.build(this.#textures, this.#render_pipelines, this.#virtual_textures);
+        ctx.build(this.#services);
 
         // build bindings
-        ctx.obtainMaterialBindGroup(this.#material_defaults);
+        ctx.obtainMaterialBindGroup();
+
+        if (template.dynamic) {
+            this.#dynamic_contexts.push(ctx);
+        }
 
         return ctx;
 
@@ -496,33 +558,14 @@ export class GPUMaterialManager {
             pass.setBindGroup(1, bind_1)
             pass.setBindGroup(2, bind_2)
 
-            /**
-             *
-             * @type {GPUMaterialContext[]}
-             */
-            const materials = [];
-            const scene_materials = view.scene.drawn_materials;
-            for (const m of scene_materials) {
-
-                if (m.transparency_mode === TransparencyMode.Transparent) {
-                    // skip transparent
-                    continue;
-                }
-
-                const material_ctx = this.contexts.get(m);
-
-                if (material_ctx === undefined) {
-                    continue;
-                }
-
-                materials.push(material_ctx);
-            }
-
+            const materials = this.#gbuffer_contexts(view.scene.drawn_materials);
+            const material_count = materials.length;
 
             let cached_last_pipeline = null;
 
             // render materials
-            for (const material_ctx of materials) {
+            for (let i = 0; i < material_count; i++) {
+                const material_ctx = materials[i];
 
                 const pipeline = material_ctx.pipeline;
 
@@ -535,11 +578,10 @@ export class GPUMaterialManager {
 
                 }
 
-                const material_bind_group = material_ctx.obtainMaterialBindGroup(this.#material_defaults);
+                pass.setBindGroup(0, material_ctx.material_binding);
 
-                pass.setBindGroup(0, material_bind_group);
-
-                pass.draw(3);
+                // the id rides in the instance index — the vertex stage binds nothing
+                pass.draw(3, 1, 0, material_ctx.material_id);
             }
 
             pass.end();
@@ -622,20 +664,232 @@ export class GPUMaterialManager {
 
             contexts.set(material, ctx);
 
-            this.#metadata_table.set(material.id, standard_material_to_struct(material));
+            this.#stage_metadata(ctx);
 
-            this.#version++;
+            this.#list_version++;
         }
 
         return ctx;
     }
 
+    /**
+     * Let a material's GPU side go: its uniform, its bind group, and whatever its template owns —
+     * terrain's textures. Nothing else releases a context, so a template that owns resources relies
+     * on its owner calling this when the material is done with.
+     *
+     * Release a material once nothing draws it — the terrain system drops its tiles first. One that
+     * is still drawn gets a new context from whatever next obtains it — the scene rows when its mesh
+     * row is rewritten, an alpha-tested or transparent pass — and the G-buffer pass, which does not
+     * create contexts, leaves it out until then.
+     *
+     * @param {ShadeMaterial} material
+     * @returns {boolean} whether there was a context to release
+     */
+    release(material) {
+        const ctx = this.contexts.get(material);
+
+        if (ctx === undefined) {
+            return false;
+        }
+
+        this.contexts.delete(material);
+
+        if (ctx.template.dynamic) {
+            const dynamic = this.#dynamic_contexts;
+
+            dynamic.splice(dynamic.indexOf(ctx), 1);
+        }
+
+        ctx.destroy();
+
+        this.#metadata_table.remove(material.id);
+
+        this.#version++;
+        this.#list_version++;
+
+        return true;
+    }
+
+    /**
+     * Give back every context's GPU side, the way {@link release} does for one — for the graphics
+     * context going away. A template's own resources, terrain's textures above all, are not owned
+     * by anything else that would free them.
+     */
+    destroy() {
+        for (const material_ctx of this.contexts.values()) {
+            material_ctx.destroy();
+        }
+
+        this.contexts.clear();
+
+        this.#dynamic_contexts.length = 0;
+
+        this.#list_version++;
+        this.#version++;
+    }
+
+    /**
+     * Build a template's G-buffer pipeline now, rather than on the frame its first material is
+     * drawn. Pipeline creation is synchronous, so a template that first appears mid-game compiles
+     * on that frame; this lets its owner pay for it at a moment of its choosing — a level load.
+     *
+     * The alpha-tested pipelines of a template that can cut out are built on the first alpha-tested
+     * pass that meets one of its materials, as they always have been.
+     *
+     * @param {ShadeMaterialTemplate} template
+     */
+    prewarm(template) {
+        assert.equal(template.isShadeMaterialTemplate, true, 'template.isShadeMaterialTemplate !== true');
+
+        this.#render_pipelines.obtain(template.gbuffer_pipeline_descriptor(this.#services));
+    }
+
+    /**
+     * @param {ShadeMaterial[]} drawn
+     * @returns {DrawnMaterialLists}
+     */
+    #lists_of(drawn) {
+        let lists = this.#drawn_lists.get(drawn);
+
+        if (lists === undefined) {
+            lists = new DrawnMaterialLists();
+
+            lists.sorted = sort_by_template(drawn);
+            // from the grouped list, so the transparent passes switch pipeline once per template too
+            lists.forward = filter_forward(lists.sorted);
+
+            this.#drawn_lists.set(drawn, lists);
+        }
+
+        return lists;
+    }
+
+    /**
+     * A scene's drawn materials grouped by template — the alpha-tested passes filter from this.
+     * Derived once per drawn set; the same array as `drawn` when it is already grouped.
+     *
+     * @param {ShadeMaterial[]} drawn a scene's {@link GPUSceneContext#drawn_materials}
+     * @returns {ShadeMaterial[]}
+     */
+    sorted_by_template(drawn) {
+        return this.#lists_of(drawn).sorted;
+    }
+
+    /**
+     * A scene's drawn materials that the transparent passes can draw, grouped by template. Derived
+     * once per drawn set; the same array as `drawn` when that is all of them and they are grouped.
+     *
+     * @param {ShadeMaterial[]} drawn a scene's {@link GPUSceneContext#drawn_materials}
+     * @returns {ShadeMaterial[]}
+     */
+    forward_drawable(drawn) {
+        return this.#lists_of(drawn).forward;
+    }
+
+    /**
+     * @param {ShadeMaterial[]} drawn
+     * @returns {GPUMaterialContext[]}
+     */
+    #gbuffer_contexts(drawn) {
+        const lists = this.#lists_of(drawn);
+
+        if (lists.gbuffer_version !== this.#list_version) {
+            const sorted = lists.sorted;
+            const contexts = lists.gbuffer;
+
+            contexts.length = 0;
+
+            for (let i = 0; i < sorted.length; i++) {
+                const material = sorted[i];
+
+                if (material.transparency_mode === TransparencyMode.Transparent) {
+                    // skip transparent
+                    continue;
+                }
+
+                const material_ctx = this.contexts.get(material);
+
+                if (material_ctx === undefined) {
+                    continue;
+                }
+
+                contexts.push(material_ctx);
+            }
+
+            lists.gbuffer_version = this.#list_version;
+        }
+
+        return lists.gbuffer;
+    }
+
+    /**
+     * Write a material's metadata row and remember the version it was written at.
+     *
+     * @param {GPUMaterialContext} ctx
+     * @returns {Object} the row
+     */
+    #stage_metadata(ctx) {
+        const material = ctx.source;
+
+        const row = ctx.template.metadata_value(material);
+
+        this.#metadata_table.set(material.id, row);
+
+        if (ctx.staged_transparency_mode !== material.transparency_mode) {
+            // whether the G-buffer pass draws it
+            ctx.staged_transparency_mode = material.transparency_mode;
+
+            this.#list_version++;
+
+            if (material.transparency_mode === TransparencyMode.Transparent && !ctx.template.forward) {
+                // the transparent passes are standard-only for now, and skip it — said when it is
+                // made transparent, whether that is at creation or later, through an editor
+                console.warn(`Material '${material.name}' is transparent, but its template '${ctx.template.name}' cannot be drawn forward; it will not be drawn until it is opaque or alpha-tested`);
+            }
+        }
+
+        ctx.staged_version = material.version;
+
+        this.#version++;
+
+        return row;
+    }
+
     /**
      *
      * @param {ShadeGPUCommandContext} ctx
      */
     update(ctx) {
+        // Restage what has changed. The row used to be written inside the create branch of
+        // `obtain` and never again — a repo-wide grep found no other writer — so every field of
+        // MATERIAL_METADATA_STRUCT was frozen at first use: setting emissive_factor on an
+        // already-drawn material changed nothing on screen, and setting draw_side left the GPU
+        // struct on the old side while every CPU reader reported the new one, which is exactly how
+        // "the declared side is not honoured" bites now that winding is per-instance. The uniform
+        // the G-buffer pass reads is rewritten with the row.
+        const queue = this.#device.queue;
+
+        for (const material_ctx of this.contexts.values()) {
+            if (material_ctx.staged_version !== material_ctx.source.version) {
+                const row = this.#stage_metadata(material_ctx);
+
+                material_ctx.write_uniform(queue, row);
+            }
+        }
+
+        const dynamic = this.#dynamic_contexts;
+        const dynamic_count = dynamic.length;
+
+        for (let i = 0; i < dynamic_count; i++) {
+            const material_ctx = dynamic[i];
+
+            if (material_ctx.template.update(material_ctx, this.#services)) {
+                // a resource the group names was replaced
+                material_ctx.rebuild_bind_group();
+            }
+        }
+
         this.#metadata_table.update(ctx);
     }
 
-}
+}

package/src/shade/renderer/material/ShadeMaterial.d.ts

@@ -17,6 +17,27 @@ export class ShadeMaterial {
      */
     draw_side: ShadeDrawSide | number;
     get id(): number;
+    /**
+     * Bumped whenever something that reaches the GPU changes. {@link GPUMaterialManager} stages a
+     * material's metadata row once and then only restages the rows whose version has moved, so a
+     * field written after the first draw reaches the GPU only if this says so.
+     *
+     * A material is a bag of public fields with no interception, so this is the author's to set —
+     * the same contract {@link ParticleEmitter} has. Nothing was watching at all before: the
+     * metadata row was written inside the create branch of `obtain` and never again, so
+     * `albedo_color`, `roughness_factor`, `metallic_factor`, `emissive_factor`,
+     * `ambient_factors`, `transmission_factor`, `ior_factor`, `transparency_mode` and
+     * `draw_side` were all frozen at first use while every CPU reader saw the new value.
+     *
+     * @returns {number}
+     */
+    get version(): number;
+    /**
+     * Mark the material changed, so its GPU row is restaged.
+     *
+     * @param {boolean} value
+     */
+    set needsUpdate(value: boolean);
     /**
      * Copies all fields from another material. The {@link id} is not copied —
      * it stays unique to this instance.

package/src/shade/renderer/material/ShadeMaterial.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ShadeMaterial.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/material/ShadeMaterial.js"],"names":[],"mappings":"AAUA;IAII,aAAU;IAEV;;;OAGG;IACH,mBAFU,MAAM,CAE4B;IAE5C;;;OAGG;IACH,WAFU,aAAa,GAAC,MAAM,CAEM;IAGpC;;;;OAIG;IACH,WAFU,aAAa,GAAC,MAAM,CAEE;IAEhC,iBAEC;IAED;;;;;OAKG;IACH,YAFW,aAAa,QAOvB;IAED;;;OAGG;IACH,SAFa,aAAa,CAQzB;IAED;;;;OAIG;IACH,cAHW,aAAa,GACX,OAAO,CAOnB;IAED,eAGC;IAED;;OAEG;IACH,oEAEC;IAGL;;;OAGG;IACH,0BAFU,OAAO,CAEsB;;CANtC;2BAnFY,OAAO,4BAA4B,EAAE,YAAY;8BALhC,oBAAoB;8BACpB,oBAAoB"}
+{"version":3,"file":"ShadeMaterial.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/material/ShadeMaterial.js"],"names":[],"mappings":"AAUA;IAII,aAAU;IAEV;;;OAGG;IACH,mBAFU,MAAM,CAE4B;IAE5C;;;OAGG;IACH,WAFU,aAAa,GAAC,MAAM,CAEM;IAGpC;;;;OAIG;IACH,WAFU,aAAa,GAAC,MAAM,CAEE;IAEhC,iBAEC;IAID;;;;;;;;;;;;;OAaG;IACH,sBAEC;IAED;;;;OAIG;IACH,gCAIC;IAED;;;;;OAKG;IACH,YAFW,aAAa,QAOvB;IAED;;;OAGG;IACH,SAFa,aAAa,CAQzB;IAED;;;;OAIG;IACH,cAHW,aAAa,GACX,OAAO,CAOnB;IAED,eAGC;IAED;;OAEG;IACH,oEAEC;IAGL;;;OAGG;IACH,0BAFU,OAAO,CAEsB;;CANtC;2BAlHY,OAAO,4BAA4B,EAAE,YAAY;8BALhC,oBAAoB;8BACpB,oBAAoB"}