ris-framework 0.2.0-dev.13 → 0.2.0-dev.16

package/src/api/rendering/render-pipelines/IMainRenderTargetRenderPipeline.ts

@@ -1,5 +1,6 @@
 import type { IRenderPipeline } from "./IRenderPipeline.ts";
 import type { ITexture2D } from "../texture/ITexture2D.ts";
+import type {ColorSpace} from "../enums.ts";
 
 /**
  * Pipeline that is used in renderer as
@@ -13,6 +14,11 @@ export interface IMainRenderTargetRenderPipeline extends IRenderPipeline {
      */
     readonly mainRenderTarget: ITexture2D;
 
+    /**
+     *  Gets or sets the preferred color space. Only relevant for WebGL2 renderer.
+     */
+    colorSpace: ColorSpace;
+
     /**
      * Render to the screen.
      */

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

@@ -0,0 +1,62 @@
+import type {TextureFormat} from "./TextureFormat.ts";
+import type {TextureUsage} from "./TextureUsage.ts";
+import type {vec2} from "gl-matrix";
+import type {ColorSpace} from "../enums.ts";
+
+/**
+ * The texture descriptor. Every field is optional; factories fill in the defaults for missing fields.
+ */
+export interface ITextureDescriptor {
+
+    /**
+     * The texture width.
+     * By default, it is 0.
+     */
+    width?: number;
+
+    /**
+     * The texture height.
+     * By default, it is 0.
+     */
+    height?: number;
+
+    /**
+     * The texture format. When loading texture preferred format can be set.
+     * This overrides framework preferred color space when loading or ktx2 transcoding.
+     * By default, it is UNDEFINED.
+     */
+    textureFormat?: TextureFormat;
+
+    /** The preferred color space. If not defined, it is specified by framework.  */
+    preferredColorSpace?: ColorSpace;
+
+    /**
+     * The texture usage.
+     * By default, it is TEXTURE_BINDING | COPY_DST.
+     */
+    textureUsage?: TextureUsage;
+
+    /**
+     * The texture label.
+     * By default, it is null.
+     */
+    label?: string | null;
+
+    /**
+     * The data per mip level.
+     * By default, it is undefined.
+     */
+    data?: Uint8Array[];
+
+    /**
+     * Should mipmaps be generated.
+     * By default, it is false.
+     */
+    generateMipmaps?: boolean;
+
+    /**
+     * The block size of a texture, which must be set for compressed textures.
+     * By default, it is undefined.
+     */
+    blockSize?: vec2;
+}

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

@@ -2,7 +2,7 @@ import {Color} from "../../data/Color.ts";
 import {TextureUsage} from "./TextureUsage.ts";
 import {TextureFormat} from "./TextureFormat.ts";
 import type { ITexture2D } from "./ITexture2D.ts";
-import {TextureDescriptor} from "./TextureDescriptor.ts";
+import type {ITextureDescriptor} from "./ITextureDescriptor.ts";
 import type {IKtx2Texture} from "ris-ktx2";
 
 /**
@@ -34,7 +34,9 @@ export interface ITextureFactory {
      * @param channels - The number of channels.
      * @param label - The label.
      * @param usage - Texture usage. By default, it is COPY_DST | TEXTURE_BINDING.
-     * @param textureFormat - The texture format. By default, it is undefined. If so, the preferred texture format is used.
+     * @param textureFormat - The texture format. By default (or when UNDEFINED), the renderer's current
+     * {@link IRenderer.preferredTextureFormat} is used, so it follows {@link IRenderer.colorSpace}.
+     * Pass {@link TextureFormat.RGBA_8_UNORM} explicitly for raw data that must stay linear.
      * @param generateMipMaps - Indicates if texture should generate mipmap levels.
      * @returns The texture.
      */
@@ -52,5 +54,5 @@ export interface ITextureFactory {
      * @param descriptor - The optional texture descriptor.
      * @returns The 2D texture.
      */
-    createFromKtx2(ktxTexture: IKtx2Texture, descriptor?: TextureDescriptor): ITexture2D;
+    createFromKtx2(ktxTexture: IKtx2Texture, descriptor?: ITextureDescriptor): ITexture2D;
 }

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

