@aura3d/rendering 1.4.0 → 1.4.2

package/src/effects/ParticleSystem.ts

@@ -1,333 +0,0 @@
-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

@@ -1,56 +0,0 @@
-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);
-  }
-}

package/src/effects/TrailModule.ts

@@ -1,72 +0,0 @@
-import { cloneVector3, type Particle, type Vector3Like } from "./Particle.js";
-import type { ParticleModule, ParticleUpdateContext } from "./ParticleModule.js";
-
-export interface TrailPoint {
-  position: Vector3Like;
-  age: number;
-}
-
-export interface TrailModuleOptions {
-  maxPoints?: number;
-  minDistance?: number;
-  lifetime?: number;
-}
-
-function distanceSquared(left: Vector3Like, right: Vector3Like): number {
-  const x = left.x - right.x;
-  const y = left.y - right.y;
-  const z = left.z - right.z;
-  return x * x + y * y + z * z;
-}
-
-export class TrailModule implements ParticleModule {
-  readonly name = "TrailModule";
-  readonly maxPoints: number;
-  readonly minDistance: number;
-  readonly lifetime: number;
-
-  constructor(options: TrailModuleOptions = {}) {
-    this.maxPoints = options.maxPoints ?? 16;
-    this.minDistance = options.minDistance ?? 0.05;
-    this.lifetime = options.lifetime ?? 0.5;
-
-    if (this.maxPoints <= 0 || this.minDistance < 0 || this.lifetime <= 0) {
-      throw new RangeError("TrailModule maxPoints and lifetime must be positive, and minDistance must be non-negative.");
-    }
-  }
-
-  onSpawn(particle: Particle, _context: ParticleUpdateContext): void {
-    particle.userData.trail = [{ position: cloneVector3(particle.position), age: 0 }] satisfies TrailPoint[];
-  }
-
-  afterIntegrate(particle: Particle, context: ParticleUpdateContext): void {
-    const trail = this.getTrail(particle);
-    for (const point of trail) {
-      point.age += context.deltaTime;
-    }
-
-    while (trail.length > 0 && trail[0].age > this.lifetime) {
-      trail.shift();
-    }
-
-    const last = trail[trail.length - 1];
-    if (!last || distanceSquared(last.position, particle.position) >= this.minDistance * this.minDistance) {
-      trail.push({ position: cloneVector3(particle.position), age: 0 });
-    }
-
-    while (trail.length > this.maxPoints) {
-      trail.shift();
-    }
-  }
-
-  getTrail(particle: Particle): TrailPoint[] {
-    const trail = particle.userData.trail;
-    if (!Array.isArray(trail)) {
-      const next: TrailPoint[] = [];
-      particle.userData.trail = next;
-      return next;
-    }
-
-    return trail as TrailPoint[];
-  }
-}

package/src/effects/VelocityModule.ts

@@ -1,75 +0,0 @@
-import type { ParticleModule, ParticleUpdateContext } from "./ParticleModule.js";
-import type { Particle, Vector3Like } from "./Particle.js";
-
-export interface VectorKeyframe {
-  time: number;
-  value: Vector3Like;
-}
-
-function validateKeyframes(keyframes: readonly VectorKeyframe[]): void {
-  if (keyframes.length === 0) {
-    throw new RangeError("VelocityModule requires at least one keyframe.");
-  }
-
-  let previous = -Number.POSITIVE_INFINITY;
-  for (const keyframe of keyframes) {
-    if (keyframe.time < 0 || keyframe.time > 1 || keyframe.time < previous) {
-      throw new RangeError("VelocityModule keyframe times must be sorted in the normalized range [0, 1].");
-    }
-    previous = keyframe.time;
-  }
-}
-
-function sampleVectorKeyframes(keyframes: readonly VectorKeyframe[], time: number): Vector3Like {
-  if (time <= keyframes[0].time) {
-    return { ...keyframes[0].value };
-  }
-
-  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 {
-        x: previous.value.x + (next.value.x - previous.value.x) * alpha,
-        y: previous.value.y + (next.value.y - previous.value.y) * alpha,
-        z: previous.value.z + (next.value.z - previous.value.z) * alpha,
-      };
-    }
-  }
-
-  return { ...keyframes[keyframes.length - 1].value };
-}
-
-export class VelocityModule implements ParticleModule {
-  readonly name = "VelocityModule";
-  readonly keyframes: readonly VectorKeyframe[];
-  readonly mode: "replace" | "add";
-
-  constructor(keyframes: readonly VectorKeyframe[], mode: "replace" | "add" = "replace") {
-    this.keyframes = keyframes;
-    this.mode = mode;
-    validateKeyframes(keyframes);
-  }
-
-  update(particle: Particle, context: ParticleUpdateContext): void {
-    const velocity = sampleVectorKeyframes(this.keyframes, context.normalizedAge);
-
-    if (this.mode === "add") {
-      particle.velocity.x += velocity.x;
-      particle.velocity.y += velocity.y;
-      particle.velocity.z += velocity.z;
-      return;
-    }
-
-    particle.velocity.x = velocity.x;
-    particle.velocity.y = velocity.y;
-    particle.velocity.z = velocity.z;
-  }
-}
-
-export function constantVelocity(value: Vector3Like, mode: "replace" | "add" = "replace"): VelocityModule {
-  return new VelocityModule([{ time: 0, value }], mode);
-}

package/src/effects/index.ts

@@ -1,15 +0,0 @@
-export * from "./Particle.js";
-export * from "./ParticleEmitter.js";
-export * from "./ParticleModule.js";
-export * from "./VelocityModule.js";
-export * from "./ColorModule.js";
-export * from "./SizeModule.js";
-export * from "./ForceModule.js";
-export * from "./CollisionModule.js";
-export * from "./TrailModule.js";
-export * from "./ParticleRenderer.js";
-export * from "./ParticleRenderPass.js";
-export * from "./GPUParticleBackend.js";
-export * from "./ParticleSystem.js";
-export * from "./ParticleEffectPresets.js";
-export * from "./ParticleDiagnostics.js";