@woosh/meep-engine 3.30.0 → 3.31.0

package/src/shade/renderer/rasterize/forward/forward_template_pipeline.js

@@ -0,0 +1,86 @@
+import { assert } from "../../../../core/assert.js";
+import { GPUShaderStage } from "../../../descriptor/GPUShaderStage.js";
+import { PipelineLayoutDescriptor } from "../../../descriptor/pipeline/PipelineLayoutDescriptor.js";
+import { SHADING_LIGHT_RESOURCE_GROUP } from "../../deferred/SHADING_LIGHT_RESOURCE_GROUP.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import { SHADING_SCENE_LAYOUT, SHADING_SCENE_RESOURCE_GROUP } from "./SHADING_SCENE_RESOURCE_GROUP.js";
+
+/**
+ * @typedef {import("../../../descriptor/binding/BindGroupLayoutDescriptor.js").BindGroupLayoutDescriptor} BindGroupLayoutDescriptor
+ * @typedef {import("../../shader/resource/ShaderResourceGroupDescriptor.js").ShaderResourceGroupDescriptor} ShaderResourceGroupDescriptor
+ * @typedef {import("../../material/template/ShadeMaterialTemplate.js").ShadeMaterialTemplate} ShadeMaterialTemplate
+ */
+
+/*
+ How every transparent pipeline is laid out, for one template: group 0 is the template's own,
+ exactly as its G-buffer pipeline declares it; group 1 is the forward scene group; the rest are the
+ pass's. Because group 0 is the template's and nothing else, the material's one bind group — the
+ G-buffer pass's — is what the transparent loop binds, and the loop builds none.
+
+ Storage buffers are counted per stage across the whole layout, against the 10 `Renderer` asks the
+ device for. The vertex stage spends six on the scene group, so a pass group is visible to it only
+ when it reads that group: the lights are the fragment stage's alone.
+*/
+
+/**
+ * The lights, as the passes that shade with them lay the group out and bind it: fragment-only.
+ *
+ * @type {BindGroupLayoutDescriptor}
+ */
+export const FORWARD_LIGHT_LAYOUT = SHADING_LIGHT_RESOURCE_GROUP.generateBindGroupLayoutDescriptor(GPUShaderStage.FRAGMENT);
+
+/**
+ * What a transparent pass's fragment stage declares for a template.
+ *
+ * @param {ShadeMaterialTemplate} template
+ * @param {ShaderResourceGroupDescriptor[]} pass_groups groups 2 and up
+ * @returns {ShaderResourceSetDescriptor}
+ */
+export function forward_fragment_resources(template, pass_groups) {
+    const resources = new ShaderResourceSetDescriptor();
+
+    resources.addGroup(template.resources);
+    resources.addGroup(SHADING_SCENE_RESOURCE_GROUP);
+
+    for (let i = 0; i < pass_groups.length; i++) {
+        resources.addGroup(pass_groups[i]);
+    }
+
+    return resources;
+}
+
+/**
+ * What the shared forward vertex stage declares: nothing at group 0, which is the template's and
+ * fragment-only.
+ *
+ * @param {ShaderResourceGroupDescriptor[]} pass_groups groups 2 and up, as far as the vertex stage
+ *        reads them
+ * @returns {ShaderResourceSetDescriptor}
+ */
+export function forward_vertex_resources(pass_groups) {
+    const resources = new ShaderResourceSetDescriptor();
+
+    resources.createGroup({ index: 0, label: "material (fragment only)" });
+    resources.addGroup(SHADING_SCENE_RESOURCE_GROUP);
+
+    for (let i = 0; i < pass_groups.length; i++) {
+        resources.addGroup(pass_groups[i]);
+    }
+
+    return resources;
+}
+
+/**
+ * @param {ShadeMaterialTemplate} template
+ * @param {BindGroupLayoutDescriptor[]} pass_layouts groups 2 and up, as the pass binds them
+ * @returns {PipelineLayoutDescriptor}
+ */
+export function forward_pipeline_layout(template, pass_layouts) {
+    assert.equal(template.forward, true, `template '${template.name}' cannot be drawn forward`);
+
+    return PipelineLayoutDescriptor.from([
+        template.resources.generateBindGroupLayoutDescriptor(),
+        SHADING_SCENE_LAYOUT,
+        ...pass_layouts,
+    ]);
+}

