@scenography/engine 0.3.1 → 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Javier López Úbeda
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.cjs

@@ -479,8 +479,126 @@ const EDGES = "edges";
 */
 const EYE_HEIGHT = "eyeHeight";
 //#endregion
+//#region src/builders/textureCache.ts
+/** Two surfaces can share a texture only at the same tiling and color space. */
+const textureKey = (src, repeat, srgb) => `${src}|${repeat[0]}x${repeat[1]}|${srgb ? "srgb" : "linear"}`;
+/** Tiling and color space of a texture; the image arrives later from the loader. */
+const configureTexture = (texture, repeat, srgb) => {
+	texture.wrapS = three.RepeatWrapping;
+	texture.wrapT = three.RepeatWrapping;
+	texture.repeat.set(repeat[0], repeat[1]);
+	texture.colorSpace = srgb ? three.SRGBColorSpace : three.NoColorSpace;
+};
+/**
+* Shares textures between materials: the same source at the same tiling and
+* color space becomes one texture, loaded once and uploaded to the GPU once.
+* Reference counted, so releasing a material keeps the texture alive while
+* another one still samples it.
+*/
+var TextureCache = class {
+	source;
+	entries = /* @__PURE__ */ new Map();
+	owners = /* @__PURE__ */ new Map();
+	constructor(source) {
+		this.source = source;
+	}
+	/** The shared texture for a source, created on first use. */
+	acquire(src, repeat, srgb) {
+		const key = textureKey(src, repeat, srgb);
+		const existing = this.entries.get(key);
+		if (existing) {
+			existing.refs += 1;
+			return existing.texture;
+		}
+		const texture = this.source(src);
+		configureTexture(texture, repeat, srgb);
+		const entry = {
+			key,
+			texture,
+			refs: 1
+		};
+		this.entries.set(key, entry);
+		this.owners.set(texture, entry);
+		return texture;
+	}
+	/** Drop one reference; the texture is disposed when the last one goes. */
+	release(texture) {
+		const entry = this.owners.get(texture);
+		if (!entry) {
+			texture.dispose();
+			return;
+		}
+		entry.refs -= 1;
+		if (entry.refs > 0) return;
+		this.entries.delete(entry.key);
+		this.owners.delete(texture);
+		texture.dispose();
+	}
+	/** Textures currently shared. */
+	get size() {
+		return this.entries.size;
+	}
+};
+//#endregion
+//#region src/builders/texture.ts
+const textureLoader = new three.TextureLoader();
+const cache = new TextureCache((src) => textureLoader.load(src));
+/**
+* Load one map into `material[slot]`. Textures are shared: every material that
+* samples the same source at the same tiling reuses one texture object. `.exr`
+* maps go through EXRLoader, imported on demand, and are not shared because
+* they resolve asynchronously.
+*/
+const loadMap = (material, slot, src, repeat, srgb) => {
+	if (src.toLowerCase().endsWith(".exr")) {
+		import("three/examples/jsm/loaders/EXRLoader.js").then(({ EXRLoader }) => {
+			new EXRLoader().load(src, (texture) => {
+				configureTexture(texture, repeat, srgb);
+				texture.needsUpdate = true;
+				material[slot] = texture;
+				material.needsUpdate = true;
+			});
+		});
+		return;
+	}
+	material[slot] = cache.acquire(src, repeat, srgb);
+};
+/**
+* Apply a `SurfaceTexture` to a standard material. Returns whether a second UV
+* set (`uv1`) is needed — three samples `aoMap` from it, so the geometry must
+* provide one.
+*/
+const applyTexture = (material, texture) => {
+	const repeat = texture.repeat ?? [1, 1];
+	loadMap(material, "map", texture.src, repeat, true);
+	if (texture.normal) {
+		loadMap(material, "normalMap", texture.normal, repeat, false);
+		const scale = texture.normalScale ?? 1;
+		material.normalScale = new three.Vector2(scale, scale);
+	}
+	if (texture.roughness) loadMap(material, "roughnessMap", texture.roughness, repeat, false);
+	if (texture.ao) loadMap(material, "aoMap", texture.ao, repeat, false);
+	material.needsUpdate = true;
+	return texture.ao !== void 0;
+};
+/**
+* Release one reference to a texture assigned by `applyTexture`. Shared
+* textures stay alive while another material still samples them.
+*/
+const releaseTexture = (texture) => {
+	cache.release(texture);
+};
+//#endregion
 //#region src/SceneManager.ts
