alpha-video-gpu-web 0.0.0-stage → 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,268 @@
+import { K as KTX2PlayerCoreOptions, P as PlayerState, M as Metadata, a as KTX2Source, b as KTX2SourceOptions } from './types-C6J2fa98.mjs';
+export { c as AlphaVideoGpuLoadEvent, d as AlphaVideoGpuStorage, e as MemoryStrategy, S as SharedGLResources } from './types-C6J2fa98.mjs';
+export { ByteSource, ByteStore, HttpSourceError, HttpSourceOptions, SourceChangedError, SourceInfo, StorageKind, blobSource, createStore, httpSource, memorySource } from 'range-source-web';
+
+/**
+ * KTX2PlayerCore - Framework-agnostic WebGL engine for KTX2 animated textures.
+ *
+ * This is the single source of truth for all web-based KTX2 playback logic.
+ * Framework wrappers (React Native Web, React, Vanilla JS) should be thin
+ * layers that create/destroy a KTX2PlayerCore instance and map props/options.
+ */
+
+declare class KTX2PlayerCore {
+    private _autoPlay;
+    private _loop;
+    private _playbackSpeed;
+    private _stream;
+    private _streamingPrefetchAhead;
+    private _memoryStrategy;
+    private _verbose;
+    private _storage;
+    private _maxStorageBytes;
+    private _ZSTDDecoderClass;
+    private _onStateChange;
+    private _onLoad;
+    private _onFrameUpdate;
+    private _frameEvents;
+    private _onFinished;
+    private _onError;
+    private _canvas;
+    private _ctx2d;
+    private _usingSharedGL;
+    private _gl;
+    private _arrayProgram;
+    private _positionBuffer;
+    private _texCoordBuffer;
+    private _textureArray;
+    private _softwareAstc;
+    private _blockWidth;
+    private _blockHeight;
+    private _metadata;
+    private _state;
+    private _currentFrame;
+    private _animationFrameId;
+    private _lastFrameTime;
+    private _loadedSource;
+    private _loadId;
+    private _reader;
+    private _zstdDecoder;
+    private _streamingMode;
+    private _streamingCancelled;
+    private _streamingFrameCache;
+    private _useVramStrategy;
+    private _streamingRingBuffer;
+    private _streamingRingSlots;
+    private _streamingRingActualSize;
+    private _streamingDecodePos;
+    private _streamingFramesReady;
+    private _streamingLoopCount;
+    private _layerStream;
+    private _streamingBytesPerLayer;
+    private _streamingWidth;
+    private _streamingHeight;
+    private _streamingLayerCount;
+    private _streamingLevel0Offset;
+    private _streamingAstcFormat;
+    private _backgroundDecodeStream;
+    private _ended;
+    private _pausedByProp;
+    private _owedFrameId;
+    private _ramHeavyMode;
+    private _ramFrameData;
+    private _ramBytesPerFrame;
+    private _ramFrameCount;
+    private _ramUploadedFrame;
+    private _ramAstcFormat;
+    private _ramWidth;
+    private _ramHeight;
+    constructor(canvas: HTMLCanvasElement, options?: KTX2PlayerCoreOptions);
+    get state(): PlayerState;
+    get currentFrame(): number;
+    get totalFrames(): number;
+    get frameRate(): number;
+    get duration(): number;
+    get currentTime(): number;
+    get metadataInfo(): Metadata | null;
+    /** Whether a source starts playing once loaded. */
+    set autoPlay(v: boolean);
+    get autoPlay(): boolean;
+    /** Whether onFrameUpdate fires for every frame played, not only for seeks. */
+    set frameEvents(v: boolean);
+    get frameEvents(): boolean;
+    set loop(v: boolean);
+    get loop(): boolean;
+    set playbackSpeed(v: number);
+    get playbackSpeed(): number;
+    /** Update callbacks after construction (useful for wrappers where callbacks change). */
+    updateCallbacks(cbs: Partial<Pick<KTX2PlayerCoreOptions, 'onStateChange' | 'onLoad' | 'onFrameUpdate' | 'onFinished' | 'onError'>>): void;
+    /** Plays from the shown frame, or from the start once a clip that doesn't loop has ended. */
+    play(): void;
+    pause(): void;
+    resume(): void;
+    /**
+     * Holds playback and decoding, keeping the frames (the `paused` prop, for screen focus and
+     * blur). Unpausing plays again only when autoPlay is on; a source loaded while paused waits.
+     */
+    setPaused(paused: boolean): void;
+    /** Pauses on the first frame. */
+    stop(): void;
+    /**
+     * Shows that frame (clamped to the clip) and keeps playing or stays paused. Ignored until
+     * the source has loaded. While streaming, a seek outside the buffered frames decodes again.
+     */
+    seekToFrame(frame: number): void;
+    /** Seeks to the frame showing at that time, in seconds. */
+    seekToTime(seconds: number): void;
+    set verbose(v: boolean);
+    /** Reset loaded source tracking so next setSource will reload even the same URI. */
+    resetSource(): void;
+    /**
+     * Loads an ASTC KTX2 texture array from a URL (http(s), relative, or asset://path, served from
+     * the site root), a Blob or File, bytes in memory, or a ByteSource. Files are read by range:
+     * streaming playback starts once the first frames have arrived, and a URL's bytes are kept in
+     * the storage option's store for the next play.
+     *
+     * @param options cacheKey and headers; a string is taken as the cacheKey
+     */
+    setSource(source: KTX2Source, options?: KTX2SourceOptions | string): Promise<void>;
+    private _log;
+    /** Tear down all resources. Call when the player is no longer needed. */
+    destroy(): void;
+    /** Stops a load that a newer setSource or destroy has replaced. */
+    private _checkLoad;
+    private _closeReader;
+    private _setState;
+    private _finishLoad;
+    private _initGL;
+    private _ensureZstdDecoder;
+    /** Uses the GPU's ASTC where the browser has it, and loads the software decoder where not. */
+    private _prepareAstc;
+    /** Allocates the bound texture array: ASTC, or RGBA8 when decoding in software. */
+    private _allocateLayers;
+    /** Uploads one layer of ASTC blocks to the bound texture array, decoding it first in software. */
+    private _uploadLayer;
+    private _cleanupTextures;
+    private _cleanupStreamingState;
+    private _cleanupRamState;
+    private _emitLoad;
+    private _loadKTX2Source;
+    private _loadTextureArray;
+    private _initStreamingRingBuffer;
+    /**
+     * Plays the level a layer at a time: zstd-decoded, or read straight from the file when
+     * uncompressed. The first frames are read before the load finishes; the rest are read
+     * ahead of playback by the background decode loop.
+     */
+    private _loadStreamingTextureArray;
+    /**
+     * Reads and decodes ahead of playback, and catches up to a seek target, in slices of
+     * DECODE_SLICE_MS so a long catch-up doesn't hold up drawing or input. A seek during a read
+     * interrupts it (readLayer returns null) and the loop carries on from the new position.
+     */
+    private _startBackgroundDecompression;
+    private _ensureFrameInRingBuffer;
+    private _evictOldFramesFromCache;
+    private _handleStreamingLoop;
+    /** Starts the streaming decoder, unless it is already running. */
+    private _kickStreamingDecode;
+    /**
+     * Points the streaming decoder at target. Frames from target up to the decoder that are all
+     * still buffered are kept; otherwise decoding carries on or starts at a seek point, whichever
+     * reaches target sooner (see ZstdLayerStream.moveTo).
+     */
+    private _moveStreamTo;
+    /** Stops the stream's reads and frees the zstd decoder's WASM buffers. */
+    private _closeLayerStream;
+    /** Drops the decoded frames and has the decoder produce target next. */
+    private _decodeFrom;
+    /** Draws the shown frame once it is decoded, for a seek while not playing. */
+    private _drawWhenReady;
+    /** Draws the current frame; false when it isn't decoded yet, leaving the last one showing. */
+    private _render;
+    private _startAnimationLoop;
+    private _stopAnimationLoop;
+}
+
+/** A zstd decoder fed one input array at a time; see createStreamingDecoder. */
+interface ZSTDStreamingDecoder {
+  /** Decodes the array, yielding its output in pieces. Finish iterating before the next call. */
+  decode(array: Uint8Array): Generator<Uint8Array, void, undefined>;
+  /** True when the input so far ends between frames. */
+  finished(): boolean;
+  /** Frees the WASM buffers; the decoder can't be used afterwards. */
+  free(): void;
+}
+
+declare class ZSTDDecoder {
+  init(): Promise<void>;
+  decode(array: Uint8Array, uncompressedSize?: number): Uint8Array;
+  decodeStreaming(arrays: Iterable<Uint8Array>): Generator<Uint8Array>;
+  createStreamingDecoder(): ZSTDStreamingDecoder;
+}
+
+/**
+ * KTX2 Parsing Utilities
+ *
+ * Functions for reading a KTX2 file's frame metadata and mapping ASTC formats.
+ */
+
+/**
+ * Reads the frame size and count from the KTX2 header and the frame rate from KTXanimData, the
+ * KTX 2.0 key for array textures whose layers are animation frames (per-frame duration /
+ * timescale seconds, so 29.97 fps is exact). Returns null if the data isn't a KTX2 file.
+ */
+declare function extractKTX2Metadata(ktx2Data: Uint8Array): Metadata | null;
+/**
+ * ASTC VkFormat → WebGL compressed format mapping.
+ * Covers all 14 ASTC block sizes (UNORM and SRGB variants).
+ */
+declare const ASTC_FORMAT_MAP: Record<number, number>;
+/**
+ * ASTC VkFormat → block dimensions (width, height).
+ * All ASTC blocks are 128 bits (16 bytes), but pixel coverage varies.
+ * VkFormat values come in UNORM/SRGB pairs; both map to the same block size.
+ */
+declare function getASTCBlockSize(vkFormat: number): {
+    blockWidth: number;
+    blockHeight: number;
+};
+/**
+ * Calculate bytes per layer for an ASTC-compressed texture.
+ * All ASTC blocks are 16 bytes regardless of block dimensions.
+ */
+declare function getASTCBytesPerLayer(width: number, height: number, vkFormat: number): number;
+
+/** Keeps this player's stored clips apart from other players' (each has its own cap). */
+declare const STORAGE_NAMESPACE = "alpha-video-gpu";
+
+/**
+ * - `ASTC_UNSUPPORTED`: the browser has no `WEBGL_compressed_texture_astc`, and the software
+ *   decoder couldn't load either (WebAssembly blocked, as by a Content-Security-Policy without
+ *   'wasm-unsafe-eval').
+ * - `WEBGL_UNSUPPORTED`: no WebGL2 context could be created.
+ */
+type AlphaVideoGpuErrorCode = 'ASTC_UNSUPPORTED' | 'WEBGL_UNSUPPORTED';
+/** An error passed to `onError` that callers can tell apart by `code`. */
+declare class AlphaVideoGpuError extends Error {
+    readonly code: AlphaVideoGpuErrorCode;
+    constructor(code: AlphaVideoGpuErrorCode, message: string);
+}
+
+/**
+ * alpha-video-gpu-web: transparent animations from ASTC KTX2 texture arrays, drawn into a
+ * <canvas> with WebGL2. The zstd decoder (JS + WASM) is bundled inline, so there are no files to
+ * host and no <script> tags.
+ *
+ *   import { createAlphaVideoGpuPlayer } from 'alpha-video-gpu-web';
+ *
+ *   const player = createAlphaVideoGpuPlayer(canvas, { autoPlay: true, loop: true });
+ *   player.setSource('https://example.com/animation.ktx2');
+ *
+ * React: `alpha-video-gpu-web/react`.
+ */
+
+/** A player on `canvas` with the bundled decoders. */
+declare function createAlphaVideoGpuPlayer(canvas: HTMLCanvasElement, options?: Omit<KTX2PlayerCoreOptions, 'ZSTDDecoderClass'>): KTX2PlayerCore;
+
+export { ASTC_FORMAT_MAP, KTX2PlayerCore as AlphaVideoGpuCore, AlphaVideoGpuError, type AlphaVideoGpuErrorCode, KTX2PlayerCoreOptions as AlphaVideoGpuOptions, KTX2Source as AlphaVideoGpuSource, KTX2SourceOptions as AlphaVideoGpuSourceOptions, Metadata, PlayerState, STORAGE_NAMESPACE, ZSTDDecoder, createAlphaVideoGpuPlayer, extractKTX2Metadata, getASTCBlockSize, getASTCBytesPerLayer };