@@ -195,6 +195,7 @@ export class TextureUtilities {
         [TextureFormat.BC7_RGBA_UNORM]: KtxTranscodeFormat.BC7_RGBA,
         [TextureFormat.ETC2_RGBA8_UNORM]: KtxTranscodeFormat.ETC2_RGBA,
         [TextureFormat.PVRTC_4BPPV1_RGBA] : KtxTranscodeFormat.PVRTC1_4_RGBA,
+        [TextureFormat.PVRTC_4BPPV1_RGB] : KtxTranscodeFormat.PVRTC1_4_RGB,
         // 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,
@@ -204,77 +205,33 @@ export class TextureUtilities {
     };
 
     private static readonly _mapKtxTranscodeFormatVkFormat: { [key: number]: number } = {
-        [KtxTranscodeFormat.KTX_TTF_ETC1_RGB]: VkFormat.ETC2_R8G8B8_UNORM_BLOCK,
+        [KtxTranscodeFormat.ETC1_RGB]: VkFormat.ETC2_R8G8B8_UNORM_BLOCK,
         [KtxTranscodeFormat.ETC2_RGBA]: VkFormat.ETC2_R8G8B8A8_UNORM_BLOCK,
-        [KtxTranscodeFormat.KTX_TTF_BC1_RGB]: VkFormat.BC1_RGB_UNORM_BLOCK,
+        [KtxTranscodeFormat.BC1_RGB]: VkFormat.BC1_RGB_UNORM_BLOCK,
         [KtxTranscodeFormat.BC3_RGBA]: VkFormat.BC3_UNORM_BLOCK,
-        [KtxTranscodeFormat.KTX_TTF_BC4_R]: VkFormat.BC4_UNORM_BLOCK,
-        [KtxTranscodeFormat.KTX_TTF_BC5_RG]: VkFormat.BC5_UNORM_BLOCK,
+        [KtxTranscodeFormat.BC4_R]: VkFormat.BC4_UNORM_BLOCK,
+        [KtxTranscodeFormat.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.PVRTC1_4_RGB]: 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.RGB565]: VkFormat.R5G6B5_UNORM_PACK16,
+        [KtxTranscodeFormat.BGR565]: VkFormat.B5G6R5_UNORM_PACK16,
+        [KtxTranscodeFormat.RGBA4444]: VkFormat.R4G4B4A4_UNORM_PACK16,
+        [KtxTranscodeFormat.PVRTC2_4_RGB]: 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,
+        [KtxTranscodeFormat.ETC2_EAC_R11]: VkFormat.EAC_R11_UNORM_BLOCK,
+        [KtxTranscodeFormat.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");
-    }
+    /** sRGB format → its linear variant. */
+    private static readonly _linearVariant: { [key: string]: TextureFormat } = Object.fromEntries(
+        Object.entries(TextureUtilities._srgbVariant).map(([linear, srgb]) => [srgb, linear as TextureFormat])
+    );
 
-    /**
-     * 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;
-    }
+    /** Every sRGB format. */
+    private static readonly _srgbFormats: TextureFormat[] = Object.values(TextureUtilities._srgbVariant);
 
     /**
      * Checks if the given texture format is a compressed texture format.
@@ -361,4 +318,45 @@ export class TextureUtilities {
         return format;
     }
 
+    /**
+     * Maps the linear format to the srgb variant.
+     * @param textureFormat The linear format.
+     * @return The srgb variant, or the format itself if it is already sRGB or has no sRGB variant (e.g. PVRTC).
+     */
+    public static convertToSrgbVariant(textureFormat: TextureFormat) : TextureFormat {
+        return this._srgbVariant[textureFormat] ?? textureFormat;
+    }
+
+    /**
+     * Maps the srgb format to the linear variant.
+     * @param textureFormat The srgb format.
+     * @return The linear variant, or the format itself if it is already linear.
+     */
+    public static convertToLinearVariant(textureFormat: TextureFormat) : TextureFormat {
+        return this._linearVariant[textureFormat] ?? textureFormat;
+    }
+
+    /**
+     * Checks whether the texture format is an sRGB format.
+     * @param textureFormat The texture format to check.
+     * @return True if srgb texture format.
+     */
+    public static isSrgbFormat(textureFormat: TextureFormat) : boolean {
+        return this._srgbFormats.includes(textureFormat);
+    }
+
+    /**
+     * Returns the requested format if it is the file's format or its sRGB/linear variant.
+     * @param fileFormat The format the data is stored in.
+     * @param requested The explicitly requested format.
+     * @throws If the requested format cannot reinterpret the data.
+     */
+    public static resolveExplicitFormat(fileFormat: TextureFormat, requested: TextureFormat): TextureFormat {
+        if (requested == fileFormat
+            || requested == TextureUtilities.convertToSrgbVariant(fileFormat)
+            || requested == TextureUtilities.convertToLinearVariant(fileFormat)) {
+            return requested;
+        }
+        throw new Error(`Texture format ${requested} is not compatible with the file's format ${fileFormat}; only its sRGB or linear variant can be used.`);
+    }
 }

