ris-framework 0.1.0 → 0.2.0-dev.11

package/src/api/content/IContentManager.ts

@@ -1,9 +1,11 @@
+import type { Scene } from "../scene/Scene.ts";
 import type { IShaderModuleLoader } from "../shader/IShaderModuleLoader.ts";
 import type { IShaderModule } from "../shader/IShaderModule.ts";
 import type { ITexture2D } from "../rendering/texture/ITexture2D.ts";
 import {TextureDescriptor} from "../rendering/texture/TextureDescriptor.ts";
 import {ContentConfig} from "./ContentConfig.ts";
 import type { IKtx2Texture } from "ris-ktx2";
+import type {IMesh} from "../meshes/IMesh.ts";
 
 /**
  * The content manager.
@@ -26,9 +28,10 @@ export interface IContentManager {
     /**
      * Loads a shader module.
      * @param shaderAssetId - The id of a shader asset.
+     * @param keyValueDictionary - If present, tries to find key in shader such that it replaced ##DIRECTIONAL_LIGHT_COUNT## by given value for key DIRECTIONAL_LIGHST_COUNT.
      * @returns The shader module.
      */
-    loadShaderModule(shaderAssetId: string): IShaderModule;
+    loadShaderModule(shaderAssetId: string, keyValueDictionary?: { [id:string]: number}): IShaderModule;
 
     /**
      * Loads a texture2D.
@@ -38,4 +41,33 @@ export interface IContentManager {
      * @returns The Texture2D.
      */
     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).
+     * @return The mesh.
+     */
+    loadMeshAsync(path: string, scene: Scene): 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.
+     * @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.
+     */
+    loadBlinnPhongMeshAsync(path: string, scene: Scene): Promise<IMesh>;
+
 }

package/src/api/content/ShaderModuleContent.ts

@@ -6,6 +6,9 @@ import inspectTextureMipsVS from "../../../shaders/glsl/inspect_texture_mips_vs.
 import inspectTextureMipsFS from "../../../shaders/glsl/inspect_texture_mips_fs.glsl?raw";
 import unlitMaterialVS from "../../../shaders/glsl/unlit_material_vs.glsl?raw";
 import unlitMaterialFS from "../../../shaders/glsl/unlit_material_fs.glsl?raw";
+import forwardBlinnPhongVS from "../../../shaders/glsl/forward_blinn_phong_material_vs.glsl?raw";
+import forwardBlinnPhongFS from "../../../shaders/glsl/forward_blinn_phong_material_fs.glsl?raw";
+
 
 /**
  * The api should look something like this for internal ones.
@@ -43,5 +46,11 @@ export const ShaderModuleContent : {[id: string]: any} = {
         "vertex": unlitMaterialVS,
         "fragment": unlitMaterialFS,
         "reflection": {}
+    },
+
+    "forward_blinn_phong_material": {
+        "vertex": forwardBlinnPhongVS,
+        "fragment": forwardBlinnPhongFS,
+        "reflection": {}
     }
 }

package/src/api/data/Color.ts

@@ -222,7 +222,13 @@ export class Color implements Iterable<number>{
         o
     }
 
-
+    /**
+     * Copy self and return new instance with same values.
+     * @return Color
+     * */
+    public copy(): Color {
+        return new Color(this.r, this.g, this.b, this.a);
+    }
 }
 
 

package/src/api/geometry/BaseGeometry.ts

@@ -2,11 +2,34 @@ import { GeometryFormat } from "./GeometryFormat.ts";
 import {VertexFormat} from "./VertexFormat.ts";
 import type {IGeometry} from "../index.ts";
 
