@woosh/meep-engine 3.30.0 → 3.31.0

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

@@ -38,6 +38,37 @@ export class ShadeMaterial {
         return this.#id;
     }
 
+    #version = 0;
+
+    /**
+     * 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() {
+        return this.#version;
+    }
+
+    /**
+     * Mark the material changed, so its GPU row is restaged.
+     *
+     * @param {boolean} value
+     */
+    set needsUpdate(value) {
+        if (value) {
+            this.#version++;
+        }
+    }
+
     /**
      * Copies all fields from another material. The {@link id} is not copied —
      * it stays unique to this instance.

package/src/shade/renderer/material/resident/GPUResidentMaterialContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUResidentMaterialContext.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/material/resident/GPUResidentMaterialContext.js"],"names":[],"mappings":"AA+DA,sDAAuD;AAEvD,wDAAyD;AAEzD,+DAAiJ;AAEjJ,+DAA+I;AAE/I;IA8GI;;;;OAIG;IACH,yCAFW,eAAe,EAsCzB;IA3HD;;;OAGG;IACH,6BAEC;IAQD;;;OAGG;IACH,kCAEC;IAQD;;;OAGG;IACH,yCAEC;IAED;;;OAGG;IACH,kCAIC;IA0GD;;;;OAIG;IACH,0BAHW,aAAa,GACX,YAAY,CAIxB;IAgBD;;;;OAIG;IACH,wBAHW,YAAY,GACV,WAAW,CAIvB;IAGD,uBA+HC;IAED,wBA2EC;IAED;;;;OAIG;IACH,sCAFW,eAAe,QAUzB;IAoCD,eASC;IAGD,gBAGC;;CACJ;8BAthBY,OAAO,0BAA0B,EAAE,eAAe;8BAClD,OAAO,gCAAgC,EAAE,eAAe;2BACxD,OAAO,+BAA+B,EAAE,YAAY;4BACpD,OAAO,qBAAqB,EAAE,aAAa;oCAC3C,OAAO,6BAA6B,EAAE,qBAAqB;kCAZtC,oCAAoC;AAOtE;;;;;;GAMG;AAEH;IACI,WAAM;IAEN;;OAEG;IACH,QAFU,qBAAqB,CAExB;IAEP;;OAEG;IACH,gBAFU,WAAW,CAEP;IAEd;;OAEG;IACH,aAFU,WAAW,CAEV;IAEX;;OAEG;IACH,gBAFU,WAAW,CAEP;IACd;;OAEG;IACH,kBAFU,WAAW,CAEL;CACnB;AAED;IACI,WAAO;IAEP;;OAEG;IACH,QAFU,YAAY,CAEf;CACV"}
+{"version":3,"file":"GPUResidentMaterialContext.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/material/resident/GPUResidentMaterialContext.js"],"names":[],"mappings":"AAgFA,sDAAuD;AAEvD,wDAAyD;AAEzD,+DAAiJ;AAEjJ,+DAA+I;AAE/I;IA8GI;;;;OAIG;IACH,yCAFW,eAAe,EAsCzB;IA3HD;;;OAGG;IACH,6BAEC;IAQD;;;OAGG;IACH,kCAEC;IAQD;;;OAGG;IACH,yCAEC;IAED;;;OAGG;IACH,kCAIC;IA0GD;;;;OAIG;IACH,0BAHW,aAAa,GACX,YAAY,CAIxB;IAgBD;;;;OAIG;IACH,wBAHW,YAAY,GACV,WAAW,CAIvB;IAGD,uBA+HC;IAED,wBA6EC;IAED;;;;OAIG;IACH,sCAFW,eAAe,QAUzB;IAoCD,eASC;IAGD,gBAGC;;CACJ;8BAziBY,OAAO,0BAA0B,EAAE,eAAe;8BAClD,OAAO,gCAAgC,EAAE,eAAe;2BACxD,OAAO,+BAA+B,EAAE,YAAY;4BACpD,OAAO,qBAAqB,EAAE,aAAa;oCAC3C,OAAO,6BAA6B,EAAE,qBAAqB;kCAZtC,oCAAoC;AAOtE;;;;;;GAMG;AAEH;IACI,WAAM;IAEN;;OAEG;IACH,QAFU,qBAAqB,CAExB;IAEP;;OAEG;IACH,gBAFU,WAAW,CAEP;IAEd;;OAEG;IACH,aAFU,WAAW,CAEV;IAEX;;OAEG;IACH,gBAFU,WAAW,CAEP;IACd;;OAEG;IACH,kBAFU,WAAW,CAEL;CACnB;AAED;IACI,WAAO;IAEP;;OAEG;IACH,QAFU,YAAY,CAEf;CACV"}

package/src/shade/renderer/material/resident/GPUResidentMaterialContext.js

@@ -61,6 +61,23 @@ class TextureInfo {
     source;
 }
 
+/**
+ * What a material that is not standard contributes to the ray passes: white, opaque, fully rough,
+ * not metallic, not transmissive, not emissive — through the default textures its missing slots
+ * already resolve to. Without it the fields the row is written from are absent and skipped into a
+ * zeroed buffer, and an opacity of 0 is a surface the rays pass through: a terrain would stop
+ * casting ray-traced shadows, and a bake would see it black. The same values a flat standard
+ * material gives, which is what the terrain drew with before it had a template of its own.
+ */
+const NEUTRAL_SURFACE = Object.freeze({
+    diffuse_color: Object.freeze([1, 1, 1, 1]),
+    roughness_factor: 1,
+    metallic_factor: 0,
+    transmission_factor: 0,
+    ior_factor: 1.5,
+    emissive_factor: Object.freeze([0, 0, 0]),
+});
+
 export const RESIDENT_MATERIAL_TEXTURE_RESOLUTION = 64;
 
 export const RESIDENT_MATERIAL_TEXTURE_LAYER_SIZE = 2048;
