@aura3d/rendering 1.0.6

package/src/effects/ParticleModule.ts

@@ -0,0 +1,26 @@
+import type { Particle } from "./Particle.js";
+
+export interface ParticleUpdateContext {
+  deltaTime: number;
+  elapsedTime: number;
+  normalizedAge: number;
+  random: () => number;
+}
+
+export interface ParticleModule {
+  readonly name: string;
+  onSpawn?(particle: Particle, context: ParticleUpdateContext): void;
+  update?(particle: Particle, context: ParticleUpdateContext): void;
+  afterIntegrate?(particle: Particle, context: ParticleUpdateContext): void;
+}
+
+export function applyParticleModules(
+  modules: readonly ParticleModule[],
+  hook: "onSpawn" | "update" | "afterIntegrate",
+  particle: Particle,
+  context: ParticleUpdateContext,
+): void {
+  for (const module of modules) {
+    module[hook]?.(particle, context);
+  }
+}

package/src/effects/ParticleRenderPass.ts

@@ -0,0 +1,117 @@
+import { BaseRenderPass, type RenderPassContext } from "../RenderPass.js";
+import { type GPUParticleBackend } from "./GPUParticleBackend.js";
+import { ParticleRenderer, type ParticleDrawTarget, type ParticleRenderBatch, type ParticleRenderOptions } from "./ParticleRenderer.js";
+import { type ParticleSystem } from "./ParticleSystem.js";
+
+export type ParticleRenderPassUpdateMode = "none" | "cpu" | "gpu";
+
+export interface ParticleRenderPassUpdateOptions {
+  readonly deltaTime: number;
+  readonly gpuBackend?: GPUParticleBackend;
+  readonly preferGPU?: boolean;
+  readonly allowCPUFallback?: boolean;
+}
+
+export interface ParticleRenderPassOptions {
+  readonly system: ParticleSystem;
+  readonly target: ParticleDrawTarget;
+  readonly renderer?: ParticleRenderer;
+  readonly renderOptions?: ParticleRenderOptions;
+  readonly update?: ParticleRenderPassUpdateOptions;
+  readonly reads?: readonly string[];
+  readonly writes?: readonly string[];
+}
+
+export class ParticleRenderPass extends BaseRenderPass {
+  readonly renderer: ParticleRenderer;
+  private lastBatch: ParticleRenderBatch | null = null;
+  private lastUpdateMode: ParticleRenderPassUpdateMode = "none";
+
+  constructor(private readonly options: ParticleRenderPassOptions) {
+    super("particles", options.reads ?? ["color"], options.writes ?? ["color"], ["color"]);
+    this.renderer = options.renderer ?? new ParticleRenderer();
+  }
+
+  execute(_context: RenderPassContext): void {
+    if (this.requiresAsyncUpdate()) {
+      throw new Error("ParticleRenderPass with a supported GPU update backend must run through RenderGraph.executeAsync().");
+    }
+    this.updateSync();
+    this.lastBatch = this.renderer.render(this.options.system, this.options.target, this.options.renderOptions);
+  }
+
+  async executeAsync(_context: RenderPassContext): Promise<void> {
+    await this.updateAsync();
+    this.lastBatch = this.renderer.render(this.options.system, this.options.target, this.options.renderOptions);
+  }
+
+  getLastBatch(): ParticleRenderBatch | null {
+    if (!this.lastBatch) {
+      return null;
+    }
+    return {
+      sprites: this.lastBatch.sprites.map((sprite) => ({
+        ...sprite,
+        position: { ...sprite.position },
+        color: { ...sprite.color }
+      })),
+      liveCount: this.lastBatch.liveCount,
+      uploadedBytes: this.lastBatch.uploadedBytes,
+      bounds: this.lastBatch.bounds ? {
+        min: { ...this.lastBatch.bounds.min },
+        max: { ...this.lastBatch.bounds.max }
+      } : null
+    };
+  }
+
+  getLastUpdateMode(): ParticleRenderPassUpdateMode {
+    return this.lastUpdateMode;
+  }
+
+  private requiresAsyncUpdate(): boolean {
+    const update = this.options.update;
+    return Boolean(update?.gpuBackend?.capabilities.supported && (update.preferGPU ?? true));
+  }
+
+  private updateSync(): void {
+    const update = this.options.update;
+    if (!update) {
+      this.lastUpdateMode = "none";
+      return;
+    }
+    validateDeltaTime(update.deltaTime);
+    if (update.gpuBackend && update.preferGPU !== false && !update.gpuBackend.capabilities.supported && update.allowCPUFallback === false) {
+      throw new Error(update.gpuBackend.capabilities.reason ?? "GPU particle backend is unsupported.");
+    }
+    this.options.system.update(update.deltaTime);
+    this.lastUpdateMode = "cpu";
+  }
+
+  private async updateAsync(): Promise<void> {
+    const update = this.options.update;
+    if (!update) {
+      this.lastUpdateMode = "none";
+      return;
+    }
+    validateDeltaTime(update.deltaTime);
+    const backend = update.gpuBackend;
+    if (backend && (update.preferGPU ?? true)) {
+      if (backend.capabilities.supported) {
+        await this.options.system.updateOnGPU(update.deltaTime, backend);
+        this.lastUpdateMode = "gpu";
+        return;
+      }
+      if (update.allowCPUFallback === false) {
+        throw new Error(backend.capabilities.reason ?? "GPU particle backend is unsupported.");
+      }
+    }
+    this.options.system.update(update.deltaTime);
+    this.lastUpdateMode = "cpu";
+  }
+}
+
+function validateDeltaTime(deltaTime: number): void {
+  if (!Number.isFinite(deltaTime) || deltaTime < 0) {
+    throw new RangeError("ParticleRenderPass update deltaTime must be a finite non-negative number.");
+  }
+}

