ris-framework 0.1.0 → 0.2.0-dev.12

package/src/api/rendering/texture/TextureUtilities.ts

@@ -8,36 +8,199 @@ import {AlignUtilities} from "../../utilities/AlignUtilities.ts";
 export class TextureUtilities {
 
     private static readonly _compressedTextureFormats = [
-        TextureFormat.ASTC_4X4_RGBA,
+
+        // ASTC
+        TextureFormat.ASTC_4X4_RGBA_UNORM,
+        TextureFormat.ASTC_4X4_RGBA_SRGB,
+        TextureFormat.ASTC_5X4_RGBA_UNORM,
+        TextureFormat.ASTC_5X4_RGBA_SRGB,
+        TextureFormat.ASTC_5X5_RGBA_UNORM,
+        TextureFormat.ASTC_5X5_RGBA_SRGB,
+        TextureFormat.ASTC_6X5_RGBA_UNORM,
+        TextureFormat.ASTC_6X5_RGBA_SRGB,
+        TextureFormat.ASTC_6X6_RGBA_UNORM,
+        TextureFormat.ASTC_6X6_RGBA_SRGB,
+        TextureFormat.ASTC_8X5_RGBA_UNORM,
+        TextureFormat.ASTC_8X5_RGBA_SRGB,
+        TextureFormat.ASTC_8X6_RGBA_UNORM,
+        TextureFormat.ASTC_8X6_RGBA_SRGB,
+        TextureFormat.ASTC_8X8_RGBA_UNORM,
+        TextureFormat.ASTC_8X8_RGBA_SRGB,
+        TextureFormat.ASTC_10X5_RGBA_UNORM,
+        TextureFormat.ASTC_10X5_RGBA_SRGB,
+        TextureFormat.ASTC_10X6_RGBA_UNORM,
+        TextureFormat.ASTC_10X6_RGBA_SRGB,
+        TextureFormat.ASTC_10X8_RGBA_UNORM,
+        TextureFormat.ASTC_10X8_RGBA_SRGB,
+        TextureFormat.ASTC_10X10_RGBA_UNORM,
+        TextureFormat.ASTC_10X10_RGBA_SRGB,
+        TextureFormat.ASTC_12X10_RGBA_UNORM,
+        TextureFormat.ASTC_12X10_RGBA_SRGB,
+        TextureFormat.ASTC_12X12_RGBA_UNORM,
+        TextureFormat.ASTC_12X12_RGBA_SRGB,
+
+        // PVRTC
+        TextureFormat.PVRTC_4BPPV1_RGBA,
+        TextureFormat.PVRTC_4BPPV1_RGB,
+        TextureFormat.PVRTC_2BPPV1_RGBA,
+        TextureFormat.PVRTC_2BPPV1_RGB,
+
         TextureFormat.BC3_RGBA_UNORM,
         TextureFormat.BC7_RGBA_UNORM,
-        TextureFormat.ETC2_RGBA8_UNORM
+        TextureFormat.ETC2_RGBA8_UNORM,
+
+        // sRGB and RGB variants
+        TextureFormat.BC7_RGBA_SRGB,
+        TextureFormat.BC3_RGBA_SRGB,
+        TextureFormat.BC1_RGB_UNORM,
+        TextureFormat.BC1_RGB_SRGB,
+        TextureFormat.ETC2_RGBA8_SRGB,
+        TextureFormat.ETC2_RGB8_UNORM,
+        TextureFormat.ETC2_RGB8_SRGB,
     ];
-    private static readonly _vkFormatTextureFormat: { [key: number]: number } = {
+
+    /** Linear compressed format → its sRGB variant. */
+    private static readonly _srgbVariant: { [key: string]: TextureFormat } = {
+        [TextureFormat.RGBA_8_UNORM]: TextureFormat.RGBA_8_UNORM_SRGB,
+        [TextureFormat.BC7_RGBA_UNORM]: TextureFormat.BC7_RGBA_SRGB,
+        [TextureFormat.BC3_RGBA_UNORM]: TextureFormat.BC3_RGBA_SRGB,
+        [TextureFormat.BC1_RGB_UNORM]: TextureFormat.BC1_RGB_SRGB,
+        [TextureFormat.ETC2_RGBA8_UNORM]: TextureFormat.ETC2_RGBA8_SRGB,
+        [TextureFormat.ETC2_RGB8_UNORM]: TextureFormat.ETC2_RGB8_SRGB,
+        [TextureFormat.ASTC_4X4_RGBA_UNORM]: TextureFormat.ASTC_4X4_RGBA_SRGB,
+        [TextureFormat.ASTC_5X4_RGBA_UNORM]: TextureFormat.ASTC_5X4_RGBA_SRGB,
+        [TextureFormat.ASTC_5X5_RGBA_UNORM]: TextureFormat.ASTC_5X5_RGBA_SRGB,
+        [TextureFormat.ASTC_6X5_RGBA_UNORM]: TextureFormat.ASTC_6X5_RGBA_SRGB,
+        [TextureFormat.ASTC_6X6_RGBA_UNORM]: TextureFormat.ASTC_6X6_RGBA_SRGB,
+        [TextureFormat.ASTC_8X5_RGBA_UNORM]: TextureFormat.ASTC_8X5_RGBA_SRGB,
+        [TextureFormat.ASTC_8X6_RGBA_UNORM]: TextureFormat.ASTC_8X6_RGBA_SRGB,
+        [TextureFormat.ASTC_8X8_RGBA_UNORM]: TextureFormat.ASTC_8X8_RGBA_SRGB,
+        [TextureFormat.ASTC_10X5_RGBA_UNORM]: TextureFormat.ASTC_10X5_RGBA_SRGB,
+        [TextureFormat.ASTC_10X6_RGBA_UNORM]: TextureFormat.ASTC_10X6_RGBA_SRGB,
+        [TextureFormat.ASTC_10X8_RGBA_UNORM]: TextureFormat.ASTC_10X8_RGBA_SRGB,
+        [TextureFormat.ASTC_10X10_RGBA_UNORM]: TextureFormat.ASTC_10X10_RGBA_SRGB,
+        [TextureFormat.ASTC_12X10_RGBA_UNORM]: TextureFormat.ASTC_12X10_RGBA_SRGB,
+        [TextureFormat.ASTC_12X12_RGBA_UNORM]: TextureFormat.ASTC_12X12_RGBA_SRGB,
+    };
+    private static readonly _vkFormatTextureFormat: { [key: number]: TextureFormat } = {
         [VkFormat.R8G8B8A8_UNORM]: TextureFormat.RGBA_8_UNORM,
         [VkFormat.R8G8B8A8_SRGB]: TextureFormat.RGBA_8_UNORM_SRGB,
         [VkFormat.BC7_UNORM_BLOCK]: TextureFormat.BC7_RGBA_UNORM,
-        [VkFormat.ASTC_4X4_UNORM_BLOCK]: TextureFormat.ASTC_4X4_RGBA,
+
+        // ASTC
+        [VkFormat.ASTC_4X4_UNORM_BLOCK]: TextureFormat.ASTC_4X4_RGBA_UNORM,
+        [VkFormat.ASTC_4X4_SRGB_BLOCK]: TextureFormat.ASTC_4X4_RGBA_SRGB,
+        [VkFormat.ASTC_5X4_UNORM_BLOCK]: TextureFormat.ASTC_5X4_RGBA_UNORM,
+        [VkFormat.ASTC_5X4_SRGB_BLOCK]: TextureFormat.ASTC_5X4_RGBA_SRGB,
+        [VkFormat.ASTC_5X5_UNORM_BLOCK]: TextureFormat.ASTC_5X5_RGBA_UNORM,
+        [VkFormat.ASTC_5X5_SRGB_BLOCK]: TextureFormat.ASTC_5X5_RGBA_SRGB,
+        [VkFormat.ASTC_6X5_UNORM_BLOCK]: TextureFormat.ASTC_6X5_RGBA_UNORM,
+        [VkFormat.ASTC_6X5_SRGB_BLOCK]: TextureFormat.ASTC_6X5_RGBA_SRGB,
+        [VkFormat.ASTC_6X6_UNORM_BLOCK]: TextureFormat.ASTC_6X6_RGBA_UNORM,
+        [VkFormat.ASTC_6X6_SRGB_BLOCK]: TextureFormat.ASTC_6X6_RGBA_SRGB,
+        [VkFormat.ASTC_8X5_UNORM_BLOCK]: TextureFormat.ASTC_8X5_RGBA_UNORM,
+        [VkFormat.ASTC_8X5_SRGB_BLOCK]: TextureFormat.ASTC_8X5_RGBA_SRGB,
+        [VkFormat.ASTC_8X6_UNORM_BLOCK]: TextureFormat.ASTC_8X6_RGBA_UNORM,
+        [VkFormat.ASTC_8X6_SRGB_BLOCK]: TextureFormat.ASTC_8X6_RGBA_SRGB,
+        [VkFormat.ASTC_8X8_UNORM_BLOCK]: TextureFormat.ASTC_8X8_RGBA_UNORM,
+        [VkFormat.ASTC_8X8_SRGB_BLOCK]: TextureFormat.ASTC_8X8_RGBA_SRGB,
+        [VkFormat.ASTC_10X5_UNORM_BLOCK]: TextureFormat.ASTC_10X5_RGBA_UNORM,
+        [VkFormat.ASTC_10X5_SRGB_BLOCK]: TextureFormat.ASTC_10X5_RGBA_SRGB,
+        [VkFormat.ASTC_10X6_UNORM_BLOCK]: TextureFormat.ASTC_10X6_RGBA_UNORM,
+        [VkFormat.ASTC_10X6_SRGB_BLOCK]: TextureFormat.ASTC_10X6_RGBA_SRGB,
+        [VkFormat.ASTC_10X8_UNORM_BLOCK]: TextureFormat.ASTC_10X8_RGBA_UNORM,
+        [VkFormat.ASTC_10X8_SRGB_BLOCK]: TextureFormat.ASTC_10X8_RGBA_SRGB,
+        [VkFormat.ASTC_10X10_UNORM_BLOCK]: TextureFormat.ASTC_10X10_RGBA_UNORM,
+        [VkFormat.ASTC_10X10_SRGB_BLOCK]: TextureFormat.ASTC_10X10_RGBA_SRGB,
+        [VkFormat.ASTC_12X10_UNORM_BLOCK]: TextureFormat.ASTC_12X10_RGBA_UNORM,
+        [VkFormat.ASTC_12X10_SRGB_BLOCK]: TextureFormat.ASTC_12X10_RGBA_SRGB,
+        [VkFormat.ASTC_12X12_UNORM_BLOCK]: TextureFormat.ASTC_12X12_RGBA_UNORM,
+        [VkFormat.ASTC_12X12_SRGB_BLOCK]: TextureFormat.ASTC_12X12_RGBA_SRGB,
+
         [VkFormat.BC3_UNORM_BLOCK]: TextureFormat.BC3_RGBA_UNORM,
         [VkFormat.ETC2_R8G8B8A8_UNORM_BLOCK]: TextureFormat.ETC2_RGBA8_UNORM,
+        [VkFormat.PVRTC1_4BPP_UNORM_BLOCK_IMG]: TextureFormat.PVRTC_4BPPV1_RGBA,
+
+        // sRGB and RGB variants
+        [VkFormat.BC7_SRGB_BLOCK]: TextureFormat.BC7_RGBA_SRGB,
+        [VkFormat.BC3_SRGB_BLOCK]: TextureFormat.BC3_RGBA_SRGB,
+        [VkFormat.BC1_RGB_UNORM_BLOCK]: TextureFormat.BC1_RGB_UNORM,
+        [VkFormat.BC1_RGB_SRGB_BLOCK]: TextureFormat.BC1_RGB_SRGB,
+        [VkFormat.ETC2_R8G8B8A8_SRGB_BLOCK]: TextureFormat.ETC2_RGBA8_SRGB,
+        [VkFormat.ETC2_R8G8B8_UNORM_BLOCK]: TextureFormat.ETC2_RGB8_UNORM,
+        [VkFormat.ETC2_R8G8B8_SRGB_BLOCK]: TextureFormat.ETC2_RGB8_SRGB,
+
     }
 
-    private static readonly _textureFormatVkFormat: { [key: number]: number } = {
+    private static readonly _textureFormatVkFormat: { [key: string]: number } = {
         [TextureFormat.RGBA_8_UNORM]: VkFormat.R8G8B8A8_UNORM,
         [TextureFormat.RGBA_8_UNORM_SRGB]: VkFormat.R8G8B8A8_SRGB,
         [TextureFormat.DEPTH_24_STENCIL_8]: VkFormat.D24_UNORM_S8_UINT,
         [TextureFormat.BC3_RGBA_UNORM]: VkFormat.BC3_UNORM_BLOCK,
         [TextureFormat.BC7_RGBA_UNORM]: VkFormat.BC7_UNORM_BLOCK,
-        [TextureFormat.ASTC_4X4_RGBA]: VkFormat.ASTC_4X4_UNORM_BLOCK,
+
+        // ASTC
+        [TextureFormat.ASTC_4X4_RGBA_UNORM]: VkFormat.ASTC_4X4_UNORM_BLOCK,
+        [TextureFormat.ASTC_4X4_RGBA_SRGB]: VkFormat.ASTC_4X4_SRGB_BLOCK,
+        [TextureFormat.ASTC_5X4_RGBA_UNORM]: VkFormat.ASTC_5X4_UNORM_BLOCK,
+        [TextureFormat.ASTC_5X4_RGBA_SRGB]: VkFormat.ASTC_5X4_SRGB_BLOCK,
+        [TextureFormat.ASTC_5X5_RGBA_UNORM]: VkFormat.ASTC_5X5_UNORM_BLOCK,
+        [TextureFormat.ASTC_5X5_RGBA_SRGB]: VkFormat.ASTC_5X5_SRGB_BLOCK,
+        [TextureFormat.ASTC_6X5_RGBA_UNORM]: VkFormat.ASTC_6X5_UNORM_BLOCK,
+        [TextureFormat.ASTC_6X5_RGBA_SRGB]: VkFormat.ASTC_6X5_SRGB_BLOCK,
+        [TextureFormat.ASTC_6X6_RGBA_UNORM]: VkFormat.ASTC_6X6_UNORM_BLOCK,
+        [TextureFormat.ASTC_6X6_RGBA_SRGB]: VkFormat.ASTC_6X6_SRGB_BLOCK,
+        [TextureFormat.ASTC_8X5_RGBA_UNORM]: VkFormat.ASTC_8X5_UNORM_BLOCK,
+        [TextureFormat.ASTC_8X5_RGBA_SRGB]: VkFormat.ASTC_8X5_SRGB_BLOCK,
+        [TextureFormat.ASTC_8X6_RGBA_UNORM]: VkFormat.ASTC_8X6_UNORM_BLOCK,
+        [TextureFormat.ASTC_8X6_RGBA_SRGB]: VkFormat.ASTC_8X6_SRGB_BLOCK,
+        [TextureFormat.ASTC_8X8_RGBA_UNORM]: VkFormat.ASTC_8X8_UNORM_BLOCK,
+        [TextureFormat.ASTC_8X8_RGBA_SRGB]: VkFormat.ASTC_8X8_SRGB_BLOCK,
+        [TextureFormat.ASTC_10X5_RGBA_UNORM]: VkFormat.ASTC_10X5_UNORM_BLOCK,
+        [TextureFormat.ASTC_10X5_RGBA_SRGB]: VkFormat.ASTC_10X5_SRGB_BLOCK,
+        [TextureFormat.ASTC_10X6_RGBA_UNORM]: VkFormat.ASTC_10X6_UNORM_BLOCK,
+        [TextureFormat.ASTC_10X6_RGBA_SRGB]: VkFormat.ASTC_10X6_SRGB_BLOCK,
+        [TextureFormat.ASTC_10X8_RGBA_UNORM]: VkFormat.ASTC_10X8_UNORM_BLOCK,
+        [TextureFormat.ASTC_10X8_RGBA_SRGB]: VkFormat.ASTC_10X8_SRGB_BLOCK,
+        [TextureFormat.ASTC_10X10_RGBA_UNORM]: VkFormat.ASTC_10X10_UNORM_BLOCK,
+        [TextureFormat.ASTC_10X10_RGBA_SRGB]: VkFormat.ASTC_10X10_SRGB_BLOCK,
+        [TextureFormat.ASTC_12X10_RGBA_UNORM]: VkFormat.ASTC_12X10_UNORM_BLOCK,
+        [TextureFormat.ASTC_12X10_RGBA_SRGB]: VkFormat.ASTC_12X10_SRGB_BLOCK,
+        [TextureFormat.ASTC_12X12_RGBA_UNORM]: VkFormat.ASTC_12X12_UNORM_BLOCK,
+        [TextureFormat.ASTC_12X12_RGBA_SRGB]: VkFormat.ASTC_12X12_SRGB_BLOCK,
+
+        // PVRTC
+        [TextureFormat.PVRTC_4BPPV1_RGBA]: VkFormat.PVRTC1_4BPP_UNORM_BLOCK_IMG,
+        [TextureFormat.PVRTC_4BPPV1_RGB]: VkFormat.PVRTC1_4BPP_UNORM_BLOCK_IMG,
+        [TextureFormat.PVRTC_2BPPV1_RGBA]: VkFormat.PVRTC1_2BPP_UNORM_BLOCK_IMG,
+        [TextureFormat.PVRTC_2BPPV1_RGB]: VkFormat.PVRTC1_2BPP_UNORM_BLOCK_IMG,
+
+
         [TextureFormat.ETC2_RGBA8_UNORM] : VkFormat.ETC2_R8G8B8A8_UNORM_BLOCK,
+
+        // sRGB and RGB variants
+        [TextureFormat.BC7_RGBA_SRGB]: VkFormat.BC7_SRGB_BLOCK,
+        [TextureFormat.BC3_RGBA_SRGB]: VkFormat.BC3_SRGB_BLOCK,
+        [TextureFormat.BC1_RGB_UNORM]: VkFormat.BC1_RGB_UNORM_BLOCK,
+        [TextureFormat.BC1_RGB_SRGB]: VkFormat.BC1_RGB_SRGB_BLOCK,
+        [TextureFormat.ETC2_RGBA8_SRGB]: VkFormat.ETC2_R8G8B8A8_SRGB_BLOCK,
+        [TextureFormat.ETC2_RGB8_UNORM]: VkFormat.ETC2_R8G8B8_UNORM_BLOCK,
+        [TextureFormat.ETC2_RGB8_SRGB]: VkFormat.ETC2_R8G8B8_SRGB_BLOCK,
     };
 
-    private static readonly _mapTextureFormatKtxTranscodeFormat: { [key: number]: number } = {
+    private static readonly _mapTextureFormatKtxTranscodeFormat: { [key: string]: number } = {
         [TextureFormat.RGBA_8_UNORM]: KtxTranscodeFormat.RGBA32,
-        [TextureFormat.ASTC_4X4_RGBA]: KtxTranscodeFormat.ASTC_4X4_RGBA,
+        [TextureFormat.ASTC_4X4_RGBA_UNORM]: KtxTranscodeFormat.ASTC_4X4_RGBA,
         [TextureFormat.BC3_RGBA_UNORM]: KtxTranscodeFormat.BC3_RGBA,
         [TextureFormat.BC7_RGBA_UNORM]: KtxTranscodeFormat.BC7_RGBA,
         [TextureFormat.ETC2_RGBA8_UNORM]: KtxTranscodeFormat.ETC2_RGBA,
+        [TextureFormat.PVRTC_4BPPV1_RGBA] : KtxTranscodeFormat.PVRTC1_4_RGBA,
+        // Basis transcodes to the same blocks for sRGB; only the GPU format differs.
+        [TextureFormat.RGBA_8_UNORM_SRGB]: KtxTranscodeFormat.RGBA32,
+        [TextureFormat.ASTC_4X4_RGBA_SRGB]: KtxTranscodeFormat.ASTC_4X4_RGBA,
+        [TextureFormat.BC3_RGBA_SRGB]: KtxTranscodeFormat.BC3_RGBA,
+        [TextureFormat.BC7_RGBA_SRGB]: KtxTranscodeFormat.BC7_RGBA,
+        [TextureFormat.ETC2_RGBA8_SRGB]: KtxTranscodeFormat.ETC2_RGBA,
     };
 
     private static readonly _mapKtxTranscodeFormatVkFormat: { [key: number]: number } = {
@@ -49,18 +212,70 @@ export class TextureUtilities {
         [KtxTranscodeFormat.KTX_TTF_BC5_RG]: VkFormat.BC5_UNORM_BLOCK,
         [KtxTranscodeFormat.BC7_RGBA]: VkFormat.BC7_UNORM_BLOCK,
         [KtxTranscodeFormat.KTX_TTF_PVRTC1_4_RGB]: VkFormat.PVRTC1_4BPP_UNORM_BLOCK_IMG,
-        [KtxTranscodeFormat.KTX_TTF_PVRTC1_4_RGBA]: VkFormat.PVRTC1_4BPP_UNORM_BLOCK_IMG,
+        [KtxTranscodeFormat.PVRTC1_4_RGBA]: VkFormat.PVRTC1_4BPP_UNORM_BLOCK_IMG,
         [KtxTranscodeFormat.ASTC_4X4_RGBA]: VkFormat.ASTC_4X4_UNORM_BLOCK,
         [KtxTranscodeFormat.RGBA32]: VkFormat.R8G8B8A8_UNORM,
         [KtxTranscodeFormat.KTX_TTF_RGB565]: VkFormat.R5G6B5_UNORM_PACK16,
         [KtxTranscodeFormat.KTX_TTF_BGR565]: VkFormat.B5G6R5_UNORM_PACK16,
         [KtxTranscodeFormat.KTX_TTF_RGBA4444]: VkFormat.R4G4B4A4_UNORM_PACK16,
         [KtxTranscodeFormat.KTX_TTF_PVRTC2_4_RGB]: VkFormat.PVRTC2_4BPP_UNORM_BLOCK_IMG,
-        [KtxTranscodeFormat.KTX_TTF_PVRTC2_4_RGBA]: VkFormat.PVRTC2_4BPP_UNORM_BLOCK_IMG,
+        [KtxTranscodeFormat.PVRTC2_4_RGBA]: VkFormat.PVRTC2_4BPP_UNORM_BLOCK_IMG,
         [KtxTranscodeFormat.KTX_TTF_ETC2_EAC_R11]: VkFormat.EAC_R11_UNORM_BLOCK,
         [KtxTranscodeFormat.KTX_TTF_ETC2_EAC_RG11]: VkFormat.EAC_R11G11_UNORM_BLOCK,
     };
 
+    /**
+     * Whether the format stores sRGB-encoded colour (sampled as linear by the GPU).
+     * @param format The texture format.
+     */
+    public static isSrgbFormat(format: TextureFormat): boolean {
+        return format.endsWith("_SRGB");
+    }
+
+    /**
+     * Gets the sRGB variant of a linear format, or the format itself if it has none or is already sRGB.
+     * @param format The texture format.
+     */
+    public static toSrgbFormat(format: TextureFormat): TextureFormat {
+        return this._srgbVariant[format] ?? format;
+    }
+
+    /**
+     * Gets the linear variant of an sRGB format, or the format itself.
+     * @param format The texture format.
+     */
+    public static toLinearFormat(format: TextureFormat): TextureFormat {
+        for (const linear in this._srgbVariant) {
+            if (this._srgbVariant[linear] === format) return linear as TextureFormat;
+        }
+        return format;
+    }
+
+    /**
+     * Gets the block size (width, height) of a format: 1x1 for uncompressed, 4x4 for BC/ETC2, and the ASTC block.
+     * Returns null for formats it does not know.
+     * @param format The texture format.
+     */
+    public static getBlockSize(format: TextureFormat): [number, number] | null {
+        if (!this.isCompressedTextureFormat(format)) {
+            return [1, 1];
+        }
+        const astc = /^ASTC_(\d+)X(\d+)_/.exec(format);
+        if (astc) {
+            return [Number(astc[1]), Number(astc[2])];
+        }
+        if (format.startsWith("BC") || format.startsWith("ETC2")) {
+            return [4, 4];
+        }
+        if (format.startsWith("PVRTC_2BPP")) {
+            return [8, 4];
+        }
+        if (format.startsWith("PVRTC_4BPP")) {
+            return [4, 4];
+        }
+        return null;
+    }
+
     /**
      * Checks if the given texture format is a compressed texture format.
      * @param format - The texture format to check.

package/src/api/scene/Scene.ts

@@ -0,0 +1,297 @@
+import {AmbientLight} from "../lights/AmbientLight.ts";
+import {DirectionalLight} from "../lights/DirectionalLight.ts";
+import {PointLight} from "../lights/PointLight.ts";
+import type {IDisposable} from "../core/IDisposable.ts";
+import type {IFramework} from "../IFramework.ts";
+import type {IRenderableMesh} from "../meshes/IRenderableMesh.ts";
+import {SceneMesh} from "./SceneMesh.ts";
+import {isCameraMaterial} from "../material/ICameraMaterial.ts";
+import {isLightsMaterial} from "../material/ILightsMaterial.ts";
+import type {GameTime} from "../time/GameTime.ts";
+import type {ICamera} from "../camera/ICamera.ts";
+
+/** Anything a scene can hold: a mesh, a light (ambient, directional, point) or a camera. */
+export type SceneItem = IRenderableMesh | SceneMesh | AmbientLight | DirectionalLight | PointLight | ICamera;
+
+/**
+ * The scene. Lights and cameras given a scene in their constructor add themselves through {@link add};
+ * meshes are added with `scene.add(mesh)` (wrapped in a {@link SceneMesh}, which owns the mesh's materials).
+ * Like C#, the scene keeps the light lists and hands its active ambient light and the lists themselves (not copies)
+ * to every lights material in {@link update}; each material owns and uploads its own lights buffer. Call {@link update} once per frame and {@link render} in the render listener.
+ */
+export class Scene implements IDisposable {
+
+    private readonly _sceneMeshes: SceneMesh[] = [];
+    private readonly _directionalLights: DirectionalLight[] = [];
+    private readonly _pointLights: PointLight[] = [];
+
+    /** The directional light slots (matches the Blinn-Phong material). */
+    public static readonly MAX_DIRECTIONAL_LIGHTS = 3;
+
+    /** The point light slots (matches the Blinn-Phong material). */
+    public static readonly MAX_POINT_LIGHTS = 5;
+    private _activeAmbientLight: AmbientLight;
+    private _disposed = false;
+    private _activeCamera?: ICamera;
+
+    /**
+     * The camera the scene renders with; undefined until one is set or added.
+     * Setting it assigns it to the materials of every mesh (and submesh) whose camera differs;
+     * {@link update} also assigns it to meshes and submeshes added later.
+     */
+    public get camera(): ICamera | undefined {
+        return this._activeCamera;
+    }
+
+    public set camera(value: ICamera | undefined) {
+        this._activeCamera = value;
+        if (!value) {
+            return;
+        }
+        for (const sceneMesh of this._sceneMeshes) {
+            Scene._assignCamera(sceneMesh, value);
+        }
+    }
+
+    /** The ambient lights registered with this scene. */
+    public readonly ambientLights: AmbientLight[] = [];
+
+    /**
+     * The constructor.
+     * @param framework The framework.
+     */
+    public constructor(framework: IFramework) {
+
+        // Assigned through add() by the ambient light constructor; set here for the type checker.
+        this._activeAmbientLight = framework.lightsFactory.createAmbientLight(undefined, this);
+    }
+
+    /** The scene meshes, in the order they were added. */
+    public get sceneMeshes(): readonly SceneMesh[] {
+        return this._sceneMeshes;
+    }
+
+    /** The root meshes in this scene, in the order they were added. */
+    public get meshes(): readonly IRenderableMesh[] {
+        return this._sceneMeshes.map(s => s.mesh);
+    }
+
+    /** The directional lights in this scene. */
+    public get directionalLights(): readonly DirectionalLight[] {
+        return this._directionalLights;
+    }
+
+    /** The point lights in this scene. */
+    public get pointLights(): readonly PointLight[] {
+        return this._pointLights;
+    }
+
+    /**
+     * Gets the active ambient light.
+     */
+    public get activeAmbientLight(): AmbientLight {
+        return this._activeAmbientLight;
+    }
+
+    /** Sets the active ambient light; it is added to {@link ambientLights} if needed. */
+    public set activeAmbientLight(value: AmbientLight) {
+        this._addAmbientLight(value);
+        this._activeAmbientLight = value;
+    }
+
+    /**
+     * Adds a mesh, a light or a camera. Adding an item that is already in the scene does nothing.
+     * - Renderable mesh or {@link SceneMesh}: drawn by {@link render}; its materials get the scene camera and lights.
+     *   A mesh is wrapped in a `SceneMesh`, so {@link dispose} also disposes its materials.
+     * - Ambient light: added to {@link ambientLights} (use {@link activeAmbientLight} to make it the lit one).
+     * - Directional / point light: added to {@link directionalLights} / {@link pointLights}.
+     * - Camera: becomes the scene {@link camera}.
+     * Constructors given a scene (lights, the perspective camera) call this themselves.
+     * @param item The item to add.
+     * @throws Error when all slots for a light kind are in use (3 directional, 5 point), or for an unsupported item.
+     */
+    public add(item: SceneItem): void {
+        if (item instanceof AmbientLight) {
+            this._addAmbientLight(item);
+        } else if (item instanceof DirectionalLight || item instanceof PointLight) {
+            this._addLight(item);
+        } else if (Scene._isCamera(item)) {
+            this.camera = item;
+        } else if (item instanceof SceneMesh || Scene._isMesh(item)) {
+            const mesh = item instanceof SceneMesh ? item.mesh : item;
+            if (!this._sceneMeshes.some(s => s.mesh === mesh)) {
+                const sceneMesh = item instanceof SceneMesh ? item : new SceneMesh(item);
+                this._sceneMeshes.push(sceneMesh);
+                this._bind(sceneMesh);
+            }
+        } else {
+            throw new Error("Scene.add: expected a mesh, an AmbientLight, DirectionalLight, PointLight or a camera.");
+        }
+    }
+
+    /**
+     * Removes a mesh (or scene mesh), a light or a camera. The mesh and its materials are not disposed.
+     * Removing the active camera clears {@link camera}.
+     * @param item The item to remove.
+     * @returns True when the item was in the scene (for a camera: was the active camera).
+     * @throws Error when removing the active ambient light (set another {@link activeAmbientLight} first), or for an unsupported item.
+     */
+    public remove(item: SceneItem): boolean {
+        if (item instanceof AmbientLight) {
+            if (item === this._activeAmbientLight) {
+                throw new Error("Scene.remove: cannot remove the active ambient light; set scene.activeAmbientLight to another light first.");
+            }
+            return Scene._removeFrom(this.ambientLights, item);
+        }
+        if (item instanceof DirectionalLight || item instanceof PointLight) {
+            return item instanceof DirectionalLight
+                ? Scene._removeFrom(this._directionalLights, item)
+                : Scene._removeFrom(this._pointLights, item);
+        }
+        if (Scene._isCamera(item)) {
+            if (item !== this._activeCamera) {
+                return false;
+            }
+            this._activeCamera = undefined;
+            return true;
+        }
+        if (item instanceof SceneMesh || Scene._isMesh(item)) {
+            const mesh = item instanceof SceneMesh ? item.mesh : item;
+            const index = this._sceneMeshes.findIndex(s => s.mesh === mesh);
+            if (index < 0) {
+                return false;
+            }
+            this._sceneMeshes.splice(index, 1);
+            return true;
+        }
+        throw new Error("Scene.remove: expected a mesh, an AmbientLight, DirectionalLight, PointLight or a camera.");
+    }
+
+    /**
+     * Adds a directional or point light.
+     * @deprecated Use {@link add}.
+     * @throws Error when all slots for that kind are in use (3 directional, 5 point).
+     */
+    public addLight(light: DirectionalLight | PointLight): void {
+        this.add(light);
+    }
+
+    /**
+     * Removes a directional or point light.
+     * @deprecated Use {@link remove}.
+     * @returns True when the light was in the scene.
+     */
+    public removeLight(light: DirectionalLight | PointLight): boolean {
+        return this.remove(light);
+    }
+
+    private _addLight(light: DirectionalLight | PointLight): void {
+        const [list, max, kind] = light instanceof DirectionalLight
+            ? [this._directionalLights as (DirectionalLight | PointLight)[], Scene.MAX_DIRECTIONAL_LIGHTS, "directional"]
+            : [this._pointLights as (DirectionalLight | PointLight)[], Scene.MAX_POINT_LIGHTS, "point"];
+        if (list.includes(light)) {
+            return;
+        }
+        if (list.length >= max) {
+            throw new Error(`Scene: cannot add ${kind} light ${light.id}; all ${max} ${kind} light slots are in use.`);
+        }
+        list.push(light);
+    }
+
+    private _addAmbientLight(ambientLight: AmbientLight): void {
+        if (!this.ambientLights.includes(ambientLight)) {
+            this.ambientLights.push(ambientLight);
+        }
+    }
+
+    private static _removeFrom<T>(list: T[], item: T): boolean {
+        const index = list.indexOf(item);
+        if (index < 0) {
+            return false;
+        }
+        list.splice(index, 1);
+        return true;
+    }
+
+    /** Cameras have the camera buffers and updateBuffers(); meshes and lights do not. */
+    private static _isCamera(item: unknown): item is ICamera {
+        const camera = item as Partial<ICamera> | null;
+        return typeof camera === "object" && camera !== null
+            && "projectionViewBuffer" in camera && "viewMatrix" in camera && typeof camera.updateBuffers === "function";
+    }
+
+    /** Renderable meshes have render() and sub meshes. */
+    private static _isMesh(item: unknown): item is IRenderableMesh {
+        const mesh = item as Partial<IRenderableMesh> | null;
+        return typeof mesh === "object" && mesh !== null && typeof mesh.render === "function" && "subMeshes" in mesh;
+    }
+
+    /**
+     * Updates the scene: assigns {@link camera}, the active ambient light and the light lists to the mesh materials.
+     * Each lights material uploads its lights buffer when drawn, only if the lights changed.
+     * @param _time The game time.
+     * @public
+     */
+    update(_time: GameTime): void {
+        for (const sceneMesh of this._sceneMeshes) {
+            this._bind(sceneMesh);
+        }
+    }
+
+    /** Assigns the camera (when set) and the lights to the scene mesh's materials. */
+    private _bind(sceneMesh: SceneMesh): void {
+        if (this._activeCamera) {
+            Scene._assignCamera(sceneMesh, this._activeCamera);
+        }
+        for (const material of sceneMesh.materials) {
+            if (isLightsMaterial(material)) {
+                if (material.ambientLight !== this._activeAmbientLight) {
+                    material.ambientLight = this._activeAmbientLight;
+                }
+                if (material.directionalLights !== this._directionalLights) {
+                    material.directionalLights = this._directionalLights;
+                }
+                if (material.pointLights !== this._pointLights) {
+                    material.pointLights = this._pointLights;
+                }
+            }
+        }
+    }
+
+    private static _assignCamera(sceneMesh: SceneMesh, camera: ICamera): void {
+        // A camera that is not initialized yet (e.g. added from its constructor) has no buffers;
+        // it is assigned by the next update() once initialize() created them.
+        if (!camera.projectionViewBuffer || !camera.positionBuffer) {
+            return;
+        }
+        for (const material of sceneMesh.materials) {
+            // The setter rebinds buffers, so skip when unchanged.
+            if (isCameraMaterial(material) && material.camera !== camera) {
+                material.camera = camera;
+            }
+        }
+    }
+
+    /**
+     * Renders the meshes.
+     */
+    render(): void {
+
+        for (const sceneMesh of this._sceneMeshes) {
+            sceneMesh.render();
+        }
+
+    }
+
+    /** Disposes the scene meshes still in the scene: their meshes and materials. Calling it twice does nothing. */
+    public dispose(): void {
+        if (this._disposed) {
+            return;
+        }
+        this._disposed = true;
+        for (const sceneMesh of this._sceneMeshes) {
+            sceneMesh.dispose();
+        }
+        this._sceneMeshes.length = 0;
+    }
+}

package/src/api/scene/SceneMesh.ts

@@ -0,0 +1,61 @@
+import type {IDisposable} from "../core/IDisposable.ts";
+import type {IRenderableMesh} from "../meshes/IRenderableMesh.ts";
+import type {IMaterial} from "../material/IMaterial.ts";
+
+/**
+ * A renderable mesh held by a scene (C# `SceneMesh`): `new SceneMesh(renderableMesh)`.
+ * It covers the mesh and all its sub meshes, and owns their materials:
+ * disposing it disposes the mesh (buffers once) and each distinct material once.
+ * @public
+ */
+export class SceneMesh implements IDisposable {
+
+    private _disposed = false;
+
+    /**
+     * The constructor.
+     * @param mesh The root renderable mesh.
+     */
+    public constructor(public readonly mesh: IRenderableMesh) {
+    }
+
+    /** The mesh and all its sub meshes, depth first. */
+    public get meshes(): IRenderableMesh[] {
+        const result: IRenderableMesh[] = [];
+        const visit = (m: IRenderableMesh) => {
+            result.push(m);
+            m.subMeshes.forEach(visit);
+        };
+        visit(this.mesh);
+        return result;
+    }
+
+    /** The distinct materials of the mesh and its sub meshes. */
+    public get materials(): IMaterial[] {
+        const result: IMaterial[] = [];
+        for (const m of this.meshes) {
+            if (m.material && !result.includes(m.material)) {
+                result.push(m.material);
+            }
+        }
+        return result;
+    }
+
+    /** Draws the mesh and its sub meshes. */
+    public render(): void {
+        this.mesh.render();
+    }
+
+    /** Disposes the mesh and its materials. Calling it twice does nothing. */
+    public dispose(): void {
+        if (this._disposed) {
+            return;
+        }
+        this._disposed = true;
+        const materials = this.materials;
+        this.mesh.dispose();
+        for (const material of materials) {
+            material.dispose();
+        }
+    }
+}

package/src/api/shader/IShaderModuleLoader.ts

@@ -8,8 +8,9 @@ export interface IShaderModuleLoader {
 /**
  * Loads a shader module.
  * @param shaderModuleId - The shader module id.
+ * @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.
  */
-  load(shaderModuleId: string): IShaderModule;
+  load(shaderModuleId: string, keyValueDictionary?: {[id:string]: number}): IShaderModule;
 
 }