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

package/src/api/loaders/obj/{ObjLoader.ts → ObjParser.ts}

@@ -3,6 +3,7 @@ import {
     type ObjColor,
     type ObjLoadResult,
     type ObjLoadOptions,
+    type ObjModel,
     type ObjMaterialRange,
 } from "./ObjTypes.ts";
 
@@ -22,10 +23,11 @@ function readColor(parts: string[]): ObjColor | undefined {
 }
 
 /**
- * Loads .obj models (and their .mtl materials) from text or a URL into plain data.
- * Engine-independent; uses only `fetch` and `URL`. `content.loadMeshAsync` turns the result into a framework mesh.
+ * Parses .obj models (and their .mtl materials) from text or a URL into plain data.
+ * Engine-independent; uses only `fetch` and `URL`, and creates no GPU resources.
+ * `framework.objLoader` (or the static `ObjLoader.parseAsync`) builds on it.
  */
-export class ObjLoader {
+export class ObjParser {
 
     /**
      * Parses .mtl text.
@@ -260,11 +262,40 @@ export class ObjLoader {
                 }
                 materials.push(...this.parseMtl(await mtlResponse.text()));
             } catch (error) {
-                console.warn(`ObjLoader: could not load material library '${library}'.`, error);
+                console.warn(`ObjParser: could not load material library '${library}'.`, error);
             }
         }
 
 
         return this.fromText(text, materials);
     }
+
+    /**
+     * Loads an .obj file (and its .mtl files) into an {@link ObjModel}: the geometry plus one sub mesh per `usemtl`
+     * range with its resolved material definition.
+     * @param filePath The .obj URL.
+     * @param options Optional: how to resolve `mtllib` names, or skip materials.
+     * @returns The model.
+     */
+    public async parseAsync(filePath: string, options?: ObjLoadOptions): Promise<ObjModel> {
+        return ObjParser.toModel(await this.loadAsync(filePath, options));
+    }
+
+    /**
+     * Turns a load result into an {@link ObjModel}.
+     * @param result The load result.
+     * @returns The model.
+     */
+    public static toModel(result: ObjLoadResult): ObjModel {
+        const byName = new Map(result.materials.map(m => [m.name, m]));
+        return {
+            ...result,
+            subMeshes: result.geometry.materialRanges.map(range => ({
+                materialName: range.materialName,
+                material: range.materialName === undefined ? undefined : byName.get(range.materialName),
+                indexStart: range.indexStart,
+                indexCount: range.indexCount,
+            })),
+        };
+    }
 }

package/src/api/loaders/obj/ObjTypes.ts

@@ -111,7 +111,7 @@ export interface ObjLoadResult {
     readonly raw: ObjRawData;
 }
 
-/** Options for {@link ObjLoader.loadAsync}. */
+/** Options for {@link ObjParser.loadAsync} and `ObjLoader.loadAsync`. */
 export interface ObjLoadOptions {
     /**
      * Maps an `mtllib` name to the URL to fetch.
@@ -122,3 +122,21 @@ export interface ObjLoadOptions {
     /** Skip fetching .mtl files. */
     ignoreMaterials?: boolean;
 }
+
+/** One `usemtl` range of an {@link ObjModel}: its index range and resolved material definition. */
+export interface ObjSubMesh {
+    /** The material name from `usemtl`, or undefined for faces before any `usemtl`. */
+    readonly materialName?: string;
+    /** The material definition from the .mtl files, or undefined when there is none. */
+    readonly material?: ObjMaterialDefinition;
+    /** First index in `geometry.indices`. */
+    readonly indexStart: number;
+    /** Number of indices. */
+    readonly indexCount: number;
+}
+
+/** A parsed OBJ model (C# `ObjModel`): geometry, sub meshes and material definitions. No GPU resources. */
+export interface ObjModel extends ObjLoadResult {
+    /** One entry per `usemtl` range, in file order. */
+    readonly subMeshes: ObjSubMesh[];
+}

package/src/api/loaders/obj/index.ts

@@ -2,4 +2,4 @@
  * OBJ/MTL loader. Self-contained: no imports outside this folder.
  */
 export * from "./ObjTypes.ts";
-export * from "./ObjLoader.ts";
+export * from "./ObjParser.ts";

package/src/api/material/ForwardBlinnPhongMaterial.ts

@@ -1,4 +1,4 @@
-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 {GeometryFormat} from "../geometry/GeometryFormat.ts";
@@ -11,6 +11,11 @@ import {Color} from "../data/Color.ts";
 import type {IPrimitiveState} from "../rendering/primitive/IPrimitiveState.ts";
 import type {ICamera} from "../camera/ICamera.ts";
 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 {ILightsMaterial} from "./ILightsMaterial.ts";
 import type {IForwardBlinnPhongRenderPipeline} from "../rendering/render-pipelines/IForwardBlinnPhongRenderPipeline.ts";
 
 /**
@@ -27,9 +32,6 @@ export class ForwardBlinnPhongMaterialDescriptor {
 
     /** The camera position buffer. */
     public cameraPositionBuffer!: IUniformBuffer;
-
-    /** The lights buffer. The shader is compiled for its light counts. Can also be set later through `material.lightsBuffer`. */
-    public lightsBuffer?: LightsBuffer;
 }
 
 
