ris-framework 0.1.0 → 0.2.0-dev.12

package/src/api/material/SpriteMaterial.ts

@@ -0,0 +1,83 @@
+import type { GeometryFormat } from "../geometry/GeometryFormat.ts";
+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 { ITexture2D } from "../rendering/texture/ITexture2D.ts";
+import type { ISampler } from "../rendering/sampler/ISampler.ts";
+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";
+
+/** The sprite material descriptor. */
+export interface SpriteMaterialDescriptor {
+
+    /** The projection view buffer. Shared, it is not disposed by the material. */
+    projectionViewBuffer: IUniformBuffer;
+
+    /** The sprite texture. */
+    texture: ITexture2D;
+
+    /** The texture sampler. */
+    sampler: ISampler;
+}
+
+/**
+ * The sprite material.
+ */
+export class SpriteMaterial implements IMaterial {
+
+    private readonly _renderPipeline: ISpriteRenderPipeline;
+
+    /**
+     * The constructor.
+     * @param framework - The framework.
+     * @param descriptor - The sprite material descriptor.
+     */
+    public constructor(framework: IFramework, descriptor: SpriteMaterialDescriptor) {
+        this._renderPipeline = framework.renderPipelineFactory.createSpriteRenderPipeline(descriptor.projectionViewBuffer);
+        this._renderPipeline.textureSampler = descriptor.sampler;
+        this._renderPipeline.spriteTexture = descriptor.texture;
+    }
+
+    /** @inheritDoc */
+    public get geometryFormat(): GeometryFormat {
+        return this._renderPipeline.geometryFormat;
+    }
+
+    /** The sprite texture. */
+    public get texture(): ITexture2D {
+        return this._renderPipeline.spriteTexture;
+    }
+
+    /** The sprite texture. */
+    public set texture(value: ITexture2D) {
+        this._renderPipeline.spriteTexture = value;
+    }
+
+    /** @inheritDoc */
+    public beforeRender(): void {
+        // Nothing to do
+    }
+
+    /** @inheritDoc */
+    public renderMesh(mesh: IRenderableMesh): void {
+        this.render(mesh.vertexBuffer!, mesh.indexBuffer!, mesh.indexCount ?? -1, mesh.indexStart ?? 0);
+    }
+
+    /**
+     * Renders the material.
+     * @param vertexBuffer - The vertex buffer.
+     * @param indexBuffer - The index buffer.
+     * @param indicesCount - The number of indices to draw. If -1 draws all indices.
+     * @param indicesOffset - Indices offset. Defaults to 0.
+     */
+    public render(vertexBuffer: IVertexBuffer, indexBuffer: IIndexBuffer, indicesCount?: number, indicesOffset?: number): void {
+        this._renderPipeline.render(vertexBuffer, indexBuffer, indicesCount, indicesOffset);
+    }
+
+    /** @inheritDoc */
+    public dispose(): void {
+        this._renderPipeline.dispose();
+    }
+}

package/src/api/material/UnlitMaterial.ts

@@ -1,5 +1,6 @@
+import type {ICameraMaterial} from "./ICameraMaterial.ts";
 
-import type { IMesh } from "../meshes/IMesh.ts";
+import type {IRenderableMesh} from "../meshes/IRenderableMesh.ts";
 import type { ITexture2D } from "../rendering/texture/ITexture2D.ts";
 import type { ISampler } from "../rendering/sampler/ISampler.ts";
 import {mat4} from "gl-matrix";
