@headless-three/renderer 0.1.10 → 0.3.0

package/README.md

@@ -68,6 +68,37 @@ 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).
+
+For real-time media, `Renderer.createGpuFramePool()` provides asynchronous,
+bounded, reusable `rgba8unorm`, `nv12-planes`, and capability-gated
+`p010-planes` output. The YUV forms are real GPU-converted separate plane
+textures, not directly importable encoder-native multi-planar surfaces. Consult
+capabilities and the linked contract before using borrowed plane handles.
+
+```js
+const pool = renderer.createGpuFramePool({
+  width: 1920,
+  height: 1080,
+  capacity: 3,
+  format: 'nv12-planes',
+  overflow: 'drop-newest',
+})
+const frame = await pool.render(scene, camera)
+if (frame) {
+  const yTexture = frame.planeHandle(0)
+  const uvTexture = frame.planeHandle(1)
+  await consumeOnRendererDevice({ yTexture, uvTexture, planes: frame.planes })
+  // The consumer must first restore every plane to requiredStateOnRelease.
+  frame.completeExternalUse()
+  frame.release()
+}
+```
+
+These two handles are separate textures, not an encoder-native NV12 surface.
+If a handle was requested, `release()` throws until external work is complete
+and `completeExternalUse()` has acknowledged the required state restoration.
+
 `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 +153,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,190 @@
+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;
+    encoderSurface: {
+        supported: boolean;
+        reason: string;
+    };
+    mediaFormats: GpuMediaFormatCapability[];
+}
+export type GpuMediaOutputFormat = 'rgba8unorm' | 'nv12-planes' | 'p010-planes';
+export type GpuFramePoolOverflowPolicy = 'error' | 'drop-newest';
+export interface GpuMediaFormatCapability {
+    format: GpuMediaOutputFormat;
+    supported: boolean;
+    storage: 'single-texture' | 'separate-textures';
+    planeFormats: string[];
+    reason?: string;
+    colorMatrix?: 'bt709';
+    colorRange?: 'limited';
+    chromaSiting?: 'centered-2x2-box';
+}
+export interface GpuFramePoolOptions {
+    width: number;
+    height: number;
+    capacity?: number;
+    format?: GpuMediaOutputFormat;
+    overflow?: GpuFramePoolOverflowPolicy;
+}
+export interface GpuFramePoolStats {
+    capacity: number;
+    available: number;
+    inFlight: number;
+    peakInFlight: number;
+    submitted: number;
+    completed: number;
+    dropped: number;
+    rejected: number;
+    reused: number;
+    allocations: number;
+    retired: number;
+    closed: boolean;
+}
+export interface GpuMediaPlaneInfo {
+    index: number;
+    format: string;
+    width: number;
+    height: number;
+    bytesPerRow: number;
+    rowSemantics: string;
+    expectedStateBeforeUse: string;
+    requiredStateOnRelease: string;
+}
+export interface GpuMediaPlaneData extends Omit<GpuMediaPlaneInfo, 'rowSemantics' | 'expectedStateBeforeUse' | 'requiredStateOnRelease'> {
+    data: Buffer;
+}
+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;
+}
+interface NativeGpuMediaFrameLeaseLike {
+    readonly width: number;
+    readonly height: number;
+    readonly format: string;
+    readonly backend: string;
+    readonly handleType: string;
+    readonly sequence: number;
+    readonly released: boolean;
+    readonly ready: boolean;
+    planeInfo(index: number): GpuMediaPlaneInfo;
+    planeHandle(index: number): bigint;
+    readPlanes(): Promise<GpuMediaPlaneData[]>;
+    exportDmaBuf(): unknown;
+    completeExternalUse(): void;
+    release(): void;
+}
+interface NativeGpuFramePoolLike {
+    reserve(): object | null;
+    renderAsync(reservation: object, scene: unknown, camera: unknown): Promise<NativeGpuMediaFrameLeaseLike>;
+    stats(): GpuFramePoolStats;
+    close(): 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;
+}
+/** A ready, pooled media frame. Release only after all external GPU use ends. */
+export declare class GpuMediaFrameLease {
+    private readonly nativeLease;
+    constructor(nativeLease: NativeGpuMediaFrameLeaseLike);
+    get width(): number;
+    get height(): number;
+    get format(): GpuMediaOutputFormat;
+    get backend(): GpuOutputCapabilities['backend'];
+    get handleType(): GpuTextureHandleType | 'unsupported';
+    get sequence(): number;
+    get released(): boolean;
+    get ready(): boolean;
+    get planes(): GpuMediaPlaneInfo[];
+    /** Borrowed same-device texture handle for one physical plane. */
+    planeHandle(index: number): bigint;
+    /** Confirm external work ended and every plane is back in requiredStateOnRelease. */
+    completeExternalUse(): void;
+    /** Explicit diagnostic CPU readback; the normal media path performs no readback. */
+    readPlanes(): Promise<GpuMediaPlaneData[]>;
+    exportDmaBuf(): DmaBufFrameLease;
+    release(): void;
+}
+type PoolRender = (scene: ThreeSceneRootLike, camera: ThreeCameraLike, options: RenderOptions) => Promise<GpuMediaFrameLease | null>;
+/** Fixed-size reusable GPU output pool with explicit overflow and lease semantics. */
+export declare class GpuFramePool {
+    private readonly nativePool;
+    private readonly renderFrame;
+    readonly options: Required<GpuFramePoolOptions>;
+    constructor(nativePool: NativeGpuFramePoolLike, renderFrame: PoolRender, options: Required<GpuFramePoolOptions>);
+    render(scene: ThreeSceneRootLike, camera: ThreeCameraLike, options?: RenderOptions): Promise<GpuMediaFrameLease | null>;
+    /** @internal */
+    renderNative(scene: unknown, camera: unknown): Promise<GpuMediaFrameLease | null>;
+    stats(): GpuFramePoolStats;
+    close(): void;
+}
+export declare function wrapGpuOutputCapabilities(value: unknown): GpuOutputCapabilities;
+import type { RenderOptions, ThreeCameraLike, ThreeSceneRootLike } from './types';
+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":"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"}

package/dist/gpu-output.js

@@ -0,0 +1,114 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GpuFramePool = exports.GpuMediaFrameLease = 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;
+/** A ready, pooled media frame. Release only after all external GPU use ends. */
+class GpuMediaFrameLease {
+    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 sequence() { return this.nativeLease.sequence; }
+    get released() { return this.nativeLease.released; }
+    get ready() { return this.nativeLease.ready; }
+    get planes() {
+        const count = this.format === 'rgba8unorm' ? 1 : 2;
+        return Array.from({ length: count }, (_, index) => this.nativeLease.planeInfo(index));
+    }
+    /** Borrowed same-device texture handle for one physical plane. */
+    planeHandle(index) {
+        return this.nativeLease.planeHandle(index);
+    }
+    /** Confirm external work ended and every plane is back in requiredStateOnRelease. */
+    completeExternalUse() {
+        this.nativeLease.completeExternalUse();
+    }
+    /** Explicit diagnostic CPU readback; the normal media path performs no readback. */
+    readPlanes() {
+        return this.nativeLease.readPlanes();
+    }
+    exportDmaBuf() {
+        return this.nativeLease.exportDmaBuf();
+    }
+    release() { this.nativeLease.release(); }
+}
+exports.GpuMediaFrameLease = GpuMediaFrameLease;
+/** Fixed-size reusable GPU output pool with explicit overflow and lease semantics. */
+class GpuFramePool {
+    constructor(nativePool, renderFrame, options) {
+        this.nativePool = nativePool;
+        this.renderFrame = renderFrame;
+        this.options = options;
+    }
+    render(scene, camera, options = {}) {
+        return this.renderFrame(scene, camera, options);
+    }
+    /** @internal */
+    async renderNative(scene, camera) {
+        const reservation = this.nativePool.reserve();
+        if (!reservation)
+            return null;
+        const lease = await this.nativePool.renderAsync(reservation, scene, camera);
+        return new GpuMediaFrameLease(lease);
+    }
+    stats() { return this.nativePool.stats(); }
+    close() { this.nativePool.close(); }
+}
+exports.GpuFramePool = GpuFramePool;
+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":"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"}