@@ -37,11 +39,17 @@ export class ForwardBlinnPhongMaterialDescriptor {
  * The Blinn-Phong material with forward calculated lighting.
  * @public
  */
-export class ForwardBlinnPhongMaterial {
+export class ForwardBlinnPhongMaterial implements ICameraMaterial, ILightsMaterial {
+
+    /** The directional light slots of the material's lights buffer and shader. */
+    public static readonly MAX_DIRECTIONAL_LIGHTS = 3;
+
+    /** The point light slots of the material's lights buffer and shader. */
+    public static readonly MAX_POINT_LIGHTS = 5;
 
     private readonly _framework: IFramework;
 
-    private _lightsBuffer?: LightsBuffer;
+    private readonly _lightsBuffer: LightsBuffer;
     private _diffuseColorCache: Color;
     private _ambientColorCache: Color;
     private _specularColorCache: Color;
@@ -94,7 +102,11 @@ export class ForwardBlinnPhongMaterial {
         this._cameraPositionBuffer = descriptor.cameraPositionBuffer;
         this._materialBuffer = framework.bufferFactory.createUniformBuffer(this._materialData, usage);
         this._primitiveState = descriptor.primitiveState;
-        this._lightsBuffer = descriptor.lightsBuffer;
+        // Owned by the material, like C#: 3 directional + 5 point slots (88 floats), uploaded only when the lights changed.
+        this._lightsBuffer = framework.lightsFactory.__createLightsBuffer({
+            maxDirectionalLights: ForwardBlinnPhongMaterial.MAX_DIRECTIONAL_LIGHTS,
+            maxPointLights: ForwardBlinnPhongMaterial.MAX_POINT_LIGHTS,
+        });
         // The pipeline is created once a model buffer is assigned (see modelBuffer).
     }
 
@@ -105,9 +117,9 @@ export class ForwardBlinnPhongMaterial {
             modelBuffer,
             materialBuffer: this._materialBuffer,
             cameraPositionBuffer: this._cameraPositionBuffer,
-            lightsBuffer: this._lightsBuffer?.buffer,
-            maxDirectionalLights: this._lightsBuffer?.maxDirectionalLights,
-            maxPointLights: this._lightsBuffer?.maxPointLights,
+            lightsBuffer: this._lightsBuffer.buffer,
+            maxDirectionalLights: this._lightsBuffer.maxDirectionalLights,
+            maxPointLights: this._lightsBuffer.maxPointLights,
             primitiveState: this._primitiveState,
         });
         if (this._pendingTexture) {
@@ -175,19 +187,31 @@ export class ForwardBlinnPhongMaterial {
         }
     }
 
-    /** The lights buffer with the scene's lights. Shared, not disposed by this material. */
-    public get lightsBuffer(): LightsBuffer | undefined {
-        return this._lightsBuffer;
+    /** @inheritDoc Defaults to a black ambient light; a `Scene` assigns its active ambient light. */
+    public get ambientLight(): AmbientLight {
+        return this._lightsBuffer.ambientLight;
     }
 
-    /** The lights buffer with the scene's lights. Shared, not disposed by this material. */
-    public set lightsBuffer(lightsBuffer: LightsBuffer | undefined) {
-        this._lightsBuffer = lightsBuffer;
-        if (lightsBuffer && this._pipeline) {
-            // Switches to the shader variant for this buffer's light counts when they differ.
-            this._pipeline.setLightCounts(lightsBuffer.maxDirectionalLights, lightsBuffer.maxPointLights);
-            this._pipeline.lightsBuffer = lightsBuffer.buffer;
-        }
+    public set ambientLight(value: AmbientLight) {
+        this._lightsBuffer.ambientLight = value;
+    }
+
+    /** @inheritDoc Only the first 3 are used. A `Scene` assigns its own list. */
+    public get directionalLights(): DirectionalLight[] {
+        return this._lightsBuffer.directionalLights;
+    }
+
+    public set directionalLights(value: DirectionalLight[]) {
+        this._lightsBuffer.directionalLights = value;
+    }
+
+    /** @inheritDoc Only the first 5 are used. A `Scene` assigns its own list. */
+    public get pointLights(): PointLight[] {
+        return this._lightsBuffer.pointLights;
+    }
+
+    public set pointLights(value: PointLight[]) {
+        this._lightsBuffer.pointLights = value;
     }
 
     /**
@@ -256,6 +280,7 @@ export class ForwardBlinnPhongMaterial {
 
     /** @inheritDoc */
     public beforeRender(): void {
+        this._lightsBuffer.update();
 
 
         if (!this._diffuseColorCache.equals(this.diffuseColor)
@@ -281,7 +306,7 @@ export class ForwardBlinnPhongMaterial {
     }
 
     /** @inheritDoc */
-    public renderMesh(mesh: IMesh): void {
+    public renderMesh(mesh: IRenderableMesh): void {
         this.render(mesh.vertexBuffer!, mesh.indexBuffer!, mesh.indexCount ?? -1, mesh.indexStart ?? 0);
     }
 
@@ -298,5 +323,6 @@ export class ForwardBlinnPhongMaterial {
         this._pipeline?.dispose();
         this._pipeline = undefined;
         this._materialBuffer.dispose();
+        this._lightsBuffer.dispose();
     }
 }

package/src/api/material/ICameraMaterial.ts

@@ -0,0 +1,22 @@
+import type { IMaterial } from "./IMaterial.ts";
+import type { ICamera } from "../camera/ICamera.ts";
+
+/**
+ * A material that renders with a camera (unlit, Blinn-Phong, inspect mips).
+ * A `Scene` assigns its camera to these materials in `scene.update()`.
+ * @public
+ */
+export interface ICameraMaterial extends IMaterial {
+
+    /** The camera. Setting it binds the camera's buffers. */
+    camera?: ICamera;
+}
+
+/**
+ * Whether a material is an {@link ICameraMaterial}.
+ * @param material The material.
+ * @public
+ */
+export function isCameraMaterial(material: IMaterial | undefined): material is ICameraMaterial {
+    return !!material && "camera" in material;
+}

package/src/api/material/ILightsMaterial.ts

@@ -0,0 +1,32 @@
+import type { IMaterial } from "./IMaterial.ts";
+import type { AmbientLight } from "../lights/AmbientLight.ts";
+import type { DirectionalLight } from "../lights/DirectionalLight.ts";
+import type { PointLight } from "../lights/PointLight.ts";
+
+/**
+ * A material lit by an ambient light, directional lights and point lights (Blinn-Phong).
+ * The material owns its lights buffer and uploads it only when the lights changed.
+ * A `Scene` hands each lights material its active ambient light and its own light lists (the same arrays, not copies)
+ * in `scene.update()`, so lights added to the scene reach every lit material.
+ * @public
+ */
+export interface ILightsMaterial extends IMaterial {
+
+    /** The ambient light. */
+    ambientLight: AmbientLight;
+
+    /** The directional lights. The list is used by reference and may be edited; extra lights beyond the slots are ignored. */
+    directionalLights: DirectionalLight[];
+
+    /** The point lights. The list is used by reference and may be edited; extra lights beyond the slots are ignored. */
+    pointLights: PointLight[];
+}
+
+/**
+ * Whether a material is an {@link ILightsMaterial}.
+ * @param material The material.
+ * @public
+ */
+export function isLightsMaterial(material: IMaterial | undefined): material is ILightsMaterial {
+    return !!material && "directionalLights" in material && "pointLights" in material && "ambientLight" in material;
+}

package/src/api/material/IMaterial.ts

@@ -1,9 +1,8 @@
 import type { IDisposable } from "../core/IDisposable.ts";
 import {GeometryFormat} from "../geometry/GeometryFormat.ts";
-import type { IMesh } from "../meshes/IMesh.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 { ICamera } from "../camera/ICamera.ts";
 import type { IUniformBuffer } from "../rendering/buffers/IUniformBuffer.ts";
 
 /**
@@ -12,12 +11,6 @@ import type { IUniformBuffer } from "../rendering/buffers/IUniformBuffer.ts";
  */
 export interface IMaterial extends IDisposable {
 
-    /**
-     * The camera this material renders with, for materials that use one (unlit, Blinn-Phong).
-     * A `Scene` assigns its camera to the materials of its meshes in `scene.update()`.
-     */
-    camera?: ICamera;
-
     /**
      * The model buffer (std140 `mat4`) for materials that use one (unlit, Blinn-Phong, inspect mips).
      * A mesh owns it and assigns it before drawing, like the scene assigns its camera; materials never dispose it.
@@ -37,7 +30,7 @@ export interface IMaterial extends IDisposable {
      * Renders the mesh with this material, honouring the mesh's index range.
      * @param mesh - The mesh.
      */
-    renderMesh(mesh: IMesh): void;
+    renderMesh(mesh: IRenderableMesh): void;
 
     /**
      * Renders the material.

package/src/api/material/InspectTextureMipsMaterial.ts

@@ -1,4 +1,4 @@
-import type { IMesh } from "../meshes/IMesh.ts";
+import type {IRenderableMesh} from "../meshes/IRenderableMesh.ts";
 import type { ITexture2D } from "../rendering/texture/ITexture2D.ts";
 import type { IInspectTextureMipsRenderPipeline } from "../rendering/render-pipelines/IInspectTextureMipsRenderPipeline.ts";
 import type { ISampler } from "../rendering/sampler/ISampler.ts";
@@ -130,7 +130,7 @@ export class InspectTextureMipsMaterial {
     }
 
     /** @inheritDoc */
-    public renderMesh(mesh: IMesh): void {
+    public renderMesh(mesh: IRenderableMesh): void {
         this.render(mesh.vertexBuffer!, mesh.indexBuffer!, mesh.indexCount ?? -1, mesh.indexStart ?? 0);
     }
 

package/src/api/material/SpriteMaterial.ts

@@ -1,5 +1,5 @@
 import type { GeometryFormat } from "../geometry/GeometryFormat.ts";
-import type { IMesh } from "../meshes/IMesh.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";
@@ -61,7 +61,7 @@ export class SpriteMaterial implements IMaterial {
     }
 
     /** @inheritDoc */
-    public renderMesh(mesh: IMesh): void {
+    public renderMesh(mesh: IRenderableMesh): void {
         this.render(mesh.vertexBuffer!, mesh.indexBuffer!, mesh.indexCount ?? -1, mesh.indexStart ?? 0);
     }
 

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";
@@ -28,7 +29,7 @@ export class UnlitMaterialDescriptor {
 /**
  * Unlit material.
  */
-export class UnlitMaterial {
+export class UnlitMaterial implements ICameraMaterial {
 
     private readonly _framework: IFramework;
     private _color = Color.white();
@@ -191,7 +192,7 @@ export class UnlitMaterial {
     }
 
     /** @inheritDoc */
-    public renderMesh(mesh: IMesh): void {
+    public renderMesh(mesh: IRenderableMesh): void {
         this.render(mesh.vertexBuffer!, mesh.indexBuffer!, mesh.indexCount ?? -1, mesh.indexStart ?? 0);
     }
 

package/src/api/material/_export.ts

@@ -5,3 +5,5 @@ export * from "./MaterialFactory.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,59 +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 { IMaterial } from "../material/IMaterial.ts";
-import type { mat4, vec3 } from "gl-matrix";
-import type { IUniformBuffer } from "../rendering/buffers/IUniformBuffer.ts";
+import type { IGeometry } from "../geometry/IGeometry.ts";
+import type { GeometryFormat } from "../geometry/GeometryFormat.ts";
+import type { State } from "../data/State.ts";
 
 /**
- * Represents a mesh containing geometry, material information, and optionally child submeshes.
- * A mesh may contain vertex and index buffers directly, or act as a container for submeshes.
+ * 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 vertex buffer containing the mesh's vertex data, if any. */
-    readonly vertexBuffer?: IVertexBuffer;
+    /** The state of the mesh. */
+    readonly state: State;
 
-    /** The index buffer containing the mesh's index data, if any. */
-    readonly indexBuffer?: IIndexBuffer;
+    /** The positions, when set through `setMesh`. */
+    readonly positions?: number[];
 
-    /** The material assigned to this mesh, if any. */
-    material?: IMaterial;
+    /** The colors, when set through `setMesh`. */
+    readonly colors?: number[];
 
-    /** First index in {@link indexBuffer} to draw. Undefined draws from 0. */
-    readonly indexStart?: number;
+    /** The texture coordinates, when set through `setMesh`. */
+    readonly textureCoords?: number[];
 
-    /** Number of indices to draw. Undefined draws the whole index buffer. */
-    readonly indexCount?: number;
+    /** The normals, when set through `setMesh`. */
+    readonly normals?: number[];
 
-    /** The child submeshes contained in this mesh, if any. */
-    readonly subMeshes?: IMesh[];
+    /** The indices, when set through `setMesh`. */
+    readonly indices?: number[];
 
-    /** World position. Defaults to the origin. In-place edits are detected. */
-    position: vec3;
+    /** The geometry the buffers were created from with `setGeometry`, if any. */
+    readonly geometry?: IGeometry;
 
-    /**
-     * 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.
-     */
-    rotation: vec3;
+    /** The vertex buffer, if created. */
+    readonly vertexBuffer?: IVertexBuffer;
 
-    /** Scale. Defaults to (1, 1, 1). In-place edits are detected. */
-    scale: vec3;
+    /** The index buffer, if created. */
+    readonly indexBuffer?: IIndexBuffer;
 
-    /**
-     * The model matrix `T * R * S`, recomputed only when position, rotation or scale changed.
-     */
-    readonly modelMatrix: mat4;
+    /** Creates the buffers from the current data. */
+    initialize(): void;
 
     /**
-     * The model buffer (std140 `mat4`) holding {@link modelMatrix}. Owned by the mesh (submeshes share the parent's),
-     * uploaded when the transform changed and assigned to the material(s) before drawing.
-     * Created on first use.
+     * Creates the vertex and index buffers from a geometry.
+     * @param geometry The geometry.
+     * @param geometryFormat The vertex layout.
      */
-    readonly modelBuffer: IUniformBuffer;
+    setGeometry(geometry: IGeometry, geometryFormat?: GeometryFormat): void;
 
-    /** Render the mesh. */
-    render(): void;
-}
+    /** Re-creates (or updates) the buffers from the current data. */
+    applyChanges(): void;
+}

package/src/api/meshes/IMeshFactory.ts

@@ -1,9 +1,10 @@
+import type { GeometryFormat } from "../geometry/GeometryFormat.ts";
 import type { IGeometry } from "../geometry/IGeometry.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 { Scene } from "../scene/Scene.ts";
+import type { IRenderableMesh } from "./IRenderableMesh.ts";
 
 /** Describes one submesh: a material and the index range it draws. */
 export interface SubMeshDescriptor {
@@ -21,24 +22,29 @@ export interface SubMeshDescriptor {
 export interface IMeshFactory {
 
     /**
-     * Creates a mesh and adds it to the scene.
-     * @param scene - The scene the mesh adds itself to.
+     * 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(scene: Scene, geometry: IGeometry, material: IMaterial): IMesh;
+    create(geometry: IGeometry, material: IMaterial): IRenderableMesh;
 
     /**
      * Creates a mesh made of submeshes that share one vertex and one index buffer.
-     * The mesh itself has no material; `scene.render()` (or `mesh.render()`) draws its submeshes.
-     * Only the mesh is added to the scene, not the submeshes.
-     * @param scene - The scene the mesh adds itself to.
+     * 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 subMeshes - One entry per submesh. All materials must use the same geometry format.
      * @returns The mesh.
      */
-    createWithSubMeshes(scene: Scene, geometry: IGeometry, subMeshes: SubMeshDescriptor[]): 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;
+}