babylon.quarks 0.26.0 → 0.28.0

package/src/effectDocumentJSON.ts

@@ -0,0 +1,261 @@
+import type {BaseTexture} from '@babylonjs/core/Materials/Textures/baseTexture';
+import type {
+    MeshLighting,
+    MeshRim,
+    ParticleErosionOptions,
+    ParticleGradientMap,
+    ParticleUVDistortionOptions,
+    TextureUV,
+} from './batchSettings';
+import type {QuarksEffectJSON, QuarksNodeJSON, QuarksTextureJSON} from './QuarksSerializer';
+import type {ParticleMaterialSource} from './system/materialResolve';
+
+// The parts of an effect document `QuarksLoader` reads: what `serializeEffect` writes, and the
+// three.js object format three.quarks files use. Every field a file may leave out is optional; the
+// loader checks what it reads, so a field of the wrong kind warns or is skipped, never throws.
+
+/** Mesh data as typed arrays, the form a loaded geometry takes. */
+export interface GeometryArrays {
+    /** `x, y, z` per vertex. */
+    positions: Float32Array;
+    /** Three per triangle. */
+    indices: Uint32Array | Uint16Array;
+    /** First UV set, `u, v` per vertex. */
+    uvs?: Float32Array;
+    /** Second UV set, `u, v` per vertex. */
+    uvs2?: Float32Array;
+    /** `x, y, z` per vertex. */
+    normals?: Float32Array;
+}
+
+/** A three.js `BufferAttribute`, inline or as a view into an interleaved buffer. */
+export interface BufferAttributeJSON {
+    /** The values, when the attribute holds its own. */
+    array?: number[];
+    /** Components per vertex. */
+    itemSize?: number;
+    /** The typed array type, e.g. `'Float32Array'` or `'Uint16Array'`. */
+    type?: string;
+    /** Set when the attribute reads an interleaved buffer. */
+    isInterleavedBufferAttribute?: boolean;
+    /** The interleaved buffer's uuid. */
+    data?: string;
+    /** Where the attribute starts in each interleaved vertex. */
+    offset?: number;
+}
+
+/** A three.js interleaved buffer: a stride over one of the geometry's array buffers. */
+export interface InterleavedBufferJSON {
+    /** The array buffer's uuid. */
+    buffer: string;
+    /** Floats per vertex. */
+    stride: number;
+}
+
+/** The vertex attributes of a three.js `BufferGeometry` that quarks reads. */
+export interface BufferGeometryAttributesJSON {
+    /** Positions, `x, y, z` per vertex. */
+    position?: BufferAttributeJSON;
+    /** The first UV set. */
+    uv?: BufferAttributeJSON;
+    /** The second UV set, as three.js r151 on names it. */
+    uv1?: BufferAttributeJSON;
+    /** The second UV set, as three.js before r151 names it. */
+    uv2?: BufferAttributeJSON;
+    /** Normals, `x, y, z` per vertex. */
+    normal?: BufferAttributeJSON;
+}
+
+/** The index of a three.js `BufferGeometry`. */
+export interface BufferIndexJSON {
+    /** `'Uint16Array'` or `'Uint32Array'`; 32-bit when absent. */
+    type?: string;
+    /** Three per triangle. */
+    array: number[];
+}
+
+/** The `data` of a three.js `BufferGeometry`. */
+export interface BufferGeometryDataJSON {
+    /** The vertex attributes. */
+    attributes?: BufferGeometryAttributesJSON;
+    /** The triangle indices. */
+    index?: BufferIndexJSON;
+    /** Interleaved buffers by uuid. */
+    interleavedBuffers?: {[uuid: string]: InterleavedBufferJSON};
+    /** The bytes of the interleaved buffers by uuid, as 32-bit words. */
+    arrayBuffers?: {[uuid: string]: number[] | ArrayBuffer};
+}
+
+/** A three.js `BufferGeometry`. */
+export interface BufferGeometryJSON {
+    /** Unique within the file. */
+    uuid: string;
+    /** Always `'BufferGeometry'`. */
+    type: 'BufferGeometry';
+    /** The vertex data. */
+    data?: BufferGeometryDataJSON;
+}
+
+/** A three.js `PlaneGeometry`: a quad in XY. */
+export interface PlaneGeometryJSON {
+    /** Unique within the file. */
+    uuid: string;
+    /** Always `'PlaneGeometry'`. */
+    type: 'PlaneGeometry';
+    /** Default 1. */
+    width?: number;
+    /** Default 1. */
+    height?: number;
+}
+
+/** A three.js `SphereGeometry`. */
+export interface SphereGeometryJSON {
+    /** Unique within the file. */
+    uuid: string;
+    /** Always `'SphereGeometry'`. */
+    type: 'SphereGeometry';
+    /** Default 0.5. */
+    radius?: number;
+    /** Default 16, at least 3. */
+    widthSegments?: number;
+    /** Default 8, at least 2. */
+    heightSegments?: number;
+    /** Default 0. */
+    phiStart?: number;
+    /** Default 2π. */
+    phiLength?: number;
+    /** Default 0. */
+    thetaStart?: number;
+    /** Default π. */
+    thetaLength?: number;
+}
+
+/**
+ * Quarks' own mesh data, inline (see `QuarksGeometryJSON`) or in its own file at `url`, which
+ * `QuarksLoader.resolveResources` inlines before parsing.
+ */
+export interface QuarksGeometryEntryJSON {
+    /** Unique within the file. */
+    uuid: string;
+    /** Always `'QuarksGeometry'`. */
+    type: 'QuarksGeometry';
+    /** The file that holds the data, until it is inlined. */
+    url?: string;
+    /** `x, y, z` per vertex. */
+    positions?: number[];
+    /** Three per triangle. */
+    indices?: number[];
+    /** First UV set. */
+    uvs?: number[];
+    /** Second UV set. */
+    uvs2?: number[];
+    /** `x, y, z` per vertex. */
+    normals?: number[];
+}
+
+/** A geometry entry of an effect document. */
+export type EffectGeometryJSON = QuarksGeometryEntryJSON | BufferGeometryJSON | PlaneGeometryJSON | SphereGeometryJSON;
+
+/** An image entry of an effect document. */
+export interface EffectImageJSON {
+    /** Unique within the file. */
+    uuid: string;
+    /** Relative to the file's base url, absolute, or a `data:` url; absent for an image with no file. */
+    url?: string;
+}
+
+/**
+ * A texture slot of a {@link QuarksMaterialJSON}: a texture uuid in a file, the texture itself once
+ * a loader resolved it, or null for a texture that could not be made.
+ */
+export type MaterialTextureRef = string | BaseTexture | null;
+
+/** The gradient mapping of a {@link QuarksMaterialJSON}; see `ParticleSystem.gradientMap`. */
+export interface GradientMapJSON extends Omit<Partial<ParticleGradientMap>, 'ramp'> {
+    /** The ramp texture. */
+    ramp?: MaterialTextureRef;
+}
+
+/** The erosion of a {@link QuarksMaterialJSON}; see `ParticleSystem.erosion`. */
+export type ErosionJSON = Omit<ParticleErosionOptions, 'mask'> & {
+    /** The mask texture. */
+    mask?: MaterialTextureRef;
+};
+
+/** The UV distortion of a {@link QuarksMaterialJSON}; see `ParticleSystem.uvDistortion`. */
+export type UVDistortionJSON = Omit<ParticleUVDistortionOptions, 'map'> & {
+    /** The distortion texture. */
+    map?: MaterialTextureRef;
+};
+
+/**
+ * A material entry of an effect document: what a particle system's material writes (`type`
+ * `'QuarksMaterial'`), or a three.js material, whose `map` and `blending` the loader reads too.
+ */
+export interface QuarksMaterialJSON {
+    /** Unique within the file. */
+    uuid: string;
+    /** `'QuarksMaterial'`, or the three.js material type. */
+    type?: string;
+    /** Whether the particles blend. Default true. */
+    transparent?: boolean;
+    /** A Babylon alpha mode constant. */
+    alphaMode?: number;
+    /** A three.js blending code (1 normal, 2 additive, 3 subtractive, 4 multiply), read without `alphaMode`. */
+    blending?: number;
+    /** A three.js side code; 2 draws both faces. */
+    side?: number;
+    /** Default true. */
+    depthTest?: boolean;
+    /** Default false. */
+    depthWrite?: boolean;
+    /** Default 0. */
+    alphaTest?: number;
+    /** The particle texture. */
+    texture?: MaterialTextureRef;
+    /** A three.js material's texture, read when there is no `texture`. */
+    map?: string;
+    /** A 3×2 environment atlas for reflections. */
+    reflectionAtlas?: MaterialTextureRef;
+    /** How strong the reflection is. */
+    reflectionLevel?: number;
+    /** Mesh particle lighting; `'fixed'` when absent. */
+    lighting?: MeshLighting;
+    /** Mesh particle rim. */
+    rim?: Partial<MeshRim>;
+    /** The particle texture's UV transform. */
+    mapUV?: Partial<TextureUV>;
+    /** Gradient mapping. */
+    gradientMap?: GradientMapJSON;
+    /** Erosion. */
+    erosion?: ErosionJSON;
+    /** UV distortion. */
+    uvDistortion?: UVDistortionJSON;
+    /** While writing: the material the system read its settings from. Never written to a file. */
+    sourceMaterial?: ParticleMaterialSource;
+}
+
+/**
+ * A geometry as an effect's resources hold it: an entry of the document, or, once loaded, its
+ * typed arrays.
+ */
+export type GeometryEntry = EffectGeometryJSON | GeometryArrays;
+
+/**
+ * An effect document as `QuarksLoader` reads it: what `serializeEffect` writes
+ * (`QuarksEffectJSON`), or a three.quarks / three.js object file. Only `object` is required.
+ */
+export interface EffectDocumentJSON {
+    /** What wrote the file. */
+    metadata?: Partial<QuarksEffectJSON['metadata']>;
+    /** Meshes the nodes and particle systems use. */
+    geometries?: EffectGeometryJSON[];
+    /** Materials, referred to by uuid. */
+    materials?: QuarksMaterialJSON[];
+    /** Textures, referred to by uuid. */
+    textures?: QuarksTextureJSON[];
+    /** Image files the textures load. */
+    images?: EffectImageJSON[];
+    /** The effect's root node. */
+    object: QuarksNodeJSON;
+}