@@ -458,6 +475,8 @@ export class GPUResidentMaterialContext {
                 continue;
             }
 
+            const surface = info.source.isStandardShadeMaterial === true ? info.source : NEUTRAL_SURFACE;
+
             write_gpu_typed_buffer(
                 {
                     texture_albedo: info.texture_albedo.id,
@@ -468,12 +487,12 @@ export class GPUResidentMaterialContext {
                     sampler_orm: sampler_descriptor_pack(info.texture_orm.source),
                     sampler_normal: sampler_descriptor_pack(info.texture_normal.source),
                     sampler_emissive: sampler_descriptor_pack(info.texture_emissive.source),
-                    color_albedo: info.source.diffuse_color,
-                    roughness_factor: info.source.roughness_factor,
-                    metallic_factor: info.source.metallic_factor,
-                    transmission_factor: info.source.transmission_factor,
-                    ior_factor: info.source.ior_factor,
-                    emissive_factor: info.source.emissive_factor,
+                    color_albedo: surface.diffuse_color,
+                    roughness_factor: surface.roughness_factor,
+                    metallic_factor: surface.metallic_factor,
+                    transmission_factor: surface.transmission_factor,
+                    ior_factor: surface.ior_factor,
+                    emissive_factor: surface.emissive_factor,
                 },
                 INDIRECT_MATERIAL_STRUCT,
                 mapped_buffer_materials,

package/src/shade/renderer/material/standard/SHADING_MATERIAL_RESOURCE_GROUP.d.ts

@@ -1,3 +1,13 @@
+/**
+ * Group 0 of the standard material template: its uniform and its four textures.
+ *
+ * Fragment-visible, as every template's group 0 is: the G-buffer pass's vertex stage binds nothing
+ * and the alpha-tested vertex stages read the side a material draws from the metadata table, so one
+ * bind group per material serves the G-buffer pass and both alpha-tested passes. The transparent
+ * passes build their own layout from this group with an explicit vertex-and-fragment visibility.
+ *
+ * @type {ShaderResourceGroupDescriptor}
+ */
 export const SHADING_MATERIAL_RESOURCE_GROUP: ShaderResourceGroupDescriptor;
 import { ShaderResourceGroupDescriptor } from "../../shader/resource/ShaderResourceGroupDescriptor.js";
 //# sourceMappingURL=SHADING_MATERIAL_RESOURCE_GROUP.d.ts.map

package/src/shade/renderer/material/standard/SHADING_MATERIAL_RESOURCE_GROUP.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SHADING_MATERIAL_RESOURCE_GROUP.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/material/standard/SHADING_MATERIAL_RESOURCE_GROUP.js"],"names":[],"mappings":"AAIA,4EAAmF;8CAJrC,wDAAwD"}
+{"version":3,"file":"SHADING_MATERIAL_RESOURCE_GROUP.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/material/standard/SHADING_MATERIAL_RESOURCE_GROUP.js"],"names":[],"mappings":"AAIA;;;;;;;;;GASG;AACH,8CAFU,6BAA6B,CAE4C;8CAbrC,wDAAwD"}

package/src/shade/renderer/material/standard/SHADING_MATERIAL_RESOURCE_GROUP.js

@@ -1,7 +1,17 @@
+import { GPUShaderStage } from "../../../descriptor/GPUShaderStage.js";
 import { ShaderResourceGroupDescriptor } from "../../shader/resource/ShaderResourceGroupDescriptor.js";
 import { MATERIAL_METADATA_STRUCT } from "../MATERIAL_METADATA_STRUCT.js";
 
-
+/**
+ * Group 0 of the standard material template: its uniform and its four textures.
+ *
+ * Fragment-visible, as every template's group 0 is: the G-buffer pass's vertex stage binds nothing
+ * and the alpha-tested vertex stages read the side a material draws from the metadata table, so one
+ * bind group per material serves the G-buffer pass and both alpha-tested passes. The transparent
+ * passes build their own layout from this group with an explicit vertex-and-fragment visibility.
+ *
+ * @type {ShaderResourceGroupDescriptor}
+ */
 export const SHADING_MATERIAL_RESOURCE_GROUP = new ShaderResourceGroupDescriptor();
 
 SHADING_MATERIAL_RESOURCE_GROUP.label = "Material";
@@ -14,4 +24,6 @@ SHADING_MATERIAL_RESOURCE_GROUP.addUniform("material_info", MATERIAL_METADATA_ST
     .addTexture("texture_orm", "float")
     .addSampler("texture_orm_sampler")
     .addTexture("texture_emissive", "float")
-    .addSampler("texture_emissive_sampler")
+    .addSampler("texture_emissive_sampler")
+
+SHADING_MATERIAL_RESOURCE_GROUP.addVisibility(GPUShaderStage.FRAGMENT);

package/src/shade/renderer/material/standard/STANDARD_MATERIAL_TEMPLATE.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @type {ShadeMaterialTemplate}
+ */
+export const STANDARD_MATERIAL_TEMPLATE: ShadeMaterialTemplate;
+export type RenderPipelineDescriptor = import("../../../descriptor/pipeline/render/RenderPipelineDescriptor.js").RenderPipelineDescriptor;
+export type GPUTextureContext = import("../../texture/GPUTextureContext.js").GPUTextureContext;
+export type ShadeTexture = import("../../texture/ShadeTexture.js").ShadeTexture;
+export type GPUMaterialContext = import("../GPUMaterialContext.js").GPUMaterialContext;
+export type StandardShadeMaterial = import("../StandardShadeMaterial.js").StandardShadeMaterial;
+export type GPUMaterialServices = import("../template/GPUMaterialServices.js").GPUMaterialServices;
+import { ShadeMaterialTemplate } from "../template/ShadeMaterialTemplate.js";
+//# sourceMappingURL=STANDARD_MATERIAL_TEMPLATE.d.ts.map

package/src/shade/renderer/material/standard/STANDARD_MATERIAL_TEMPLATE.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"STANDARD_MATERIAL_TEMPLATE.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/material/standard/STANDARD_MATERIAL_TEMPLATE.js"],"names":[],"mappings":"AA2JA;;GAEG;AACH,yCAFU,qBAAqB,CAS5B;uCAzJU,OAAO,iEAAiE,EAAE,wBAAwB;gCAClG,OAAO,oCAAoC,EAAE,iBAAiB;2BAC9D,OAAO,+BAA+B,EAAE,YAAY;iCACpD,OAAO,0BAA0B,EAAE,kBAAkB;oCACrD,OAAO,6BAA6B,EAAE,qBAAqB;kCAC3D,OAAO,oCAAoC,EAAE,mBAAmB;sCAdvC,sCAAsC"}

