node-av-lgpl 0.0.0 → 7.1.0-beta.1

package/dist/api/utilities/electron-shared-texture.d.ts

@@ -0,0 +1,368 @@
+import { Frame } from '../../lib/frame.js';
+import type { AVColorPrimaries, AVColorRange, AVColorSpace, AVColorTransferCharacteristic, AVPixelFormat } from '../../constants/constants.js';
+import type { IRational } from '../../lib/types.js';
+import type { HardwareContext } from '../hardware.js';
+/**
+ * Electron SharedTextureHandle (textureInfo.handle).
+ *
+ * Platform-specific GPU texture handles provided by Electron's offscreen rendering
+ * with shared textures enabled.
+ */
+export interface SharedTextureHandle {
+    ioSurface?: Buffer;
+    ntHandle?: Buffer;
+    nativePixmap?: {
+        planes: {
+            fd: number;
+            stride: number;
+            offset: number;
+            size: number;
+        }[];
+        modifier: string;
+    };
+}
+/**
+ * Electron color space descriptor from textureInfo.colorSpace.
+ */
+export interface TextureColorSpace {
+    range?: 'limited' | 'full' | 'derived' | 'invalid';
+    primaries?: string;
+    transfer?: string;
+    matrix?: string;
+}
+/**
+ * Electron textureInfo object.
+ *
+ * Contains GPU texture metadata and platform-specific handle for zero-copy frame import.
+ */
+export interface TextureInfo {
+    pixelFormat: string;
+    codedSize: {
+        width: number;
+        height: number;
+    };
+    colorSpace?: TextureColorSpace;
+    handle: SharedTextureHandle;
+}
+/**
+ * Options for each frame import via {@link SharedTexture.importTexture} or {@link SharedTexture.importHandle}.
+ */
+export interface TextureFrameOptions {
+    pts?: bigint;
+    timeBase?: IRational;
+}
+/**
+ * Options for {@link SharedTexture.create}.
+ */
+export interface SharedTextureOptions {
+    width?: number;
+    height?: number;
+    swFormat?: AVPixelFormat;
+}
+/**
+ * Properties for importing a raw GPU texture handle via {@link SharedTexture.importHandle}.
+ */
+export interface ImportHandleProps {
+    width: number;
+    height: number;
+    pixelFormat?: string | AVPixelFormat;
+    pts?: bigint;
+    timeBase?: IRational;
+}
+/**
+ * Map an Electron color space descriptor to FFmpeg color properties.
+ *
+ * Translates Electron's `textureInfo.colorSpace` strings (range, primaries,
+ * transfer, matrix) to the corresponding `AVCOL_*` enums. Unknown values map to
+ * the `UNSPECIFIED` variants; a missing descriptor falls back to the BGRA/sRGB
+ * defaults typical of Electron textures.
+ *
+ * @param colorSpace - Electron color space descriptor from textureInfo.colorSpace
+ *
+ * @returns Mapped FFmpeg color properties (colorRange, colorPrimaries, colorTrc, colorSpace) with fallbacks
+ *
+ * @internal
+ */
+export declare function mapColorSpace(colorSpace?: TextureColorSpace): {
+    colorRange: AVColorRange;
+    colorPrimaries: AVColorPrimaries;
+    colorTrc: AVColorTransferCharacteristic;
+    colorSpace: AVColorSpace;
+};
+/**
+ * Resolve the software pixel format for a hardware mapping context.
+ *
+ * The mapping context's sw_format must be the *software* layout of the frames
+ * (e.g. NV12, BGRA), never a hardware wrapper format like AV_PIX_FMT_DRM_PRIME /
+ * D3D11 / VIDEOTOOLBOX (which is what `srcFrame.format` is for an imported GPU
+ * frame). Prefer the source frame's own hwframe context software format (set on
+ * macOS IOSurface imports), and fall back to the layout used at the last import
+ * for bare frames (Windows D3D11, Linux DMA-BUF) that carry no hwframe context.
+ *
+ * @param srcFrame - The source hardware frame being mapped
+ *
+ * @param fallback - Software format to use when the frame carries no hwframe context
+ *
+ * @returns The software pixel format to set on the mapping context
+ *
+ * @internal
+ */
+export declare function resolveMappingSwFormat(srcFrame: Frame, fallback: AVPixelFormat): AVPixelFormat;
+/**
+ * High-level GPU texture import for Electron shared textures.
+ *
+ * Handles platform detection (macOS IOSurface, Windows D3D11,
+ * Linux DMA-BUF), HardwareFramesContext lifecycle, and format mapping automatically.
+ *
+ * @example
+ * ```typescript
+ * import { HardwareContext, SharedTexture } from 'node-av/api';
+ *
+ * const hw = HardwareContext.auto();
+ * using sharedTexture = SharedTexture.create(hw);
+ *
+ * // In Electron paint event:
+ * offscreen.webContents.on('paint', (event) => {
+ *   const texture = event.texture;
+ *   if (!texture?.textureInfo) return;
+ *
+ *   using frame = sharedTexture.importTexture(texture.textureInfo, { pts: 0n });
+ *   // frame is a hardware Frame ready for encoding/filtering
+ *
+ *   texture.release();
+ * });
+ * ```
+ *
+ * @see {@link HardwareContext} For hardware acceleration setup
+ * @see {@link Frame} For frame operations
+ */
+export declare class SharedTexture implements Disposable {
+    private _hardware;
+    private _framesCtx;
+    private _currentWidth;
+    private _currentHeight;
+    private _swFormat;
+    private _importSwFormat;
+    private _isDisposed;
+    private _mappingCtx;
+    private _mappingHw;
+    private constructor();
+    /**
+     * Create a SharedTexture.
+     *
+     * @param hardware - Initialized hardware context (from HardwareContext.auto() or HardwareContext.create())
+     *
+     * @param options - Optional configuration overrides
+     *
+     * @returns SharedTexture instance
+     *
+     * @example
+     * ```typescript
+     * const hw = HardwareContext.auto();
+     * using sharedTexture = SharedTexture.create(hw);
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // With explicit software format
+     * import { AV_PIX_FMT_NV12 } from 'node-av/constants';
+     *
+     * using sharedTexture = SharedTexture.create(hw, { swFormat: AV_PIX_FMT_NV12 });
+     * ```
+     */
+    static create(hardware: HardwareContext, options?: SharedTextureOptions): SharedTexture;
+    /**
+     * The hardware context used by this sharedTexture.
+     */
+    get hardware(): HardwareContext;
+    /**
+     * Current width of the cached HardwareFramesContext.
+     */
+    get width(): number;
+    /**
+     * Current height of the cached HardwareFramesContext.
+     */
+    get height(): number;
+    /**
+     * Whether this sharedTexture has been disposed.
+     */
+    get isDisposed(): boolean;
+    /**
+     * Import an Electron textureInfo as a hardware Frame.
+     *
+     * Automatically detects the platform from the handle contents,
+     * manages the HardwareFramesContext, and creates a zero-copy hardware frame.
+     *
+     * @param textureInfo - Electron's textureInfo object from paint event
+     *
+     * @param options - Per-frame options (pts, timeBase)
+     *
+     * @returns Hardware Frame referencing the GPU texture
+     *
+     * @throws {Error} If disposed, no valid handle found, or import fails
+     *
+     * @example
+     * ```typescript
+     * offscreen.webContents.on('paint', (event) => {
+     *   const texture = event.texture;
+     *   if (!texture?.textureInfo) return;
+     *
+     *   using frame = sharedTexture.importTexture(texture.textureInfo, {
+     *     pts: BigInt(Date.now()) * 1000n,
+     *     timeBase: { num: 1, den: 1000000 },
+     *   });
+     *
+     *   texture.release();
+     * });
+     * ```
+     */
+    importTexture(textureInfo: TextureInfo, options?: TextureFrameOptions): Frame;
+    /**
+     * Import a raw SharedTextureHandle as a hardware Frame.
+     *
+     * Use this when you have the handle directly without the full textureInfo wrapper.
+     *
+     * @param handle - Platform-specific GPU texture handle
+     *
+     * @param props - Dimensions, format, and timing options
+     *
+     * @returns Hardware Frame referencing the GPU texture
+     *
+     * @throws {Error} If disposed, no valid handle found, or import fails
+     *
+     * @example
+     * ```typescript
+     * const frame = sharedTexture.importHandle(handle, {
+     *   width: 1920,
+     *   height: 1080,
+     *   pixelFormat: 'BGRA',
+     *   pts: 0n,
+     * });
+     * ```
+     */
+    importHandle(handle: SharedTextureHandle, props: ImportHandleProps): Frame;
+    /**
+     * Map a frame to a different hardware format.
+     *
+     * Handles HardwareFramesContext creation and caching automatically.
+     * The mapping context is cached and reused for subsequent calls with the
+     * same target hardware and frame dimensions.
+     *
+     * @param srcFrame - Source frame (e.g., DRM PRIME from importTexture on Linux)
+     *
+     * @param targetHw - Target hardware context (e.g., VAAPI, Vulkan)
+     *
+     * @param flags - Mapping flags
+     *
+     * @returns Mapped frame in target hardware format
+     *
+     * @throws {FFmpegError} If mapping fails (e.g., unsupported mapping, invalid frames)
+     *
+     * @example
+     * ```typescript
+     * import { HardwareContext, SharedTexture } from 'node-av/api';
+     * import { AV_HWDEVICE_TYPE_VAAPI } from 'node-av/constants';
+     *
+     * // Import DRM PRIME frame from Electron shared texture
+     * const drmFrame = sharedTexture.importTexture(textureInfo, { pts: 0n });
+     *
+     * // Map to VAAPI for encoding
+     * const vaapiHw = HardwareContext.create(AV_HWDEVICE_TYPE_VAAPI);
+     * const vaapiFrame = sharedTexture.mapTo(drmFrame, vaapiHw);
+     *
+     * // Encode with VAAPI encoder
+     * encoder.encode(vaapiFrame);
+     * ```
+     */
+    mapTo(srcFrame: Frame, targetHw: HardwareContext, flags?: number): Frame;
+    /**
+     * Ensure mapping context exists and matches the target hardware and frame dimensions.
+     *
+     * Re-creates the context if target hardware changes or dimensions change.
+     *
+     * @param srcFrame - Source frame to get dimensions from
+     *
+     * @param targetHw - Target hardware context
+     *
+     * @internal
+     */
+    private ensureMappingContext;
+    /**
+     * Release the cached HardwareFramesContext and mapping context.
+     *
+     * The HardwareContext is NOT disposed — it belongs to the caller.
+     * Safe to call multiple times.
+     *
+     * @example
+     * ```typescript
+     * sharedTexture.dispose();
+     * ```
+     */
+    dispose(): void;
+    /**
+     * Core import logic — dispatches to the correct Frame factory based on handle type.
+     *
+     * @param handle - Platform-specific GPU texture handle
+     *
+     * @param width - Texture width in pixels
+     *
+     * @param height - Texture height in pixels
+     *
+     * @param swFormat - Software pixel format for HardwareFramesContext
+     *
+     * @param options - Per-frame timing options
+     *
+     * @param colorSpace - Electron color space descriptor for mapping to FFmpeg color properties
+     *
+     * @returns Hardware Frame referencing the GPU texture
+     *
+     * @internal
+     */
+    private importFromHandle;
+    /**
+     * Ensure HardwareFramesContext is created and matches the requested dimensions/format.
+     *
+     * Re-creates the context only when dimensions or format change.
+     * Windows D3D11 does not use this — it passes HardwareDeviceContext directly.
+     *
+     * @param width - Frame width in pixels
+     *
+     * @param height - Frame height in pixels
+     *
+     * @param swFormat - Software pixel format
+     *
+     * @returns Initialized HardwareFramesContext matching the requested parameters
+     *
+     * @internal
+     */
+    private ensureFramesContext;
+    /**
+     * Resolve a pixel format string (e.g., 'BGRA') to an AVPixelFormat enum value.
+     *
+     * Falls back to the configured swFormat if the name is not recognized.
+     *
+     * @param name - Pixel format name string from Electron
+     *
+     * @returns Resolved AVPixelFormat enum value
+     *
+     * @internal
+     */
+    private resolvePixelFormat;
+    /**
+     * Dispose of the SharedTexture.
+     *
+     * Implements the Disposable interface for automatic cleanup.
+     * Equivalent to calling dispose().
+     *
+     * @example
+     * ```typescript
+     * {
+     *   using sharedTexture = SharedTexture.create(hw);
+     *   // Use sharedTexture...
+     * } // Automatically disposed
+     * ```
+     *
+     * @see {@link dispose} For manual cleanup
+     */
+    [Symbol.dispose](): void;
+}