melonjs 19.9.1 → 20.1.0

package/build/renderable/instanced_mesh.d.ts

@@ -0,0 +1,286 @@
+/**
+ * A {@link Mesh} drawn many times from one copy of its geometry.
+ *
+ * Ordinary meshes pay for every repeat: a forest of five thousand trees is
+ * five thousand geometries on the GPU, each re-uploaded when it changes. An
+ * `InstancedMesh` uploads the geometry **once** and stamps out copies from a
+ * small per-instance record, so cost scales with the number of instances
+ * rather than with `instances × vertices`, and the whole thing draws in a
+ * single call.
+ *
+ * Every `Mesh` setting works unchanged — `model` + `material` from an OBJ,
+ * raw `vertices`/`uvs`/`indices`, `lit`, `cullBackFaces`, `rightHanded`,
+ * `tint`, `textureRepeat`, the lot. What an instanced mesh adds is the
+ * instance buffer:
+ *
+ * - a **transform** per instance, always present;
+ * - a **colour** per instance, when `instanceColors` is declared, multiplied
+ *   into the mesh tint;
+ * - an opaque **`vec4`** per instance, when `instanceData` is declared. The
+ *   built-in lit shading reads its `rgb` as emissive; a custom
+ *   {@link Mesh#shader} may read it as a wind phase, an atlas offset, a
+ *   random seed — whatever the shader wants.
+ *
+ * The mesh's own position, rotation and scale keep their ordinary meaning and
+ * act as the **group** transform: moving an `InstancedMesh` moves every
+ * instance with one uniform write and re-uploads nothing.
+ *
+ * Requires a GPU backend (`renderer.supportsInstancing`). Under the Canvas
+ * renderer the instances are drawn one at a time through the ordinary CPU
+ * mesh path — correct, but without any of the benefit.
+ * @augments Mesh
+ * @category Rendering
+ * @example
+ * const forest = new me.InstancedMesh(0, 0, {
+ *     model: "tree",
+ *     material: "tree",
+ *     width: 64,
+ *     lit: true,
+ *     instanceCount: 5000,     // pre-allocate
+ *     instanceColors: true,
+ *     instanceData: true,
+ * });
+ *
+ * const placement = new me.Matrix3d();   // one scratch — zero allocation
+ * for (let i = 0; i < forest.instanceCount; i++) {
+ *     placement.identity().translate(x, y, z).scale(s);
+ *     forest.setInstance(i, placement);
+ *     forest.setInstanceColor(i, autumnTint);
+ *     forest.setInstanceData(i, windPhase, seed, 0, 0);
+ * }
+ *
+ * // draw only the nearest 1200 — no re-upload, just a smaller draw
+ * forest.visibleInstanceCount = 1200;
+ * app.world.addChild(forest, 10);
+ */
+export default class InstancedMesh extends Mesh {
+    /**
+     * @param {number} x - the x coordinate of the group origin
+     * @param {number} y - the y coordinate of the group origin
+     * @param {object} settings - every {@link Mesh} setting, plus those below
+     * @param {number} [settings.instanceCount=0] - number of instances to pre-allocate. Instances start at the group origin (identity transform) until placed; `addInstance` grows past this.
+     * @param {boolean} [settings.instanceColors=false] - give each instance its own colour (16 bytes per instance), multiplied into the mesh tint
+     * @param {boolean} [settings.instanceData=false] - give each instance an opaque `vec4` (16 bytes per instance). Read as emissive by the built-in lit shading, or as anything at all by a custom mesh shader.
+     */
+    constructor(x: number, y: number, settings: {
+        instanceCount?: number | undefined;
+        instanceColors?: boolean | undefined;
+        instanceData?: boolean | undefined;
+    });
+    /**
+     * How this mesh's per-instance records are laid out — record width and
+     * the offset of each opt-in slot. Consumed by the batchers to describe
+     * the instance vertex buffer.
+     * @type {object}
+     * @ignore
+     */
+    instanceLayout: object;
+    /**
+     * The packed instance records, `instanceLayout.floats` per instance.
+     * Editable in place for bulk updates — announce those with
+     * {@link InstancedMesh#needsInstanceUpdate} or
+     * {@link InstancedMesh#markInstancesDirty}, since writing here bypasses
+     * the setters that track the dirty range.
+     * @type {Float32Array}
+     */
+    instanceBuffer: Float32Array;
+    /**
+     * bumped whenever the buffer is reallocated, so a renderer holding a
+     * GPU copy knows its capacity assumption is stale
+     * @type {number}
+     * @ignore
+     */
+    _instanceVersion: number;
+    /** @ignore */
+    _instanceRevision: number;
+    /** @ignore */
+    _spanFromRevision: number;
+    /** @ignore */
+    _dirtyFirst: number;
+    /** @ignore */
+    _dirtyLast: number;
+    /** @ignore */
+    _instanceCount: number;
+    /** @ignore */
+    _visibleInstanceCount: number;
+    /** @ignore */
+    _cullRevision: number;
+    set instanceCount(count: number);
+    /**
+     * How many instances this mesh holds.
+     *
+     * Growing pre-allocates the new records as identity transforms (an
+     * unplaced instance sits at the group origin rather than collapsing onto
+     * a zero matrix); shrinking keeps the allocation, so a count that
+     * oscillates does not thrash it.
+     * @type {number}
+     */
+    get instanceCount(): number;
+    set visibleInstanceCount(count: number);
+    /**
+     * How many instances are actually drawn, counted from the first.
+     *
+     * The cheap culling and level-of-detail knob: sort the instances by
+     * distance once, then draw fewer of them by moving this single number —
+     * no re-upload, no rebuild. Defaults to every instance (`-1`).
+     * @type {number}
+     * @example
+     * forest.visibleInstanceCount = playerIsIndoors ? 0 : 1200;
+     */
+    get visibleInstanceCount(): number;
+    /**
+     * Append an instance, growing the buffer as needed.
+     * @param {Matrix3d} [transform] - where this instance sits, relative to the group. Defaults to the group origin.
+     * @param {object} [options] - optional per-instance slots
+     * @param {Color} [options.color] - instance colour (requires `instanceColors`)
+     * @param {number[]} [options.data] - four numbers for the custom slot (requires `instanceData`)
+     * @returns {number} the new instance's index
+     */
+    addInstance(transform?: Matrix3d, options?: {
+        color?: any;
+        data?: number[] | undefined;
+    }): number;
+    /**
+     * Remove an instance by moving the last one into its place.
+     *
+     * Swapping is what keeps this O(1) instead of shifting every record after
+     * the hole — but it means **indices are not stable across a removal**: the
+     * instance that was last now answers to `index`. Callers holding indices
+     * must re-read them, or avoid removal in favour of
+     * {@link InstancedMesh#visibleInstanceCount}.
+     * @param {number} index - the instance to remove
+     */
+    removeInstance(index: number): void;
+    /**
+     * Place one instance.
+     * @param {number} index - the instance to place
+     * @param {Matrix3d} transform - where it sits, relative to the group
+     */
+    setInstance(index: number, transform: Matrix3d): void;
+    /**
+     * Read one instance's transform back.
+     * @param {number} index - the instance to read
+     * @param {Matrix3d} [out] - matrix to write into; a new one is allocated when omitted
+     * @returns {Matrix3d|undefined} the transform, or `undefined` for an out-of-range index
+     */
+    getInstance(index: number, out?: Matrix3d): Matrix3d | undefined;
+    /**
+     * Set one instance's colour, multiplied into the mesh tint.
+     * @param {number} index - the instance to colour
+     * @param {Color} color - the instance colour
+     */
+    setInstanceColor(index: number, color: Color): void;
+    /**
+     * Set one instance's custom `vec4`.
+     * @param {number} index - the instance to write
+     * @param {number} x - first component (emissive red, under the built-in lit shading)
+     * @param {number} y - second component
+     * @param {number} z - third component
+     * @param {number} [w=0] - fourth component
+     */
+    setInstanceData(index: number, x: number, y: number, z: number, w?: number): void;
+    /**
+     * Announce that a span of instances was edited directly through
+     * {@link InstancedMesh#instanceBuffer}, so the next draw re-uploads it.
+     * The per-instance setters do this themselves.
+     * @param {number} first - first instance changed
+     * @param {number} count - how many
+     */
+    markInstancesDirty(first: number, count: number): void;
+    /**
+     * Announce that the whole instance buffer was edited in place. The
+     * instancing counterpart of {@link Mesh#needsUpdate} — and, like it, a
+     * signal rather than a state, so it is write-only.
+     * @type {boolean}
+     * @example
+     * forest.instanceBuffer.set(myRecords);
+     * forest.needsInstanceUpdate = true;
+     */
+    set needsInstanceUpdate(value: any);
+    /**
+     * The dirty span, in floats, as `[first, lastExclusive)`. Empty when
+     * nothing changed since the last upload.
+     * @returns {number[]} the span
+     * @ignore
+     */
+    dirtyRange(): number[];
+    /**
+     * What one GPU buffer must upload to catch up, given the revision it last
+     * reached. Replaces a shared "clear the dirty flag" step, which the first
+     * consumer would drain out from under the second.
+     * @param {number} uploadedRevision - the revision that buffer holds
+     * @returns {object} `{first, count, full, revision}` — float span, or `full`
+     * @ignore
+     */
+    instanceUpload(uploadedRevision: number): object;
+    /**
+     * Called by the batcher once the dirty span has been uploaded.
+     * @ignore
+     */
+    clearInstanceDirty(): void;
+    /**
+     * The world-space bounding box of every instance, so the whole group
+     * frustum-culls as one object.
+     *
+     * Bounds the prototype geometry through each instance transform and then
+     * through the group placement — correct before the first draw, like the
+     * base implementation, and independent of what any draw left behind.
+     * @returns {AABB3d} the union of all instance bounds (reused instance)
+     */
+    /**
+     * Resize the renderable's own 2D bounds box so it encloses every
+     * instance.
+     *
+     * This is what makes the group frustum-cull correctly. `Camera3d.isVisible`
+     * tests a sphere derived from `getBounds()` — the flat width/height box —
+     * **not** {@link InstancedMesh#getBounds3d}. Left at the prototype's size,
+     * a forest scattered over thousands of units presents a box a few tens of
+     * pixels across at the group origin: pan the camera just past that origin
+     * and every instance disappears at once, while still on screen.
+     * @ignore
+     */
+    _refreshCullVolume(): any;
+    _cullRadius: number | undefined;
+    /**
+     * Draw the instanced mesh. Under a GPU backend this is one instanced
+     * draw call; the Canvas renderer has no instancing, so each instance is
+     * drawn through the ordinary mesh path instead.
+     * @param {CanvasRenderer|WebGLRenderer} renderer - a renderer instance
+     * @param {Camera2d} [viewport] - the camera rendering this frame
+     */
+    draw(renderer: CanvasRenderer | WebGLRenderer, viewport?: Camera2d): void;
+    /**
+     * Fallback for renderers without instancing (Canvas): walk the instances
+     * and draw the prototype once per instance, composing the group and
+     * instance transforms by hand. Correct, and as slow as the uninstanced
+     * scene it replaces — the point is that a scene authored for instancing
+     * still renders everywhere.
+     * @param {CanvasRenderer} renderer - a renderer instance
+     * @param {Camera2d} [viewport] - the camera rendering this frame
+     * @ignore
+     */
+    _drawInstancesIndividually(renderer: CanvasRenderer, viewport?: Camera2d): void;
+    /**
+     * Release the instance records along with the mesh.
+     * @ignore
+     */
+    /**
+     * Draw a ground shadow for every visible instance — one call for the whole
+     * set, over the instance buffer the mesh itself just drew from (#1515).
+     *
+     * The group matrix is passed with its Y basis column zeroed and its
+     * translation Y set to the ground, so whatever Y the shadow vertex stage
+     * produces is flattened onto the floor. That is what lets the ground
+     * height reach the shader without a new uniform.
+     *
+     * One ground height serves the whole set — flat terrain. Per-instance
+     * ground height would have to ride the `instanceData` slot, which the
+     * built-in shading already reads as emissive.
+     * @param {WebGLRenderer} renderer - the active renderer
+     * @ignore
+     */
+    _drawInstancedGroundShadow(renderer: WebGLRenderer): void;
+}
+import Mesh from "./mesh.js";
+import { Matrix3d } from "../math/matrix3d.ts";
+//# sourceMappingURL=instanced_mesh.d.ts.map