+
 /**
  * The default IGeometry implementation. GeometryBuilder fills it with vertex data.
  */
 export class BaseGeometry implements IGeometry {
 
+    /**
+     * Initializes a new instance of the BaseGeometry class.
+     * @param positions The optional positions of the geometry.
+     * @param indices The optional indices of the geometry.
+     * @param normals The optional normals of the geometry.
+     * @param textureCoords The optional texture coordinates of the geometry.
+     * @param colors The optional colors of the geometry.
+     */
+    constructor(positions?: number[], indices?: number[], normals?: number[], textureCoords?: number[], colors?: number[]) {
+        this.positions = positions;
+        this.indices = indices;
+        this.normals = normals;
+        this.textureCoords = textureCoords;
+        this.colors = colors;
+
+        if(this.indices && this.indices.length > 0) {
+            this.vertexCount = this.indices.length / 3;
+        } else if(this.positions && this.positions.length > 0) {
+            this.vertexCount = this.positions.length / 3;
+        } 
+    }
+
     /** @inheritdoc */
     public vertexCount: number = 0;
 

package/src/api/geometry/GeometryBuilder.ts

@@ -1,6 +1,6 @@
 import { vec2 } from "gl-matrix"
 import { BaseGeometry } from "./BaseGeometry.ts";
-import type {IGeometry, IGeometryBuilder} from "../index.ts";
+import type {IGeometry, IGeometryBuilder, GeometryDescriptor} from "../index.ts";
 
 /**
  * The GeometryBuilder class provides methods for creating various types of geometries, such as quads, with specified parameters like scale and winding order.
@@ -55,4 +55,16 @@ export class GeometryBuilder implements IGeometryBuilder {
 
         return geometry;
     }
-}
+
+    /** @inheritdoc */
+    public create(descriptor: GeometryDescriptor): IGeometry {
+        const vertexCount = descriptor.positions.length / 3;
+        return new BaseGeometry(
+            [...descriptor.positions],
+            descriptor.indices ? [...descriptor.indices] : undefined,
+            descriptor.normals ? [...descriptor.normals] : new Array(vertexCount * 3).fill(0),
+            descriptor.textureCoords ? [...descriptor.textureCoords] : new Array(vertexCount * 2).fill(0),
+            descriptor.colors ? [...descriptor.colors] : new Array(vertexCount * 4).fill(1),
+        );
+    }
+}

package/src/api/geometry/IGeometryBuilder.ts

@@ -1,6 +1,28 @@
 import type { IGeometry } from "./IGeometry.ts";
 import {vec2} from "gl-matrix";
 
+/**
+ * The geometry descriptor.
+ * @public
+ */
+export interface GeometryDescriptor {
+
+    /** Positions, 3 per vertex. */
+    readonly positions: number[];
+
+    /** Triangle indices, 3 per triangle. Optional for non-indexed geometry. */
+    readonly indices?: number[];
+
+    /** Normals, 3 per vertex. */
+    readonly normals?: number[];
+
+    /** Texture coordinates, 2 per vertex. */
+    readonly textureCoords?: number[];
+
+    /** RGBA colours, 4 per vertex. */
+    readonly colors?: number[];
+}
+
 /**
  * The geometry builder.
  */
@@ -13,5 +35,13 @@ export interface IGeometryBuilder {
  * @returns The geometry.
  */
   quadGeometry(scale?: vec2, counterClockwise?: boolean): IGeometry;
-
+  
+/**
+ * Creates geometry from a plain descriptor.
+ * Attributes a material's geometry format needs but the descriptor lacks are filled with defaults:
+ * white colours, zero texture coordinates and zero normals.
+ * @param descriptor - The geometry descriptor. Its arrays are copied.
+ * @returns The geometry.
+ */
+  create(descriptor: GeometryDescriptor): IGeometry;
 }

package/src/api/geometry/_export-geometry.ts

@@ -1,4 +1,5 @@
 export * from "./IGeometryBuilder.ts";
 export * from "./IGeometry.ts";
 export * from "./VertexFormat.ts";
-export * from "./GeometryFormat.ts";
+export * from "./GeometryFormat.ts";
+export * from "./BaseGeometry.ts";

