@absolutejs/rendering 0.1.0 → 0.2.0

package/README.md

@@ -35,3 +35,22 @@ This retains onBeforeCompile, customProgramCacheKey and onBeforeRender. A regist
 Qualified against Three r186. No React dependency and no animation loop. Runtime cost is a small callback and destination check per affected draw; switching sampling modes can select another cached shader program. Hardware frame-rate improvements are not claimed. Game-specific foliage algorithms, lighting, world generation and simulation remain outside this package.
 
 Use `bun run check:package` to build declarations and run the ownership/policy tests. Browser evidence is retained under docs/.
+
+## Scoped captures and readback
+
+`renderTargetScope(renderer, run)` restores the render target, cube face, mip,
+viewport, scissor and scissor-test state even if synchronous work throws. The
+callback must finish renderer mutations synchronously; do not hold a scope over
+an await.
+
+`readTargetPixelsScoped(renderer, target, width, height, buffer, textureIndex?)`
+submits a byte/float read from a neutral target and restores the caller through
+Three's target setter. This avoids restoring a resolve framebuffer in place of
+its multisample draw attachment, or treating a cube framebuffer array as a single
+framebuffer.
+
+`readFloatTargetScoped(...)` submits asynchronous float readback in the same
+neutral state, restores the caller immediately, and returns the exact supplied
+Float32Array on completion. It never restores stale renderer state after await.
+Allocate supported targets and correctly sized buffers before calling these
+helpers. The helpers do not choose formats, sample counts or capture resolution.

package/dist/index.d.ts

@@ -11,3 +11,4 @@ export declare function bindAlphaToCoverageDestination(material: Material, enabl
  * Destination policy is cloned independently so changing one owner's preference
  * cannot alter another. No source material is mutated. */
 export declare function cloneRenderMaterial<T extends Material>(source: T): T;
+export { renderTargetScope, readTargetPixelsScoped, readFloatTargetScoped, } from "./renderTargetScope.js";

package/dist/index.js

@@ -75,3 +75,4 @@ export function cloneRenderMaterial(source) {
         copy.onBeforeRender = source.onBeforeRender;
     return copy;
 }
+export { renderTargetScope, readTargetPixelsScoped, readFloatTargetScoped, } from "./renderTargetScope.js";

package/dist/renderTargetScope.d.ts

@@ -0,0 +1,18 @@
+import { type WebGLRenderer } from "three";
+/** Synchronous offscreen work; preserve target attachment, viewport and clipping.
+ * The callback must finish its renderer mutations before returning.
+ */
+export declare function renderTargetScope<T>(renderer: WebGLRenderer, run: () => T): T;
+/** Start an async float diagnostic with a neutral current target, then immediately
+ * restore the caller's attachment. Three's async reader restores a raw framebuffer
+ * property before awaiting; cube/mipmap targets store arrays in that property.
+ * Keeping the neutral target only for submission avoids that invalid bind without
+ * holding renderer state across the asynchronous wait.
+ */
+export declare function readFloatTargetScoped(renderer: WebGLRenderer, target: import("three").WebGLRenderTarget, width: number, height: number, buffer: Float32Array, textureIndex?: number): Promise<Float32Array>;
+/** Synchronous authoring/diagnostic read. Three restores the raw resolve
+ * framebuffer, not a current target's multisample attachment, after reading.
+ * Submit from a neutral target and let setRenderTarget restore the actual
+ * attachment; otherwise the next draw can resolve stale samples over new data.
+ * This also avoids restoring cube/mip framebuffer arrays as a framebuffer. */
+export declare function readTargetPixelsScoped(renderer: WebGLRenderer, target: import("three").WebGLRenderTarget, width: number, height: number, buffer: Uint8Array | Float32Array, textureIndex?: number): void;

package/dist/renderTargetScope.js

@@ -0,0 +1,47 @@
+import { Vector4 } from "three";
+/** Synchronous offscreen work; preserve target attachment, viewport and clipping.
+ * The callback must finish its renderer mutations before returning.
+ */
+export function renderTargetScope(renderer, run) {
+    const target = renderer.getRenderTarget(), face = renderer.getActiveCubeFace(), mip = renderer.getActiveMipmapLevel();
+    const viewport = renderer.getViewport(new Vector4()), scissor = renderer.getScissor(new Vector4()), test = renderer.getScissorTest();
+    try {
+        renderer.setScissorTest(false);
+        return run();
+    }
+    finally {
+        renderer.setRenderTarget(target, face, mip);
+        renderer.setViewport(viewport);
+        renderer.setScissor(scissor);
+        renderer.setScissorTest(test);
+    }
+}
+/** Start an async float diagnostic with a neutral current target, then immediately
+ * restore the caller's attachment. Three's async reader restores a raw framebuffer
+ * property before awaiting; cube/mipmap targets store arrays in that property.
+ * Keeping the neutral target only for submission avoids that invalid bind without
+ * holding renderer state across the asynchronous wait.
+ */
+export function readFloatTargetScoped(renderer, target, width, height, buffer, textureIndex = 0) {
+    let pending;
+    renderTargetScope(renderer, () => {
+        renderer.setRenderTarget(null);
+        pending = renderer.readRenderTargetPixelsAsync(target, 0, 0, width, height, buffer, undefined, textureIndex);
+    });
+    return pending.then((value) => {
+        if (value !== buffer)
+            throw new Error("Float target read did not return its buffer");
+        return buffer;
+    });
+}
+/** Synchronous authoring/diagnostic read. Three restores the raw resolve
+ * framebuffer, not a current target's multisample attachment, after reading.
+ * Submit from a neutral target and let setRenderTarget restore the actual
+ * attachment; otherwise the next draw can resolve stale samples over new data.
+ * This also avoids restoring cube/mip framebuffer arrays as a framebuffer. */
+export function readTargetPixelsScoped(renderer, target, width, height, buffer, textureIndex = 0) {
+    renderTargetScope(renderer, () => {
+        renderer.setRenderTarget(null);
+        renderer.readRenderTargetPixels(target, 0, 0, width, height, buffer, undefined, textureIndex);
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@absolutejs/rendering",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Render-destination coverage policies and callback-preserving material ownership for Three.js applications.",
   "type": "module",
   "main": "./dist/index.js",