@driftengine/core 3.61.0

package/src/render/orderIndependent.ts

@@ -0,0 +1,136 @@
+/**
+ * Order-independent transparency: the arithmetic, so it can be asserted without a device.
+ *
+ * **Two panes of glass should not depend on which was submitted first.** Sorted alpha blending is
+ * order-dependent by construction — `over` does not commute — so a translucent set is drawn back to
+ * front and anything the sort cannot separate flickers or wins arbitrarily: two panes that
+ * intersect, a pane containing another, a pane and the smoke inside it. A consumer's answer is
+ * usually to sort harder, which cannot fix an intersection at all.
+ *
+ * **Weighted blending replaces the ordering with a sum.** Each fragment contributes its colour
+ * scaled by a weight that falls off with distance, and separately multiplies a running
+ * transmittance. A sum and a product both commute, so the frame does not depend on the order the
+ * fragments arrived in — which is the property the census row asks for, and it is asserted here
+ * against numbers rather than argued about.
+ *
+ * **It is an approximation of the ordering and exact for one layer**, which is the honest way to
+ * state what it buys: with a single translucent surface there is no ordering to approximate and
+ * this reproduces `over` precisely, and the test beside it pins that. With several, near layers
+ * count for more than far ones and the result is plausible rather than correct — which is what a
+ * pane of glass needs and what a stained-glass window with eight overlapping leaves does not.
+ *
+ * McGuire and Bavoil, *Weighted Blended Order-Independent Transparency*, JCGT 2013 — equation 9
+ * for the weight, and its recommended constants, which are what the clamps below are.
+ *
+ * The one thing here that is not arithmetic is `OIT_MULTISAMPLE_REFUSAL`, and it is here for the
+ * same reason: it is a decision both backends take, so it is written once where neither owns it.
+ */
+
+/** A colour the accumulation is working on, as three numbers rather than a texture fetch. */
+export type Rgb = readonly [number, number, number];
+
+/**
+ * What the two targets hold between them.
+ *
+ * `accum` is the weighted sum of premultiplied colour with the weighted alpha in its fourth
+ * channel; `reveal` is the running product of what each layer let through. On a GPU these are two
+ * render targets with two blend states — additive for one, multiplicative for the other — and this
+ * object is the same numbers on the CPU so the algebra has somewhere to be tested.
+ */
+export interface OitAccumulator {
+  accum: [number, number, number, number];
+  /** One is "nothing has covered this pixel yet", which is why it is not zero. */
+  reveal: number;
+}
+
+/** An empty pixel: nothing accumulated, everything still revealed. */
+export function newOitAccumulator(): OitAccumulator {
+  return { accum: [0, 0, 0, 0], reveal: 1 };
+}
+
+/**
+ * How much a fragment at `viewDepth` metres and this alpha counts for.
+ *
+ * **A near fragment must count for more than a far one**, or the accumulation is an unweighted
+ * average: a pane thirty metres away would contribute as much as one against the camera, which
+ * reads as fog rather than as glass.
+ *
+ * **Clamped at both ends, and the clamp is what keeps this stable in float.** Without a ceiling a
+ * fragment on the near plane takes a weight large enough to swamp every other layer, and their
+ * contributions are then lost to rounding inside a 16-bit target; without a floor a distant one
+ * rounds to nothing and vanishes rather than fading.
+ */
+export function oitWeight(viewDepth: number, alpha: number): number {
+  const z = Math.max(0, viewDepth) / 200;
+  const falloff = 0.03 / (1e-5 + z * z * z * z);
+  return alpha * Math.min(3e3, Math.max(1e-2, falloff));
+}
+
+/**
+ * Fold one fragment in.
+ *
+ * **A sum and a product, which is the whole mechanism**: both commute, so the pixel does not
+ * depend on the order its fragments arrived in. A change that made either depend on order — an
+ * `if` on what is already there, a max instead of a sum — breaks the row this exists to close, and
+ * the test beside this fails before it reaches a GPU.
+ */
+export function accumulateOit(
+  state: OitAccumulator,
+  colour: Rgb,
+  alpha: number,
+  viewDepth: number,
+): void {
+  const w = oitWeight(viewDepth, alpha);
+  state.accum[0] += colour[0] * alpha * w;
+  state.accum[1] += colour[1] * alpha * w;
+  state.accum[2] += colour[2] * alpha * w;
+  state.accum[3] += alpha * w;
+  state.reveal *= 1 - alpha;
+}
+
+/**
+ * The two targets composited over what is behind them.
+ *
+ * The weighted sum divided by the weighted alpha is the average colour the layers make; `reveal`
+ * says how much of the background still shows through. For one layer that reduces exactly to
+ * `colour * alpha + background * (1 - alpha)`, which is `over` — the anchor the test asserts.
+ */
+export function resolveOit(state: OitAccumulator, background: Rgb): [number, number, number] {
+  /* Guarded because a pixel no fragment touched has a weighted alpha of zero, and the reveal of
+     one below then discards whatever this produced anyway. */
+  const weight = Math.max(state.accum[3], 1e-5);
+  const average: [number, number, number] = [
+    state.accum[0] / weight,
+    state.accum[1] / weight,
+    state.accum[2] / weight,
+  ];
+  const covered = 1 - state.reveal;
+  return [
+    average[0] * covered + background[0] * state.reveal,
+    average[1] * covered + background[1] * state.reveal,
+    average[2] * covered + background[2] * state.reveal,
+  ];
+}
+
+/**
+ * What both backends say when a profile asks for this and multisampling excludes it.
+ *
+ * **One string rather than one per backend, and that is rule 1 of the parity hard rule**:
+ * decisions live in backend-neutral code and only the binding is per-backend. The engine already
+ * paid for the other arrangement — `compositeWantsDepth` was two copies of one expression, depth
+ * of field was added to one of them, and the effect then ran against a discarded attachment. A
+ * refusal is a smaller thing than a depth attachment and drifts exactly as easily: the decal and
+ * reflection refusals beside this one are duplicated literals whose two halves have to be diffed
+ * by eye to know they still agree.
+ *
+ * **Why the effect is excluded rather than degraded.** Both passes attach the scene target's own
+ * depth and test against it, and above one sample the frame is not drawn into that texture — it
+ * is drawn into a multisampled renderbuffer, and the texture receives a copy at the end of the
+ * frame if anything asked for one. So the panes would be rejected against the frame before, or
+ * against a texture nothing has ever written.
+ */
+export const OIT_MULTISAMPLE_REFUSAL =
+  "driftengine: order-independent transparency attaches the scene target's own depth and tests " +
+  'against it, and a multisampled frame is not drawn into that texture — so translucent draws ' +
+  'stay sorted and blended wherever `sceneSamples` is above one. Antialiasing and this effect ' +
+  'are a choice of one.';

