ris-framework 0.2.0-dev.11 → 0.2.0-dev.13

package/src/api/IFramework.ts

@@ -7,6 +7,7 @@ import type { IBufferFactory } from "./rendering/buffers/IBufferFactory.ts";
 import type { IGeometryBuilder } from "./geometry/IGeometryBuilder.ts";
 import type { ICameraFactory } from "./camera/ICameraFactory.ts";
 import type { ITextureFactory } from "./rendering/texture/ITextureFactory.ts";
+import type { ObjLoader } from "./loaders/ObjLoader.ts";
 import type { IContentManager } from "./content/IContentManager.ts";
 import type { IImageLoader } from "./loaders/IImageLoader.ts";
 import type { IMeshFactory } from "./meshes/IMeshFactory.ts";
@@ -19,6 +20,49 @@ import {GameTime} from "./time/GameTime.ts";
 import type { IImageProcessor } from "./image/IImageProcessor.ts";
 import type { IKtx2Factory } from "ris-ktx2";
 import type { IDisposable } from "./core/IDisposable.ts";
+import type {vec2} from "gl-matrix";
+import type {TextureSamplerFilteringPreset} from "../core/rendering/enums.ts";
+import type {PowerPreferenceType} from "./rendering/PowerPreference.ts";
+import type {TextureColorSpace} from "./rendering/enums.ts";
+
+
+/**
+ * The configuration for the framework.
+ * @public
+ **/
+export class IFrameworkConfiguration {
+
+    /** If true, creates and makes the KTX2 factory available. */
+    useKtx2?: boolean;
+
+    /** The size of back buffer. By default, if not specified (800, 600). */
+    backBufferSize?: vec2;
+
+    /** The texture filtering to configure */
+    textureFiltering?: TextureSamplerFilteringPreset;
+
+    /** The texture color space to use by default. By default, it is {@link TextureColorSpace.SRGB}. */
+     textureColorSpace?: TextureColorSpace;
+
+     /**
+     * The HTMLCanvasElement to use for rendering.
+     * If null, a new canvas will be created and added to the document body.
+     */
+    canvas?: HTMLCanvasElement;
+
+    /** Should back buffer use alpha. */
+    alpha?: boolean;
+
+    /** The preference when it comes to selecting GPU device. Only makes sense to set on multi-GPU devices. */
+    powerPreference ?: PowerPreferenceType;
+
+    /**
+     * The rendering backend. Defaults to WebGL.
+     * WebGPU requires `Framework.initializeAsync()`; when `navigator.gpu` is missing or no device is available,
+     * the framework falls back to WebGL with a warning.
+     */
+    renderingBackend?: RenderingBackend;
+}
 
 /** The framework interface. */
 export interface IFramework extends IDisposable {
@@ -87,6 +131,11 @@ export interface IFramework extends IDisposable {
      */
     readonly meshFactory: IMeshFactory;
 
+    /**
+     * The OBJ loader: `objLoader.loadAsync(path, blinnPhongDescriptor | subMesh => material)`.
+     */
+    readonly objLoader: ObjLoader;
+
     /**
      * The material factory.
      */
@@ -152,4 +201,10 @@ export interface IFramework extends IDisposable {
     /** Initializes the framework. */
     initialize(): void;
 
+    /**
+     * Initializes the framework asynchronously and starts the event loop.
+     * Required for the WebGPU backend; for WebGL it behaves like {@link initialize}.
+     */
+    initializeAsync(): Promise<void>;
+
 }

package/src/api/_export.ts

@@ -1,5 +1,4 @@
 export * from "./IFramework.ts";
-export * from "./IFrameworkConfiguration.ts";
 export * from "./rendering/texture/_export-texture.ts";
 export * from "./rendering/buffers/_export-buffers.ts";
 export * from "./data/_export.ts";
@@ -24,5 +23,6 @@ export * from "./meshes/_export.ts";
 export * from "./material/_export.ts";
 export * from "./lights/_export.ts";
 export * from "./scene/Scene.ts";
+export * from "./scene/SceneMesh.ts";
 export * from "./input/_export.ts";
 export * from "./image/_export.ts";

package/src/api/content/ContentManager.ts

@@ -9,23 +9,19 @@ import {
     ContentConfig,
     TextureUsage,
     type IMesh,
-    ObjLoader,
+    type IRenderableMesh,
+    type GeometryFormat,
     Color,
     type ICamera,
-    type IMaterial,
-    type ObjMaterialDefinition,
-    type SubMeshDescriptor,
-    type ObjLoadResult,
-    type ObjGeometryDefinition,
-    type IGeometry,
-    type LightsBuffer,
-    type Scene,
     type IDisposable,
 } from "../index.ts";
 import {ObjGeometryMapper} from "../loaders/ObjGeometryMapper.ts";
+import {ObjLoader} from "../loaders/ObjLoader.ts";
 import {Ktx2Factory} from "ris-ktx2";
 import type {IKtx2Texture} from "ris-ktx2";
 
+const KTX2_EXTENSION = ".ktx2";
+
 /**
  * The content manager.
  * The content manager is responsible for managing the content modules and loading the content with the given asset file path or identifier.
@@ -33,8 +29,7 @@ import type {IKtx2Texture} from "ris-ktx2";
 export class ContentManager implements IContentManager {
 
     private readonly _ktx2Factory = new Ktx2Factory();
-    private readonly _ktx2TextureCache: {[key: string]: IKtx2Texture} = {};
-    private readonly _objLoader = new ObjLoader();
+    private readonly _ktx2TextureCache: { [key: string]: IKtx2Texture } = {};
 
     /**
      * The constructor.
@@ -47,13 +42,16 @@ export class ContentManager implements IContentManager {
     /** @inheritDoc */
     public async loadKtx2Async(path: string, contentConfig?: ContentConfig): Promise<IKtx2Texture> {
 
+        // it's fine to call it, handled internally if called multiple times.
+        await this._ktx2Factory.initializeAsync();
+
         let ktx2Texture = this._ktx2TextureCache[path];
-        if(ktx2Texture) {
+        if (ktx2Texture) {
             return ktx2Texture;
         }
 
         ktx2Texture = await this._ktx2Factory.loadAsync(path);
-        if(contentConfig?.keepDataCached == true){
+        if (contentConfig?.keepDataCached == true) {
             this._ktx2TextureCache[path] = ktx2Texture;
         }
         return ktx2Texture;
@@ -66,45 +64,53 @@ export class ContentManager implements IContentManager {
     public dispose(): void {
         (this.shaderModuleLoader as Partial<IDisposable>).dispose?.();
         for (const key of Object.keys(this._ktx2TextureCache)) {
+            this._ktx2TextureCache[key].delete();
             delete this._ktx2TextureCache[key];
         }
     }
 
     /** @inheritDoc */
-    public loadShaderModule(shaderModuleId: string,  keyValueDictionary?: { [id:string]: number}): IShaderModule {
-        return this.shaderModuleLoader.load(shaderModuleId,  keyValueDictionary);
+    public loadShaderModule(shaderModuleId: string, keyValueDictionary?: { [id: string]: number }): IShaderModule {
+        return this.shaderModuleLoader.load(shaderModuleId, keyValueDictionary);
     }
 
     /** @inheritDoc */
     public async loadTexture2DAsync(path: string,
                                     textureDescriptor?: TextureDescriptor,
                                     contentConfig?: ContentConfig,
-                                    ): Promise<ITexture2D> {
+    ): Promise<ITexture2D> {
 
-        if(path.endsWith(".ktx2")) {
-            const ktx2Texture = await this.loadKtx2Async(path, contentConfig);
+        // TODO: check texture cache
+        if (path.endsWith(KTX2_EXTENSION)) {
+
+            const ktx2Texture = await this.loadKtx2Async(path);
             textureDescriptor = textureDescriptor ?? new TextureDescriptor();
-            return this._framework.textureFactory.createFromKtx2(ktx2Texture, textureDescriptor);
+            const tex = this._framework.textureFactory.createFromKtx2(ktx2Texture, textureDescriptor);
+            if (contentConfig?.keepDataCached !== true) {
+                ktx2Texture.delete();
+            }
+            return tex;
         }
 
-        let format =  this._framework.renderer.preferredTextureFormat;
+        let format = this._framework.renderer.preferredTextureFormat;
 
-        if(textureDescriptor && textureDescriptor.textureFormat != TextureFormat.UNDEFINED) {
+        if (textureDescriptor && textureDescriptor.textureFormat != TextureFormat.UNDEFINED) {
             format = textureDescriptor.textureFormat;
         }
 
-        // TODO: pass texture descriptor
         const imageLoader = this._framework.imageLoader;
         const data = await imageLoader.loadAsync(path, contentConfig?.keepDataCached);
+
+        // TODO: pass texture descriptor
         return this._framework.textureFactory.create(
             data.baseWidth, data.baseHeight,
             data.getData(0) as Uint8Array,
             data.channels,
-            undefined,
+            path,
             TextureUsage.TEXTURE_BINDING | TextureUsage.COPY_SRC,
             format,
             textureDescriptor?.generateMipmaps
-            );
+        );
     }
 
     /** @inheritDoc */
@@ -114,170 +120,30 @@ export class ContentManager implements IContentManager {
     }
 
     /** @inheritDoc */
-    public async loadMeshAsync(path: string, scene: Scene): Promise<IMesh> {
-
-        const objResult = await this._loadObj(path);
-        const geometry = this._createGeometry(objResult.geometry);
-        const subMeshes = this._createSubMeshDescriptors(objResult,
-            definition => this._createUnlitMaterial(definition, scene.camera));
-
-        return this._framework.meshFactory.createWithSubMeshes(scene, geometry, subMeshes);
+    public async loadMeshAsync(path: string, geometryFormat: GeometryFormat): Promise<IMesh> {
+        const model = await ObjLoader.parseAsync(path, {ignoreMaterials: true});
+        const geometry = this._framework.geometryBuilder.create(ObjGeometryMapper.toDescriptor(model.geometry));
+        return this._framework.meshFactory.createMesh(geometry, geometryFormat);
     }
 
     /** @inheritDoc */
-    public async loadBlinnPhongMeshAsync(path: string, scene: Scene): Promise<IMesh> {
-        // Checked before loading, so a missing camera fails fast.
-        const camera = scene.camera;
-        if (!camera) {
-            throw new Error(`loadBlinnPhongMeshAsync("${path}"): the scene has no camera. Set scene.camera (or pass the scene to createPerspectiveCamera) before loading a Blinn-Phong mesh.`);
-        }
-        if (!camera.positionBuffer || !camera.projectionViewBuffer) {
-            const what = [camera.projectionViewBuffer ? undefined : "projectionViewBuffer", camera.positionBuffer ? undefined : "positionBuffer"]
-                .filter(x => x !== undefined).join(" and ");
-            throw new Error(`loadBlinnPhongMeshAsync("${path}"): the scene camera has no ${what}. Call camera.initialize() first (the camera factory does).`);
-        }
-        const objResult = await this._loadObj(path);
-        const geometry = this._createGeometry(objResult.geometry);
-        const subMeshes = this._createSubMeshDescriptors(objResult,
-            definition => this._createBlinnPhongMaterial(definition, camera, scene.__forwardLightsBuffer));
-
-        return this._framework.meshFactory.createWithSubMeshes(scene, geometry, subMeshes);
-    }
-
-    /**
-     * Loads the OBJ file and its .mtl material libraries.
-     * @param path The path or url to the .obj file.
-     * @returns The plain OBJ data.
-     */
-    private _loadObj(path: string): Promise<ObjLoadResult> {
-        return this._objLoader.loadAsync(path);
-    }
-
-    /**
-     * Creates framework geometry from the OBJ geometry.
-     * Vertex colours stay white, because each submesh's material carries the colour.
-     * @param definition The OBJ geometry definition.
-     * @returns The geometry.
-     */
-    private _createGeometry(definition: ObjGeometryDefinition): IGeometry {
-        const descriptor = ObjGeometryMapper.toDescriptor(definition);
-        return this._framework.geometryBuilder.create(descriptor);
-    }
-
-
-    /**
-     * Creates one submesh descriptor per material range.
-     * Ranges that use the same material name share one material instance.
-     * @param objResult The loaded OBJ data.
-     * @param createMaterial Creates the material for a definition (undefined without `usemtl` or .mtl entry).
-     * @returns The submesh descriptors, in file order.
-     */
-    private _createSubMeshDescriptors(
-        objResult: ObjLoadResult,
-        createMaterial: (definition: ObjMaterialDefinition | undefined) => IMaterial): SubMeshDescriptor[] {
-
-        const definitionsByName = this._indexMaterialDefinitions(objResult.materials);
-        const materialsByName = new Map<string | undefined, IMaterial>();
-        const subMeshes: SubMeshDescriptor[] = [];
-
-        for (const range of objResult.geometry.materialRanges) {
-            let material = materialsByName.get(range.materialName);
-            if (material === undefined) {
-                const definition = this._findMaterialDefinition(definitionsByName, range.materialName);
-                material = createMaterial(definition);
-                materialsByName.set(range.materialName, material);
-            }
-
-            subMeshes.push({
-                material: material,
-                indexStart: range.indexStart,
-                indexCount: range.indexCount,
-            });
-        }
-
-        return subMeshes;
-    }
-
-    /**
-     * Indexes material definitions by name.
-     * @param definitions The material definitions from the .mtl files.
-     * @returns A map from material name to definition.
-     */
-    private _indexMaterialDefinitions(definitions: ObjMaterialDefinition[]): Map<string, ObjMaterialDefinition> {
-        const definitionsByName = new Map<string, ObjMaterialDefinition>();
-        for (const definition of definitions) {
-            definitionsByName.set(definition.name, definition);
-        }
-        return definitionsByName;
-    }
-
-    /**
-     * Finds the definition for a `usemtl` name.
-     * @param definitionsByName The definitions by name.
-     * @param materialName The material name, or undefined for faces without `usemtl`.
-     * @returns The definition, or undefined when there is none.
-     */
-    private _findMaterialDefinition(
-        definitionsByName: Map<string, ObjMaterialDefinition>,
-        materialName: string | undefined): ObjMaterialDefinition | undefined {
-        if (materialName === undefined) {
-            return undefined;
-        }
-        return definitionsByName.get(materialName);
-    }
-
-    /**
-     * Creates the default unlit material for an OBJ material definition.
-     * The diffuse colour is the definition's `Kd` with `d` as alpha; white when there is no definition.
-     * @param definition The material definition, or undefined.
-     * @param camera The scene's current camera, or undefined; the scene assigns it on update.
-     * @returns The unlit material.
-     */
-    private _createUnlitMaterial(definition: ObjMaterialDefinition | undefined, camera: ICamera | undefined): IMaterial {
-        const material = this._framework.materialFactory.createUnlitMaterial({
-            camera: camera,
+    public loadUnlitMeshAsync(path: string, camera?: ICamera): Promise<IRenderableMesh> {
+        return this._framework.objLoader.loadAsync(path, subMesh => {
+            const material = this._framework.materialFactory.createUnlitMaterial({camera});
+            const diffuse = subMesh.material?.diffuseColor ?? [1, 1, 1];
+            material.diffuseColor = new Color(diffuse[0], diffuse[1], diffuse[2], subMesh.material?.opacity ?? 1);
+            return material;
         });
-
-        const diffuse = definition?.diffuseColor ?? [1, 1, 1];
-        const opacity = definition?.opacity ?? 1;
-        material.diffuseColor = new Color(diffuse[0], diffuse[1], diffuse[2], opacity);
-        return material;
     }
 
-    /**
-     * Creates a Blinn-Phong material for an OBJ material definition.
-     * `Kd` (with `d` as alpha) becomes the diffuse colour, white when missing.
-     * `Ka` becomes the ambient colour; when missing the diffuse colour is used, so ambient light tints by the surface colour.
-     * `Ks` and `Ns` become specular colour and shininess; when missing the material defaults stay (0.5 grey, 32).
-     * @param definition The material definition, or undefined.
-     * @param camera The scene's camera; its projection view and position buffers are bound.
-     * @param lightsBuffer The optional lights buffer; the shader is compiled for its light counts.
-     * @returns The Blinn-Phong material.
-     */
-    private _createBlinnPhongMaterial(
-        definition: ObjMaterialDefinition | undefined,
-        camera: ICamera,
-        lightsBuffer: LightsBuffer | undefined): IMaterial {
-
-        const material = this._framework.materialFactory.createForwardBlinnPhongMaterial({
+    /** @inheritDoc */
+    public loadBlinnPhongMeshAsync(path: string, camera: ICamera): Promise<IRenderableMesh> {
+        if (!camera?.projectionViewBuffer || !camera?.positionBuffer) {
+            throw new Error(`loadBlinnPhongMeshAsync("${path}"): the camera has no projectionViewBuffer/positionBuffer. Pass an initialized camera (the camera factory initializes it).`);
+        }
+        return this._framework.objLoader.loadAsync(path, {
             projectionViewBuffer: camera.projectionViewBuffer,
             cameraPositionBuffer: camera.positionBuffer,
-            lightsBuffer: lightsBuffer,
         });
-        // Matches the scene camera, so Scene.update() does not rebind.
-        material.camera = camera;
-
-        const diffuse = definition?.diffuseColor ?? [1, 1, 1];
-        const ambient = definition?.ambientColor ?? diffuse;
-        material.diffuseColor = new Color(diffuse[0], diffuse[1], diffuse[2], definition?.opacity ?? 1);
-        material.ambientColor = new Color(ambient[0], ambient[1], ambient[2]);
-        if (definition?.specularColor) {
-            const specular = definition.specularColor;
-            material.specularColor = new Color(specular[0], specular[1], specular[2]);
-        }
-        if (definition?.specularExponent !== undefined) {
-            material.shininess = definition.specularExponent;
-        }
-        return material;
     }
 }

package/src/api/content/IContentManager.ts

@@ -1,4 +1,6 @@
-import type { Scene } from "../scene/Scene.ts";
+import type { ICamera } from "../camera/ICamera.ts";
+import type { GeometryFormat } from "../geometry/GeometryFormat.ts";
+import type { IRenderableMesh } from "../meshes/IRenderableMesh.ts";
 import type { IShaderModuleLoader } from "../shader/IShaderModuleLoader.ts";
 import type { IShaderModule } from "../shader/IShaderModule.ts";
 import type { ITexture2D } from "../rendering/texture/ITexture2D.ts";
@@ -43,31 +45,33 @@ export interface IContentManager {
     loadTexture2DAsync(path: string, desc?: TextureDescriptor, contentConfig?: ContentConfig): Promise<ITexture2D>;
 
     /**
-     * Loads a mesh from a model, typically.
-     * Currently, OBJ(WAVEFRONT) is supported.
-     * The mesh has one submesh per `usemtl` range, all sharing one vertex and index buffer.
-     * By default, each submesh gets an unlit material with the .mtl `Kd` as diffuse colour and `d` as alpha.
-     * @param path The path or url to the model.
-     * @param scene The scene the mesh adds itself to; `scene.render()` draws it. The materials use `scene.camera`
-     *              (assigned on `scene.update()` when it is set later).
+     * Loads a plain mesh (geometry and buffers only, no material or transform) from an OBJ (Wavefront) file,
+     * like C# `ContentManager.LoadMesh`. Materials (.mtl) are not loaded.
+     * @param path The path or url to the .obj file.
+     * @param geometryFormat The vertex layout of the buffers, e.g. the format of the material it will be drawn with.
      * @return The mesh.
      */
-    loadMeshAsync(path: string, scene: Scene): Promise<IMesh>;
+    loadMeshAsync(path: string, geometryFormat: GeometryFormat): Promise<IMesh>;
 
     /**
-     * Loads an OBJ (Wavefront) mesh with lit Blinn-Phong materials.
-     * Like {@link loadMeshAsync}, the mesh has one submesh per `usemtl` range sharing one vertex and index buffer,
-     * and ranges with the same material name share one material. `scene.render()` draws it.
-     * The .mtl values map onto `ForwardBlinnPhongMaterial`:
-     * - `Kd` → `diffuseColor` (with `d` as alpha), white when missing.
-     * - `Ka` → `ambientColor`, the diffuse colour when missing.
-     * - `Ks` → `specularColor` and `Ns` → `shininess`, the material defaults (0.5 grey, 32) when missing.
-     * Without an .mtl file every submesh gets a white material with those defaults.
+     * Loads an OBJ mesh with unlit materials, through `framework.objLoader`.
+     * The root mesh has no material; each `usemtl` range is a sub mesh with an unlit material
+     * (`Kd` as diffuse colour, `d` as alpha, white when missing). Add it with `scene.add(mesh)`.
+     * @param path The path or url to the .obj file.
+     * @param camera The optional camera; `scene.update()` assigns the scene camera anyway.
+     * @return The root mesh.
+     */
+    loadUnlitMeshAsync(path: string, camera?: ICamera): Promise<IRenderableMesh>;
+
+    /**
+     * Loads an OBJ mesh with Blinn-Phong materials: shorthand for
+     * `framework.objLoader.loadAsync(path, {projectionViewBuffer: camera.projectionViewBuffer, cameraPositionBuffer: camera.positionBuffer})`.
+     * See `ObjLoader.loadAsync` for the .mtl mapping. Add it with `scene.add(mesh)`; the scene assigns its camera and lights.
      * @param path The path or url to the .obj file. A relative `mtllib` is resolved against it.
-     * @param scene The scene the mesh adds itself to. Every material uses the scene's lights and `scene.camera`
-     *              (assigned on `scene.update()` when it is set later).
-     * @return The mesh.
+     * @param camera An initialized camera (e.g. `scene.camera`).
+     * @return The root mesh.
+     * @throws Error when the camera has no buffers.
      */
-    loadBlinnPhongMeshAsync(path: string, scene: Scene): Promise<IMesh>;
+    loadBlinnPhongMeshAsync(path: string, camera: ICamera): Promise<IRenderableMesh>;
 
 }

package/src/api/lights/LightsBuffer.ts

@@ -36,8 +36,9 @@ export interface LightsBufferDescriptor {
 }
 
 /**
- * Holds the lights of a scene and owns the uniform buffer that shaders read them from.
- * Assign it to lit materials, e.g. `ForwardBlinnPhongMaterial.lightsBuffer`.
+ * Holds lights and owns the uniform buffer that shaders read them from.
+ * Each lit material (`ForwardBlinnPhongMaterial`) owns one.
+ *
  *
  * std140 layout of the `LightsBuffer` block:
  * Every light colour is written premultiplied by its intensity, so the layout has no intensity field.
@@ -52,14 +53,20 @@ export interface LightsBuffer extends IDisposable {
     /** The ambient light written to the buffer. */
     ambientLight: AmbientLight;
 
-    /** The directional lights written to the buffer. Read-only; use {@link add} and {@link remove}. Unused slots are black. */
-    readonly directionalLights: readonly DirectionalLight[];
+    /**
+     * The directional lights written to the buffer. Can be replaced by another list, which is then used by reference
+     * (a lit material uses the scene's list). Only the first {@link maxDirectionalLights} are written; unused slots are black.
+     */
+    directionalLights: DirectionalLight[];
 
     /** The number of directional light slots in the buffer. */
     readonly maxDirectionalLights: number;
 
-    /** The point lights written to the buffer. Read-only; use {@link add} and {@link remove}. Unused slots are black. */
-    readonly pointLights: readonly PointLight[];
+    /**
+     * The point lights written to the buffer. Can be replaced by another list, which is then used by reference.
+     * Only the first {@link maxPointLights} are written; unused slots are black.
+     */
+    pointLights: PointLight[];
 
     /** The number of point light slots in the buffer. */
     readonly maxPointLights: number;

package/src/api/loaders/ObjGeometryMapper.ts

@@ -2,7 +2,7 @@ import type {GeometryDescriptor} from "../geometry/IGeometryBuilder.ts";
 import type {ObjGeometryDefinition} from "./obj/index.ts";
 
 /**
- * Maps plain OBJ geometry definitions from {@link ObjLoader} onto the framework's {@link GeometryDescriptor}.
+ * Maps plain OBJ geometry definitions from {@link ObjParser} onto the framework's {@link GeometryDescriptor}.
  * Pass the result to `geometryBuilder.create`.
  * Not part of the public API: `content.loadMeshAsync` and `content.loadBlinnPhongMeshAsync` use it.
  * @internal
@@ -11,7 +11,7 @@ export class ObjGeometryMapper {
 
     /**
      * Creates a geometry descriptor from an OBJ geometry definition.
-     * @param definition The geometry definition, e.g. `result.geometry` from `ObjLoader.loadAsync`.
+     * @param definition The geometry definition, e.g. `result.geometry` from `ObjParser.loadAsync`.
      * @param useMaterialColors True keeps the loader's per-vertex `Kd` colours; false (the default) uses white,
      * for when each submesh's material carries the colour instead.
      * @returns The descriptor. It references the definition's arrays; `geometryBuilder.create` copies them.

package/src/api/loaders/ObjLoader.ts

@@ -0,0 +1,126 @@
+import type {IFramework} from "../IFramework.ts";
+import type {IRenderableMesh} from "../meshes/IRenderableMesh.ts";
+import {RenderableMesh} from "../meshes/RenderableMesh.ts";
+import type {IMaterial} from "../material/IMaterial.ts";
+import {ForwardBlinnPhongMaterialDescriptor} from "../material/ForwardBlinnPhongMaterial.ts";
+import {Color} from "../data/Color.ts";
+import {ObjParser} from "./obj/ObjParser.ts";
+import type {ObjLoadOptions, ObjModel, ObjSubMesh} from "./obj/ObjTypes.ts";
+import {ObjGeometryMapper} from "./ObjGeometryMapper.ts";
+
+/** Creates the material for one OBJ sub mesh (`usemtl` range). */
+export type ObjMaterialFactory = (subMesh: ObjSubMesh) => IMaterial;
+
+/**
+ * Loads OBJ (Wavefront) models into renderable meshes (C# `ObjLoader`). Available as `framework.objLoader`.
+ *
+ * The returned root mesh has no material and owns the vertex and index buffers; each `usemtl` range is a sub mesh
+ * with its own material (ranges with the same material name share one material instance).
+ * Vertex colours are white, the materials carry the colour. Parsing is done by the engine-independent {@link ObjParser}.
+ * @public
+ */
+export class ObjLoader {
+
+    /** Default specular colour when the .mtl has no `Ks` (0.5 grey). */
+    public static readonly DEFAULT_SPECULAR = 0.5;
+
+    /** Default shininess when the .mtl has no `Ns`. */
+    public static readonly DEFAULT_SHININESS = 32;
+
+    /**
+     * The constructor.
+     * @param _framework The framework.
+     */
+    public constructor(private readonly _framework: IFramework) {
+    }
+
+    /**
+     * Parses an .obj file (and its .mtl files) into plain data. Creates no GPU resources (C# `ObjLoader.Parse`).
+     * @param path The .obj URL.
+     * @param options Optional: how to resolve `mtllib` names, or skip materials.
+     * @returns The model.
+     */
+    public static parseAsync(path: string, options?: ObjLoadOptions): Promise<ObjModel> {
+        return new ObjParser().parseAsync(path, options);
+    }
+
+    /**
+     * Loads an .obj file into a renderable mesh with one Blinn-Phong material per `usemtl` range.
+     * The .mtl values map onto `ForwardBlinnPhongMaterial`: `Kd` (with `d` as alpha) → diffuse colour (white when missing),
+     * `Ka` → ambient colour (falls back to `Kd`), `Ks` → specular colour (0.5 grey), `Ns` → shininess (32).
+     * @param path The .obj URL. A relative `mtllib` is resolved against it.
+     * @param descriptor The descriptor every material is created with (camera buffers, primitive state).
+     * @param options Optional parser options.
+     * @returns The root mesh.
+     */
+    public loadAsync(path: string, descriptor: ForwardBlinnPhongMaterialDescriptor, options?: ObjLoadOptions): Promise<IRenderableMesh>;
+
+    /**
+     * Loads an .obj file into a renderable mesh, creating each sub mesh's material with a callback.
+     * @param path The .obj URL.
+     * @param createMaterial Called once per distinct `usemtl` name.
+     * @param options Optional parser options.
+     * @returns The root mesh.
+     */
+    public loadAsync(path: string, createMaterial: ObjMaterialFactory, options?: ObjLoadOptions): Promise<IRenderableMesh>;
+
+    public async loadAsync(path: string,
+                           materialSource: ForwardBlinnPhongMaterialDescriptor | ObjMaterialFactory,
+                           options?: ObjLoadOptions): Promise<IRenderableMesh> {
+        // Validate before fetching, so a bad descriptor fails fast.
+        const createMaterial: ObjMaterialFactory = typeof materialSource === "function"
+            ? materialSource
+            : this._blinnPhongFactory(materialSource);
+        const model = await ObjLoader.parseAsync(path, options);
+        return this.createMesh(model, createMaterial);
+    }
+
+    /**
+     * Creates a renderable mesh from a parsed model.
+     * @param model The model, e.g. from {@link parseAsync}.
+     * @param createMaterial Creates the material per distinct `usemtl` name.
+     * @returns The root mesh, without a material, with one sub mesh per range.
+     */
+    public createMesh(model: ObjModel, createMaterial: ObjMaterialFactory): IRenderableMesh {
+        if (model.subMeshes.length == 0) {
+            throw new Error("ObjLoader: the model has no faces.");
+        }
+        const materialsByName = new Map<string | undefined, IMaterial>();
+        const materials = model.subMeshes.map(subMesh => {
+            let material = materialsByName.get(subMesh.materialName);
+            if (!material) {
+                material = createMaterial(subMesh);
+                materialsByName.set(subMesh.materialName, material);
+            }
+            return material;
+        });
+        const format = materials[0].geometryFormat;
+        if (materials.some(m => m.geometryFormat != format)) {
+            throw new Error("ObjLoader: all materials must use the same geometry format, as the sub meshes share one vertex buffer.");
+        }
+
+        const geometry = this._framework.geometryBuilder.create(ObjGeometryMapper.toDescriptor(model.geometry));
+        const root = new RenderableMesh(this._framework);
+        root.setGeometry(geometry, format);
+        model.subMeshes.forEach((subMesh, i) => root.addSubMesh(materials[i], subMesh.indexStart, subMesh.indexCount));
+        return root;
+    }
+
+    private _blinnPhongFactory(descriptor: ForwardBlinnPhongMaterialDescriptor): ObjMaterialFactory {
+        if (!descriptor?.projectionViewBuffer || !descriptor?.cameraPositionBuffer) {
+            throw new Error("ObjLoader.loadAsync: the Blinn-Phong descriptor needs projectionViewBuffer and cameraPositionBuffer (e.g. camera.projectionViewBuffer and camera.positionBuffer).");
+        }
+        return subMesh => {
+            const definition = subMesh.material;
+            const material = this._framework.materialFactory.createForwardBlinnPhongMaterial(descriptor);
+            const diffuse = definition?.diffuseColor ?? [1, 1, 1];
+            const ambient = definition?.ambientColor ?? diffuse;
+            const specular = definition?.specularColor ?? [ObjLoader.DEFAULT_SPECULAR, ObjLoader.DEFAULT_SPECULAR, ObjLoader.DEFAULT_SPECULAR];
+            material.diffuseColor = new Color(diffuse[0], diffuse[1], diffuse[2], definition?.opacity ?? 1);
+            material.ambientColor = new Color(ambient[0], ambient[1], ambient[2]);
+            material.specularColor = new Color(specular[0], specular[1], specular[2]);
+            material.shininess = definition?.specularExponent ?? ObjLoader.DEFAULT_SHININESS;
+            return material;
+        };
+    }
+}

package/src/api/loaders/_export.ts

@@ -1,3 +1,4 @@
 export * from "./IImageLoader.ts"
 export * from "./ImageLoader.ts"
 export * from "./obj/index.ts"
+export * from "./ObjLoader.ts"