@volter/editor-blender 0.1.150 → 0.1.152

package/contributions/blender-scene-mixer.ts

@@ -0,0 +1,51 @@
+/**
+ * ONE MIXER PER PRESENTED SCENE (`docs/SCENE-ANIMATION.md`, steps 3 and 4).
+ *
+ * Every armature's layers (`blender-mixer-pose.ts`, each bound to its own rig so bones of the same
+ * name in two characters never meet) and the scene's movie (`blender-playback-movie.ts`, its objects and
+ * cameras) are actions on ONE `THREE.AnimationMixer` rooted at the view's root, on one clock. A
+ * frame is placed in three steps for the Timeline preview:
+ *
+ * 1. PLACE: each player sets its actions' times and weights for the frame (`place`).
+ * 2. EVALUATE: the mixer applies every enabled action at once (`evaluate`), once per frame however
+ *    many characters there are.
+ * 3. SETTLE: what the mixer does not do on its own, after it (`settle`): Damped Track and Track To,
+ *    and the fidelity check against Blender's own pose.
+ *
+ * An action left enabled keeps writing its last placement every evaluation, so a player that is not
+ * placed this frame (the movie while the Timeline stands at Blender's own frame) disables its actions
+ * rather than leaving them behind.
+ */
+import * as THREE from 'three';
+
+export class SceneMixer {
+  readonly mixer: THREE.AnimationMixer;
+
+  constructor(readonly root: THREE.Object3D) {
+    this.mixer = new THREE.AnimationMixer(root);
+  }
+
+  /** Apply every placed action, all at once. */
+  evaluate(): void {
+    this.mixer.update(0);
+    this.root.updateMatrixWorld(true);
+  }
+
+  dispose(): void {
+    this.mixer.stopAllAction();
+    this.mixer.uncacheRoot(this.root);
+  }
+}
+
+const mixers = new WeakMap<object, SceneMixer>();
+
+/** The one mixer of a presented view: made on first use,
+ *  and made again when the view's root is a new object (a new present). */
+export function sceneMixer(view: { readonly root: THREE.Object3D }): SceneMixer {
+  const held = mixers.get(view);
+  if (held && held.root === view.root) return held;
+  held?.dispose();
+  const made = new SceneMixer(view.root);
+  mixers.set(view, made);
+  return made;
+}

package/contributions/blender-screenshot.service.ts

@@ -0,0 +1,28 @@
+/**
+ * Save Screenshot (Editor)… — Blender's own Window menu row (`TOPBAR_MT_window`,
+ * `screen.screenshot_area`), the person's door to the photograph an agent takes with
+ * `get_viewport_screenshot`. It is this package's command `volter.blender.saveScreenshotEditor`
+ * (`contributes.commands`, in the palette); this runs it.
+ *
+ * Blender asks for a path in its file browser; the files door has no file picker, so the picture
+ * goes to the project's `screenshots/` folder and a notification says which file it is. Like every
+ * photograph of the document it flashes the document and shows itself in the corner.
+ */
+import { bytesFromBase64 } from '@volter/blender-engine/browser/three/blender-base64';
+import { editorHost } from '@volter/sdk/host';
+import { announcePhotograph } from '@volter/sdk/photograph-notice';
+
+export const point = 'workspace.service';
+
+async function saveScreenshot(): Promise<void> {
+  const host = editorHost();
+  const capture = await host.documents.captureActive();
+  announcePhotograph(capture.base64);
+  const path = `screenshots/screenshot-${new Date().toISOString().replace(/[:.]/g, '-')}.png`;
+  await host.files.write(path, bytesFromBase64(capture.base64));
+  host.notify({ id: 'blender-screenshot', tone: 'info', title: 'Saved the screenshot', detail: path });
+}
+
+export function start(): () => void {
+  return editorHost().keyboard.bindActions([{ id: 'blender.saveScreenshotEditor', run: () => void saveScreenshot() }]);
+}

package/contributions/blender-timeline-geometry.ts

