ris-framework 0.1.0-dev.9 → 0.2.0-dev.11

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"

package/src/api/loaders/obj/ObjLoader.ts

@@ -0,0 +1,270 @@
+import {
+    ObjMaterialDefinition,
+    type ObjColor,
+    type ObjLoadResult,
+    type ObjLoadOptions,
+    type ObjMaterialRange,
+} from "./ObjTypes.ts";
+
+function tokens(line: string): string[] {
+    return line.trim().split(/\s+/);
+}
+
+function readColor(parts: string[]): ObjColor | undefined {
+    // "Kd spectral ..." and "Kd xyz ..." are not supported.
+    if (parts.length < 2 || isNaN(parseFloat(parts[1]))) {
+        return undefined;
+    }
+    const r = parseFloat(parts[1]);
+    const g = parts.length > 2 ? parseFloat(parts[2]) : r;
+    const b = parts.length > 3 ? parseFloat(parts[3]) : r;
+    return [r, g, b];
+}
+
+/**
+ * Loads .obj models (and their .mtl materials) from text or a URL into plain data.
+ * Engine-independent; uses only `fetch` and `URL`. `content.loadMeshAsync` turns the result into a framework mesh.
+ */
+export class ObjLoader {
+
+    /**
+     * Parses .mtl text.
+     * @param text The .mtl contents.
+     * @returns The material definitions, in file order.
+     */
+    public parseMtl(text: string): ObjMaterialDefinition[] {
+        const materials: ObjMaterialDefinition[] = [];
+        let current: ObjMaterialDefinition | undefined;
+
+        for (const rawLine of text.split(/\r?\n/)) {
+            const line = rawLine.trim();
+            if (line.length == 0 || line.startsWith("#")) {
+                continue;
+            }
+            const parts = tokens(line);
+            const keyword = parts[0];
+
+            if (keyword == "newmtl") {
+                current = new ObjMaterialDefinition(line.substring(keyword.length).trim());
+                materials.push(current);
+                continue;
+            }
+            if (!current) {
+                continue;
+            }
+
+            switch (keyword) {
+                case "Ka":
+                    current.ambientColor = readColor(parts);
+                    break;
+                case "Kd":
+                    current.diffuseColor = readColor(parts);
+                    break;
+                case "Ks":
+                    current.specularColor = readColor(parts);
+                    break;
+                case "Ke":
+                    current.emissiveColor = readColor(parts);
+                    break;
+                case "Ns":
+                    current.specularExponent = parseFloat(parts[1]);
+                    break;
+                case "Ni":
+                    current.opticalDensity = parseFloat(parts[1]);
+                    break;
+                case "illum":
+                    current.illuminationModel = parseInt(parts[1]);
+                    break;
+                case "d":
+                    current.opacity = parseFloat(parts[parts.length - 1]);
+                    break;
+                case "Tr":
+                    // "d" wins when both are present.
+                    if (current.opacity === undefined) {
+                        current.opacity = 1 - parseFloat(parts[1]);
+                    }
+                    break;
+                default:
+                    if (keyword.startsWith("map_") || keyword == "bump" || keyword == "disp"
+                        || keyword == "decal" || keyword == "refl" || keyword == "norm") {
+                        if (parts.length >= 2) {
+                            current.maps[keyword] = parts[parts.length - 1];
+                            if (parts.length > 2) {
+                                current.mapOptions[keyword] = parts.slice(1, -1).join(" ");
+                            }
+                        }
+                    }
+                    break;
+            }
+        }
+
+        return materials;
+    }
+
+    /**
+     * Parses .obj text.
+     * @param text The .obj contents.
+     * @param materials Material definitions to use for `usemtl`, e.g. from {@link parseMtl}. Default none.
+     * @returns The geometry, materials and raw data.
+     */
+    public fromText(text: string, materials: ObjMaterialDefinition[] = []): ObjLoadResult {
+        const rawPositions: number[] = [];
+        const rawTextureCoords: number[] = [];
+        const rawNormals: number[] = [];
+        const faceIndices: number[] = [];
+        const materialLibraries: string[] = [];
+        const materialRanges: ObjMaterialRange[] = [];
+
+        const positions: number[] = [];
+        const textureCoords: number[] = [];
+        const normals: number[] = [];
+        const colors: number[] = [];
+        const indices: number[] = [];
+        const vertexLookup = new Map<string, number>();
+
+        const materialsByName = new Map(materials.map(m => [m.name, m]));
+        let materialName: string | undefined;
+        let rangeStart = 0;
+
+        const closeRange = () => {
+            if (indices.length > rangeStart) {
+                materialRanges.push({materialName, indexStart: rangeStart, indexCount: indices.length - rangeStart});
+            }
+            rangeStart = indices.length;
+        };
+
+        const resolve = (value: string | undefined, count: number): number => {
+            if (value === undefined || value.length == 0) {
+                return -1;
+            }
+            const index = parseInt(value);
+            // OBJ indices are one-based; negative values count back from the end.
+            return index < 0 ? count + index : index - 1;
+        };
+
+        const addCorner = (p: number, t: number, n: number): void => {
+            faceIndices.push(p, t, n);
+            const key = `${p}/${t}/${n}/${materialName ?? ""}`;
+            let vertex = vertexLookup.get(key);
+            if (vertex === undefined) {
+                vertex = positions.length / 3;
+                vertexLookup.set(key, vertex);
+                positions.push(rawPositions[p * 3], rawPositions[p * 3 + 1], rawPositions[p * 3 + 2]);
+                textureCoords.push(t >= 0 ? rawTextureCoords[t * 2] : 0, t >= 0 ? rawTextureCoords[t * 2 + 1] : 0);
+                normals.push(n >= 0 ? rawNormals[n * 3] : 0, n >= 0 ? rawNormals[n * 3 + 1] : 0, n >= 0 ? rawNormals[n * 3 + 2] : 0);
+                const material = materialName !== undefined ? materialsByName.get(materialName) : undefined;
+                const kd = material?.diffuseColor ?? [1, 1, 1];
+                colors.push(kd[0], kd[1], kd[2], material?.opacity ?? 1);
+            }
+            indices.push(vertex);
+        };
+
+        for (const rawLine of text.split(/\r?\n/)) {
+            const line = rawLine.trim();
+            if (line.length == 0 || line.startsWith("#")) {
+                continue;
+            }
+            const parts = tokens(line);
+
+            switch (parts[0]) {
+                case "v":
+                    rawPositions.push(parseFloat(parts[1]), parseFloat(parts[2]), parseFloat(parts[3]));
+                    break;
+                case "vt":
+                    rawTextureCoords.push(parseFloat(parts[1]), parts.length > 2 ? parseFloat(parts[2]) : 0);
+                    break;
+                case "vn":
+                    rawNormals.push(parseFloat(parts[1]), parseFloat(parts[2]), parseFloat(parts[3]));
+                    break;
+                case "f": {
+                    const corners = parts.slice(1).map(corner => {
+                        const [p, t, n] = corner.split("/");
+                        return [
+                            resolve(p, rawPositions.length / 3),
+                            resolve(t, rawTextureCoords.length / 2),
+                            resolve(n, rawNormals.length / 3),
+                        ];
+                    });
+                    // Triangulate polygons as a fan.
+                    for (let i = 1; i + 1 < corners.length; i++) {
+                        addCorner(corners[0][0], corners[0][1], corners[0][2]);
+                        addCorner(corners[i][0], corners[i][1], corners[i][2]);
+                        addCorner(corners[i + 1][0], corners[i + 1][1], corners[i + 1][2]);
+                    }
+                    break;
+                }
+                case "mtllib":
+                    materialLibraries.push(...parts.slice(1));
+                    break;
+                case "usemtl":
+                    closeRange();
+                    materialName = line.substring(parts[0].length).trim();
+                    break;
+            }
+        }
+        closeRange();
+
+        if(positions.length == 0){
+            throw new Error("Invalid obj file.");
+        }
+
+        return {
+            geometry: {
+                positions, textureCoords, normals, colors, indices,
+                vertexCount: positions.length / 3,
+                materialRanges,
+            },
+            materials,
+            materialLibraries,
+            raw: {positions: rawPositions, textureCoords: rawTextureCoords, normals: rawNormals, faceIndices},
+        };
+    }
+
+    /**
+     * Loads an .obj file and the .mtl files it references with `mtllib`.
+     * A missing or failing .mtl is skipped (logged as a warning); the model still loads with white vertex colours.
+     * @param filePath The .obj URL.
+     * @param options Optional: how to resolve `mtllib` names, or skip materials.
+     * @returns The geometry, materials and raw data.
+     */
+    public async loadAsync(filePath: string, options?: ObjLoadOptions): Promise<ObjLoadResult> {
+        const response = await fetch(filePath);
+        if (!response.ok) {
+            throw new Error(`Failed to load OBJ '${filePath}': ${response.status} ${response.statusText}`);
+        }
+        const text = await response.text();
+
+        const materials: ObjMaterialDefinition[] = [];
+
+        const libraries = options?.ignoreMaterials ? [] : text.split(/\r?\n/)
+            .map(line => tokens(line))
+            .filter(parts => parts[0] == "mtllib")
+            .flatMap(parts => parts.slice(1));
+
+        // data: and blob: URLs have no directory, so relative names cannot be resolved against them.
+        const opaqueUrl = /^(data|blob):/i.test(filePath);
+        for (const library of libraries) {
+            try {
+                let mtlUrl: string;
+                if (options?.resolveMaterialUrl) {
+                    mtlUrl = options.resolveMaterialUrl(library);
+                } else if (opaqueUrl) {
+                    throw new Error("the OBJ was loaded from a data: or blob: URL (e.g. a bundler-inlined asset), so the name cannot be resolved; pass options.resolveMaterialUrl");
+                } else {
+                    mtlUrl = filePath.substring(0, filePath.lastIndexOf("/") + 1) + library;
+                }
+                const mtlResponse = await fetch(mtlUrl);
+
+                if (!mtlResponse.ok) {
+                    throw new Error(`${mtlResponse.status} ${mtlResponse.statusText}`);
+                }
+                materials.push(...this.parseMtl(await mtlResponse.text()));
+            } catch (error) {
+                console.warn(`ObjLoader: could not load material library '${library}'.`, error);
+            }
+        }
+
+
+        return this.fromText(text, materials);
+    }
+}