+const TEXTURE_SLOTS = [
+	"map",
+	"normalMap",
+	"roughnessMap",
+	"aoMap",
+	"metalnessMap"
+];
 const disposeObject = (object) => {
+	const materials = /* @__PURE__ */ new Set();
 	object.traverse((child) => {
 		const video = child.userData?.video;
 		if (video) {
@@ -490,21 +608,18 @@ const disposeObject = (object) => {
 		}
 		const mesh = child;
 		mesh.geometry?.dispose?.();
-		const dispose = (m) => {
-			const material = m;
-			for (const slot of [
-				"map",
-				"normalMap",
-				"roughnessMap",
-				"aoMap",
-				"metalnessMap"
-			]) (material?.[slot])?.dispose?.();
-			material?.dispose?.();
-		};
 		const material = mesh.material;
-		if (Array.isArray(material)) material.forEach(dispose);
-		else dispose(material);
+		if (Array.isArray(material)) for (const entry of material) materials.add(entry);
+		else if (material) materials.add(material);
 	});
+	for (const entry of materials) {
+		const material = entry;
+		for (const slot of TEXTURE_SLOTS) {
+			const texture = material[slot];
+			if (texture) releaseTexture(texture);
+		}
+		material.dispose?.();
+	}
 };
 /**
 * Owns the live three.js scene graph and keeps it in sync with a `Scene`
@@ -954,50 +1069,6 @@ function createGallery(scene, options) {
 	};
 }
 //#endregion
-//#region src/builders/texture.ts
-const textureLoader = new three.TextureLoader();
-/** Configure a loaded texture: tiling + color space (sRGB only for color maps). */
-const configure = (tex, repeat, srgb) => {
-	tex.wrapS = three.RepeatWrapping;
-	tex.wrapT = three.RepeatWrapping;
-	tex.repeat.set(repeat[0], repeat[1]);
-	tex.colorSpace = srgb ? three.SRGBColorSpace : three.NoColorSpace;
-	tex.needsUpdate = true;
-};
-/**
-* Load one map and assign it to `material[slot]` once ready. `.exr` maps go
-* through EXRLoader, imported on demand so it only ships in the bundle when a
-* scene actually uses an EXR map; everything else uses the image loader.
-*/
-const loadMap = (material, slot, src, repeat, srgb) => {
-	const assign = (tex) => {
-		configure(tex, repeat, srgb);
-		material[slot] = tex;
-		material.needsUpdate = true;
-	};
-	if (src.toLowerCase().endsWith(".exr")) import("three/examples/jsm/loaders/EXRLoader.js").then(({ EXRLoader }) => {
-		new EXRLoader().load(src, assign);
-	});
-	else textureLoader.load(src, assign);
-};
-/**
-* Apply a `SurfaceTexture` to a standard material. Returns whether a second UV
-* set (`uv1`) is needed — three samples `aoMap` from it, so the geometry must
-* provide one.
-*/
-const applyTexture = (material, texture) => {
-	const repeat = texture.repeat ?? [1, 1];
-	loadMap(material, "map", texture.src, repeat, true);
-	if (texture.normal) {
-		loadMap(material, "normalMap", texture.normal, repeat, false);
-		const s = texture.normalScale ?? 1;
-		material.normalScale = new three.Vector2(s, s);
-	}
-	if (texture.roughness) loadMap(material, "roughnessMap", texture.roughness, repeat, false);
-	if (texture.ao) loadMap(material, "aoMap", texture.ao, repeat, false);
-	return texture.ao !== void 0;
-};
-//#endregion
 exports.COLLIDERS = COLLIDERS;
 exports.CapabilityRegistry = CapabilityRegistry;
 exports.ControlSettings = ControlSettings;