package/src/effects/ParticleRenderer.ts

@@ -0,0 +1,132 @@
+import type { ColorLike, Particle, Vector3Like } from "./Particle.js";
+import type { ParticleSystem } from "./ParticleSystem.js";
+
+export interface ParticleSprite {
+  id: number;
+  position: Vector3Like;
+  color: ColorLike;
+  size: number;
+  rotation: number;
+}
+
+export interface ParticleBatchBounds {
+  min: Vector3Like;
+  max: Vector3Like;
+}
+
+export interface ParticleRenderBatch {
+  sprites: ParticleSprite[];
+  liveCount: number;
+  uploadedBytes: number;
+  bounds: ParticleBatchBounds | null;
+}
+
+export interface ParticleDrawTarget {
+  drawParticles(batch: ParticleRenderBatch): void;
+}
+
+export type ParticleSortMode = "none" | "front-to-back" | "back-to-front";
+
+export interface ParticleRenderOptions {
+  readonly sort?: ParticleSortMode;
+  readonly cameraPosition?: Vector3Like;
+}
+
+export class ParticleRenderer {
+  private lastBatch: ParticleRenderBatch = {
+    sprites: [],
+    liveCount: 0,
+    uploadedBytes: 0,
+    bounds: null,
+  };
+
+  buildBatch(particles: readonly Particle[], options: ParticleRenderOptions = {}): ParticleRenderBatch {
+    const sprites = particles
+      .filter((particle) => particle.alive)
+      .map((particle) => ({
+        id: particle.id,
+        position: { ...particle.position },
+        color: { ...particle.color },
+        size: particle.size,
+        rotation: particle.rotation,
+      }));
+    sortSprites(sprites, options);
+
+    this.lastBatch = {
+      sprites,
+      liveCount: sprites.length,
+      uploadedBytes: sprites.length * (3 + 4 + 1 + 1) * Float32Array.BYTES_PER_ELEMENT,
+      bounds: computeBounds(sprites),
+    };
+
+    return this.lastBatch;
+  }
+
+  render(system: ParticleSystem, target: ParticleDrawTarget, options: ParticleRenderOptions = {}): ParticleRenderBatch {
+    const batch = this.buildBatch(system.particles, options);
+    target.drawParticles(batch);
+    system.recordBufferUpload(batch.uploadedBytes);
+    return batch;
+  }
+
+  getLastBatch(): ParticleRenderBatch {
+    return {
+      sprites: this.lastBatch.sprites.map((sprite) => ({
+        ...sprite,
+        position: { ...sprite.position },
+        color: { ...sprite.color },
+      })),
+      liveCount: this.lastBatch.liveCount,
+      uploadedBytes: this.lastBatch.uploadedBytes,
+      bounds: this.lastBatch.bounds ? {
+        min: { ...this.lastBatch.bounds.min },
+        max: { ...this.lastBatch.bounds.max },
+      } : null,
+    };
+  }
+}
+
+function sortSprites(sprites: ParticleSprite[], options: ParticleRenderOptions): void {
+  const mode = options.sort ?? "none";
+  if (mode === "none") return;
+  const camera = options.cameraPosition;
+  if (!camera || !isFiniteVector(camera)) {
+    throw new RangeError("ParticleRenderer cameraPosition must be finite when depth sorting is enabled.");
+  }
+  const direction = mode === "back-to-front" ? -1 : 1;
+  sprites.sort((a, b) => {
+    const distanceDelta = distanceSquared(a.position, camera) - distanceSquared(b.position, camera);
+    if (Math.abs(distanceDelta) > 1e-9) return distanceDelta * direction;
+    return a.id - b.id;
+  });
+}
+
+function computeBounds(sprites: readonly ParticleSprite[]): ParticleBatchBounds | null {
+  if (sprites.length === 0) return null;
+  const min = { x: Number.POSITIVE_INFINITY, y: Number.POSITIVE_INFINITY, z: Number.POSITIVE_INFINITY };
+  const max = { x: Number.NEGATIVE_INFINITY, y: Number.NEGATIVE_INFINITY, z: Number.NEGATIVE_INFINITY };
+  for (const sprite of sprites) {
+    if (!isFiniteVector(sprite.position) || !Number.isFinite(sprite.size) || sprite.size < 0) {
+      throw new RangeError("ParticleRenderer sprites require finite positions and non-negative finite sizes.");
+    }
+    const radius = sprite.size * 0.5;
+    min.x = Math.min(min.x, sprite.position.x - radius);
+    min.y = Math.min(min.y, sprite.position.y - radius);
+    min.z = Math.min(min.z, sprite.position.z - radius);
+    max.x = Math.max(max.x, sprite.position.x + radius);
+    max.y = Math.max(max.y, sprite.position.y + radius);
+    max.z = Math.max(max.z, sprite.position.z + radius);
+  }
+  return { min, max };
+}
+
+function distanceSquared(a: Vector3Like, b: Vector3Like): number {
+  const x = a.x - b.x;
+  const y = a.y - b.y;
+  const z = a.z - b.z;
+  return x * x + y * y + z * z;
+}
+
+function isFiniteVector(value: Vector3Like): boolean {
+  return Number.isFinite(value.x) && Number.isFinite(value.y) && Number.isFinite(value.z);
+}