package/src/shade/renderer/material/standard/STANDARD_MATERIAL_TEMPLATE.js

@@ -0,0 +1,166 @@
+import { sampler_descriptor_from_shade_texture } from "../../texture/sampler_descriptor_from_shade_texture.js";
+import { MATERIAL_METADATA_STRUCT } from "../MATERIAL_METADATA_STRUCT.js";
+import { standard_material_to_struct } from "../standard_material_to_struct.js";
+import { ShadeMaterialTemplate } from "../template/ShadeMaterialTemplate.js";
+import {
+    chunk_standard_material_opacity,
+    chunk_standard_material_surface
+} from "./chunk_standard_material_surface.js";
+import { gbuffer_pipeline_descriptor_for_shader, gbuffer_shader } from "./fragment_gbuffer.js";
+import { SHADING_MATERIAL_RESOURCE_GROUP } from "./SHADING_MATERIAL_RESOURCE_GROUP.js";
+
+/**
+ * @typedef {import("../../../descriptor/pipeline/render/RenderPipelineDescriptor.js").RenderPipelineDescriptor} RenderPipelineDescriptor
+ * @typedef {import("../../texture/GPUTextureContext.js").GPUTextureContext} GPUTextureContext
+ * @typedef {import("../../texture/ShadeTexture.js").ShadeTexture} ShadeTexture
+ * @typedef {import("../GPUMaterialContext.js").GPUMaterialContext} GPUMaterialContext
+ * @typedef {import("../StandardShadeMaterial.js").StandardShadeMaterial} StandardShadeMaterial
+ * @typedef {import("../template/GPUMaterialServices.js").GPUMaterialServices} GPUMaterialServices
+ */
+
+/**
+ * The template every {@link StandardShadeMaterial} without a virtual-texture stack draws with: four
+ * per-material textures and the {@link MATERIAL_METADATA_STRUCT} uniform. The only template the
+ * transparent passes can draw, with the same bind group the G-buffer pass binds.
+ */
+class StandardMaterialTemplate extends ShadeMaterialTemplate {
+    /**
+     * @type {RenderPipelineDescriptor|null}
+     */
+    #gbuffer_pipeline = null;
+
+    /**
+     * Built around {@link gbuffer_shader}, so the standard fragment shader is assembled once.
+     *
+     * @param {GPUMaterialServices} services
+     * @returns {RenderPipelineDescriptor}
+     */
+    gbuffer_pipeline_descriptor(services) {
+        if (this.#gbuffer_pipeline === null) {
+            this.#gbuffer_pipeline = gbuffer_pipeline_descriptor_for_shader(
+                "Standard material / Viz-Buffer to G-Buffer laydown",
+                gbuffer_shader
+            );
+        }
+
+        return this.#gbuffer_pipeline;
+    }
+
+    /**
+     * @param {GPUMaterialContext} ctx
+     * @param {GPUMaterialServices} services
+     */
+    build(ctx, services) {
+        /**
+         * @type {StandardShadeMaterial}
+         */
+        const material = ctx.source;
+
+        const material_textures = [
+            material.texture_albedo,
+            material.texture_normal,
+            material.texture_orm,
+            material.texture_emissive,
+        ];
+
+        for (let i = 0; i < material_textures.length; i++) {
+            const texture = material_textures[i];
+
+            if (texture === undefined) {
+                continue;
+            }
+
+            ctx.textures.set(texture, services.textures.obtain(texture));
+        }
+    }
+
+    /**
+     * The uniform is the metadata row.
+     *
+     * @param {StandardShadeMaterial} material
+     * @param {Object} [metadata]
+     * @returns {Object}
+     */
+    uniform_value(material, metadata) {
+        return metadata ?? standard_material_to_struct(material);
+    }
+
+    /**
+     * @param {StandardShadeMaterial} material
+     * @returns {Object}
+     */
+    metadata_value(material) {
+        return standard_material_to_struct(material);
+    }
+
+    /**
+     * @param {GPUMaterialContext} ctx
+     * @param {GPUBindGroupLayout} layout
+     * @param {GPUMaterialServices} services
+     * @returns {GPUBindGroup}
+     */
+    create_bind_group(ctx, layout, services) {
+        const device = services.device;
+        const defaults = services.defaults;
+        const textures = ctx.textures;
+
+        /**
+         * @type {StandardShadeMaterial}
+         */
+        const material = ctx.source;
+
+        /**
+         * @param {ShadeTexture} [source]
+         * @param {GPUTextureContext} fallback
+         * @returns {{texture:GPUTextureContext, sampler:GPUSampler}}
+         */
+        function sampled(source, fallback) {
+            if (source === undefined) {
+                return { texture: fallback, sampler: defaults.sampler };
+            }
+
+            return {
+                texture: textures.get(source),
+                sampler: device.createSampler(sampler_descriptor_from_shade_texture(source))
+            };
+        }
+
+        const texture_diffuse = sampled(material.texture_albedo, defaults.texture_pixel_white);
+        const texture_normal = sampled(material.texture_normal, defaults.texture_pixel_normal);
+        const texture_orm = sampled(material.texture_orm, defaults.texture_orm);
+        const texture_emissive = sampled(material.texture_emissive, defaults.texture_pixel_white);
+
+        const binding_data = {
+            material_info: { buffer: ctx.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
+        };
+
+        return device.createBindGroup({
+            layout,
+            entries: SHADING_MATERIAL_RESOURCE_GROUP.generateGPUBindGroupEntryArray(binding_data)
+        });
+    }
+}
+
+/**
+ * @type {ShadeMaterialTemplate}
+ */
+export const STANDARD_MATERIAL_TEMPLATE = new StandardMaterialTemplate({
+    name: "Standard",
+    resources: SHADING_MATERIAL_RESOURCE_GROUP,
+    uniform_type: MATERIAL_METADATA_STRUCT,
+    surface: chunk_standard_material_surface,
+    opacity: chunk_standard_material_opacity,
+    forward: true,
+});