package/dist/index.d.ts

@@ -0,0 +1,268 @@
+import { K as KTX2PlayerCoreOptions, P as PlayerState, M as Metadata, a as KTX2Source, b as KTX2SourceOptions } from './types-C6J2fa98.js';
+export { c as AlphaVideoGpuLoadEvent, d as AlphaVideoGpuStorage, e as MemoryStrategy, S as SharedGLResources } from './types-C6J2fa98.js';
+export { ByteSource, ByteStore, HttpSourceError, HttpSourceOptions, SourceChangedError, SourceInfo, StorageKind, blobSource, createStore, httpSource, memorySource } from 'range-source-web';
+
+/**
+ * KTX2PlayerCore - Framework-agnostic WebGL engine for KTX2 animated textures.
+ *
+ * This is the single source of truth for all web-based KTX2 playback logic.
+ * Framework wrappers (React Native Web, React, Vanilla JS) should be thin
+ * layers that create/destroy a KTX2PlayerCore instance and map props/options.
+ */
+
+declare class KTX2PlayerCore {
+    private _autoPlay;
+    private _loop;
+    private _playbackSpeed;
+    private _stream;
+    private _streamingPrefetchAhead;
+    private _memoryStrategy;
+    private _verbose;
+    private _storage;
+    private _maxStorageBytes;
+    private _ZSTDDecoderClass;
+    private _onStateChange;
+    private _onLoad;
+    private _onFrameUpdate;
+    private _frameEvents;
+    private _onFinished;
+    private _onError;
+    private _canvas;
+    private _ctx2d;
+    private _usingSharedGL;
+    private _gl;
+    private _arrayProgram;
+    private _positionBuffer;
+    private _texCoordBuffer;
+    private _textureArray;
+    private _softwareAstc;
+    private _blockWidth;
+    private _blockHeight;
+    private _metadata;
+    private _state;
+    private _currentFrame;
+    private _animationFrameId;
+    private _lastFrameTime;
+    private _loadedSource;
+    private _loadId;
+    private _reader;
+    private _zstdDecoder;
+    private _streamingMode;
+    private _streamingCancelled;
+    private _streamingFrameCache;
+    private _useVramStrategy;
+    private _streamingRingBuffer;
+    private _streamingRingSlots;
+    private _streamingRingActualSize;
+    private _streamingDecodePos;
+    private _streamingFramesReady;
+    private _streamingLoopCount;
+    private _layerStream;
+    private _streamingBytesPerLayer;
+    private _streamingWidth;
+    private _streamingHeight;
+    private _streamingLayerCount;
+    private _streamingLevel0Offset;
+    private _streamingAstcFormat;
+    private _backgroundDecodeStream;
+    private _ended;
+    private _pausedByProp;
+    private _owedFrameId;
+    private _ramHeavyMode;
+    private _ramFrameData;
+    private _ramBytesPerFrame;
+    private _ramFrameCount;
+    private _ramUploadedFrame;
+    private _ramAstcFormat;
+    private _ramWidth;
+    private _ramHeight;
+    constructor(canvas: HTMLCanvasElement, options?: KTX2PlayerCoreOptions);
+    get state(): PlayerState;
+    get currentFrame(): number;
+    get totalFrames(): number;
+    get frameRate(): number;
+    get duration(): number;
+    get currentTime(): number;
+    get metadataInfo(): Metadata | null;
+    /** Whether a source starts playing once loaded. */
+    set autoPlay(v: boolean);
+    get autoPlay(): boolean;
+    /** Whether onFrameUpdate fires for every frame played, not only for seeks. */
+    set frameEvents(v: boolean);
+    get frameEvents(): boolean;
+    set loop(v: boolean);
+    get loop(): boolean;
+    set playbackSpeed(v: number);
+    get playbackSpeed(): number;
+    /** Update callbacks after construction (useful for wrappers where callbacks change). */
+    updateCallbacks(cbs: Partial<Pick<KTX2PlayerCoreOptions, 'onStateChange' | 'onLoad' | 'onFrameUpdate' | 'onFinished' | 'onError'>>): void;
+    /** Plays from the shown frame, or from the start once a clip that doesn't loop has ended. */
+    play(): void;
+    pause(): void;
+    resume(): void;
+    /**
+     * Holds playback and decoding, keeping the frames (the `paused` prop, for screen focus and
+     * blur). Unpausing plays again only when autoPlay is on; a source loaded while paused waits.
+     */
+    setPaused(paused: boolean): void;
+    /** Pauses on the first frame. */
+    stop(): void;
+    /**
+     * Shows that frame (clamped to the clip) and keeps playing or stays paused. Ignored until
+     * the source has loaded. While streaming, a seek outside the buffered frames decodes again.
+     */
+    seekToFrame(frame: number): void;
+    /** Seeks to the frame showing at that time, in seconds. */
+    seekToTime(seconds: number): void;
+    set verbose(v: boolean);
+    /** Reset loaded source tracking so next setSource will reload even the same URI. */
+    resetSource(): void;
+    /**
+     * Loads an ASTC KTX2 texture array from a URL (http(s), relative, or asset://path, served from
+     * the site root), a Blob or File, bytes in memory, or a ByteSource. Files are read by range:
+     * streaming playback starts once the first frames have arrived, and a URL's bytes are kept in
+     * the storage option's store for the next play.
+     *
+     * @param options cacheKey and headers; a string is taken as the cacheKey
+     */
+    setSource(source: KTX2Source, options?: KTX2SourceOptions | string): Promise<void>;
+    private _log;
+    /** Tear down all resources. Call when the player is no longer needed. */
+    destroy(): void;
+    /** Stops a load that a newer setSource or destroy has replaced. */
+    private _checkLoad;
+    private _closeReader;
+    private _setState;
+    private _finishLoad;
+    private _initGL;
+    private _ensureZstdDecoder;
+    /** Uses the GPU's ASTC where the browser has it, and loads the software decoder where not. */
+    private _prepareAstc;
+    /** Allocates the bound texture array: ASTC, or RGBA8 when decoding in software. */
+    private _allocateLayers;
+    /** Uploads one layer of ASTC blocks to the bound texture array, decoding it first in software. */
+    private _uploadLayer;
+    private _cleanupTextures;
+    private _cleanupStreamingState;
+    private _cleanupRamState;
+    private _emitLoad;
+    private _loadKTX2Source;
+    private _loadTextureArray;
+    private _initStreamingRingBuffer;
+    /**
+     * Plays the level a layer at a time: zstd-decoded, or read straight from the file when
+     * uncompressed. The first frames are read before the load finishes; the rest are read
+     * ahead of playback by the background decode loop.
+     */
+    private _loadStreamingTextureArray;
+    /**
+     * Reads and decodes ahead of playback, and catches up to a seek target, in slices of
+     * DECODE_SLICE_MS so a long catch-up doesn't hold up drawing or input. A seek during a read
+     * interrupts it (readLayer returns null) and the loop carries on from the new position.
+     */
+    private _startBackgroundDecompression;
+    private _ensureFrameInRingBuffer;
+    private _evictOldFramesFromCache;
+    private _handleStreamingLoop;
+    /** Starts the streaming decoder, unless it is already running. */
+    private _kickStreamingDecode;
+    /**
+     * Points the streaming decoder at target. Frames from target up to the decoder that are all
+     * still buffered are kept; otherwise decoding carries on or starts at a seek point, whichever
+     * reaches target sooner (see ZstdLayerStream.moveTo).
+     */
+    private _moveStreamTo;
+    /** Stops the stream's reads and frees the zstd decoder's WASM buffers. */
+    private _closeLayerStream;
+    /** Drops the decoded frames and has the decoder produce target next. */
+    private _decodeFrom;
+    /** Draws the shown frame once it is decoded, for a seek while not playing. */
+    private _drawWhenReady;
+    /** Draws the current frame; false when it isn't decoded yet, leaving the last one showing. */
+    private _render;
+    private _startAnimationLoop;
+    private _stopAnimationLoop;
+}
+
+/** A zstd decoder fed one input array at a time; see createStreamingDecoder. */
+interface ZSTDStreamingDecoder {
+  /** Decodes the array, yielding its output in pieces. Finish iterating before the next call. */
+  decode(array: Uint8Array): Generator<Uint8Array, void, undefined>;
+  /** True when the input so far ends between frames. */
+  finished(): boolean;
+  /** Frees the WASM buffers; the decoder can't be used afterwards. */
+  free(): void;
+}
+
+declare class ZSTDDecoder {
+  init(): Promise<void>;
+  decode(array: Uint8Array, uncompressedSize?: number): Uint8Array;
+  decodeStreaming(arrays: Iterable<Uint8Array>): Generator<Uint8Array>;
+  createStreamingDecoder(): ZSTDStreamingDecoder;
+}
+
+/**
+ * KTX2 Parsing Utilities
+ *
+ * Functions for reading a KTX2 file's frame metadata and mapping ASTC formats.
+ */
+
+/**
+ * Reads the frame size and count from the KTX2 header and the frame rate from KTXanimData, the
+ * KTX 2.0 key for array textures whose layers are animation frames (per-frame duration /
+ * timescale seconds, so 29.97 fps is exact). Returns null if the data isn't a KTX2 file.
+ */
+declare function extractKTX2Metadata(ktx2Data: Uint8Array): Metadata | null;
+/**
+ * ASTC VkFormat → WebGL compressed format mapping.
+ * Covers all 14 ASTC block sizes (UNORM and SRGB variants).
+ */
+declare const ASTC_FORMAT_MAP: Record<number, number>;
+/**
+ * ASTC VkFormat → block dimensions (width, height).
+ * All ASTC blocks are 128 bits (16 bytes), but pixel coverage varies.
+ * VkFormat values come in UNORM/SRGB pairs; both map to the same block size.
+ */
+declare function getASTCBlockSize(vkFormat: number): {
+    blockWidth: number;
+    blockHeight: number;
+};
+/**
+ * Calculate bytes per layer for an ASTC-compressed texture.
+ * All ASTC blocks are 16 bytes regardless of block dimensions.
+ */
+declare function getASTCBytesPerLayer(width: number, height: number, vkFormat: number): number;
+
+/** Keeps this player's stored clips apart from other players' (each has its own cap). */
+declare const STORAGE_NAMESPACE = "alpha-video-gpu";
+
+/**
+ * - `ASTC_UNSUPPORTED`: the browser has no `WEBGL_compressed_texture_astc`, and the software
+ *   decoder couldn't load either (WebAssembly blocked, as by a Content-Security-Policy without
+ *   'wasm-unsafe-eval').
+ * - `WEBGL_UNSUPPORTED`: no WebGL2 context could be created.
+ */
+type AlphaVideoGpuErrorCode = 'ASTC_UNSUPPORTED' | 'WEBGL_UNSUPPORTED';
+/** An error passed to `onError` that callers can tell apart by `code`. */
+declare class AlphaVideoGpuError extends Error {
+    readonly code: AlphaVideoGpuErrorCode;
+    constructor(code: AlphaVideoGpuErrorCode, message: string);
+}
+
+/**
+ * alpha-video-gpu-web: transparent animations from ASTC KTX2 texture arrays, drawn into a
+ * <canvas> with WebGL2. The zstd decoder (JS + WASM) is bundled inline, so there are no files to
+ * host and no <script> tags.
+ *
+ *   import { createAlphaVideoGpuPlayer } from 'alpha-video-gpu-web';
+ *
+ *   const player = createAlphaVideoGpuPlayer(canvas, { autoPlay: true, loop: true });
+ *   player.setSource('https://example.com/animation.ktx2');
+ *
+ * React: `alpha-video-gpu-web/react`.
+ */
+
+/** A player on `canvas` with the bundled decoders. */
+declare function createAlphaVideoGpuPlayer(canvas: HTMLCanvasElement, options?: Omit<KTX2PlayerCoreOptions, 'ZSTDDecoderClass'>): KTX2PlayerCore;
+
+export { ASTC_FORMAT_MAP, KTX2PlayerCore as AlphaVideoGpuCore, AlphaVideoGpuError, type AlphaVideoGpuErrorCode, KTX2PlayerCoreOptions as AlphaVideoGpuOptions, KTX2Source as AlphaVideoGpuSource, KTX2SourceOptions as AlphaVideoGpuSourceOptions, Metadata, PlayerState, STORAGE_NAMESPACE, ZSTDDecoder, createAlphaVideoGpuPlayer, extractKTX2Metadata, getASTCBlockSize, getASTCBytesPerLayer };