package/src/shade/renderer/rasterize/forward/vertex_shader_chunk.d.ts

@@ -1,3 +1,14 @@
+/**
+ * The forward vertex stage every transparent pipeline shares, whatever the material's template.
+ *
+ * **It reads nothing from group 0.** The side a material draws comes from the metadata table, per
+ * instance, as it does for the opaque and alpha-tested rasterizers, and the colour it hands on is
+ * the vertex's own — the material's albedo colour is applied by the fragment stage, which is the
+ * one that knows the material. That is what lets group 0 be the material's own fragment-only group,
+ * the one the G-buffer pass binds.
+ *
+ * @type {CodeChunk}
+ */
 export const vertex_shader_chunk: CodeChunk;
 import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
 //# sourceMappingURL=vertex_shader_chunk.d.ts.map

package/src/shade/renderer/rasterize/forward/vertex_shader_chunk.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vertex_shader_chunk.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/rasterize/forward/vertex_shader_chunk.js"],"names":[],"mappings":"AAeA,4CAgEE;0BAnEwB,oCAAoC"}
+{"version":3,"file":"vertex_shader_chunk.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/rasterize/forward/vertex_shader_chunk.js"],"names":[],"mappings":"AAeA;;;;;;;;;;GAUG;AACH,kCAFU,SAAS,CAkEjB;0BA9EwB,oCAAoC"}

package/src/shade/renderer/rasterize/forward/vertex_shader_chunk.js

