@codexo/exojs 0.13.0 → 0.15.0

package/dist/esm/rendering/RenderingContext.d.ts

@@ -1,11 +1,18 @@
 import type { Color } from '#core/Color';
+import type { System } from '#core/System';
+import type { Time } from '#core/Time';
+import type { Matrix } from '#math/Matrix';
+import type { Geometry } from '#rendering/geometry/Geometry';
+import type { MeshMaterial } from '#rendering/material/MeshMaterial';
 import { RenderTexture } from '#rendering/texture/RenderTexture';
-import { Camera } from './Camera';
+import type { DrawContext, RenderToOptions } from './DrawContext';
 import { type RenderBackend } from './RenderBackend';
+import { type RenderBatch } from './RenderBatch';
 import { type RenderNode } from './RenderNode';
 import { type RenderStats } from './RenderStats';
 import { View } from './View';
-export interface RenderToOptions {
+/** Options for {@link RenderingContext.capture} — allocates a new RenderTexture. */
+export interface CaptureOptions {
     width: number;
     height: number;
     clearColor?: Color;
@@ -14,6 +21,24 @@ export interface RenderOptions {
     /** Override the view used for this render call. Defaults to the context's active camera. */
     view?: View;
 }
+/** Options for {@link RenderingContext.drawGeometry}. */
+export interface DrawGeometryOptions {
+    /**
+     * Custom look (shader / uniforms / textures / blend mode) for this draw. Must
+     * target `'mesh'`. Defaults to the standard mesh material (vertex colors,
+     * optional texture), so an untextured colored geometry needs no material.
+     */
+    material?: MeshMaterial;
+    /** Tint multiplied into the geometry's vertex colors. Defaults to white (no tint). */
+    tint?: Color;
+    /** Override the view used for this draw. Defaults to the context's active camera. */
+    view?: View;
+}
+/** Options for {@link RenderingContext.drawBatch}. */
+export interface DrawBatchOptions {
+    /** Override the view used for this draw. Defaults to the context's active camera. */
+    view?: View;
+}
 /**
  * Owns rendering orchestration: builds, optimizes and plays the internal
  * RenderPlan for a RenderNode subtree, manages render-target/view state for
@@ -21,22 +46,33 @@ export interface RenderOptions {
  *
  * The conceptual model is "the context renders the node":
  *   context.render(node)            // into the active target (canvas by default)
- *   context.render(node, { view })  // override view (camera, screenView, etc.)
- *   context.renderTo(node, opts)    // into an off-screen RenderTexture
+ *   context.render(node, { view })  // override view (the world view, screenView, etc.)
+ *   context.renderTo(node, { target })       // into a caller-owned off-screen target (per-frame)
+ *   context.capture(node, { width, height }) // into a freshly allocated RenderTexture
  * @stable
  */
-export declare class RenderingContext {
+export declare class RenderingContext implements System, DrawContext {
+    /** App-systems tick band — rendering last (camera + render-plan prep). @internal */
+    readonly order = 500;
     private readonly _backend;
-    private _camera;
+    private _view;
     private readonly _screenView;
+    /** Lazily-created pooled drawable reused by every {@link drawGeometry} call. */
+    private _immediateMesh;
+    /** Lazily-created pooled geometry/look source reused by every {@link drawBatch} call. */
+    private _batchMesh;
+    /** Views explicitly pinned for per-frame update via {@link trackView} (escape hatch for views ticked but never rendered). */
+    private readonly _trackedViews;
+    /** Views rendered since the last {@link update} — auto-advanced then cleared each frame, so a custom view's follow/shake ticks with no manual bookkeeping. */
+    private readonly _renderedViews;
     constructor(backend: RenderBackend);
     /**
-     * The active camera. Defaults to a camera that matches the initial
-     * backend view. Replace with a custom `Camera` instance for follow,
-     * zoom, bounds, or split-screen viewport behavior.
+     * The active world {@link View} — the default for {@link render}. Defaults to
+     * a view matching the initial backend view. Replace with a custom `View` for
+     * follow, zoom, bounds, or split-screen viewport behavior.
      */
-    get camera(): Camera;
-    set camera(camera: Camera);
+    get view(): View;
+    set view(view: View);
     /**
      * A RenderingContext-managed screen-space {@link View} suitable for UI
      * overlays. Center and size are reset to match canvas logical dimensions
@@ -46,13 +82,31 @@ export declare class RenderingContext {
      * Never follows, shakes, or rotates by default.
      */
     get screenView(): View;
-    /** Backward-compatible alias — returns the active {@link camera}. */
-    get view(): View;
     /**
-     * Advance follow, shake, and bounds-constraint animations on the
-     * active camera. Call once per frame before rendering.
+     * Register a custom {@link View} (e.g. a picture-in-picture or minimap view)
+     * so {@link update} advances its `follow`/`shake`/bounds each frame, alongside
+     * the active {@link view}. The active view and {@link screenView} are managed
+     * automatically and need not be tracked.
+     *
+     * The view is caller-owned: call {@link untrackView} before discarding it,
+     * otherwise a `follow` target keeps it (and its target node) referenced.
+     */
+    trackView(view: View): void;
+    /** Stop advancing a previously {@link trackView}-ed view. No-op if absent. */
+    untrackView(view: View): void;
+    /**
+     * Advance follow, shake, and bounds-constraint animations on the active
+     * {@link view}, every view rendered last frame (automatic), and any
+     * {@link trackView}-ed view. Ticked once per frame via {@link Application.systems}.
      */
-    update(deltaMs: number): void;
+    update(delta: Time): void;
+    /**
+     * Destroy the resources this context owns — the active {@link View} and the
+     * screen-space {@link View}. The {@link RenderBackend} is owned by the
+     * Application and destroyed separately.
+     * @internal — invoked via Application.systems on teardown.
+     */
+    destroy(): void;
     /**
      * Resize the camera and screen view to match new canvas dimensions.
      * Preserves the camera's center and zoom; only the visible area size changes.
@@ -75,7 +129,68 @@ export declare class RenderingContext {
      * Saves and restores the active render target and view so the caller's
      * rendering state is undisturbed.
      */
-    renderTo(node: RenderNode, options: RenderToOptions): RenderTexture;
+    capture(node: RenderNode, options: CaptureOptions): RenderTexture;
+    /**
+     * Clear the active render target to `color`. Routes through the pass
+     * coordinator so it respects the clear-vs-load policy and never leaks the
+     * clear onto another target. Falls back to a raw backend clear when no
+     * coordinator is present (test stubs).
+     */
+    clear(color: Color): void;
+    /**
+     * Render `node` into a caller-owned {@link RenderTexture} that is reused across
+     * frames — the per-frame, allocation-free counterpart to {@link capture}. The
+     * target and view are supplied by the caller; the view defaults to the
+     * target's own view. Save/restore is handled by the pass coordinator.
+     */
+    renderTo(node: RenderNode, options: RenderToOptions): void;
+    /**
+     * Immediately draw a single {@link Geometry} with `transform` as its world
+     * matrix — no retained {@link RenderNode} required. Useful for procedural or
+     * data-driven shapes that would be wasteful to wrap in a node.
+     *
+     * The draw is submitted through the mesh renderer and flushed at once, so it
+     * lands in call order relative to the surrounding {@link render} calls: a
+     * `drawGeometry` issued after a layer's `render` draws on top of it. All
+     * output is presented at the frame-end backend flush, as usual.
+     *
+     * `transform` is taken as the raw world matrix (`a, b, c, d, tx, ty`),
+     * bypassing the position / rotation / scale / origin composition a node would
+     * apply — build it with {@link Matrix} directly. The geometry must use the
+     * `triangle-list` topology and the standard mesh attribute layout (position,
+     * optional texcoord and color); custom per-vertex attributes are dropped.
+     *
+     * This is the single-draw convenience of the immediate API: each call is its
+     * own flush and draw call, and the geometry is repacked every call, so it is
+     * best for a handful of draws. An instanced batch path for drawing many like
+     * items as one upload + one draw follows in a later release.
+     *
+     * @param geometry  Source geometry (interleaved vertex data + layout).
+     * @param transform World matrix applied to the geometry's local vertices.
+     * @param options   Optional {@link DrawGeometryOptions.material material},
+     *                  {@link DrawGeometryOptions.tint tint}, and
+     *                  {@link DrawGeometryOptions.view view}.
+     */
+    drawGeometry(geometry: Geometry, transform: Matrix, options?: DrawGeometryOptions): void;
+    /**
+     * Immediately draw an instanced {@link RenderBatch} — one geometry + material
+     * drawn once with the batch's N per-instance `(transform, tint)` pairs as a
+     * single instanced draw call. This is the high-throughput immediate path: use
+     * it for many like items (tiles, bullets, procedural instances) where
+     * {@link drawGeometry} would issue one draw call each.
+     *
+     * Like {@link drawGeometry}, the batch is flushed at once and lands in call
+     * order relative to the surrounding {@link render} calls. An empty batch is a
+     * no-op.
+     *
+     * v1 renders with the default mesh material (per-instance tint over the
+     * geometry's vertex colors); a custom {@link RenderBatch.material} is not yet
+     * supported on the instanced path.
+     *
+     * @param batch   The instanced submission (geometry + per-instance transforms/tints).
+     * @param options Optional {@link DrawBatchOptions.view view} override.
+     */
+    drawBatch(batch: RenderBatch, options?: DrawBatchOptions): void;
     /** Per-frame render counters. Convenience over backend.stats. */
     get stats(): RenderStats;
     /**

package/dist/esm/rendering/RenderingContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RenderingContext.d.ts","sourceRoot":"","sources":["../../../src/rendering/RenderingContext.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAIzC,OAAO,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAC;AAEjE,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAE9B,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,KAAK,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,4FAA4F;IAC5F,IAAI,CAAC,EAAE,IAAI,CAAC;CACb;AAED;;;;;;;;;;GAUG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAgB;IACzC,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAO;gBAEhB,OAAO,EAAE,aAAa;IAezC;;;;OAIG;IACH,IAAW,MAAM,IAAI,MAAM,CAE1B;IAED,IAAW,MAAM,CAAC,MAAM,EAAE,MAAM,EAQ/B;IAED;;;;;;;OAOG;IACH,IAAW,UAAU,IAAI,IAAI,CAE5B;IAED,qEAAqE;IACrE,IAAW,IAAI,IAAI,IAAI,CAEtB;IAED;;;OAGG;IACI,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAIpC;;;OAGG;IACI,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAMlD;;;;;;OAMG;IACI,MAAM,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,GAAE,aAAkB,GAAG,IAAI;IAOlE;;;;;;;;OAQG;IACI,QAAQ,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,eAAe,GAAG,aAAa;IA2C1E,iEAAiE;IACjE,IAAW,KAAK,IAAI,WAAW,CAE9B;IAED;;;;OAIG;IACH,IAAW,OAAO,IAAI,aAAa,CAElC;CACF"}
+{"version":3,"file":"RenderingContext.d.ts","sourceRoot":"","sources":["../../../src/rendering/RenderingContext.ts"],"names":[],"mappings":"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"}

package/dist/esm/rendering/RenderingContext.js

@@ -1,15 +1,15 @@
+import { ImmediateMesh } from './mesh/ImmediateMesh.js';
 import { StencilAttachmentMode } from './pass/RenderPassDescriptor.js';
 import { playRenderTree } from './plan/playRenderTree.js';
 import { RenderTexture } from './texture/RenderTexture.js';
-import { Camera } from './Camera.js';
 import '../core/Color.js';
+import '../math/Matrix.js';
 import '../core/SceneNode.js';
 import '../math/Size.js';
-import '../core/Time.js';
 import '../math/Rectangle.js';
+import './types.js';
 import './plan/RenderCommand.js';
 import './plan/RenderScope.js';
-import './types.js';
 import { View } from './View.js';
 
 /**
@@ -19,39 +19,50 @@ import { View } from './View.js';
  *
  * The conceptual model is "the context renders the node":
  *   context.render(node)            // into the active target (canvas by default)
- *   context.render(node, { view })  // override view (camera, screenView, etc.)
- *   context.renderTo(node, opts)    // into an off-screen RenderTexture
+ *   context.render(node, { view })  // override view (the world view, screenView, etc.)
+ *   context.renderTo(node, { target })       // into a caller-owned off-screen target (per-frame)
+ *   context.capture(node, { width, height }) // into a freshly allocated RenderTexture
  * @stable
  */
 class RenderingContext {
+    /** App-systems tick band — rendering last (camera + render-plan prep). @internal */
+    order = 500;
     _backend;
-    _camera;
+    _view;
     _screenView;
+    /** Lazily-created pooled drawable reused by every {@link drawGeometry} call. */
+    _immediateMesh = null;
+    /** Lazily-created pooled geometry/look source reused by every {@link drawBatch} call. */
+    _batchMesh = null;
+    /** Views explicitly pinned for per-frame update via {@link trackView} (escape hatch for views ticked but never rendered). */
+    _trackedViews = new Set();
+    /** Views rendered since the last {@link update} — auto-advanced then cleared each frame, so a custom view's follow/shake ticks with no manual bookkeeping. */
+    _renderedViews = new Set();
     constructor(backend) {
         this._backend = backend;
         const viewWidth = backend.view?.width ?? 0;
         const viewHeight = backend.view?.height ?? 0;
         const viewCenterX = backend.view?.center?.x ?? viewWidth / 2;
         const viewCenterY = backend.view?.center?.y ?? viewHeight / 2;
-        this._camera = new Camera({
+        this._view = View.from({
             center: { x: viewCenterX, y: viewCenterY },
             size: { width: viewWidth, height: viewHeight },
         });
         this._screenView = new View(viewCenterX, viewCenterY, viewWidth, viewHeight);
     }
     /**
-     * The active camera. Defaults to a camera that matches the initial
-     * backend view. Replace with a custom `Camera` instance for follow,
-     * zoom, bounds, or split-screen viewport behavior.
+     * The active world {@link View} — the default for {@link render}. Defaults to
+     * a view matching the initial backend view. Replace with a custom `View` for
+     * follow, zoom, bounds, or split-screen viewport behavior.
      */
-    get camera() {
-        return this._camera;
-    }
-    set camera(camera) {
-        const previousCamera = this._camera;
-        this._camera = camera;
-        if (previousCamera !== camera) {
-            previousCamera.destroy();
+    get view() {
+        return this._view;
+    }
+    set view(view) {
+        const previousView = this._view;
+        this._view = view;
+        if (previousView !== view) {
+            previousView.destroy();
         }
     }
     /**
@@ -65,23 +76,68 @@ class RenderingContext {
     get screenView() {
         return this._screenView;
     }
-    /** Backward-compatible alias — returns the active {@link camera}. */
-    get view() {
-        return this._camera;
+    /**
+     * Register a custom {@link View} (e.g. a picture-in-picture or minimap view)
+     * so {@link update} advances its `follow`/`shake`/bounds each frame, alongside
+     * the active {@link view}. The active view and {@link screenView} are managed
+     * automatically and need not be tracked.
+     *
+     * The view is caller-owned: call {@link untrackView} before discarding it,
+     * otherwise a `follow` target keeps it (and its target node) referenced.
+     */
+    trackView(view) {
+        this._trackedViews.add(view);
+    }
+    /** Stop advancing a previously {@link trackView}-ed view. No-op if absent. */
+    untrackView(view) {
+        this._trackedViews.delete(view);
     }
     /**
-     * Advance follow, shake, and bounds-constraint animations on the
-     * active camera. Call once per frame before rendering.
+     * Advance follow, shake, and bounds-constraint animations on the active
+     * {@link view}, every view rendered last frame (automatic), and any
+     * {@link trackView}-ed view. Ticked once per frame via {@link Application.systems}.
      */
-    update(deltaMs) {
-        this._camera.update(deltaMs);
+    update(delta) {
+        const ms = delta.milliseconds;
+        this._view.update(ms);
+        // Auto-advance every view rendered last frame (so a custom view's follow/shake
+        // ticks with no manual bookkeeping) plus any explicitly tracked view; each view
+        // updates at most once per frame.
+        for (const view of this._trackedViews) {
+            if (view !== this._view) {
+                view.update(ms);
+            }
+        }
+        for (const view of this._renderedViews) {
+            if (view !== this._view && !this._trackedViews.has(view)) {
+                view.update(ms);
+            }
+        }
+        // Render-usage is per-frame: clear so a view that stops being rendered stops ticking.
+        this._renderedViews.clear();
+    }
+    /**
+     * Destroy the resources this context owns — the active {@link View} and the
+     * screen-space {@link View}. The {@link RenderBackend} is owned by the
+     * Application and destroyed separately.
+     * @internal — invoked via Application.systems on teardown.
+     */
+    destroy() {
+        this._view.destroy();
+        this._screenView.destroy();
+        this._trackedViews.clear();
+        this._renderedViews.clear();
+        this._immediateMesh?.destroy();
+        this._immediateMesh = null;
+        this._batchMesh?.destroy();
+        this._batchMesh = null;
     }
     /**
      * Resize the camera and screen view to match new canvas dimensions.
      * Preserves the camera's center and zoom; only the visible area size changes.
      */
     resize(width, height) {
-        this._camera.resize(width, height);
+        this._view.resize(width, height);
         this._screenView.resize(width, height);
         this._screenView.setCenter(width / 2, height / 2);
     }
@@ -93,7 +149,8 @@ class RenderingContext {
      * high-level rendering entry point.
      */
     render(node, options = {}) {
-        const view = options.view ?? this._camera;
+        const view = options.view ?? this._view;
+        this._renderedViews.add(view);
         this._backend.setView(view);
         playRenderTree(node, this._backend);
     }
@@ -106,7 +163,7 @@ class RenderingContext {
      * Saves and restores the active render target and view so the caller's
      * rendering state is undisturbed.
      */
-    renderTo(node, options) {
+    capture(node, options) {
         const target = new RenderTexture(options.width, options.height);
         const view = new View(options.width / 2, options.height / 2, options.width, options.height);
         const coordinator = this._backend._passCoordinator;
@@ -139,6 +196,149 @@ class RenderingContext {
         }
         return target;
     }
+    /**
+     * Clear the active render target to `color`. Routes through the pass
+     * coordinator so it respects the clear-vs-load policy and never leaks the
+     * clear onto another target. Falls back to a raw backend clear when no
+     * coordinator is present (test stubs).
+     */
+    clear(color) {
+        const coordinator = this._backend._passCoordinator;
+        if (coordinator) {
+            coordinator.withChildPass({
+                target: coordinator.activeTarget,
+                view: coordinator.activeView,
+                load: 'clear',
+                clearColor: color,
+                stencil: StencilAttachmentMode.None,
+            }, () => {
+                /* Clear is expressed entirely by the pass descriptor above; the pass body is intentionally empty. */
+            });
+            return;
+        }
+        this._backend.clear(color);
+    }
+    /**
+     * Render `node` into a caller-owned {@link RenderTexture} that is reused across
+     * frames — the per-frame, allocation-free counterpart to {@link capture}. The
+     * target and view are supplied by the caller; the view defaults to the
+     * target's own view. Save/restore is handled by the pass coordinator.
+     */
+    renderTo(node, options) {
+        const view = options.view ?? options.target.view;
+        this._renderedViews.add(view);
+        const coordinator = this._backend._passCoordinator;
+        if (coordinator) {
+            coordinator.withChildPass({
+                target: options.target,
+                view,
+                load: options.clear !== undefined ? 'clear' : 'load',
+                clearColor: options.clear ?? null,
+                stencil: StencilAttachmentMode.None,
+            }, () => {
+                playRenderTree(node, this._backend);
+            });
+            return;
+        }
+        const previousTarget = this._backend.renderTarget;
+        const previousView = this._backend.view;
+        this._backend.setRenderTarget(options.target);
+        this._backend.setView(view);
+        if (options.clear !== undefined) {
+            this._backend.clear(options.clear);
+        }
+        try {
+            playRenderTree(node, this._backend);
+        }
+        finally {
+            this._backend.setRenderTarget(previousTarget);
+            this._backend.setView(previousView);
+        }
+    }
+    /**
+     * Immediately draw a single {@link Geometry} with `transform` as its world
+     * matrix — no retained {@link RenderNode} required. Useful for procedural or
+     * data-driven shapes that would be wasteful to wrap in a node.
+     *
+     * The draw is submitted through the mesh renderer and flushed at once, so it
+     * lands in call order relative to the surrounding {@link render} calls: a
+     * `drawGeometry` issued after a layer's `render` draws on top of it. All
+     * output is presented at the frame-end backend flush, as usual.
+     *
+     * `transform` is taken as the raw world matrix (`a, b, c, d, tx, ty`),
+     * bypassing the position / rotation / scale / origin composition a node would
+     * apply — build it with {@link Matrix} directly. The geometry must use the
+     * `triangle-list` topology and the standard mesh attribute layout (position,
+     * optional texcoord and color); custom per-vertex attributes are dropped.
+     *
+     * This is the single-draw convenience of the immediate API: each call is its
+     * own flush and draw call, and the geometry is repacked every call, so it is
+     * best for a handful of draws. An instanced batch path for drawing many like
+     * items as one upload + one draw follows in a later release.
+     *
+     * @param geometry  Source geometry (interleaved vertex data + layout).
+     * @param transform World matrix applied to the geometry's local vertices.
+     * @param options   Optional {@link DrawGeometryOptions.material material},
+     *                  {@link DrawGeometryOptions.tint tint}, and
+     *                  {@link DrawGeometryOptions.view view}.
+     */
+    drawGeometry(geometry, transform, options = {}) {
+        const material = options.material ?? null;
+        // Defensive guard for JS callers; the MeshMaterial type already enforces
+        // this for TypeScript callers (its `target` is the literal 'mesh').
+        if (material !== null && material.target !== 'mesh') {
+            throw new Error(`drawGeometry material must target 'mesh' (got '${String(material.target)}').`);
+        }
+        const view = options.view ?? this._view;
+        this._renderedViews.add(view);
+        const mesh = (this._immediateMesh ??= new ImmediateMesh());
+        // Set the view first: setView now only flushes when the view actually changes
+        // (not unconditionally). Correctness here rests on (a) the trailing flush()
+        // below — so a later drawGeometry cannot observe this pooled mesh through a
+        // still-deferred draw — and (b) any renderer switch flushing its pending batch.
+        this._backend.setView(view);
+        mesh.configure(geometry, transform, material, options.tint ?? null);
+        this._backend.draw(mesh);
+        this._backend.flush();
+    }
+    /**
+     * Immediately draw an instanced {@link RenderBatch} — one geometry + material
+     * drawn once with the batch's N per-instance `(transform, tint)` pairs as a
+     * single instanced draw call. This is the high-throughput immediate path: use
+     * it for many like items (tiles, bullets, procedural instances) where
+     * {@link drawGeometry} would issue one draw call each.
+     *
+     * Like {@link drawGeometry}, the batch is flushed at once and lands in call
+     * order relative to the surrounding {@link render} calls. An empty batch is a
+     * no-op.
+     *
+     * v1 renders with the default mesh material (per-instance tint over the
+     * geometry's vertex colors); a custom {@link RenderBatch.material} is not yet
+     * supported on the instanced path.
+     *
+     * @param batch   The instanced submission (geometry + per-instance transforms/tints).
+     * @param options Optional {@link DrawBatchOptions.view view} override.
+     */
+    drawBatch(batch, options = {}) {
+        if (batch.material !== null) {
+            throw new Error('drawBatch custom materials are not supported yet — v1 renders batches with the default mesh material.');
+        }
+        if (batch.count === 0) {
+            return;
+        }
+        const view = options.view ?? this._view;
+        this._renderedViews.add(view);
+        const mesh = (this._batchMesh ??= new ImmediateMesh());
+        // Set the view first (setView only flushes when the view actually changes;
+        // correctness rests on the trailing flush() below and on any renderer switch
+        // flushing its pending batch), configure the pooled geometry/look source,
+        // then submit a single instanced draw over the batch's per-instance
+        // transforms/tints and flush it immediately.
+        this._backend.setView(view);
+        mesh.configureBatchSource(batch.geometry, batch.material);
+        this._backend.drawInstanced(mesh, batch._instanceTransforms, batch._instanceTints, batch.count);
+        this._backend.flush();
+    }
     /** Per-frame render counters. Convenience over backend.stats. */
     get stats() {
         return this._backend.stats;

package/dist/esm/rendering/RenderingContext.js.map

@@ -1 +1 @@
-{"version":3,"file":"RenderingContext.js","sources":["../../../../src/rendering/RenderingContext.ts"],"sourcesContent":[null],"names":[],"mappings":"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"}
+{"version":3,"file":"RenderingContext.js","sources":["../../../../src/rendering/RenderingContext.ts"],"sourcesContent":[null],"names":[],"mappings":"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"}

package/dist/esm/rendering/TransformBuffer.d.ts

@@ -28,6 +28,8 @@ export declare class TransformBuffer {
     private _skippedWriteCount;
     private _uploadCount;
     private _uploadedRecordCount;
+    private _dirtyMin;
+    private _dirtyMax;
     get count(): number;
     /**
      * Number of transform rows written into the buffer (via {@link write} /
@@ -59,8 +61,29 @@ export declare class TransformBuffer {
     get capacity(): number;
     get data(): Float32Array;
     get version(): number;
+    /** Running content hash of the rows written since begin(). @internal */
+    get frameHash(): number;
     begin(expectedCount?: number): this;
     push(transform: Matrix, tint: Color): number;
+    /**
+     * Rewind the write cursor to `count`, freeing the rows above it for reuse, and
+     * (optionally) restore the running content hash to its pre-rewind value so the
+     * freed rows' writes don't linger in the hash and trigger spurious re-uploads.
+     * Used by nested draw plans (filters / cacheAsBitmap) to isolate their slots.
+     * @internal
+     */
+    rewindTo(count: number, frameHash?: number): this;
+    /**
+     * Consume the dirty row range written since the last upload, clamped to
+     * `[0, maxCount)`, and clear it. Returns the contiguous `[firstRow, firstRow +
+     * rowCount)` a delta upload should push (`rowCount === 0` when nothing is
+     * dirty). The backend calls this at its upload boundary.
+     * @internal
+     */
+    consumeDirtyRange(maxCount: number): {
+        firstRow: number;
+        rowCount: number;
+    };
     write(slot: number, transform: Matrix, tint: Color): this;
     /**
      * Record that a draw command's transform write was intentionally skipped

package/dist/esm/rendering/TransformBuffer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TransformBuffer.d.ts","sourceRoot":"","sources":["../../../src/rendering/TransformBuffer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAU3C,gBAAgB;AAChB,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;GASG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,KAAK,CAAmE;IAChF,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,UAAU,CAAoB;IACtC,OAAO,CAAC,kBAAkB,CAAK;IAC/B,OAAO,CAAC,mBAAmB,CAAM;IACjC,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,kBAAkB,CAAK;IAC/B,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,oBAAoB,CAAK;IAEjC,IAAW,KAAK,IAAI,MAAM,CAEzB;IAED;;;;;OAKG;IACH,IAAW,UAAU,IAAI,MAAM,CAE9B;IAED;;;;;OAKG;IACH,IAAW,iBAAiB,IAAI,MAAM,CAErC;IAED;;;;;OAKG;IACH,IAAW,WAAW,IAAI,MAAM,CAE/B;IAED;;;;OAIG;IACH,IAAW,mBAAmB,IAAI,MAAM,CAEvC;IAED,IAAW,QAAQ,IAAI,MAAM,CAE5B;IAED,IAAW,IAAI,IAAI,YAAY,CAE9B;IAED,IAAW,OAAO,IAAI,MAAM,CAE3B;IAEM,KAAK,CAAC,aAAa,SAAI,GAAG,IAAI;IAe9B,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,GAAG,MAAM;IAQ5C,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,GAAG,IAAI;IAsChE;;;;;OAKG;IACI,kBAAkB,IAAI,IAAI;IAMjC;;;;OAIG;IACI,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAOvC,cAAc,CAAC,QAAQ,SAAI,GAAG,4BAA4B;IAmBjE,OAAO,CAAC,eAAe;IAmBvB,OAAO,CAAC,UAAU;IAMlB,OAAO,CAAC,IAAI;CAGb"}
+{"version":3,"file":"TransformBuffer.d.ts","sourceRoot":"","sources":["../../../src/rendering/TransformBuffer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAU3C,gBAAgB;AAChB,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;GASG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,KAAK,CAAmE;IAChF,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,UAAU,CAAoB;IACtC,OAAO,CAAC,kBAAkB,CAAK;IAC/B,OAAO,CAAC,mBAAmB,CAAM;IACjC,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,kBAAkB,CAAK;IAC/B,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,oBAAoB,CAAK;IAKjC,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,SAAS,CAAM;IAEvB,IAAW,KAAK,IAAI,MAAM,CAEzB;IAED;;;;;OAKG;IACH,IAAW,UAAU,IAAI,MAAM,CAE9B;IAED;;;;;OAKG;IACH,IAAW,iBAAiB,IAAI,MAAM,CAErC;IAED;;;;;OAKG;IACH,IAAW,WAAW,IAAI,MAAM,CAE/B;IAED;;;;OAIG;IACH,IAAW,mBAAmB,IAAI,MAAM,CAEvC;IAED,IAAW,QAAQ,IAAI,MAAM,CAE5B;IAED,IAAW,IAAI,IAAI,YAAY,CAE9B;IAED,IAAW,OAAO,IAAI,MAAM,CAE3B;IAED,wEAAwE;IACxE,IAAW,SAAS,IAAI,MAAM,CAE7B;IAEM,KAAK,CAAC,aAAa,SAAI,GAAG,IAAI;IAiB9B,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,GAAG,MAAM;IAQnD;;;;;;OAMG;IACI,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI;IAYxD;;;;;;OAMG;IACI,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE;IAe3E,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,GAAG,IAAI;IAiDhE;;;;;OAKG;IACI,kBAAkB,IAAI,IAAI;IAMjC;;;;OAIG;IACI,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAOvC,cAAc,CAAC,QAAQ,SAAI,GAAG,4BAA4B;IAmBjE,OAAO,CAAC,eAAe;IAmBvB,OAAO,CAAC,UAAU;IAOlB,OAAO,CAAC,IAAI;CAGb"}