@mediaway/device 0.1.5 → 0.1.8

package/README.md

@@ -55,24 +55,53 @@ await mic.close();
 
 ## Screen capture
 
+GPU-only, Zero-Copy — there is no CPU fallback in the wrapped Rust backend
+(`adr/0003-gpu-handle-c-abi.md` §4), so `openScreenCapture()` needs a live GPU
+device. It creates one internally by default (via the GPU device factory,
+`mediaway-device` ADR-0007):
+
 ```ts
 import { openScreenCapture } from "@mediaway/device";
 
-const screen = await openScreenCapture({
-  timeBase: { num: 1, den: 30 },
-  captureCursor: true,
-});
-const frame = screen.pollFrame(); // VideoFrame | null
+const screen = await openScreenCapture({ timeBase: { num: 1, den: 30 }, monitorIndex: 0 });
+console.log(`screen: ${screen.width}x${screen.height}`);
+const frame = screen.pollFrame(); // VideoFrame | null — data is ALWAYS empty (see below)
+await screen.close(); // also closes the internally-created GPU device
+```
+
+`pollFrame()`'s `VideoFrame.data` is always empty — it proves frames are
+genuinely arriving (real `pts`/geometry) but does not copy pixels out (no CPU
+readback path for Screen). For real pixel data, feed the session straight
+into an encoder with `EncodeSession.writeFrameFromDesktopCapture()`
+(`@mediaway/encoder`), Zero-Copy end to end — see that package's README.
+
+## GPU device factory
+
+```ts
+import { listGpuAdapters, GpuDevice, openScreenCapture } from "@mediaway/device";
+
+const adapters = listGpuAdapters(); // name, vendorId, deviceId, dedicatedVideoMemoryBytes, isHardware
+const device = await GpuDevice.create({ adapterIndex: adapters[0].index });
+
+// Share one device across capture and encode (see @mediaway/encoder):
+const screen = await openScreenCapture({ timeBase: { num: 1, den: 30 }, gpuDevice: device });
+// ... screen.close() leaves `device` open since you supplied it — close it yourself:
 await screen.close();
+device.close();
 ```
 
+Omit `adapterIndex` (or the whole `options` object) for the first hardware
+adapter DXGI reports.
+
 ## API
 
 | Function | Session | Frames |
 | --- | --- | --- |
 | `openCamera({ index, timeBase })` | `CameraSession` (`width`, `height`, `pixelFormat` = `"nv12"`) | `pollFrame(): VideoFrame \| null` |
 | `openMicrophone({ sampleRate, channels })` | `MicSession` (`sampleRate`, `channels`) | `pollFrame(): AudioFrame \| null` |
-| `openScreenCapture({ timeBase, captureCursor? })` | `ScreenSession` | `pollFrame(): VideoFrame \| null` |
+| `openScreenCapture({ timeBase, monitorIndex?, gpuDevice? })` | `ScreenSession` | `pollFrame(): VideoFrame \| null` (`data` always empty) |
+| `listGpuAdapters()` | — | `GpuAdapterInfo[]` |
+| `GpuDevice.create({ adapterIndex?, videoSupport?, debugLayer? })` | `GpuDevice` | — |
 
 Every session's `close()` is async (joins the backend worker thread).
 `CaptureUnavailableError` signals a missing device.

package/dist/index.d.ts

@@ -1,16 +1,28 @@
 /**
- * @mediaway/device — device capability: camera / screen / microphone capture.
+ * @mediaway/device — device capability: camera / screen / microphone capture,
+ * plus the GPU device factory (mediaway-device ADR-0007).
  *
  * Implements the DX contract in bindings/nodejs/README.md over the
  * mediaway-ffi C ABI (via @mediaway/ffi). The ABI is domain-split
- * (`adr/0004-domain-feature-split.md`): this package folds it back into the
- * three DX functions. CPU-storage only: Camera delivers CPU frames; Screen
- * capture raises CaptureUnavailableError from the C ABI today (it needs a
- * live GPU device handle with no CPU fallback). Audio capture delivers raw
+ * (`adr/0004-domain-feature-split.md`): this package folds it back into DX
+ * functions. Camera delivers CPU frames; Screen capture is GPU-only, Zero-Copy
+ * — it needs a live GPU device handle with no CPU fallback
+ * (`adr/0003-gpu-handle-c-abi.md`), which `openScreenCapture()` now gets from
+ * `GpuDevice` (auto-created, or caller-supplied for explicit adapter control
+ * / sharing one device across capture + encode). Audio capture delivers raw
  * interleaved f32le PCM — there is no audio encoder in the ABI.
  */
