@codexo/exojs-particles 0.15.3 → 0.16.0

package/dist/esm/renderModes/ParticleBufferLayout.js

@@ -0,0 +1,99 @@
+//#region src/renderModes/ParticleBufferLayout.ts
+const attributeTypeByteSizes = {
+	f32: 4,
+	u8: 1,
+	u16: 2,
+	u32: 4,
+	i32: 4
+};
+const validTopologies = /* @__PURE__ */ new Set(["triangle-list", "triangle-strip"]);
+const validUsages = /* @__PURE__ */ new Set([
+	"static",
+	"dynamic",
+	"stream"
+]);
+/**
+* Check that an attribute set describes a bindable interleaved record: unique
+* names, sane sizes and offsets, and ranges that neither overlap each other nor
+* reach past the stride.
+*/
+const validateAttributes = (attributes, stride) => {
+	const ranges = [];
+	const names = /* @__PURE__ */ new Set();
+	for (const attribute of attributes) {
+		if (typeof attribute.name !== "string" || attribute.name.length === 0) throw new Error("ParticleBufferLayout attribute name must be a non-empty string.");
+		if (names.has(attribute.name)) throw new Error(`ParticleBufferLayout attribute "${attribute.name}" is declared more than once.`);
+		names.add(attribute.name);
+		if (!Number.isInteger(attribute.size) || attribute.size === 0 || attribute.size > 4) throw new Error(`ParticleBufferLayout attribute "${attribute.name}" size must be an integer in [1..4] (got ${attribute.size}).`);
+		if (!Number.isInteger(attribute.offset) || attribute.offset < 0) throw new Error(`ParticleBufferLayout attribute "${attribute.name}" offset must be a non-negative integer (got ${attribute.offset}).`);
+		const end = attribute.offset + attributeTypeByteSizes[attribute.type] * attribute.size;
+		if (end > stride) throw new Error(`ParticleBufferLayout attribute "${attribute.name}" range [${attribute.offset}, ${end}) exceeds stride ${stride}.`);
+		for (const range of ranges) if (attribute.offset < range.end && end > range.start) throw new Error(`ParticleBufferLayout attribute "${attribute.name}" overlaps attribute "${range.name}" in the interleaved layout.`);
+		ranges.push({
+			name: attribute.name,
+			start: attribute.offset,
+			end
+		});
+	}
+};
+/**
+* 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.
+*/
+var ParticleBufferLayout = class {
+	attributes;
+	stride;
+	usage;
+	topology;
+	indices;
+	constructor(options) {
+		const { attributes, stride, usage = "stream", topology = "triangle-list", indices = null } = options;
+		if (attributes.length === 0) throw new Error("ParticleBufferLayout attributes must be a non-empty array.");
+		if (!Number.isInteger(stride) || stride <= 0) throw new Error(`ParticleBufferLayout stride must be a positive integer (got ${stride}).`);
+		if (!validTopologies.has(topology)) throw new Error(`ParticleBufferLayout topology must be one of: triangle-list, triangle-strip (got ${String(topology)}).`);
+		if (!validUsages.has(usage)) throw new Error(`ParticleBufferLayout usage must be one of: static, dynamic, stream (got ${String(usage)}).`);
+		validateAttributes(attributes, stride);
+		this.attributes = attributes.map((attribute) => ({ ...attribute }));
+		this.stride = stride;
+		this.usage = usage;
+		this.topology = topology;
+		this.indices = indices;
+	}
+	/** Elements one draw consumes from {@link indices}, or 0 when there are none. */
+	get indexCount() {
+		return this.indices?.length ?? 0;
+	}
+};
+/**
+* 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.
+*/
+const assertVertexGeometryCompatible = (dataLayout, vertexGeometry, instanced, modeName) => {
+	if (vertexGeometry === null) return;
+	if (!instanced) throw new Error(`${modeName}: a per-vertex geometry requires an instanced mode. Without instancing both buffers would step per vertex, which no draw can express.`);
+	const declared = new Set(dataLayout.attributes.map((attribute) => attribute.name));
+	for (const attribute of vertexGeometry.attributes) if (declared.has(attribute.name)) throw new Error(`${modeName}: attribute "${attribute.name}" is declared by both the per-frame buffer and the per-vertex geometry. Every attribute name must be unique across the two buffers.`);
+};
+
+//#endregion
+export { ParticleBufferLayout, assertVertexGeometryCompatible };
+//# sourceMappingURL=ParticleBufferLayout.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ParticleBufferLayout.js","names":[],"sources":["../../../src/renderModes/ParticleBufferLayout.ts"],"sourcesContent":["import type { AttributeType, Geometry, GeometryAttribute, GeometryUsage, Topology } from '@codexo/exojs';\n\nconst attributeTypeByteSizes: Record<AttributeType, number> = {\n  f32: 4,\n  u8: 1,\n  u16: 2,\n  u32: 4,\n  i32: 4,\n};\n\nconst validTopologies = new Set<Topology>(['triangle-list', 'triangle-strip']);\nconst validUsages = new Set<GeometryUsage>(['static', 'dynamic', 'stream']);\n\ninterface AttributeRange {\n  readonly name: string;\n  readonly start: number;\n  readonly end: number;\n}\n\n/**\n * Check that an attribute set describes a bindable interleaved record: unique\n * names, sane sizes and offsets, and ranges that neither overlap each other nor\n * reach past the stride.\n */\nconst validateAttributes = (attributes: readonly GeometryAttribute[], stride: number): void => {\n  const ranges: AttributeRange[] = [];\n  const names = new Set<string>();\n\n  for (const attribute of attributes) {\n    if (typeof attribute.name !== 'string' || attribute.name.length === 0) {\n      throw new Error('ParticleBufferLayout attribute name must be a non-empty string.');\n    }\n\n    if (names.has(attribute.name)) {\n      throw new Error(`ParticleBufferLayout attribute \"${attribute.name}\" is declared more than once.`);\n    }\n\n    names.add(attribute.name);\n\n    if (!Number.isInteger(attribute.size) || attribute.size === 0 || attribute.size > 4) {\n      throw new Error(`ParticleBufferLayout attribute \"${attribute.name}\" size must be an integer in [1..4] (got ${attribute.size}).`);\n    }\n\n    if (!Number.isInteger(attribute.offset) || attribute.offset < 0) {\n      throw new Error(`ParticleBufferLayout attribute \"${attribute.name}\" offset must be a non-negative integer (got ${attribute.offset}).`);\n    }\n\n    const end = attribute.offset + attributeTypeByteSizes[attribute.type] * attribute.size;\n\n    if (end > stride) {\n      throw new Error(`ParticleBufferLayout attribute \"${attribute.name}\" range [${attribute.offset}, ${end}) exceeds stride ${stride}.`);\n    }\n\n    for (const range of ranges) {\n      if (attribute.offset < range.end && end > range.start) {\n        throw new Error(`ParticleBufferLayout attribute \"${attribute.name}\" overlaps attribute \"${range.name}\" in the interleaved layout.`);\n      }\n    }\n\n    ranges.push({ name: attribute.name, start: attribute.offset, end });\n  }\n};\n\n/** Construction options for {@link ParticleBufferLayout}. */\nexport interface ParticleBufferLayoutOptions {\n  /** Interleaved attributes, in declaration order. Shader locations follow this order. */\n  readonly attributes: readonly GeometryAttribute[];\n\n  /** Bytes one record occupies. Must be a positive integer. */\n  readonly stride: number;\n\n  /** Upload hint for the buffer this layout describes. Defaults to `stream`. */\n  readonly usage?: GeometryUsage;\n\n  /**\n   * Topology of the draw, used only when the mode declares no per-vertex\n   * geometry to take it from. Defaults to `triangle-list`.\n   */\n  readonly topology?: Topology;\n\n  /**\n   * Index list for the draw, used only when the mode declares no per-vertex\n   * geometry to take it from. Defaults to none.\n   */\n  readonly indices?: Uint16Array | Uint32Array | null;\n}\n\n/**\n * Describes the interleaved buffer a render mode's `build()` fills each frame.\n *\n * Deliberately not a `Geometry`. A `Geometry` requires a position attribute,\n * requires that attribute to carry at least two components, and validates any\n * index list against the vertex count implied by its `vertexData` - three rules\n * that are meaningful for geometry and meaningless for a per-instance record.\n * Satisfying them used to cost the instanced modes a zero-filled placeholder\n * buffer that was never uploaded, sized purely to keep the index check quiet.\n *\n * What is checked here is the subset that protects a real GPU binding: a\n * positive stride, at least one attribute, unique names, and ranges that\n * neither overlap each other nor reach past the stride.\n *\n * A layout is a description rather than a resource: it owns no GPU handle and\n * needs no disposal.\n */\nexport class ParticleBufferLayout {\n  public readonly attributes: readonly GeometryAttribute[];\n  public readonly stride: number;\n  public readonly usage: GeometryUsage;\n  public readonly topology: Topology;\n  public readonly indices: Uint16Array | Uint32Array | null;\n\n  public constructor(options: ParticleBufferLayoutOptions) {\n    const { attributes, stride, usage = 'stream', topology = 'triangle-list', indices = null } = options;\n\n    if (attributes.length === 0) {\n      throw new Error('ParticleBufferLayout attributes must be a non-empty array.');\n    }\n\n    if (!Number.isInteger(stride) || stride <= 0) {\n      throw new Error(`ParticleBufferLayout stride must be a positive integer (got ${stride}).`);\n    }\n\n    if (!validTopologies.has(topology)) {\n      throw new Error(`ParticleBufferLayout topology must be one of: triangle-list, triangle-strip (got ${String(topology)}).`);\n    }\n\n    if (!validUsages.has(usage)) {\n      throw new Error(`ParticleBufferLayout usage must be one of: static, dynamic, stream (got ${String(usage)}).`);\n    }\n\n    validateAttributes(attributes, stride);\n\n    this.attributes = attributes.map(attribute => ({ ...attribute }));\n    this.stride = stride;\n    this.usage = usage;\n    this.topology = topology;\n    this.indices = indices;\n  }\n\n  /** Elements one draw consumes from {@link indices}, or 0 when there are none. */\n  public get indexCount(): number {\n    return this.indices?.length ?? 0;\n  }\n}\n\n/**\n * Guard the two seam combinations a mode must not declare.\n *\n * Called by a mode's own constructor, so the error names the mistake where it\n * was made, and repeated by each executor when it first realises a mode, so a\n * mode written outside this package cannot slip past. Both checks are cheap and\n * run once per mode rather than per frame.\n *\n * @param modeName Class name of the mode, used to prefix the error.\n */\nexport const assertVertexGeometryCompatible = (\n  dataLayout: ParticleBufferLayout,\n  vertexGeometry: Geometry | null,\n  instanced: boolean,\n  modeName: string,\n): void => {\n  if (vertexGeometry === null) {\n    return;\n  }\n\n  if (!instanced) {\n    throw new Error(\n      `${modeName}: a per-vertex geometry requires an instanced mode. Without instancing both buffers would step per vertex, which no draw can express.`,\n    );\n  }\n\n  const declared = new Set(dataLayout.attributes.map(attribute => attribute.name));\n\n  for (const attribute of vertexGeometry.attributes) {\n    if (declared.has(attribute.name)) {\n      throw new Error(\n        `${modeName}: attribute \"${attribute.name}\" is declared by both the per-frame buffer and the per-vertex geometry. Every attribute name must be unique across the two buffers.`,\n      );\n    }\n  }\n};\n"],"mappings":";AAEA,MAAM,yBAAwD;CAC5D,KAAK;CACL,IAAI;CACJ,KAAK;CACL,KAAK;CACL,KAAK;AACP;AAEA,MAAM,kCAAkB,IAAI,IAAc,CAAC,iBAAiB,gBAAgB,CAAC;AAC7E,MAAM,8BAAc,IAAI,IAAmB;CAAC;CAAU;CAAW;AAAQ,CAAC;;;;;;AAa1E,MAAM,sBAAsB,YAA0C,WAAyB;CAC7F,MAAM,SAA2B,CAAC;CAClC,MAAM,wBAAQ,IAAI,IAAY;CAE9B,KAAK,MAAM,aAAa,YAAY;EAClC,IAAI,OAAO,UAAU,SAAS,YAAY,UAAU,KAAK,WAAW,GAClE,MAAM,IAAI,MAAM,iEAAiE;EAGnF,IAAI,MAAM,IAAI,UAAU,IAAI,GAC1B,MAAM,IAAI,MAAM,mCAAmC,UAAU,KAAK,8BAA8B;EAGlG,MAAM,IAAI,UAAU,IAAI;EAExB,IAAI,CAAC,OAAO,UAAU,UAAU,IAAI,KAAK,UAAU,SAAS,KAAK,UAAU,OAAO,GAChF,MAAM,IAAI,MAAM,mCAAmC,UAAU,KAAK,2CAA2C,UAAU,KAAK,GAAG;EAGjI,IAAI,CAAC,OAAO,UAAU,UAAU,MAAM,KAAK,UAAU,SAAS,GAC5D,MAAM,IAAI,MAAM,mCAAmC,UAAU,KAAK,+CAA+C,UAAU,OAAO,GAAG;EAGvI,MAAM,MAAM,UAAU,SAAS,uBAAuB,UAAU,QAAQ,UAAU;EAElF,IAAI,MAAM,QACR,MAAM,IAAI,MAAM,mCAAmC,UAAU,KAAK,WAAW,UAAU,OAAO,IAAI,IAAI,mBAAmB,OAAO,EAAE;EAGpI,KAAK,MAAM,SAAS,QAClB,IAAI,UAAU,SAAS,MAAM,OAAO,MAAM,MAAM,OAC9C,MAAM,IAAI,MAAM,mCAAmC,UAAU,KAAK,wBAAwB,MAAM,KAAK,6BAA6B;EAItI,OAAO,KAAK;GAAE,MAAM,UAAU;GAAM,OAAO,UAAU;GAAQ;EAAI,CAAC;CACpE;AACF;;;;;;;;;;;;;;;;;;AA2CA,IAAa,uBAAb,MAAkC;CAChC,AAAgB;CAChB,AAAgB;CAChB,AAAgB;CAChB,AAAgB;CAChB,AAAgB;CAEhB,AAAO,YAAY,SAAsC;EACvD,MAAM,EAAE,YAAY,QAAQ,QAAQ,UAAU,WAAW,iBAAiB,UAAU,SAAS;EAE7F,IAAI,WAAW,WAAW,GACxB,MAAM,IAAI,MAAM,4DAA4D;EAG9E,IAAI,CAAC,OAAO,UAAU,MAAM,KAAK,UAAU,GACzC,MAAM,IAAI,MAAM,+DAA+D,OAAO,GAAG;EAG3F,IAAI,CAAC,gBAAgB,IAAI,QAAQ,GAC/B,MAAM,IAAI,MAAM,oFAAoF,OAAO,QAAQ,EAAE,GAAG;EAG1H,IAAI,CAAC,YAAY,IAAI,KAAK,GACxB,MAAM,IAAI,MAAM,2EAA2E,OAAO,KAAK,EAAE,GAAG;EAG9G,mBAAmB,YAAY,MAAM;EAErC,KAAK,aAAa,WAAW,KAAI,eAAc,EAAE,GAAG,UAAU,EAAE;EAChE,KAAK,SAAS;EACd,KAAK,QAAQ;EACb,KAAK,WAAW;EAChB,KAAK,UAAU;CACjB;;CAGA,IAAW,aAAqB;EAC9B,OAAO,KAAK,SAAS,UAAU;CACjC;AACF;;;;;;;;;;;AAYA,MAAa,kCACX,YACA,gBACA,WACA,aACS;CACT,IAAI,mBAAmB,MACrB;CAGF,IAAI,CAAC,WACH,MAAM,IAAI,MACR,GAAG,SAAS,sIACd;CAGF,MAAM,WAAW,IAAI,IAAI,WAAW,WAAW,KAAI,cAAa,UAAU,IAAI,CAAC;CAE/E,KAAK,MAAM,aAAa,eAAe,YACrC,IAAI,SAAS,IAAI,UAAU,IAAI,GAC7B,MAAM,IAAI,MACR,GAAG,SAAS,eAAe,UAAU,KAAK,oIAC5C;AAGN"}

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

