@woosh/meep-engine 3.29.0 → 3.31.0

package/src/shade/renderer/material/template/ShadeMaterialTemplate.js

@@ -0,0 +1,234 @@
+import { assert } from "../../../../core/assert.js";
+import { build_gbuffer_pipeline_descriptor } from "../standard/fragment_gbuffer.js";
+import { material_metadata_neutral } from "./material_metadata_neutral.js";
+
+/**
+ * @typedef {import("../../../descriptor/pipeline/render/RenderPipelineDescriptor.js").RenderPipelineDescriptor} RenderPipelineDescriptor
+ * @typedef {import("../../shader/compiler/CodeChunk.js").CodeChunk} CodeChunk
+ * @typedef {import("../../shader/resource/ShaderResourceGroupDescriptor.js").ShaderResourceGroupDescriptor} ShaderResourceGroupDescriptor
+ * @typedef {import("../../shader/type/WebGPUType.js").WebGPUType} WebGPUType
+ * @typedef {import("../GPUMaterialContext.js").GPUMaterialContext} GPUMaterialContext
+ * @typedef {import("../ShadeMaterial.js").ShadeMaterial} ShadeMaterial
+ * @typedef {import("./GPUMaterialServices.js").GPUMaterialServices} GPUMaterialServices
+ */
+
+let ordinal_counter = 0;
+
+/**
+ * A kind of surface: the shader code that turns a visibility-buffer pixel into G-buffer values, the
+ * group-0 resources that code reads, and the CPU hooks that fill those resources for one material.
+ *
+ * A template is created once and shared; a {@link ShadeMaterial} is an instance of one, and its
+ * {@link GPUMaterialContext} holds that instance's uniform buffer and bind group, built by the
+ * template's hooks. There are only ever a handful of templates, and every G-buffer pipeline, every
+ * alpha-tested pipeline and every compile is per template — never per material.
+ *
+ * **Group 0 is the template's.** It is declared with fragment visibility, and one bind group per
+ * material built on it serves the G-buffer pass and both alpha-tested passes. Groups 1 and 2 belong
+ * to the passes, so a template must not reuse their names (`viz_buffer_triangle`, `viz_buffer_mesh`,
+ * `view`, `camera`, `scene_database`, `geometries`, `meshlets`, `meshlet_metadata`, `meshlet_data`,
+ * `materials`, `t_noise`).
+ *
+ * **The surface function** — `fn material_surface(s: MaterialSurfaceInput) -> MaterialSurfaceOutput`,
+ * see {@link chunk_material_surface_contract} — is all a template contributes to the G-buffer pass.
+ * **The opacity function** — `fn material_opacity(s: MaterialOpacityInput) -> f32` — is optional;
+ * without one the template is opaque-only, and a material of it set to alpha-tested draws fully
+ * covered rather than vanishing.
+ */
+export class ShadeMaterialTemplate {
+    /**
+     * Small, unique and stable: the draw lists sort by it, so every material of a template draws
+     * together and pipeline switches are one per template.
+     *
+     * @readonly
+     * @type {number}
+     */
+    ordinal = ordinal_counter++;
+
+    /**
+     * @type {string}
+     */
+    name;
+
+    /**
+     * Group 0, with fragment visibility.
+     *
+     * @type {ShaderResourceGroupDescriptor}
+     */
+    resources;
+
+    /**
+     * Type of the per-material uniform buffer the context allocates, or `null` for a template that
+     * has none. The buffer is written from {@link uniform_value} when the context is created and
+     * again whenever the material's version moves; binding it is the template's, in
+     * {@link create_bind_group}.
+     *
+     * @type {WebGPUType|null}
+     */
+    uniform_type = null;
+
+    /**
+     * Defines `material_surface`. `null` only for a template that builds its G-buffer pipeline itself
+     * — the virtual-texture one, whose surface depends on the cache geometry.
+     *
+     * @type {CodeChunk|null}
+     */
+    surface;
+
+    /**
+     * Defines `material_opacity`, or `null` when the template cannot cut out.
+     *
+     * @type {CodeChunk|null}
+     */
+    opacity = null;
+
+    /**
+     * Whether the transparent passes can draw it. They are standard-only for now, and skip a
+     * material whose template is not.
+     *
+     * @type {boolean}
+     */
+    forward = false;
+
+    /**
+     * Whether {@link update} runs once a frame for each of its materials. Only a template with
+     * resources that change without the material's version moving — terrain's weight and overlay
+     * maps — says so.
+     *
+     * @type {boolean}
+     */
+    dynamic = false;
+
+    /**
+     * @type {RenderPipelineDescriptor|null}
+     */
+    #gbuffer_pipeline_descriptor = null;
+
+    /**
+     * @param {Object} options
+     * @param {string} options.name
+     * @param {ShaderResourceGroupDescriptor} options.resources
+     * @param {CodeChunk|null} options.surface
+     * @param {WebGPUType|null} [options.uniform_type]
+     * @param {CodeChunk|null} [options.opacity]
+     * @param {boolean} [options.forward]
+     * @param {boolean} [options.dynamic]
+     */
+    constructor({
+                    name,
+                    resources,
+                    surface,
+                    uniform_type = null,
+                    opacity = null,
+                    forward = false,
+                    dynamic = false,
+                }) {
+        assert.isString(name, 'name');
+        assert.defined(resources, 'resources');
+        assert.defined(surface, 'surface');
+        assert.isBoolean(forward, 'forward');
+        assert.isBoolean(dynamic, 'dynamic');
+
+        this.name = name;
+        this.resources = resources;
+        this.surface = surface;
+        this.uniform_type = uniform_type;
+        this.opacity = opacity;
+        this.forward = forward;
+        this.dynamic = dynamic;
+    }
+
+    /**
+     * The template's G-buffer pipeline. Built once, from {@link resources} and {@link surface}.
+     *
+     * @param {GPUMaterialServices} services
+     * @returns {RenderPipelineDescriptor}
+     */
+    gbuffer_pipeline_descriptor(services) {
+        if (this.#gbuffer_pipeline_descriptor === null) {
+            assert.notNull(this.surface, `template '${this.name}' has no surface function`);
+
+            this.#gbuffer_pipeline_descriptor = build_gbuffer_pipeline_descriptor({
+                label: `${this.name} material / Viz-Buffer to G-Buffer laydown`,
+                material_group: this.resources,
+                surface: this.surface,
+            });
+        }
+
+        return this.#gbuffer_pipeline_descriptor;
+    }
+
+    /**
+     * Once, when the material's context is created and before its uniform is written: obtain what
+     * the bind group will name, and upload anything the template owns, so the first bind group
+     * binds real resources.
+     *
+     * @param {GPUMaterialContext} ctx
+     * @param {GPUMaterialServices} services
+     */
+    build(ctx, services) {
+    }
+
+    /**
+     * The value of the material's uniform, of {@link uniform_type}.
+     *
+     * @param {ShadeMaterial} material
+     * @param {Object} [metadata] the metadata row just written for the same version of the material,
+     *        when the uniform is being rewritten — a template whose uniform is that row returns it as
+     *        is, rather than building it twice
+     * @returns {Object}
+     */
+    uniform_value(material, metadata) {
+        throw new Error(`Template '${this.name}' declares a uniform type but no uniform value`);
+    }
+
+    /**
+     * The material's row of the metadata table — every field the GPU reads from it, always, because
+     * the table's upload stream is rewound rather than cleared and a skipped field would carry the
+     * previous record's bytes.
+     *
+     * @param {ShadeMaterial} material
+     * @returns {Object} a {@link MATERIAL_METADATA_STRUCT} value
+     */
+    metadata_value(material) {
+        return material_metadata_neutral(material);
+    }
+
+    /**
+     * @param {GPUMaterialContext} ctx
+     * @param {GPUBindGroupLayout} layout group 0 of the template's G-buffer pipeline, which is the
+     *        same layout object as group 0 of its alpha-tested pipelines
+     * @param {GPUMaterialServices} services
+     * @returns {GPUBindGroup}
+     */
+    create_bind_group(ctx, layout, services) {
+        throw new Error(`Template '${this.name}' does not build a bind group`);
+    }
+
+    /**
+     * Once a frame, before any pass, for each material of a {@link dynamic} template.
+     *
+     * @param {GPUMaterialContext} ctx
+     * @param {GPUMaterialServices} services
+     * @returns {boolean} true when a resource the bind group names was replaced, so it has to be
+     *          rebuilt
+     */
+    update(ctx, services) {
+        return false;
+    }
+
+    /**
+     * Give back what {@link build} and {@link update} created.
+     *
+     * @param {GPUMaterialContext} ctx
+     * @param {GPUMaterialServices} services
+     */
+    destroy(ctx, services) {
+    }
+}
+
+/**
+ * @readonly
+ * @type {boolean}
+ */
+ShadeMaterialTemplate.prototype.isShadeMaterialTemplate = true;

