@volter/editor-threejs 0.5.190 → 0.5.191

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@volter/editor-threejs",
   "author": "Volter AI, Inc.",
-  "version": "0.5.190",
+  "version": "0.5.191",
   "publishConfig": {
     "access": "public"
   },
@@ -135,12 +135,12 @@
     "serving": "./dist-node/serving.mjs"
   },
   "dependencies": {
-    "@volter/editor-project": "0.5.190",
+    "@volter/editor-project": "0.5.191",
     "@sparkjsdev/spark": "^2.1.0",
     "three.quarks": "^0.16.0",
     "zod": "^4.3.6",
     "typescript": "5.9.3",
-    "@volter/editor-sdk": "0.5.190",
+    "@volter/editor-sdk": "0.5.191",
     "postprocessing": "6.38.3",
     "quarks.core": "0.16.0",
     "@fortawesome/free-solid-svg-icons": "^7.2.0"

package/src/capture/linear-resolve.ts

@@ -0,0 +1,40 @@
+import * as THREE from 'three';
+import {FullScreenQuad} from 'three/addons/postprocessing/Pass.js';
+
+let quad: FullScreenQuad | null = null;
+let material: THREE.RawShaderMaterial | null = null;
+
+/** The capture renders exactly 2x in each axis. Linear filtering at a pixel's
+ * center averages its four scene-linear samples BEFORE the nonlinear display
+ * transform. Downsampling display-encoded canvas pixels darkens color edges.
+ * The caller owns the returned target; input and associated alpha stay intact. */
+export function resolveSceneLinearSize(
+  renderer: THREE.WebGLRenderer,
+  input: THREE.WebGLRenderTarget,
+  width: number,
+  height: number,
+): THREE.WebGLRenderTarget {
+  if (input.width !== width * 2 || input.height !== height * 2)
+    throw new Error('Linear capture resolve requires a 2x scene target');
+  material ??= new THREE.RawShaderMaterial({
+    uniforms: {frame: {value:null}, texel: {value:new THREE.Vector2()}},
+    depthTest:false, depthWrite:false, blending:THREE.NoBlending,
+    vertexShader:`precision highp float; attribute vec3 position; attribute vec2 uv;
+      varying vec2 vUv; void main(){vUv=uv;gl_Position=vec4(position,1.0);}`,
+    fragmentShader:`precision highp float; uniform sampler2D frame; uniform vec2 texel; varying vec2 vUv;
+      void main(){
+        gl_FragColor=(texture2D(frame,vUv+texel*vec2(-.5,-.5))+
+          texture2D(frame,vUv+texel*vec2(.5,-.5))+
+          texture2D(frame,vUv+texel*vec2(-.5,.5))+
+          texture2D(frame,vUv+texel*vec2(.5,.5)))*.25;
+      }`,
+  });
+  quad ??= new FullScreenQuad(material);
+  material.uniforms['frame']!.value=input.texture;
+  material.uniforms['texel']!.value.set(1/input.width,1/input.height);
+  const output=new THREE.WebGLRenderTarget(width,height,{type:THREE.HalfFloatType});
+  const previous=renderer.getRenderTarget();
+  try { renderer.setRenderTarget(output); quad.render(renderer); return output; }
+  catch(error) { output.dispose(); throw error; }
+  finally { renderer.setRenderTarget(previous); }
+}

package/src/capture/scene.ts

@@ -3,6 +3,8 @@
 import * as THREE from 'three';
 import { acquireInspectorPreviewRenderer } from '../viewport/preview-renderer';
 import { viewportCaptureOutputPass } from './output-pass';
+import type { DocumentDisplayTransform } from '../render/document-display-transform';
+import {resolveSceneLinearSize} from './linear-resolve';
 
 export interface SceneCaptureOptions {
   width: number;
@@ -10,6 +12,8 @@ export interface SceneCaptureOptions {
   transparent?: boolean;
   toneMapping?: THREE.ToneMapping;
   exposure?: number;
+  /** Integration-owned GPU display resolve, shared with its live viewport. */
+  displayTransform?: DocumentDisplayTransform;
   /** Caller-owned scene-linear effect. The input carries a depth texture;
    * the returned target remains caller-owned and must contain half floats. */
   effect?: {
@@ -69,6 +73,7 @@ function capture(
   };
   let hdr: THREE.WebGLRenderTarget | undefined;
   let display: THREE.WebGLRenderTarget | undefined;
+  let displayInput: THREE.WebGLRenderTarget | undefined;
   let completed = false;
   try {
     hdr = new THREE.WebGLRenderTarget(renderWidth, renderHeight, { type: THREE.HalfFloatType });
@@ -92,26 +97,24 @@ function capture(
       completed = true;
       return { pixels, width, height };
     }
-    display = new THREE.WebGLRenderTarget(renderWidth, renderHeight);
-    viewportCaptureOutputPass(options.transparent === true).render(
-      renderer,
-      display,
-      resolved,
-      0,
-      false,
-    );
-    const pixels = new Uint8Array(renderWidth * renderHeight * 4);
-    renderer.readRenderTargetPixels(display, 0, 0, renderWidth, renderHeight, pixels);
+    display = new THREE.WebGLRenderTarget(options.displayTransform ? width : renderWidth, options.displayTransform ? height : renderHeight);
+    if (options.displayTransform) {
+      displayInput=resolveSceneLinearSize(renderer,resolved,width,height);
+      options.displayTransform.render(renderer, displayInput, display, options.transparent === true);
+    }
+    else viewportCaptureOutputPass(options.transparent === true).render(renderer, display, resolved, 0, false);
+    const pixels = new Uint8Array(display.width * display.height * 4);
+    renderer.readRenderTargetPixels(display, 0, 0, display.width, display.height, pixels);
     const full = document.createElement('canvas');
-    full.width = renderWidth;
-    full.height = renderHeight;
+    full.width = display.width;
+    full.height = display.height;
     const context = full.getContext('2d');
     if (!context) throw new Error('Scene capture could not create an image canvas');
-    const image = context.createImageData(renderWidth, renderHeight);
-    const stride = renderWidth * 4;
-    for (let y = 0; y < renderHeight; y++)
+    const image = context.createImageData(display.width, display.height);
+    const stride = display.width * 4;
+    for (let y = 0; y < display.height; y++)
       image.data.set(
-        pixels.subarray((renderHeight - 1 - y) * stride, (renderHeight - y) * stride),
+        pixels.subarray((display.height - 1 - y) * stride, (display.height - y) * stride),
         y * stride,
       );
     context.putImageData(image, 0, 0);
@@ -134,6 +137,7 @@ function capture(
     renderer.shadowMap.type = previous.shadowType;
     renderer.setClearColor(previous.clearColor, previous.clearAlpha);
     display?.dispose();
+    displayInput?.dispose();
     hdr?.dispose();
     lease.release({ discard: !completed });
   }
@@ -154,3 +158,30 @@ export function captureSceneImage(
 ): string {
   return capture(scene, camera, options, false);
 }
+
+/** Resolve a compositor/EXR frame through the SAME GPU display pipeline as
+ * the document. The input stays scene-linear; only the returned bytes are
+ * display encoded. Pixels retain GL's bottom-up ordering. */
+export function resolveSceneLinearDisplay(
+  frame: LinearCaptureFrame,
+  transform: DocumentDisplayTransform,
+): Uint8Array {
+  const lease = acquireInspectorPreviewRenderer();
+  const renderer = lease.renderer;
+  const previous = renderer.getRenderTarget();
+  const input = new THREE.DataTexture(frame.pixels, frame.width, frame.height, THREE.RGBAFormat, THREE.HalfFloatType);
+  input.needsUpdate = true;
+  const output = new THREE.WebGLRenderTarget(frame.width, frame.height);
+  let completed = false;
+  try {
+    transform.render(renderer, {texture: input}, output, true);
+    const pixels = new Uint8Array(frame.width * frame.height * 4);
+    renderer.readRenderTargetPixels(output, 0, 0, frame.width, frame.height, pixels);
+    completed = true;
+    return pixels;
+  } finally {
+    renderer.setRenderTarget(previous);
+    input.dispose(); output.dispose();
+    lease.release({discard: !completed});
+  }
+}

package/src/kit/authoring/object3d-document-session.ts

@@ -3,6 +3,7 @@ import { resetViewPresentation, setViewPresentation, type ViewportXray } from '@
 import { invalidateStages } from '@volter/editor-sdk/kit/stage-invalidation';
 import type { AuthoringAdapter } from '@volter/editor-project/adapter';
 import { viewportCaptureOutputPass } from '@volter/editor-threejs/capture/output-pass';
+import { resolveSceneLinearSize } from '@volter/editor-threejs/capture/linear-resolve';
 import { contentWorldBounds } from '@volter/editor-threejs/viewport/content-bounds';
 import { setUserData } from '@volter/editor-threejs/ecs/user-data';
 import {
@@ -13,6 +14,7 @@ import {
 import type { EffectComposer, EffectPass, RenderPass } from 'postprocessing';
 import * as THREE from 'three';
 import { DepthDrawMaterials } from '../../render/depth-draw-materials';
+import type { DocumentDisplayTransform } from '../../render/document-display-transform';
 import { threeObject } from '../../adapter/three-contract';
 import { axisViewName, cameraPresetDirection, type ModelCameraPreset } from '../asset-workflow/model-inspection';
 import { activeKeymapNavigation } from '@volter/editor-sdk/kit/keymap-presets';
@@ -127,6 +129,25 @@ export class Object3DDocumentSession {
   private boneSelectionHighlight: BoneSelectionHighlight | null = null;
   private boneSelectionSignature = '';
   private composer: EffectComposer | null = null;
+  private displayTransform: DocumentDisplayTransform | null = null;
+  private displayTarget: THREE.WebGLRenderTarget | null = null;
+
+  /** Authoring diagnostics retain their studio display; authored materials
+   * and scene-lit views use the integration's color pipeline. */
+  setDisplayTransform(transform: DocumentDisplayTransform | null): void {
+    if (this.displayTransform === transform) return;
+    this.displayTransform = transform;
+    if (!transform) {
+      this.displayTarget?.dispose();
+      this.displayTarget = null;
+    }
+    invalidateStages();
+  }
+
+  private materialDisplayTransform(): DocumentDisplayTransform | null {
+    return this.state.mode === 'rendered' || this.state.mode === 'preview'
+      ? this.displayTransform : null;
+  }
   /** One in-flight `import('postprocessing')` at a time — {@link ensureComposer}
    *  is called from every frame. */
   private composerLoading = false;
@@ -1406,6 +1427,24 @@ export class Object3DDocumentSession {
   renderViewport(deltaSeconds = 0, interactive = false): void {
     this.advanceLook(deltaSeconds);
     this.ensureComposer();
+    const transform = this.materialDisplayTransform();
+    if (transform) {
+      const size = this.renderer.getDrawingBufferSize(new THREE.Vector2());
+      const target = this.displayTarget ??= new THREE.WebGLRenderTarget(size.x, size.y, {
+        type: THREE.HalfFloatType,
+        samples: 4,
+      });
+      target.setSize(size.x, size.y);
+      const previous = this.renderer.getRenderTarget();
+      try {
+        this.renderer.setRenderTarget(target);
+        this.render(camera => this.renderLinearScene(camera, target), interactive);
+        transform.render(this.renderer, target, previous, false);
+      } finally {
+        this.renderer.setRenderTarget(previous);
+      }
+      return;
+    }
     this.render((camera) => {
       const composer = this.composer;
       if (!composer) {
@@ -1491,7 +1530,9 @@ export class Object3DDocumentSession {
     const sceneTarget = new THREE.WebGLRenderTarget(renderWidth, renderHeight, {
       type: THREE.HalfFloatType,
     });
-    const target = new THREE.WebGLRenderTarget(renderWidth, renderHeight);
+    const transform = this.materialDisplayTransform();
+    const target = new THREE.WebGLRenderTarget(transform ? outputWidth : renderWidth, transform ? outputHeight : renderHeight);
+    let resolved: THREE.WebGLRenderTarget | null = null;
     const previousTarget = this.renderer.getRenderTarget();
     const previousPixelRatio = this.renderer.getPixelRatio();
     const perspective = this.viewport.camera;
@@ -1510,25 +1551,24 @@ export class Object3DDocumentSession {
         (camera) => this.renderSolidForCapture(camera, sceneTarget, renderWidth, renderHeight),
         typeof size !== 'number' && size.transparent === true,
       );
-      viewportCaptureOutputPass(typeof size !== 'number' && size.transparent === true).render(
-        this.renderer,
-        target,
-        sceneTarget,
-        0,
-        false,
-      );
+      const straightAlpha = typeof size !== 'number' && size.transparent === true;
+      if (transform) {
+        resolved = resolveSceneLinearSize(this.renderer, sceneTarget, outputWidth, outputHeight);
+        transform.render(this.renderer, resolved, target, straightAlpha);
+      }
+      else viewportCaptureOutputPass(straightAlpha).render(this.renderer, target, sceneTarget, 0, false);
 
-      const rowBytes = renderWidth * 4;
-      const pixels = new Uint8Array(rowBytes * renderHeight);
-      this.renderer.readRenderTargetPixels(target, 0, 0, renderWidth, renderHeight, pixels);
+      const rowBytes = target.width * 4;
+      const pixels = new Uint8Array(rowBytes * target.height);
+      this.renderer.readRenderTargetPixels(target, 0, 0, target.width, target.height, pixels);
       const fullCanvas = document.createElement('canvas');
-      fullCanvas.width = renderWidth;
-      fullCanvas.height = renderHeight;
+      fullCanvas.width = target.width;
+      fullCanvas.height = target.height;
       const fullContext = fullCanvas.getContext('2d');
       if (!fullContext) return null;
-      const imageData = fullContext.createImageData(renderWidth, renderHeight);
-      for (let y = 0; y < renderHeight; y++) {
-        const sourceRow = (renderHeight - 1 - y) * rowBytes;
+      const imageData = fullContext.createImageData(target.width, target.height);
+      for (let y = 0; y < target.height; y++) {
+        const sourceRow = (target.height - 1 - y) * rowBytes;
         const destinationRow = y * rowBytes;
         imageData.data.set(pixels.subarray(sourceRow, sourceRow + rowBytes), destinationRow);
       }
@@ -1555,6 +1595,7 @@ export class Object3DDocumentSession {
       // selection and 4 after a repaint that resized.
       this.composer?.setSize(this.renderWidth, this.renderHeight, false);
       target.dispose();
+      resolved?.dispose();
       sceneTarget.dispose();
       // AND THE VIEW IS DRAWN AGAIN. Sizing the composer clears what the view showed, and a stage
       // that draws on demand had nothing asking it to: on the browser-substrate page every photograph
@@ -1583,6 +1624,9 @@ export class Object3DDocumentSession {
     if (this.selectionOutline)
       releaseThreeSelectionOutline(this.renderer, this.selectionOutline, this.selectionOutlinePass);
     this.composer?.dispose();
+    this.displayTarget?.dispose();
+    this.displayTarget = null;
+    this.displayTransform = null;
     this.sceneRenderPass = null;
     this.selectionOutline = null;
     this.selectionOutlinePass = null;
@@ -1673,7 +1717,9 @@ export class Object3DDocumentSession {
         this.composerLoading = false;
         if (this.disposed || this.composer) return;
         const camera = this.camera();
-        const composer = new postprocessing.EffectComposer(this.renderer);
+        const composer = new postprocessing.EffectComposer(this.renderer, {
+          frameBufferType: THREE.HalfFloatType,
+        });
         this.sceneRenderPass = new postprocessing.RenderPass(this.scene, camera);
         composer.addPass(this.sceneRenderPass);
         this.selectionOutline = acquireThreeSelectionOutline(
@@ -1739,14 +1785,32 @@ export class Object3DDocumentSession {
     }
     const previousWidth = this.renderWidth;
     const previousHeight = this.renderHeight;
+    try {
+      composer.setSize(width, height, false);
+      this.renderLinearScene(camera, target);
+    } finally {
+      composer.setSize(previousWidth, previousHeight, false);
+      this.syncComposerOutput();
+      this.renderer.setRenderTarget(target);
+    }
+  }
+
+  /** Live HDR draw at the renderer's CURRENT size. Resizing the composer with
+   * device pixels here would resize the canvas and multiply HiDPI twice on
+   * every frame. Only an offscreen photograph changes its sizing. */
+  private renderLinearScene(camera: THREE.Camera, target: THREE.WebGLRenderTarget): void {
+    const composer = this.composer;
+    const outlined = (this.selectionOutline?.selection.size ?? 0) > 0;
+    if (!composer || !outlined || !this.sceneRenderPass || !this.selectionOutlinePass) {
+      this.renderer.render(this.scene, camera);
+      return;
+    }
     try {
       this.sceneRenderPass.renderToScreen = false;
       this.selectionOutlinePass.renderToScreen = false;
-      composer.setSize(width, height, false);
       this.sceneRenderPass.render(this.renderer, composer.inputBuffer, composer.outputBuffer, 0);
       this.selectionOutlinePass.render(this.renderer, composer.inputBuffer, target, 0);
     } finally {
-      composer.setSize(previousWidth, previousHeight, false);
       this.syncComposerOutput();
       this.renderer.setRenderTarget(target);
     }

package/src/render/document-display-transform.ts

@@ -0,0 +1,14 @@
+import type * as THREE from 'three';
+
+/** An integration's scene-linear to display resolve. The stage owns its HDR
+ * input; the integration owns the transform and its GPU resources. Output is
+ * already display encoded, with associated alpha for the canvas and straight
+ * alpha for a transparent photograph. No readback belongs on this path. */
+export interface DocumentDisplayTransform {
+  render(
+    renderer: THREE.WebGLRenderer,
+    input: Pick<THREE.WebGLRenderTarget, 'texture'>,
+    output: THREE.WebGLRenderTarget | null,
+    straightAlpha: boolean,
+  ): void;
+}