package/src/effects/ParticleSystem.ts

@@ -0,0 +1,333 @@
+import {
+  addScaledVector3,
+  normalizedParticleAge,
+  setVector3,
+  type Particle,
+} from "./Particle.js";
+import { ParticleEmitter } from "./ParticleEmitter.js";
+import type { GPUParticleBackend } from "./GPUParticleBackend.js";
+import { applyParticleModules, type ParticleModule, type ParticleUpdateContext } from "./ParticleModule.js";
+
+export interface ParticleSystemStats {
+  liveCount: number;
+  capacity: number;
+  spawnedCount: number;
+  killedCount: number;
+  droppedCount: number;
+  bufferUploads: number;
+  uploadedBytes: number;
+  gpuSpawns: number;
+  gpuUpdates: number;
+}
+
+export interface ParticleSystemOptions {
+  maxParticles?: number;
+  emitters?: readonly ParticleEmitter[];
+  modules?: readonly ParticleModule[];
+  gpuBackend?: GPUParticleBackend;
+  preferGPU?: boolean;
+}
+
+export class ParticleSystem {
+  readonly particles: Particle[] = [];
+  readonly emitters: ParticleEmitter[] = [];
+  readonly modules: ParticleModule[] = [];
+  readonly maxParticles: number;
+
+  elapsedTime = 0;
+  paused = false;
+
+  private stats: ParticleSystemStats;
+  private gpuBackend?: GPUParticleBackend;
+  private preferGPU: boolean;
+
+  constructor(options: ParticleSystemOptions = {}) {
+    this.maxParticles = options.maxParticles ?? 1000;
+    if (!Number.isInteger(this.maxParticles) || this.maxParticles <= 0) {
+      throw new RangeError("ParticleSystem maxParticles must be a positive integer.");
+    }
+
+    this.emitters.push(...(options.emitters ?? []));
+    this.modules.push(...(options.modules ?? []));
+    this.gpuBackend = options.gpuBackend;
+    this.preferGPU = options.preferGPU ?? options.gpuBackend !== undefined;
+    this.stats = {
+      liveCount: 0,
+      capacity: this.maxParticles,
+      spawnedCount: 0,
+      killedCount: 0,
+      droppedCount: 0,
+      bufferUploads: 0,
+      uploadedBytes: 0,
+      gpuSpawns: 0,
+      gpuUpdates: 0,
+    };
+  }
+
+  addEmitter(emitter: ParticleEmitter): this {
+    this.emitters.push(emitter);
+    return this;
+  }
+
+  addModule(module: ParticleModule): this {
+    this.modules.push(module);
+    return this;
+  }
+
+  setGPUBackend(backend: GPUParticleBackend | undefined, preferGPU = backend !== undefined): this {
+    this.gpuBackend = backend;
+    this.preferGPU = preferGPU;
+    return this;
+  }
+
+  clear(): void {
+    this.stats.killedCount += this.particles.length;
+    this.particles.length = 0;
+    this.stats.liveCount = 0;
+  }
+
+  dispose(): void {
+    this.clear();
+    this.emitters.length = 0;
+    this.modules.length = 0;
+    this.paused = true;
+  }
+
+  update(deltaTime: number): void {
+    if (!Number.isFinite(deltaTime) || deltaTime < 0) {
+      throw new RangeError("ParticleSystem.update deltaTime must be a finite non-negative number.");
+    }
+
+    if (this.paused || deltaTime === 0) {
+      return;
+    }
+
+    this.spawn(deltaTime);
+    this.integrate(deltaTime);
+    this.compactDeadParticles();
+    this.elapsedTime += deltaTime;
+    this.stats.liveCount = this.particles.length;
+  }
+
+  async updateOnGPU(deltaTime: number, backend: GPUParticleBackend): Promise<void> {
+    if (!Number.isFinite(deltaTime) || deltaTime < 0) {
+      throw new RangeError("ParticleSystem.updateOnGPU deltaTime must be a finite non-negative number.");
+    }
+
+    if (this.paused || deltaTime === 0) {
+      return;
+    }
+
+    const spawnedParticles = this.spawn(deltaTime);
+    await this.initializeSpawnedOnGPU(spawnedParticles, backend);
+    await this.integrateOnGPU(deltaTime, backend);
+    this.compactDeadParticles();
+    this.elapsedTime += deltaTime;
+    this.stats.liveCount = this.particles.length;
+  }
+
+  async updateBest(deltaTime: number): Promise<"gpu" | "cpu"> {
+    if (this.preferGPU && this.gpuBackend?.capabilities.supported) {
+      await this.updateOnGPU(deltaTime, this.gpuBackend);
+      return "gpu";
+    }
+
+    this.update(deltaTime);
+    return "cpu";
+  }
+
+  getStats(): ParticleSystemStats {
+    return { ...this.stats, liveCount: this.particles.length };
+  }
+
+  recordBufferUpload(bytes: number): void {
+    if (!Number.isFinite(bytes) || bytes < 0) {
+      throw new RangeError("ParticleSystem buffer upload bytes must be a finite non-negative number.");
+    }
+
+    this.stats.bufferUploads += 1;
+    this.stats.uploadedBytes += bytes;
+  }
+
+  private spawn(deltaTime: number): Particle[] {
+    const spawnedParticles: Particle[] = [];
+    for (const emitter of this.emitters) {
+      const capacity = this.maxParticles - this.particles.length;
+      const result = emitter.emit(deltaTime, capacity);
+
+      this.stats.droppedCount += Math.max(0, result.requested - result.emitted);
+      this.stats.spawnedCount += result.emitted;
+
+      for (const particle of result.particles) {
+        const context = this.createContext(deltaTime, particle);
+        applyParticleModules(this.modules, "onSpawn", particle, context);
+        this.particles.push(particle);
+        spawnedParticles.push(particle);
+      }
+    }
+    return spawnedParticles;
+  }
+
+  private async initializeSpawnedOnGPU(spawnedParticles: readonly Particle[], backend: GPUParticleBackend): Promise<void> {
+    if (!backend.spawn || spawnedParticles.length === 0) {
+      return;
+    }
+
+    const positions = new Float32Array(spawnedParticles.length * 4);
+    const velocities = new Float32Array(spawnedParticles.length * 4);
+    const accelerations = new Float32Array(spawnedParticles.length * 4);
+
+    for (let index = 0; index < spawnedParticles.length; index += 1) {
+      const particle = spawnedParticles[index]!;
+      const offset = index * 4;
+      positions[offset] = particle.position.x;
+      positions[offset + 1] = particle.position.y;
+      positions[offset + 2] = particle.position.z;
+      positions[offset + 3] = particle.age;
+      velocities[offset] = particle.velocity.x;
+      velocities[offset + 1] = particle.velocity.y;
+      velocities[offset + 2] = particle.velocity.z;
+      accelerations[offset] = particle.acceleration.x;
+      accelerations[offset + 1] = particle.acceleration.y;
+      accelerations[offset + 2] = particle.acceleration.z;
+    }
+
+    const result = await backend.spawn({
+      positions,
+      velocities,
+      accelerations,
+      count: spawnedParticles.length,
+    });
+
+    for (let index = 0; index < spawnedParticles.length; index += 1) {
+      const particle = spawnedParticles[index]!;
+      const offset = index * 4;
+      particle.position.x = result.positions[offset];
+      particle.position.y = result.positions[offset + 1];
+      particle.position.z = result.positions[offset + 2];
+      particle.age = result.positions[offset + 3];
+      setVector3(particle.previousPosition, particle.position);
+      particle.velocity.x = result.velocities[offset];
+      particle.velocity.y = result.velocities[offset + 1];
+      particle.velocity.z = result.velocities[offset + 2];
+      particle.acceleration.x = result.accelerations[offset];
+      particle.acceleration.y = result.accelerations[offset + 1];
+      particle.acceleration.z = result.accelerations[offset + 2];
+    }
+
+    this.stats.gpuSpawns += 1;
+    this.recordBufferUpload(positions.byteLength + velocities.byteLength + accelerations.byteLength + 16);
+  }
+
+  private integrate(deltaTime: number): void {
+    for (const particle of this.particles) {
+      if (!particle.alive) {
+        continue;
+      }
+
+      const context = this.createContext(deltaTime, particle);
+      applyParticleModules(this.modules, "update", particle, context);
+
+      setVector3(particle.previousPosition, particle.position);
+      addScaledVector3(particle.velocity, particle.acceleration, deltaTime);
+      addScaledVector3(particle.position, particle.velocity, deltaTime);
+      particle.rotation += particle.angularVelocity * deltaTime;
+      particle.age += deltaTime;
+
+      applyParticleModules(this.modules, "afterIntegrate", particle, this.createContext(deltaTime, particle));
+
+      if (particle.age >= particle.lifetime) {
+        particle.alive = false;
+      }
+    }
+  }
+
+  private async integrateOnGPU(deltaTime: number, backend: GPUParticleBackend): Promise<void> {
+    const liveParticles = this.particles.filter((particle) => particle.alive);
+    if (liveParticles.length === 0) {
+      return;
+    }
+
+    for (const particle of liveParticles) {
+      const context = this.createContext(deltaTime, particle);
+      applyParticleModules(this.modules, "update", particle, context);
+      setVector3(particle.previousPosition, particle.position);
+    }
+
+    const positions = new Float32Array(liveParticles.length * 4);
+    const velocities = new Float32Array(liveParticles.length * 4);
+    const accelerations = new Float32Array(liveParticles.length * 4);
+
+    for (let index = 0; index < liveParticles.length; index += 1) {
+      const particle = liveParticles[index];
+      const offset = index * 4;
+      positions[offset] = particle.position.x;
+      positions[offset + 1] = particle.position.y;
+      positions[offset + 2] = particle.position.z;
+      positions[offset + 3] = particle.age;
+      velocities[offset] = particle.velocity.x;
+      velocities[offset + 1] = particle.velocity.y;
+      velocities[offset + 2] = particle.velocity.z;
+      accelerations[offset] = particle.acceleration.x;
+      accelerations[offset + 1] = particle.acceleration.y;
+      accelerations[offset + 2] = particle.acceleration.z;
+    }
+
+    const result = await backend.update({
+      positions,
+      velocities,
+      accelerations,
+      deltaTime,
+      count: liveParticles.length,
+    });
+
+    for (let index = 0; index < liveParticles.length; index += 1) {
+      const particle = liveParticles[index];
+      const offset = index * 4;
+      particle.position.x = result.positions[offset];
+      particle.position.y = result.positions[offset + 1];
+      particle.position.z = result.positions[offset + 2];
+      particle.age = result.positions[offset + 3];
+      particle.velocity.x = result.velocities[offset];
+      particle.velocity.y = result.velocities[offset + 1];
+      particle.velocity.z = result.velocities[offset + 2];
+      particle.rotation += particle.angularVelocity * deltaTime;
+
+      applyParticleModules(this.modules, "afterIntegrate", particle, this.createContext(deltaTime, particle));
+
+      if (particle.age >= particle.lifetime) {
+        particle.alive = false;
+      }
+    }
+
+    this.stats.gpuUpdates += 1;
+    this.recordBufferUpload(positions.byteLength + velocities.byteLength + accelerations.byteLength + 16);
+  }
+
+  private compactDeadParticles(): void {
+    let write = 0;
+    let killed = 0;
+
+    for (let read = 0; read < this.particles.length; read += 1) {
+      const particle = this.particles[read];
+      if (particle.alive) {
+        this.particles[write] = particle;
+        write += 1;
+      } else {
+        killed += 1;
+      }
+    }
+
+    this.particles.length = write;
+    this.stats.killedCount += killed;
+  }
+
+  private createContext(deltaTime: number, particle: Particle): ParticleUpdateContext {
+    return {
+      deltaTime,
+      elapsedTime: this.elapsedTime,
+      normalizedAge: normalizedParticleAge(particle),
+      random: this.emitters[0]?.random ?? Math.random,
+    };
+  }
+}

