@volter/blender-engine 0.1.36 → 0.1.38

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/protocol.ts

@@ -76,6 +76,9 @@ export type WorkerRequest =
   /** ONE RESTRICTION COLUMN, written (`session.py`'s `outliner_set`). A column
    *  Blender draws on no row of that type is refused by name. */
   | { id: number; op: 'outliner-set'; path: string; column: string; value: boolean }
+  /** A person's shading pick, kept in the file's own 3D View (`session.py`'s `_view_shading`);
+   *  UI state, so it marks nothing changed and rides the next save. */
+  | { id: number; op: 'view-shading'; shading: 'WIREFRAME' | 'SOLID' | 'MATERIAL' | 'RENDERED' }
   | { id: number; op: 'read-file'; path: string }
   | { id: number; op: 'write-file'; path: string; bytes: Uint8Array }
   | { id: number; op: 'list-files'; path: string }

package/browser/runtime.ts

@@ -318,6 +318,12 @@ export class BlenderRuntime {
     })) as BlenderRnaWrite;
   }
 
+  /** Keep a person's shading pick in the file's own 3D View, as UI state (no save of its own). */
+  async viewShading(shading: 'WIREFRAME' | 'SOLID' | 'MATERIAL' | 'RENDERED'): Promise<void> {
+    await this.#ready();
+    await this.#request({ op: 'view-shading', shading });
+  }
+
   /** BLENDER'S VIEW LAYER TREE for the scene — what its Outliner shows, as
    *  rows (`./rna.ts`, `BlenderOutlinerTree`). `selected` is our viewport's
    *  selection by object name; reading it never writes the engine's. */

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

@@ -789,6 +789,23 @@ def _saved_view():
     return None
 
 
+def _view_shading(shading):
+    """A person's shading pick, written where Blender keeps it: the `View3DShading.type` of the 3D
+    View `_saved_view` reads. UI STATE, NOT THE MODEL: nothing is marked changed, so it rides the
+    next save the model's own edits make, as a shading change in Blender is kept only by a save."""
+    screens = [window.screen for wm in bpy.data.window_managers for window in wm.windows
+               if window.screen is not None]
+    workspace = bpy.data.workspaces.get("Modeling")
+    screens.extend(workspace.screens if workspace is not None else [])
+    screens.extend(bpy.data.screens)
+    for screen in screens:
+        for area in screen.areas:
+            if area.type == "VIEW_3D":
+                area.spaces[0].shading.type = shading
+                return {"shading": area.spaces[0].shading.type}
+    return {"shading": None}
+
+
 def _subject_line(scene, view_layer):
     """The 3D Viewport's second overlay line, as `draw_selected_name` (`view3d_draw.cc`) writes it,
     less the two parts that follow the playhead: the tab draws `(frame)` and the marker on it
@@ -1356,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:
@@ -1482,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
@@ -1518,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
@@ -1536,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.
 
@@ -5002,6 +5060,8 @@ def _dispatch(request):
             _say("@@VOLTER-ERROR the present after this call failed, so the Model document is "
                  "showing the state before it: " + repr(thrown))
         return answer
+    if op == "view-shading":
+        return _view_shading(request["shading"])
     if op == "rna-set":
         SESSION.mark_changed()
         answer = rna_set(request["path"], request["property"], request["value"],

package/browser/three/blender-runtime-view.ts

@@ -843,6 +843,10 @@ export class BlenderRuntimeView {
    * draw mode Blender reopens it in (null from a file whose view carried none). Null before a
    * frame or when the file saved no 3D View.
    */
+  noteSavedShading(shading: keyof typeof SAVED_SHADING): void {
+    if (this.frame?.view) this.frame.view.shading = shading;
+  }
+
   savedView(): {
     readonly target: readonly [number, number, number];
     readonly direction: readonly [number, number, number];

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
@@ -508,6 +589,8 @@ async function handle(request: WorkerRequest): Promise<unknown> {
         ...(request.object === undefined ? {} : { object: request.object }),
         ...(request.collection === undefined ? {} : { collection: request.collection }),
       });
+    case 'view-shading':
+      return ask({ op: 'view-shading', shading: request.shading });
     case 'rna-set':
       return ask({
         op: 'rna-set',

package/package.json

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