@@ -1,54 +1,15 @@
-/**
- * THE TIMELINE'S CONSTANTS — every one read from Blender's source at the
- * engine's pin (5.2.0, `fbe6228777e7`) AND checked against a PIXEL in Blender's
- * own frame (5.2.1 on this box, `scripts/blender-reference-frames.py`).
- *
- * This is the first unit of the inspection arc with a sighted read behind it.
- * I1-I5 each recorded that the reference frames were not at hand, so each was graded
- * against Blender's SOURCE alone; Blender is installed here, the script above
- * drives its real GUI, and the numbers below carry three things each: the
- * source that defines them, the pixel that confirms them, and what we draw.
- *
- * ## The screenshot reads ONE 8-BIT LEVEL BELOW the theme byte
- *
- * Measured on every flat fill in the frame: the theme's `#303030` reads
- * `#2f2f2f`, `#1d1d1d` reads `#1c1c1c`, `#161616` reads `#151515`,
- * `#4772b3` reads `#4671b2`, `#ffbe33` reads `#ffbd32`. It is uniform and it
- * is the screenshot path's, not the theme's — so the values below are the
- * THEME BYTES (what Blender means) and a reader comparing them against a
- * reference PNG should expect that −1.
- *
- * ## The theme's own table disagrees with the source's default in one place,
- * and the running theme wins
- *
- * `userdef_default_theme.c:490` declares `.space_action.back` as
- * `RGBA(0x30303000)` — alpha ZERO. Read off the RUNNING factory theme
- * (`bpy.context.preferences.themes[0].dopesheet_editor.space.back`) it is
- * `#303030ff`. The difference is load-bearing: `ANIM_draw_framerange` paints
- * the out-of-range area with `TH_BACK` shaded −25 at alpha −100, which at
- * alpha 0 would draw NOTHING and at alpha 255 draws a visible darkening. The
- * frame settles it — outside the range is `#202020` against `#2f2f2f` inside,
- * which is exactly `48 + (23 − 48) × 155/255 = 32.8`. The screenshot wins.
- */
+/** Timeline geometry and theme constants follow Blender at the engine pin. Use the running factory theme’s opaque space_action.back, which controls out-of-range shading. */
 
-/** `U.widget_unit` — `wm_window.cc:779`, `int(roundf(18 * scale_factor)) + 2 *
- *  pixelsize` = 20 at scale 1. Confirmed in the frame: a transport button
- *  block of six is 120 px wide (x 697…816), so each is 20. */
+/** U.widget_unit is 20 at scale 1 (wm_window.cc:779). */
 export const WIDGET_UNIT = 20;
 
-/** `UI_TIME_SCRUB_MARGIN_Y` — `UI_view2d.hh:491`, `23 * UI_SCALE_FAC`. The
- *  strip the ruler and the playhead's number pill live in. CONFIRMED: the
- *  Timeline area's `.regions.scrubbing.back` band is exactly 23 px tall
- *  (image rows 26…48 under a 26-px header). */
+/** UI_TIME_SCRUB_MARGIN_Y is 23 × UI_SCALE_FAC (UI_view2d.hh:491). */
 export const SCRUB_HEIGHT = 23;
 
-/** `HEADERY` — `DNA_screen_types.h:602`, `20 + HEADER_PADDING_Y`. CONFIRMED
- *  at 26 px, with its 20-px widgets centred (3 px above, 3 below). */
+/** HEADERY is 20 + HEADER_PADDING_Y = 26 (DNA_screen_types.h:602). */
 export const HEADER_HEIGHT = 26;
 
-/** `ANIM_UI_get_channel_height` — `anim_channels_defines.cc:5147-5150`,
- *  `0.8 * keyframe_scale_fac * widget_unit`; `keyframe_scale_fac` is 1.0
- *  (`userdef_default_theme.c:508`, and read back 1.0 off the running theme). */
+/** Channel height is 0.8 × keyframe_scale_fac × widget_unit; the theme scale is 1 (anim_channels_defines.cc:5147-5150). */
 export const CHANNEL_HEIGHT = 16;
 /** `ANIM_UI_get_channel_skip` — `:5152-5155`, `0.1 * widget_unit`. */
 export const CHANNEL_SKIP = 2;
@@ -56,24 +17,6 @@ export const CHANNEL_SKIP = 2;
  *  `-UI_TIME_SCRUB_MARGIN_Y - skip` below the region's top edge. */
 export const FIRST_CHANNEL_TOP = SCRUB_HEIGHT + CHANNEL_SKIP;
 
