@volter/blender-engine 0.1.37 → 0.1.39

package/browser/blender-engine.mts

@@ -114,7 +114,24 @@ export interface BlenderEngineOptions {
    *  `saveDue` rides BESIDE the frame (the frame's own schema is the
    *  presenter's): this present left the session's `.blend` behind the model,
    *  and whoever answers owes it a save once the session goes idle. */
-  ask(payload: { frame: unknown; capture?: unknown; saveDue?: boolean }): Promise<unknown>;
+  ask(payload: SessionAsk): Promise<unknown>;
+}
+
+/**
+ * WHAT THE SESSION ASKS. A whole frame (`frame`), presented at once; or a frame in pieces
+ * (`session.py::_pull`): the frame whose changed meshes and pictures are deferred (`hold`), then
+ * each of them (`mesh` or `image`, with its `piece`), then the frame again with `present`, which is
+ * answered as a whole frame is.
+ */
+export interface SessionAsk {
+  frame?: unknown;
+  hold?: unknown;
+  mesh?: string;
+  image?: string;
+  piece?: unknown;
+  present?: boolean;
+  capture?: unknown;
+  saveDue?: boolean;
 }
 
 export interface BlenderEngine {

package/browser/runtime.ts

@@ -133,6 +133,10 @@ export interface BlenderCallMetrics {
   readonly wasmMemoryMB: number | null;
 }
 
+/** The engine's linear-memory ceiling, its link's `-sMAXIMUM_MEMORY` (4 GiB, wasm32's limit;
+ *  `blender_web_headless.cmake`). JavaScript cannot read a memory's maximum back. */
+const ENGINE_MEMORY_CEILING_MB = 4096;
+
 export class BlenderRuntime {
   readonly #worker: Worker;
   readonly #options: BlenderRuntimeOptions;
@@ -187,8 +191,15 @@ export class BlenderRuntime {
       // Error ("Uncaught [object Object]"), while the reason (an allocation that failed, the file
       // it was reading) is the last thing Blender printed.
       const last = this.#lastLines.length > 0 ? `\nBlender's last output:\n${this.#lastLines.join('\n')}` : '';
+      // OUT OF MEMORY IS SAID AS SUCH, from the heap the worker reported as the thread died.
+      const heapMB = this.#wasmBytes === null ? null : Math.round(this.#wasmBytes / 1048576);
+      const exhausted =
+        heapMB !== null && heapMB >= ENGINE_MEMORY_CEILING_MB - 16
+          ? `Blender ran out of memory: its heap reached ${heapMB} MB of the in-tab engine's ` +
+            `${ENGINE_MEMORY_CEILING_MB} MB, and this scene needs more. `
+          : '';
       const error = new Error(
-        `Blender worker failed: ${said || 'the worker script did not load'}${where}${last}`,
+        `${exhausted}Blender worker failed: ${said || 'the worker script did not load'}${where}${last}`,
       );
       // The page console is the editor's ledger (`installEditorConsoleReporting`
       // captures it, source-blind), and this package may import nothing of the

package/browser/session-frame.mts

@@ -35,7 +35,7 @@ export interface ColumnDescriptor {
   stride: number;
 }
 
-const isDescriptor = (value: unknown): value is ColumnDescriptor =>
+export const isColumnDescriptor = (value: unknown): value is ColumnDescriptor =>
   typeof value === 'object' &&
   value !== null &&
   typeof (value as ColumnDescriptor).offset === 'number' &&
@@ -97,7 +97,7 @@ function readColumn(arena: Uint8Array, name: string, descriptor: ColumnDescripto
  */
 export function columnsToTypedArrays(arena: Uint8Array, frame: unknown): unknown {
   const walk = (value: unknown, key: string): unknown => {
-    if (isDescriptor(value)) {
+    if (isColumnDescriptor(value)) {
       const view = readColumn(arena, key, value);
       return key === 'co' ? Float64Array.from(view) : view;
     }
@@ -144,7 +144,7 @@ export interface ColumnDigest {
  */
 export async function describeFrame(arena: Uint8Array, frame: unknown): Promise<unknown> {
   const walk = async (value: unknown, key: string): Promise<unknown> => {
-    if (isDescriptor(value)) {
+    if (isColumnDescriptor(value)) {
       const { offset, length, dtype } = value;
       if (offset < 0 || length < 0 || offset + length > arena.byteLength)
         throw new Error(

package/browser/session.py

@@ -1373,6 +1373,11 @@ class Session:
         # that can see the ask can read the file.
         if EXPORT_BUFFER_PATH:
             options["buffer_path"] = EXPORT_BUFFER_PATH
+        # NOTICE, THEN PULL (`_present`): a changed mesh is named here and its columns are written
+        # one mesh at a time after, so the engine never holds every changed mesh's columns at once.
+        # An engine without the pull door ships them all in this call, as before.
+        if hasattr(_blender_web, "export_mesh"):
+            options["defer"] = True
         frame = json.loads(_blender_web.export_frame(json.dumps(options)))
         error = frame.get("error")
         if error:
@@ -1499,13 +1504,15 @@ class Session:
     def _present(self, capture=None):
         known = dict(self._known)
         frame = self._export()
+        pulled = self._pull(frame)
         self._drop_unreachable_textures(frame)
         # WHAT THIS FRAME SHIPPED, for the session's own accounting: the ids
         # whose columns crossed, and the ids that went as a reference. The
         # export's whole revision rule is visible here and nowhere else.
         self.last_shipped = {
             "revision": self.revision,
-            "columns": sorted(k for k, v in frame["meshes"].items() if "columns" in v),
+            "columns": sorted(k for k, v in frame["meshes"].items()
+                              if "columns" in v or v.get("deferred")),
             "unchanged": sorted(k for k, v in frame["meshes"].items() if v.get("unchanged")),
             "images": sorted(frame["images"].keys()),
             # How many COLUMN BYTES this frame actually shipped: a move ships
@@ -1535,6 +1542,8 @@ class Session:
             self._known["weights:%s:%s" % (weights["object"], weights["group"])] = (
                 weights["digest"])
         request = {"frame": frame}
+        if pulled:
+            request["present"] = True
         if capture:
             request["capture"] = capture
         # BESIDE the frame, never inside it: the frame's schema is the
@@ -1553,6 +1562,38 @@ class Session:
         self._reconcile_with_presenter(answer, frame)
         return answer
 
+    def _pull(self, frame):
+        """THE PULL, one datablock at a time, as Hydra's render delegate pulls each prim's data
+        during Sync after the scene index's notice (`HydraSceneIndex::populate`). The door named
+        the changed meshes and pictures as deferred; the worker first copies the frame's own
+        columns out of the heap (`hold`), then each mesh's columns and each picture's pixels in
+        turn, copying each out before the next is written (every pull frees the one before). The
+        engine's peak is the scene plus one datablock's columns, not plus every changed one's.
+
+        The pieces come back into the frame as the door would have written them: a picture with no
+        readable pixels leaves `images` with its warning, as it did when the frame carried it
+        whole, so `_drop_unreachable_textures` reads the same frame either way. Answers whether
+        anything was pulled; the worker then presents the frame with its pieces."""
+        meshes = [key for key, mesh in frame["meshes"].items() if mesh.get("deferred")]
+        images = [name for name, image in frame["images"].items() if image.get("deferred")]
+        if not meshes and not images:
+            return False
+        ask({"hold": frame})
+        options = {"buffer_path": EXPORT_BUFFER_PATH} if EXPORT_BUFFER_PATH else {}
+        for kind, keys, door in (("mesh", meshes, _blender_web.export_mesh),
+                                 ("image", images, _blender_web.export_image)):
+            for key in keys:
+                options["key"] = key
+                piece = json.loads(door(json.dumps(options)))
+                if piece.get("error"):
+                    raise RuntimeError("Blender export door: %s" % piece["error"])
+                frame["warnings"].extend(piece.get("warnings", []))
+                if piece[kind] is None:
+                    del frame["images"][key]
+                    continue
+                ask({kind: key, "piece": piece[kind]})
+        return True
+
     def _drop_unreachable_textures(self, frame):
         """A picture the export could not read is a WARNING, not a refusal.
 
@@ -2311,10 +2352,14 @@ class NativeHistory:
         finally:
             self.moving = False
         self.cursor += -1 if direction == "undo" else 1
-        # Native undo replaces datablocks. Both revision caches must forget their
-        # old pointers before the restored scene is exported to the presenter.
-        _blender_web.session_reset()
-        SESSION.forget()
+        # AN UNDO STEP IS AN ORDINARY UPDATE when Blender kept its datablocks and depsgraph:
+        # memfile undo re-reads only the changed IDs and tags exactly those, so the next frame
+        # re-ships what changed and the presenter keeps the rest (`session_undo`). A step that
+        # replaced the depsgraph starts both revision caches over, as does an engine without
+        # the door.
+        if not hasattr(_blender_web, "session_undo") or _blender_web.session_undo():
+            _blender_web.session_reset()
+            SESSION.forget()
         SESSION.present()
         return {"moved": True}
 

package/browser/worker.ts

@@ -38,7 +38,7 @@
 
 import { type BlenderEngine, type BlenderFiles, startBlenderEngine } from './blender-engine.mts';
 import type { CaptureRequest, FileEntry, WorkerReply, WorkerRequest } from './protocol';
-import { columnsToTypedArrays, describeFrame } from './session-frame.mts';
+import { columnsToTypedArrays, describeFrame, isColumnDescriptor } from './session-frame.mts';
 
 const post = (reply: WorkerReply) => (self as unknown as Worker).postMessage(reply);
 const log = (level: 'log' | 'warn' | 'error', text: string) => post({ op: 'log', level, text });
@@ -123,6 +123,65 @@ function enqueue<T>(work: () => Promise<T>): Promise<T> {
   return result;
 }
 
+/** A frame arriving in pieces (`session.py::_pull`), held until its `present`: the frame's own
+ *  columns by their arena offset, and each deferred datablock copied as it came. */
+interface Copied {
+  typed: unknown;
+  description: unknown;
+}
+interface PendingFrame {
+  columns: Map<number, Copied>;
+  meshes: Map<string, Copied>;
+  images: Map<string, Copied>;
+}
+let pending: PendingFrame | null = null;
+
+/** Every column the held frame names, copied now and keyed by its offset (unique in its arena). */
+async function copyColumns(arena: Uint8Array, frame: unknown): Promise<Map<number, Copied>> {
+  const columns = new Map<number, Copied>();
+  const walk = async (value: unknown, key: string): Promise<void> => {
+    if (isColumnDescriptor(value)) {
+      columns.set(value.offset, {
+        typed: (columnsToTypedArrays(arena, { [key]: value }) as Record<string, unknown>)[key],
+        description: (await describeFrame(arena, value)) as unknown,
+      });
+      return;
+    }
+    if (Array.isArray(value)) for (const entry of value) await walk(entry, key);
+    else if (typeof value === 'object' && value !== null)
+      for (const [name, held] of Object.entries(value)) await walk(held, name);
+  };
+  await walk(frame, '');
+  return columns;
+}
+
+/** The presented frame with its pieces put back: each column from the held copies, each deferred
+ *  mesh and picture from its pulled piece. Both the typed frame and its record. */
+function assemblePending(held: PendingFrame, frame: unknown): { typed: unknown; description: unknown } {
+  const build = (side: keyof Copied) => {
+    const walk = (value: unknown, path: readonly string[]): unknown => {
+      if (isColumnDescriptor(value)) {
+        const copied = held.columns.get(value.offset);
+        if (!copied) throw new Error(`Blender frame column ${path.join('.')}: not in the held frame`);
+        return copied[side];
+      }
+      if (Array.isArray(value)) return value.map((entry) => walk(entry, path));
+      if (typeof value !== 'object' || value === null) return value;
+      if ((value as { deferred?: unknown }).deferred === true) {
+        const [group, name] = path.slice(-2);
+        const piece = (group === 'meshes' ? held.meshes : held.images).get(name as string);
+        if (!piece) throw new Error(`Blender frame ${group} ${name}: deferred and never pulled`);
+        return piece[side];
+      }
+      const out: Record<string, unknown> = {};
+      for (const [name, entry] of Object.entries(value)) out[name] = walk(entry, [...path, name]);
+      return out;
+    };
+    return walk(frame, []);
+  };
+  return { typed: build('typed'), description: build('description') };
+}
+
 function setDocumentDirty(dirty: boolean): void {
   documentDirty = dirty;
   post({ op: 'document-dirty', dirty });
@@ -182,22 +241,44 @@ async function startBlender(project: string, document?: string): Promise<unknown
   const started = await startBlenderEngine({
     project,
     log,
-    ask: async ({ frame, capture, saveDue }) => {
+    ask: async ({ frame, hold, mesh, image, piece, present, capture, saveDue }) => {
       if (!holder.engine) throw new Error('The Blender session presented before it started');
       // Save once after the whole command, never during a partial frame.
       if (saveDue && documentPath !== null) setDocumentDirty(true);
-      // THE ARENA IS READ ONCE, HERE, and both readers share those bytes: the
+      // THE ARENA IS READ ONCE PER ASK, and both readers share those bytes: the
       // typed arrays the tab draws from, and the record of what was sent
       // (`describeFrame`). After the post the buffers are detached and the
-      // next `export_frame` overwrites the arena -- on either skew -- so there
+      // next export call overwrites the arena -- on either skew -- so there
       // is no later moment at which either could be taken.
       const arena = await holder.engine.readArena();
-      const description = await describeFrame(arena, frame);
-      const answered = await presentToTab(
-        columnsToTypedArrays(arena, frame),
-        description,
-        capture as CaptureRequest | undefined,
-      );
+      // A FRAME IN PIECES (`session.py::_pull`): its own columns and each deferred datablock are
+      // copied out of the heap as they come, because the next export call frees them; the tab
+      // gets the whole frame at `present`.
+      if (hold !== undefined) {
+        pending = { columns: await copyColumns(arena, hold), meshes: new Map(), images: new Map() };
+        return {};
+      }
+      if (mesh !== undefined || image !== undefined) {
+        if (!pending) throw new Error(`The Blender session sent ${mesh ?? image} before its frame`);
+        const copied = {
+          typed: columnsToTypedArrays(arena, piece),
+          description: await describeFrame(arena, piece),
+        };
+        if (mesh !== undefined) pending.meshes.set(mesh, copied);
+        else pending.images.set(image as string, copied);
+        return {};
+      }
+      let typed: unknown;
+      let description: unknown;
+      if (present) {
+        if (!pending) throw new Error('The Blender session presented a frame it never sent');
+        ({ typed, description } = assemblePending(pending, frame));
+        pending = null;
+      } else {
+        typed = columnsToTypedArrays(arena, frame);
+        description = await describeFrame(arena, frame);
+      }
+      const answered = await presentToTab(typed, description, capture as CaptureRequest | undefined);
       // THE CAPTURE IS THE ANSWER'S BODY, and `held` rides beside it: the
       // session reads a photograph's own fields off this object
       // (`session.py::_photograph`), and reads `held` to judge whether its
@@ -623,6 +704,11 @@ function reportMemory(): void {
   if (bytes !== null) post({ op: 'memory', bytes });
 }
 
+// A BLENDER THREAD THAT DIES IS WEIGHED FIRST: its error reaches this scope before the page's
+// `onerror`, so the heap it died at is posted ahead of the failure, and the page can say whether
+// the engine ran out of memory (`runtime.ts`) instead of "Uncaught [object Object]".
+self.addEventListener('error', reportMemory);
+
 self.onmessage = (event: MessageEvent<WorkerRequest>) => {
   const request = event.data;
   if (request.op === 'present-result') {

package/package.json

@@ -2,7 +2,7 @@
   "name": "@volter/blender-engine",
   "author": "Volter AI, Inc.",
   "license": "GPL-3.0-or-later",
-  "version": "0.1.37",
+  "version": "0.1.39",
   "publishConfig": {
     "access": "public"
   },