package/src/api/rendering/texture/_export-texture.ts

@@ -5,5 +5,5 @@ export * from "./TextureViewDimension.ts";
 export * from "./TextureFormat.ts";
 export * from "./ITextureView.ts";
 export * from "./ITextureFactory.ts";
-export * from "./TextureDescriptor.ts";
+export * from "./ITextureDescriptor.ts";
 export * from "./TextureUtilities.ts";

package/src/api/scene/ISceneObject.ts

@@ -0,0 +1,13 @@
+import type {TransformNode} from "./node/TransformNode.ts";
+
+/**
+ * An object that can be placed in a scene: it has a transform.
+ * @public
+ */
+export interface ISceneObject {
+
+    /**
+     * The transform node.
+     */
+    transform: TransformNode;
+}

package/src/api/scene/Scene.ts

@@ -5,13 +5,14 @@ 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";
+import type {ISceneObject} from "./ISceneObject.ts";
+import {TransformNode} from "./node/TransformNode.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;
+/** Anything a scene can hold: a mesh, a scene object, a light (ambient, directional, point) or a camera. */
+export type SceneItem = IRenderableMesh | SceneMesh | ISceneObject | AmbientLight | DirectionalLight | PointLight | ICamera;
 
 /**
  * The scene. Lights and cameras given a scene in their constructor add themselves through {@link add};
@@ -22,6 +23,7 @@ export type SceneItem = IRenderableMesh | SceneMesh | AmbientLight | Directional
 export class Scene implements IDisposable {
 
     private readonly _sceneMeshes: SceneMesh[] = [];
+    private readonly _nodes: ISceneObject[] = [];
     private readonly _directionalLights: DirectionalLight[] = [];
     private readonly _pointLights: PointLight[] = [];
 
@@ -71,6 +73,11 @@ export class Scene implements IDisposable {
         return this._sceneMeshes;
     }
 
+    /** The scene objects (anything with a transform, including root meshes), in the order they were added. */
+    public get nodes(): readonly ISceneObject[] {
+        return this._nodes;
+    }
+
     /** The root meshes in this scene, in the order they were added. */
     public get meshes(): readonly IRenderableMesh[] {
         return this._sceneMeshes.map(s => s.mesh);
@@ -103,9 +110,13 @@ export class Scene implements IDisposable {
      * 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).
+     *   The mesh is also added to {@link nodes}.
+     * - {@link ISceneObject} (anything with a `transform`): added to {@link nodes}; {@link update} updates its transform.
+     * - Lights are also added to {@link nodes} (they are scene objects).
+ * - 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}.
+     * - Camera: becomes the scene {@link camera} and is added to {@link nodes} (cameras are scene objects).
+     *   Checked before the generic scene object case.
      * 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.