package/src/render/particleBatch.ts

@@ -0,0 +1,299 @@
+import { compileProgram, uniformLocations } from './shader.ts';
+import { particleShaders, type ParticleMaterial } from './particleMaterial.ts';
+import { PARTICLE_BLADES, PARTICLE_INDICES, PARTICLE_VERTS } from './shaders/particle.ts';
+import type { ParticleInstances } from './particlePool.ts';
+
+/**
+ * One draw call for a live particle pool: one camera-facing quad per particle, or a
+ * crossed pair of world-fixed ones when `facing` asks for them.
+ *
+ * Instanced: the cross is uploaded once as eight vertices, and each frame only the
+ * per-particle stream is re-sent. That is the difference between this and the
+ * scatter path it replaces — `InstancedMesh` is built for data that never changes
+ * after placement, and a particle system's data changes entirely every frame.
+ *
+ * Blending and depth are the batch's own decision because they are a property of
+ * the *material*: smoke occludes what is behind it and sparks add to it, and a
+ * caller that had to remember which would eventually forget. Neither writes depth
+ * — a soft particle that did would punch a hole in everything drawn after it.
+ */
+export type ParticleBlend = 'additive' | 'alpha';
+
+/**
+ * How a particle's quads are turned.
+ *
+ * `'camera'` is one quad facing the viewer, and the default. `'cross'` is the pair of
+ * world-fixed blades this batch drew before the option existed — see `uCameraFacing` in
+ * `shaders/particle.ts` for the artifact that made the default the other one, and for what
+ * the cross still buys a caller who wants it back.
+ */
+export type ParticleFacing = 'camera' | 'cross';
+
+export interface ParticleBatchOptions {
+  /**
+   * Which particle this is, by name.
+   *
+   * **This replaced a GLSL source string on 2026-08-13**, the same change and for the same
+   * reason as `PlumeOptions.material`: a caller-supplied shader is a capability that can only
+   * ever exist on WebGL2, and naming the material lets each backend resolve what it can
+   * compile. See `particleMaterial.ts`.
+   */
+  material: ParticleMaterial;
+  blend: ParticleBlend;
+  /**
+   * Seconds of travel a particle is stretched along. 0 for smoke.
+   *
+   * **The velocity it stretches along is a direction to be drawn on, not a motion being
+   * simulated, and it must stay that way.** Nothing here integrates it: a caller writes both
+   * position and velocity every frame, so a deterministic consumer that computes where a
+   * particle *is* from its own plan can still ask for the streak that a moving thing has. That
+   * is load-bearing outside this repository, where a corona's streamers are the spark material
+   * stretched radially and nothing about them moves. Advancing position from this would take
+   * the feature away from every caller that is not running a simulation.
+   */
+  stretchSec?: number;
+  /** How hard the noise erodes a puff, 0 to 1. Ignored by the spark and mote materials. */
+  erosion?: number;
+  /** How far past white a spark's core may go. Ignored by the smoke and mote materials. */
+  coreGain?: number;
+  /**
+   * Whether the medium's fog and underwater tint reach this pool. Ignored by the spark and
+   * smoke materials, which stay unconditionally fogged — a real ember and real grit belong in
+   * the same haze as the rest of the world, matching every particle drawn before this option
+   * existed. Defaults to false, because a caller reaching for `'mote'` over `'spark'`/`'smoke'`
+   * is usually asking for exactly what those two cannot draw: an unlit point exactly its own
+   * colour, untouched by distance. See `PARTICLE_MOTE_FRAG`'s own comment on `uFogEnabled`.
+   */
+  fog?: boolean;
+  /**
+   * Whether each particle is one camera-facing quad or a world-fixed cross of two.
+   *
+   * Defaults to `'camera'`, and **this default changed** — every particle drawn before it
+   * was a cross. A cross has a blade edge-on down each of two world axes, and a sprite
+   * squeezed into a one-pixel column spends its whole brightness there: a bright straight
+   * line through the middle, worst on the additive materials, and a pair of them from
+   * directly above. Consider `'cross'` when the camera stays near horizontal and the
+   * parallax of two blades is worth more than a stable brightness, which is the trade the
+   * shader's own comment on `uCameraFacing` lays out.
+   */
+  facing?: ParticleFacing;
+  /**
+   * Another batch whose compiled program this one should reuse.
+   *
+   * Several pools legitimately share a *material* while needing their own buffers —
+   * a game may have four kinds of smoke, each with its own colours, lifetime and
+   * capacity, all drawn by one fragment shader. Without this each of them compiles
+   * the same source again, which is pure boot time on the device where boot time is
+   * scarcest. The per-material constants stay per batch, because they are the point
+   * of having several.
+   *
+   * Only valid for the same `material`, and **that is now checked** — it was not, and could
+   * not be, while the material was an opaque source string a caller supplied. Naming it made
+   * the constraint expressible, so a spark batch reusing a smoke program fails at construction
+   * with both names rather than drawing sparks that look like smoke.
+   */
+  reuse?: ParticleBatch;
+}
+
+/** Corners of one blade, as a triangle-strip-friendly quad. */
+const CORNERS = [
+  [-1, -1],
+  [1, -1],
+  [1, 1],
+  [-1, 1],
+] as const;
+
+export class ParticleBatch {
+  readonly program: WebGLProgram;
+  readonly uniforms: Record<string, WebGLUniformLocation>;
+
+  private readonly vao: WebGLVertexArrayObject;
+  private readonly buffers: WebGLBuffer[] = [];
+  private readonly positionBuffer: WebGLBuffer;
+  private readonly sizeBuffer: WebGLBuffer;
+  private readonly spinBuffer: WebGLBuffer;
+  private readonly colorBuffer: WebGLBuffer;
+  private readonly alphaBuffer: WebGLBuffer;
+  private readonly ageBuffer: WebGLBuffer;
+  private readonly seedBuffer: WebGLBuffer;
+  private readonly velocityBuffer: WebGLBuffer;
+  private readonly blend: ParticleBlend;
+  private readonly stretchSec: number;
+  private readonly erosion: number;
+  private readonly coreGain: number;
+  private readonly fog: boolean;
+  private readonly facing: ParticleFacing;
+  /** False when the program belongs to another batch, so `dispose` leaves it alone. */
+  private readonly ownsProgram: boolean;
+  /** Which material compiled this batch's program, so `reuse` can be checked. */
+  readonly material: ParticleMaterial;
+
+  constructor(gl: WebGL2RenderingContext, capacity: number, options: ParticleBatchOptions) {
+    /* The vertex stage comes with the material now; it used to be a separate argument that
+       every caller passed the same value for. */
+    const shaders = particleShaders(options.material);
+    const shared = options.reuse;
+    if (shared !== undefined && shared.material !== options.material) {
+      throw new Error(
+        `createParticles: cannot reuse a "${shared.material}" program for a ` +
+          `"${options.material}" batch. \`reuse\` shares one compiled material between pools.`,
+      );
+    }
+    this.ownsProgram = shared === undefined;
+    this.material = options.material;
+    this.program =
+      shared?.program ??
+      compileProgram(gl, shaders.vertexSource, shaders.fragmentSource, shaders.label);
+    this.uniforms = shared?.uniforms ?? uniformLocations(gl, this.program, 'particleBatch');
+    this.blend = options.blend;
+    this.stretchSec = options.stretchSec ?? 0;
+    this.erosion = options.erosion ?? 0;
+    this.coreGain = options.coreGain ?? 1;
+    this.fog = options.fog ?? false;
+    this.facing = options.facing ?? 'camera';
+
+    const corners = new Float32Array(PARTICLE_VERTS * 2);
+    const blades = new Float32Array(PARTICLE_VERTS);
+    const indices = new Uint16Array(PARTICLE_INDICES);
+    for (let b = 0; b < PARTICLE_BLADES; b++) {
+      for (let c = 0; c < 4; c++) {
+        const v = b * 4 + c;
+        const corner = CORNERS[c] ?? [0, 0];
+        corners[v * 2] = corner[0];
+        corners[v * 2 + 1] = corner[1];
+        blades[v] = b;
+      }
+      const base = b * 4;
+      const i = b * 6;
+      indices[i] = base;
+      indices[i + 1] = base + 1;
+      indices[i + 2] = base + 2;
+      indices[i + 3] = base;
+      indices[i + 4] = base + 2;
+      indices[i + 5] = base + 3;
+    }
+
+    const vao = gl.createVertexArray();
+    if (vao === null) throw new Error(`${shaders.label}: createVertexArray failed`);
+    this.vao = vao;
+    gl.bindVertexArray(vao);
+
+    this.attach(gl, 0, corners, 2, 0, shaders.label);
+    this.attach(gl, 1, blades, 1, 0, shaders.label);
+    this.positionBuffer = this.attach(gl, 2, capacity * 3, 3, 1, shaders.label);
+    this.sizeBuffer = this.attach(gl, 3, capacity, 1, 1, shaders.label);
+    this.spinBuffer = this.attach(gl, 4, capacity, 1, 1, shaders.label);
+    this.colorBuffer = this.attach(gl, 5, capacity * 3, 3, 1, shaders.label);
+    this.alphaBuffer = this.attach(gl, 6, capacity, 1, 1, shaders.label);
+    this.ageBuffer = this.attach(gl, 7, capacity, 1, 1, shaders.label);
+    this.seedBuffer = this.attach(gl, 8, capacity, 1, 1, shaders.label);
+    this.velocityBuffer = this.attach(gl, 9, capacity * 3, 3, 1, shaders.label);
+
+    const indexBuffer = gl.createBuffer();
+    if (indexBuffer === null) throw new Error(`${shaders.label}: createBuffer failed`);
+    this.buffers.push(indexBuffer);
+    gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, indexBuffer);
+    gl.bufferData(gl.ELEMENT_ARRAY_BUFFER, indices, gl.STATIC_DRAW);
+    gl.bindVertexArray(null);
+  }
+
+  /**
+   * Send this frame's particles.
+   *
+   * Only the live prefix of each array, which is what the pool's compaction
+   * exists for: a pool at a tenth of its capacity uploads a tenth of the bytes.
+   */
+  upload(gl: WebGL2RenderingContext, data: ParticleInstances): void {
+    const n = data.count;
+    if (n === 0) return;
+    this.send(gl, this.positionBuffer, data.positions, n * 3);
+    this.send(gl, this.sizeBuffer, data.sizes, n);
+    this.send(gl, this.spinBuffer, data.spins, n);
+    this.send(gl, this.colorBuffer, data.colors, n * 3);
+    this.send(gl, this.alphaBuffer, data.alphas, n);
+    this.send(gl, this.ageBuffer, data.ages, n);
+    this.send(gl, this.seedBuffer, data.seeds, n);
+    this.send(gl, this.velocityBuffer, data.velocities, n * 3);
+  }
+
+  /** Bind this material's own constants. Called once per draw, before `drawTo`. */
+  bindMaterial(gl: WebGL2RenderingContext): void {
+    const u = this.uniforms;
+    gl.uniform1f(u['uStretchSec'] ?? null, this.stretchSec);
+    gl.uniform1f(u['uCameraFacing'] ?? null, this.facing === 'camera' ? 1 : 0);
+    gl.uniform1f(u['uErosion'] ?? null, this.erosion);
+    gl.uniform1f(u['uCoreGain'] ?? null, this.coreGain);
+    /* Only the mote program declares uFogEnabled, so this is a no-op — not a leak into the
+       next draw — on the other two: `u['uFogEnabled']` is undefined there and gl.uniform1i
+       silently ignores a null location. */
+    gl.uniform1i(u['uFogEnabled'] ?? null, this.fog ? 1 : 0);
+  }
+
+  /**
+   * Draw the live particles.
+   *
+   * Depth *tested* but not written, so a puff is correctly hidden behind the deck
+   * and never hides a puff behind it. Culling off, because a blade seen from
+   * behind is exactly as valid as one seen from the front.
+   */
+  drawTo(gl: WebGL2RenderingContext, count: number): void {
+    if (count === 0) return;
+    gl.enable(gl.BLEND);
+    if (this.blend === 'additive') gl.blendFunc(gl.SRC_ALPHA, gl.ONE);
+    else gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
+    gl.depthMask(false);
+    gl.disable(gl.CULL_FACE);
+
+    gl.bindVertexArray(this.vao);
+    gl.drawElementsInstanced(gl.TRIANGLES, PARTICLE_INDICES, gl.UNSIGNED_SHORT, 0, count);
+    gl.bindVertexArray(null);
+
+    gl.enable(gl.CULL_FACE);
+    gl.depthMask(true);
+    gl.disable(gl.BLEND);
+  }
+
+  dispose(gl: WebGL2RenderingContext): void {
+    for (const buffer of this.buffers) gl.deleteBuffer(buffer);
+    this.buffers.length = 0;
+    gl.deleteVertexArray(this.vao);
+    if (this.ownsProgram) gl.deleteProgram(this.program);
+  }
+
+  private send(
+    gl: WebGL2RenderingContext,
+    buffer: WebGLBuffer,
+    data: Float32Array,
+    length: number,
+  ): void {
+    gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
+    gl.bufferSubData(gl.ARRAY_BUFFER, 0, data, 0, length);
+  }
+
+  /**
+   * One attribute buffer. `divisor` 0 is per-vertex, 1 is per-instance — the whole
+   * mechanism by which eight vertices draw a thousand particles.
+   */
+  private attach(
+    gl: WebGL2RenderingContext,
+    location: number,
+    dataOrFloats: Float32Array | number,
+    size: number,
+    divisor: number,
+    label: string,
+  ): WebGLBuffer {
+    const buffer = gl.createBuffer();
+    if (buffer === null) throw new Error(`${label}: createBuffer failed`);
+    this.buffers.push(buffer);
+    gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
+    if (typeof dataOrFloats === 'number') {
+      gl.bufferData(gl.ARRAY_BUFFER, dataOrFloats * 4, gl.DYNAMIC_DRAW);
+    } else {
+      gl.bufferData(gl.ARRAY_BUFFER, dataOrFloats, gl.STATIC_DRAW);
+    }
+    gl.enableVertexAttribArray(location);
+    gl.vertexAttribPointer(location, size, gl.FLOAT, false, 0, 0);
+    gl.vertexAttribDivisor(location, divisor);
+    return buffer;
+  }
+}