package/src/effects/SizeModule.ts

@@ -0,0 +1,56 @@
+import type { Particle } from "./Particle.js";
+import type { ParticleModule, ParticleUpdateContext } from "./ParticleModule.js";
+
+export interface SizeKeyframe {
+  time: number;
+  size: number;
+}
+
+function validateCurve(keyframes: readonly SizeKeyframe[]): void {
+  if (keyframes.length === 0) {
+    throw new RangeError("SizeModule requires at least one size keyframe.");
+  }
+
+  let previous = -Number.POSITIVE_INFINITY;
+  for (const keyframe of keyframes) {
+    if (keyframe.time < 0 || keyframe.time > 1 || keyframe.time < previous) {
+      throw new RangeError("SizeModule keyframe times must be sorted in the normalized range [0, 1].");
+    }
+    if (!Number.isFinite(keyframe.size) || keyframe.size < 0) {
+      throw new RangeError("SizeModule keyframe sizes must be finite non-negative numbers.");
+    }
+    previous = keyframe.time;
+  }
+}
+
+export function sampleSizeCurve(keyframes: readonly SizeKeyframe[], time: number): number {
+  if (time <= keyframes[0].time) {
+    return keyframes[0].size;
+  }
+
+  for (let index = 1; index < keyframes.length; index += 1) {
+    const next = keyframes[index];
+    if (time <= next.time) {
+      const previous = keyframes[index - 1];
+      const span = next.time - previous.time || 1;
+      const alpha = (time - previous.time) / span;
+      return previous.size + (next.size - previous.size) * alpha;
+    }
+  }
+
+  return keyframes[keyframes.length - 1].size;
+}
+
+export class SizeModule implements ParticleModule {
+  readonly name = "SizeModule";
+  readonly curve: readonly SizeKeyframe[];
+
+  constructor(curve: readonly SizeKeyframe[]) {
+    this.curve = curve;
+    validateCurve(curve);
+  }
+
+  update(particle: Particle, context: ParticleUpdateContext): void {
+    particle.size = sampleSizeCurve(this.curve, context.normalizedAge);
+  }
+}