@@ -113,10 +124,15 @@ export class Scene implements IDisposable {
     public add(item: SceneItem): void {
         if (item instanceof AmbientLight) {
             this._addAmbientLight(item);
+            this._addNode(item);
         } else if (item instanceof DirectionalLight || item instanceof PointLight) {
             this._addLight(item);
+            this._addNode(item);
         } else if (Scene._isCamera(item)) {
             this.camera = item;
+            if (Scene._isSceneObject(item)) {
+                this._addNode(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)) {
@@ -124,8 +140,11 @@ export class Scene implements IDisposable {
                 this._sceneMeshes.push(sceneMesh);
                 this._bind(sceneMesh);
             }
+            this._addNode(mesh);
+        } else if (Scene._isSceneObject(item)) {
+            this._addNode(item);
         } else {
-            throw new Error("Scene.add: expected a mesh, an AmbientLight, DirectionalLight, PointLight or a camera.");
+            throw new Error("Scene.add: expected a mesh, a scene object, an AmbientLight, DirectionalLight, PointLight or a camera.");
         }
     }
 
@@ -133,7 +152,7 @@ export class Scene implements IDisposable {
      * 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).
+     * @returns True when the item was in the scene.
      * @throws Error when removing the active ambient light (set another {@link activeAmbientLight} first), or for an unsupported item.
      */
     public remove(item: SceneItem): boolean {
@@ -141,16 +160,19 @@ export class Scene implements IDisposable {
             if (item === this._activeAmbientLight) {
                 throw new Error("Scene.remove: cannot remove the active ambient light; set scene.activeAmbientLight to another light first.");
             }
+            Scene._removeFrom(this._nodes, item);
             return Scene._removeFrom(this.ambientLights, item);
         }
         if (item instanceof DirectionalLight || item instanceof PointLight) {
+            Scene._removeFrom(this._nodes, item);
             return item instanceof DirectionalLight
                 ? Scene._removeFrom(this._directionalLights, item)
                 : Scene._removeFrom(this._pointLights, item);
         }
         if (Scene._isCamera(item)) {
+            const wasNode = Scene._removeFrom(this._nodes, item);
             if (item !== this._activeCamera) {
-                return false;
+                return wasNode;
             }
             this._activeCamera = undefined;
             return true;
@@ -158,13 +180,17 @@ export class Scene implements IDisposable {
         if (item instanceof SceneMesh || Scene._isMesh(item)) {
             const mesh = item instanceof SceneMesh ? item.mesh : item;
             const index = this._sceneMeshes.findIndex(s => s.mesh === mesh);
+            Scene._removeFrom(this._nodes, 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.");
+        if (Scene._isSceneObject(item)) {
+            return Scene._removeFrom(this._nodes, item);
+        }
+        throw new Error("Scene.remove: expected a mesh, a scene object, an AmbientLight, DirectionalLight, PointLight or a camera.");
     }
 
     /**
@@ -220,6 +246,17 @@ export class Scene implements IDisposable {
             && "projectionViewBuffer" in camera && "viewMatrix" in camera && typeof camera.updateBuffers === "function";
     }
 
+    /** Scene objects have a TransformNode as transform. */
+    private static _isSceneObject(item: unknown): item is ISceneObject {
+        return typeof item === "object" && item !== null && (item as Partial<ISceneObject>).transform instanceof TransformNode;
+    }
+
+    private _addNode(node: ISceneObject): void {
+        if (!this._nodes.includes(node)) {
+            this._nodes.push(node);
+        }
+    }
+
     /** Renderable meshes have render() and sub meshes. */
     private static _isMesh(item: unknown): item is IRenderableMesh {
         const mesh = item as Partial<IRenderableMesh> | null;
@@ -227,12 +264,15 @@ export class Scene implements IDisposable {
     }
 
     /**
-     * Updates the scene: assigns {@link camera}, the active ambient light and the light lists to the mesh materials.
+     * Updates the scene: updates the transforms of {@link nodes}, 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 node of this._nodes) {
+            node.transform.update(_time);
+        }
         for (const sceneMesh of this._sceneMeshes) {
             this._bind(sceneMesh);
         }
@@ -266,7 +306,7 @@ export class Scene implements IDisposable {
         }
         for (const material of sceneMesh.materials) {
             // The setter rebinds buffers, so skip when unchanged.
-            if (isCameraMaterial(material) && material.camera !== camera) {
+            if (material.camera !== camera) {
                 material.camera = camera;
             }
         }
@@ -293,5 +333,6 @@ export class Scene implements IDisposable {
             sceneMesh.dispose();
         }
         this._sceneMeshes.length = 0;
+        this._nodes.length = 0;
     }
 }

package/src/api/scene/node/Node.ts

@@ -0,0 +1,54 @@
+/**
+ * A node in a hierarchy. A node has at most one parent; use {@link addChild} and {@link removeChild}
+ * to change the hierarchy (they keep `parent` and `children` in sync).
+ * @public
+ */
+export class Node {
+
+    private readonly _children: Node[] = [];
+    private _parent?: Node;
+
+    /** The child nodes of this node. */
+    public get children(): readonly Node[] {
+        return this._children;
+    }
+
+    /** The parent node of this node, if any. */
+    public get parent(): Node | undefined {
+        return this._parent;
+    }
+
+    /**
+     * Adds a child. It is removed from its previous parent first. Adding an existing child does nothing.
+     * @param child The child to add.
+     * @throws Error when adding the node to itself or to one of its descendants.
+     */
+    public addChild(child: Node): void {
+        if (child._parent === this) {
+            return;
+        }
+        for (let n: Node | undefined = this; n; n = n._parent) {
+            if (n === child) {
+                throw new Error("Node.addChild: a node cannot be added to itself or to one of its descendants.");
+            }
+        }
+        child._parent?.removeChild(child);
+        child._parent = this;
+        this._children.push(child);
+    }
+
+    /**
+     * Removes a child.
+     * @param child The child to remove.
+     * @returns True when it was a child of this node.
+     */
+    public removeChild(child: Node): boolean {
+        const index = this._children.indexOf(child);
+        if (index < 0) {
+            return false;
+        }
+        this._children.splice(index, 1);
+        child._parent = undefined;
+        return true;
+    }
+}

package/src/api/scene/node/TransformNode.ts

@@ -0,0 +1,88 @@
+import {mat4, quat, vec3} from "gl-matrix";
+import type {GameTime} from "../../time/GameTime.ts";
+import {Node} from "./Node.ts";
+
+/**
+ * The node responsible for transformations in the world.
+ *
+ * The matrices are computed lazily: reading {@link modelMatrix} recomputes them when position, rotation or scale
+ * changed (also through in-place edits), so {@link update} does not have to be called before the first render.
+ * When the parent is a `TransformNode`, {@link modelMatrix} is the world matrix `parent.modelMatrix * localMatrix`.
+ * @public
+ */
+export class TransformNode extends Node {
+
+    private readonly _rotationQuat = quat.create();
+    private readonly _localMatrix = mat4.create();
+    private readonly _worldMatrix = mat4.create();
+    // Cached copies to detect in-place edits; NaN forces the first computation.
+    private readonly _lastPosition = vec3.fromValues(NaN, NaN, NaN);
+    private readonly _lastRotation = vec3.create();
+    private readonly _lastScale = vec3.create();
+
+    /**
+     * The constructor.
+     */
+    public constructor() {
+        super();
+
+        this.position = vec3.fromValues(0, 0, 0);
+        this.rotation = vec3.fromValues(0, 0, 0);
+        this.scale = vec3.fromValues(1, 1, 1);
+    }
+
+    /** Position relative to the parent (the world, without one). Defaults to the origin. In-place edits are detected. */
+    public position: vec3;
+
+    /**
+     * Euler rotation in radians, applied in Y, X, Z order (yaw, pitch, roll): `R = Ry * Rx * Rz`.
+     * Defaults to (0, 0, 0). In-place edits are detected.
+     */
+    public rotation: vec3;
+
+    /** Scale. Defaults to (1, 1, 1). In-place edits are detected. */
+    public scale: vec3;
+
+    /** The local matrix `T * R * S`, recomputed only when position, rotation or scale changed. */
+    public get localMatrix(): mat4 {
+        if (!vec3.exactEquals(this._lastPosition, this.position)
+            || !vec3.exactEquals(this._lastRotation, this.rotation)
+            || !vec3.exactEquals(this._lastScale, this.scale)) {
+            vec3.copy(this._lastPosition, this.position);
+            vec3.copy(this._lastRotation, this.rotation);
+            vec3.copy(this._lastScale, this.scale);
+            const q = quat.identity(this._rotationQuat);
+            quat.rotateY(q, q, this.rotation[1]);
+            quat.rotateX(q, q, this.rotation[0]);
+            quat.rotateZ(q, q, this.rotation[2]);
+            mat4.fromRotationTranslationScale(this._localMatrix, q, this.position, this.scale);
+        }
+        return this._localMatrix;
+    }
+
+    /**
+     * The model (world) matrix: {@link localMatrix}, or `parent.modelMatrix * localMatrix` when the parent is a
+     * `TransformNode`. Always the same matrix object for a node without a parent transform.
+     */
+    public get modelMatrix(): mat4 {
+        const parent = this.parent;
+        if (parent instanceof TransformNode) {
+            return mat4.multiply(this._worldMatrix, parent.modelMatrix, this.localMatrix);
+        }
+        return this.localMatrix;
+    }
+
+    /**
+     * Updates the node and its transform children, recomputing the matrices if needed.
+     * Called by `Scene.update` for scene nodes; optional otherwise.
+     * @param gameTime The {@link GameTime}
+     */
+    public update(gameTime: GameTime): void {
+        void this.modelMatrix;
+        for (const child of this.children) {
+            if (child instanceof TransformNode) {
+                child.update(gameTime);
+            }
+        }
+    }
+}

package/src/core/material/UnlitMaterialDescriptorUtilities.ts

@@ -0,0 +1,21 @@
+import type {IUnlitMaterialDescriptor} from "../../api/material/IUnlitMaterialDescriptor.ts";
+
+/**
+ * An unlit material descriptor with every field present. `undefined` means "use the default":
+ * the pipeline's default primitive state, and no camera (a placeholder projection view buffer).
+ * @internal
+ */
+export type ResolvedUnlitMaterialDescriptor = { [K in keyof Required<IUnlitMaterialDescriptor>]: IUnlitMaterialDescriptor[K] };
+
+/**
+ * Fills in the defaults for every missing field of an unlit material descriptor.
+ * @param desc The descriptor, possibly partial or missing.
+ * @returns A new descriptor with the defaults applied.
+ * @internal
+ */
+export function resolveUnlitMaterialDescriptor(desc?: IUnlitMaterialDescriptor): ResolvedUnlitMaterialDescriptor {
+    return {
+        primitiveState: desc?.primitiveState,
+        camera: desc?.camera,
+    };
+}

package/src/core/rendering/AGraphicsDevice.ts

@@ -8,7 +8,7 @@ import {
     type IBlendState,
     type IPrimitiveState,
     type IGraphicsDevice, SwapChainDescriptor, type RenderPassDescriptor, SamplerFilter, MipMapSamplerFilter,
-    type ISwapChain, type IRenderPass, type PrimitiveStateDescriptor
+    type ISwapChain, type IRenderPass, type IPrimitiveStateDescriptor
 } from "../../api/index.ts";
 import {PowerPreferenceType} from "../../api/rendering/PowerPreference.ts";
 
@@ -103,7 +103,7 @@ export abstract class AGraphicsDevice implements IGraphicsDevice {
     public abstract createBlendState(descriptor: BlendStateDescriptor): IBlendState;
 
     /** @inheritdoc */
-    public abstract createPrimitiveState(descriptor?: PrimitiveStateDescriptor ): IPrimitiveState;
+    public abstract createPrimitiveState(descriptor?: IPrimitiveStateDescriptor): IPrimitiveState;
 
     /** @inheritDoc */
     public abstract setupDebugCallback(): void;