package/src/effectResources.ts

@@ -0,0 +1,76 @@
+import type {Material} from '@babylonjs/core/Materials/material';
+import type {BaseTexture} from '@babylonjs/core/Materials/Textures/baseTexture';
+import type {TransformNode} from '@babylonjs/core/Meshes/transformNode';
+import type {Node} from '@babylonjs/core/node';
+
+/** What an effect root holds a count on: the textures it draws with and the materials made for the effect. */
+interface EffectResources {
+    textures: Set<BaseTexture>;
+    materials: Set<Material>;
+}
+
+const owned = new WeakMap<Node, EffectResources>();
+/** How many effect roots hold each texture and material. */
+const holders = new WeakMap<BaseTexture | Material, number>();
+
+/**
+ * Records that `root` uses `textures` and the `materials` made for the effect. Each is freed once
+ * the last root holding it is disposed, however that happens: {@link disposeEffect},
+ * `root.dispose()`, a parent's dispose or the scene's.
+ */
+export function retainEffectResources(
+    root: TransformNode,
+    textures: Iterable<BaseTexture>,
+    materials: Iterable<Material>
+): void {
+    if (owned.has(root)) {
+        return;
+    }
+    const resources: EffectResources = {textures: new Set(textures), materials: new Set(materials)};
+    for (const resource of [...resources.textures, ...resources.materials]) {
+        holders.set(resource, (holders.get(resource) ?? 0) + 1);
+    }
+    owned.set(root, resources);
+    root.onDisposeObservable.addOnce(() => releaseEffectResources(root));
+}
+
+/**
+ * Gives `copy` a hold on the textures and materials the effect `source` belongs to holds, as a
+ * copy of the effect, or of a node in it, draws with them too.
+ */
+export function shareEffectResources(source: TransformNode, copy: TransformNode): void {
+    for (let node: Node | null = source; node !== null; node = node.parent) {
+        const resources = owned.get(node);
+        if (resources !== undefined) {
+            retainEffectResources(copy, resources.textures, resources.materials);
+            return;
+        }
+    }
+}
+
+function releaseEffectResources(root: Node): void {
+    const resources = owned.get(root);
+    if (resources === undefined) {
+        return;
+    }
+    owned.delete(root);
+    for (const resource of [...resources.materials, ...resources.textures]) {
+        const count = (holders.get(resource) ?? 1) - 1;
+        if (count > 0) {
+            holders.set(resource, count);
+        } else {
+            holders.delete(resource);
+            resource.dispose();
+        }
+    }
+}
+
+/**
+ * Disposes an effect root and its nodes and systems, and each material and texture it holds once no
+ * other effect root holds it. A root nothing was recorded for is only disposed.
+ */
+export function disposeEffect(root: TransformNode): void {
+    root.dispose();
+    // A root disposed earlier, before its hold was recorded, still lets go.
+    releaseEffectResources(root);
+}

