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;
}
