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

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;
+    }
+}

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++;
+}