-/**
- * THE TIMELINE DRAWS EXACTLY ONE CHANNEL ROW, and that is a source fact rather
- * than a layout choice: `action_create` sets `ADS_FLAG_SUMMARY_COLLAPSED` when
- * the area's subtype is `SACTCONT_TIMELINE` (`space_action.cc:80-83`), and
- * `animdata_filter_dopesheet` returns 0 right after adding the summary channel
- * when that flag is set (`anim_filter.cc:3845-3849`). The channel-NAMES region
- * is not drawn at all in Timeline mode
- * (`action_region_poll_hide_in_timeline`, `space_action.cc:785-790`).
- *
- * THE ROW HAS NO BACKDROP EITHER. `draw_backdrops` branches on
- * `ELEM(ac->datatype, ANIMCONT_ACTION, ANIMCONT_DOPESHEET, ANIMCONT_SHAPEKEY)`
- * and then on GPENCIL and MASK (`action_draw.cc:218-300`); `ANIMCONT_TIMELINE`
- * matches none of them, so the summary row is drawn straight onto the region's
- * own clear. CONFIRMED: the row is `#2f2f2f` inside the frame range, the same
- * value as the rest of the region.
- */
-export const TIMELINE_ROWS = 1;
-
 /** `MIN_MAJOR_LINE_DISTANCE` — `view2d_draw.cc:41`, `U.v2d_min_gridsize *
  *  UI_SCALE_FAC`, default 35 (`versioning_userdef.cc:1028-1029`). The real
  *  minimum is `max(35, label width + 6)` (`get_min_line_distance_x`, `:485`,
@@ -152,27 +95,20 @@ export function minorStep(major: number): number | null {
  * running theme is what draws, and the disagreement is named.
  */
 export const TIMELINE_THEME = {
-  /** `.space_action.back` — `userdef_default_theme.c:490` declares
-   *  `0x30303000`; the RUNNING theme is `#303030ff` (see the module header).
-   *  The region's clear, `frame_buffer_clear(TH_BACK)`. */
+  /** space_action.back is #303030ff in the running factory theme; frame_buffer_clear uses its RGB. */
   back: '#303030',
-  /** `.space_action.header` `0x303030b3` (`:494`) over the window. Reads
-   *  `#2f2f2f` in the frame, which at alpha 0xb3 over `#2d2d2d`-ish window
-   *  chrome is what this value resolves to; drawn flat here. */
+  /** space_action.header from userdef_default_theme.c, drawn flat. */
   header: '#303030',
   /** `.space_action.grid` — `:498`. The MAJOR frame lines. */
   grid: '#161616',
-  /** `get_color_shade_3ubv(TH_GRID, 16)` — `view2d_draw.cc:266`. The MINOR
-   *  lines, exactly 16 levels lighter. CONFIRMED `#252525` in the frame
-   *  against the major's `#151515`. */
+  /** Minor grid lines use TH_GRID shaded 16 levels lighter (view2d_draw.cc). */
   gridMinor: '#262626',
   /** `.regions.scrubbing.back` — `userdef_default_theme.c:300`. */
   scrubBack: '#1d1d1d',
   /** `.regions.scrubbing.text` — `:301`, the ruler's numbers
    *  (`TH_TIME_SCRUB_TEXT`, passed by `ED_time_scrub_draw`). */
   scrubText: '#808080',
-  /** `.common.anim.playhead` (`TH_CFRAME`) — `:312`. The stalk, the pill and
-   *  its tip. CONFIRMED `#4671b2` in the frame. */
+  /** TH_CFRAME supplies the playhead stalk, pill and tip. */
   playhead: '#4772b3',
   /** `TH_HEADER_TEXT_HI` — the pill's number (`draw_playhead_box`,
    *  `time_scrub_ui.cc:182`); `.space_action.header_text_hi` `:496`. */
@@ -187,8 +123,7 @@ export const TIMELINE_THEME = {
   longKeyAlpha: 0x1f / 255,
   longKeySelected: '#ff8c00',
   longKeySelectedAlpha: 0x99 / 255,
-  /** `.space_action.keyborder` / `keyborder_select` — `:502-503`, BOTH black
-   *  (confirmed off the running theme: `#000000ff` each). */
+  /** space_action.keyborder and keyborder_select are both black. */
   keyBorder: '#000000',
 } as const;
 
@@ -215,58 +150,13 @@ export const KEY_SIZE_FACTOR: Record<string, number> = {
   JITTER: 0.8,
   GENERATED: 0.75,
 };
-
-/**
- * THE DIAMOND, and this is the one number a lane must not re-derive by eye.
- *
- * `icon_size = widget_unit * 0.5 * yscale_fac` = 10 (`keyframes_draw.cc:218`),
- * and the SHAPE is the shader's arithmetic
- * (`gpu_shader_keyframe_shape_vert.glsl:46-66`, `outline_scale` 1 at its one
- * caller `keyframes_draw.cc:660`):
- *
- *     half_width = 0.06 + (size − 10) × 0.04        → 0.06
- *     line_width = half_width + line_falloff(1.0)   → 1.06
- *     thresholds = (max(0, line_width − 1), line_width) → (0.06, 1.06)
- *     ext_radius = round(0.5 × size) + thresholds.x → 5.06
- *     pointSize  = ceil(ext_radius + thresholds.y) × 2 + 1 → 15
- *
- * and the fragment's diamond test is an L1 ball: `radius = (|x| + |y|) ×
- * √0.5` against `radii[0] = ext_radius × √0.5`, with
- * `alpha = 1 − smoothstep(thresholds.x, thresholds.y, |outline_dist|)`. So the
- * OUTLINE is a band around L1 = 5.06 whose PERPENDICULAR half-extent is
- * `line_width` = 1.06 px, and the fill shows inside L1 ≈ 3.56.
- *
- * CONFIRMED PIXEL FOR PIXEL in Blender's frame: the sprite is 15 rows tall
- * (image rows 51…65 for a key centred at 58), the filled core is 7 rows
- * (55…61 — L1 ≤ 3.5), and the black band reaches L1 ≈ 6.5.
- *
- * WE DRAW IT as an SVG polygon of half-diagonal `DIAMOND_RADIUS` with a
- * `DIAMOND_STROKE`-wide stroke straddling it, which reproduces both extents
- * exactly — 3.56 for the fill's edge and 6.56 for the outline's. The stated
- * difference: Blender's band is a 0.06 → 1.06 smoothstep in each direction and
- * SVG has no such ramp, so the browser antialiases its own hard edges instead.
- * The INK-weighted equivalent would be 1.12 px (the integral of
- * `1 − smoothstep(0,1,u)` is exactly ½, so each side deposits 0.06 + 0.5), and
- * it would put the fill 0.7 px further out than Blender's — the extents are
- * what a parity read measures, so the extent is what is matched.
- */
-export const KEY_ICON_SIZE = 10;
 export const DIAMOND_RADIUS = 5.06;
 export const DIAMOND_STROKE = 2.12;
 /** `gl_PointSize` — the sprite Blender rasterises the shape into. Reported in
  *  the view's `state` so a parity reading can check it. */
 export const DIAMOND_SPRITE = 15;
 
-/**
- * THE PLAYHEAD — `get_playhead_dimensions` (`time_scrub_ui.cc:96-116`) and
- * `draw_playhead_box` / `draw_playhead_tip` (`:161-206`).
- *
- * CONFIRMED: a 24-px pill (22 px of flat `#4671b2` plus a pixel of
- * antialiasing each side) starting 2 px below the scrub strip's top, and a
- * 3-px stalk (`draw_playhead_stalk`'s `rect` at `UI_SCALE_FAC ≥ 0.91`:
- * `floor(x − 1) − 1` to `floor(x + 2) + 1`, of which the shadow is the outer
- * pixel on each side).
- */
+/** Playhead dimensions follow get_playhead_dimensions and draw_playhead_box/tip in time_scrub_ui.cc. */
 export const PLAYHEAD = {
   /** `box_min_width = 24 * UI_SCALE_FAC` (`:109`); a wider number grows it to
    *  `text_width + 2 * text_padding`. */
@@ -280,35 +170,25 @@ export const PLAYHEAD = {
   /** `tri_half_width` / `tri_height` = `6 * UI_SCALE_FAC` (`:113-114`). */
   tipHalfWidth: 6,
   tipHeight: 6,
-  /** The stalk's drawn core, measured: 3 px. */
+  /** The stalk’s core is 3 CSS px. */
   stalkWidth: 3,
 } as const;
 
-/**
- * `ANIM_draw_framerange` — `anim_draw.cc:172-190`: the area OUTSIDE
- * `scene.frame_start … frame_end` takes `TH_BACK` shaded −25 with alpha −100.
- * With the running theme's `#303030ff` that resolves to
- * `48 + (23 − 48) × 155/255 = 32.8`, and the frame reads `#202020` (32).
- * Drawn here as one flat colour rather than a blend, because the blend has one
- * possible answer over the region's own clear.
- */
+/** Out-of-range fill is TH_BACK shaded −25 at alpha −100 (ANIM_draw_framerange), resolved once over the opaque region clear. */
 export const OUT_OF_RANGE = '#212121';
 
 /** `.space_action.text` — `userdef_default_theme.c:492`, the status line's. */
 export const TIMELINE_CHROME = {
   text: '#a6a6a6',
   textHi: '#ffffff',
-  /** `ui.editor_border` — `#161616`, read back off the running theme. */
+  /** ui.editor_border from the running factory theme. */
   rule: '#161616',
-  /** `wcol_tool.inner` / `.text` / `.outline`, read back off the running
-   *  theme: `#545454` / `#e6e6e6` / `#3d3d3d`, roundness 0.4. A 20-px widget
-   *  therefore has a 4-px corner radius. */
+  /** wcol_tool inner/text/outline and roundness 0.4; a 20-px widget has a 4-px corner radius. */
   widget: '#545454',
   widgetText: '#e6e6e6',
   widgetOutline: '#3d3d3d',
   widgetRadius: 4,
-  /** `UI_UNIT_X` / `UI_UNIT_Y` — one `widget_unit`. Confirmed: the six
-   *  transport buttons span exactly 120 px. */
+  /** UI_UNIT_X and UI_UNIT_Y equal one widget_unit. */
   unit: WIDGET_UNIT,
   refusal: '#ffaf23',
   /** The header's own padding and the gap between its widget groups —