package/src/shade/renderer/material/standard/VT_MATERIAL_TEMPLATE.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @type {ShadeMaterialTemplate}
+ */
+export const VT_MATERIAL_TEMPLATE: ShadeMaterialTemplate;
+export type RenderPipelineDescriptor = import("../../../descriptor/pipeline/render/RenderPipelineDescriptor.js").RenderPipelineDescriptor;
+export type GPUMaterialContext = import("../GPUMaterialContext.js").GPUMaterialContext;
+export type StandardShadeMaterial = import("../StandardShadeMaterial.js").StandardShadeMaterial;
+export type GPUMaterialServices = import("../template/GPUMaterialServices.js").GPUMaterialServices;
+import { ShadeMaterialTemplate } from "../template/ShadeMaterialTemplate.js";
+//# sourceMappingURL=VT_MATERIAL_TEMPLATE.d.ts.map

package/src/shade/renderer/material/standard/VT_MATERIAL_TEMPLATE.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"VT_MATERIAL_TEMPLATE.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/material/standard/VT_MATERIAL_TEMPLATE.js"],"names":[],"mappings":"AAoIA;;GAEG;AACH,mCAFU,qBAAqB,CAO5B;uCAnIU,OAAO,iEAAiE,EAAE,wBAAwB;iCAClG,OAAO,0BAA0B,EAAE,kBAAkB;oCACrD,OAAO,6BAA6B,EAAE,qBAAqB;kCAC3D,OAAO,oCAAoC,EAAE,mBAAmB;sCARvC,sCAAsC"}