package/src/shade/renderer/material/template/chunk_material_surface.d.ts

@@ -0,0 +1,47 @@
+/**
+ * What a material template's surface function is given and what it gives back — the whole of the
+ * boundary between a template and the G-buffer pass.
+ *
+ * The G-buffer body ({@link build_gbuffer_fragment_body}) reconstructs everything on the input side
+ * from the visibility buffer and consumes the output: it builds the tangent frame the normal is
+ * expressed in, anti-aliases and dithers the roughness, and encodes the G-buffer. A template sees
+ * none of that — no visibility buffer, no G-buffer format, no binding but its own group 0.
+ *
+ * **Gradients are analytic.** The resolve's neighbouring pixels can belong to another triangle or
+ * another material, so hardware derivatives mean nothing here. Both UV sets arrive with the gradients
+ * the body derives from the barycentrics, already scaled by the mip bias (`gradient_bias` says by
+ * how much); geometry-space position arrives with its own gradients, unbiased, for a template that
+ * maps from position rather than from UVs — terrain, which cannot use its tiles' `uv0` because the
+ * tile builder relaxes interior UVs away from the planar projection.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_material_surface_contract: CodeChunk;
+/**
+ * What the alpha-tested passes — visibility and shadow — hand a template's opacity function.
+ *
+ * `material_opacity` is called at the top of the pass's `main`, in uniform control flow, so a
+ * template may sample with implicit derivatives: `textureSampleBias(t, s, input.uv.uv, input.mip_bias)`
+ * is exactly the sample these passes have always taken, and the one to prefer. Explicit-gradient
+ * sampling runs at a reduced rate on common hardware, and scaled gradients shrink the anisotropic
+ * footprint where a bias only moves the level.
+ *
+ * For a template that has to sample where derivatives are not available, the gradients are there
+ * too: `dpdx`/`dpdy` of the interpolated UV, scaled by `exp2(mip_bias)`, which selects the level the
+ * bias would. Unused, they cost nothing — the compiler drops them.
+ *
+ * The hashed threshold, and the noise each pass feeds it, stay in the pass.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_material_opacity_contract: CodeChunk;
+/**
+ * The opacity of a template that cannot cut out: fully covered. A material of such a template that
+ * is set to alpha-tested therefore draws, opaque, through the alpha-tested passes — rather than
+ * vanishing, or throwing on binding names its group 0 does not have.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_material_opacity_opaque: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_material_surface.d.ts.map

package/src/shade/renderer/material/template/chunk_material_surface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_material_surface.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/material/template/chunk_material_surface.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;GAiBG;AACH,8CAFU,SAAS,CA8CjB;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,8CAFU,SAAS,CAcjB;AAEF;;;;;;GAMG;AACH,4CAFU,SAAS,CAYjB;0BAlHwB,oCAAoC"}

package/src/shade/renderer/material/template/chunk_material_surface.js

@@ -0,0 +1,116 @@
+import { GRADIENT_SAMPLING_INFO_STRUCT } from "../../shader/chunk/texture/GRADIENT_SAMPLING_INFO_STRUCT.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+
+/**
+ * What a material template's surface function is given and what it gives back — the whole of the
+ * boundary between a template and the G-buffer pass.
+ *
+ * The G-buffer body ({@link build_gbuffer_fragment_body}) reconstructs everything on the input side
+ * from the visibility buffer and consumes the output: it builds the tangent frame the normal is
+ * expressed in, anti-aliases and dithers the roughness, and encodes the G-buffer. A template sees
+ * none of that — no visibility buffer, no G-buffer format, no binding but its own group 0.
+ *
+ * **Gradients are analytic.** The resolve's neighbouring pixels can belong to another triangle or
+ * another material, so hardware derivatives mean nothing here. Both UV sets arrive with the gradients
+ * the body derives from the barycentrics, already scaled by the mip bias (`gradient_bias` says by
+ * how much); geometry-space position arrives with its own gradients, unbiased, for a template that
+ * maps from position rather than from UVs — terrain, which cannot use its tiles' `uv0` because the
+ * tile builder relaxes interior UVs away from the planar projection.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_material_surface_contract = CodeChunk.from(
+    //language=WGSL
+    `
+struct MaterialSurfaceInput {
+    uv: ${GRADIENT_SAMPLING_INFO_STRUCT.wgsl_ref},
+    uv1: ${GRADIENT_SAMPLING_INFO_STRUCT.wgsl_ref},
+    gradient_bias: vec2<f32>,
+    position_os: vec3<f32>,
+    position_os_ddx: vec3<f32>,
+    position_os_ddy: vec3<f32>,
+    position_ws: vec3<f32>,
+    normal_ws: vec3<f32>,
+    face_normal_ws: vec3<f32>,
+    view_direction_ws: vec3<f32>,
+    vertex_color: vec3<f32>,
+    pixel: vec2<f32>,
+}
+
+struct MaterialSurfaceOutput {
+    albedo: vec3<f32>,
+    ambient: f32,
+    roughness: f32,
+    metalness: f32,
+    normal: vec3<f32>,
+    emissive: vec3<f32>,
+}
+
+/**
+ * White, fully lit, fully rough, not metallic, no normal perturbation, no emission.
+ */
+fn material_surface_default() -> MaterialSurfaceOutput {
+    return MaterialSurfaceOutput(
+        vec3<f32>(1.0),
+        1.0,
+        1.0,
+        0.0,
+        vec3<f32>(0.0, 0.0, 1.0),
+        vec3<f32>(0.0),
+    );
+}
+`,
+    [
+        GRADIENT_SAMPLING_INFO_STRUCT.declaration_chunk,
+    ]
+);
+
+/**
+ * What the alpha-tested passes — visibility and shadow — hand a template's opacity function.
+ *
+ * `material_opacity` is called at the top of the pass's `main`, in uniform control flow, so a
+ * template may sample with implicit derivatives: `textureSampleBias(t, s, input.uv.uv, input.mip_bias)`
+ * is exactly the sample these passes have always taken, and the one to prefer. Explicit-gradient
+ * sampling runs at a reduced rate on common hardware, and scaled gradients shrink the anisotropic
+ * footprint where a bias only moves the level.
+ *
+ * For a template that has to sample where derivatives are not available, the gradients are there
+ * too: `dpdx`/`dpdy` of the interpolated UV, scaled by `exp2(mip_bias)`, which selects the level the
+ * bias would. Unused, they cost nothing — the compiler drops them.
+ *
+ * The hashed threshold, and the noise each pass feeds it, stay in the pass.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_material_opacity_contract = CodeChunk.from(
+    //language=WGSL
+    `
+struct MaterialOpacityInput {
+    uv: ${GRADIENT_SAMPLING_INFO_STRUCT.wgsl_ref},
+    mip_bias: f32,
+    position_ws: vec3<f32>,
+}
+`,
+    [
+        GRADIENT_SAMPLING_INFO_STRUCT.declaration_chunk,
+    ]
+);
+
+/**
+ * The opacity of a template that cannot cut out: fully covered. A material of such a template that
+ * is set to alpha-tested therefore draws, opaque, through the alpha-tested passes — rather than
+ * vanishing, or throwing on binding names its group 0 does not have.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_material_opacity_opaque = CodeChunk.from(
+    //language=WGSL
+    `
+fn material_opacity(s: MaterialOpacityInput) -> f32 {
+    return 1.0;
+}
+`,
+    [
+        chunk_material_opacity_contract,
+    ]
+);

package/src/shade/renderer/material/template/flat_material_template_spec_support.d.ts

@@ -0,0 +1,22 @@
+export const FLAT_SURFACE_STRUCT: WebGPUStruct;
+export const FLAT_MATERIAL_RESOURCE_GROUP: ShaderResourceGroupDescriptor;
+export const chunk_flat_material_surface: CodeChunk;
+export const FLAT_MATERIAL_TEMPLATE: FlatMaterialTemplate;
+export class FlatShadeMaterial extends ShadeMaterial {
+    color: number[];
+    equals(other: any): boolean;
+    template: FlatMaterialTemplate;
+}
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+import { ShaderResourceGroupDescriptor } from "../../shader/resource/ShaderResourceGroupDescriptor.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+declare class FlatMaterialTemplate extends ShadeMaterialTemplate {
+    uniform_value(material: any): {
+        color: any;
+    };
+    create_bind_group(ctx: any, layout: any, services: any): any;
+}
+import { ShadeMaterial } from "../ShadeMaterial.js";
+import { ShadeMaterialTemplate } from "./ShadeMaterialTemplate.js";
+export {};
+//# sourceMappingURL=flat_material_template_spec_support.d.ts.map

package/src/shade/renderer/material/template/flat_material_template_spec_support.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flat_material_template_spec_support.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/material/template/flat_material_template_spec_support.js"],"names":[],"mappings":"AAeA,+CAEkB;AAElB,yEAAgF;AAQhF,oDAcE;AAiBF,0DAKG;AAEH;IACI,gBAAqB;IAErB,4BAEC;IAOL,+BAAoC;CAFnC;6BAvE4B,mCAAmC;8CAFlB,wDAAwD;0BAD5E,oCAAoC;AA0C9D;IACI;;MAEC;IAED,6DAOC;CACJ;8BAnD6B,qBAAqB;sCAEb,4BAA4B"}

package/src/shade/renderer/material/template/flat_material_template_spec_support.js

@@ -0,0 +1,78 @@
+import { GPUShaderStage } from "../../../descriptor/GPUShaderStage.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { ShaderResourceGroupDescriptor } from "../../shader/resource/ShaderResourceGroupDescriptor.js";
+import { vec4f } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+import { ShadeMaterial } from "../ShadeMaterial.js";
+import { chunk_material_surface_contract } from "./chunk_material_surface.js";
+import { ShadeMaterialTemplate } from "./ShadeMaterialTemplate.js";
+
+/*
+ The smallest template that is not the standard one: a colour in its own uniform, under its own
+ group 0, with no textures and no opacity function. What the specs use to show that nothing on the
+ way from a material to a draw assumes the standard material.
+*/
+
+export const FLAT_SURFACE_STRUCT = WebGPUStruct.from({
+    color: vec4f,
+}, "FlatSurface");
+
+export const FLAT_MATERIAL_RESOURCE_GROUP = new ShaderResourceGroupDescriptor();
+
+FLAT_MATERIAL_RESOURCE_GROUP.label = "Material Flat";
+
+FLAT_MATERIAL_RESOURCE_GROUP.addUniform("flat", FLAT_SURFACE_STRUCT);
+
+FLAT_MATERIAL_RESOURCE_GROUP.addVisibility(GPUShaderStage.FRAGMENT);
+
+export const chunk_flat_material_surface = CodeChunk.from(
+    //language=WGSL
+    `
+fn material_surface(s: MaterialSurfaceInput) -> MaterialSurfaceOutput {
+    var out = material_surface_default();
+
+    out.albedo = flat.color.rgb;
+
+    return out;
+}
+`,
+    [
+        chunk_material_surface_contract,
+    ]
+);
+
+class FlatMaterialTemplate extends ShadeMaterialTemplate {
+    uniform_value(material) {
+        return { color: material.color };
+    }
+
+    create_bind_group(ctx, layout, services) {
+        return services.device.createBindGroup({
+            layout,
+            entries: FLAT_MATERIAL_RESOURCE_GROUP.generateGPUBindGroupEntryArray({
+                flat: { buffer: ctx.uniform_buffer }
+            })
+        });
+    }
+}
+
+export const FLAT_MATERIAL_TEMPLATE = new FlatMaterialTemplate({
+    name: "Flat",
+    resources: FLAT_MATERIAL_RESOURCE_GROUP,
+    uniform_type: FLAT_SURFACE_STRUCT,
+    surface: chunk_flat_material_surface,
+});
+
+export class FlatShadeMaterial extends ShadeMaterial {
+    color = [1, 0, 0, 1];
+
+    equals(other) {
+        return this === other;
+    }
+
+    hash() {
+        return this.id;
+    }
+}
+
+FlatShadeMaterial.prototype.template = FLAT_MATERIAL_TEMPLATE;

package/src/shade/renderer/material/template/material_metadata_neutral.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The metadata row of a material that is not standard: the fields the GPU reads from the table —
+ * id, transparency mode, draw mode, draw side and VT stack — from the material, and the standard
+ * surface fields at values that change nothing: white, opaque, fully rough, not metallic, not
+ * transmissive, not emissive.
+ *
+ * Complete on purpose. The table's upload stream is rewound and not cleared, so a field left out
+ * would carry whatever the previous record left at that offset.
+ *
+ * @see MATERIAL_METADATA_STRUCT
+ * @param {ShadeMaterial} material
+ * @returns {Object}
+ */
+export function material_metadata_neutral(material: ShadeMaterial): any;
+//# sourceMappingURL=material_metadata_neutral.d.ts.map

package/src/shade/renderer/material/template/material_metadata_neutral.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"material_metadata_neutral.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/material/template/material_metadata_neutral.js"],"names":[],"mappings":"AAiBA;;;;;;;;;;;;GAYG;AACH,wEAeC"}

package/src/shade/renderer/material/template/material_metadata_neutral.js

@@ -0,0 +1,46 @@
+import { VT_STACK_ID_INVALID } from "../../texture/virtual/VT_CONSTANTS.js";
+
+/**
+ * @type {number[]}
+ */
+const NEUTRAL_ALBEDO = Object.freeze([1, 1, 1, 1]);
+
+/**
+ * @type {number[]}
+ */
+const NEUTRAL_EMISSIVE = Object.freeze([0, 0, 0]);
+
+/**
+ * @type {number[]}
+ */
+const NEUTRAL_AMBIENT = Object.freeze([1, 0]);
+
+/**
+ * The metadata row of a material that is not standard: the fields the GPU reads from the table —
+ * id, transparency mode, draw mode, draw side and VT stack — from the material, and the standard
+ * surface fields at values that change nothing: white, opaque, fully rough, not metallic, not
+ * transmissive, not emissive.
+ *
+ * Complete on purpose. The table's upload stream is rewound and not cleared, so a field left out
+ * would carry whatever the previous record left at that offset.
+ *
+ * @see MATERIAL_METADATA_STRUCT
+ * @param {ShadeMaterial} material
+ * @returns {Object}
+ */
+export function material_metadata_neutral(material) {
+    return {
+        id: material.id,
+        albedo_color: NEUTRAL_ALBEDO,
+        roughness_factor: 1,
+        metallic_factor: 0,
+        transmission_factor: 0,
+        ior_factor: 1.5,
+        emissive_factor: NEUTRAL_EMISSIVE,
+        ambient_factors: NEUTRAL_AMBIENT,
+        transparency_mode: material.transparency_mode,
+        draw_mode: material.draw_mode,
+        draw_side: material.draw_side,
+        vt_stack: VT_STACK_ID_INVALID,
+    };
+}

package/src/shade/renderer/material/template/material_template_of.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The template a material draws with. A material that is not standard names its own, as
+ * `template`; a {@link StandardShadeMaterial} names none and draws with the standard template, or
+ * the virtual-texture one when it has a stack.
+ *
+ * @param {ShadeMaterial} material
+ * @returns {ShadeMaterialTemplate}
+ */
+export function material_template_of(material: ShadeMaterial): ShadeMaterialTemplate;
+//# sourceMappingURL=material_template_of.d.ts.map

package/src/shade/renderer/material/template/material_template_of.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"material_template_of.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/material/template/material_template_of.js"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AACH,qFAQC"}

package/src/shade/renderer/material/template/material_template_of.js

@@ -0,0 +1,20 @@
+import { STANDARD_MATERIAL_TEMPLATE } from "../standard/STANDARD_MATERIAL_TEMPLATE.js";
+import { VT_MATERIAL_TEMPLATE } from "../standard/VT_MATERIAL_TEMPLATE.js";
+
+/**
+ * The template a material draws with. A material that is not standard names its own, as
+ * `template`; a {@link StandardShadeMaterial} names none and draws with the standard template, or
+ * the virtual-texture one when it has a stack.
+ *
+ * @param {ShadeMaterial} material
+ * @returns {ShadeMaterialTemplate}
+ */
+export function material_template_of(material) {
+    const template = material.template;
+
+    if (template !== undefined) {
+        return template;
+    }
+
+    return material.vt_stack != null ? VT_MATERIAL_TEMPLATE : STANDARD_MATERIAL_TEMPLATE;
+}

package/src/shade/renderer/object_property/chunk_write_object_property.d.ts

@@ -9,6 +9,11 @@
  * the full handle (so it can re-emit it onto the object-property reference
  * stream when needed) and unpacks the index itself.
  *
+ * `weight` is the weight `value` has already been multiplied by. Only the
+ * Node3D writer wants it, and only for rotation: a rotation channel missing
+ * its `w` curve defaults to the identity's 1, which has to be weighted the
+ * same way the authored channels were.
+ *
  * Each writer lives in its own CodeChunk and operates on whatever storage
  * buffers the importing shader has bound under the documented names —
  * the Node3D writer expects `pose_accumulator: array<atomic<u32>>` (the

package/src/shade/renderer/object_property/chunk_write_object_property.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_write_object_property.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/object_property/chunk_write_object_property.js"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;GAkBG;AACH,0CAFU,SAAS,CA0Bb;0BApDoB,iCAAiC"}
+{"version":3,"file":"chunk_write_object_property.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/object_property/chunk_write_object_property.js"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,0CAFU,SAAS,CA2Bb;0BA1DoB,iCAAiC"}

package/src/shade/renderer/object_property/chunk_write_object_property.js

@@ -18,6 +18,11 @@ import { ObjectType } from "./ObjectType.js";
  * the full handle (so it can re-emit it onto the object-property reference
  * stream when needed) and unpacks the index itself.
  *
+ * `weight` is the weight `value` has already been multiplied by. Only the
+ * Node3D writer wants it, and only for rotation: a rotation channel missing
+ * its `w` curve defaults to the identity's 1, which has to be weighted the
+ * same way the authored channels were.
+ *
  * Each writer lives in its own CodeChunk and operates on whatever storage
  * buffers the importing shader has bound under the documented names —
  * the Node3D writer expects `pose_accumulator: array<atomic<u32>>` (the
@@ -34,12 +39,13 @@ fn write_object_property(
     property: u32,
     mask: u32,
     value: vec4f,
+    weight: f32,
 ) {
     let object_type = instance >> 24u;
 
     switch(object_type){
         case ${ObjectType.Node3D}u: {
-            write_object_property_node3d(instance, property, mask, value);
+            write_object_property_node3d(instance, property, mask, value, weight);
         }
         case ${ObjectType.Material}u: {
             write_object_property_material(instance, property, mask, value);

package/src/shade/renderer/object_property/chunk_write_object_property_node3d.d.ts

@@ -27,7 +27,13 @@
  * `mask` is the per-channel write gate. Translation and Scale respect
  * it per axis (the accumulator's per-axis dirty bits ensure the
  * resolve pass only overwrites the channels that were actually
- * contributed); Rotation needs all four channels and ignores the mask.
+ * contributed); Rotation needs all four channels, and uses the mask
+ * only to tell a missing `w` curve from an authored zero.
+ *
+ * `weight` is the clip weight `value` has already been multiplied by.
+ * Rotation needs it because the identity it substitutes for a missing
+ * channel has to carry the same weight as the channels that were
+ * authored; nothing else here does.
  *
  * @type {CodeChunk}
  */