package/src/render/particleMaterial.ts

@@ -0,0 +1,84 @@
+import {
+  PARTICLE_MOTE_FRAG,
+  PARTICLE_SMOKE_FRAG,
+  PARTICLE_SPARK_FRAG,
+  PARTICLE_VERT,
+} from './shaders/particle.ts';
+import {
+  PARTICLE_BINDINGS,
+  PARTICLE_MOTE_FRAG_WGSL,
+  PARTICLE_SMOKE_FRAG_WGSL,
+  PARTICLE_SPARK_FRAG_WGSL,
+  PARTICLE_VERT_WGSL,
+} from './shaders/generated/particle.wgsl.ts';
+
+/**
+ * Which particle material a caller wants, by name rather than by source.
+ *
+ * **The same change `PlumeMaterial` documents, for the same reason.**
+ * `ParticleBatchOptions.fragmentSource` was a GLSL string, and a caller-supplied GLSL string
+ * is a capability that can only ever exist on WebGL2 — WebGPU has no runtime compiler and this
+ * package must never ship one. Naming the material lets each backend resolve what it can
+ * compile.
+ *
+ * **The three are not interchangeable and never were**, which is why the names read as
+ * materials rather than as shaders: `erosion` is ignored by the spark and the mote, `coreGain`
+ * by the smoke and the mote, and `fog` by the spark and the smoke — and the options already
+ * document that. Naming them makes the pairing explicit instead of leaving it to a caller to
+ * match a source with the constants that suit it.
+ */
+export type ParticleMaterial = 'smoke' | 'spark' | 'mote';
+
+/** Both compilations of one material, and what the generator recorded about each stage. */
+export interface ParticleShaders {
+  readonly label: string;
+  readonly vertexSource: string;
+  readonly fragmentSource: string;
+  readonly vertexWgsl: string;
+  readonly fragmentWgsl: string;
+}
+
+/**
+ * Every particle material this engine ships.
+ *
+ * One table with both compilations, rather than a lookup per backend — a material present in
+ * one and absent from the other is the drift the 2026-08-13 rule in `AGENTS.md` prevents.
+ */
+const MATERIALS: Readonly<Record<ParticleMaterial, ParticleShaders>> = {
+  smoke: {
+    label: 'particle:smoke',
+    vertexSource: PARTICLE_VERT,
+    fragmentSource: PARTICLE_SMOKE_FRAG,
+    vertexWgsl: PARTICLE_VERT_WGSL,
+    fragmentWgsl: PARTICLE_SMOKE_FRAG_WGSL,
+  },
+  spark: {
+    label: 'particle:spark',
+    vertexSource: PARTICLE_VERT,
+    fragmentSource: PARTICLE_SPARK_FRAG,
+    vertexWgsl: PARTICLE_VERT_WGSL,
+    fragmentWgsl: PARTICLE_SPARK_FRAG_WGSL,
+  },
+  mote: {
+    label: 'particle:mote',
+    vertexSource: PARTICLE_VERT,
+    fragmentSource: PARTICLE_MOTE_FRAG,
+    vertexWgsl: PARTICLE_VERT_WGSL,
+    fragmentWgsl: PARTICLE_MOTE_FRAG_WGSL,
+  },
+};
+
+/** What the generator recorded about the shared vertex stage. */
+export const PARTICLE_VERT_BINDINGS = PARTICLE_BINDINGS.PARTICLE_VERT;
+
+/** Resolve a material name, or say which names exist. */
+export function particleShaders(material: ParticleMaterial): ParticleShaders {
+  const found = MATERIALS[material];
+  if (found === undefined) {
+    throw new Error(
+      `createParticles: unknown particle material "${String(material)}". ` +
+        `Known materials: ${Object.keys(MATERIALS).join(', ')}.`,
+    );
+  }
+  return found;
+}