@@ -13,6 +13,17 @@ import {
 import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
 import { FORWARD_VERTEX_SHADER_STRUCT } from "./FORWARD_VERTEX_SHADER_STRUCT.js";
 
+/**
+ * The forward vertex stage every transparent pipeline shares, whatever the material's template.
+ *
+ * **It reads nothing from group 0.** The side a material draws comes from the metadata table, per
+ * instance, as it does for the opaque and alpha-tested rasterizers, and the colour it hands on is
+ * the vertex's own — the material's albedo colour is applied by the fragment stage, which is the
+ * one that knows the material. That is what lets group 0 be the material's own fragment-only group,
+ * the one the G-buffer pass binds.
+ *
+ * @type {CodeChunk}
+ */
 export const vertex_shader_chunk = CodeChunk.from(
     //language=WGSL
     `
@@ -39,7 +50,7 @@ fn main(
         meshlet_header,
         triangle_list_reverse_winding(
             meshlet_vertex_id,
-            triangle_winding_is_reversed(node, material_info.draw_side)
+            triangle_winding_is_reversed(node, materials[mesh.material].draw_side)
         ),
     );
 
@@ -64,7 +75,7 @@ fn main(
     let world_tangent = vec4( normalize( normal_model_matrix * geometry_tangent.xyz ), tangent_handedness );
     output.tangent = world_tangent;
 
-    output.color = geo_vertex.color * material_info.albedo_color.rgb;
+    output.color = geo_vertex.color;
 
     return output;
 }

package/src/shade/renderer/rasterize/native/alpha_tested_pass_resources.d.ts

@@ -1,6 +1,64 @@
+/**
+ * What a template's alpha-tested fragment stage declares: the template's group 0, then the passes'
+ * groups 1 and 2.
+ *
+ * @param {ShadeMaterialTemplate} template
+ * @returns {ShaderResourceSetDescriptor}
+ */
+export function alpha_tested_fragment_resources(template: ShadeMaterialTemplate): ShaderResourceSetDescriptor;
+/**
+ * The layout of a template's alpha-tested pipelines. Group 0 is laid out exactly as it is in the
+ * template's G-buffer pipeline — same descriptor, same visibility — so the layout manager hands
+ * both the same bind group layout and one bind group per material serves every pass.
+ *
+ * @param {ShadeMaterialTemplate} template
+ * @returns {PipelineLayoutDescriptor}
+ */
+export function alpha_tested_pipeline_layout(template: ShadeMaterialTemplate): PipelineLayoutDescriptor;
+/**
+ * @typedef {import("../../material/template/ShadeMaterialTemplate.js").ShadeMaterialTemplate} ShadeMaterialTemplate
+ */
 export const RASTERIZATION_SHADER_BIND_GROUP_MATERIAL: 0;
 export const RASTERIZATION_SHADER_BIND_GROUP_SCENE: 1;
 export const RASTERIZATION_SHADER_BIND_GROUP_VIEW: 2;
-export const alpha_tested_pass_resources: ShaderResourceSetDescriptor;
+/**
+ * Group 1 of every alpha-tested pipeline, whatever the template.
+ *
+ * `materials` is the metadata table: the vertex stage reads the side a material draws from it, per
+ * instance, the way the opaque raster already does — which is what takes group 0 out of the vertex
+ * stage, so the template's own group 0, fragment-only, can be bound here as it is in the G-buffer
+ * pass.
+ *
+ * Vertex-only: nothing here is read by a fragment stage, and six storage buffers visible to the
+ * fragment stage would count against its storage-buffer limit next to whatever the template's group
+ * 0 declares.
+ *
+ * @type {ShaderResourceGroupDescriptor}
+ */
+export const ALPHA_TESTED_SCENE_GROUP: ShaderResourceGroupDescriptor;
+/**
+ * Group 2 of every alpha-tested pipeline, whatever the template.
+ *
+ * @type {ShaderResourceGroupDescriptor}
+ */
+export const ALPHA_TESTED_VIEW_GROUP: ShaderResourceGroupDescriptor;
+/**
+ * @type {BindGroupLayoutDescriptor}
+ */
+export const ALPHA_TESTED_SCENE_LAYOUT: BindGroupLayoutDescriptor;
+/**
+ * @type {BindGroupLayoutDescriptor}
+ */
+export const ALPHA_TESTED_VIEW_LAYOUT: BindGroupLayoutDescriptor;
+/**
+ * What the alpha-tested vertex stages declare: nothing at group 0, which is the template's and
+ * fragment-only.
+ *
+ * @type {ShaderResourceSetDescriptor}
+ */
+export const alpha_tested_vertex_resources: ShaderResourceSetDescriptor;
+export type ShadeMaterialTemplate = import("../../material/template/ShadeMaterialTemplate.js").ShadeMaterialTemplate;
 import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import { PipelineLayoutDescriptor } from "../../../descriptor/pipeline/PipelineLayoutDescriptor.js";
+import { ShaderResourceGroupDescriptor } from "../../shader/resource/ShaderResourceGroupDescriptor.js";
 //# sourceMappingURL=alpha_tested_pass_resources.d.ts.map

package/src/shade/renderer/rasterize/native/alpha_tested_pass_resources.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"alpha_tested_pass_resources.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/rasterize/native/alpha_tested_pass_resources.js"],"names":[],"mappings":"AAWA,yDAA0D;AAC1D,sDAAuD;AACvD,qDAAsD;AAEtD,sEAA6E;4CAXjC,sDAAsD"}
+{"version":3,"file":"alpha_tested_pass_resources.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/rasterize/native/alpha_tested_pass_resources.js"],"names":[],"mappings":"AAkGA;;;;;;GAMG;AACH,0DAHW,qBAAqB,GACnB,2BAA2B,CAgBvC;AAED;;;;;;;GAOG;AACH,uDAHW,qBAAqB,GACnB,wBAAwB,CAQpC;AAzHD;;GAEG;AAEH,yDAA0D;AAC1D,sDAAuD;AACvD,qDAAsD;AAEtD;;;;;;;;;;;;;GAaG;AACH,uCAFU,6BAA6B,CAEqC;AAe5E;;;;GAIG;AACH,sCAFU,6BAA6B,CAEoC;AAY3E;;GAEG;AACH,kEAAsG;AAEtG;;GAEG;AACH,iEAAoG;AAEpG;;;;;GAKG;AACH,4CAFU,2BAA2B,CAE0C;oCArElE,OAAO,kDAAkD,EAAE,qBAAqB;4CARjD,sDAAsD;yCANzD,0DAA0D;8CAKrD,wDAAwD"}

package/src/shade/renderer/rasterize/native/alpha_tested_pass_resources.js

@@ -1,7 +1,10 @@
+import { GPUShaderStage } from "../../../descriptor/GPUShaderStage.js";
+import { PipelineLayoutDescriptor } from "../../../descriptor/pipeline/PipelineLayoutDescriptor.js";
 import { u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
 import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
 import { CAMERA_UNIFORM_STRUCT } from "../../camera/CAMERA_UNIFORM_STRUCT.js";
 import { MATERIAL_METADATA_STRUCT } from "../../material/MATERIAL_METADATA_STRUCT.js";
+import { ShaderResourceGroupDescriptor } from "../../shader/resource/ShaderResourceGroupDescriptor.js";
 import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
 import { VIEW_UNIFORM_STRUCT } from "../../view/VIEW_UNIFORM_STRUCT.js";
 import { GEOMETRY_ATTRIBUTE_DATA_TYPE } from "../../geometry/GEOMETRY_ATTRIBUTE_DATA_TYPE.js";
@@ -9,26 +12,125 @@ import { GEOMETRY_METADATA_STRUCT } from "../../geometry/GEOMETRY_METADATA_STRUC
 import { MESHLET_DEFINITION_STRUCT } from "../../geometry/meshlet/encoding/MESHLET_DEFINITION_STRUCT.js";
 import { MESHLET_METADATA_STRUCT } from "../../geometry/meshlet/encoding/MESHLET_METADATA_STRUCT.js";
 
+/**
+ * @typedef {import("../../material/template/ShadeMaterialTemplate.js").ShadeMaterialTemplate} ShadeMaterialTemplate
+ */
+
 export const RASTERIZATION_SHADER_BIND_GROUP_MATERIAL = 0;
 export const RASTERIZATION_SHADER_BIND_GROUP_SCENE = 1;
 export const RASTERIZATION_SHADER_BIND_GROUP_VIEW = 2;
 
-export const alpha_tested_pass_resources = new ShaderResourceSetDescriptor();
+/**
+ * Group 1 of every alpha-tested pipeline, whatever the template.
+ *
+ * `materials` is the metadata table: the vertex stage reads the side a material draws from it, per
+ * instance, the way the opaque raster already does — which is what takes group 0 out of the vertex
+ * stage, so the template's own group 0, fragment-only, can be bound here as it is in the G-buffer
+ * pass.
+ *
+ * Vertex-only: nothing here is read by a fragment stage, and six storage buffers visible to the
+ * fragment stage would count against its storage-buffer limit next to whatever the template's group
+ * 0 declares.
+ *
+ * @type {ShaderResourceGroupDescriptor}
+ */
+export const ALPHA_TESTED_SCENE_GROUP = new ShaderResourceGroupDescriptor();
 
-alpha_tested_pass_resources.createGroup({ index: RASTERIZATION_SHADER_BIND_GROUP_MATERIAL, label: "material" })
-    .addTexture("t_color", "float")
-    .addSampler("t_color_sampler", "filtering")
-    .addUniform("material", MATERIAL_METADATA_STRUCT);
+ALPHA_TESTED_SCENE_GROUP.label = "scene";
 
-alpha_tested_pass_resources.createGroup({ index: RASTERIZATION_SHADER_BIND_GROUP_SCENE, label: "scene" })
+ALPHA_TESTED_SCENE_GROUP
     .addStorageBuffer("meshlets", WebGPUArray.from(MESHLET_DEFINITION_STRUCT))
     .addStorageBuffer("meshlet_metadata", WebGPUArray.from(MESHLET_METADATA_STRUCT))
     .addStorageBuffer("meshlet_data", GEOMETRY_ATTRIBUTE_DATA_TYPE)
     .addStorageBuffer("scene_database", WebGPUArray.from(u32))
     .addStorageBuffer("geometries", WebGPUArray.from(GEOMETRY_METADATA_STRUCT))
+    .addStorageBuffer("materials", WebGPUArray.from(MATERIAL_METADATA_STRUCT))
+;
+
+ALPHA_TESTED_SCENE_GROUP.addVisibility(GPUShaderStage.VERTEX);
+
+/**
+ * Group 2 of every alpha-tested pipeline, whatever the template.
+ *
+ * @type {ShaderResourceGroupDescriptor}
+ */
+export const ALPHA_TESTED_VIEW_GROUP = new ShaderResourceGroupDescriptor();
+
+ALPHA_TESTED_VIEW_GROUP.label = "view";
 
-alpha_tested_pass_resources.createGroup({ index: RASTERIZATION_SHADER_BIND_GROUP_VIEW, label: "view" })
+ALPHA_TESTED_VIEW_GROUP
     .addUniform("camera", CAMERA_UNIFORM_STRUCT)
     .addUniform("view", VIEW_UNIFORM_STRUCT)
     .addTexture("t_noise", "uint")
 ;
+
+ALPHA_TESTED_VIEW_GROUP.addVisibility(GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT);
+
+/**
+ * @type {BindGroupLayoutDescriptor}
+ */
+export const ALPHA_TESTED_SCENE_LAYOUT = ALPHA_TESTED_SCENE_GROUP.generateBindGroupLayoutDescriptor();
+
+/**
+ * @type {BindGroupLayoutDescriptor}
+ */
+export const ALPHA_TESTED_VIEW_LAYOUT = ALPHA_TESTED_VIEW_GROUP.generateBindGroupLayoutDescriptor();
+
+/**
+ * What the alpha-tested vertex stages declare: nothing at group 0, which is the template's and
+ * fragment-only.
+ *
+ * @type {ShaderResourceSetDescriptor}
+ */
+export const alpha_tested_vertex_resources = new ShaderResourceSetDescriptor();
+
+alpha_tested_vertex_resources.createGroup({
+    index: RASTERIZATION_SHADER_BIND_GROUP_MATERIAL,
+    label: "material (fragment only)"
+});
+alpha_tested_vertex_resources.addGroup(ALPHA_TESTED_SCENE_GROUP);
+alpha_tested_vertex_resources.addGroup(ALPHA_TESTED_VIEW_GROUP);
+
+/**
+ * @type {WeakMap<ShadeMaterialTemplate, ShaderResourceSetDescriptor>}
+ */
+const fragment_resources = new WeakMap();
+
+/**
+ * What a template's alpha-tested fragment stage declares: the template's group 0, then the passes'
+ * groups 1 and 2.
+ *
+ * @param {ShadeMaterialTemplate} template
+ * @returns {ShaderResourceSetDescriptor}
+ */
+export function alpha_tested_fragment_resources(template) {
+    let resources = fragment_resources.get(template);
+
+    if (resources === undefined) {
+        resources = new ShaderResourceSetDescriptor();
+
+        resources.addGroup(template.resources);
+        resources.addGroup(ALPHA_TESTED_SCENE_GROUP);
+        resources.addGroup(ALPHA_TESTED_VIEW_GROUP);
+
+        fragment_resources.set(template, resources);
+    }
+
+    return resources;
+}
+
+/**
+ * The layout of a template's alpha-tested pipelines. Group 0 is laid out exactly as it is in the
+ * template's G-buffer pipeline — same descriptor, same visibility — so the layout manager hands
+ * both the same bind group layout and one bind group per material serves every pass.
+ *
+ * @param {ShadeMaterialTemplate} template
+ * @returns {PipelineLayoutDescriptor}
+ */
+export function alpha_tested_pipeline_layout(template) {
+    return PipelineLayoutDescriptor.from([
+        template.resources.generateBindGroupLayoutDescriptor(),
+        ALPHA_TESTED_SCENE_LAYOUT,
+        ALPHA_TESTED_VIEW_LAYOUT,
+    ]);
+}

package/src/shade/renderer/rasterize/native/avboit/AVBOITSideChannel.d.ts

@@ -1,6 +1,7 @@
 /**
  * A source of transparent fragments that is not a meshlet bucket, drawn through the AVBOIT pipeline
- * alongside the transparent meshes: particles today, anything quad- or point-shaped tomorrow.
+ * alongside the transparent meshes: the GPU particles (`GPUParticleSystem`), the dynamic meshes a
+ * system registers (`DynamicMeshAVBOITChannel` — the trails), anything quad- or point-shaped tomorrow.
  *
  * The orchestrator (`graph_rasterize_meshes_transparent_avboit`) collects three things from every
  * transparent surface in the frame, in this order, and a side channel is asked for each at the
@@ -23,6 +24,14 @@
  * Every method takes the frame graph and the handles the orchestrator currently holds, and returns
  * the handles the next reader must take — the frame-graph threading rule, unchanged. A channel with
  * nothing to add returns what it was given.
+ *
+ * A channel may also say, before the frame records, that it has nothing to add at all
+ * (`avboit_is_empty`). The orchestrator runs whenever it is handed a channel, even with no
+ * transparent material in the scene; a channel that is always registered but usually empty — a
+ * system's, from outside the renderer — would otherwise buy every frame the pipeline's fixed cost.
+ * The renderer leaves a channel that says it is empty out of that frame's list, and asks registered
+ * channels nothing at all with transparency off or under MBOIT, which takes no side channels. A
+ * channel without the method is always asked.
  */
 export type AVBOITSideChannel = {
     /**
@@ -83,5 +92,11 @@ export type AVBOITSideChannel = {
         extinction: number;
         emission: number;
     };
+    /**
+     * whether the channel would add nothing this frame;
+     * asked before the orchestrator records, and a channel that answers `true` is not asked for
+     * anything else in that frame.
+     */
+    avboit_is_empty?: () => boolean;
 };
 //# sourceMappingURL=AVBOITSideChannel.d.ts.map

package/src/shade/renderer/rasterize/native/avboit/AVBOITSideChannel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AVBOITSideChannel.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/rasterize/native/avboit/AVBOITSideChannel.js"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;sBA2Bc,CAAC,IAAI,EAAE;QACpB,KAAW,EAAE,OAAO,iEAAiE,EAAE,UAAU,CAAC;QAClG,MAAY,EAAE,MAAM,CAAC;QACrB,kBAAwB,EAAE,UAAU,MAAM,CAAC,CAAC;QAC5C,SAAe,EAAE,MAAM,CAAC;KACrB,KAAK,MAAM;;;;;;;;kBAED,CAAC,IAAI,EAAE;QACpB,KAAW,EAAE,OAAO,iEAAiE,EAAE,UAAU,CAAC;QAClG,MAAY,EAAE,MAAM,CAAC;QACrB,IAAU,EAAE,MAAM,CAAC;QACnB,aAAmB,EAAE,MAAM,CAAC;QAC5B,gBAAsB,EAAE,MAAM,EAAE,CAAC;QACjC,MAAY,EAAE;YAAC,UAAU,EAAE,MAAM,CAAC;YAAC,QAAQ,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAC,CAAC;KACjE,KAAK;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAC;;;;;iBAKhD,CAAC,IAAI,EAAE;QACpB,KAAW,EAAE,OAAO,iEAAiE,EAAE,UAAU,CAAC;QAClG,QAAc,EAAE,OAAO,iCAAiC,EAAE,cAAc,CAAC;QACzE,MAAY,EAAE,MAAM,CAAC;QACrB,aAAmB,EAAE,MAAM,CAAC;QAC5B,IAAU,EAAE,MAAM,CAAC;QACnB,QAAc,EAAE,MAAM,CAAC;QACvB,eAAqB,EAAE,MAAM,CAAC;QAC9B,oBAA0B,EAAE,MAAM,CAAC;QACnC,YAAkB,EAAE;YAAC,KAAK,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAC;YAAC,UAAU,EAAE,MAAM,CAAC;YAAC,QAAQ,EAAE,MAAM,CAAA;SAAC,CAAC;KACrF,KAAK;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAC"}
+{"version":3,"file":"AVBOITSideChannel.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/rasterize/native/avboit/AVBOITSideChannel.js"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;sBAoCc,CAAC,IAAI,EAAE;QACpB,KAAW,EAAE,OAAO,iEAAiE,EAAE,UAAU,CAAC;QAClG,MAAY,EAAE,MAAM,CAAC;QACrB,kBAAwB,EAAE,UAAU,MAAM,CAAC,CAAC;QAC5C,SAAe,EAAE,MAAM,CAAC;KACrB,KAAK,MAAM;;;;;;;;kBAED,CAAC,IAAI,EAAE;QACpB,KAAW,EAAE,OAAO,iEAAiE,EAAE,UAAU,CAAC;QAClG,MAAY,EAAE,MAAM,CAAC;QACrB,IAAU,EAAE,MAAM,CAAC;QACnB,aAAmB,EAAE,MAAM,CAAC;QAC5B,gBAAsB,EAAE,MAAM,EAAE,CAAC;QACjC,MAAY,EAAE;YAAC,UAAU,EAAE,MAAM,CAAC;YAAC,QAAQ,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAC,CAAC;KACjE,KAAK;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAC;;;;;iBAKhD,CAAC,IAAI,EAAE;QACpB,KAAW,EAAE,OAAO,iEAAiE,EAAE,UAAU,CAAC;QAClG,QAAc,EAAE,OAAO,iCAAiC,EAAE,cAAc,CAAC;QACzE,MAAY,EAAE,MAAM,CAAC;QACrB,aAAmB,EAAE,MAAM,CAAC;QAC5B,IAAU,EAAE,MAAM,CAAC;QACnB,QAAc,EAAE,MAAM,CAAC;QACvB,eAAqB,EAAE,MAAM,CAAC;QAC9B,oBAA0B,EAAE,MAAM,CAAC;QACnC,YAAkB,EAAE;YAAC,KAAK,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAC;YAAC,UAAU,EAAE,MAAM,CAAC;YAAC,QAAQ,EAAE,MAAM,CAAA;SAAC,CAAC;KACrF,KAAK;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAC;;;;;;sBAE9D,MAAM,OAAO"}

package/src/shade/renderer/rasterize/native/avboit/AVBOITSideChannel.js

@@ -1,6 +1,7 @@
 /**
  * A source of transparent fragments that is not a meshlet bucket, drawn through the AVBOIT pipeline
- * alongside the transparent meshes: particles today, anything quad- or point-shaped tomorrow.
+ * alongside the transparent meshes: the GPU particles (`GPUParticleSystem`), the dynamic meshes a
+ * system registers (`DynamicMeshAVBOITChannel` — the trails), anything quad- or point-shaped tomorrow.
  *
  * The orchestrator (`graph_rasterize_meshes_transparent_avboit`) collects three things from every
  * transparent surface in the frame, in this order, and a side channel is asked for each at the
@@ -24,6 +25,14 @@
  * the handles the next reader must take — the frame-graph threading rule, unchanged. A channel with
  * nothing to add returns what it was given.
  *
+ * A channel may also say, before the frame records, that it has nothing to add at all
+ * (`avboit_is_empty`). The orchestrator runs whenever it is handed a channel, even with no
+ * transparent material in the scene; a channel that is always registered but usually empty — a
+ * system's, from outside the renderer — would otherwise buy every frame the pipeline's fixed cost.
+ * The renderer leaves a channel that says it is empty out of that frame's list, and asks registered
+ * channels nothing at all with transparency off or under MBOIT, which takes no side channels. A
+ * channel without the method is always asked.
+ *
  * @typedef {object} AVBOITSideChannel
  * @property {(args: {
  *     graph: import("../../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph,
@@ -56,6 +65,9 @@
  *     accumulators: {color: number, norm: number, extinction: number, emission: number},
  * }) => {color: number, norm: number, extinction: number, emission: number}} avboit_draw draw the
  *     channel's fragments into the accumulators; returns their handles after the draw.
+ * @property {() => boolean} [avboit_is_empty] whether the channel would add nothing this frame;
+ *     asked before the orchestrator records, and a channel that answers `true` is not asked for
+ *     anything else in that frame.
  */
 
 export {};