ris-framework 0.1.0 → 0.2.0-dev.12

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,94 @@
+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 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.
+ * - `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. 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. 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;
+
+    /**
+     * 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 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
+ */
+export class ObjGeometryMapper {
+
+    /**
+     * Creates a geometry descriptor from an OBJ geometry definition.
+     * @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.
+     */
+    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/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,2 +1,4 @@
 export * from "./IImageLoader.ts"
-export * from "./ImageLoader.ts"
+export * from "./ImageLoader.ts"
+export * from "./obj/index.ts"
+export * from "./ObjLoader.ts"