feat(core,soba/loaders,soba/staging): implement resources

Author: nartc

apps/examples/src/app/soba/basic/scene.ts

@@ -15,7 +15,7 @@ import {
 import { NgtArgs } from 'angular-three';
 import { NgtpBloom, NgtpEffectComposer, NgtpGlitch } from 'angular-three-postprocessing';
 import { NgtsOrbitControls } from 'angular-three-soba/controls';
-import { injectGLTF } from 'angular-three-soba/loaders';
+import { gltfResource, injectGLTF } from 'angular-three-soba/loaders';
 import { NgtsAnimation, injectAnimations } from 'angular-three-soba/misc';
 import { injectMatcapTexture } from 'angular-three-soba/staging';
 import {
@@ -68,7 +68,7 @@ export class BotAnimations {
 	template: `
 		<ngt-group [position]="[0, -1, 0]">
 			<ngt-grid-helper *args="[10, 20]" />
-			@if (gltf(); as gltf) {
+			@if (resource.value(); as gltf) {
 				<ngt-group [dispose]="null" [animations]="gltf" [referenceRef]="boneRef()">
 					<ngt-group [rotation]="[Math.PI / 2, 0, 0]" [scale]="0.01">
 						<ngt-primitive #bone *args="[gltf.nodes.mixamorigHips]" />
@@ -97,6 +97,9 @@ export class Bot {
 	protected Math = Math;
 
 	protected gltf = injectGLTF<BotGLTF>(() => './ybot.glb');
+
+	protected resource = gltfResource<BotGLTF>(() => './ybot.glb');
+
 	protected matcapBody = injectMatcapTexture(() => '293534_B2BFC5_738289_8A9AA7', {
 		onLoad: (textures) => {
 			textures[0].colorSpace = SRGBColorSpace;

libs/core/src/index.ts

@@ -1,14 +1,14 @@
 export * from './lib/directives/args';
 export * from './lib/directives/parent';
 export * from './lib/directives/selection';
+export * from './lib/events';
 export * from './lib/html';
 export * from './lib/instance';
 export * from './lib/loader';
+export * from './lib/loader-resource';
 export * from './lib/loop';
 export * from './lib/pipes/hexify';
 export * from './lib/portal';
-// export * from './lib/renderer-old';
-export * from './lib/events';
 export * from './lib/renderer/catalogue';
 export * from './lib/renderer/constants';
 export * from './lib/renderer/renderer';

libs/core/src/lib/loader-resource.ts

@@ -0,0 +1,181 @@
+import { type Injector, resource, type ResourceRef } from '@angular/core';
+import { assertInjector } from 'ngxtension/assert-injector';
+import * as THREE from 'three';
+import type {
+	NgtBranchingReturn,
+	NgtGLTFLike,
+	NgtLoaderExtensions,
+	NgtLoaderProto,
+	NgtLoaderResults,
+	NgtLoaderReturnType,
+} from './loader';
+import type { NgtAnyRecord } from './types';
+import { makeObjectGraph, type NgtObjectMap } from './utils/make';
+
+function normalizeInputs(input: string | string[] | Record<string, string>) {
+	let urls: string[] = [];
+	if (Array.isArray(input)) {
+		urls = input;
+	} else if (typeof input === 'string') {
+		urls = [input];
+	} else {
+		urls = Object.values(input);
+	}
+
+	return urls.map((url) => (url.includes('undefined') || url.includes('null') || !url ? '' : url));
+}
+
+const cached = new Map();
+const memoizedLoaders = new WeakMap();
+
+function getLoaderRequestParams<
+	TData,
+	TUrl extends string | string[] | Record<string, string>,
+	TLoaderConstructor extends NgtLoaderProto<TData>,
+>(
+	input: { (): TUrl },
+	loaderConstructorFactory: {
+		(url: TUrl): TLoaderConstructor;
+	},
+	extensions: NgtLoaderExtensions<TLoaderConstructor> | undefined,
+) {
+	const urls = input();
+	const LoaderConstructor = loaderConstructorFactory(urls);
+	const normalizedUrls = normalizeInputs(urls);
+	let loader: THREE.Loader<TData> = memoizedLoaders.get(LoaderConstructor);
+	if (!loader) {
+		loader = new LoaderConstructor();
+		memoizedLoaders.set(LoaderConstructor, loader);
+	}
+
+	if (extensions) extensions(loader);
+
+	return { urls, normalizedUrls, loader };
+}
+
+function getLoaderPromises<TData, TUrl extends string | string[] | Record<string, string>>(
+	request: { loader: THREE.Loader<TData>; normalizedUrls: string[]; urls: TUrl },
+	onProgress?: { (event: ProgressEvent<EventTarget>): void },
+) {
+	return request.normalizedUrls.map((url) => {
+		if (url === '') return Promise.resolve(null);
+		const cachedPromise = cached.get(url);
+		if (cachedPromise) return cachedPromise;
+
+		const promise = new Promise<TData>((res, rej) => {
+			request.loader.load(
+				url,
+				(data) => {
+					if ('scene' in (data as NgtAnyRecord)) {
+						Object.assign(data as NgtAnyRecord, makeObjectGraph((data as NgtAnyRecord)['scene']));
+					}
+
+					res(data);
+				},
+				onProgress,
+				(error) => rej(new Error(`[NGT] Could not load ${url}: ${(error as ErrorEvent)?.message}`)),
+			);
+		});
+
+		cached.set(url, promise);
+
+		return promise;
+	});
+}
+
+export function loaderResource<
+	TData,
+	TUrl extends string | string[] | Record<string, string>,
+	TLoaderConstructor extends NgtLoaderProto<TData>,
+	TReturn = NgtLoaderReturnType<TData, TLoaderConstructor>,
+>(
+	loaderConstructorFactory: (url: TUrl) => TLoaderConstructor,
+	input: () => TUrl,
+	{
+		extensions,
+		onLoad,
+		onProgress,
+		injector,
+	}: {
+		extensions?: NgtLoaderExtensions<TLoaderConstructor>;
+		onLoad?: (
+			data: NoInfer<NgtLoaderResults<TUrl, NgtBranchingReturn<TReturn, NgtGLTFLike, NgtGLTFLike & NgtObjectMap>>>,
+		) => void;
+		onProgress?: (event: ProgressEvent) => void;
+		injector?: Injector;
+	} = {},
+): ResourceRef<
+	NgtLoaderResults<TUrl, NgtBranchingReturn<TReturn, NgtGLTFLike, NgtGLTFLike & NgtObjectMap>> | undefined
+> {
+	return assertInjector(loaderResource, injector, () => {
+		return resource({
+			request: () => getLoaderRequestParams(input, loaderConstructorFactory, extensions),
+			loader: async ({ request }) => {
+				const loadedResults = await Promise.all(getLoaderPromises(request, onProgress));
+
+				let results: NgtLoaderResults<
+					TUrl,
+					NgtBranchingReturn<TReturn, NgtGLTFLike, NgtGLTFLike & NgtObjectMap>
+				>;
+
+				if (Array.isArray(request.urls)) {
+					results = loadedResults as NgtLoaderResults<
+						TUrl,
+						NgtBranchingReturn<TReturn, NgtGLTFLike, NgtGLTFLike & NgtObjectMap>
+					>;
+				} else if (typeof request.urls === 'string') {
+					results = loadedResults[0] as NgtLoaderResults<
+						TUrl,
+						NgtBranchingReturn<TReturn, NgtGLTFLike, NgtGLTFLike & NgtObjectMap>
+					>;
+				} else {
+					const keys = Object.keys(request.urls);
+					results = keys.reduce(
+						(result, key) => {
+							// @ts-ignore
+							(result as NgtAnyRecord)[key] = loadedResults[keys.indexOf(key)];
+							return result;
+						},
+						{} as {
+							[key in keyof TUrl]: NgtBranchingReturn<TReturn, NgtGLTFLike, NgtGLTFLike & NgtObjectMap>;
+						},
+					) as NgtLoaderResults<TUrl, NgtBranchingReturn<TReturn, NgtGLTFLike, NgtGLTFLike & NgtObjectMap>>;
+				}
+
+				if (onLoad) {
+					onLoad(results);
+				}
+
+				return results;
+			},
+		});
+	});
+}
+
+loaderResource.preload = <
+	TData,
+	TUrl extends string | string[] | Record<string, string>,
+	TLoaderConstructor extends NgtLoaderProto<TData>,
+>(
+	loaderConstructor: TLoaderConstructor,
+	inputs: TUrl,
+	extensions?: NgtLoaderExtensions<TLoaderConstructor>,
+) => {
+	const params = getLoaderRequestParams(
+		() => inputs,
+		() => loaderConstructor,
+		extensions,
+	);
+	void Promise.all(getLoaderPromises(params));
+};
+
+loaderResource.destroy = () => {
+	cached.clear();
+};
+
+loaderResource.clear = (urls: string | string[]) => {
+	const urlToClear = Array.isArray(urls) ? urls : [urls];
+	urlToClear.forEach((url) => {
+		cached.delete(url);
+	});
+};

libs/core/src/lib/loader.ts

@@ -1,12 +1,12 @@
 import { Injector, Signal, effect, signal } from '@angular/core';
 import { assertInjector } from 'ngxtension/assert-injector';
-import { Loader, Object3D } from 'three';
+import * as THREE from 'three';
 import type { NgtAnyRecord } from './types';
 import { NgtObjectMap, makeObjectGraph } from './utils/make';
 
-export type NgtGLTFLike = { scene: Object3D };
+export type NgtGLTFLike = { scene: THREE.Object3D };
 
-export interface NgtLoader<T> extends Loader {
+export interface NgtLoader<T> extends THREE.Loader {
 	load(
 		url: string,
 		onLoad?: (result: T) => void,
@@ -24,7 +24,6 @@ export type NgtLoaderReturnType<T, L extends NgtLoaderProto<T>> = T extends unkn
 export type NgtLoaderExtensions<T extends { prototype: NgtLoaderProto<any> }> = (loader: T['prototype']) => void;
 export type NgtConditionalType<Child, Parent, Truthy, Falsy> = Child extends Parent ? Truthy : Falsy;
 export type NgtBranchingReturn<T, Parent, Coerced> = NgtConditionalType<T, Parent, Coerced, T>;
-
 export type NgtLoaderResults<
 	TInput extends string | string[] | Record<string, string>,
 	TReturn,
@@ -67,7 +66,7 @@ function load<
 	return (): Array<Promise<any>> => {
 		const urls = normalizeInputs(inputs());
 
-		let loader: Loader<TData> = memoizedLoaders.get(loaderConstructorFactory(urls));
+		let loader: THREE.Loader<TData> = memoizedLoaders.get(loaderConstructorFactory(urls));
 		if (!loader) {
 			loader = new (loaderConstructorFactory(urls))();
 			memoizedLoaders.set(loaderConstructorFactory(urls), loader);
@@ -111,6 +110,10 @@ function load<
 	};
 }
 
+/**
+ * @deprecated Use loaderResource instead. Will be removed in v5.0.0
+ * @since v4.0.0~
+ */
 function _injectLoader<
 	TData,
 	TUrl extends string | string[] | Record<string, string>,
@@ -197,4 +200,9 @@ _injectLoader.clear = (urls: string | string[]) => {
 };
 
 export type NgtInjectedLoader = typeof _injectLoader;
+
+/**
+ * @deprecated Use loaderResource instead. Will be removed in v5.0.0
+ * @since v4.0.0~
+ */
 export const injectLoader: NgtInjectedLoader = _injectLoader;

libs/soba/loaders/src/index.ts

@@ -1,6 +1,10 @@
 export * from './lib/fbx-loader';
+export * from './lib/fbx-resource';
 export * from './lib/font-loader';
+export * from './lib/font-resource';
 export * from './lib/gltf-loader';
+export * from './lib/gltf-resource';
 export * from './lib/loader';
 export * from './lib/progress';
 export * from './lib/texture-loader';
+export * from './lib/texture-resource';

libs/soba/loaders/src/lib/fbx-loader.ts

@@ -3,6 +3,10 @@ import { injectLoader } from 'angular-three';
 import { assertInjector } from 'ngxtension/assert-injector';
 import { FBXLoader } from 'three-stdlib';
 
+/**
+ * @deprecated Use fbxResource instead. Will be removed in v5.0.0
+ * @since v4.0.0
+ */
 function _injectFBX<TUrl extends string | string[] | Record<string, string>>(
 	input: () => TUrl,
 	{ injector }: { injector?: Injector } = {},
@@ -17,4 +21,9 @@ _injectFBX.preload = <TUrl extends string | string[] | Record<string, string>>(i
 };
 
 export type NgtsFBXLoader = typeof _injectFBX;
+
+/**
+ * @deprecated Use fbxResource instead. Will be removed in v5.0.0
+ * @since v4.0.0
+ */
 export const injectFBX: NgtsFBXLoader = _injectFBX;

libs/soba/loaders/src/lib/fbx-resource.ts

@@ -0,0 +1,17 @@
+import { Injector } from '@angular/core';
+import { loaderResource } from 'angular-three';
+import { assertInjector } from 'ngxtension/assert-injector';
+import { FBXLoader } from 'three-stdlib';
+
+export function fbxResource<TUrl extends string | string[] | Record<string, string>>(
+	input: () => TUrl,
+	{ injector }: { injector?: Injector } = {},
+) {
+	return assertInjector(fbxResource, injector, () => {
+		return loaderResource(() => FBXLoader, input);
+	});
+}
+
+fbxResource.preload = <TUrl extends string | string[] | Record<string, string>>(input: TUrl) => {
+	loaderResource.preload(FBXLoader, input);
+};

libs/soba/loaders/src/lib/font-loader.ts

@@ -25,11 +25,11 @@ export type NgtsFontInput = string | FontData;
 
 let fontLoader: FontLoader | null = null;
 
-async function loadFontData(font: NgtsFontInput): Promise<FontData> {
+export async function loadFontData(font: NgtsFontInput): Promise<FontData> {
 	return typeof font === 'string' ? await (await fetch(font)).json() : font;
 }
 
-function parseFontData(fontData: FontData) {
+export function parseFontData(fontData: FontData) {
 	if (!fontLoader) {
 		fontLoader = new FontLoader();
 	}
@@ -38,6 +38,10 @@ function parseFontData(fontData: FontData) {
 
 const cache = new Map<NgtsFontInput, Font>();
 
+/**
+ * @deprecated Use fontResource instead. Will be removed in v5.0.0
+ * @since v4.0.0
+ */
 export function injectFont(input: () => NgtsFontInput, { injector }: { injector?: Injector } = {}) {
 	return assertInjector(injectFont, injector, () => {
 		const font = signal<Font | null>(null);

libs/soba/loaders/src/lib/font-resource.ts

@@ -0,0 +1,39 @@
+import { Injector, resource } from '@angular/core';
+import { assertInjector } from 'ngxtension/assert-injector';
+import { Font } from 'three-stdlib';
+import { loadFontData, NgtsFontInput, parseFontData } from './font-loader';
+
+const cache = new Map<NgtsFontInput, Font>();
+
+export function fontResource(input: () => NgtsFontInput, { injector }: { injector?: Injector } = {}) {
+	return assertInjector(fontResource, injector, () => {
+		return resource({
+			request: input,
+			loader: async ({ request }) => {
+				if (cache.has(request)) {
+					return cache.get(request) as Font;
+				}
+
+				const fontData = await loadFontData(request);
+				const parsed = parseFontData(fontData);
+				cache.set(request, parsed);
+				return parsed;
+			},
+		});
+	});
+}
+
+fontResource.preload = (input: NgtsFontInput) => {
+	loadFontData(input).then((data) => {
+		const parsed = parseFontData(data);
+		cache.set(input, parsed);
+	});
+};
+
+fontResource.clear = (input?: NgtsFontInput) => {
+	if (input) {
+		cache.delete(input);
+	} else {
+		cache.clear();
+	}
+};