@@ -0,0 +1,58 @@
+import type { GeometryAttribute } from '@codexo/exojs';
+import type { ParticleBatch } from '#ParticleStorage';
+import type { ParticleSystem } from '#ParticleSystem';
+/** Bytes one particle occupies in the interleaved per-instance buffer. */
+export declare const instanceStrideBytes = 40;
+/** 32-bit words one particle occupies in that buffer. */
+export declare const wordsPerInstance: number;
+/**
+ * The per-instance attribute layout every instanced render mode declares, and
+ * the layout the GPU compute pipeline emits into its instance buffer:
+ *
+ * ```
+ *   a_position   f32x2  (offset  0,  8 bytes)  particle position (system-local)
+ *   a_scale      f32x2  (offset  8,  8 bytes)
+ *   a_rotation   f32    (offset 16,  4 bytes)  degrees
+ *   a_color      u8x4   (offset 20,  4 bytes)  RGBA tint, normalised
+ *   a_uvMin      f32x2  (offset 24,  8 bytes)  pre-resolved frame uvMin
+ *   a_uvMax      f32x2  (offset 32,  8 bytes)  pre-resolved frame uvMax
+ * ```
+ *
+ * Shared rather than copied per mode so a mode using it cannot drift out of
+ * step with the compute shader and quietly lose its GPU eligibility. `Geometry`
+ * copies the attribute objects it is handed, so one frozen list serves every
+ * mode.
+ */
+export declare const instanceAttributes: readonly GeometryAttribute[];
+/**
+ * Fills the interleaved per-instance buffer shared by the instanced render
+ * modes - one 40-byte record per live particle, in {@link instanceAttributes}
+ * order.
+ *
+ * A class rather than a free function because the frame-UV table it resolves
+ * per frame is scratch state that must survive between calls: the arithmetic
+ * runs once per declared frame, not once per particle.
+ *
+ * This is the CPU counterpart of the compute pipeline's pack-instances step;
+ * the two must agree byte for byte, since a GPU-eligible mode's system swaps
+ * between them silently depending on the backend.
+ */
+export declare class ParticleInstanceWriter {
+    private _uvMinsScratch;
+    private _uvMaxsScratch;
+    /**
+     * Pack the live particles into the two views over one buffer, which must
+     * already hold `particles.count * instanceStrideBytes` bytes. Returns the
+     * number of instances written - dead slots in a GPU-mode system's live range
+     * are skipped, so that can be below the count.
+     */
+    write(system: ParticleSystem, particles: ParticleBatch, f32: Float32Array, u32: Uint32Array): number;
+    /**
+     * Compute (uvMin, uvMax) pairs for every declared frame on the system.
+     * Pulled out of the hot pack loop so the arithmetic runs once per frame
+     * rather than once per particle. Falls back to a single entry from
+     * `system.textureFrame` when no atlas is declared.
+     */
+    private _computeFrameUvs;
+}
+//# sourceMappingURL=ParticleInstanceWriter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ParticleInstanceWriter.d.ts","sourceRoot":"","sources":["../../../src/renderModes/ParticleInstanceWriter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAEvD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEtD,0EAA0E;AAC1E,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAEtC,yDAAyD;AACzD,eAAO,MAAM,gBAAgB,QAAsD,CAAC;AAEpF;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,kBAAkB,EAAE,SAAS,iBAAiB,EAO1D,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,qBAAa,sBAAsB;IACjC,OAAO,CAAC,cAAc,CAAuB;IAC7C,OAAO,CAAC,cAAc,CAAuB;IAE7C;;;;;OAKG;IACI,KAAK,CAAC,MAAM,EAAE,cAAc,EAAE,SAAS,EAAE,aAAa,EAAE,GAAG,EAAE,YAAY,EAAE,GAAG,EAAE,WAAW,GAAG,MAAM;IA8C3G;;;;;OAKG;IACH,OAAO,CAAC,gBAAgB;CAiDzB"}