package/src/envAtlas.ts

@@ -2,8 +2,20 @@ import {BaseTexture} from '@babylonjs/core/Materials/Textures/baseTexture';
 import {Texture} from '@babylonjs/core/Materials/Textures/texture';
 import {Scene} from '@babylonjs/core/scene';
 
-const atlasByCube = new WeakMap<BaseTexture, Texture>();
-const pendingByCube = new WeakMap<BaseTexture, Promise<Texture | null>>();
+/**
+ * Atlases by cube, then by the scene they were built for: a texture belongs to one scene and one
+ * engine, so a second scene (an editor preview, a second canvas) gets an atlas of its own.
+ */
+const atlasesByCube = new WeakMap<BaseTexture, Map<Scene, Texture>>();
+const pendingByCube = new WeakMap<BaseTexture, Map<Scene, Promise<Texture | null>>>();
+/** Atlases this module built, which it disposes; an atlas given to {@link cacheEnvAtlas} stays the caller's. */
+const builtAtlases = new WeakSet<Texture>();
+/** The faces each cube's atlas failed to build from: not tried, or warned about, again. */
+const failedFaces = new WeakMap<BaseTexture, string>();
+/** Atlases whose dispose this module already listens to. */
+const watchedAtlases = new WeakSet<Texture>();
+/** Cubes whose dispose this module already listens to. */
+const watchedCubes = new WeakSet<BaseTexture>();
 
 /** Reads the six face URLs from a Babylon CubeTexture (px py pz nx ny nz). */
 export function cubeFaceUrls(reflection: BaseTexture | null | undefined): string[] | null {
@@ -15,14 +27,86 @@ export function cubeFaceUrls(reflection: BaseTexture | null | undefined): string
     return files?.length === 6 ? files.slice() : null;
 }
 