+import { type RawGpuDeviceHandle } from "@mediaway/ffi";
 import { MediawayError, type Rational } from "@mediaway/container";
 export type { Rational } from "@mediaway/container";
+/**
+ * @internal Key for the opaque native handle behind a capture/GPU-device
+ * session, consumed only by @mediaway/encoder's capture-to-encode bridge
+ * (`EncodeSession.writeFrameFromCameraCapture`/`writeFrameFromDesktopCapture`)
+ * and by `AutoVideoEncodeConfig.gpuDevice`. Not part of the public DX
+ * contract — never read this directly.
+ */
+export declare const NATIVE_HANDLE: unique symbol;
 export interface VideoFrame {
     pts: number;
     duration: number;
@@ -46,6 +58,8 @@ export declare class CameraSession {
     pollFrame(): VideoFrame | null;
     /** Joins the backend worker thread — can block up to one frame interval. */
     close(): Promise<void>;
+    /** @internal */
+    [NATIVE_HANDLE](): unknown;
 }
 /** Open camera `index` at `timeBase`; throws CaptureUnavailableError when no
  * camera exists on this machine. */
@@ -71,25 +85,90 @@ export declare function openMicrophone(options: {
     sampleRate: number;
     channels?: number;
 }): Promise<MicSession>;
+export interface GpuAdapterInfo {
+    /** Pass to `GpuDevice.create({ adapterIndex })` to select this exact adapter. */
+    index: number;
+    name: string;
+    vendorId: number;
+    deviceId: number;
+    dedicatedVideoMemoryBytes: number;
+    /** `false` for a software rasterizer adapter (e.g. WARP). */
+    isHardware: boolean;
+}
+/** List every GPU adapter this machine's DXGI factory reports. */
+export declare function listGpuAdapters(): GpuAdapterInfo[];
+export interface GpuDeviceOptions {
+    /** Explicit adapter (from `listGpuAdapters()`'s `index`); omit for the first
+     * hardware adapter DXGI reports. */
+    adapterIndex?: number;
+    /** D3D11_CREATE_DEVICE_VIDEO_SUPPORT. Default true. */
+    videoSupport?: boolean;
+    /** D3D11_CREATE_DEVICE_DEBUG. Default false. */
+    debugLayer?: boolean;
+}
+/**
+ * A real GPU device, created via the factory (no "bring your own device" path
+ * exists from JS). Pass into `openScreenCapture({ gpuDevice })` and/or
+ * `AutoVideoEncodeConfig.gpuDevice` (`@mediaway/encoder`) to share one device
+ * across capture and encode — Zero-Copy end to end. Close it after every
+ * session built from it is closed.
+ */
+export declare class GpuDevice {
+    private handle;
+    /** Wrap a native GPU device handle. Prefer the create() factory. */
+    private constructor();
+    /** Create a real GPU device. Throws CaptureUnavailableError when no usable
+     * adapter exists (e.g. headless CI without even WARP). */
+    static create(options?: GpuDeviceOptions): Promise<GpuDevice>;
+    /** Release the underlying GPU device. Every session built from it (Screen
+     * capture, encode config) becomes invalid the moment this returns. */
+    close(): void;
+    /** @internal — the `mediaway_gpu_device_handle_t` value bits, read once at
+     * create() time. Consumed by openScreenCapture() and
+     * AutoVideoEncodeConfig.gpuDevice (@mediaway/encoder). Not part of the
+     * public DX contract. */
+    [NATIVE_HANDLE](): RawGpuDeviceHandle;
+}
 /**
- * A Screen capture session — NOT available from the C ABI today. Screen needs
- * a live GPU device handle (ID3D11Device*) with no CPU fallback, and its C
- * representation is deferred (crates/mediaway-ffi/adr/0001 § Deferred),
- * so openScreenCapture always throws CaptureUnavailableError. The ideal DX
- * (BGRA8 CPU frames at the display's native geometry) is what the aspirational
- * screen-record example targets.
+ * A Screen capture session — GPU-only, Zero-Copy (`adr/0003-gpu-handle-c-abi.md`
+ * §4: no CPU fallback exists in the wrapped Rust backend, so unlike Camera
+ * there is no CPU pixel readback path here either). `pollFrame()` proves
+ * frames are genuinely arriving (real `pts`/geometry) but its `VideoFrame.data`
+ * is always empty — it does not copy pixels out. For real pixel data, feed
+ * the session straight into the encoder with
+ * `EncodeSession.writeFrameFromDesktopCapture()` (`@mediaway/encoder`), which
+ * moves the GPU texture Zero-Copy with no CPU round trip at all.
  */
 export declare class ScreenSession {
-    readonly width = 0;
-    readonly height = 0;
+    readonly width: number;
+    readonly height: number;
     readonly pixelFormat: "bgra8";
     readonly timeBase: Rational;
-    /** Screen session (always throws — no C-ABI screen path yet). */
-    constructor(timeBase: Rational);
+    private handle;
+    private readonly ownsGpuDevice;
+    /** Wrap a native desktop capture handle. Prefer the openScreenCapture() factory. */
+    constructor(handle: unknown, width: number, height: number, timeBase: Rational, ownsGpuDevice: GpuDevice | undefined);
+    /** Poll the next frame; null when nothing is ready yet. Sync, never blocks.
+     * `data` is always empty — see the class doc. */
     pollFrame(): VideoFrame | null;
+    /** Joins the backend worker thread — can block up to one frame interval.
+     * Also closes the GPU device this session created internally (auto mode);
+     * a caller-supplied device (`options.gpuDevice`) is left open — the caller
+     * owns it and must close it themselves. */
     close(): Promise<void>;
+    /** @internal */
+    [NATIVE_HANDLE](): unknown;
 }
+/**
+ * Open Screen capture for output `monitorIndex` (default the primary
+ * display). Creates a `GpuDevice` internally unless `options.gpuDevice` is
+ * supplied — pass one in to pick an explicit adapter
+ * (`GpuDevice.create({ adapterIndex })`) or to share one device across
+ * capture and encode. Throws `CaptureUnavailableError` when no usable
+ * GPU/Desktop-Duplication path exists.
+ */
 export declare function openScreenCapture(options: {
     timeBase: Rational;
     monitorIndex?: number;
+    gpuDevice?: GpuDevice;
 }): Promise<ScreenSession>;

package/dist/index.js

@@ -1,16 +1,27 @@
 /**
- * @mediaway/device — device capability: camera / screen / microphone capture.
+ * @mediaway/device — device capability: camera / screen / microphone capture,
+ * plus the GPU device factory (mediaway-device ADR-0007).
  *
  * Implements the DX contract in bindings/nodejs/README.md over the
  * mediaway-ffi C ABI (via @mediaway/ffi). The ABI is domain-split
- * (`adr/0004-domain-feature-split.md`): this package folds it back into the
- * three DX functions. CPU-storage only: Camera delivers CPU frames; Screen
- * capture raises CaptureUnavailableError from the C ABI today (it needs a
- * live GPU device handle with no CPU fallback). Audio capture delivers raw
+ * (`adr/0004-domain-feature-split.md`): this package folds it back into DX
+ * functions. Camera delivers CPU frames; Screen capture is GPU-only, Zero-Copy
+ * — it needs a live GPU device handle with no CPU fallback
+ * (`adr/0003-gpu-handle-c-abi.md`), which `openScreenCapture()` now gets from
+ * `GpuDevice` (auto-created, or caller-supplied for explicit adapter control
+ * / sharing one device across capture + encode). Audio capture delivers raw
  * interleaved f32le PCM — there is no audio encoder in the ABI.
  */
-import { MwAudioFrame, MwAudioConfig, MwCameraConfig, MwCameraFrame, device, copyBytes, } from "@mediaway/ffi";
+import { MwAudioFrame, MwAudioConfig, MwCameraConfig, MwCameraFrame, MwGpuAdapterInfo, device, copyBytes, decodeArray, } from "@mediaway/ffi";
 import { MediawayError } from "@mediaway/container";
+/**
+ * @internal Key for the opaque native handle behind a capture/GPU-device
+ * session, consumed only by @mediaway/encoder's capture-to-encode bridge
+ * (`EncodeSession.writeFrameFromCameraCapture`/`writeFrameFromDesktopCapture`)
+ * and by `AutoVideoEncodeConfig.gpuDevice`. Not part of the public DX
+ * contract — never read this directly.
+ */
+export const NATIVE_HANDLE = Symbol("mediaway.device.nativeHandle");
 /** No capture device/backend is available, or the ABI rejects this
  * configuration as unsupported (today: Screen capture) — expected outcomes,
  * not hard failures. */
@@ -82,6 +93,10 @@ export class CameraSession {
             this.handle = null;
         }
     }