@@ -12,6 +13,7 @@ import {BufferUsage} from "../rendering/buffers/BufferUsage.ts";
 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 {
@@ -19,26 +21,32 @@ export class UnlitMaterialDescriptor {
     /** The primitive state. */
     public primitiveState?: IPrimitiveState;
 
-    /** The projection view buffer to use */
-    public projectionViewBuffer?: IUniformBuffer;
+    /** The camera used to render this material. */
+    public camera?: ICamera;
 }
 
 
 /**
  * Unlit material.
  */
-export class UnlitMaterial {
+export class UnlitMaterial implements ICameraMaterial {
 
     private readonly _framework: IFramework;
     private _color = Color.white();
     private _materialData = [1,1,1,1];
-    private _pipeline: IUnlitRenderPipeline;
+    /** Created when the model buffer is assigned (the pipeline requires one). */
+    private _pipeline?: IUnlitRenderPipeline;
+    private readonly _primitiveState?: IPrimitiveState;
+    /** Texture and sampler set before the pipeline exists; applied when it is created. */
+    private _pendingTexture?: ITexture2D;
+    private _pendingSampler?: ISampler;
+    private _samplerSet = false;
     private _projectionViewBuffer: IUniformBuffer;
     /** False when the projection view buffer came from the descriptor. The caller owns that one. */
-    private readonly _ownsProjectionViewBuffer: boolean;
+    private _ownsProjectionViewBuffer: boolean;
+    private _camera?: ICamera;
     private _materialBuffer: IUniformBuffer;
-    private _modelBuffer: IUniformBuffer;
-    private _previousModelMatrix = mat4.create();
+    private _modelBuffer?: IUniformBuffer;
 
     /**
      * The constructor.
@@ -47,18 +55,59 @@ export class UnlitMaterial {
      */
     public constructor(framework: IFramework, config? :UnlitMaterialDescriptor) {
         this._framework = framework;
-        void this._framework;
         const usage = BufferUsage.UNIFORM | BufferUsage.COPY_DST;
-        this._ownsProjectionViewBuffer = !config?.projectionViewBuffer;
-        this._projectionViewBuffer = config?.projectionViewBuffer ?? framework.bufferFactory.createUniformBuffer(this._previousModelMatrix, usage);
-        this._modelBuffer = framework.bufferFactory.createUniformBuffer(this._previousModelMatrix, usage);
+        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._materialBuffer = framework.bufferFactory.createUniformBuffer(this._materialData, usage);
-        this._pipeline = framework.renderPipelineFactory.createUnlitRenderPipeline(
+        this._primitiveState = config?.primitiveState;
+        // The pipeline is created once a model buffer is assigned (see modelBuffer).
+    }
+
+    /** Creates the pipeline with the current bindings. */
+    private _createPipeline(modelBuffer: IUniformBuffer): IUnlitRenderPipeline {
+        const pipeline = this._framework.renderPipelineFactory.createUnlitRenderPipeline(
             this._projectionViewBuffer,
-            this._modelBuffer,
+            modelBuffer,
             this._materialBuffer,
-            config?.primitiveState
+            this._primitiveState
         );
+        if (this._pendingTexture) {
+            pipeline.diffuseTexture = this._pendingTexture;
+        }
+        if (this._samplerSet) {
+            pipeline.diffuseTextureSampler = this._pendingSampler;
+        }
+        this._pipeline = pipeline;
+        return pipeline;
+    }
+
+    /**
+     * The camera. Setting it binds the camera's projection view buffer to the pipeline
+     * (the material's own placeholder buffer is disposed). Setting undefined keeps the last bound buffer.
+     */
+    public get camera(): ICamera | undefined {
+        return this._camera;
+    }
+
+    /** @inheritDoc */
+    public set camera(camera: ICamera | undefined) {
+        if (camera === this._camera) {
+            return;
+        }
+        this._camera = camera;
+        if (!camera) {
+            return;
+        }
+        if (this._ownsProjectionViewBuffer) {
+            this._projectionViewBuffer.dispose();
+            this._ownsProjectionViewBuffer = false;
+        }
+        this._projectionViewBuffer = camera.projectionViewBuffer;
+        if (this._pipeline) {
+            this._pipeline.projectionViewBuffer = this._projectionViewBuffer;
+        }
     }
 
     /**
@@ -70,34 +119,60 @@ export class UnlitMaterial {
      * The texture to inspect.
      */
     public get diffuseTexture(): ITexture2D {
-        return this._pipeline.diffuseTexture;
+        return this._pipeline?.diffuseTexture ?? this._pendingTexture!;
     }
 
     /**
      * The texture to inspect.
      */
     public set diffuseTexture(value: ITexture2D) {
-        this._pipeline.diffuseTexture = value;
+        this._pendingTexture = value;
+        if (this._pipeline) {
+            this._pipeline.diffuseTexture = value;
+        }
     }
 
     /**
      * The texture sampler.
      */
     public get diffuseTextureSampler(): ISampler | undefined {
-        return this._pipeline.diffuseTextureSampler;
+        return this._pipeline ? this._pipeline.diffuseTextureSampler : this._pendingSampler;
     }
 
     /**
      * The texture sampler.
      */
     public set diffuseTextureSampler(value: ISampler | undefined) {
-        this._pipeline.diffuseTextureSampler = value;
+        this._pendingSampler = value;
+        this._samplerSet = true;
+        if (this._pipeline) {
+            this._pipeline.diffuseTextureSampler = value;
+        }
     }
 
     /**
-     * The model matrix.
+     * The model buffer (std140 `mat4`). Owned by the mesh, which assigns it before drawing; never disposed by this material.
+     * Undefined until assigned: rendering without one throws.
      */
-    public modelMatrix: mat4 = mat4.create();
+    public get modelBuffer(): IUniformBuffer | undefined {
+        return this._modelBuffer;
+    }
+
+    /** Binds the model buffer to the pipeline. */
+    public set modelBuffer(value: IUniformBuffer | undefined) {
+        if (value === this._modelBuffer) {
+            return;
+        }
+        this._modelBuffer = value;
+        if (!value) {
+            return;
+        }
+        if (this._pipeline) {
+            this._pipeline.modelBuffer = value;
+        } else {
+            this._createPipeline(value);
+        }
+    }
 
     /**
      * The geometry format.
@@ -114,30 +189,28 @@ export class UnlitMaterial {
             this._materialData[3] = this._color.a;
             this._materialBuffer.update(this._materialData);
         }
-
-        if (!mat4.equals(this._previousModelMatrix, this.modelMatrix)) {
-            mat4.copy(this._previousModelMatrix, this.modelMatrix);
-            this._modelBuffer.update(this._previousModelMatrix);
-        }
     }
 
     /** @inheritDoc */
-    public renderMesh(mesh: IMesh): void {
-        this.render(mesh.vertexBuffer!, mesh.indexBuffer!);
+    public renderMesh(mesh: IRenderableMesh): void {
+        this.render(mesh.vertexBuffer!, mesh.indexBuffer!, mesh.indexCount ?? -1, mesh.indexStart ?? 0);
     }
 
     /** @inheritDoc */
-    public render(vertexBuffer: IVertexBuffer, indexBuffer: IIndexBuffer): void {
-        this._pipeline.render(vertexBuffer, indexBuffer);
+    public render(vertexBuffer: IVertexBuffer, indexBuffer: IIndexBuffer, indicesCount?: number, indicesOffset?: number): void {
+        if (!this._modelBuffer) {
+            throw new Error("UnlitMaterial: no modelBuffer. Render it through a mesh (the mesh assigns its model buffer) or set material.modelBuffer.");
+        }
+        (this._pipeline ?? this._createPipeline(this._modelBuffer)).render(vertexBuffer, indexBuffer, indicesCount, indicesOffset);
     }
 
     /** @inheritDoc */
     public dispose(): void {
-        this._pipeline.dispose();
+        this._pipeline?.dispose();
+        this._pipeline = undefined;
         if (this._ownsProjectionViewBuffer) {
             this._projectionViewBuffer.dispose();
         }
-        this._modelBuffer.dispose();
         this._materialBuffer.dispose();
     }
 }

package/src/api/material/_export.ts

@@ -2,4 +2,8 @@ export * from "./IMaterial.ts"
 export * from "./IMaterialFactory.ts"
 export * from "./InspectTextureMipsMaterial.ts"
 export * from "./MaterialFactory.ts"
-export * from "./UnlitMaterial.ts"
+export * from "./SpriteMaterial.ts"
+export * from "./UnlitMaterial.ts"
+export * from "./ForwardBlinnPhongMaterial.ts"
+export * from "./ICameraMaterial.ts"
+export * from "./ILightsMaterial.ts"

package/src/api/meshes/IMesh.ts

@@ -1,20 +1,54 @@
 import type { IVertexBuffer } from "../rendering/buffers/IVertexBuffer.ts";
 import type { IDisposable } from "../core/IDisposable.ts";
 import type { IIndexBuffer } from "../rendering/buffers/IIndexBuffer.ts";
+import type { IGeometry } from "../geometry/IGeometry.ts";
+import type { GeometryFormat } from "../geometry/GeometryFormat.ts";
+import type { State } from "../data/State.ts";
 
 /**
- * The mesh interface.
+ * A mesh: geometry and the vertex and index buffers created from it.
+ * It has no material and no transform; see {@link IRenderableMesh} for a mesh that can be drawn.
+ * @public
  */
 export interface IMesh extends IDisposable {
 
-    /**
-     * The positions buffer.
-     */
+    /** The state of the mesh. */
+    readonly state: State;
+
+    /** The positions, when set through `setMesh`. */
+    readonly positions?: number[];
+
+    /** The colors, when set through `setMesh`. */
+    readonly colors?: number[];
+
+    /** The texture coordinates, when set through `setMesh`. */
+    readonly textureCoords?: number[];
+
+    /** The normals, when set through `setMesh`. */
+    readonly normals?: number[];
+
+    /** The indices, when set through `setMesh`. */
+    readonly indices?: number[];
+
+    /** The geometry the buffers were created from with `setGeometry`, if any. */
+    readonly geometry?: IGeometry;
+
+    /** The vertex buffer, if created. */
     readonly vertexBuffer?: IVertexBuffer;
 
+    /** The index buffer, if created. */
+    readonly indexBuffer?: IIndexBuffer;
+
+    /** Creates the buffers from the current data. */
+    initialize(): void;
+
     /**
-     * The indices buffer.
+     * Creates the vertex and index buffers from a geometry.
+     * @param geometry The geometry.
+     * @param geometryFormat The vertex layout.
      */
-    readonly indexBuffer?: IIndexBuffer;
+    setGeometry(geometry: IGeometry, geometryFormat?: GeometryFormat): void;
 
+    /** Re-creates (or updates) the buffers from the current data. */
+    applyChanges(): void;
 }

package/src/api/meshes/IMeshFactory.ts

@@ -1,8 +1,20 @@
+import type { GeometryFormat } from "../geometry/GeometryFormat.ts";
 import type { IGeometry } from "../geometry/IGeometry.ts";
-import {GeometryFormat} from "../geometry/GeometryFormat.ts";
 import {QuadMesh} from "./QuadMesh.ts";
 import {vec2} from "gl-matrix";
 import type { IMesh } from "./IMesh.ts";
+import type { IMaterial } from "../material/IMaterial.ts";
+import type { IRenderableMesh } from "./IRenderableMesh.ts";
+
+/** Describes one submesh: a material and the index range it draws. */
+export interface SubMeshDescriptor {
+    /** The material. */
+    readonly material: IMaterial;
+    /** The first index of the range. */
+    readonly indexStart: number;
+    /** The number of indices in the range. */
+    readonly indexCount: number;
+}
 
 /**
  * The mesh factory.
@@ -10,12 +22,29 @@ import type { IMesh } from "./IMesh.ts";
 export interface IMeshFactory {
 
     /**
-     * Creates a mesh.
+     * Creates a plain mesh (buffers only, no material or transform) from a geometry.
+     * @param geometry - The geometry.
+     * @param geometryFormat - The vertex layout.
+     * @returns The mesh.
+     */
+    createMesh(geometry: IGeometry, geometryFormat: GeometryFormat): IMesh;
+
+    /**
+     * Creates a renderable mesh with one material. Add it to a scene with `scene.add(mesh)`.
+     * @param geometry - The geometry.
+     * @param material - The material.
+     * @returns The mesh.
+     */
+    create(geometry: IGeometry, material: IMaterial): IRenderableMesh;
+
+    /**
+     * Creates a mesh made of submeshes that share one vertex and one index buffer.
+     * The root mesh has no material; `mesh.render()` draws its submeshes. Add the root to a scene with `scene.add(mesh)`.
      * @param geometry - The geometry.
-     * @param geometryFormat - The geometry format.
+     * @param subMeshes - One entry per submesh. All materials must use the same geometry format.
      * @returns The mesh.
      */
-    create(geometry: IGeometry, geometryFormat: GeometryFormat): IMesh;
+    createWithSubMeshes(geometry: IGeometry, subMeshes: SubMeshDescriptor[]): IRenderableMesh;
 
     /**
      * Creates the quad mesh.

package/src/api/meshes/IRenderableMesh.ts

@@ -0,0 +1,58 @@
+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";
+
+/**
+ * A mesh that can be drawn: a mesh plus an optional material, an index range and sub meshes.
+ *
+ * - A root mesh owns the vertex and index buffers. Sub meshes share them and only store their index range.
+ * - Rendering: a mesh with a material draws its range, then its sub meshes draw theirs.
+ *   A root without a material only draws its sub meshes.
+ * - The transform (position, rotation, scale) and the model buffer live on the root and are shared by all sub meshes,
+ *   so a mesh uploads its model matrix once per change, whatever the number of materials.
+ * - Disposing the root disposes the sub meshes and the buffers once. Materials are not disposed by the mesh
+ *   (a `SceneMesh` does that).
+ * @public
+ */
+export interface IRenderableMesh extends IMesh {
+
+    /** The material, if any. A root mesh made only of sub meshes has none. */
+    material?: IMaterial;
+
+    /** The parent for a sub mesh; undefined for a root mesh. */
+    readonly parent?: IRenderableMesh;
+
+    /** The sub meshes. */
+    readonly subMeshes: readonly IRenderableMesh[];
+
+    /** First index of the range to draw. Defaults to 0. */
+    readonly indexStart: number;
+
+    /** 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),
+     * uploaded when the transform changed and assigned to the material(s) before drawing. Created on first use.
+     */
+    readonly modelBuffer: IUniformBuffer;
+
+    /** Draws the mesh's range with its material (if any), then the sub meshes. */
+    render(): void;
+}