package/dist/esm/renderModes/ParticleInstanceWriter.js

@@ -0,0 +1,173 @@
+//#region src/renderModes/ParticleInstanceWriter.ts
+/** Bytes one particle occupies in the interleaved per-instance buffer. */
+const instanceStrideBytes = 40;
+/** 32-bit words one particle occupies in that buffer. */
+const wordsPerInstance = 40 / Uint32Array.BYTES_PER_ELEMENT;
+/**
+* The per-instance attribute layout every instanced render mode declares, and
+* the layout the GPU compute pipeline emits into its instance buffer:
+*
+* ```
+*   a_position   f32x2  (offset  0,  8 bytes)  particle position (system-local)
+*   a_scale      f32x2  (offset  8,  8 bytes)
+*   a_rotation   f32    (offset 16,  4 bytes)  degrees
+*   a_color      u8x4   (offset 20,  4 bytes)  RGBA tint, normalised
+*   a_uvMin      f32x2  (offset 24,  8 bytes)  pre-resolved frame uvMin
+*   a_uvMax      f32x2  (offset 32,  8 bytes)  pre-resolved frame uvMax
+* ```
+*
+* Shared rather than copied per mode so a mode using it cannot drift out of
+* step with the compute shader and quietly lose its GPU eligibility. `Geometry`
+* copies the attribute objects it is handed, so one frozen list serves every
+* mode.
+*/
+const instanceAttributes = [
+	{
+		name: "a_position",
+		size: 2,
+		type: "f32",
+		normalized: false,
+		offset: 0
+	},
+	{
+		name: "a_scale",
+		size: 2,
+		type: "f32",
+		normalized: false,
+		offset: 8
+	},
+	{
+		name: "a_rotation",
+		size: 1,
+		type: "f32",
+		normalized: false,
+		offset: 16
+	},
+	{
+		name: "a_color",
+		size: 4,
+		type: "u8",
+		normalized: true,
+		offset: 20
+	},
+	{
+		name: "a_uvMin",
+		size: 2,
+		type: "f32",
+		normalized: false,
+		offset: 24
+	},
+	{
+		name: "a_uvMax",
+		size: 2,
+		type: "f32",
+		normalized: false,
+		offset: 32
+	}
+];
+/**
+* Fills the interleaved per-instance buffer shared by the instanced render
+* modes - one 40-byte record per live particle, in {@link instanceAttributes}
+* order.
+*
+* A class rather than a free function because the frame-UV table it resolves
+* per frame is scratch state that must survive between calls: the arithmetic
+* runs once per declared frame, not once per particle.
+*
+* This is the CPU counterpart of the compute pipeline's pack-instances step;
+* the two must agree byte for byte, since a GPU-eligible mode's system swaps
+* between them silently depending on the backend.
+*/
+var ParticleInstanceWriter = class {
+	_uvMinsScratch = /* @__PURE__ */ new Float32Array(2);
+	_uvMaxsScratch = /* @__PURE__ */ new Float32Array(2);
+	/**
+	* Pack the live particles into the two views over one buffer, which must
+	* already hold `particles.count * instanceStrideBytes` bytes. Returns the
+	* number of instances written - dead slots in a GPU-mode system's live range
+	* are skipped, so that can be below the count.
+	*/
+	write(system, particles, f32, u32) {
+		const limit = particles.count;
+		const { x: posX, y: posY } = particles.position;
+		const { x: scaleX, y: scaleY } = particles.scale;
+		const { angle: rotations } = particles.rotation;
+		const { color, frame: textureIndex } = particles;
+		const { uvMins, uvMaxs } = this._computeFrameUvs(system);
+		const frameCount = uvMins.length / 2;
+		const fallbackFrame = 0;
+		let writeIndex = 0;
+		for (let i = 0; i < limit; i++) {
+			if (!particles.isAlive(i)) continue;
+			const offset = writeIndex * wordsPerInstance;
+			const uvBase = (textureIndex[i] < frameCount ? textureIndex[i] : fallbackFrame) * 2;
+			f32[offset + 0] = posX[i];
+			f32[offset + 1] = posY[i];
+			f32[offset + 2] = scaleX[i];
+			f32[offset + 3] = scaleY[i];
+			f32[offset + 4] = rotations[i];
+			u32[offset + 5] = color[i];
+			f32[offset + 6] = uvMins[uvBase + 0];
+			f32[offset + 7] = uvMins[uvBase + 1];
+			f32[offset + 8] = uvMaxs[uvBase + 0];
+			f32[offset + 9] = uvMaxs[uvBase + 1];
+			writeIndex++;
+		}
+		return writeIndex;
+	}
+	/**
+	* Compute (uvMin, uvMax) pairs for every declared frame on the system.
+	* Pulled out of the hot pack loop so the arithmetic runs once per frame
+	* rather than once per particle. Falls back to a single entry from
+	* `system.textureFrame` when no atlas is declared.
+	*/
+	_computeFrameUvs(system) {
+		const frames = system.frames;
+		const tex = system.texture;
+		const texW = tex.width;
+		const texH = tex.height;
+		const flipY = tex.flipY;
+		const count = frames.length === 0 ? 1 : frames.length;
+		if (this._uvMinsScratch.length < count * 2) {
+			this._uvMinsScratch = new Float32Array(count * 2);
+			this._uvMaxsScratch = new Float32Array(count * 2);
+		}
+		const mins = this._uvMinsScratch;
+		const maxs = this._uvMaxsScratch;
+		if (frames.length === 0) {
+			const f = system.textureFrame;
+			const minU = f.left / texW;
+			const maxU = f.right / texW;
+			const topV = f.top / texH;
+			const bottomV = f.bottom / texH;
+			mins[0] = minU;
+			mins[1] = flipY ? bottomV : topV;
+			maxs[0] = maxU;
+			maxs[1] = flipY ? topV : bottomV;
+			return {
+				uvMins: mins,
+				uvMaxs: maxs
+			};
+		}
+		for (let i = 0; i < frames.length; i++) {
+			const f = frames[i];
+			const o = i * 2;
+			const minU = f.left / texW;
+			const maxU = f.right / texW;
+			const topV = f.top / texH;
+			const bottomV = f.bottom / texH;
+			mins[o + 0] = minU;
+			mins[o + 1] = flipY ? bottomV : topV;
+			maxs[o + 0] = maxU;
+			maxs[o + 1] = flipY ? topV : bottomV;
+		}
+		return {
+			uvMins: mins,
+			uvMaxs: maxs
+		};
+	}
+};
+
+//#endregion
+export { ParticleInstanceWriter, instanceAttributes, wordsPerInstance };
+//# sourceMappingURL=ParticleInstanceWriter.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ParticleInstanceWriter.js","names":[],"sources":["../../../src/renderModes/ParticleInstanceWriter.ts"],"sourcesContent":["import type { GeometryAttribute } from '@codexo/exojs';\n\nimport type { ParticleBatch } from '#ParticleStorage';\nimport type { ParticleSystem } from '#ParticleSystem';\n\n/** Bytes one particle occupies in the interleaved per-instance buffer. */\nexport const instanceStrideBytes = 40;\n\n/** 32-bit words one particle occupies in that buffer. */\nexport const wordsPerInstance = instanceStrideBytes / Uint32Array.BYTES_PER_ELEMENT;\n\n/**\n * The per-instance attribute layout every instanced render mode declares, and\n * the layout the GPU compute pipeline emits into its instance buffer:\n *\n * ```\n *   a_position   f32x2  (offset  0,  8 bytes)  particle position (system-local)\n *   a_scale      f32x2  (offset  8,  8 bytes)\n *   a_rotation   f32    (offset 16,  4 bytes)  degrees\n *   a_color      u8x4   (offset 20,  4 bytes)  RGBA tint, normalised\n *   a_uvMin      f32x2  (offset 24,  8 bytes)  pre-resolved frame uvMin\n *   a_uvMax      f32x2  (offset 32,  8 bytes)  pre-resolved frame uvMax\n * ```\n *\n * Shared rather than copied per mode so a mode using it cannot drift out of\n * step with the compute shader and quietly lose its GPU eligibility. `Geometry`\n * copies the attribute objects it is handed, so one frozen list serves every\n * mode.\n */\nexport const instanceAttributes: readonly GeometryAttribute[] = [\n  { name: 'a_position', size: 2, type: 'f32', normalized: false, offset: 0 },\n  { name: 'a_scale', size: 2, type: 'f32', normalized: false, offset: 8 },\n  { name: 'a_rotation', size: 1, type: 'f32', normalized: false, offset: 16 },\n  { name: 'a_color', size: 4, type: 'u8', normalized: true, offset: 20 },\n  { name: 'a_uvMin', size: 2, type: 'f32', normalized: false, offset: 24 },\n  { name: 'a_uvMax', size: 2, type: 'f32', normalized: false, offset: 32 },\n];\n\n/**\n * Fills the interleaved per-instance buffer shared by the instanced render\n * modes - one 40-byte record per live particle, in {@link instanceAttributes}\n * order.\n *\n * A class rather than a free function because the frame-UV table it resolves\n * per frame is scratch state that must survive between calls: the arithmetic\n * runs once per declared frame, not once per particle.\n *\n * This is the CPU counterpart of the compute pipeline's pack-instances step;\n * the two must agree byte for byte, since a GPU-eligible mode's system swaps\n * between them silently depending on the backend.\n */\nexport class ParticleInstanceWriter {\n  private _uvMinsScratch = new Float32Array(2);\n  private _uvMaxsScratch = new Float32Array(2);\n\n  /**\n   * Pack the live particles into the two views over one buffer, which must\n   * already hold `particles.count * instanceStrideBytes` bytes. Returns the\n   * number of instances written - dead slots in a GPU-mode system's live range\n   * are skipped, so that can be below the count.\n   */\n  public write(system: ParticleSystem, particles: ParticleBatch, f32: Float32Array, u32: Uint32Array): number {\n    const limit = particles.count;\n    const { x: posX, y: posY } = particles.position;\n    const { x: scaleX, y: scaleY } = particles.scale;\n    const { angle: rotations } = particles.rotation;\n    const { color, frame: textureIndex } = particles;\n\n    // Pre-compute frame UVs from system.frames + texture; falls back\n    // to the system.textureFrame when no atlas is declared.\n    const { uvMins, uvMaxs } = this._computeFrameUvs(system);\n    const frameCount = uvMins.length / 2;\n    // Anything that is not a valid explicit index shows frame 0, matching both\n    // the zero-initialised default and the compute pipeline. See\n    // `ParticleSystem.textureIndex`.\n    const fallbackFrame = 0;\n\n    let writeIndex = 0;\n\n    for (let i = 0; i < limit; i++) {\n      // Skip dead slots in GPU-mode systems where the live range can\n      // contain holes.\n      if (!particles.isAlive(i)) {\n        continue;\n      }\n\n      const offset = writeIndex * wordsPerInstance;\n      const frame = textureIndex[i]! < frameCount ? textureIndex[i]! : fallbackFrame;\n      const uvBase = frame * 2;\n\n      f32[offset + 0] = posX[i]!;\n      f32[offset + 1] = posY[i]!;\n      f32[offset + 2] = scaleX[i]!;\n      f32[offset + 3] = scaleY[i]!;\n      f32[offset + 4] = rotations[i]!;\n      u32[offset + 5] = color[i]!;\n      f32[offset + 6] = uvMins[uvBase + 0]!;\n      f32[offset + 7] = uvMins[uvBase + 1]!;\n      f32[offset + 8] = uvMaxs[uvBase + 0]!;\n      f32[offset + 9] = uvMaxs[uvBase + 1]!;\n\n      writeIndex++;\n    }\n\n    return writeIndex;\n  }\n\n  /**\n   * Compute (uvMin, uvMax) pairs for every declared frame on the system.\n   * Pulled out of the hot pack loop so the arithmetic runs once per frame\n   * rather than once per particle. Falls back to a single entry from\n   * `system.textureFrame` when no atlas is declared.\n   */\n  private _computeFrameUvs(system: ParticleSystem): { uvMins: Float32Array; uvMaxs: Float32Array } {\n    const frames = system.frames;\n    const tex = system.texture;\n    const texW = tex.width;\n    const texH = tex.height;\n    const flipY = tex.flipY;\n\n    const count = frames.length === 0 ? 1 : frames.length;\n\n    // Re-allocate scratch when capacity grows.\n    if (this._uvMinsScratch.length < count * 2) {\n      this._uvMinsScratch = new Float32Array(count * 2);\n      this._uvMaxsScratch = new Float32Array(count * 2);\n    }\n\n    const mins = this._uvMinsScratch;\n    const maxs = this._uvMaxsScratch;\n\n    if (frames.length === 0) {\n      const f = system.textureFrame;\n      const minU = f.left / texW;\n      const maxU = f.right / texW;\n      const topV = f.top / texH;\n      const bottomV = f.bottom / texH;\n\n      mins[0] = minU;\n      mins[1] = flipY ? bottomV : topV;\n      maxs[0] = maxU;\n      maxs[1] = flipY ? topV : bottomV;\n\n      return { uvMins: mins, uvMaxs: maxs };\n    }\n\n    for (let i = 0; i < frames.length; i++) {\n      const f = frames[i]!;\n      const o = i * 2;\n      const minU = f.left / texW;\n      const maxU = f.right / texW;\n      const topV = f.top / texH;\n      const bottomV = f.bottom / texH;\n\n      mins[o + 0] = minU;\n      mins[o + 1] = flipY ? bottomV : topV;\n      maxs[o + 0] = maxU;\n      maxs[o + 1] = flipY ? topV : bottomV;\n    }\n\n    return { uvMins: mins, uvMaxs: maxs };\n  }\n}\n"],"mappings":"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"}

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

