@onerjs/core 9.0.1 → 9.0.3

package/Misc/khronosTextureContainer2Encoder.d.ts

@@ -0,0 +1,166 @@
+import { type BaseTexture } from "../Materials/Textures/baseTexture.pure.js";
+import { AutoReleaseWorkerPool } from "./workerPool.js";
+import { type _IKTX2EncoderDefaultOptions, type IKTX2EncoderOptions } from "../Materials/Textures/ktx2encoderTypes.js";
+import { type _KTX2EncoderBasisFactory, type IKTX2EncoderModule } from "./khronosTextureContainer2EncoderWorker.js";
+export type { IKTX2EncoderOptions, KTX2EncoderUsage } from "../Materials/Textures/ktx2encoderTypes.js";
+/**
+ * Encoder-wide KTX2 encoding options. Defined values override per-call options, as KhronosTextureContainer2.DefaultDecoderOptions does.
+ * ETC1S fields apply only to color usage; uastcQualityLevel and zstandard apply only to data and normal usage.
+ * @experimental
+ */
+export declare class DefaultKTX2EncoderOptions {
+    private _isDirty;
+    /**
+     * Gets the dirty flag
+     * @experimental
+     */
+    get isDirty(): boolean;
+    private _etc1sQualityLevel?;
+    /**
+     * Integer ETC1S quality for color usage, from 1 to 255.
+     * @experimental
+     */
+    get etc1sQualityLevel(): number | undefined;
+    set etc1sQualityLevel(value: number | undefined);
+    private _etc1sCompressionLevel?;
+    /**
+     * Integer ETC1S compression effort for color usage, from 0 to 6.
+     * @experimental
+     */
+    get etc1sCompressionLevel(): number | undefined;
+    set etc1sCompressionLevel(value: number | undefined);
+    private _uastcQualityLevel?;
+    /**
+     * Integer UASTC quality for data and normal usage, from 0 to 4.
+     * @experimental
+     */
+    get uastcQualityLevel(): number | undefined;
+    set uastcQualityLevel(value: number | undefined);
+    private _zstandard?;
+    /**
+     * Use Zstandard with UASTC for data and normal usage.
+     * @experimental
+     */
+    get zstandard(): boolean | undefined;
+    set zstandard(value: boolean | undefined);
+    private _ktx2EncoderOptions;
+    /** @internal */
+    _getKTX2EncoderOptions(): _IKTX2EncoderDefaultOptions;
+}
+/**
+ * Options for the KTX2 encoder.
+ * @experimental
+ */
+export interface IKhronosTextureContainer2EncoderOptions {
+    /**
+     * Number of workers for the shared automatic pool. Specify `0` to encode on the main thread.
+     * @experimental
+     */
+    numWorkers?: number;
+    /**
+     * Worker pool captured by this instance, whose workers are already initialized with the encoder worker protocol. If set, `numWorkers` is ignored.
+     * This release has no public worker bootstrap.
+     * @experimental
+     */
+    workerPool?: AutoReleaseWorkerPool;
+    /**
+     * Dependencies that replace their URLConfig entries.
+     * JavaScript modules cannot be sent to automatic workers; use them with `numWorkers: 0`.
+     * The WASM binary is copied to automatic workers and is not detached.
+     * @experimental
+     */
+    binariesAndModulesContainer?: {
+        /**
+         * The Babylon KTX2 encoder module, such as the KTX2ENCODER global.
+         * @experimental
+         */
+        jsEncoderModule?: IKTX2EncoderModule;
+        /**
+         * The Basis Universal v2_50 encoder factory, such as the BASIS global.
+         * @experimental
+         */
+        jsBasisEncoder?: _KTX2EncoderBasisFactory;
+        /**
+         * The Basis Universal v2_50 encoder WASM binary.
+         * @experimental
+         */
+        wasmBasisEncoder?: ArrayBuffer;
+    };
+}
+/**
+ * Determines the Basis row flip without modifying pixels.
+ * GetTextureDataAsync's direct and LOD RTT paths preserve texture texel row order:
+ * WebGL reads bottom-first; WebGPU's Y-flipped RTT draw compensates its top-left origin.
+ * Uploaded images undo their upload flip. Compressed uploads retain their source rows;
+ * loader UV compensation does not change readback pixels.
+ * KTX2's uncompressed fallback uses the regular upload flip.
+ * Render targets need a flip on WebGL and on WebGPU, whose render-target draws are Y-flipped.
+ * @internal
+ */
+export declare function _GetKTX2TextureFlipY(texture: BaseTexture): boolean;
+/**
+ * Encodes Babylon textures to KTX2 through a shared pool of Basis Universal workers.
+ * This is groundwork for future glTF export; encoding is internal for now.
+ * Configure URLConfig, WorkerPool, and constructor options before the first construction, which fixes the automatic configuration.
+ * Fatally failed automatic workers are terminated and replaced for the next job.
+ * Normal encode-error replies and cancellation do not terminate healthy workers. Caller-provided pools remain caller-owned.
+ * Each worker starts with approximately 128 MiB of WASM memory.
+ * The official Basis v2_50 factory requires CSP 'unsafe-eval' for Embind.
+ * @experimental
+ */
+export declare class KhronosTextureContainer2Encoder {
+    /**
+     * URLs of the Babylon encoder module and its Basis Universal v2_50 dependencies.
+     * Each URL is resolved with Tools.GetBabylonScriptURL. Configure before the first construction.
+     * @experimental
+     */
+    static URLConfig: {
+        jsEncoderModule: string;
+        jsBasisEncoder: string;
+        wasmBasisEncoder: string;
+    };
+    /**
+     * Worker pool to use instead of creating one. Its workers must already be initialized with the encoder worker protocol;
+     * this release has no public worker bootstrap. Each instance captures this setting at construction and never disposes the pool.
+     * @experimental
+     */
+    static WorkerPool?: AutoReleaseWorkerPool;
+    /**
+     * Default number of workers: half the logical processors, from 1 to 2.
+     * @experimental
+     */
+    static DefaultNumWorkers: number;
+    /**
+     * Encoder-wide options. Defined values override per-call options for the usages they apply to.
+     * @experimental
+     */
+    static DefaultEncoderOptions: DefaultKTX2EncoderOptions;
+    private static _WorkerPoolPromise?;
+    private static _MainThreadSettings?;
+    private static _MainThreadEncoderPromise?;
+    private static readonly _MainThreadLock;
+    private readonly _workerPool?;
+    private static _Initialize;
+    private static _CreateMainThreadEncoderAsync;
+    /**
+     * Configures the shared encoder without loading scripts or creating workers.
+     * The first construction without a worker pool fixes the automatic worker count, URLs, and dependencies.
+     * @param numWorkersOrOptions The number of workers, or encoder options. Specify `0` to encode on the main thread.
+     * @experimental
+     */
+    constructor(numWorkersOrOptions?: number | IKhronosTextureContainer2EncoderOptions);
+    /**
+     * Encodes level zero of a 2D unsigned byte texture to a top-down KTX2 image.
+     * flipY and mipmap generation are derived from the texture. Texture UV transforms are not baked into the image.
+     * Cancellation rejects promptly; an active worker finishes its encode before taking more work, and main-thread encoding is cooperative.
+     * @param texture Source texture. Dimensions must be multiples of 4 from 4 through 16,384, with at most 12,582,912 pixels.
+     * @param options Encoding options and an optional cancellation signal.
+     * @returns KTX2 file bytes.
+     * @internal
+     */
+    _encodeAsync(texture: BaseTexture, options: Omit<IKTX2EncoderOptions, "flipY" | "generateMipmaps"> & {
+        signal?: AbortSignal;
+    }): Promise<Uint8Array>;
+    private static _EncodeOnWorkerAsync;
+    private static _EncodeOnMainThreadAsync;
+}