package/build/renderable/instanced_mesh.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instanced_mesh.d.ts","sourceRoot":"","sources":["../../src/renderable/instanced_mesh.js"],"names":[],"mappings":"AAsBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH;IACC;;;;;;;OAOG;IACH,eAPW,MAAM,KACN,MAAM,YAEd;QAA0B,aAAa;QACZ,cAAc;QACd,YAAY;KACzC,EAiEA;IA7DA;;;;;;OAMG;IACH,gBAHU,MAAM,CAMf;IAED;;;;;;;OAOG;IACH,gBAFU,YAAY,CAEmB;IAEzC;;;;;OAKG;IACH,kBAHU,MAAM,CAGS;IAUzB,cAAc;IACd,0BAA0B;IAG1B,cAAc;IACd,0BAA0B;IAE1B,cAAc;IACd,oBAA2B;IAC3B,cAAc;IACd,mBAAmB;IAEnB,cAAc;IACd,uBAAuB;IACvB,cAAc;IACd,8BAA+B;IAE/B,cAAc;IACd,sBAAuB;IAoBxB,yBANU,MAAM,EAgDf;IAvDD;;;;;;;;OAQG;IACH,qBAFU,MAAM,CAIf;IA8DD,gCAVU,MAAM,EAiBf;IAvBD;;;;;;;;;OASG;IACH,4BAJU,MAAM,CAQf;IAWD;;;;;;;OAOG;IACH,wBANW,QAAQ,YAEhB;QAAwB,KAAK;QACF,IAAI;KAC/B,GAAU,MAAM,CAqBlB;IAED;;;;;;;;;OASG;IACH,sBAFW,MAAM,QAiBhB;IAED;;;;OAIG;IACH,mBAHW,MAAM,aACN,QAAQ,QAYlB;IAED;;;;;OAKG;IACH,mBAJW,MAAM,QACN,QAAQ,GACN,QAAQ,GAAC,SAAS,CAW9B;IAED;;;;OAIG;IACH,wBAHW,MAAM,SACN,KAAK,QAaf;IAED;;;;;;;OAOG;IACH,uBANW,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,MACN,MAAM,QAahB;IAED;;;;;;OAMG;IACH,0BAHW,MAAM,SACN,MAAM,QAyBhB;IAED;;;;;;;;OAQG;IAEH,oCAIC;IAED;;;;;OAKG;IACH,cAHa,MAAM,EAAE,CAYpB;IAED;;;;;;;OAOG;IACH,iCAJW,MAAM,GACJ,MAAM,CAclB;IAED;;;OAGG;IACH,2BAIC;IAED;;;;;;;;OAQG;IACH;;;;;;;;;;;OAWG;IACH,0BA8BC;IAVC,gCAAsC;IAkDxC;;;;;;OAMG;IACH,eAHW,cAAc,GAAC,aAAa,aAC5B,QAAQ,QA6BlB;IAED;;;;;;;;;OASG;IACH,qCAJW,cAAc,aACd,QAAQ,QA6BlB;IAED;;;OAGG;IACH;;;;;;;;;;;;;;OAcG;IACH,qCAHW,aAAa,QAqEvB;CAOD;iBAlsBgB,WAAW;yBATH,qBAAqB"}