@@ -0,0 +1,18 @@
+import type { MaterialOptions } from '@codexo/exojs';
+import { Material } from '@codexo/exojs';
+/**
+ * Material specialization for particle render modes.
+ *
+ * `Material`'s constructor is protected, so every material family declares a
+ * thin subclass that fixes {@link target} and opens construction up - this is
+ * the particle counterpart of core's `MeshMaterial` and `SpriteMaterial`.
+ *
+ * Particle draws bind their system-level state (transform, local bounds,
+ * texture) through the renderer rather than through the material, so this
+ * subclass adds no behaviour of its own; it exists to name the contract.
+ */
+export declare class ParticleMaterial extends Material {
+    readonly target = "particle";
+    constructor(options: MaterialOptions);
+}
+//# sourceMappingURL=ParticleMaterial.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ParticleMaterial.d.ts","sourceRoot":"","sources":["../../../src/renderModes/ParticleMaterial.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEzC;;;;;;;;;;GAUG;AACH,qBAAa,gBAAiB,SAAQ,QAAQ;IAC5C,SAAgB,MAAM,cAAc;gBAEjB,OAAO,EAAE,eAAe;CAG5C"}

package/dist/esm/renderModes/ParticleMaterial.js

@@ -0,0 +1,24 @@
+import { Material } from "@codexo/exojs";
+
+//#region src/renderModes/ParticleMaterial.ts
+/**
+* Material specialization for particle render modes.
+*
+* `Material`'s constructor is protected, so every material family declares a
+* thin subclass that fixes {@link target} and opens construction up - this is
+* the particle counterpart of core's `MeshMaterial` and `SpriteMaterial`.
+*
+* Particle draws bind their system-level state (transform, local bounds,
+* texture) through the renderer rather than through the material, so this
+* subclass adds no behaviour of its own; it exists to name the contract.
+*/
+var ParticleMaterial = class extends Material {
+	target = "particle";
+	constructor(options) {
+		super(options);
+	}
+};
+
+//#endregion
+export { ParticleMaterial };
+//# sourceMappingURL=ParticleMaterial.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ParticleMaterial.js","names":[],"sources":["../../../src/renderModes/ParticleMaterial.ts"],"sourcesContent":["import type { MaterialOptions } from '@codexo/exojs';\nimport { Material } from '@codexo/exojs';\n\n/**\n * Material specialization for particle render modes.\n *\n * `Material`'s constructor is protected, so every material family declares a\n * thin subclass that fixes {@link target} and opens construction up - this is\n * the particle counterpart of core's `MeshMaterial` and `SpriteMaterial`.\n *\n * Particle draws bind their system-level state (transform, local bounds,\n * texture) through the renderer rather than through the material, so this\n * subclass adds no behaviour of its own; it exists to name the contract.\n */\nexport class ParticleMaterial extends Material {\n  public readonly target = 'particle';\n\n  public constructor(options: MaterialOptions) {\n    super(options);\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;AAcA,IAAa,mBAAb,cAAsC,SAAS;CAC7C,AAAgB,SAAS;CAEzB,AAAO,YAAY,SAA0B;EAC3C,MAAM,OAAO;CACf;AACF"}

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

