@scenography/engine 0.5.0 → 0.7.0

package/dist/index.cjs

@@ -1,5 +1,48 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 let three = require("three");
+//#region src/loading.ts
+const pending = /* @__PURE__ */ new Set();
+const listeners = /* @__PURE__ */ new Set();
+let state = {
+	loaded: 0,
+	total: 0,
+	done: true
+};
+const notify = () => {
+	for (const listener of listeners) listener(state);
+};
+/** Begin tracking a new initial asset set; resets the previous one. */
+const startLoading = (urls) => {
+	pending.clear();
+	for (const url of urls) pending.add(url);
+	state = {
+		loaded: 0,
+		total: pending.size,
+		done: pending.size === 0
+	};
+	notify();
+};
+/** Mark one initial asset as loaded; unknown URLs (lazy assets) are ignored. */
+const trackAsset = (url) => {
+	if (!pending.delete(url)) return;
+	state = {
+		loaded: state.total - pending.size,
+		total: state.total,
+		done: pending.size === 0
+	};
+	notify();
+};
+/** Current loading progress. */
+const loadingState = () => state;
+/** Subscribe to progress; the listener runs immediately with the current state. */
+const onLoading = (listener) => {
+	listeners.add(listener);
+	listener(state);
+	return () => {
+		listeners.delete(listener);
+	};
+};
+//#endregion
 //#region src/environment/EnvironmentController.ts
 /** Load an equirectangular HDRI, picking the loader by extension. */
 const loadHDRI = (src, onLoad) => {
@@ -31,6 +74,7 @@ var EnvironmentController = class {
 		this.clear();
 		if (!env) return;
 		loadHDRI(env.src, (tex) => {
+			trackAsset(env.src);
 			if (this.hash !== hash) {
 				tex.dispose();
 				return;
@@ -60,6 +104,189 @@ var EnvironmentController = class {
 	}
 };
 //#endregion
+//#region src/builders/ktx2.ts
+let loader = null;
+/**
+* Configure the shared KTX2 loader. Called by the kernel once the renderer
+* exists; `.ktx2` textures and glTF models then decode through it.
+*/
+const configureKtx2 = (renderer, path) => {
+	loader = import("three/examples/jsm/loaders/KTX2Loader.js").then(({ KTX2Loader }) => {
+		const instance = new KTX2Loader();
+		instance.setTranscoderPath(path);
+		instance.detectSupport(renderer);
+		return instance;
+	});
+};
+/** The configured loader, or null when the gallery did not set `ktx2Path`. */
+const getKtx2Loader = () => loader;
+//#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, () => trackAsset(src)));
+const ktx2Entries = /* @__PURE__ */ new Map();
+const ktx2Owners = /* @__PURE__ */ new Map();
+/**
+* KTX2 textures resolve asynchronously, so the material slot is filled through
+* a waiter list. One entry per source and tiling is shared by every material
+* that samples it, just like the image cache.
+*/
+const loadKtx2 = (material, slot, src, repeat, srgb) => {
+	const loader = getKtx2Loader();
+	if (!loader) {
+		console.warn(`KTX2 texture "${src}" needs the gallery's ktx2Path option.`);
+		return;
+	}
+	const key = textureKey(src, repeat, srgb);
+	let entry = ktx2Entries.get(key);
+	if (!entry) {
+		entry = {
+			key,
+			refs: 0,
+			waiters: []
+		};
+		ktx2Entries.set(key, entry);
+		const created = entry;
+		loader.then((ktx2) => ktx2.load(src, (texture) => {
+			configureTexture(texture, repeat, srgb);
+			texture.needsUpdate = true;
+			trackAsset(src);
+			created.texture = texture;
+			ktx2Owners.set(texture, created);
+			for (const assign of created.waiters) assign(texture);
+			created.waiters = [];
+		}, void 0, (error) => console.error(`Failed to load KTX2 texture "${src}".`, error)));
+	}
+	entry.refs += 1;
+	if (entry.texture) {
+		material[slot] = entry.texture;
+		material.needsUpdate = true;
+	} else entry.waiters.push((texture) => {
+		material[slot] = texture;
+		material.needsUpdate = true;
+	});
+};
+/**
+* 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; `.ktx2` maps share through their own cache.
+*/
+const loadMap = (material, slot, src, repeat, srgb) => {
+	if (src.toLowerCase().endsWith(".ktx2")) {
+		loadKtx2(material, slot, src, repeat, srgb);
+		return;
+	}
+	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;
+				trackAsset(src);
+				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) => {
+	const ktx2 = ktx2Owners.get(texture);
+	if (!ktx2) {
+		cache.release(texture);
+		return;
+	}
+	ktx2.refs -= 1;
+	if (ktx2.refs > 0) return;
+	ktx2Owners.delete(texture);
+	ktx2Entries.delete(ktx2.key);
+	texture.dispose();
+};
+//#endregion
 //#region src/interaction/InteractionController.ts
 const HIGHLIGHT_COLOR = "#ef4444";
 const HIGHLIGHT_THICKNESS = 1.5;
@@ -503,116 +730,6 @@ 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",
@@ -656,12 +773,24 @@ var SceneManager = class {
 	root;
 	plugins;
 	capabilities;
+	view;
 	/** Mounted plugin elements, per kind, keyed by element id ("" for singletons). */
 	pluginElements = /* @__PURE__ */ new Map();
-	constructor(root, plugins = [], capabilities = new CapabilityRegistry()) {
+	constructor(root, plugins = [], capabilities = new CapabilityRegistry(), view = {
+		camera: new three.PerspectiveCamera(),
+		renderer: {}
+	}) {
 		this.root = root;
 		this.plugins = plugins;
 		this.capabilities = capabilities;
+		this.view = view;
+	}
+	/** The build context handed to every plugin. */
+	context() {
+		return {
+			capabilities: this.capabilities,
+			...this.view
+		};
 	}
 	reconcile(scene) {
 		const eye = scene.camera.start.position[1];
@@ -694,7 +823,7 @@ var SceneManager = class {
 				const existing = mounted.get(key);
 				if (existing?.hash === hash) continue;
 				if (existing) this.removePluginElement(mounted, key, existing);
-				const built = plugin.build(value, { capabilities: this.capabilities });
+				const built = plugin.build(value, this.context());
 				if (built.object) this.root.add(built.object);
 				mounted.set(key, {
 					...built,
@@ -702,7 +831,7 @@ var SceneManager = class {
 				});
 			}
 			for (const [key, entry] of mounted) if (!seen.has(key)) this.removePluginElement(mounted, key, entry);
-			plugin.provide?.(items.map(([, value]) => value), { capabilities: this.capabilities });
+			plugin.provide?.(items.map(([, value]) => value), this.context());
 		}
 	}
 	removePluginElement(mounted, key, entry) {
@@ -793,7 +922,20 @@ function createGallery(scene, options) {
 	const systemPlugins = allPlugins.filter(isSystemPlugin);
 	const elementPlugins = allPlugins.filter((p) => !isSystemPlugin(p));
 	const capabilities = new CapabilityRegistry();
-	const manager = new SceneManager(threeScene, elementPlugins, capabilities);
+	if (options.ktx2Path) configureKtx2(renderer, options.ktx2Path);
+	const assets = /* @__PURE__ */ new Set();
+	for (const plugin of elementPlugins) {
+		const { kind, cardinality } = plugin.data;
+		const raw = scene[kind];
+		const values = cardinality === "many" ? Array.isArray(raw) ? raw : [] : raw !== void 0 ? [raw] : [];
+		for (const value of values) for (const url of plugin.data.assets?.(value) ?? []) assets.add(url);
+	}
+	if (scene.environment?.src) assets.add(scene.environment.src);
+	startLoading(assets);
+	const manager = new SceneManager(threeScene, elementPlugins, capabilities, {
+		camera,
+		renderer
+	});
 	manager.reconcile(scene);
 	const input = new InputBus();
 	const controlSettings = new ControlSettings(loadControlFlags() ?? (options.cardboard ? MODE_PRESETS.cardboard : {}));
@@ -1012,6 +1154,10 @@ function createGallery(scene, options) {
 				renderer
 			}
 		},
+		loading: {
+			get: loadingState,
+			subscribe: onLoading
+		},
 		setScene(next) {
 			manager.reconcile(next);
 			interaction.setRadii(radiiOf(next));
@@ -1108,7 +1254,9 @@ exports.TERRAIN = TERRAIN;
 exports.applyMode = applyMode;
 exports.applyTexture = applyTexture;
 exports.createGallery = createGallery;
+exports.getKtx2Loader = getKtx2Loader;
 exports.isSystemPlugin = isSystemPlugin;
 exports.modeOf = modeOf;
+exports.trackAsset = trackAsset;
 
 //# sourceMappingURL=index.cjs.map