@headless-three/renderer 0.1.10 → 0.2.0

package/README.md

@@ -68,6 +68,8 @@ const imageBuffer = renderer.render(scene, camera, { width: 512, height: 512 })
 
 `Renderer.renderAsync(scene, camera, options)` is a Promise-returning compatibility wrapper around the same scene-output contract.
 
+`Renderer.renderGpuFrame(scene, camera, options)` returns a same-device GPU texture lease without RGBA readback when `Renderer.getGpuOutputCapabilities().texture.supported` is true. Native handles are borrowed `bigint` values and must be released deterministically. See the [GPU-native output contract](https://github.com/portwatcher/headless-three-renderer/blob/main/docs/gpu-native-output.md).
+
 `Renderer.sortObjects`, `Renderer.opaque`, `Renderer.transparent`, `Renderer.setOpaqueSort(fn)`, `Renderer.setTransparentSort(fn)`, and the matching `render()` options (`sortObjects`, `opaque`, `transparent`, `opaqueSort`, `transparentSort`) control native draw-list sorting and bucket inclusion.
 
 It also exports Node loader helpers:
@@ -122,6 +124,7 @@ Install the main package, not the platform package directly.
 - [Compatibility matrix](https://github.com/portwatcher/headless-three-renderer/blob/main/docs/compatibility.md)
 - [Node loader setup](https://github.com/portwatcher/headless-three-renderer/blob/main/docs/node-loader-setup.md)
 - [Scale budgets](https://github.com/portwatcher/headless-three-renderer/blob/main/docs/scale-budgets.md)
+- [GPU-native output](https://github.com/portwatcher/headless-three-renderer/blob/main/docs/gpu-native-output.md)
 - [Release notes](https://github.com/portwatcher/headless-three-renderer/blob/main/docs/release-notes.md)
 - [glTF example](https://github.com/portwatcher/headless-three-renderer/blob/main/examples/render-gltf.mjs)
 - [VRM/VRMA example](https://github.com/portwatcher/headless-three-renderer/blob/main/examples/render-vrm.mjs)

package/dist/gpu-output.d.ts

@@ -0,0 +1,81 @@
+export type GpuTextureHandleType = 'metal-texture' | 'vulkan-image' | 'd3d12-resource';
+export interface GpuTextureOutputCapability {
+    supported: boolean;
+    handleType?: GpuTextureHandleType;
+    synchronization: 'submission-complete';
+    scope: 'same-renderer-device';
+    format: 'rgba8unorm';
+    usage: 'copy-dst|copy-src|texture-binding';
+    layout: 'backend-managed-copy-dst';
+    reason?: string;
+}
+export interface DmaBufOutputCapability {
+    supported: boolean;
+    reason?: string;
+}
+export interface GpuOutputCapabilities {
+    backend: 'metal' | 'vulkan' | 'dx12' | 'gles' | 'browser-webgpu' | 'noop';
+    texture: GpuTextureOutputCapability;
+    dmaBuf: DmaBufOutputCapability;
+}
+export interface DmaBufPlane {
+    fd: number;
+    offset: number;
+    stride: number;
+}
+export interface DmaBufFrameLease {
+    width: number;
+    height: number;
+    fourcc: number;
+    modifier: bigint;
+    planes: DmaBufPlane[];
+    released: boolean;
+    release(): void;
+}
+interface NativeGpuFrameLeaseLike {
+    readonly width: number;
+    readonly height: number;
+    readonly format: string;
+    readonly backend: string;
+    readonly handleType: string;
+    readonly released: boolean;
+    readonly completed: boolean;
+    readonly scope: string;
+    readonly usage: string;
+    readonly layout: string;
+    nativeHandle(): bigint;
+    exportDmaBuf(): unknown;
+    release(): void;
+}
+/**
+ * Owns one rendered GPU texture and controls the lifetime of its borrowed
+ * native handle. Call `release()` in a `finally` block when interop completes.
+ */
+export declare class GpuFrameLease {
+    private readonly nativeLease;
+    constructor(nativeLease: NativeGpuFrameLeaseLike);
+    get width(): number;
+    get height(): number;
+    get format(): 'rgba8unorm';
+    get backend(): GpuOutputCapabilities['backend'];
+    get handleType(): GpuTextureHandleType;
+    get released(): boolean;
+    get completed(): true;
+    get scope(): 'same-renderer-device';
+    get usage(): 'copy-dst|copy-src|texture-binding';
+    get layout(): 'backend-managed-copy-dst';
+    /**
+     * Returns a borrowed MTLTexture*, VkImage, or ID3D12Resource* bigint.
+     * It is valid only for integrations already using this renderer's native
+     * device/context. Never destroy it, use it after release, or access/transition
+     * it concurrently with renderer work.
+     */
+    nativeHandle(): bigint;
+    /** Export an owned DMA-BUF descriptor when `capabilities.dmaBuf.supported`. */
+    exportDmaBuf(): DmaBufFrameLease;
+    /** Idempotently invalidates the borrowed handle and drops the GPU texture. */
+    release(): void;
+}
+export declare function wrapGpuOutputCapabilities(value: unknown): GpuOutputCapabilities;
+export {};
+//# sourceMappingURL=gpu-output.d.ts.map

package/dist/gpu-output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gpu-output.d.ts","sourceRoot":"","sources":["../api/gpu-output.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,oBAAoB,GAAG,eAAe,GAAG,cAAc,GAAG,gBAAgB,CAAA;AAEtF,MAAM,WAAW,0BAA0B;IACzC,SAAS,EAAE,OAAO,CAAA;IAClB,UAAU,CAAC,EAAE,oBAAoB,CAAA;IACjC,eAAe,EAAE,qBAAqB,CAAA;IACtC,KAAK,EAAE,sBAAsB,CAAA;IAC7B,MAAM,EAAE,YAAY,CAAA;IACpB,KAAK,EAAE,mCAAmC,CAAA;IAC1C,MAAM,EAAE,0BAA0B,CAAA;IAClC,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,sBAAsB;IACrC,SAAS,EAAE,OAAO,CAAA;IAClB,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,OAAO,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,gBAAgB,GAAG,MAAM,CAAA;IACzE,OAAO,EAAE,0BAA0B,CAAA;IACnC,MAAM,EAAE,sBAAsB,CAAA;CAC/B;AAED,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAA;IACV,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,WAAW,EAAE,CAAA;IACrB,QAAQ,EAAE,OAAO,CAAA;IACjB,OAAO,IAAI,IAAI,CAAA;CAChB;AAED,UAAU,uBAAuB;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;IAC1B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,YAAY,IAAI,MAAM,CAAA;IACtB,YAAY,IAAI,OAAO,CAAA;IACvB,OAAO,IAAI,IAAI,CAAA;CAChB;AAED;;;GAGG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAyB;gBAEzC,WAAW,EAAE,uBAAuB;IAIhD,IAAI,KAAK,IAAI,MAAM,CAAkC;IACrD,IAAI,MAAM,IAAI,MAAM,CAAmC;IACvD,IAAI,MAAM,IAAI,YAAY,CAAmD;IAC7E,IAAI,OAAO,IAAI,qBAAqB,CAAC,SAAS,CAAC,CAE9C;IACD,IAAI,UAAU,IAAI,oBAAoB,CAErC;IACD,IAAI,QAAQ,IAAI,OAAO,CAAqC;IAC5D,IAAI,SAAS,IAAI,IAAI,CAA8C;IACnE,IAAI,KAAK,IAAI,sBAAsB,CAA4D;IAC/F,IAAI,KAAK,IAAI,mCAAmC,CAE/C;IACD,IAAI,MAAM,IAAI,0BAA0B,CAEvC;IAED;;;;;OAKG;IACH,YAAY,IAAI,MAAM;IAItB,+EAA+E;IAC/E,YAAY,IAAI,gBAAgB;IAIhC,8EAA8E;IAC9E,OAAO,IAAI,IAAI;CAGhB;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,qBAAqB,CAE/E"}

package/dist/gpu-output.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GpuFrameLease = void 0;
+exports.wrapGpuOutputCapabilities = wrapGpuOutputCapabilities;
+/**
+ * Owns one rendered GPU texture and controls the lifetime of its borrowed
+ * native handle. Call `release()` in a `finally` block when interop completes.
+ */
+class GpuFrameLease {
+    constructor(nativeLease) {
+        this.nativeLease = nativeLease;
+    }
+    get width() { return this.nativeLease.width; }
+    get height() { return this.nativeLease.height; }
+    get format() { return this.nativeLease.format; }
+    get backend() {
+        return this.nativeLease.backend;
+    }
+    get handleType() {
+        return this.nativeLease.handleType;
+    }
+    get released() { return this.nativeLease.released; }
+    get completed() { return this.nativeLease.completed; }
+    get scope() { return this.nativeLease.scope; }
+    get usage() {
+        return this.nativeLease.usage;
+    }
+    get layout() {
+        return this.nativeLease.layout;
+    }
+    /**
+     * Returns a borrowed MTLTexture*, VkImage, or ID3D12Resource* bigint.
+     * It is valid only for integrations already using this renderer's native
+     * device/context. Never destroy it, use it after release, or access/transition
+     * it concurrently with renderer work.
+     */
+    nativeHandle() {
+        return this.nativeLease.nativeHandle();
+    }
+    /** Export an owned DMA-BUF descriptor when `capabilities.dmaBuf.supported`. */
+    exportDmaBuf() {
+        return this.nativeLease.exportDmaBuf();
+    }
+    /** Idempotently invalidates the borrowed handle and drops the GPU texture. */
+    release() {
+        this.nativeLease.release();
+    }
+}
+exports.GpuFrameLease = GpuFrameLease;
+function wrapGpuOutputCapabilities(value) {
+    return value;
+}
+//# sourceMappingURL=gpu-output.js.map

package/dist/gpu-output.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gpu-output.js","sourceRoot":"","sources":["../api/gpu-output.ts"],"names":[],"mappings":";;;AA2GA,8DAEC;AArDD;;;GAGG;AACH,MAAa,aAAa;IAGxB,YAAY,WAAoC;QAC9C,IAAI,CAAC,WAAW,GAAG,WAAW,CAAA;IAChC,CAAC;IAED,IAAI,KAAK,KAAa,OAAO,IAAI,CAAC,WAAW,CAAC,KAAK,CAAA,CAAC,CAAC;IACrD,IAAI,MAAM,KAAa,OAAO,IAAI,CAAC,WAAW,CAAC,MAAM,CAAA,CAAC,CAAC;IACvD,IAAI,MAAM,KAAmB,OAAO,IAAI,CAAC,WAAW,CAAC,MAAsB,CAAA,CAAC,CAAC;IAC7E,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,WAAW,CAAC,OAA2C,CAAA;IACrE,CAAC;IACD,IAAI,UAAU;QACZ,OAAO,IAAI,CAAC,WAAW,CAAC,UAAkC,CAAA;IAC5D,CAAC;IACD,IAAI,QAAQ,KAAc,OAAO,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAA,CAAC,CAAC;IAC5D,IAAI,SAAS,KAAW,OAAO,IAAI,CAAC,WAAW,CAAC,SAAiB,CAAA,CAAC,CAAC;IACnE,IAAI,KAAK,KAA6B,OAAO,IAAI,CAAC,WAAW,CAAC,KAA+B,CAAA,CAAC,CAAC;IAC/F,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,WAAW,CAAC,KAA4C,CAAA;IACtE,CAAC;IACD,IAAI,MAAM;QACR,OAAO,IAAI,CAAC,WAAW,CAAC,MAAoC,CAAA;IAC9D,CAAC;IAED;;;;;OAKG;IACH,YAAY;QACV,OAAO,IAAI,CAAC,WAAW,CAAC,YAAY,EAAE,CAAA;IACxC,CAAC;IAED,+EAA+E;IAC/E,YAAY;QACV,OAAO,IAAI,CAAC,WAAW,CAAC,YAAY,EAAsB,CAAA;IAC5D,CAAC;IAED,8EAA8E;IAC9E,OAAO;QACL,IAAI,CAAC,WAAW,CAAC,OAAO,EAAE,CAAA;IAC5B,CAAC;CACF;AA7CD,sCA6CC;AAED,SAAgB,yBAAyB,CAAC,KAAc;IACtD,OAAO,KAA8B,CAAA;AACvC,CAAC"}