+    /** @internal */
+    [NATIVE_HANDLE]() {
+        return this.handle;
+    }
 }
 /** Open camera `index` at `timeBase`; throws CaptureUnavailableError when no
  * camera exists on this machine. */
@@ -140,30 +155,163 @@ export async function openMicrophone(options) {
     checkDevice(device.audioFormat(out[0], rate, channels));
     return new MicSession(out[0], rate[0], channels[0]);
 }
-// ── Screen (ideal only) ────────────────────────────────────────────────────────
+/** List every GPU adapter this machine's DXGI factory reports. */
+export function listGpuAdapters() {
+    const outAdapters = [null];
+    const outCount = [0];
+    checkDevice(device.gpuAdapterList(outAdapters, outCount));
+    const count = outCount[0];
+    const decoded = decodeArray(outAdapters[0], MwGpuAdapterInfo, count);
+    const result = decoded.map((raw) => ({
+        index: raw.index,
+        name: raw.name,
+        vendorId: raw.vendor_id,
+        deviceId: raw.device_id,
+        dedicatedVideoMemoryBytes: Number(raw.dedicated_video_memory),
+        isHardware: raw.is_hardware,
+    }));
+    if (count > 0)
+        device.gpuAdapterListFree(outAdapters[0], count);
+    return result;
+}
+/**
+ * A real GPU device, created via the factory (no "bring your own device" path
+ * exists from JS). Pass into `openScreenCapture({ gpuDevice })` and/or
+ * `AutoVideoEncodeConfig.gpuDevice` (`@mediaway/encoder`) to share one device
+ * across capture and encode — Zero-Copy end to end. Close it after every
+ * session built from it is closed.
+ */
+export class GpuDevice {
+    handle;
+    /** Wrap a native GPU device handle. Prefer the create() factory. */
+    constructor(handle) {
+        this.handle = handle;
+    }
+    /** Create a real GPU device. Throws CaptureUnavailableError when no usable
+     * adapter exists (e.g. headless CI without even WARP). */
+    static async create(options = {}) {
+        const raw = {
+            adapter: {
+                kind: options.adapterIndex === undefined ? 0 : 1,
+                index: options.adapterIndex ?? 0,
+            },
+            video_support: options.videoSupport ?? true,
+            debug_layer: options.debugLayer ?? false,
+        };
+        const out = [null];
+        checkDevice(device.gpuDeviceCreate(raw, out));
+        if (!out[0])
+            throw new MediawayError(9, "GPU device create returned no handle");
+        return new GpuDevice(out[0]);
+    }
+    /** Release the underlying GPU device. Every session built from it (Screen
+     * capture, encode config) becomes invalid the moment this returns. */
+    close() {
+        if (this.handle) {
+            device.gpuDeviceClose(this.handle);
+            this.handle = null;
+        }
+    }
+    /** @internal — the `mediaway_gpu_device_handle_t` value bits, read once at
+     * create() time. Consumed by openScreenCapture() and
+     * AutoVideoEncodeConfig.gpuDevice (@mediaway/encoder). Not part of the
+     * public DX contract. */
+    [NATIVE_HANDLE]() {
+        const out = {};
+        checkDevice(device.gpuDeviceHandle(this.handle, out));
+        return out;
+    }
+}
+// ── Screen ───────────────────────────────────────────────────────────────────
 /**
- * A Screen capture session — NOT available from the C ABI today. Screen needs
- * a live GPU device handle (ID3D11Device*) with no CPU fallback, and its C
- * representation is deferred (crates/mediaway-ffi/adr/0001 § Deferred),
- * so openScreenCapture always throws CaptureUnavailableError. The ideal DX
- * (BGRA8 CPU frames at the display's native geometry) is what the aspirational
- * screen-record example targets.
+ * A Screen capture session — GPU-only, Zero-Copy (`adr/0003-gpu-handle-c-abi.md`
+ * §4: no CPU fallback exists in the wrapped Rust backend, so unlike Camera
+ * there is no CPU pixel readback path here either). `pollFrame()` proves
+ * frames are genuinely arriving (real `pts`/geometry) but its `VideoFrame.data`
+ * is always empty — it does not copy pixels out. For real pixel data, feed
+ * the session straight into the encoder with
+ * `EncodeSession.writeFrameFromDesktopCapture()` (`@mediaway/encoder`), which
+ * moves the GPU texture Zero-Copy with no CPU round trip at all.
  */
 export class ScreenSession {
-    width = 0;
-    height = 0;
+    width;
+    height;
     pixelFormat = "bgra8";
     timeBase;
-    /** Screen session (always throws — no C-ABI screen path yet). */
-    constructor(timeBase) {
+    handle;
+    ownsGpuDevice;
+    /** Wrap a native desktop capture handle. Prefer the openScreenCapture() factory. */
+    constructor(handle, width, height, timeBase, ownsGpuDevice) {
+        this.handle = handle;
+        this.width = width;
+        this.height = height;
         this.timeBase = timeBase;
+        this.ownsGpuDevice = ownsGpuDevice;
     }
+    /** Poll the next frame; null when nothing is ready yet. Sync, never blocks.
+     * `data` is always empty — see the class doc. */
     pollFrame() {
-        throw new CaptureUnavailableError(3, "Screen capture is not available from this binding today");
+        const raw = {};
+        const has = [false];
+        checkDevice(device.desktopPollFrame(this.handle, raw, has));
+        if (!has[0])
+            return null;
+        // storage_kind is always GPU (1) for Screen — the frame lives in
+        // gpu_buffer, a BORROWED handle released below (never freed via
+        // desktopFrameFree, which would double-release it; there is nothing to
+        // copy out of raw.data/data_len, which stay empty for GPU storage).
+        checkDevice(device.desktopReleaseFrame(this.handle));
+        return {
+            pts: Number(raw.pts),
+            duration: Number(raw.duration),
+            width: raw.width,
+            height: raw.height,
+            pixelFormat: "bgra8",
+            data: Buffer.alloc(0),
+        };
+    }
+    /** Joins the backend worker thread — can block up to one frame interval.
+     * Also closes the GPU device this session created internally (auto mode);
+     * a caller-supplied device (`options.gpuDevice`) is left open — the caller
+     * owns it and must close it themselves. */
+    async close() {
+        if (this.handle) {
+            checkDevice(device.desktopClose(this.handle));
+            this.handle = null;
+        }
+        this.ownsGpuDevice?.close();
+    }
+    /** @internal */
+    [NATIVE_HANDLE]() {
+        return this.handle;
     }
-    async close() { }
 }
+/**
+ * Open Screen capture for output `monitorIndex` (default the primary
+ * display). Creates a `GpuDevice` internally unless `options.gpuDevice` is
+ * supplied — pass one in to pick an explicit adapter
+ * (`GpuDevice.create({ adapterIndex })`) or to share one device across
+ * capture and encode. Throws `CaptureUnavailableError` when no usable
+ * GPU/Desktop-Duplication path exists.
+ */
 export async function openScreenCapture(options) {
-    void options;
-    throw new CaptureUnavailableError(3, "Screen capture needs a live GPU device handle with no CPU fallback, and its C representation is deferred — not available from this binding today");
+    const ownsGpuDevice = options.gpuDevice === undefined ? await GpuDevice.create() : undefined;
+    const gpuDevice = options.gpuDevice ?? ownsGpuDevice;
+    if (gpuDevice === undefined)
+        throw new MediawayError(9, "no GPU device available");
+    try {
+        const config = device.desktopConfigScreen(options.monitorIndex ?? 0, { num: BigInt(options.timeBase.num), den: options.timeBase.den }, gpuDevice[NATIVE_HANDLE]());
+        const out = [null];
+        checkDevice(device.desktopOpen(config, out));
+        if (!out[0])
+            throw new MediawayError(9, "capture open returned no handle");
+        const width = [0];
+        const height = [0];
+        checkDevice(device.desktopGeometry(out[0], width, height));
+        return new ScreenSession(out[0], width[0], height[0], options.timeBase, ownsGpuDevice);
+    }
+    catch (err) {
+        ownsGpuDevice?.close();
+        throw err;
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mediaway/device",
-  "version": "0.1.5",
+  "version": "0.1.8",
   "description": "Rust-based, lightweight, fast — camera, microphone, and screen capture for Node.js (poll-based, never blocks)",
   "type": "module",
   "main": "./dist/index.js",