package/src/api/loaders/obj/ObjTypes.ts

@@ -0,0 +1,124 @@
+/*
+ * Plain-data types produced by the OBJ loader.
+ * This folder is self-contained: files here import only each other, so it can move to its own package.
+ */
+
+/** An RGB colour as read from an .mtl file, each channel usually in 0..1. */
+export type ObjColor = [r: number, g: number, b: number];
+
+/**
+ * A material definition read from an .mtl file (`newmtl` block).
+ * This is plain data, not a GPU material; map it onto a framework material yourself.
+ */
+export class ObjMaterialDefinition {
+
+    /**
+     * The constructor.
+     * @param name The material name from `newmtl`.
+     */
+    public constructor(public name: string) {
+    }
+
+    /** Ambient colour (`Ka`). */
+    public ambientColor?: ObjColor;
+
+    /** Diffuse colour (`Kd`). */
+    public diffuseColor?: ObjColor;
+
+    /** Specular colour (`Ks`). */
+    public specularColor?: ObjColor;
+
+    /** Emissive colour (`Ke`). */
+    public emissiveColor?: ObjColor;
+
+    /** Specular exponent (`Ns`). */
+    public specularExponent?: number;
+
+    /** Opacity, from `d`, or `1 - Tr` when only `Tr` is given. */
+    public opacity?: number;
+
+    /** Optical density / index of refraction (`Ni`). */
+    public opticalDensity?: number;
+
+    /** Illumination model (`illum`). */
+    public illuminationModel?: number;
+
+    /**
+     * Texture maps by statement name, e.g. `map_Kd`, `map_Ks`, `map_Bump`, `bump`, `disp`, `decal`, `refl`.
+     * The value is the file name (last token); map options such as `-bm 1` are kept in {@link mapOptions}.
+     */
+    public maps: Record<string, string> = {};
+
+    /** Options written before the file name of a map statement, e.g. `{ map_Bump: "-bm 0.5" }`. */
+    public mapOptions: Record<string, string> = {};
+}
+
+/** A run of triangles in the geometry's index buffer drawn with one material (`usemtl`). */
+export interface ObjMaterialRange {
+    /** The material name from `usemtl`, or undefined for faces before any `usemtl`. */
+    readonly materialName?: string;
+    /** First index in `geometry.indices`. */
+    readonly indexStart: number;
+    /** Number of indices (3 per triangle). */
+    readonly indexCount: number;
+}
+
+/** The OBJ data exactly as listed in the file, before expansion. */
+export interface ObjRawData {
+    /** `v` values, 3 per position. */
+    readonly positions: number[];
+    /** `vt` values, 2 per texture coordinate (a third `w` value is dropped). */
+    readonly textureCoords: number[];
+    /** `vn` values, 3 per normal. */
+    readonly normals: number[];
+    /**
+     * Triangulated face corners as zero-based `position, texcoord, normal` triplets.
+     * A missing texcoord or normal is -1.
+     */
+    readonly faceIndices: number[];
+}
+
+/**
+ * Renderable geometry as plain data: one vertex per unique position/texcoord/normal/material corner.
+ * Has no dependency on any engine; convert it to engine geometry yourself.
+ */
+export interface ObjGeometryDefinition {
+    /** Positions, 3 per vertex. */
+    readonly positions: number[];
+    /** Texture coordinates, 2 per vertex (0,0 when the corner has none). */
+    readonly textureCoords: number[];
+    /** Normals, 3 per vertex (0,0,0 when the corner has none). */
+    readonly normals: number[];
+    /** RGBA colours, 4 per vertex: the material's `Kd` with alpha from `d`, white without a material. */
+    readonly colors: number[];
+    /** Triangle indices, 3 per triangle. */
+    readonly indices: number[];
+    /** Number of vertices (`positions.length / 3`). */
+    readonly vertexCount: number;
+    /** Index ranges per `usemtl`, in file order. */
+    readonly materialRanges: ObjMaterialRange[];
+}
+
+/** The result of loading an OBJ file. */
+export interface ObjLoadResult {
+    /** The renderable geometry as plain data. */
+    readonly geometry: ObjGeometryDefinition;
+    /** Material definitions from the referenced .mtl files. Empty when there is no `mtllib` or it could not be loaded. */
+    readonly materials: ObjMaterialDefinition[];
+    /** Library file names from `mtllib`, in order. */
+    readonly materialLibraries: string[];
+    /** The raw OBJ lists. */
+    readonly raw: ObjRawData;
+}
+
+/** Options for {@link ObjLoader.loadAsync}. */
+export interface ObjLoadOptions {
+    /**
+     * Maps an `mtllib` name to the URL to fetch.
+     * By default, the name is resolved relative to the OBJ URL, which fails for `data:` or `blob:` URLs
+     * (for example a bundler-inlined asset); use this to point at the real file.
+     */
+    resolveMaterialUrl?: (libraryName: string) => string;
+    /** Skip fetching .mtl files. */
+    ignoreMaterials?: boolean;
+}

package/src/api/loaders/obj/index.ts

@@ -0,0 +1,5 @@
+/*
+ * OBJ/MTL loader. Self-contained: no imports outside this folder.
+ */
+export * from "./ObjTypes.ts";
+export * from "./ObjLoader.ts";