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

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,
@@ -343,4 +344,19 @@ export class TextureUtilities {
     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/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;

package/src/core/rendering/ARenderer.ts

@@ -36,6 +36,7 @@ export abstract class ARenderer implements ITempRenderer {
     private _swapChainRequiresResize: boolean = false;
     private _mainRenderPassDirty = true;
     private _clearColor: Color = Color.lightPink();
+    private _colorSpace: ColorSpace;
 
     protected _mainRenderTargetRequiresResize: boolean = false;
     protected _swapChain: ISwapChain = null!;
@@ -46,6 +47,7 @@ export abstract class ARenderer implements ITempRenderer {
     protected _mainRenderTargetPipeline?: IMainRenderTargetRenderPipeline;
     protected _renderConfiguration: IRendererConfiguration;
 
+
     /** @inheritdoc */
     public get graphicsDevice(): IGraphicsDevice {
         return this._graphicsDevice;
@@ -67,10 +69,27 @@ export abstract class ARenderer implements ITempRenderer {
     }
 
     /** @inheritdoc */
-    public readonly preferredTextureFormat: TextureFormat;
+    public get preferredTextureFormat(): TextureFormat {
+        return this._colorSpace == ColorSpace.SRGB ? TextureFormat.RGBA_8_UNORM_SRGB : TextureFormat.RGBA_8_UNORM;
+    }
+
+    /** @inheritDoc */
+    public get colorSpace(): ColorSpace {
+        return this._colorSpace;
+    }
 
     /** @inheritDoc */
-    public readonly preferredColorSpace: ColorSpace;
+    public set colorSpace(colorSpace: ColorSpace) {
+        if (colorSpace == this._colorSpace) {
+            return;
+        }
+        this._colorSpace = colorSpace;
+        if (this._mainRenderTargetPipeline) {
+            this._mainRenderTargetPipeline.colorSpace = colorSpace;
+            // The main render target's format follows the color space, so recreate it on the next frame.
+            this._mainRenderTargetRequiresResize = true;
+        }
+    }
 
     /** @inheritdoc */
     public get preferredDepthStencilFormat(): TextureFormat {
@@ -111,9 +130,7 @@ export abstract class ARenderer implements ITempRenderer {
         this._windowManager = framework.windowManager;
         this._currentBackBufferSize[0] = this._windowManager.canvas.width;
         this._currentBackBufferSize[1] = this._windowManager.canvas.height;
-        this.preferredColorSpace = configuration.textureColorSpace;
-        this.preferredTextureFormat = configuration.textureColorSpace == ColorSpace.SRGB
-            ? TextureFormat.RGBA_8_UNORM_SRGB : TextureFormat.RGBA_8_UNORM;
+        this._colorSpace = configuration.textureColorSpace;
     }
 
      backend: RenderingBackend = RenderingBackend.WEB_GL;
@@ -192,6 +209,7 @@ export abstract class ARenderer implements ITempRenderer {
         this._mainRenderTargetPipeline = this._framework
             .renderPipelineFactory
             .createMainFrameBufferPipeline(this._mainRenderTarget);
+        this._mainRenderTargetPipeline.colorSpace = this._colorSpace;
 
         this._createMainRenderPass();
         this._mainRenderTargetRequiresResize = false;

package/src/core/rendering/primitive/PrimitiveStateDescriptorUtilities.ts

@@ -0,0 +1,22 @@
+import {CullMode, FrontFace, type IPrimitiveStateDescriptor, PrimitiveTopology} from "../../../api/index.ts";
+
+/**
+ * A primitive state descriptor with all defaults applied.
+ * @internal
+ */
+export type ResolvedPrimitiveStateDescriptor = Required<IPrimitiveStateDescriptor>;
+
+/**
+ * Fills in the defaults for every missing field of a primitive state descriptor:
+ * TRIANGLE_LIST topology, BACK culling and CCW front face.
+ * @param desc The descriptor, possibly partial or missing.
+ * @returns A new descriptor with the defaults applied.
+ * @internal
+ */
+export function resolvePrimitiveStateDescriptor(desc?: IPrimitiveStateDescriptor): ResolvedPrimitiveStateDescriptor {
+    return {
+        topology: desc?.topology ?? PrimitiveTopology.TRIANGLE_LIST,
+        cullFace: desc?.cullFace ?? CullMode.BACK,
+        frontFace: desc?.frontFace ?? FrontFace.CCW,
+    };
+}

package/src/core/rendering/texture/TextureDescriptorUtilities.ts

@@ -1,11 +1,11 @@
 import {type ITextureDescriptor, TextureFormat, TextureUsage} from "../../../api/index.ts";
 
 /**
- * A texture descriptor with all defaults applied. Only `data` and `blockSize` stay optional.
+ * A texture descriptor with all defaults applied. Only `data`, `blockSize` and `preferredColorSpace` stay optional.
  * @internal
  */
 export type ResolvedTextureDescriptor =
-    Required<Omit<ITextureDescriptor, "data" | "blockSize">> & Pick<ITextureDescriptor, "data" | "blockSize">;
+    Required<Omit<ITextureDescriptor, "data" | "blockSize" | "preferredColorSpace">> & Pick<ITextureDescriptor, "data" | "blockSize" | "preferredColorSpace">;
 
 /**
  * Fills in the defaults for every missing field of a texture descriptor.
@@ -23,5 +23,6 @@ export function resolveTextureDescriptor(desc?: ITextureDescriptor): ResolvedTex
         data: desc?.data,
         generateMipmaps: desc?.generateMipmaps ?? false,
         blockSize: desc?.blockSize,
+        preferredColorSpace: desc?.preferredColorSpace,
     };
 }

package/src/webgl/WebGlGraphicsDevice.ts

@@ -15,7 +15,7 @@ import {
     type ISampler,
     type ISwapChain,
     type IWindowManager,
-    PrimitiveStateDescriptor,
+    type IPrimitiveStateDescriptor,
     RenderPassDescriptor,
     SwapChainDescriptor
 } from "../api/index.ts";
@@ -125,8 +125,7 @@ export class WebGlGraphicsDevice extends AGraphicsDevice {
     }
 
     /** @inheritdoc */
-    public createPrimitiveState(descriptor?: PrimitiveStateDescriptor): IPrimitiveState {
-        descriptor = descriptor ?? new PrimitiveStateDescriptor();
+    public createPrimitiveState(descriptor?: IPrimitiveStateDescriptor): IPrimitiveState {
         return new WebGlPrimitiveState(this._gl, descriptor);
     }
 }

package/src/webgl/lights/WebGlLightsBuffer.ts

@@ -11,6 +11,9 @@ import {
     type LightsBufferDescriptor,
     DEFAULT_DIRECTIONAL_LIGHTS_COUNT,
 } from "../../api/index.ts";
+import {vec3} from "gl-matrix";
+
+const _v = vec3.create();
 
 /**
  * The WebGL lights buffer. Owns a std140 uniform buffer for the `LightsBuffer` block.
@@ -191,10 +194,15 @@ export class WebGlLightsBuffer implements LightsBuffer {
             this._writeColor(offset, light?.color, light?.intensity ?? 0);
             this._data[offset + 3] = 0;
 
-            // vec3 direction
-            this._data[offset + 4] = light ? light.direction[0] : 0;
-            this._data[offset + 5] = light ? light.direction[1] : 0;
-            this._data[offset + 6] = light ? light.direction[2] : 0;
+            // vec3 direction (world space, from the transform)
+            if (light) {
+                light.getDirection(_v);
+            } else {
+                vec3.zero(_v);
+            }
+            this._data[offset + 4] = _v[0];
+            this._data[offset + 5] = _v[1];
+            this._data[offset + 6] = _v[2];
             this._data[offset + 7] = 0;
         }
 
@@ -209,10 +217,15 @@ export class WebGlLightsBuffer implements LightsBuffer {
             // An empty slot keeps constant at 1 so the shader never divides by zero.
             this._data[offset + 3] = light ? light.constant : 1;
 
-            // vec3 position, float linear
-            this._data[offset + 4] = light ? light.position[0] : 0;
-            this._data[offset + 5] = light ? light.position[1] : 0;
-            this._data[offset + 6] = light ? light.position[2] : 0;
+            // vec3 position (world space, from the transform), float linear
+            if (light) {
+                light.getPosition(_v);
+            } else {
+                vec3.zero(_v);
+            }
+            this._data[offset + 4] = _v[0];
+            this._data[offset + 5] = _v[1];
+            this._data[offset + 6] = _v[2];
             this._data[offset + 7] = light ? light.linear : 0;
 
             // float quadratic, then padding to the 16-byte struct size

package/src/webgl/primitive/WebGlPrimitiveState.ts

@@ -2,9 +2,10 @@ import {
     CullMode,
     type FrontFace,
     type IPrimitiveState,
-    type PrimitiveStateDescriptor,
+    type IPrimitiveStateDescriptor,
     type PrimitiveTopology
 } from "../../api/index.ts";
+import {resolvePrimitiveStateDescriptor} from "../../core/rendering/primitive/PrimitiveStateDescriptorUtilities.ts";
 import { WebGlConverter } from "../utilities/WebGlConverter.ts";
 
 /**
@@ -19,12 +20,13 @@ export class WebGlPrimitiveState implements IPrimitiveState {
     /**
      * The constructor.
      * @param _gl The WebGL2 Rendering Context.
-     * @param descriptor The descriptor of the primitive state.
+     * @param descriptor The descriptor of the primitive state; missing fields use the defaults.
      */
-    public constructor(_gl: WebGL2RenderingContext, descriptor: PrimitiveStateDescriptor) {
-        this.topology = descriptor.topology;
-        this.cullFace = descriptor.cullFace;
-        this.frontFace = descriptor.frontFace;
+    public constructor(_gl: WebGL2RenderingContext, descriptor?: IPrimitiveStateDescriptor) {
+        const resolved = resolvePrimitiveStateDescriptor(descriptor);
+        this.topology = resolved.topology;
+        this.cullFace = resolved.cullFace;
+        this.frontFace = resolved.frontFace;
 
         this._cullingEnabled = this.cullFace != CullMode.NONE;
 

package/src/webgl/render-pipelines/WebGlMainRenderTargetRenderPipeline.ts

@@ -13,6 +13,7 @@ import {
     type ITexture2D,
     TextureFormat
 } from "../../api/index.ts";
+import {ColorSpace} from "../../api/rendering/enums.ts";
 
 /**
  * The WebGL implementation of the main render target render pipeline.
@@ -24,6 +25,7 @@ export class WebGlMainRenderTargetRenderPipeline extends AWebGlRenderPipeline im
     private _mainRenderTarget: WebGlTexture2D = null!;
 
     private _colorConversionUniformLocation: WebGLUniformLocation = null!;
+    /** The shader's `u_colorConversion`: 1 encodes linear to sRGB on output, 0 passes through. */
     private _colorSpaceValue = 0;
 
     /**
@@ -40,6 +42,18 @@ export class WebGlMainRenderTargetRenderPipeline extends AWebGlRenderPipeline im
         }
     }
 
+    /**
+     * The color space. With SRGB the main render target is sRGB (sampled back as linear) and the shader
+     * encodes to sRGB for the screen; with LINEAR the values are passed through. Takes effect on the next frame.
+     */
+    public get colorSpace(): ColorSpace {
+        return this._colorSpaceValue == 1 ? ColorSpace.SRGB : ColorSpace.LINEAR;
+    }
+
+    public set colorSpace(value: ColorSpace) {
+        this._colorSpaceValue = value == ColorSpace.SRGB ? 1 : 0;
+    }
+
     /** @inheritDoc */
     public readonly geometryFormat = GeometryFormat.POS3_COLOR4_TEXTURECOORDS2;