@codexo/exojs-particles 0.15.2 → 0.16.0

package/dist/esm/particlesExtension.js

@@ -1,49 +1,45 @@
-import { RenderBackendType } from '@codexo/exojs/renderer-sdk';
-import { WebGl2ParticleRenderer } from './renderers/WebGl2ParticleRenderer.js';
-import { WebGpuParticleRenderer } from './renderers/WebGpuParticleRenderer.js';
-import { ParticleSystem } from './ParticleSystem.js';
+import { WebGl2ParticleRenderer } from "./renderers/WebGl2ParticleRenderer.js";
+import { WebGpuParticleRenderer } from "./renderers/WebGpuParticleRenderer.js";
+import { ParticleSystem } from "./ParticleSystem.js";
+import { RenderBackendType } from "@codexo/exojs/renderer-sdk";
 
-function buildParticlesRendererBinding(batchSize) {
-    return {
-        targets: [ParticleSystem],
-        create(backend) {
-            if (backend.backendType === RenderBackendType.WebGl2) {
-                return new WebGl2ParticleRenderer(batchSize);
-            }
-            if (backend.backendType === RenderBackendType.WebGpu) {
-                return new WebGpuParticleRenderer();
-            }
-            throw new Error(`Unsupported render backend: ${String(backend.backendType)}`);
-        },
-    };
-}
+//#region src/particlesExtension.ts
+const buildParticlesRendererBinding = (batchSize) => ({
+	targets: [ParticleSystem],
+	create(backend) {
+		if (backend.backendType === RenderBackendType.WebGl2) return new WebGl2ParticleRenderer(batchSize);
+		if (backend.backendType === RenderBackendType.WebGpu) return new WebGpuParticleRenderer();
+		throw new Error(`Unsupported render backend: ${String(backend.backendType)}`);
+	}
+});
 /**
- * Default immutable Particles extension descriptor.
- * Use with `ApplicationOptions.extensions` or call
- * `import '@codexo/exojs-particles/register'` for global auto-registration.
- */
+* Default immutable Particles extension descriptor.
+* Pass it to the application that should have it via
+* `ApplicationOptions.extensions`.
+*/
 const particlesExtension = Object.freeze({
-    id: '@codexo/exojs-particles',
-    renderers: [buildParticlesRendererBinding(8192)],
+	id: "@codexo/exojs-particles",
+	renderers: [buildParticlesRendererBinding(8192)]
 });
 /**
- * Create a Particles extension with custom configuration.
- * Returns an application-local descriptor — safe to pass to one
- * `Application` only. For shared use, prefer {@link particlesExtension}.
- *
- * @example
- * ```ts
- * const ext = createParticlesExtension({ batchSize: 4096 });
- * const app = new Application({ extensions: [ext] });
- * ```
- */
-function createParticlesExtension(options = {}) {
-    const batchSize = options.batchSize ?? 8192;
-    return {
-        id: '@codexo/exojs-particles',
-        renderers: [buildParticlesRendererBinding(batchSize)],
-    };
-}
+* Create a Particles extension with custom configuration.
+* Returns an application-local descriptor - safe to pass to one
+* `Application` only. For shared use, prefer {@link particlesExtension}.
+*
+* @example
+* ```ts
+* const ext = createParticlesExtension({ batchSize: 4096 });
+* const app = new Application({ extensions: [ext] });
+* ```
+*/
+const createParticlesExtension = (options = {}) => {
+	const batchSize = options.batchSize ?? 8192;
+	return {
+		id: "@codexo/exojs-particles",
+		renderers: [buildParticlesRendererBinding(batchSize)]
+	};
+};
 
+//#endregion
 export { createParticlesExtension, particlesExtension };
-//# sourceMappingURL=particlesExtension.js.map
+//# sourceMappingURL=particlesExtension.js.map

package/dist/esm/particlesExtension.js.map