package/src/api/input/InputManager.ts

@@ -63,6 +63,8 @@ export class InputManager implements IInputManager {
     private readonly _touchCapabilities: TouchPanelCapabilities;
     private readonly _contacts: TouchContact[];
     private _touchListening = false;
+    /** Aborting it removes every canvas listener added in initialize(). */
+    private _listeners = new AbortController();
     /** Set in update, consumed in afterUpdate. Ageing before a publish would hide the press. */
     private _touchPublished = false;
 
@@ -120,6 +122,13 @@ export class InputManager implements IInputManager {
         return this._touchCapabilities;
     }
 
+    /** Removes the canvas listeners. Called from `Framework.dispose()`. */
+    public dispose(): void {
+        this._listeners.abort();
+        this._listeners = new AbortController();
+        this._touchListening = false;
+    }
+
     /** @inheritDoc */
     public initialize(): void {
 
@@ -133,20 +142,20 @@ export class InputManager implements IInputManager {
         canvas.addEventListener("mousemove", (e: MouseEvent) => {
             this._mousePosition[0] = e.clientX;
             this._mousePosition[1] = e.clientY;
-        });
+        }, {signal: this._listeners.signal});
 
         canvas.addEventListener("mousedown", (e: MouseEvent) => {
             const idx = e.button;
             const btn = this._mouseButtonMap[idx] ?? MouseButton.NONE;
             this._mouseButtonDown[btn] = true;
-        })
+        }, {signal: this._listeners.signal})
 
         canvas.addEventListener("mouseup", (e: MouseEvent) => {
             const idx = e.button;
             const btn = this._mouseButtonMap[idx] ?? MouseButton.NONE;
             this._mouseButtonDown[btn] = false;
             this._mouseButtonReleased[btn] = true;
-        });
+        }, {signal: this._listeners.signal});
 
         canvas.addEventListener("wheel", (e: WheelEvent) => {
 
@@ -167,7 +176,7 @@ export class InputManager implements IInputManager {
             vec2.set(this._scrollWheelPosition, x, y);
 
             e.preventDefault();
-        })
+        }, {signal: this._listeners.signal})
     }
 
     private _handleTouchEvents(canvas: HTMLCanvasElement): void {
@@ -179,7 +188,7 @@ export class InputManager implements IInputManager {
         // Pan and pinch-zoom start on this canvas only. The rest of the page is left alone.
         canvas.style.touchAction = "none";
 
-        const options = InputManager._touchListenerOptions;
+        const options: AddEventListenerOptions = {...InputManager._touchListenerOptions, signal: this._listeners.signal};
         canvas.addEventListener("touchstart", this._onTouchStart, options);
         canvas.addEventListener("touchmove", this._onTouchMove, options);
         canvas.addEventListener("touchend", this._onTouchEnd, options);

package/src/api/lights/AmbientLight.ts

@@ -0,0 +1,53 @@
+import {Color} from "../data/Color.ts";
+import {createLightId} from "./LightId.ts";
+import type {Scene} from "../scene/Scene.ts";
+
+/** The descriptor for an ambient light. All fields are optional. */
+export interface AmbientLightDescriptor {
+    /** The unique id. Assigned automatically when omitted. */
+    id?: number;
+
+    /** The optional name for a light. */
+    name?: string;
+
+    /** The light colour. Alpha is ignored. Defaults to black. */
+    color?: Color;
+
+    /** Multiplies the colour. Defaults to 1. */
+    intensity?: number;
+}
+
+/**
+ * The ambient light. Plain data: it has no GPU resources.
+ * Put it into a {@link LightsBuffer} to use it in shaders.
+ * @public
+ */
+export class AmbientLight {
+
+    /**
+     * The constructor.
+     * @param descriptor The optional descriptor. The colour is copied.
+     * @param scene The optional scene to register with.
+     */
+    public constructor(descriptor?: AmbientLightDescriptor, scene?: Scene) {
+
+        this.id = descriptor?.id ?? createLightId();
+        this.name = descriptor?.name;
+        this.color = descriptor?.color?.copy() ?? Color.black();
+        this.intensity = descriptor?.intensity ?? 1;
+
+        scene?.add(this);
+    }
+
+    /** The unique id of this light. */
+    public readonly id: number;
+
+    /** The optional name for a light. */
+    public name?: string;
+
+    /** The light color. Alpha is ignored. */
+    public color: Color;
+
+    /** Multiplies {@link color} when written to the lights buffer. */
+    public intensity: number;
+}

package/src/api/lights/DirectionalLight.ts

@@ -0,0 +1,60 @@
+import {vec3} from "gl-matrix";
+import {Color} from "../data/Color.ts";
+import {createLightId} from "./LightId.ts";
+import type {Scene} from "../scene/Scene.ts";
+
+/** The descriptor for a directional light. All fields are optional. */
+export interface DirectionalLightDescriptor {
+    /** The unique id. Assigned automatically when omitted. */
+    id?: number;
+
+    /** The optional name for a light. */
+    name?: string;
+
+    /** The light colour. Alpha is ignored. Defaults to white. */
+    color?: Color;
+
+    /** Multiplies the colour. Defaults to 1. */
+    intensity?: number;
+
+    /** The direction in which the light travels. Defaults to straight down, (0, -1, 0). */
+    direction?: vec3;
+}
+
+/**
+ * The directional light. Plain data: it has no GPU resources.
+ * @public
+ */
+export class DirectionalLight {
+
+    /**
+     * The constructor.
+     * @param descriptor The optional descriptor. Colour and direction are copied.
+     * @param scene The optional scene; the light adds itself via {@link Scene.add}.
+     * @throws Error when the scene has no free directional light slot left (the light is then not in the scene).
+     */
+    public constructor(descriptor?: DirectionalLightDescriptor, scene?: Scene) {
+        this.id = descriptor?.id ?? createLightId();
+        this.name = descriptor?.name;
+        this.color = descriptor?.color?.copy() ?? Color.white();
+        this.intensity = descriptor?.intensity ?? 1;
+        this.direction = descriptor?.direction ? vec3.clone(descriptor.direction) : vec3.fromValues(0, -1, 0);
+
+        scene?.add(this);
+    }
+
+    /** The unique id of this light. */
+    public readonly id: number;
+
+    /** The optional name for a light. */
+    public name?: string;
+
+    /** The light colour. Alpha is ignored. */
+    public color: Color;
+
+    /** Multiplies {@link color} when written to the lights buffer. */
+    public intensity: number;
+
+    /** The direction in which the light travels. */
+    public direction: vec3;
+}

package/src/api/lights/LightFactory.ts

@@ -0,0 +1,21 @@
+import type {AmbientLight, AmbientLightDescriptor} from "./AmbientLight.ts";
+import type {Scene} from "../scene/Scene.ts";
+import type {LightsBuffer, LightsBufferDescriptor} from "./LightsBuffer.ts";
+
+/** The light factory */
+export interface AmbientLightFactory {
+
+    /**
+     * Creates the ambient light.
+     * @param desc The descriptor for ambient light. The colour defaults to a dim grey; the id is assigned automatically.
+     * @param scene The optional scene to register the light with.
+     */
+    createAmbientLight(desc?: AmbientLightDescriptor, scene?: Scene): AmbientLight;
+
+    /**
+     * Creates a lights buffer, which owns the uniform buffer with all lights for shaders.
+     * @param desc The optional descriptor with the initial lights and directional light count.
+     */
+    __createLightsBuffer(desc?: LightsBufferDescriptor): LightsBuffer;
+
+}

package/src/api/lights/LightId.ts

@@ -0,0 +1,9 @@
+let nextLightId = 1;
+
+/**
+ * Returns a new unique light id. Light constructors call this when no id is given.
+ * @internal
+ */
+export function createLightId(): number {
+    return nextLightId++;
+}

package/src/api/lights/LightsBuffer.ts

@@ -0,0 +1,87 @@
+import type {AmbientLight} from "./AmbientLight.ts";
+import type {DirectionalLight} from "./DirectionalLight.ts";
+import type {PointLight} from "./PointLight.ts";
+import type {IUniformBuffer} from "../rendering/buffers/IUniformBuffer.ts";
+import type {IDisposable} from "../core/IDisposable.ts";
+
+/** The number of directional lights the lights buffer and the Blinn-Phong shader hold by default. */
+export const DEFAULT_DIRECTIONAL_LIGHTS_COUNT = 3;
+
+/** The number of point lights the lights buffer and the Blinn-Phong shader hold by default. */
+export const DEFAULT_POINT_LIGHTS_COUNT = 3;
+
+/** The descriptor for a lights buffer. */
+export interface LightsBufferDescriptor {
+
+    /** The ambient light. Defaults to a black ambient light. */
+    ambientLight?: AmbientLight;
+
+    /** The initial directional lights. More than {@link maxDirectionalLights} throws. */
+    directionalLights?: DirectionalLight[];
+
+    /**
+     * The number of directional light slots. Must match `DIRECTIONAL_LIGHTS_COUNT` in the shader.
+     * Defaults to {@link DEFAULT_DIRECTIONAL_LIGHTS_COUNT}.
+     */
+    maxDirectionalLights?: number;
+
+    /** The initial point lights. More than {@link maxPointLights} throws. */
+    pointLights?: PointLight[];
+
+    /**
+     * The number of point light slots. Must match `POINT_LIGHTS_COUNT` in the shader.
+     * Defaults to {@link DEFAULT_POINT_LIGHTS_COUNT}.
+     */
+    maxPointLights?: number;
+}
+
+/**
+ * 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`.
+ *
+ * std140 layout of the `LightsBuffer` block:
+ * Every light colour is written premultiplied by its intensity, so the layout has no intensity field.
+ * - `vec3 u_ambientLight` at offset 0, padded to 16 bytes.
+ * - `DirectionalLight u_directionalLight[N]` from offset 16, 32 bytes each:
+ *   `vec3 light` at +0 and `vec3 direction` at +16.
+ * - `PointLight u_pointLight[M]` after the directional lights, 48 bytes each:
+ *   `vec3 light` at +0, `float constant` at +12, `vec3 position` at +16, `float linear` at +28, `float quadratic` at +32.
+ */
+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 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 number of point light slots in the buffer. */
+    readonly maxPointLights: number;
+
+    /**
+     * The uniform buffer holding the lights for shaders.
+     * NOTE: Intended to be used internally, never set this value manually.
+     */
+    readonly buffer: IUniformBuffer;
+
+    /**
+     * Adds a directional or point light. Adding a light that is already in the buffer does nothing.
+     * @throws Error when all slots for that kind of light are in use.
+     */
+    add(light: DirectionalLight | PointLight): void;
+
+    /**
+     * Removes a directional or point light.
+     * @returns True when the light was in the buffer.
+     */
+    remove(light: DirectionalLight | PointLight): boolean;
+
+    /** Writes the lights to {@link buffer} if anything changed since the last update. Call once per frame before rendering. */
+    update(): void;
+}

package/src/api/lights/PointLight.ts

@@ -0,0 +1,91 @@
+import {vec3} from "gl-matrix";
+import {Color} from "../data/Color.ts";
+import {createLightId} from "./LightId.ts";
+import type {Scene} from "../scene/Scene.ts";
+
+/** The descriptor for a point light. All fields are optional. */
+export interface PointLightDescriptor {
+    /** The unique id. Assigned automatically when omitted. */
+    id?: number;
+
+    /** The optional name for a light. */
+    name?: string;
+
+    /** The light colour. Alpha is ignored. Defaults to white. */
+    color?: Color;
+
+    /** Multiplies the colour. Defaults to 1. */
+    intensity?: number;
+
+    /** World-space position. Defaults to the origin. */
+    position?: vec3;
+
+    /** Constant attenuation term. Defaults to 1. */
+    constant?: number;
+
+    /** Linear attenuation term. Defaults to 0.09 (about 50 units of range). */
+    linear?: number;
+
+    /** Quadratic attenuation term. Defaults to 0.032 (about 50 units of range). */
+    quadratic?: number;
+}
+
+/**
+ * The point light. Plain data: it has no GPU resources.
+ * Attenuation is `1 / (constant + linear * d + quadratic * d²)` for distance `d`.
+ * @public
+ */
+export class PointLight {
+
+    /** The default constant attenuation. */
+    public static readonly DEFAULT_CONSTANT = 1;
+
+    /** The default linear attenuation. */
+    public static readonly DEFAULT_LINEAR = 0.09;
+
+    /** The default quadratic attenuation. */
+    public static readonly DEFAULT_QUADRATIC = 0.032;
+
+    /**
+     * The constructor.
+     * @param descriptor The optional descriptor. Colour and position are copied.
+     * @param scene The optional scene; the light adds itself via {@link Scene.add}.
+     * @throws Error when the scene has no free point light slot left (the light is then not in the scene).
+     */
+    public constructor(descriptor?: PointLightDescriptor, scene?: Scene) {
+        this.id = descriptor?.id ?? createLightId();
+        this.name = descriptor?.name;
+        this.color = descriptor?.color?.copy() ?? Color.white();
+        this.intensity = descriptor?.intensity ?? 1;
+        this.position = descriptor?.position ? vec3.clone(descriptor.position) : vec3.create();
+        this.constant = descriptor?.constant ?? PointLight.DEFAULT_CONSTANT;
+        this.linear = descriptor?.linear ?? PointLight.DEFAULT_LINEAR;
+        this.quadratic = descriptor?.quadratic ?? PointLight.DEFAULT_QUADRATIC;
+
+        scene?.add(this);
+    }
+
+    /** The unique id of this light. */
+    public readonly id: number;
+
+    /** The optional name for a light. */
+    public name?: string;
+
+    /** The light colour. Alpha is ignored. */
+    public color: Color;
+
+    /** Multiplies {@link color} when written to the lights buffer. */
+    public intensity: number;
+
+    /** World-space position of the light. */
+    public position: vec3;
+
+    /** Constant attenuation term. */
+    public constant: number;
+
+    /** Linear attenuation term. */
+    public linear: number;
+
+    /** Quadratic attenuation term. */
+    public quadratic: number;
+}

package/src/api/lights/_export.ts

@@ -0,0 +1,5 @@
+export * from "./AmbientLight.ts";
+export * from "./DirectionalLight.ts";
+export * from "./PointLight.ts";
+export * from "./LightsBuffer.ts";
+export * from "./LightFactory.ts";

package/src/api/loaders/ObjGeometryMapper.ts

@@ -0,0 +1,28 @@
+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}.
+ * Pass the result to `geometryBuilder.create`.
+ * Not part of the public API: `content.loadMeshAsync` and `content.loadBlinnPhongMeshAsync` use it.
+ * @internal
+ */
+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 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.
+     */
+    public static toDescriptor(definition: ObjGeometryDefinition, useMaterialColors = false): GeometryDescriptor {
+        return {
+            positions: definition.positions,
+            indices: definition.indices,
+            normals: definition.normals,
+            textureCoords: definition.textureCoords,
+            colors: useMaterialColors ? definition.colors : undefined,
+        };
+    }
+}

package/src/api/loaders/_export.ts

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