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

package/src/api/lights/AmbientLight.ts

@@ -1,6 +1,8 @@
 import {Color} from "../data/Color.ts";
 import {createLightId} from "./LightId.ts";
 import type {Scene} from "../scene/Scene.ts";
+import type {ILight} from "./ILight.ts";
+import {TransformNode} from "../scene/node/TransformNode.ts";
 
 /** The descriptor for an ambient light. All fields are optional. */
 export interface AmbientLightDescriptor {
@@ -18,11 +20,12 @@ export interface AmbientLightDescriptor {
 }
 
 /**
- * The ambient light. Plain data: it has no GPU resources.
+ * The ambient light. Plain data: it has no GPU resources. It has a {@link transform} (so it can live in `scene.nodes`),
+ * but the transform has no effect on the lighting.
  * Put it into a {@link LightsBuffer} to use it in shaders.
  * @public
  */
-export class AmbientLight {
+export class AmbientLight implements ILight {
 
     /**
      * The constructor.
@@ -39,6 +42,9 @@ export class AmbientLight {
         scene?.add(this);
     }
 
+    /** The transform. It has no effect on an ambient light. */
+    public transform: TransformNode = new TransformNode();
+
     /** The unique id of this light. */
     public readonly id: number;
 

package/src/api/lights/DirectionalLight.ts

@@ -2,6 +2,11 @@ import {vec3} from "gl-matrix";
 import {Color} from "../data/Color.ts";
 import {createLightId} from "./LightId.ts";
 import type {Scene} from "../scene/Scene.ts";
+import type {ILight} from "./ILight.ts";
+import {TransformNode} from "../scene/node/TransformNode.ts";
+import {CameraTransformUtilities} from "../camera/CameraTransformUtilities.ts";
+
+const _target = vec3.create();
 
 /** The descriptor for a directional light. All fields are optional. */
 export interface DirectionalLightDescriptor {
@@ -17,15 +22,16 @@ export interface DirectionalLightDescriptor {
     /** Multiplies the colour. Defaults to 1. */
     intensity?: number;
 
-    /** The direction in which the light travels. Defaults to straight down, (0, -1, 0). */
+    /** The initial world direction in which the light travels (see {@link DirectionalLight.setDirection}). Defaults to straight down, (0, -1, 0). */
     direction?: vec3;
 }
 
 /**
  * The directional light. Plain data: it has no GPU resources.
+ * The light travels along its transform's forward axis (local -Z), in world space; position and scale are ignored.
  * @public
  */
-export class DirectionalLight {
+export class DirectionalLight implements ILight {
 
     /**
      * The constructor.
@@ -38,7 +44,7 @@ export class DirectionalLight {
         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);
+        this.setDirection(descriptor?.direction ?? [0, -1, 0]);
 
         scene?.add(this);
     }
@@ -55,6 +61,25 @@ export class DirectionalLight {
     /** Multiplies {@link color} when written to the lights buffer. */
     public intensity: number;
 
-    /** The direction in which the light travels. */
-    public direction: vec3;
+    /** The transform. Its world rotation sets the direction (forward is -Z). */
+    public transform: TransformNode = new TransformNode();
+
+    /**
+     * Rotates the transform so the light travels along a world-space direction (converted into the parent's space
+     * when parented). A zero vector leaves the rotation unchanged.
+     * @param direction The world direction; it does not need to be normalized.
+     */
+    public setDirection(direction: vec3): void {
+        const m = this.transform.modelMatrix;
+        vec3.set(_target, m[12] + direction[0], m[13] + direction[1], m[14] + direction[2]);
+        CameraTransformUtilities.aimTransform(this.transform, _target, [0, 1, 0]);
+    }
+
+    /**
+     * Gets the world-space direction in which the light travels (unit length), derived from the transform.
+     * @param out The optional output vector.
+     */
+    public getDirection(out: vec3 = vec3.create()): vec3 {
+        return CameraTransformUtilities.forwardFromWorld(out, this.transform.modelMatrix);
+    }
 }

package/src/api/lights/ILight.ts

@@ -0,0 +1,22 @@
+import type {Color} from "../data/Color.ts";
+import type {ISceneObject} from "../scene/ISceneObject.ts";
+
+/**
+ * The common interface of all lights. A light is a scene object: its `transform` is the single source of truth
+ * for where it is (point lights) or where it points (directional lights). The ambient light ignores its transform.
+ * @public
+ */
+export interface ILight extends ISceneObject {
+
+    /** The unique id of this light. */
+    readonly id: number;
+
+    /** The optional name for a light. */
+    name?: string;
+
+    /** The light colour. Alpha is ignored. */
+    color: Color;
+
+    /** Multiplies {@link color} when written to the lights buffer. */
+    intensity: number;
+}

package/src/api/lights/PointLight.ts

@@ -2,6 +2,9 @@ import {vec3} from "gl-matrix";
 import {Color} from "../data/Color.ts";
 import {createLightId} from "./LightId.ts";
 import type {Scene} from "../scene/Scene.ts";
+import type {ILight} from "./ILight.ts";
+import {TransformNode} from "../scene/node/TransformNode.ts";
+import {CameraTransformUtilities} from "../camera/CameraTransformUtilities.ts";
 
 /** The descriptor for a point light. All fields are optional. */
 export interface PointLightDescriptor {
@@ -17,7 +20,7 @@ export interface PointLightDescriptor {
     /** Multiplies the colour. Defaults to 1. */
     intensity?: number;
 
-    /** World-space position. Defaults to the origin. */
+    /** The initial world position (see {@link PointLight.setPosition}). Defaults to the origin. */
     position?: vec3;
 
     /** Constant attenuation term. Defaults to 1. */
@@ -32,10 +35,11 @@ export interface PointLightDescriptor {
 
 /**
  * The point light. Plain data: it has no GPU resources.
+ * Its position is the world position of its {@link transform}.
  * Attenuation is `1 / (constant + linear * d + quadratic * d²)` for distance `d`.
  * @public
  */
-export class PointLight {
+export class PointLight implements ILight {
 
     /** The default constant attenuation. */
     public static readonly DEFAULT_CONSTANT = 1;
@@ -57,7 +61,7 @@ export class PointLight {
         this.name = descriptor?.name;
         this.color = descriptor?.color?.copy() ?? Color.white();
         this.intensity = descriptor?.intensity ?? 1;
-        this.position = descriptor?.position ? vec3.clone(descriptor.position) : vec3.create();
+        vec3.copy(this.transform.position, descriptor?.position ?? [0, 0, 0]);
         this.constant = descriptor?.constant ?? PointLight.DEFAULT_CONSTANT;
         this.linear = descriptor?.linear ?? PointLight.DEFAULT_LINEAR;
         this.quadratic = descriptor?.quadratic ?? PointLight.DEFAULT_QUADRATIC;
@@ -77,8 +81,25 @@ export class PointLight {
     /** Multiplies {@link color} when written to the lights buffer. */
     public intensity: number;
 
-    /** World-space position of the light. */
-    public position: vec3;
+    /** The transform. Its world position is the light position. */
+    public transform: TransformNode = new TransformNode();
+
+    /**
+     * Moves the light to a world position (converted into the parent's space when parented).
+     * @param position The world position.
+     */
+    public setPosition(position: vec3): void {
+        CameraTransformUtilities.setWorldPosition(this.transform, position);
+    }
+
+    /**
+     * Gets the world position of the light, read from the transform.
+     * @param out The optional output vector.
+     */
+    public getPosition(out: vec3 = vec3.create()): vec3 {
+        const m = this.transform.modelMatrix;
+        return vec3.set(out, m[12], m[13], m[14]);
+    }
 
     /** Constant attenuation term. */
     public constant: number;

package/src/api/lights/_export.ts

@@ -1,3 +1,4 @@
+export * from "./ILight.ts";
 export * from "./AmbientLight.ts";
 export * from "./DirectionalLight.ts";
 export * from "./PointLight.ts";

package/src/api/material/ForwardBlinnPhongMaterial.ts

@@ -14,7 +14,7 @@ import type {LightsBuffer} from "../lights/LightsBuffer.ts";
 import type {AmbientLight} from "../lights/AmbientLight.ts";
 import type {DirectionalLight} from "../lights/DirectionalLight.ts";
 import type {PointLight} from "../lights/PointLight.ts";
-import type {ICameraMaterial} from "./ICameraMaterial.ts";
+import type {IMaterial} from "./IMaterial.ts";
 import type {ILightsMaterial} from "./ILightsMaterial.ts";
 import type {IForwardBlinnPhongRenderPipeline} from "../rendering/render-pipelines/IForwardBlinnPhongRenderPipeline.ts";
 
@@ -39,7 +39,7 @@ export class ForwardBlinnPhongMaterialDescriptor {
  * The Blinn-Phong material with forward calculated lighting.
  * @public
  */
-export class ForwardBlinnPhongMaterial implements ICameraMaterial, ILightsMaterial {
+export class ForwardBlinnPhongMaterial implements IMaterial, ILightsMaterial {
 
     /** The directional light slots of the material's lights buffer and shader. */
     public static readonly MAX_DIRECTIONAL_LIGHTS = 3;

package/src/api/material/IMaterial.ts

@@ -4,6 +4,7 @@ import type { IRenderableMesh } from "../meshes/IRenderableMesh.ts";
 import type { IVertexBuffer } from "../rendering/buffers/IVertexBuffer.ts";
 import type { IIndexBuffer } from "../rendering/buffers/IIndexBuffer.ts";
 import type { IUniformBuffer } from "../rendering/buffers/IUniformBuffer.ts";
+import type {ICamera} from "../camera/ICamera.ts";
 
 /**
  * The material interface.
@@ -21,6 +22,13 @@ export interface IMaterial extends IDisposable {
     /** The geometry format required by the material.*/
     readonly geometryFormat: GeometryFormat;
 
+    /**
+     * The camera.
+     * Setting it binds the camera's buffers, if material uses them.
+     * For some materials, setting camera plays no role as they might not use camera.
+     */
+    camera?: ICamera;
+
     /**
      * Called before rendering.
      */

package/src/api/material/IMaterialFactory.ts

@@ -1,6 +1,7 @@
 import {InspectTextureMipsMaterial} from "./InspectTextureMipsMaterial.ts";
 import type {SpriteMaterial, SpriteMaterialDescriptor} from "./SpriteMaterial.ts";
-import {UnlitMaterial, UnlitMaterialDescriptor} from "./UnlitMaterial.ts";
+import {UnlitMaterial} from "./UnlitMaterial.ts";
+import type {IUnlitMaterialDescriptor} from "./IUnlitMaterialDescriptor.ts";
 import type {ForwardBlinnPhongMaterial, ForwardBlinnPhongMaterialDescriptor} from "./ForwardBlinnPhongMaterial.ts";
 
 /**
@@ -19,7 +20,7 @@ export interface IMaterialFactory {
      * @param descriptor The optional additional configuration options for material, such as rendering options.
      * @returns The Unlit Material.
      */
-    createUnlitMaterial(descriptor?: UnlitMaterialDescriptor): UnlitMaterial;
+    createUnlitMaterial(descriptor?: IUnlitMaterialDescriptor): UnlitMaterial;
 
     /**
      * Creates a sprite material.

package/src/api/material/IUnlitMaterialDescriptor.ts

@@ -0,0 +1,18 @@
+import type {IPrimitiveState} from "../rendering/primitive/IPrimitiveState.ts";
+import type {ICamera} from "../camera/ICamera.ts";
+
+/**
+ * The descriptor for an unlit material. All fields are optional.
+ * @public
+ */
+export interface IUnlitMaterialDescriptor {
+
+    /** The primitive state. By default, the render pipeline's default (back-face culled, counter-clockwise triangles). */
+    primitiveState?: IPrimitiveState;
+
+    /**
+     * The camera used to render this material. By default, none: a zero projection view buffer is bound
+     * until a camera is assigned (a scene assigns its camera).
+     */
+    camera?: ICamera;
+}

package/src/api/material/MaterialFactory.ts

@@ -2,7 +2,8 @@ import {InspectTextureMipsMaterial} from "./InspectTextureMipsMaterial.ts";
 import type { IFramework } from "../IFramework.ts";
 import type { IMaterialFactory } from "./IMaterialFactory.ts";
 import {SpriteMaterial, type SpriteMaterialDescriptor} from "./SpriteMaterial.ts";
-import {UnlitMaterial, UnlitMaterialDescriptor} from "./UnlitMaterial.ts";
+import {UnlitMaterial} from "./UnlitMaterial.ts";
+import type {IUnlitMaterialDescriptor} from "./IUnlitMaterialDescriptor.ts";
 import {ForwardBlinnPhongMaterial, type ForwardBlinnPhongMaterialDescriptor} from "./ForwardBlinnPhongMaterial.ts";
 
 /**
@@ -23,8 +24,8 @@ export class MaterialFactory implements IMaterialFactory {
     }
 
     /** @inheritDoc */
-    public createUnlitMaterial(descriptor? : UnlitMaterialDescriptor): UnlitMaterial {
-        return new UnlitMaterial(this._framework, descriptor );
+    public createUnlitMaterial(descriptor?: IUnlitMaterialDescriptor): UnlitMaterial {
+        return new UnlitMaterial(this._framework, descriptor);
     }
 
     /** @inheritDoc */

package/src/api/material/SpriteMaterial.ts

@@ -8,6 +8,7 @@ import type { IFramework } from "../IFramework.ts";
 import type { IUniformBuffer } from "../rendering/buffers/IUniformBuffer.ts";
 import type { ISpriteRenderPipeline } from "../rendering/render-pipelines/ISpriteRenderPipeline.ts";
 import type { IMaterial } from "./IMaterial.ts";
+import type { ICamera } from "../camera/ICamera.ts";
 
 /** The sprite material descriptor. */
 export interface SpriteMaterialDescriptor {
@@ -27,6 +28,9 @@ export interface SpriteMaterialDescriptor {
  */
 export class SpriteMaterial implements IMaterial {
 
+    /** The camera. Stored only: sprites render in screen space and use no camera buffers. */
+    public camera?: ICamera;
+
     private readonly _renderPipeline: ISpriteRenderPipeline;
 
     /**

package/src/api/material/UnlitMaterial.ts

@@ -1,4 +1,4 @@
-import type {ICameraMaterial} from "./ICameraMaterial.ts";
+import type {IMaterial} from "./IMaterial.ts";
 
 import type {IRenderableMesh} from "../meshes/IRenderableMesh.ts";
 import type { ITexture2D } from "../rendering/texture/ITexture2D.ts";
@@ -14,22 +14,14 @@ import {Color} from "../data/Color.ts";
 import type { IUnlitRenderPipeline } from "../rendering/render-pipelines/IUnlitRenderPipeline.ts";
 import type { IPrimitiveState } from "../rendering/primitive/IPrimitiveState.ts";
 import type {ICamera} from "../camera/ICamera.ts";
-
-/** The additional material config options */
-export class UnlitMaterialDescriptor {
-
-    /** The primitive state. */
-    public primitiveState?: IPrimitiveState;
-
-    /** The camera used to render this material. */
-    public camera?: ICamera;
-}
+import type {IUnlitMaterialDescriptor} from "./IUnlitMaterialDescriptor.ts";
+import {resolveUnlitMaterialDescriptor} from "../../core/material/UnlitMaterialDescriptorUtilities.ts";
 
 
 /**
  * Unlit material.
  */
-export class UnlitMaterial implements ICameraMaterial {
+export class UnlitMaterial implements IMaterial {
 
     private readonly _framework: IFramework;
     private _color = Color.white();
@@ -51,17 +43,18 @@ export class UnlitMaterial implements ICameraMaterial {
     /**
      * The constructor.
      * @param framework The framework.
-     * @param config The optional material descriptor. A projection view buffer passed here is shared and is not disposed by this material.
+     * @param descriptor The optional material descriptor. A projection view buffer passed here is shared and is not disposed by this material.
      */
-    public constructor(framework: IFramework, config? :UnlitMaterialDescriptor) {
+    public constructor(framework: IFramework, descriptor?: IUnlitMaterialDescriptor) {
+        const config = resolveUnlitMaterialDescriptor(descriptor);
         this._framework = framework;
         const usage = BufferUsage.UNIFORM | BufferUsage.COPY_DST;
-        this._camera = config?.camera;
+        this._camera = config.camera;
         // Without a camera an own zero buffer is bound, so rendering before the scene assigns one does not crash.
-        this._ownsProjectionViewBuffer = !config?.camera?.projectionViewBuffer;
-        this._projectionViewBuffer = config?.camera?.projectionViewBuffer ?? framework.bufferFactory.createUniformBuffer(mat4.create(), usage);
+        this._ownsProjectionViewBuffer = !config.camera?.projectionViewBuffer;
+        this._projectionViewBuffer = config.camera?.projectionViewBuffer ?? framework.bufferFactory.createUniformBuffer(mat4.create(), usage);
         this._materialBuffer = framework.bufferFactory.createUniformBuffer(this._materialData, usage);
-        this._primitiveState = config?.primitiveState;
+        this._primitiveState = config.primitiveState;
         // The pipeline is created once a model buffer is assigned (see modelBuffer).
     }
 

package/src/api/material/_export.ts

@@ -4,6 +4,6 @@ export * from "./InspectTextureMipsMaterial.ts"
 export * from "./MaterialFactory.ts"
 export * from "./SpriteMaterial.ts"
 export * from "./UnlitMaterial.ts"
+export * from "./IUnlitMaterialDescriptor.ts";
 export * from "./ForwardBlinnPhongMaterial.ts"
-export * from "./ICameraMaterial.ts"
 export * from "./ILightsMaterial.ts"

package/src/api/meshes/IRenderableMesh.ts

@@ -1,7 +1,7 @@
-import type { mat4, vec3 } from "gl-matrix";
 import type { IMesh } from "./IMesh.ts";
 import type { IMaterial } from "../material/IMaterial.ts";
 import type { IUniformBuffer } from "../rendering/buffers/IUniformBuffer.ts";
+import type {ISceneObject} from "../scene/ISceneObject.ts";
 
 /**
  * A mesh that can be drawn: a mesh plus an optional material, an index range and sub meshes.
@@ -15,7 +15,7 @@ import type { IUniformBuffer } from "../rendering/buffers/IUniformBuffer.ts";
  *   (a `SceneMesh` does that).
  * @public
  */
-export interface IRenderableMesh extends IMesh {
+export interface IRenderableMesh extends IMesh, ISceneObject {
 
     /** The material, if any. A root mesh made only of sub meshes has none. */
     material?: IMaterial;
@@ -32,23 +32,8 @@ export interface IRenderableMesh extends IMesh {
     /** Number of indices to draw; -1 (the default) draws all indices. */
     readonly indexCount: number;
 
-    /** World position. Defaults to the origin. In-place edits are detected. A sub mesh uses the root's. */
-    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. A sub mesh uses the root's.
-     */
-    rotation: vec3;
-
-    /** Scale. Defaults to (1, 1, 1). In-place edits are detected. A sub mesh uses the root's. */
-    scale: vec3;
-
-    /** The model matrix `T * R * S`, recomputed only when position, rotation or scale changed. */
-    readonly modelMatrix: mat4;
-
     /**
-     * The model buffer (std140 `mat4`) holding {@link modelMatrix}. Owned by the root mesh (sub meshes share it),
+     * The model buffer (std140 `mat4`) holding the root's `transform.modelMatrix`. Owned by the root mesh (sub meshes share it),
      * uploaded when the transform changed and assigned to the material(s) before drawing. Created on first use.
      */
     readonly modelBuffer: IUniformBuffer;

package/src/api/meshes/RenderableMesh.ts

@@ -1,4 +1,4 @@
-import {mat4, quat, vec3} from "gl-matrix";
+import {mat4} from "gl-matrix";
 import {Mesh} from "./Mesh.ts";
 import type {IRenderableMesh} from "./IRenderableMesh.ts";
 import type {IFramework} from "../IFramework.ts";
@@ -8,6 +8,7 @@ import type {IVertexBuffer} from "../rendering/buffers/IVertexBuffer.ts";
 import type {IIndexBuffer} from "../rendering/buffers/IIndexBuffer.ts";
 import type {GeometryFormat} from "../geometry/GeometryFormat.ts";
 import {BufferUsage} from "../rendering/buffers/BufferUsage.ts";
+import {TransformNode} from "../scene/node/TransformNode.ts";
 
 /**
  * A mesh that can be drawn (C# `RenderableMesh`). See {@link IRenderableMesh}.
@@ -22,16 +23,6 @@ export class RenderableMesh extends Mesh implements IRenderableMesh {
     private readonly _subMeshes: RenderableMesh[] = [];
     private readonly _parent?: RenderableMesh;
 
-    // Transform; only used on the root.
-    private _position: vec3 = vec3.create();
-    private _rotation: vec3 = vec3.create();
-    private _scale: vec3 = vec3.fromValues(1, 1, 1);
-    private readonly _modelMatrix = mat4.create();
-    private readonly _rotationQuat = quat.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();
     private _modelBuffer?: IUniformBuffer;
     /** The matrix last uploaded to the model buffer. */
     private readonly _uploadedMatrix = mat4.create();
@@ -45,6 +36,17 @@ export class RenderableMesh extends Mesh implements IRenderableMesh {
     /** @inheritDoc */
     public readonly indexCount: number;
 
+    private _transform = new TransformNode();
+
+    /** @inheritDoc A sub mesh returns (and sets) the root's transform. */
+    public get transform(): TransformNode {
+        return this._root._transform;
+    }
+
+    public set transform(value: TransformNode) {
+        this._root._transform = value;
+    }
+
     /**
      * The constructor.
      * @param framework The framework.
@@ -103,38 +105,6 @@ export class RenderableMesh extends Mesh implements IRenderableMesh {
         return this.material?.geometryFormat;
     }
 
-    /** @inheritDoc */
-    public get position(): vec3 { return this._root._position; }
-    public set position(value: vec3) { this._root._position = value; }
-
-    /** @inheritDoc */
-    public get rotation(): vec3 { return this._root._rotation; }
-    public set rotation(value: vec3) { this._root._rotation = value; }
-
-    /** @inheritDoc */
-    public get scale(): vec3 { return this._root._scale; }
-    public set scale(value: vec3) { this._root._scale = value; }
-
-    /** @inheritDoc */
-    public get modelMatrix(): mat4 {
-        const root = this._root;
-        if (root !== this) {
-            return root.modelMatrix;
-        }
-        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._modelMatrix, q, this._position, this._scale);
-        }
-        return this._modelMatrix;
-    }
 
     /** @inheritDoc Created on first access and disposed with the root mesh. */
     public get modelBuffer(): IUniformBuffer {
@@ -143,7 +113,7 @@ export class RenderableMesh extends Mesh implements IRenderableMesh {
             return root.modelBuffer;
         }
         if (!this._modelBuffer) {
-            mat4.copy(this._uploadedMatrix, this.modelMatrix);
+            mat4.copy(this._uploadedMatrix, this.transform.modelMatrix);
             this._modelBuffer = this._framework.bufferFactory.createUniformBuffer(
                 this._uploadedMatrix, BufferUsage.UNIFORM | BufferUsage.COPY_DST, "RenderableMesh.modelBuffer");
         }
@@ -154,7 +124,7 @@ export class RenderableMesh extends Mesh implements IRenderableMesh {
     private _updateModelBuffer(): IUniformBuffer {
         const root = this._root;
         const buffer = root.modelBuffer;
-        const matrix = root.modelMatrix;
+        const matrix = root.transform.modelMatrix;
         if (!mat4.exactEquals(root._uploadedMatrix, matrix)) {
             mat4.copy(root._uploadedMatrix, matrix);
             buffer.update(root._uploadedMatrix);

package/src/api/rendering/IGraphicsDevice.ts

@@ -9,7 +9,7 @@ import type { IRenderPass } from "./renderpass/IRenderPass.ts";
 import {SwapChainDescriptor} from "./swapchain/SwapChainDescriptor.ts";
 import type { ISwapChain } from "./swapchain/ISwapChain.ts";
 import {SamplerDescriptor} from "./sampler/SamplerDescriptor.ts";
-import {PrimitiveStateDescriptor} from "./primitive/PrimitiveStateDescriptor.ts";
+import type {IPrimitiveStateDescriptor} from "./primitive/IPrimitiveStateDescriptor.ts";
 
 /**
  * The interface for a graphics device.
@@ -71,7 +71,7 @@ export interface IGraphicsDevice extends IDisposable {
      * @param descriptor - The primitive state descriptor.
      * @returns The created primitive state.
      */
-    createPrimitiveState(descriptor: PrimitiveStateDescriptor): IPrimitiveState;
+    createPrimitiveState(descriptor?: IPrimitiveStateDescriptor): IPrimitiveState;
 
     /**
      * Creates a render pass for the graphics device.

package/src/api/rendering/IRenderer.ts

@@ -5,7 +5,7 @@ import {RenderingBackend} from "./RenderingBackend.ts";
 import {vec2} from "gl-matrix";
 import type {PowerPreferenceType} from "./PowerPreference.ts";
 import type {TextureSamplerFilteringPreset} from "../../core/rendering/enums.ts";
-import type {TextureColorSpace} from "./enums.ts";
+import type {ColorSpace} from "./enums.ts";
 
 
 /**
@@ -31,7 +31,7 @@ export interface IRendererConfiguration {
     textureFiltering: TextureSamplerFilteringPreset;
 
     /** The desired texture color space. */
-    textureColorSpace: TextureColorSpace;
+    textureColorSpace: ColorSpace;
 }
 
 /**
@@ -46,13 +46,21 @@ export interface IRenderer {
     readonly graphicsDevice: IGraphicsDevice;
 
     /**
-     * The preferred texture format.
-     * This will encode texture which do not specify texture format to:
-     * - {@link TextureFormat.} // TODO: describe SRGB depending on TextureSurfaceFormat requested
-     * - {@link TextureFormat.} // TODO: describe RGBA depending on TextureSurfaceFormat requested
+     * The preferred texture format, derived from the current {@link IRenderer.colorSpace}.
+     * Textures that do not specify a texture format are created with it:
+     * - {@link TextureFormat.RGBA_8_UNORM_SRGB} when the color space is {@link ColorSpace.SRGB} (the default).
+     * - {@link TextureFormat.RGBA_8_UNORM} when the color space is {@link ColorSpace.LINEAR}.
      */
     readonly preferredTextureFormat: TextureFormat;
 
+    /**
+     * The color space. Defaults to the framework configuration's `textureColorSpace`.
+     * Can be switched at runtime, e.g. `framework.renderer.colorSpace = ColorSpace.SRGB`.
+     * Changing it affects textures created afterwards and the main render target's output conversion;
+     * already-created textures are not converted.
+     */
+    colorSpace: ColorSpace;
+
     /**
      * The preferred depth stencil format.
      */

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

@@ -3,4 +3,5 @@ export * from "./IGraphicsDeviceFeatures.ts";
 export * from "./IRenderer.ts";
 export * from "./RenderingBackend.ts";
 export * from "./IGPUInfo.ts";
-export * from "./PowerPreference.ts";
+export * from "./PowerPreference.ts";
+export * from "./enums.ts";

package/src/api/rendering/enums.ts

@@ -19,12 +19,12 @@ export enum Culling {
     Front
 }
 
-/** TODO: */
-export enum TextureColorSpace
+/** The color space. */
+export enum ColorSpace
 {
-    /** TODO */
+    /** The linear color space. */
     LINEAR = "LINEAR",
 
-    /** TODO */
-    SRGB = "S_RGBA",
+    /** The sRGB color space. */
+    SRGB = "SRGB",
 }

package/src/api/rendering/primitive/IPrimitiveStateDescriptor.ts

@@ -0,0 +1,27 @@
+import type {PrimitiveTopology} from "./PrimitiveTopology.ts";
+import type {CullMode} from "./CullMode.ts";
+import type {FrontFace} from "./FrontFace.ts";
+
+/**
+ * Describes the state of a primitive. All fields are optional; the graphics device fills in the defaults.
+ */
+export interface IPrimitiveStateDescriptor {
+
+    /**
+     * The topology of the primitive.
+     * By default, it is set to TRIANGLE_LIST.
+     */
+    topology?: PrimitiveTopology;
+
+    /**
+     * The culling mode.
+     * By default, it is set to BACK.
+     */
+    cullFace?: CullMode;
+
+    /**
+     * The front face.
+     * By default, it is set to CCW (counter clockwise).
+     */
+    frontFace?: FrontFace;
+}

package/src/api/rendering/primitive/_export.ts

@@ -2,4 +2,4 @@ export * from "./CullMode.ts"
 export * from "./FrontFace.ts"
 export * from "./IPrimitiveState.ts"
 export * from "./PrimitiveTopology.ts"
-export * from "./PrimitiveStateDescriptor.ts"
+export * from "./IPrimitiveStateDescriptor.ts"