@@ -0,0 +1,114 @@
+import type { Geometry, Material } from '@codexo/exojs';
+import type { ParticleBatch } from '#ParticleStorage';
+import type { ParticleSystem } from '#ParticleSystem';
+import type { ParticleBufferLayout } from './ParticleBufferLayout';
+/**
+ * Turns a particle system's SoA storage into drawable vertex data.
+ *
+ * A mode owns the whole "how": the vertex layout, the shader pair, the draw
+ * model, and the loop that fills the buffer. The backend renderers only upload
+ * what it produces and issue the draw it declares, so a new primitive is a new
+ * mode rather than a renderer change.
+ *
+ * Implementations are fixed at system construction (see
+ * `ParticleSystemOptions.render`) and default to `QuadParticles`.
+ *
+ * **Limits of the seam.** The executors are deliberately thin, so a new mode
+ * has to stay inside what they can express:
+ *
+ * - The geometry's `stride` must be a multiple of 4. WebGPU's
+ *   `queue.writeBuffer` validates its copy size against that alignment and
+ *   rejects anything else, so a mode with, say, a 38-byte stride draws on
+ *   WebGL2 and fails validation on WebGPU.
+ * - An **indexed, non-instanced** mode always draws the geometry's fixed
+ *   `indexCount` and ignores {@link count} on both backends. That is right for
+ *   a fixed-topology mode and wrong for one whose element count varies per
+ *   frame; such a mode needs the executors taught to derive an index count
+ *   from {@link count} first. No mode ships in that shape today.
+ * - An **instanced** mode that declares no {@link vertexGeometry} has to derive
+ *   its vertices in the shader from the vertex index, and its
+ *   {@link dataLayout} must carry the indices that address them. Without either
+ *   there is nothing to tell the executors how many vertices one instance
+ *   spans.
+ */
+export declare abstract class ParticleRenderMode {
+    /**
+     * Layout of the buffer {@link build} fills each frame: attributes, stride,
+     * upload hint, and - when this mode declares no {@link vertexGeometry} - the
+     * topology and index list the draw uses.
+     *
+     * Named after {@link data}, the buffer it describes. It holds per-instance
+     * records for an instanced mode and per-vertex records otherwise, so a name
+     * fixed to either would be wrong for one of the two draw models.
+     */
+    abstract readonly dataLayout: ParticleBufferLayout;
+    /**
+     * Fixed per-vertex geometry this mode instances, or `null` when it derives
+     * its vertices in the shader from the vertex index - which is what
+     * `QuadParticles` and `RibbonParticles` do.
+     *
+     * When set, it supplies the topology, index list and index count for the draw
+     * in place of {@link dataLayout}'s, and the executors bind its `vertexData`
+     * as a second vertex buffer stepping per vertex beside the per-instance one.
+     * Only meaningful on an instanced mode: without instancing both buffers would
+     * step per vertex and no draw is expressible.
+     *
+     * Attribute names must not collide with {@link dataLayout}'s, since both sets
+     * bind into the same shader. Mutating the geometry is picked up on the next
+     * draw through its `version`, so `invalidate()` after an in-place edit is
+     * enough to reach the GPU.
+     */
+    readonly vertexGeometry: Geometry | null;
+    /** Shader pair plus uniforms/textures for this mode. */
+    abstract readonly material: Material;
+    /**
+     * Draw model. `true` issues an instanced draw, `false` a plain draw over the
+     * built vertex buffer. Declared here because a layout carries topology but
+     * has no instancing concept.
+     */
+    abstract readonly instanced: boolean;
+    /**
+     * Whether this mode can run while the system is in GPU compute mode.
+     * Mirrors `UpdateModule.wgsl()`: a mode that cannot forces the whole system
+     * onto the CPU path, silently and observably via `ParticleSystem.gpuMode`.
+     *
+     * A GPU-eligible mode's layout must match what the compute pipeline emits
+     * into `gpuState.instanceBuffer` - the shared 40-byte per-instance layout
+     * (`instanceAttributes`). `QuadParticles` and `MeshParticles` both declare
+     * exactly that layout and differ only in the shape they expand it into,
+     * which is why both are eligible without the compute shader knowing either.
+     */
+    readonly gpuEligible: boolean;
+    private _data;
+    private _count;
+    /**
+     * Element count of the draw call this mode's last {@link build} produced.
+     * Draw-model relative: instance count when {@link instanced}, vertex count
+     * otherwise. Do not assume one meaning.
+     */
+    get count(): number;
+    /** The buffer the renderer uploads. Valid until the next {@link build}. */
+    get data(): ArrayBuffer;
+    /**
+     * Fill the scratch buffer from the system's live particles.
+     *
+     * `particles` is the simulation's own channel storage, handed in rather than
+     * read off the system: a render mode is the one consumer that legitimately
+     * works in bulk, and it runs at the point in the frame where those values are
+     * the ones being drawn.
+     */
+    abstract build(system: ParticleSystem, particles: ParticleBatch): void;
+    /** Optional cleanup, called from `ParticleSystem.destroy`. */
+    destroy(): void;
+    /** Record the element count produced by a {@link build}. */
+    protected _setCount(count: number): void;
+    /**
+     * Grow the scratch buffer to hold at least `byteLength`. Grow-only: a
+     * shrinking particle count reuses the larger buffer rather than
+     * reallocating, matching the renderers' existing buffer policy.
+     */
+    protected _ensureCapacity(byteLength: number): void;
+    /** Re-create typed-array views after {@link _ensureCapacity} reallocates. */
+    protected _onBufferGrown(_data: ArrayBuffer): void;
+}
+//# sourceMappingURL=ParticleRenderMode.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ParticleRenderMode.d.ts","sourceRoot":"","sources":["../../../src/renderModes/ParticleRenderMode.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAExD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEtD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAEnE;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,8BAAsB,kBAAkB;IACtC;;;;;;;;OAQG;IACH,kBAAyB,UAAU,EAAE,oBAAoB,CAAC;IAE1D;;;;;;;;;;;;;;;OAeG;IACH,SAAgB,cAAc,EAAE,QAAQ,GAAG,IAAI,CAAQ;IAEvD,wDAAwD;IACxD,kBAAyB,QAAQ,EAAE,QAAQ,CAAC;IAE5C;;;;OAIG;IACH,kBAAyB,SAAS,EAAE,OAAO,CAAC;IAE5C;;;;;;;;;;OAUG;IACH,SAAgB,WAAW,EAAE,OAAO,CAAS;IAE7C,OAAO,CAAC,KAAK,CAAmC;IAChD,OAAO,CAAC,MAAM,CAAK;IAEnB;;;;OAIG;IACH,IAAW,KAAK,IAAI,MAAM,CAEzB;IAED,2EAA2E;IAC3E,IAAW,IAAI,IAAI,WAAW,CAE7B;IAED;;;;;;;OAOG;aACa,KAAK,CAAC,MAAM,EAAE,cAAc,EAAE,SAAS,EAAE,aAAa,GAAG,IAAI;IAE7E,8DAA8D;IACvD,OAAO,IAAI,IAAI;IAEtB,4DAA4D;IAC5D,SAAS,CAAC,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAIxC;;;;OAIG;IACH,SAAS,CAAC,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAenD,6EAA6E;IAC7E,SAAS,CAAC,cAAc,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI;CACnD"}

