ris-framework 0.1.0 → 0.2.0-dev.12

package/src/api/camera/PerspectiveCamera.ts

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

package/src/api/content/ContentManager.ts

@@ -3,11 +3,24 @@ import {
     type IContentManager,
     type IShaderModuleLoader,
     type ITexture2D,
-    type IFramework, TextureDescriptor, TextureFormat, ContentConfig, TextureUsage
+    type IFramework,
+    TextureDescriptor,
+    TextureFormat,
+    ContentConfig,
+    TextureUsage,
+    type IMesh,
+    type IRenderableMesh,
+    type GeometryFormat,
+    Color,
+    type ICamera,
+    type IDisposable,
 } from "../index.ts";
+import {ObjGeometryMapper} from "../loaders/ObjGeometryMapper.ts";
+import {ObjLoader} from "../loaders/ObjLoader.ts";
 import {Ktx2Factory} from "ris-ktx2";
 import type {IKtx2Texture} from "ris-ktx2";
 
+const KTX2_EXTENSION = ".ktx2";
 
 /**
  * The content manager.
@@ -16,7 +29,7 @@ import type {IKtx2Texture} from "ris-ktx2";
 export class ContentManager implements IContentManager {
 
     private readonly _ktx2Factory = new Ktx2Factory();
-    private readonly _ktx2TextureCache: {[key: string]: IKtx2Texture} = {};
+    private readonly _ktx2TextureCache: { [key: string]: IKtx2Texture } = {};
 
     /**
      * The constructor.
@@ -29,53 +42,75 @@ export class ContentManager implements IContentManager {
     /** @inheritDoc */
     public async loadKtx2Async(path: string, contentConfig?: ContentConfig): Promise<IKtx2Texture> {
 
+        // it's fine to call it, handled internally if called multiple times.
+        await this._ktx2Factory.initializeAsync();
+
         let ktx2Texture = this._ktx2TextureCache[path];
-        if(ktx2Texture) {
+        if (ktx2Texture) {
             return ktx2Texture;
         }
 
         ktx2Texture = await this._ktx2Factory.loadAsync(path);
-        if(contentConfig?.keepDataCached == true){
+        if (contentConfig?.keepDataCached == true) {
             this._ktx2TextureCache[path] = ktx2Texture;
         }
         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)) {
+            this._ktx2TextureCache[key].delete();
+            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 */
     public async loadTexture2DAsync(path: string,
                                     textureDescriptor?: TextureDescriptor,
                                     contentConfig?: ContentConfig,
-                                    ): Promise<ITexture2D> {
+    ): Promise<ITexture2D> {
+
+        // TODO: check texture cache
+        if (path.endsWith(KTX2_EXTENSION)) {
 
-        if(path.endsWith(".ktx2")) {
-            const ktx2Texture = await this.loadKtx2Async(path, contentConfig);
+            const ktx2Texture = await this.loadKtx2Async(path);
             textureDescriptor = textureDescriptor ?? new TextureDescriptor();
-            return this._framework.textureFactory.createFromKtx2(ktx2Texture, textureDescriptor);
+            const tex = this._framework.textureFactory.createFromKtx2(ktx2Texture, textureDescriptor);
+            if (contentConfig?.keepDataCached !== true) {
+                ktx2Texture.delete();
+            }
+            return tex;
         }
 
-        let format =  this._framework.renderer.preferredTextureFormat;
+        let format = this._framework.renderer.preferredTextureFormat;
 
-        if(textureDescriptor && textureDescriptor.textureFormat != TextureFormat.UNDEFINED) {
+        if (textureDescriptor && textureDescriptor.textureFormat != TextureFormat.UNDEFINED) {
             format = textureDescriptor.textureFormat;
         }
 
-        // TODO: pass texture descriptor
         const imageLoader = this._framework.imageLoader;
         const data = await imageLoader.loadAsync(path, contentConfig?.keepDataCached);
+
+        // TODO: pass texture descriptor
         return this._framework.textureFactory.create(
             data.baseWidth, data.baseHeight,
             data.getData(0) as Uint8Array,
             data.channels,
-            undefined,
+            path,
             TextureUsage.TEXTURE_BINDING | TextureUsage.COPY_SRC,
             format,
             textureDescriptor?.generateMipmaps
-            );
+        );
     }
 
     /** @inheritDoc */
@@ -84,4 +119,31 @@ export class ContentManager implements IContentManager {
         return this._framework.textureFactory.create(width, height, view);
     }
 
-}
+    /** @inheritDoc */
+    public async loadMeshAsync(path: string, geometryFormat: GeometryFormat): Promise<IMesh> {
+        const model = await ObjLoader.parseAsync(path, {ignoreMaterials: true});
+        const geometry = this._framework.geometryBuilder.create(ObjGeometryMapper.toDescriptor(model.geometry));
+        return this._framework.meshFactory.createMesh(geometry, geometryFormat);
+    }
+
+    /** @inheritDoc */
+    public loadUnlitMeshAsync(path: string, camera?: ICamera): Promise<IRenderableMesh> {
+        return this._framework.objLoader.loadAsync(path, subMesh => {
+            const material = this._framework.materialFactory.createUnlitMaterial({camera});
+            const diffuse = subMesh.material?.diffuseColor ?? [1, 1, 1];
+            material.diffuseColor = new Color(diffuse[0], diffuse[1], diffuse[2], subMesh.material?.opacity ?? 1);
+            return material;
+        });
+    }
+
+    /** @inheritDoc */
+    public loadBlinnPhongMeshAsync(path: string, camera: ICamera): Promise<IRenderableMesh> {
+        if (!camera?.projectionViewBuffer || !camera?.positionBuffer) {
+            throw new Error(`loadBlinnPhongMeshAsync("${path}"): the camera has no projectionViewBuffer/positionBuffer. Pass an initialized camera (the camera factory initializes it).`);
+        }
+        return this._framework.objLoader.loadAsync(path, {
+            projectionViewBuffer: camera.projectionViewBuffer,
+            cameraPositionBuffer: camera.positionBuffer,
+        });
+    }
+}

package/src/api/content/IContentManager.ts

@@ -1,9 +1,13 @@
+import type { ICamera } from "../camera/ICamera.ts";
+import type { GeometryFormat } from "../geometry/GeometryFormat.ts";
+import type { IRenderableMesh } from "../meshes/IRenderableMesh.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 +30,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 +43,35 @@ export interface IContentManager {
      * @returns The Texture2D.
      */
     loadTexture2DAsync(path: string, desc?: TextureDescriptor, contentConfig?: ContentConfig): Promise<ITexture2D>;
+
+    /**
+     * Loads a plain mesh (geometry and buffers only, no material or transform) from an OBJ (Wavefront) file,
+     * like C# `ContentManager.LoadMesh`. Materials (.mtl) are not loaded.
+     * @param path The path or url to the .obj file.
+     * @param geometryFormat The vertex layout of the buffers, e.g. the format of the material it will be drawn with.
+     * @return The mesh.
+     */
+    loadMeshAsync(path: string, geometryFormat: GeometryFormat): Promise<IMesh>;
+
+    /**
+     * Loads an OBJ mesh with unlit materials, through `framework.objLoader`.
+     * The root mesh has no material; each `usemtl` range is a sub mesh with an unlit material
+     * (`Kd` as diffuse colour, `d` as alpha, white when missing). Add it with `scene.add(mesh)`.
+     * @param path The path or url to the .obj file.
+     * @param camera The optional camera; `scene.update()` assigns the scene camera anyway.
+     * @return The root mesh.
+     */
+    loadUnlitMeshAsync(path: string, camera?: ICamera): Promise<IRenderableMesh>;
+
+    /**
+     * Loads an OBJ mesh with Blinn-Phong materials: shorthand for
+     * `framework.objLoader.loadAsync(path, {projectionViewBuffer: camera.projectionViewBuffer, cameraPositionBuffer: camera.positionBuffer})`.
+     * See `ObjLoader.loadAsync` for the .mtl mapping. Add it with `scene.add(mesh)`; the scene assigns its camera and lights.
+     * @param path The path or url to the .obj file. A relative `mtllib` is resolved against it.
+     * @param camera An initialized camera (e.g. `scene.camera`).
+     * @return The root mesh.
+     * @throws Error when the camera has no buffers.
+     */
+    loadBlinnPhongMeshAsync(path: string, camera: ICamera): Promise<IRenderableMesh>;
+
 }

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