@@ -1 +1 @@
-{"version":3,"file":"particlesExtension.js","sources":["../../../src/particlesExtension.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;;AAeA,SAAS,6BAA6B,CAAC,SAAiB,EAAA;IACtD,OAAO;QACL,OAAO,EAAE,CAAC,cAAc,CAAC;AACzB,QAAA,MAAM,CAAC,OAAsB,EAAA;YAC3B,IAAI,OAAO,CAAC,WAAW,KAAK,iBAAiB,CAAC,MAAM,EAAE;AACpD,gBAAA,OAAO,IAAI,sBAAsB,CAAC,SAAS,CAAC;YAC9C;YAEA,IAAI,OAAO,CAAC,WAAW,KAAK,iBAAiB,CAAC,MAAM,EAAE;gBACpD,OAAO,IAAI,sBAAsB,EAAE;YACrC;AAEA,YAAA,MAAM,IAAI,KAAK,CAAC,CAAA,4BAAA,EAA+B,MAAM,CAAC,OAAO,CAAC,WAA2B,CAAC,CAAA,CAAE,CAAC;QAC/F,CAAC;KACF;AACH;AAEA;;;;AAIG;AACI,MAAM,kBAAkB,GAAc,MAAM,CAAC,MAAM,CAAC;AACzD,IAAA,EAAE,EAAE,yBAAyB;AAC7B,IAAA,SAAS,EAAE,CAAC,6BAA6B,CAAC,IAAI,CAAC,CAAC;AACjD,CAAA;AAED;;;;;;;;;;AAUG;AACG,SAAU,wBAAwB,CAAC,OAAA,GAAqC,EAAE,EAAA;AAC9E,IAAA,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,IAAI;IAE3C,OAAO;AACL,QAAA,EAAE,EAAE,yBAAyB;AAC7B,QAAA,SAAS,EAAE,CAAC,6BAA6B,CAAC,SAAS,CAAC,CAAC;KACtD;AACH;;;;"}
+{"version":3,"file":"particlesExtension.js","names":[],"sources":["../../src/particlesExtension.ts"],"sourcesContent":["import type { Extension, RendererBinding } from '@codexo/exojs/extensions';\nimport type { RenderBackend } from '@codexo/exojs/renderer-sdk';\nimport { RenderBackendType } from '@codexo/exojs/renderer-sdk';\n\nimport { WebGl2ParticleRenderer } from '#renderers/WebGl2ParticleRenderer';\nimport { WebGpuParticleRenderer } from '#renderers/WebGpuParticleRenderer';\n\nimport { ParticleSystem } from './ParticleSystem';\n\n/** Options for {@link createParticlesExtension}. */\nexport interface ParticlesExtensionOptions {\n  /**\n   * Particles the WebGL2 renderer's instance buffer is pre-sized for.\n   * Defaults to 8192.\n   *\n   * This is a starting allocation, not a limit: a system with more live\n   * particles grows the buffer instead of dropping the surplus, so raise it\n   * only to avoid the initial growth steps for a known-large system.\n   */\n  readonly batchSize?: number;\n}\n\nconst buildParticlesRendererBinding = (batchSize: number): RendererBinding => ({\n  targets: [ParticleSystem],\n  create(backend: RenderBackend) {\n    if (backend.backendType === RenderBackendType.WebGl2) {\n      return new WebGl2ParticleRenderer(batchSize);\n    }\n\n    if (backend.backendType === RenderBackendType.WebGpu) {\n      return new WebGpuParticleRenderer();\n    }\n\n    throw new Error(`Unsupported render backend: ${String(backend.backendType satisfies never)}`);\n  },\n});\n\n/**\n * Default immutable Particles extension descriptor.\n * Pass it to the application that should have it via\n * `ApplicationOptions.extensions`.\n */\nexport const particlesExtension: Extension = Object.freeze({\n  id: '@codexo/exojs-particles',\n  renderers: [buildParticlesRendererBinding(8192)],\n});\n\n/**\n * Create a Particles extension with custom configuration.\n * Returns an application-local descriptor - safe to pass to one\n * `Application` only. For shared use, prefer {@link particlesExtension}.\n *\n * @example\n * ```ts\n * const ext = createParticlesExtension({ batchSize: 4096 });\n * const app = new Application({ extensions: [ext] });\n * ```\n */\nexport const createParticlesExtension = (options: ParticlesExtensionOptions = {}): Extension => {\n  const batchSize = options.batchSize ?? 8192;\n\n  return {\n    id: '@codexo/exojs-particles',\n    renderers: [buildParticlesRendererBinding(batchSize)],\n  };\n};\n"],"mappings":";;;;;;AAsBA,MAAM,iCAAiC,eAAwC;CAC7E,SAAS,CAAC,cAAc;CACxB,OAAO,SAAwB;EAC7B,IAAI,QAAQ,gBAAgB,kBAAkB,QAC5C,OAAO,IAAI,uBAAuB,SAAS;EAG7C,IAAI,QAAQ,gBAAgB,kBAAkB,QAC5C,OAAO,IAAI,uBAAuB;EAGpC,MAAM,IAAI,MAAM,+BAA+B,OAAO,QAAQ,WAA2B,GAAG;CAC9F;AACF;;;;;;AAOA,MAAa,qBAAgC,OAAO,OAAO;CACzD,IAAI;CACJ,WAAW,CAAC,8BAA8B,IAAI,CAAC;AACjD,CAAC;;;;;;;;;;;;AAaD,MAAa,4BAA4B,UAAqC,CAAC,MAAiB;CAC9F,MAAM,YAAY,QAAQ,aAAa;CAEvC,OAAO;EACL,IAAI;EACJ,WAAW,CAAC,8BAA8B,SAAS,CAAC;CACtD;AACF"}

package/dist/esm/public.d.ts

@@ -4,6 +4,17 @@ export type { ParticlesBuildInfo } from './particlesBuildInfo';
 export { particlesBuildInfo } from './particlesBuildInfo';
 export type { ParticlesExtensionOptions } from './particlesExtension';
 export { createParticlesExtension, particlesExtension } from './particlesExtension';
+export type { ParticleBatch, ParticleDeathContext, ParticleEmitter, ParticleRotationChannel, ParticleTimingChannel, ParticleVectorChannel, ParticleVectorWriter, ParticleWriter, } from './ParticleStorage';
 export type { ParticleSystemOptions } from './ParticleSystem';
 export { ParticleSystem } from './ParticleSystem';
+export type { MeshParticlesOptions } from './renderModes/MeshParticles';
+export { MeshParticles } from './renderModes/MeshParticles';
+export type { ParticleBufferLayoutOptions } from './renderModes/ParticleBufferLayout';
+export { ParticleBufferLayout } from './renderModes/ParticleBufferLayout';
+export { ParticleMaterial } from './renderModes/ParticleMaterial';
+export { ParticleRenderMode } from './renderModes/ParticleRenderMode';
+export { QuadParticles } from './renderModes/QuadParticles';
+export type { RibbonParticlesOptions } from './renderModes/RibbonParticles';
+export { RibbonParticles } from './renderModes/RibbonParticles';
 export type { Extension, RendererBinding } from '@codexo/exojs/extensions';
+//# sourceMappingURL=public.d.ts.map

package/dist/esm/public.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"public.d.ts","sourceRoot":"","sources":["../../src/public.ts"],"names":[],"mappings":"AAGA,cAAc,iBAAiB,CAAC;AAChC,cAAc,WAAW,CAAC;AAC1B,YAAY,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC/D,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,YAAY,EAAE,yBAAyB,EAAE,MAAM,sBAAsB,CAAC;AACtE,OAAO,EAAE,wBAAwB,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AACpF,YAAY,EACV,aAAa,EACb,oBAAoB,EACpB,eAAe,EACf,uBAAuB,EACvB,qBAAqB,EACrB,qBAAqB,EACrB,oBAAoB,EACpB,cAAc,GACf,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAC9D,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,YAAY,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACxE,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAC5D,YAAY,EAAE,2BAA2B,EAAE,MAAM,oCAAoC,CAAC;AACtF,OAAO,EAAE,oBAAoB,EAAE,MAAM,oCAAoC,CAAC;AAC1E,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAClE,OAAO,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AACtE,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAC5D,YAAY,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AAC5E,OAAO,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAChE,YAAY,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/esm/renderModes/MeshParticles.d.ts

@@ -0,0 +1,128 @@
+import type { Material } from '@codexo/exojs';
+import { Geometry } from '@codexo/exojs';
+import type { ParticleBatch } from '#ParticleStorage';
+import type { ParticleSystem } from '#ParticleSystem';
+import { ParticleBufferLayout } from './ParticleBufferLayout';
+import { ParticleRenderMode } from './ParticleRenderMode';
+/** Construction options for {@link MeshParticles}. */
+export interface MeshParticlesOptions {
+    /**
+     * The shape one particle draws, in system-local units before the
+     * per-particle scale and rotation are applied.
+     *
+     * Its position attribute (`a_position`/`position`) supplies the vertex
+     * positions and its texcoord attribute (`a_texcoord`/`texcoord`/`a_uv`/`uv`)
+     * the UVs. See {@link MeshParticles} for what a geometry without the latter
+     * renders as, and for how to make a mutation take effect.
+     */
+    readonly geometry: Geometry;
+}
+/**
+ * WGSL counterpart of `shaders/mesh.vert` plus the quad's fragment stage. Vertex
+ * and fragment entry points share one source per WGSL convention. The
+ * per-instance attributes bind at `@location(0..5)`, matching the declaration
+ * order and byte offsets of {@link instanceAttributes}, and the mesh's own
+ * vertices follow at `@location(6..7)` from the second vertex buffer.
+ *
+ * The uniform struct is the one the WebGPU particle renderer writes for every
+ * mode, so `localBounds` and `uvBounds` are declared but unused here: a mesh
+ * carries its own local footprint rather than taking it from the texture frame.
+ */
+export declare const meshParticleWgsl: string;
+/**
+ * One caller-supplied mesh per particle, drawn as a single instanced draw.
+ *
+ * The cheap counterpart to `RibbonParticles`: the relationship stays one
+ * particle, one instance, and the per-instance data is byte-identical to
+ * `QuadParticles`'s - {@link instanceAttributes}, filled by the same
+ * writer. Only the shape changes. That is what makes this mode **GPU-eligible**
+ * without touching the compute pipeline: the pipeline emits precisely that
+ * layout, so a system on the GPU path binds its instance buffer directly and
+ * never calls {@link build}.
+ *
+ * **The mesh rides in its own vertex buffer**, alongside the per-instance one.
+ * The shader is fixed and shared, so any number of `MeshParticles` compile one
+ * program per backend regardless of how many distinct shapes they draw, and a
+ * mesh is limited only by what a vertex buffer holds.
+ *
+ * **Mutating the mesh works.** Its vertices are read into a normalised
+ * `(x, y, u, v)` table - the shader binds fixed names, a caller's geometry may
+ * use any - and re-read whenever the geometry's `version` changes. Edit the
+ * geometry in place, call `invalidate()` on it, and the next draw picks it up.
+ * Changing the vertex *count* is equally fine.
+ *
+ * **Atlas frames still work.** The mesh's own UVs are treated exactly like the
+ * quad's 0..1 corners: the shader mixes them across the particle's resolved
+ * frame (`uv = mix(uvMin, uvMax, meshUV)`), so `system.frames` plus a
+ * per-particle `textureIndex` selects a frame the same way. A geometry with
+ * **no texcoord attribute** therefore carries UV `(0, 0)` on every vertex and
+ * the mix degenerates to `uvMin` - the whole mesh samples the single texel at
+ * the frame's top-left corner, which on the default 1×1 white texture is
+ * exactly "untextured, tinted by the particle's `color`".
+ *
+ * **Sizing is the mesh's own.** Unlike the quad, which derives its footprint
+ * from the texture frame, a mesh particle's footprint is whatever its vertex
+ * positions say, in system-local units, multiplied by the per-particle
+ * `scaleX`/`scaleY`. The texture only supplies colour.
+ *
+ * @example
+ * const shard = new Geometry({
+ *     attributes: [
+ *         { name: 'a_position', size: 2, type: 'f32', normalized: false, offset: 0 },
+ *         { name: 'a_uv', size: 2, type: 'f32', normalized: false, offset: 8 },
+ *     ],
+ *     vertexData: new Float32Array([0, -8, 0.5, 0, 6, 6, 1, 1, -6, 6, 0, 1]),
+ *     stride: 16,
+ * });
+ *
+ * const debris = new ParticleSystem(rockTexture, {
+ *     capacity: 512,
+ *     render: new MeshParticles({ geometry: shard }),
+ * });
+ *
+ * debris.addUpdateModule(new RotateOverLifetime(180)); // each shard tumbles
+ */
+export declare class MeshParticles extends ParticleRenderMode {
+    readonly gpuEligible = true;
+    readonly instanced = true;
+    /**
+     * The geometry this mode was constructed with - the shape one particle
+     * draws. Owned by the caller: {@link destroy} leaves it alone, so one mesh
+     * can back several modes.
+     */
+    readonly mesh: Geometry;
+    /**
+     * The normalised mesh the executors bind as the per-vertex buffer: the
+     * caller's {@link mesh} reduced to `(x, y, u, v)` per vertex, keeping its
+     * topology and index list. Owned by this mode and disposed with it.
+     */
+    readonly vertexGeometry: Geometry;
+    /** Per-instance layout, byte-identical to the quad's and to the compute output. */
+    readonly dataLayout: ParticleBufferLayout;
+    private readonly _writer;
+    private _meshTable;
+    private _meshVersion;
+    private _material;
+    private _float32;
+    private _uint32;
+    constructor(options: MeshParticlesOptions);
+    /**
+     * Built on first read rather than in the constructor: a system may be
+     * simulated without ever being drawn, and the shader pair is only needed
+     * once a backend actually compiles it.
+     */
+    get material(): Material;
+    build(system: ParticleSystem, particles: ParticleBatch): void;
+    destroy(): void;
+    protected _onBufferGrown(data: ArrayBuffer): void;
+    /**
+     * Re-read the caller's mesh when it has been mutated since the last look.
+     *
+     * Re-runs from {@link build} rather than from a draw so it also happens for a
+     * system whose backend has not compiled a pipeline yet. A vertex count change
+     * swaps the table, which is why the geometry's own `vertexData` is reassigned
+     * rather than written through - the executors notice via its `version`.
+     */
+    private _syncMesh;
+}
+//# sourceMappingURL=MeshParticles.d.ts.map

package/dist/esm/renderModes/MeshParticles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MeshParticles.d.ts","sourceRoot":"","sources":["../../../src/renderModes/MeshParticles.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAoC,QAAQ,EAAE,MAAM,eAAe,CAAC;AAChF,OAAO,EAAE,QAAQ,EAAgB,MAAM,eAAe,CAAC;AAEvD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAGtD,OAAO,EAAkC,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAG9F,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AA6B1D,sDAAsD;AACtD,MAAM,WAAW,oBAAoB;IACnC;;;;;;;;OAQG;IACH,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;CAC7B;AA2ED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAA+B,CAAC;AAE/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,qBAAa,aAAc,SAAQ,kBAAkB;IACnD,SAAyB,WAAW,QAAQ;IAC5C,SAAgB,SAAS,QAAQ;IAEjC;;;;OAIG;IACH,SAAgB,IAAI,EAAE,QAAQ,CAAC;IAE/B;;;;OAIG;IACH,SAAyB,cAAc,EAAE,QAAQ,CAAC;IAElD,mFAAmF;IACnF,SAAgB,UAAU,uBAIvB;IAEH,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgC;IAExD,OAAO,CAAC,UAAU,CAAe;IACjC,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,SAAS,CAAiC;IAClD,OAAO,CAAC,QAAQ,CAA+B;IAC/C,OAAO,CAAC,OAAO,CAA8B;gBAE1B,OAAO,EAAE,oBAAoB;IAoBhD;;;;OAIG;IACH,IAAW,QAAQ,IAAI,QAAQ,CAS9B;IAEM,KAAK,CAAC,MAAM,EAAE,cAAc,EAAE,SAAS,EAAE,aAAa,GAAG,IAAI;IAUpD,OAAO,IAAI,IAAI;cAMZ,cAAc,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI;IAK1D;;;;;;;OAOG;IACH,OAAO,CAAC,SAAS;CAgBlB"}

package/dist/esm/renderModes/MeshParticles.js

@@ -0,0 +1,263 @@
+import { ParticleBufferLayout, assertVertexGeometryCompatible } from "./ParticleBufferLayout.js";
+import particle_default from "../renderers/shaders/particle.frag.js";
+import { ParticleInstanceWriter, instanceAttributes } from "./ParticleInstanceWriter.js";
+import { ParticleMaterial } from "./ParticleMaterial.js";
+import { ParticleRenderMode } from "./ParticleRenderMode.js";
+import mesh_default from "./shaders/mesh.vert.js";
+import mesh_particles_default from "./shaders/mesh-particles.wgsl.js";
+import { Geometry, ShaderSource } from "@codexo/exojs";
+
+//#region src/renderModes/MeshParticles.ts
+/** Floats one entry of the normalised mesh vertex table occupies: x, y, u, v. */
+const floatsPerMeshVertex = 4;
+const meshVertexStrideBytes = floatsPerMeshVertex * Float32Array.BYTES_PER_ELEMENT;
+/**
+* Layout the normalised mesh table is read back with. Named apart from the
+* per-instance attributes because both sets bind into the same shader.
+*/
+const meshVertexAttributes = [{
+	name: "a_meshPosition",
+	size: 2,
+	type: "f32",
+	normalized: false,
+	offset: 0
+}, {
+	name: "a_meshTexcoord",
+	size: 2,
+	type: "f32",
+	normalized: false,
+	offset: 8
+}];
+const componentByteSizes = {
+	f32: 4,
+	u8: 1,
+	u16: 2,
+	u32: 4,
+	i32: 4
+};
+const positionAttributeNames = /* @__PURE__ */ new Set(["a_position", "position"]);
+const texcoordAttributeNames = /* @__PURE__ */ new Set([
+	"a_texcoord",
+	"texcoord",
+	"a_uv",
+	"uv"
+]);
+/** Read one component of `attribute`, applying its normalisation. */
+const readComponent = (view, attribute, byteOffset) => {
+	switch (attribute.type) {
+		case "f32": return view.getFloat32(byteOffset, true);
+		case "u8": {
+			const value = view.getUint8(byteOffset);
+			return attribute.normalized ? value / 255 : value;
+		}
+		case "u16": {
+			const value = view.getUint16(byteOffset, true);
+			return attribute.normalized ? value / 65535 : value;
+		}
+		case "u32": {
+			const value = view.getUint32(byteOffset, true);
+			return attribute.normalized ? value / 4294967295 : value;
+		}
+		case "i32": {
+			const value = view.getInt32(byteOffset, true);
+			return attribute.normalized ? Math.max(value / 2147483647, -1) : value;
+		}
+	}
+};
+/**
+* Read a mesh geometry's (x, y, u, v) per vertex into one flat table.
+*
+* The shader this mode ships is fixed, so it binds fixed attribute names and a
+* fixed stride, while a caller's mesh may declare any names in any supported
+* types. Normalising here is what lets one compiled program serve every mesh.
+*
+* `Geometry` guarantees a position attribute exists - it resolves one in its
+* own constructor and throws otherwise - so the same resolution order is
+* mirrored here rather than re-validated. A geometry without a texcoord
+* attribute leaves the UV columns at zero.
+*
+* @param out Table to fill; a new one is allocated when it is the wrong size,
+*   so a re-read after an in-place mutation reuses the existing allocation.
+*/
+const readMeshTable = (mesh, out = null) => {
+	const { attributes, stride, vertexData } = mesh;
+	const vertexCount = mesh.vertexCount;
+	const table = out !== null && out.length === vertexCount * floatsPerMeshVertex ? out : new Float32Array(vertexCount * floatsPerMeshVertex);
+	const view = vertexData instanceof Float32Array ? new DataView(vertexData.buffer, vertexData.byteOffset, vertexData.byteLength) : new DataView(vertexData);
+	const position = attributes.find((attribute) => positionAttributeNames.has(attribute.name)) ?? attributes.find((attribute) => attribute.name.toLowerCase().includes("position"));
+	const texcoord = attributes.find((attribute) => texcoordAttributeNames.has(attribute.name)) ?? null;
+	for (let i = 0; i < vertexCount; i++) {
+		const vertexStart = i * stride;
+		const target = i * floatsPerMeshVertex;
+		table[target + 0] = readComponent(view, position, vertexStart + position.offset);
+		table[target + 1] = readComponent(view, position, vertexStart + position.offset + componentByteSizes[position.type]);
+		if (texcoord !== null) {
+			table[target + 2] = readComponent(view, texcoord, vertexStart + texcoord.offset);
+			table[target + 3] = readComponent(view, texcoord, vertexStart + texcoord.offset + componentByteSizes[texcoord.type]);
+		} else {
+			table[target + 2] = 0;
+			table[target + 3] = 0;
+		}
+	}
+	return table;
+};
+/**
+* WGSL counterpart of `shaders/mesh.vert` plus the quad's fragment stage. Vertex
+* and fragment entry points share one source per WGSL convention. The
+* per-instance attributes bind at `@location(0..5)`, matching the declaration
+* order and byte offsets of {@link instanceAttributes}, and the mesh's own
+* vertices follow at `@location(6..7)` from the second vertex buffer.
+*
+* The uniform struct is the one the WebGPU particle renderer writes for every
+* mode, so `localBounds` and `uvBounds` are declared but unused here: a mesh
+* carries its own local footprint rather than taking it from the texture frame.
+*/
+const meshParticleWgsl = mesh_particles_default;
+/**
+* One caller-supplied mesh per particle, drawn as a single instanced draw.
+*
+* The cheap counterpart to `RibbonParticles`: the relationship stays one
+* particle, one instance, and the per-instance data is byte-identical to
+* `QuadParticles`'s - {@link instanceAttributes}, filled by the same
+* writer. Only the shape changes. That is what makes this mode **GPU-eligible**
+* without touching the compute pipeline: the pipeline emits precisely that
+* layout, so a system on the GPU path binds its instance buffer directly and
+* never calls {@link build}.
+*
+* **The mesh rides in its own vertex buffer**, alongside the per-instance one.
+* The shader is fixed and shared, so any number of `MeshParticles` compile one
+* program per backend regardless of how many distinct shapes they draw, and a
+* mesh is limited only by what a vertex buffer holds.
+*
+* **Mutating the mesh works.** Its vertices are read into a normalised
+* `(x, y, u, v)` table - the shader binds fixed names, a caller's geometry may
+* use any - and re-read whenever the geometry's `version` changes. Edit the
+* geometry in place, call `invalidate()` on it, and the next draw picks it up.
+* Changing the vertex *count* is equally fine.
+*
+* **Atlas frames still work.** The mesh's own UVs are treated exactly like the
+* quad's 0..1 corners: the shader mixes them across the particle's resolved
+* frame (`uv = mix(uvMin, uvMax, meshUV)`), so `system.frames` plus a
+* per-particle `textureIndex` selects a frame the same way. A geometry with
+* **no texcoord attribute** therefore carries UV `(0, 0)` on every vertex and
+* the mix degenerates to `uvMin` - the whole mesh samples the single texel at
+* the frame's top-left corner, which on the default 1×1 white texture is
+* exactly "untextured, tinted by the particle's `color`".
+*
+* **Sizing is the mesh's own.** Unlike the quad, which derives its footprint
+* from the texture frame, a mesh particle's footprint is whatever its vertex
+* positions say, in system-local units, multiplied by the per-particle
+* `scaleX`/`scaleY`. The texture only supplies colour.
+*
+* @example
+* const shard = new Geometry({
+*     attributes: [
+*         { name: 'a_position', size: 2, type: 'f32', normalized: false, offset: 0 },
+*         { name: 'a_uv', size: 2, type: 'f32', normalized: false, offset: 8 },
+*     ],
+*     vertexData: new Float32Array([0, -8, 0.5, 0, 6, 6, 1, 1, -6, 6, 0, 1]),
+*     stride: 16,
+* });
+*
+* const debris = new ParticleSystem(rockTexture, {
+*     capacity: 512,
+*     render: new MeshParticles({ geometry: shard }),
+* });
+*
+* debris.addUpdateModule(new RotateOverLifetime(180)); // each shard tumbles
+*/
+var MeshParticles = class extends ParticleRenderMode {
+	gpuEligible = true;
+	instanced = true;
+	/**
+	* The geometry this mode was constructed with - the shape one particle
+	* draws. Owned by the caller: {@link destroy} leaves it alone, so one mesh
+	* can back several modes.
+	*/
+	mesh;
+	/**
+	* The normalised mesh the executors bind as the per-vertex buffer: the
+	* caller's {@link mesh} reduced to `(x, y, u, v)` per vertex, keeping its
+	* topology and index list. Owned by this mode and disposed with it.
+	*/
+	vertexGeometry;
+	/** Per-instance layout, byte-identical to the quad's and to the compute output. */
+	dataLayout = new ParticleBufferLayout({
+		attributes: instanceAttributes,
+		stride: 40,
+		usage: "stream"
+	});
+	_writer = new ParticleInstanceWriter();
+	_meshTable;
+	_meshVersion;
+	_material = null;
+	_float32 = new Float32Array(this.data);
+	_uint32 = new Uint32Array(this.data);
+	constructor(options) {
+		super();
+		const mesh = options.geometry;
+		this.mesh = mesh;
+		this._meshTable = readMeshTable(mesh);
+		this._meshVersion = mesh.version;
+		this.vertexGeometry = new Geometry({
+			attributes: meshVertexAttributes,
+			vertexData: this._meshTable,
+			stride: meshVertexStrideBytes,
+			indices: mesh.indices,
+			topology: mesh.topology,
+			usage: mesh.usage
+		});
+		assertVertexGeometryCompatible(this.dataLayout, this.vertexGeometry, this.instanced, "MeshParticles");
+	}
+	/**
+	* Built on first read rather than in the constructor: a system may be
+	* simulated without ever being drawn, and the shader pair is only needed
+	* once a backend actually compiles it.
+	*/
+	get material() {
+		this._material ??= new ParticleMaterial({ shader: new ShaderSource({
+			glsl: {
+				vertex: mesh_default,
+				fragment: particle_default
+			},
+			wgsl: meshParticleWgsl
+		}) });
+		return this._material;
+	}
+	build(system, particles) {
+		this._syncMesh();
+		this._ensureCapacity(particles.count * 40);
+		this._setCount(this._writer.write(system, particles, this._float32, this._uint32));
+	}
+	destroy() {
+		this._material?.destroy();
+		this._material = null;
+		this.vertexGeometry.destroy();
+	}
+	_onBufferGrown(data) {
+		this._float32 = new Float32Array(data);
+		this._uint32 = new Uint32Array(data);
+	}
+	/**
+	* Re-read the caller's mesh when it has been mutated since the last look.
+	*
+	* Re-runs from {@link build} rather than from a draw so it also happens for a
+	* system whose backend has not compiled a pipeline yet. A vertex count change
+	* swaps the table, which is why the geometry's own `vertexData` is reassigned
+	* rather than written through - the executors notice via its `version`.
+	*/
+	_syncMesh() {
+		if (this._meshVersion === this.mesh.version) return;
+		this._meshVersion = this.mesh.version;
+		const table = readMeshTable(this.mesh, this._meshTable);
+		if (table !== this._meshTable) {
+			this._meshTable = table;
+			this.vertexGeometry.vertexData = table;
+		}
+		this.vertexGeometry.invalidate();
+	}
+};
+
+//#endregion
+export { MeshParticles, meshParticleWgsl };
+//# sourceMappingURL=MeshParticles.js.map

package/dist/esm/renderModes/MeshParticles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MeshParticles.js","names":["meshParticleWgslModule","vertexSource","fragmentSource"],"sources":["../../../src/renderModes/MeshParticles.ts"],"sourcesContent":["import type { AttributeType, GeometryAttribute, Material } from '@codexo/exojs';\nimport { Geometry, ShaderSource } from '@codexo/exojs';\n\nimport type { ParticleBatch } from '#ParticleStorage';\nimport type { ParticleSystem } from '#ParticleSystem';\n\nimport fragmentSource from '../renderers/shaders/particle.frag';\nimport { assertVertexGeometryCompatible, ParticleBufferLayout } from './ParticleBufferLayout';\nimport { instanceAttributes, instanceStrideBytes, ParticleInstanceWriter } from './ParticleInstanceWriter';\nimport { ParticleMaterial } from './ParticleMaterial';\nimport { ParticleRenderMode } from './ParticleRenderMode';\nimport vertexSource from './shaders/mesh.vert';\nimport meshParticleWgslModule from './shaders/mesh-particles.wgsl';\n\n/** Floats one entry of the normalised mesh vertex table occupies: x, y, u, v. */\nconst floatsPerMeshVertex = 4;\n\nconst meshVertexStrideBytes = floatsPerMeshVertex * Float32Array.BYTES_PER_ELEMENT;\n\n/**\n * Layout the normalised mesh table is read back with. Named apart from the\n * per-instance attributes because both sets bind into the same shader.\n */\nconst meshVertexAttributes: readonly GeometryAttribute[] = [\n  { name: 'a_meshPosition', size: 2, type: 'f32', normalized: false, offset: 0 },\n  { name: 'a_meshTexcoord', size: 2, type: 'f32', normalized: false, offset: 8 },\n];\n\nconst componentByteSizes: Record<AttributeType, number> = {\n  f32: 4,\n  u8: 1,\n  u16: 2,\n  u32: 4,\n  i32: 4,\n};\n\nconst positionAttributeNames = new Set<string>(['a_position', 'position']);\nconst texcoordAttributeNames = new Set<string>(['a_texcoord', 'texcoord', 'a_uv', 'uv']);\n\n/** Construction options for {@link MeshParticles}. */\nexport interface MeshParticlesOptions {\n  /**\n   * The shape one particle draws, in system-local units before the\n   * per-particle scale and rotation are applied.\n   *\n   * Its position attribute (`a_position`/`position`) supplies the vertex\n   * positions and its texcoord attribute (`a_texcoord`/`texcoord`/`a_uv`/`uv`)\n   * the UVs. See {@link MeshParticles} for what a geometry without the latter\n   * renders as, and for how to make a mutation take effect.\n   */\n  readonly geometry: Geometry;\n}\n\n/** Read one component of `attribute`, applying its normalisation. */\nconst readComponent = (view: DataView, attribute: GeometryAttribute, byteOffset: number): number => {\n  switch (attribute.type) {\n    case 'f32':\n      return view.getFloat32(byteOffset, true);\n    case 'u8': {\n      const value = view.getUint8(byteOffset);\n\n      return attribute.normalized ? value / 255 : value;\n    }\n    case 'u16': {\n      const value = view.getUint16(byteOffset, true);\n\n      return attribute.normalized ? value / 65535 : value;\n    }\n    case 'u32': {\n      const value = view.getUint32(byteOffset, true);\n\n      return attribute.normalized ? value / 4294967295 : value;\n    }\n    case 'i32': {\n      const value = view.getInt32(byteOffset, true);\n\n      return attribute.normalized ? Math.max(value / 2147483647, -1) : value;\n    }\n  }\n};\n\n/**\n * Read a mesh geometry's (x, y, u, v) per vertex into one flat table.\n *\n * The shader this mode ships is fixed, so it binds fixed attribute names and a\n * fixed stride, while a caller's mesh may declare any names in any supported\n * types. Normalising here is what lets one compiled program serve every mesh.\n *\n * `Geometry` guarantees a position attribute exists - it resolves one in its\n * own constructor and throws otherwise - so the same resolution order is\n * mirrored here rather than re-validated. A geometry without a texcoord\n * attribute leaves the UV columns at zero.\n *\n * @param out Table to fill; a new one is allocated when it is the wrong size,\n *   so a re-read after an in-place mutation reuses the existing allocation.\n */\nconst readMeshTable = (mesh: Geometry, out: Float32Array | null = null): Float32Array => {\n  const { attributes, stride, vertexData } = mesh;\n  const vertexCount = mesh.vertexCount;\n  const table = out !== null && out.length === vertexCount * floatsPerMeshVertex ? out : new Float32Array(vertexCount * floatsPerMeshVertex);\n  const view = vertexData instanceof Float32Array ? new DataView(vertexData.buffer, vertexData.byteOffset, vertexData.byteLength) : new DataView(vertexData);\n\n  const position =\n    attributes.find(attribute => positionAttributeNames.has(attribute.name)) ??\n    attributes.find(attribute => attribute.name.toLowerCase().includes('position'))!;\n  const texcoord = attributes.find(attribute => texcoordAttributeNames.has(attribute.name)) ?? null;\n\n  for (let i = 0; i < vertexCount; i++) {\n    const vertexStart = i * stride;\n    const target = i * floatsPerMeshVertex;\n\n    table[target + 0] = readComponent(view, position, vertexStart + position.offset);\n    table[target + 1] = readComponent(view, position, vertexStart + position.offset + componentByteSizes[position.type]);\n\n    if (texcoord !== null) {\n      table[target + 2] = readComponent(view, texcoord, vertexStart + texcoord.offset);\n      table[target + 3] = readComponent(view, texcoord, vertexStart + texcoord.offset + componentByteSizes[texcoord.type]);\n    } else {\n      table[target + 2] = 0;\n      table[target + 3] = 0;\n    }\n  }\n\n  return table;\n};\n\n/**\n * WGSL counterpart of `shaders/mesh.vert` plus the quad's fragment stage. Vertex\n * and fragment entry points share one source per WGSL convention. The\n * per-instance attributes bind at `@location(0..5)`, matching the declaration\n * order and byte offsets of {@link instanceAttributes}, and the mesh's own\n * vertices follow at `@location(6..7)` from the second vertex buffer.\n *\n * The uniform struct is the one the WebGPU particle renderer writes for every\n * mode, so `localBounds` and `uvBounds` are declared but unused here: a mesh\n * carries its own local footprint rather than taking it from the texture frame.\n */\nexport const meshParticleWgsl: string = meshParticleWgslModule;\n\n/**\n * One caller-supplied mesh per particle, drawn as a single instanced draw.\n *\n * The cheap counterpart to `RibbonParticles`: the relationship stays one\n * particle, one instance, and the per-instance data is byte-identical to\n * `QuadParticles`'s - {@link instanceAttributes}, filled by the same\n * writer. Only the shape changes. That is what makes this mode **GPU-eligible**\n * without touching the compute pipeline: the pipeline emits precisely that\n * layout, so a system on the GPU path binds its instance buffer directly and\n * never calls {@link build}.\n *\n * **The mesh rides in its own vertex buffer**, alongside the per-instance one.\n * The shader is fixed and shared, so any number of `MeshParticles` compile one\n * program per backend regardless of how many distinct shapes they draw, and a\n * mesh is limited only by what a vertex buffer holds.\n *\n * **Mutating the mesh works.** Its vertices are read into a normalised\n * `(x, y, u, v)` table - the shader binds fixed names, a caller's geometry may\n * use any - and re-read whenever the geometry's `version` changes. Edit the\n * geometry in place, call `invalidate()` on it, and the next draw picks it up.\n * Changing the vertex *count* is equally fine.\n *\n * **Atlas frames still work.** The mesh's own UVs are treated exactly like the\n * quad's 0..1 corners: the shader mixes them across the particle's resolved\n * frame (`uv = mix(uvMin, uvMax, meshUV)`), so `system.frames` plus a\n * per-particle `textureIndex` selects a frame the same way. A geometry with\n * **no texcoord attribute** therefore carries UV `(0, 0)` on every vertex and\n * the mix degenerates to `uvMin` - the whole mesh samples the single texel at\n * the frame's top-left corner, which on the default 1×1 white texture is\n * exactly \"untextured, tinted by the particle's `color`\".\n *\n * **Sizing is the mesh's own.** Unlike the quad, which derives its footprint\n * from the texture frame, a mesh particle's footprint is whatever its vertex\n * positions say, in system-local units, multiplied by the per-particle\n * `scaleX`/`scaleY`. The texture only supplies colour.\n *\n * @example\n * const shard = new Geometry({\n *     attributes: [\n *         { name: 'a_position', size: 2, type: 'f32', normalized: false, offset: 0 },\n *         { name: 'a_uv', size: 2, type: 'f32', normalized: false, offset: 8 },\n *     ],\n *     vertexData: new Float32Array([0, -8, 0.5, 0, 6, 6, 1, 1, -6, 6, 0, 1]),\n *     stride: 16,\n * });\n *\n * const debris = new ParticleSystem(rockTexture, {\n *     capacity: 512,\n *     render: new MeshParticles({ geometry: shard }),\n * });\n *\n * debris.addUpdateModule(new RotateOverLifetime(180)); // each shard tumbles\n */\nexport class MeshParticles extends ParticleRenderMode {\n  public override readonly gpuEligible = true;\n  public readonly instanced = true;\n\n  /**\n   * The geometry this mode was constructed with - the shape one particle\n   * draws. Owned by the caller: {@link destroy} leaves it alone, so one mesh\n   * can back several modes.\n   */\n  public readonly mesh: Geometry;\n\n  /**\n   * The normalised mesh the executors bind as the per-vertex buffer: the\n   * caller's {@link mesh} reduced to `(x, y, u, v)` per vertex, keeping its\n   * topology and index list. Owned by this mode and disposed with it.\n   */\n  public override readonly vertexGeometry: Geometry;\n\n  /** Per-instance layout, byte-identical to the quad's and to the compute output. */\n  public readonly dataLayout = new ParticleBufferLayout({\n    attributes: instanceAttributes,\n    stride: instanceStrideBytes,\n    usage: 'stream',\n  });\n\n  private readonly _writer = new ParticleInstanceWriter();\n\n  private _meshTable: Float32Array;\n  private _meshVersion: number;\n  private _material: ParticleMaterial | null = null;\n  private _float32 = new Float32Array(this.data);\n  private _uint32 = new Uint32Array(this.data);\n\n  public constructor(options: MeshParticlesOptions) {\n    super();\n\n    const mesh = options.geometry;\n\n    this.mesh = mesh;\n    this._meshTable = readMeshTable(mesh);\n    this._meshVersion = mesh.version;\n    this.vertexGeometry = new Geometry({\n      attributes: meshVertexAttributes,\n      vertexData: this._meshTable,\n      stride: meshVertexStrideBytes,\n      indices: mesh.indices,\n      topology: mesh.topology,\n      usage: mesh.usage,\n    });\n\n    assertVertexGeometryCompatible(this.dataLayout, this.vertexGeometry, this.instanced, 'MeshParticles');\n  }\n\n  /**\n   * Built on first read rather than in the constructor: a system may be\n   * simulated without ever being drawn, and the shader pair is only needed\n   * once a backend actually compiles it.\n   */\n  public get material(): Material {\n    this._material ??= new ParticleMaterial({\n      shader: new ShaderSource({\n        glsl: { vertex: vertexSource, fragment: fragmentSource },\n        wgsl: meshParticleWgsl,\n      }),\n    });\n\n    return this._material;\n  }\n\n  public build(system: ParticleSystem, particles: ParticleBatch): void {\n    this._syncMesh();\n\n    // Must precede the view reads below: growing swaps in fresh typed-array\n    // views over a new backing buffer.\n    this._ensureCapacity(particles.count * instanceStrideBytes);\n\n    this._setCount(this._writer.write(system, particles, this._float32, this._uint32));\n  }\n\n  public override destroy(): void {\n    this._material?.destroy();\n    this._material = null;\n    this.vertexGeometry.destroy();\n  }\n\n  protected override _onBufferGrown(data: ArrayBuffer): void {\n    this._float32 = new Float32Array(data);\n    this._uint32 = new Uint32Array(data);\n  }\n\n  /**\n   * Re-read the caller's mesh when it has been mutated since the last look.\n   *\n   * Re-runs from {@link build} rather than from a draw so it also happens for a\n   * system whose backend has not compiled a pipeline yet. A vertex count change\n   * swaps the table, which is why the geometry's own `vertexData` is reassigned\n   * rather than written through - the executors notice via its `version`.\n   */\n  private _syncMesh(): void {\n    if (this._meshVersion === this.mesh.version) {\n      return;\n    }\n\n    this._meshVersion = this.mesh.version;\n\n    const table = readMeshTable(this.mesh, this._meshTable);\n\n    if (table !== this._meshTable) {\n      this._meshTable = table;\n      this.vertexGeometry.vertexData = table;\n    }\n\n    this.vertexGeometry.invalidate();\n  }\n}\n"],"mappings":"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"}

package/dist/esm/renderModes/ParticleBufferLayout.d.ts

@@ -0,0 +1,59 @@
+import type { Geometry, GeometryAttribute, GeometryUsage, Topology } from '@codexo/exojs';
+/** Construction options for {@link ParticleBufferLayout}. */
+export interface ParticleBufferLayoutOptions {
+    /** Interleaved attributes, in declaration order. Shader locations follow this order. */
+    readonly attributes: readonly GeometryAttribute[];
+    /** Bytes one record occupies. Must be a positive integer. */
+    readonly stride: number;
+    /** Upload hint for the buffer this layout describes. Defaults to `stream`. */
+    readonly usage?: GeometryUsage;
+    /**
+     * Topology of the draw, used only when the mode declares no per-vertex
+     * geometry to take it from. Defaults to `triangle-list`.
+     */
+    readonly topology?: Topology;
+    /**
+     * Index list for the draw, used only when the mode declares no per-vertex
+     * geometry to take it from. Defaults to none.
+     */
+    readonly indices?: Uint16Array | Uint32Array | null;
+}
+/**
+ * Describes the interleaved buffer a render mode's `build()` fills each frame.
+ *
+ * Deliberately not a `Geometry`. A `Geometry` requires a position attribute,
+ * requires that attribute to carry at least two components, and validates any
+ * index list against the vertex count implied by its `vertexData` - three rules
+ * that are meaningful for geometry and meaningless for a per-instance record.
+ * Satisfying them used to cost the instanced modes a zero-filled placeholder
+ * buffer that was never uploaded, sized purely to keep the index check quiet.
+ *
+ * What is checked here is the subset that protects a real GPU binding: a
+ * positive stride, at least one attribute, unique names, and ranges that
+ * neither overlap each other nor reach past the stride.
+ *
+ * A layout is a description rather than a resource: it owns no GPU handle and
+ * needs no disposal.
+ */
+export declare class ParticleBufferLayout {
+    readonly attributes: readonly GeometryAttribute[];
+    readonly stride: number;
+    readonly usage: GeometryUsage;
+    readonly topology: Topology;
+    readonly indices: Uint16Array | Uint32Array | null;
+    constructor(options: ParticleBufferLayoutOptions);
+    /** Elements one draw consumes from {@link indices}, or 0 when there are none. */
+    get indexCount(): number;
+}
+/**
+ * Guard the two seam combinations a mode must not declare.
+ *
+ * Called by a mode's own constructor, so the error names the mistake where it
+ * was made, and repeated by each executor when it first realises a mode, so a
+ * mode written outside this package cannot slip past. Both checks are cheap and
+ * run once per mode rather than per frame.
+ *
+ * @param modeName Class name of the mode, used to prefix the error.
+ */
+export declare const assertVertexGeometryCompatible: (dataLayout: ParticleBufferLayout, vertexGeometry: Geometry | null, instanced: boolean, modeName: string) => void;
+//# sourceMappingURL=ParticleBufferLayout.d.ts.map

package/dist/esm/renderModes/ParticleBufferLayout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ParticleBufferLayout.d.ts","sourceRoot":"","sources":["../../../src/renderModes/ParticleBufferLayout.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAiB,QAAQ,EAAE,iBAAiB,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AA+DzG,6DAA6D;AAC7D,MAAM,WAAW,2BAA2B;IAC1C,wFAAwF;IACxF,QAAQ,CAAC,UAAU,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAElD,6DAA6D;IAC7D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB,8EAA8E;IAC9E,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC;IAE/B;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAE7B;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,WAAW,GAAG,WAAW,GAAG,IAAI,CAAC;CACrD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,oBAAoB;IAC/B,SAAgB,UAAU,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACzD,SAAgB,MAAM,EAAE,MAAM,CAAC;IAC/B,SAAgB,KAAK,EAAE,aAAa,CAAC;IACrC,SAAgB,QAAQ,EAAE,QAAQ,CAAC;IACnC,SAAgB,OAAO,EAAE,WAAW,GAAG,WAAW,GAAG,IAAI,CAAC;gBAEvC,OAAO,EAAE,2BAA2B;IA4BvD,iFAAiF;IACjF,IAAW,UAAU,IAAI,MAAM,CAE9B;CACF;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,8BAA8B,GACzC,YAAY,oBAAoB,EAChC,gBAAgB,QAAQ,GAAG,IAAI,EAC/B,WAAW,OAAO,EAClB,UAAU,MAAM,KACf,IAoBF,CAAC"}