package/src/shade/renderer/material/standard/VT_MATERIAL_TEMPLATE.js

@@ -0,0 +1,141 @@
+import { assert } from "../../../../core/assert.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 { standard_material_to_struct } from "../standard_material_to_struct.js";
+import { ShadeMaterialTemplate } from "../template/ShadeMaterialTemplate.js";
+import { TransparencyMode } from "../TransparencyMode.js";
+import { SHADING_MATERIAL_VT_RESOURCE_GROUP } from "./fragment_gbuffer_vt.js";
+
+/**
+ * @typedef {import("../../../descriptor/pipeline/render/RenderPipelineDescriptor.js").RenderPipelineDescriptor} RenderPipelineDescriptor
+ * @typedef {import("../GPUMaterialContext.js").GPUMaterialContext} GPUMaterialContext
+ * @typedef {import("../StandardShadeMaterial.js").StandardShadeMaterial} StandardShadeMaterial
+ * @typedef {import("../template/GPUMaterialServices.js").GPUMaterialServices} GPUMaterialServices
+ */
+
+/**
+ * The template a {@link StandardShadeMaterial} with a `vt_stack` draws with: albedo, normal and ORM
+ * stream through the stack, emissive stays a resident texture, and the uniform is the standard one.
+ *
+ * Its surface depends on the cache geometry, so its G-buffer pipeline is the
+ * {@link VirtualTextureManager}'s, built once that geometry is frozen. It cannot cut out: a VT
+ * material set to alpha-tested after creation draws fully covered through the alpha-tested passes.
+ */
+class VirtualTextureMaterialTemplate extends ShadeMaterialTemplate {
+
+    /**
+     * @param {GPUMaterialServices} services
+     * @returns {RenderPipelineDescriptor}
+     */
+    gbuffer_pipeline_descriptor(services) {
+        assert.defined(services.virtual_textures, 'material uses a vt_stack but no VirtualTextureManager is wired');
+
+        return services.virtual_textures.material_pipeline_descriptor;
+    }
+
+    /**
+     * @param {GPUMaterialContext} ctx
+     * @param {GPUMaterialServices} services
+     */
+    build(ctx, services) {
+        /**
+         * @type {StandardShadeMaterial}
+         */
+        const material = ctx.source;
+
+        const virtual_textures = services.virtual_textures;
+
+        assert.defined(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
+        virtual_textures.register_stack(material.vt_stack);
+
+        if (material.texture_emissive !== undefined) {
+            ctx.textures.set(material.texture_emissive, services.textures.obtain(material.texture_emissive));
+        }
+    }
+
+    /**
+     * The uniform is the metadata row.
+     *
+     * @param {StandardShadeMaterial} material
+     * @param {Object} [metadata]
+     * @returns {Object}
+     */
+    uniform_value(material, metadata) {
+        return metadata ?? standard_material_to_struct(material);
+    }
+
+    /**
+     * @param {StandardShadeMaterial} material
+     * @returns {Object}
+     */
+    metadata_value(material) {
+        return standard_material_to_struct(material);
+    }
+
+    /**
+     * 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 {GPUMaterialContext} ctx
+     * @param {GPUBindGroupLayout} layout
+     * @param {GPUMaterialServices} services
+     * @returns {GPUBindGroup}
+     */
+    create_bind_group(ctx, layout, services) {
+        const device = services.device;
+        const defaults = services.defaults;
+        const vt = services.virtual_textures;
+
+        /**
+         * @type {StandardShadeMaterial}
+         */
+        const material = ctx.source;
+
+        let texture_emissive = defaults.texture_pixel_white;
+        let texture_emissive_sampler = defaults.sampler;
+
+        const source_emissive = material.texture_emissive;
+
+        if (source_emissive !== undefined) {
+            texture_emissive = ctx.textures.get(source_emissive);
+            texture_emissive_sampler = device.createSampler(sampler_descriptor_from_shade_texture(source_emissive));
+        }
+
+        const binding_data = {
+            material_info: { buffer: ctx.uniform_buffer },
+
+            texture_emissive: texture_emissive.obtainView(),
+            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,
+        };
+
+        return device.createBindGroup({
+            layout,
+            entries: SHADING_MATERIAL_VT_RESOURCE_GROUP.generateGPUBindGroupEntryArray(binding_data)
+        });
+    }
+}
+
+/**
+ * @type {ShadeMaterialTemplate}
+ */
+export const VT_MATERIAL_TEMPLATE = new VirtualTextureMaterialTemplate({
+    name: "Virtual texture",
+    resources: SHADING_MATERIAL_VT_RESOURCE_GROUP,
+    uniform_type: MATERIAL_METADATA_STRUCT,
+    surface: null,
+});

package/src/shade/renderer/material/standard/chunk_standard_material_surface.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The standard material's arithmetic, given its four texel reads: the part the regular and the
+ * virtual-texture variants share, so the two cannot drift apart. Reads `material_info`, which both
+ * variants declare at group 0.
+ *
+ * `diffuse_sample` is premultiplied, as every albedo texture is uploaded — see
+ * {@link chunk_albedo_unpremultiply}, which is where the rule lives now that the path tracer reads
+ * the same textures through it.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_standard_material_compose: CodeChunk;
+/**
+ * The standard material's surface: the four per-material textures, sampled with the analytic
+ * gradients the G-buffer body hands over, and composed exactly as the G-buffer pass always has.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_standard_material_surface: CodeChunk;
+/**
+ * The standard material's coverage: the albedo texture's alpha times the albedo colour's, sampled
+ * exactly as the alpha-tested passes always have — with the pass's bias and implicit derivatives,
+ * which the contract allows because the passes call this in uniform control flow.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_standard_material_opacity: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_standard_material_surface.d.ts.map

package/src/shade/renderer/material/standard/chunk_standard_material_surface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_standard_material_surface.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/material/standard/chunk_standard_material_surface.js"],"names":[],"mappings":"AASA;;;;;;;;;;GAUG;AACH,8CAFU,SAAS,CA6BjB;AAEF;;;;;GAKG;AACH,8CAFU,SAAS,CAmBjB;AAEF;;;;;;GAMG;AACH,8CAFU,SAAS,CAYjB;0BAxFwB,oCAAoC"}

package/src/shade/renderer/material/standard/chunk_standard_material_surface.js

@@ -0,0 +1,92 @@
+import { chunk_decode_tangent_normal } from "../../shader/chunk/geometry/normal/chunk_decode_tangent_normal.js";
+import { chunk_albedo_unpremultiply } from "../../shader/chunk/material/chunk_albedo_unpremultiply.js";
+import { chunk_textureSampleBarycentric } from "../../shader/chunk/texture/sample/chunk_texture_sample_barycentric.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import {
+    chunk_material_opacity_contract,
+    chunk_material_surface_contract
+} from "../template/chunk_material_surface.js";
+
+/**
+ * The standard material's arithmetic, given its four texel reads: the part the regular and the
+ * virtual-texture variants share, so the two cannot drift apart. Reads `material_info`, which both
+ * variants declare at group 0.
+ *
+ * `diffuse_sample` is premultiplied, as every albedo texture is uploaded — see
+ * {@link chunk_albedo_unpremultiply}, which is where the rule lives now that the path tracer reads
+ * the same textures through it.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_standard_material_compose = CodeChunk.from(
+    //language=WGSL
+    `
+fn standard_material_compose(
+    s: MaterialSurfaceInput,
+    orm_sample: vec4<f32>,
+    diffuse_sample: vec4<f32>,
+    normal_sample: vec4<f32>,
+    emissive_sample: vec3<f32>,
+) -> MaterialSurfaceOutput {
+    var out: MaterialSurfaceOutput;
+
+    out.albedo = albedo_unpremultiply(diffuse_sample) * s.vertex_color * material_info.albedo_color.rgb;
+    out.ambient = fma(orm_sample.r, material_info.ambient_factors.x, material_info.ambient_factors.y);
+    out.roughness = orm_sample.g * material_info.roughness_factor;
+    out.metalness = orm_sample.b * material_info.metallic_factor;
+    out.normal = decode_tangent_normal(normal_sample);
+    out.emissive = emissive_sample * material_info.emissive_factor;
+
+    return out;
+}
+`,
+    [
+        chunk_material_surface_contract,
+        chunk_albedo_unpremultiply,
+        chunk_decode_tangent_normal,
+    ]
+);
+
+/**
+ * The standard material's surface: the four per-material textures, sampled with the analytic
+ * gradients the G-buffer body hands over, and composed exactly as the G-buffer pass always has.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_standard_material_surface = CodeChunk.from(
+    //language=WGSL
+    `
+fn material_surface(s: MaterialSurfaceInput) -> MaterialSurfaceOutput {
+    return standard_material_compose(
+        s,
+        textureSampleBarycentric(texture_orm, texture_orm_sampler, s.uv),
+        textureSampleBarycentric(texture_diffuse, texture_diffuse_sampler, s.uv),
+        textureSampleBarycentric(texture_normal, texture_normal_sampler, s.uv),
+        textureSampleBarycentric(texture_emissive, texture_emissive_sampler, s.uv).rgb,
+    );
+}
+`,
+    [
+        chunk_standard_material_compose,
+        chunk_textureSampleBarycentric,
+    ]
+);
+
+/**
+ * The standard material's coverage: the albedo texture's alpha times the albedo colour's, sampled
+ * exactly as the alpha-tested passes always have — with the pass's bias and implicit derivatives,
+ * which the contract allows because the passes call this in uniform control flow.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_standard_material_opacity = CodeChunk.from(
+    //language=WGSL
+    `
+fn material_opacity(s: MaterialOpacityInput) -> f32 {
+    return textureSampleBias(texture_diffuse, texture_diffuse_sampler, s.uv.uv, s.mip_bias).a * material_info.albedo_color.a;
+}
+`,
+    [
+        chunk_material_opacity_contract,
+    ]
+);