package/dist/esm/renderModes/ParticleRenderMode.js

@@ -0,0 +1,99 @@
+//#region src/renderModes/ParticleRenderMode.ts
+/**
+* Turns a particle system's SoA storage into drawable vertex data.
+*
+* A mode owns the whole "how": the vertex layout, the shader pair, the draw
+* model, and the loop that fills the buffer. The backend renderers only upload
+* what it produces and issue the draw it declares, so a new primitive is a new
+* mode rather than a renderer change.
+*
+* Implementations are fixed at system construction (see
+* `ParticleSystemOptions.render`) and default to `QuadParticles`.
+*
+* **Limits of the seam.** The executors are deliberately thin, so a new mode
+* has to stay inside what they can express:
+*
+* - The geometry's `stride` must be a multiple of 4. WebGPU's
+*   `queue.writeBuffer` validates its copy size against that alignment and
+*   rejects anything else, so a mode with, say, a 38-byte stride draws on
+*   WebGL2 and fails validation on WebGPU.
+* - An **indexed, non-instanced** mode always draws the geometry's fixed
+*   `indexCount` and ignores {@link count} on both backends. That is right for
+*   a fixed-topology mode and wrong for one whose element count varies per
+*   frame; such a mode needs the executors taught to derive an index count
+*   from {@link count} first. No mode ships in that shape today.
+* - An **instanced** mode that declares no {@link vertexGeometry} has to derive
+*   its vertices in the shader from the vertex index, and its
+*   {@link dataLayout} must carry the indices that address them. Without either
+*   there is nothing to tell the executors how many vertices one instance
+*   spans.
+*/
+var ParticleRenderMode = class {
+	/**
+	* Fixed per-vertex geometry this mode instances, or `null` when it derives
+	* its vertices in the shader from the vertex index - which is what
+	* `QuadParticles` and `RibbonParticles` do.
+	*
+	* When set, it supplies the topology, index list and index count for the draw
+	* in place of {@link dataLayout}'s, and the executors bind its `vertexData`
+	* as a second vertex buffer stepping per vertex beside the per-instance one.
+	* Only meaningful on an instanced mode: without instancing both buffers would
+	* step per vertex and no draw is expressible.
+	*
+	* Attribute names must not collide with {@link dataLayout}'s, since both sets
+	* bind into the same shader. Mutating the geometry is picked up on the next
+	* draw through its `version`, so `invalidate()` after an in-place edit is
+	* enough to reach the GPU.
+	*/
+	vertexGeometry = null;
+	/**
+	* Whether this mode can run while the system is in GPU compute mode.
+	* Mirrors `UpdateModule.wgsl()`: a mode that cannot forces the whole system
+	* onto the CPU path, silently and observably via `ParticleSystem.gpuMode`.
+	*
+	* A GPU-eligible mode's layout must match what the compute pipeline emits
+	* into `gpuState.instanceBuffer` - the shared 40-byte per-instance layout
+	* (`instanceAttributes`). `QuadParticles` and `MeshParticles` both declare
+	* exactly that layout and differ only in the shape they expand it into,
+	* which is why both are eligible without the compute shader knowing either.
+	*/
+	gpuEligible = false;
+	_data = /* @__PURE__ */ new ArrayBuffer(0);
+	_count = 0;
+	/**
+	* Element count of the draw call this mode's last {@link build} produced.
+	* Draw-model relative: instance count when {@link instanced}, vertex count
+	* otherwise. Do not assume one meaning.
+	*/
+	get count() {
+		return this._count;
+	}
+	/** The buffer the renderer uploads. Valid until the next {@link build}. */
+	get data() {
+		return this._data;
+	}
+	/** Optional cleanup, called from `ParticleSystem.destroy`. */
+	destroy() {}
+	/** Record the element count produced by a {@link build}. */
+	_setCount(count) {
+		this._count = count;
+	}
+	/**
+	* Grow the scratch buffer to hold at least `byteLength`. Grow-only: a
+	* shrinking particle count reuses the larger buffer rather than
+	* reallocating, matching the renderers' existing buffer policy.
+	*/
+	_ensureCapacity(byteLength) {
+		if (this._data.byteLength >= byteLength) return;
+		let next = Math.max(this._data.byteLength, 1);
+		while (next < byteLength) next *= 2;
+		this._data = new ArrayBuffer(next);
+		this._onBufferGrown(this._data);
+	}
+	/** Re-create typed-array views after {@link _ensureCapacity} reallocates. */
+	_onBufferGrown(_data) {}
+};
+
+//#endregion
+export { ParticleRenderMode };
+//# sourceMappingURL=ParticleRenderMode.js.map