ris-framework 0.1.0 → 0.2.0-dev.11

package/shaders/glsl/unlit_material_fs.glsl

@@ -7,7 +7,7 @@ in vec2 v_texCoords;
 layout(location = 0) out vec4 o_outputColor;
 
 layout(std140) uniform MaterialBuffer
- {
+{
     vec4 diffuseColor;
 };
 

package/src/Framework.ts

@@ -1,7 +1,7 @@
-import {container, type DependencyContainer} from "tsyringe";
+import {WebGlAmbientLightFactory} from "./webgl/lights/WebGlAmbientLightFactory.ts";
 import {WindowManager} from "./api/window/WindowManager.ts";
 import {FrameworkConfiguration} from "./api/FrameworkConfiguration.ts";
-import {type IRendererConfiguration, RenderConfigurationSymbol} from "./api/rendering/renderer-interface.ts";
+import {type IRendererConfiguration} from "./api/rendering/renderer-interface.ts";
 import {GeometryBuilder} from "./api/geometry/GeometryBuilder.ts";
 import {ContentManager} from "./api/content/ContentManager.ts";
 import {WebGlRenderer} from "./webgl/WebGlRenderer.ts";
@@ -26,6 +26,7 @@ import {
     type IInputManager,
     ImageLoader,
     type IMaterialFactory,
+    type AmbientLightFactory,
     type IMeshFactory,
     type ISpriteBatch,
     type ITextureFactory,
@@ -35,6 +36,8 @@ import {
     RenderingBackend,
     TimeManager
 } from "./api/index.ts";
+import {WebGlTexture2D} from "./webgl/texture/WebGlTexture2D.ts";
+import type {IDisposable} from "./api/core/IDisposable.ts";
 import {WebGlShaderModuleLoader} from "./webgl/shader/WebGlShaderModuleLoader.ts";
 import {TextureSamplerFilteringPreset} from "./core/rendering/enums.ts";
 import {SpriteBatch} from "./api/sprites/SpriteBatch.ts";
@@ -53,12 +56,12 @@ export class Framework implements IFramework {
     private readonly _onUpdateListeners: ((gameTime: GameTime) => void)[] = [];
     private readonly _onRenderListeners: (() => void)[] = [];
 
-    private readonly _container: DependencyContainer;
     private readonly _textureFactory: ITextureFactory;
     private readonly _buffersFactory: IBufferFactory;
     private readonly _contentManager: IContentManager;
     private readonly _geometryBuilder: IGeometryBuilder;
     private readonly _meshFactory: IMeshFactory;
+    private _disposed = false;
 
     /**
      * The constructor for the Framework class.
@@ -73,17 +76,15 @@ export class Framework implements IFramework {
         }
         options.backBufferSize = options.backBufferSize ?? vec2.fromValues(800, 600);
 
-        this._container = container.createChildContainer();
         this.windowManager = new WindowManager(options.canvas ?? null);
 
-        // Setup container.
+        // Services are created here and get their dependencies through their constructors.
         const rendererConfig: IRendererConfiguration = {
             backBufferSize: options.backBufferSize,
             textureFiltering: options.textureFiltering ?? TextureSamplerFilteringPreset.BILINEAR,
             alpha: options.alpha ?? false,
             powerPreference: options.powerPreference ?? PowerPreferenceType.DEFAULT
         };
-        this._container.registerInstance(RenderConfigurationSymbol, rendererConfig);
         this.renderer = new WebGlRenderer(this, rendererConfig);
         this.renderingBackend = RenderingBackend.WEB_GL;
         this._textureFactory = new WebGlTextureFactory(this);
@@ -92,6 +93,7 @@ export class Framework implements IFramework {
         this._contentManager = new ContentManager(this, new WebGlShaderModuleLoader(this));
         this._meshFactory = new MeshFactory(this);
         this.materialFactory = new MaterialFactory(this);
+        this.lightsFactory = new WebGlAmbientLightFactory(this);
 
         this._buffersFactory = new WebGlBuffersFactory(this);
         this.spriteBatch = new SpriteBatch(this);
@@ -216,6 +218,9 @@ export class Framework implements IFramework {
     /** @inheritDoc */
     public readonly materialFactory: IMaterialFactory;
 
+    /** @inheritDoc */
+    public readonly lightsFactory: AmbientLightFactory;
+
     /** @inheritDoc */
     public readonly timeManager: ITimeManager;
 
@@ -235,12 +240,13 @@ export class Framework implements IFramework {
 
         this.timeManager.prepareStart();
 
-        // Load content events.
-        for(const listener of this._onLoadContentListeners){
+        // Initialize callbacks.
+        for(const listener of this._onInitializeListeners){
             listener();
         }
 
-        for(const listener of this._onInitializeListeners){
+        // Load content events.
+        for(const listener of this._onLoadContentListeners){
             listener();
         }
 
@@ -271,10 +277,28 @@ export class Framework implements IFramework {
         this.windowManager.runEventLoop();
     }
 
-    /** @inheritDoc */
-    public dispose() {
-       //  this.windowManager.dispose();
+    /**
+     * Stops the event loop and disposes the framework's services and GL resources,
+     * including per-framework caches such as the default texture and the shader modules.
+     * A new `Framework` afterwards creates fresh resources on its own context. Calling it twice does nothing.
+     */
+    public dispose(): void {
+        if (this._disposed) {
+            return;
+        }
+        this._disposed = true;
+
+        this.windowManager.dispose();
+        (this.input as Partial<IDisposable>).dispose?.();
+
+        this._onLoadContentListeners.length = 0;
+        this._onInitializeListeners.length = 0;
+        this._onUpdateListeners.length = 0;
+        this._onRenderListeners.length = 0;
 
-        // TODO: dispose of other resources
+        WebGlTexture2D.disposeDefault(this);
+        (this._contentManager as Partial<IDisposable>).dispose?.();
+        // Only exists after initialize(); it owns the default sampler and blend state.
+        (this.renderer.graphicsDevice as IGraphicsDevice | undefined)?.dispose();
     }
 }

package/src/api/IFramework.ts

@@ -11,6 +11,7 @@ import type { IContentManager } from "./content/IContentManager.ts";
 import type { IImageLoader } from "./loaders/IImageLoader.ts";
 import type { IMeshFactory } from "./meshes/IMeshFactory.ts";
 import type { IMaterialFactory } from "./material/IMaterialFactory.ts";
+import type { AmbientLightFactory } from "./lights/LightFactory.ts";
 import type { ITimeManager } from "./time/ITimeManager.ts";
 import type { IInputManager } from "./input/IInputManager.ts";
 import type { IWindowManager } from "./window/IWindowManager.ts";
@@ -91,6 +92,11 @@ export interface IFramework extends IDisposable {
      */
     readonly materialFactory: IMaterialFactory;
 
+    /**
+     * The ambient light factory.
+     */
+    readonly lightsFactory: AmbientLightFactory;
+
     /**
      * The time manager.
      */
@@ -117,14 +123,10 @@ export interface IFramework extends IDisposable {
      */
     removeOnLoadContentListener(event: () => void): void;
 
-    /**
-     * Called when the framework is initialized.
-     */
+    /** Called when the framework is initialized.*/
     addOnInitializedListener(event: () => void): void;
 
-    /**
-     * Called when the framework is initialized.
-     */
+    /** Called when the framework is initialized.*/
     removeOnInitializedListener(event: () => void): void;
 
     /**

package/src/api/_export.ts

@@ -22,5 +22,7 @@ export * from "./rendering/sampler/_export.ts"
 export * from "./utilities/_export.ts"
 export * from "./meshes/_export.ts";
 export * from "./material/_export.ts";
+export * from "./lights/_export.ts";
+export * from "./scene/Scene.ts";
 export * from "./input/_export.ts";
 export * from "./image/_export.ts";

package/src/api/camera/CameraFactory.ts

@@ -1,11 +1,11 @@
 import  {vec2} from "gl-matrix";
 import type { ICameraFactory } from "./ICameraFactory.ts";
+import type { Scene } from "../scene/Scene.ts";
 import type { IFramework } from "../IFramework.ts";
 import type { IOrthographicCamera } from "./IOrthographicCamera.ts";
 import {OrthographicCamera} from "./OrthographicCamera.ts";
 import {OrbitCamera} from "./OrbitCamera.ts";
-import {PerspectiveCamera} from "./PerspectiveCamera.ts";
-import {MathHelper} from "../utilities/MathHelper.ts";
+import {PerspectiveCamera, type PerspectiveCameraDescriptor} from "./PerspectiveCamera.ts";
 
 /** The Camera Factory */
 export class CameraFactory implements ICameraFactory {
@@ -41,15 +41,15 @@ export class CameraFactory implements ICameraFactory {
 
     /** @inheritDoc */
     public createOrbitCamera(fov = 60, aspectRatio = 1, near = 0.01, far = 100): OrbitCamera {
-        return new OrbitCamera(this.createPerspectiveCamera(fov, aspectRatio, near, far), this._framework.input);
+        return new OrbitCamera(this.createPerspectiveCamera({fov, aspectRatio, near, far}), this._framework.input);
 
     }
 
     /** @inheritDoc */
-    public createPerspectiveCamera(fov= 60, aspectRatio = 1, near= 0.01, far = 100): PerspectiveCamera {
-        fov = MathHelper.toRadians(fov);
-        const camera = new PerspectiveCamera(this._framework, fov, aspectRatio, near, far);
+    public createPerspectiveCamera(descriptor?: PerspectiveCameraDescriptor, scene? : Scene): PerspectiveCamera {
+        const camera = new PerspectiveCamera(this._framework, descriptor, scene);
         camera.initialize();
+
         return camera;
     }
 

package/src/api/camera/ICamera.ts

@@ -36,6 +36,12 @@ export interface ICamera extends IDisposable {
      */
     readonly viewBuffer: IUniformBuffer;
 
+    /**
+     * The world-space eye position buffer, std140 `vec3` (`[x, y, z, 0]`).
+     * Used by lit materials for specular highlights.
+     */
+    readonly positionBuffer: IUniformBuffer;
+
     /**
      * Update the GPU buffers.
      * This needs to be called when camera properties are changed.

package/src/api/camera/ICameraFactory.ts

@@ -1,7 +1,8 @@
 import type { IOrthographicCamera } from "./IOrthographicCamera.ts";
 import {vec2} from "gl-matrix";
 import {OrbitCamera} from "./OrbitCamera.ts";
-import {PerspectiveCamera} from "./PerspectiveCamera.ts";
+import {PerspectiveCamera, type PerspectiveCameraDescriptor} from "./PerspectiveCamera.ts";
+import type {Scene} from "../scene/Scene.ts";
 
 /**
  * The camera factory.
@@ -10,17 +11,11 @@ export interface ICameraFactory {
 
     /**
      * Creates a new perspective camera.
-     * @param fov The field of view. By default, 60 degrees.
-     * @param aspectRatio The aspect ratio. By default, 1.
-     * @param near The near plane. By default, 0.01.
-     * @param far The far plane. By default, 100.
+     * @param descriptor The optional descriptor; omitted fields use the defaults documented on {@link PerspectiveCameraDescriptor}.
+     * @param scene The optional scene; the camera becomes its `scene.camera`.
      * @return The perspective camera.
      */
-    createPerspectiveCamera(
-        fov?: number,
-        aspectRatio?: number,
-        near?: number,
-        far?: number): PerspectiveCamera;
+    createPerspectiveCamera(descriptor?: PerspectiveCameraDescriptor, scene?: Scene): PerspectiveCamera;
 
     /**
      * Creates a new orthographic camera which is suitable for 2D games, or for UI rendering.

package/src/api/camera/OrthographicCamera.ts

@@ -40,6 +40,9 @@ export class OrthographicCamera implements IOrthographicCamera {
     private _projectionBuffer: IUniformBuffer = null!;
     private _viewBuffer: IUniformBuffer = null!;
     private _projectionViewBuffer: IUniformBuffer = null!;
+    private _positionBuffer: IUniformBuffer = null!;
+    /** std140 vec3 world-space eye, padded to 4 floats. */
+    private readonly _positionData = [0, 0, 0, 0];
 
     /**
      *
@@ -69,7 +72,7 @@ export class OrthographicCamera implements IOrthographicCamera {
         this._near = near;
         this._far = far;
 
-        this._eye = vec3.fromValues(0, 0, -1);
+        this._eye = vec3.fromValues(0, 0, 1);
         this._target = vec3.fromValues(0, 0, 0);
 
         this._zSpaceLength = 2; // For WebGL2 it is 2, WebGPU it is 1.
@@ -204,6 +207,19 @@ export class OrthographicCamera implements IOrthographicCamera {
         return this._viewBuffer;
     }
 
+    /** @inheritDoc */
+    public get positionBuffer(): IUniformBuffer {
+        return this._positionBuffer;
+    }
+
+    /** Writes the world-space eye into the std140 position data (no z flip: the look-at uses the eye as is). */
+    private _updatePositionData(): number[] {
+        this._positionData[0] = this._eye[0];
+        this._positionData[1] = this._eye[1];
+        this._positionData[2] = this._eye[2];
+        return this._positionData;
+    }
+
     /**
      * Updates the camera matrices.
      */
@@ -227,6 +243,10 @@ export class OrthographicCamera implements IOrthographicCamera {
         this._projectionViewBuffer = this._framework.bufferFactory.createUniformBuffer(
             this._projectionViewMatrix, BufferUsage.UNIFORM, "OrthographicCamera.projectionViewBuffer"
         );
+
+        this._positionBuffer = this._framework.bufferFactory.createUniformBuffer(
+            this._updatePositionData(), BufferUsage.UNIFORM, "OrthographicCamera.positionBuffer"
+        );
     }
 
     /** @inheritDoc */
@@ -235,6 +255,7 @@ export class OrthographicCamera implements IOrthographicCamera {
         this.projectionBuffer.update(this.projectionMatrix);
         this.viewBuffer.update(this.viewMatrix);
         this.projectionViewBuffer.update(this.projectionViewMatrix);
+        this.positionBuffer.update(this._updatePositionData());
     }
 
     /** @inheritDoc */
@@ -253,5 +274,6 @@ export class OrthographicCamera implements IOrthographicCamera {
         this.projectionBuffer.dispose();
         this.projectionViewBuffer.dispose();
         this.viewBuffer.dispose();
+        this.positionBuffer.dispose();
     }
 }

package/src/api/camera/PerspectiveCamera.ts

@@ -5,6 +5,34 @@ import {MathHelper} from "../utilities/MathHelper.ts";
 import {BufferUsage} from "../rendering/buffers/BufferUsage.ts";
 import type { IUniformBuffer } from "../rendering/buffers/IUniformBuffer.ts";
 import {GameTime} from "../time/GameTime.ts";
+import type {Scene} from "../scene/Scene.ts";
+
+/**
+ * The descriptor for a perspective camera. Every field is optional.
+ */
+export interface PerspectiveCameraDescriptor {
+
+    /** The vertical field of view in degrees. By default, 60. */
+    fov?: number;
+
+    /** The aspect ratio (width / height). By default, 1. */
+    aspectRatio?: number;
+
+    /** The near plane. By default, 0.01. */
+    near?: number;
+
+    /** The far plane. By default, 100. */
+    far?: number;
+
+    /** The eye position. Copied. By default, (0, 0, 3). */
+    eye?: vec3;
+
+    /** The point the camera looks at. Copied. By default, the origin. */
+    target?: vec3;
+
+    /** The up vector. Copied. By default, (0, 1, 0). */
+    up?: vec3;
+}
 
 /**
  * The perspective camera.
@@ -26,24 +54,33 @@ export class PerspectiveCamera implements ICamera {
     private _projectionBuffer: IUniformBuffer = null!;
 
     /**
-     * The constructor.
+     * The constructor. Call `initialize()` before use (the camera factory does).
      * @param framework The framework.
-     * @param fov The field of view in radians.
-     * @param aspectRatio The aspect ratio.
-     * @param nearPlane The near plane.
-     * @param farPlane The far plane.
+     * @param descriptor The optional descriptor; omitted fields use the defaults documented on {@link PerspectiveCameraDescriptor}.
+     *                   `fov` is in degrees; {@link fieldOfView} holds it in radians. Vectors are copied.
+     * @param scene The optional scene; the camera assigns itself as `scene.camera`.
      */
     public constructor(
         framework: IFramework,
-        fov: number,
-        aspectRatio: number,
-        nearPlane: number,
-        farPlane: number) {
+        descriptor?: PerspectiveCameraDescriptor,
+        scene?: Scene) {
         this._framework = framework;
-        this.fieldOfView = fov;
-        this.aspectRatio = aspectRatio;
-        this.nearPlane = nearPlane;
-        this.farPlane = farPlane;
+        this.fieldOfView = MathHelper.toRadians(descriptor?.fov ?? 60);
+        this.aspectRatio = descriptor?.aspectRatio ?? 1;
+        this.nearPlane = descriptor?.near ?? 0.01;
+        this.farPlane = descriptor?.far ?? 100;
+        if (descriptor?.eye) {
+            vec3.copy(this.eye, descriptor.eye);
+        }
+        if (descriptor?.target) {
+            vec3.copy(this.target, descriptor.target);
+        }
+        if (descriptor?.up) {
+            vec3.copy(this.up, descriptor.up);
+        }
+        if (scene) {
+            scene.add(this);
+        }
 
         this._updateMatrices();
     }
@@ -159,12 +196,20 @@ export class PerspectiveCamera implements ICamera {
      */
     public initialize(): void {
         const bufferUsage = BufferUsage.UNIFORM | BufferUsage.COPY_DST;
-        this._positionBuffer = this._framework.bufferFactory.createUniformBuffer(this.eye, bufferUsage);
+        this._positionBuffer = this._framework.bufferFactory.createUniformBuffer(this._worldEye(), bufferUsage);
         this._projectionViewBuffer = this._framework.bufferFactory.createUniformBuffer(this.projectionViewMatrix, bufferUsage);
         this._projectionBuffer = this._framework.bufferFactory.createUniformBuffer(this.projectionMatrix, bufferUsage);
         this._viewBuffer = this._framework.bufferFactory.createUniformBuffer(this.viewMatrix, bufferUsage);
     }
 
+    /**
+     * The eye in world space, as used by the view matrix: z is flipped for the right-handed look-at.
+     * This is what {@link positionBuffer} holds, std140 `vec3` (padded to 16 bytes).
+     */
+    private _worldEye(): number[] {
+        return [this.eye[0], this.eye[1], -this.eye[2], 0];
+    }
+
     /**
      * Updates the camera matrices.
      */
@@ -190,7 +235,7 @@ export class PerspectiveCamera implements ICamera {
 
     /** @inheritDoc */
     public updateBuffers(): void {
-        this._positionBuffer.update(this.eye);
+        this._positionBuffer.update(this._worldEye());
         this._projectionBuffer.update(this.projectionMatrix);
         this._viewBuffer.update(this.viewMatrix);
         this._projectionViewBuffer.update(this.projectionViewMatrix);

package/src/api/content/ContentManager.ts

@@ -3,12 +3,29 @@ import {
     type IContentManager,
     type IShaderModuleLoader,
     type ITexture2D,
-    type IFramework, TextureDescriptor, TextureFormat, ContentConfig, TextureUsage
+    type IFramework,
+    TextureDescriptor,
+    TextureFormat,
+    ContentConfig,
+    TextureUsage,
+    type IMesh,
+    ObjLoader,
+    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 {Ktx2Factory} from "ris-ktx2";
 import type {IKtx2Texture} from "ris-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.
@@ -17,6 +34,7 @@ export class ContentManager implements IContentManager {
 
     private readonly _ktx2Factory = new Ktx2Factory();
     private readonly _ktx2TextureCache: {[key: string]: IKtx2Texture} = {};
+    private readonly _objLoader = new ObjLoader();
 
     /**
      * The constructor.
@@ -41,9 +59,20 @@ export class ContentManager implements IContentManager {
         return ktx2Texture;
     }
 
+    /**
+     * Disposes the cached shader modules (their GL programs) and forgets cached KTX2 data.
+     * Called from `Framework.dispose()`.
+     */
+    public dispose(): void {
+        (this.shaderModuleLoader as Partial<IDisposable>).dispose?.();
+        for (const key of Object.keys(this._ktx2TextureCache)) {
+            delete this._ktx2TextureCache[key];
+        }
+    }
+
     /** @inheritDoc */
-    public loadShaderModule(shaderModuleId: string): IShaderModule {
-        return this.shaderModuleLoader.load(shaderModuleId);
+    public loadShaderModule(shaderModuleId: string,  keyValueDictionary?: { [id:string]: number}): IShaderModule {
+        return this.shaderModuleLoader.load(shaderModuleId,  keyValueDictionary);
     }
 
     /** @inheritDoc */
@@ -84,4 +113,171 @@ export class ContentManager implements IContentManager {
         return this._framework.textureFactory.create(width, height, view);
     }
 
-}
+    /** @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);
+    }
+
+    /** @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,
+        });
+
+        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({
+            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;
+    }
+}