-/** Returns a previously built atlas for this cube, if any. */
-export function getCachedEnvAtlas(cube: BaseTexture): Texture | null {
-    return atlasByCube.get(cube) ?? null;
+/** The scene a texture belongs to, or null for a disposed texture or one with no scene. */
+function sceneOf(texture: BaseTexture): Scene | null {
+    return (texture as {getScene?: () => Scene | null}).getScene?.() ?? null;
 }
 
-/** Stores an atlas for a cube source (tests / prebuilt atlases). */
+/**
+ * Returns the atlas already built or cached for this cube in `scene`, if any.
+ *
+ * @param cube - The cube texture the atlas was made from.
+ * @param scene - The scene the atlas must belong to. Defaults to the cube's own scene.
+ */
+export function getCachedEnvAtlas(cube: BaseTexture, scene: Scene | null = sceneOf(cube)): Texture | null {
+    return (scene && atlasesByCube.get(cube)?.get(scene)) || null;
+}
+
+/**
+ * Stores a prebuilt atlas for a cube in the atlas's scene, so systems that use the cube in that
+ * scene take it instead of building one. The atlas stays the caller's: quarks never disposes it,
+ * and drops it from the cache when it, or the cube, is disposed.
+ *
+ * @param cube - The cube texture the atlas stands in for.
+ * @param atlas - A 3×2 atlas in the layout of {@link createEnvAtlasFromFaceUrls}.
+ */
 export function cacheEnvAtlas(cube: BaseTexture, atlas: Texture): void {
-    atlasByCube.set(cube, atlas);
+    const scene = sceneOf(atlas) ?? sceneOf(cube);
+    if (scene) {
+        store(cube, scene, atlas);
+    } else {
+        console.warn('[babylon.quarks] cacheEnvAtlas: neither the atlas nor the cube has a scene; not cached');
+    }
+}
+
+/**
+ * Drops the atlases made for `cube` from the cache and disposes the ones quarks built. Runs by
+ * itself when the cube is disposed; call it when an environment is swapped out but the cube is
+ * kept. Systems that use the cube build a new atlas the next time their material is resolved.
+ *
+ * @param cube - The cube texture whose atlases to drop.
+ * @param scene - Only the atlas for this scene. Defaults to every scene.
+ */
+export function disposeEnvAtlas(cube: BaseTexture, scene?: Scene): void {
+    failedFaces.delete(cube);
+    const atlases = atlasesByCube.get(cube);
+    if (!atlases) {
+        return;
+    }
+    for (const [atlasScene, atlas] of [...atlases]) {
+        if (scene && atlasScene !== scene) {
+            continue;
+        }
+        atlases.delete(atlasScene);
+        if (builtAtlases.has(atlas)) {
+            atlas.dispose();
+        }
+    }
+}
+
+function store(cube: BaseTexture, scene: Scene, atlas: Texture): void {
+    let atlases = atlasesByCube.get(cube);
+    if (!atlases) {
+        atlases = new Map();
+        atlasesByCube.set(cube, atlases);
+    }
+    atlases.set(scene, atlas);
+    // A scene disposes its textures, so this also lets go of a disposed scene.
+    if (!watchedAtlases.has(atlas) && atlas.onDisposeObservable) {
+        watchedAtlases.add(atlas);
+        atlas.onDisposeObservable.addOnce(() => {
+            if (atlasesByCube.get(cube)?.get(scene) === atlas) {
+                atlasesByCube.get(cube)!.delete(scene);
+            }
+        });
+    }
+    if (!watchedCubes.has(cube) && cube.onDisposeObservable) {
+        watchedCubes.add(cube);
+        cube.onDisposeObservable.addOnce(() => {
+            watchedCubes.delete(cube);
+            disposeEnvAtlas(cube);
+        });
+    }
 }
 
 /**
@@ -63,23 +147,32 @@ export const envAtlasBuilder = {
 };
 
 /**
- * Ensures a 3×2 env atlas exists for a CubeTexture. Returns a cached atlas
- * synchronously when available; otherwise starts (or joins) an async build and
- * invokes onReady when the atlas is usable.
+ * Ensures a 3×2 env atlas exists for a CubeTexture in `scene`. Returns a cached atlas
+ * synchronously when available; otherwise starts (or joins) an async build and invokes onReady
+ * when the atlas is usable. A cube disposed before its build finishes gets no atlas. A build that
+ * fails warns once and is not tried again until the cube's faces change or
+ * {@link disposeEnvAtlas} is called for it; {@link cacheEnvAtlas} still supplies an atlas.
  */
 export function ensureEnvAtlasFromCube(
     cube: BaseTexture,
     scene: Scene,
     onReady: (atlas: Texture) => void
 ): Texture | null {
-    const cached = atlasByCube.get(cube);
+    const cached = getCachedEnvAtlas(cube, scene);
     if (cached) {
         onReady(cached);
         return cached;
     }
 
+    let pendingByScene = pendingByCube.get(cube);
+    if (!pendingByScene) {
+        pendingByScene = new Map();
+        pendingByCube.set(cube, pendingByScene);
+    }
+    const pendings = pendingByScene;
+
     const kick = () => {
-        const existingPending = pendingByCube.get(cube);
+        const existingPending = pendings.get(scene);
         if (existingPending) {
             existingPending.then((atlas) => {
                 if (atlas) {
@@ -90,24 +183,39 @@ export function ensureEnvAtlasFromCube(
         }
 
         const urls = cubeFaceUrls(cube);
-        if (!urls) {
+        if (!urls || failedFaces.get(cube) === urls.join('\n')) {
             return;
         }
 
+        let cubeDisposed = false;
+        // Removed once the build settles, so it does not keep the scene and onReady alive.
+        const cubeObserver = cube.onDisposeObservable?.addOnce(() => (cubeDisposed = true));
+        const settle = () => {
+            pendings.delete(scene);
+            if (cubeObserver) {
+                cube.onDisposeObservable.remove(cubeObserver);
+            }
+        };
         const pending = envAtlasBuilder
             .createFromFaceUrls(urls, scene)
             .then((atlas) => {
-                atlasByCube.set(cube, atlas);
-                pendingByCube.delete(cube);
+                settle();
+                if (cubeDisposed || scene.isDisposed) {
+                    atlas.dispose();
+                    return null;
+                }
+                builtAtlases.add(atlas);
+                store(cube, scene, atlas);
                 onReady(atlas);
                 return atlas;
             })
             .catch((err) => {
-                pendingByCube.delete(cube);
+                settle();
+                failedFaces.set(cube, urls.join('\n'));
                 console.warn('[babylon.quarks] Failed to build env atlas from cubemap faces', err);
                 return null;
             });
-        pendingByCube.set(cube, pending);
+        pendings.set(scene, pending);
     };
 
     if (cube.isReady()) {
@@ -121,7 +229,7 @@ export function ensureEnvAtlasFromCube(
         }
     }
 
-    return atlasByCube.get(cube) ?? null;
+    return getCachedEnvAtlas(cube, scene);
 }
 
 /** Loads one image URL as an HTMLImageElement. */

package/src/geometryUtil.ts

@@ -1,4 +1,4 @@
-/** Sequential 0..N-1 indices for non-indexed triangle-list BufferGeometry (Three.js drawArrays). */
+/** `indices` when there are some, else `0..N-1`: each three vertices of `positions` one triangle. */
 export function ensureTriangleIndices(
     positions: Float32Array,
     indices?: Uint32Array | Uint16Array