ris-ktx2-api 0.1.0-dev.2.4

package/src/ris-ktx2/KtxTranscodeFlags.ts

@@ -0,0 +1,32 @@
+/**
+ * Flags that select options for Basis Universal transcoding.
+ *
+ * Numeric values match the libktx `ktx_transcode_flag_bits_e` enumerators.
+ * Combine them with bitwise OR when more than one option applies.
+ */
+export enum KtxTranscodeFlags {
+    /** No special transcoding options. */
+    NONE = 0,
+
+    /**
+     * For PVRTC1, decode a non-power-of-two ETC1S level to the next larger
+     * power of two.
+     *
+     * libktx still documents this option as not implemented. It is ignored
+     * when the slice dimensions are already powers of two.
+     */
+    PVRTC_DECODE_TO_NEXT_POW2 = 2,
+
+    /**
+     * When transcoding to an opaque format, decode the alpha slice instead of
+     * the color slice if the Basis data has alpha. Has no effect when there
+     * is no alpha data.
+     */
+    TRANSCODE_ALPHA_DATA_TO_OPAQUE_FORMATS = 4,
+
+    /**
+     * Request a higher-quality transcode of UASTC to BC1, BC3, ETC2 EAC R11,
+     * or ETC2 EAC RG11. Unused by other UASTC transcode targets.
+     */
+    HIGH_QUALITY = 32,
+}

package/src/ris-ktx2/KtxTranscodeFormat.ts

@@ -0,0 +1,121 @@
+/**
+ * Target formats for transcoding a Basis Universal (ETC1S or UASTC) texture.
+ *
+ * Numeric values match the libktx `ktx_transcode_fmt_e` enumerators.
+ * Gaps in the numbering are formats libktx does not expose (there is no
+ * equivalent `VkFormat` for the omitted targets).
+ */
+export enum KtxTranscodeFormat {
+    /**
+     * Opaque ETC1 RGB. Returns alpha data instead when
+     * {@link KtxTranscodeFlags.TRANSCODE_ALPHA_DATA_TO_OPAQUE_FORMATS} is set.
+     */
+    KTX_TTF_ETC1_RGB = 0,
+
+    /**
+     * ETC2 RGBA. An EAC alpha block followed by an ETC1 block.
+     * Textures without alpha get an opaque alpha channel.
+     */
+    ETC2_RGBA = 1,
+
+    /**
+     * Opaque BC1 RGB. Returns alpha data instead when
+     * {@link KtxTranscodeFlags.TRANSCODE_ALPHA_DATA_TO_OPAQUE_FORMATS} is set.
+     */
+    KTX_TTF_BC1_RGB = 2,
+
+    /**
+     * BC3 compressed RGBA.
+     * Common on desktop devices. Widely supported block compression for color textures.
+     */
+    BC3_RGBA = 3,
+
+    /**
+     * Single-channel BC4. The red channel is the opaque or alpha green component,
+     * depending on {@link KtxTranscodeFlags.TRANSCODE_ALPHA_DATA_TO_OPAQUE_FORMATS}.
+     */
+    KTX_TTF_BC4_R = 4,
+
+    /**
+     * Two-channel BC5 (red and green). Intended for tangent-space normal maps.
+     * The texture should have an alpha channel; otherwise green is 255.
+     */
+    KTX_TTF_BC5_RG = 5,
+
+    /**
+     * BC7 compressed RGBA.
+     * High quality block compression for color textures.
+     * Supports an alpha channel and is suitable for diffuse and physically based textures.
+     */
+    BC7_RGBA = 6,
+
+    /**
+     * Opaque PVRTC1 4bpp RGB. Returns alpha data instead when
+     * {@link KtxTranscodeFlags.TRANSCODE_ALPHA_DATA_TO_OPAQUE_FORMATS} is set.
+     */
+    KTX_TTF_PVRTC1_4_RGB = 8,
+
+    /**
+     * PVRTC1 4bpp RGBA. Useful for simple opacity maps.
+     * If the texture has no alpha channel, PVRTC1 4bpp RGB is used instead.
+     */
+    KTX_TTF_PVRTC1_4_RGBA = 9,
+
+    /**
+     * ASTC 4×4 RGBA.
+     * Common on mobile devices, especially Apple. High quality block compression
+     * for color textures, including an alpha channel.
+     */
+    ASTC_4X4_RGBA = 10,
+
+    /**
+     * Uncompressed 32bpp RGBA in raster order (R, G, B, A).
+     * Supported on all devices.
+     */
+    RGBA32 = 13,
+
+    /** Uncompressed 16bpp RGB565 in raster order, with red in the high bits. */
+    KTX_TTF_RGB565 = 14,
+
+    /** Uncompressed 16bpp BGR565 in raster order, with red in the low bits. */
+    KTX_TTF_BGR565 = 15,
+
+    /** Uncompressed 16bpp RGBA4444 in raster order. */
+    KTX_TTF_RGBA4444 = 16,
+
+    /**
+     * Opaque PVRTC2 4bpp RGB. Supports arbitrary dimensions, unlike PVRTC1.
+     */
+    KTX_TTF_PVRTC2_4_RGB = 18,
+
+    /** PVRTC2 4bpp RGBA. Premultiplied alpha is recommended. */
+    KTX_TTF_PVRTC2_4_RGBA = 19,
+
+    /**
+     * Unsigned ETC2 EAC R11. The red channel is the opaque or alpha green
+     * component, depending on
+     * {@link KtxTranscodeFlags.TRANSCODE_ALPHA_DATA_TO_OPAQUE_FORMATS}.
+     */
+    KTX_TTF_ETC2_EAC_R11 = 20,
+
+    /**
+     * Unsigned ETC2 EAC RG11. Intended for tangent-space normal maps.
+     * The texture should have an alpha channel; otherwise green is 255.
+     */
+    KTX_TTF_ETC2_EAC_RG11 = 21,
+
+    /**
+     * Selects {@link KtxTranscodeFormat.KTX_TTF_ETC1_RGB} or
+     * {@link KtxTranscodeFormat.ETC2_RGBA} according to whether the texture has alpha.
+     */
+    KTX_TTF_ETC = 22,
+
+    /**
+     * Selects {@link KtxTranscodeFormat.KTX_TTF_BC1_RGB} or
+     * {@link KtxTranscodeFormat.BC3_RGBA} according to whether the texture has alpha.
+     */
+    BC1_OR_3 = 23,
+
+    /** No transcode format selected. */
+    NO_SELECTION = 2147483647,
+}

package/src/ris-ktx2/KtxUastcFlags.ts

@@ -0,0 +1,66 @@
+/**
+ * UASTC encoding configuration flags.
+ *
+ * Packed bitfield matching libktx `ktx_pack_uastc_flag_bits_e`.
+ * Bits 0–3 hold the compression level ({@link KtxUastcFlags.LEVEL_MASK}).
+ * {@link KtxUastcFlags.FAVOR_UASTC_ERROR} is `8`, so it sits inside that mask:
+ * combining it with a level changes the value `LEVEL_MASK` extracts.
+ * Hints at bit 4 and above (`16`, `64`, `128`, `256`) combine with a level
+ * with bitwise OR and leave bits 0–3 unchanged.
+ */
+export enum KtxUastcFlags {
+    /**
+     * Fastest compression (lowest quality, highest speed). About 43.45 dB.
+     */
+    LEVEL_FASTEST = 0,
+
+    /**
+     * Faster compression. About 46.49 dB.
+     */
+    LEVEL_FASTER = 1,
+
+    /**
+     * Default compression level. About 47.47 dB.
+     */
+    LEVEL_DEFAULT = 2,
+
+    /**
+     * Slower compression (higher quality). About 48.01 dB.
+     */
+    LEVEL_SLOWER = 3,
+
+    /**
+     * Very slow compression (highest quality). About 48.24 dB.
+     */
+    LEVEL_VERY_SLOW = 4,
+
+    /**
+     * Mask for the compression level in bits 0–3.
+     */
+    LEVEL_MASK = 15,
+
+    /**
+     * Optimize encoding for the lowest UASTC reconstruction error.
+     */
+    FAVOR_UASTC_ERROR = 8,
+
+    /**
+     * Optimize encoding for the lowest BC7 decode error.
+     */
+    FAVOR_BC7_ERROR = 16,
+
+    /**
+     * Hint to optimize for faster ETC1 transcoding.
+     */
+    ETC1_FASTER_HINTS = 64,
+
+    /**
+     * Hint to optimize for the fastest ETC1 transcoding.
+     */
+    ETC1_FASTEST_HINTS = 128,
+
+    /**
+     * Disables flip-and-individual optimizations for ETC1 transcoding.
+     */
+    ETC1_DISABLE_FLIP_AND_INDIVIDUAL = 256,
+}

package/src/ris-ktx2/TextureFormatInfo.ts

@@ -0,0 +1,275 @@
+import {VkFormat} from "./VkFormat.ts";
+
+/**
+ * Describes how a texture format is laid out in memory, in blocks.
+ *
+ * For uncompressed formats a block is one pixel:
+ * `blockWidth` and `blockHeight` are `1`, and `bytesPerBlock` is the bytes per pixel.
+ *
+ * For compressed formats such as BC7, a block is a group of pixels
+ * (typically 4×4) stored in a fixed number of bytes.
+ */
+export class TextureFormatInfo {
+    /** Width of one block, in pixels. */
+    public readonly blockWidth: number;
+
+    /** Height of one block, in pixels. */
+    public readonly blockHeight: number;
+
+    /** Depth of one block, in pixels. */
+    public readonly blockDepth: number;
+
+    /** Size of one block, in bytes. */
+    public readonly bytesPerBlock: number;
+
+    /**
+     * Average number of bytes used per pixel.
+     *
+     * For uncompressed formats this is the bytes per pixel.
+     * For compressed formats this is the average storage cost per pixel.
+     */
+    public get pixelSize(): number {
+        return this.bytesPerBlock /
+            (this.blockWidth * this.blockHeight * this.blockDepth);
+    }
+
+    /**
+     * Creates a block-layout description.
+     *
+     * @param blockWidth - Block width, in pixels.
+     * @param blockHeight - Block height, in pixels.
+     * @param blockDepth - Block depth, in pixels.
+     * @param bytesPerBlock - Bytes stored in one block.
+     */
+    public constructor(
+        blockWidth: number,
+        blockHeight: number,
+        blockDepth: number,
+        bytesPerBlock: number
+    ) {
+        this.blockWidth = blockWidth;
+        this.blockHeight = blockHeight;
+        this.blockDepth = blockDepth;
+        this.bytesPerBlock = bytesPerBlock;
+    }
+
+    /**
+     * Number of blocks needed to cover `width` pixels.
+     *
+     * @param width - Texture width, in pixels.
+     * @returns Block count, rounded up to a whole block.
+     */
+    public getBlocksPerRow(width: number): number {
+        return Math.ceil(width / this.blockWidth);
+    }
+
+    /**
+     * Number of block rows needed to cover `height` pixels.
+     *
+     * @param height - Texture height, in pixels.
+     * @returns Block-row count, rounded up to a whole block.
+     */
+    public getBlocksPerColumn(height: number): number {
+        return Math.ceil(height / this.blockHeight);
+    }
+
+    /**
+     * Number of block slices needed to cover `depth` pixels.
+     *
+     * @param depth - Texture depth, in pixels.
+     * @returns Block-slice count, rounded up to a whole block.
+     */
+    public getBlocksPerSlice(depth: number): number {
+        return Math.ceil(depth / this.blockDepth);
+    }
+
+    /**
+     * Unaligned number of bytes in one row of blocks.
+     *
+     * @param width - Texture width, in pixels.
+     * @returns Bytes per row, without a 256-byte alignment.
+     */
+    public getBytesPerRow(width: number): number {
+        return this.getBlocksPerRow(width) * this.bytesPerBlock;
+    }
+
+    /**
+     * WebGPU `bytesPerRow` for `width`.
+     *
+     * WebGPU requires `bytesPerRow` to be a multiple of 256.
+     *
+     * @param width - Texture width, in pixels.
+     * @returns `getBytesPerRow(width)` rounded up to a multiple of 256.
+     */
+    public getAlignedBytesPerRow(width: number): number {
+        const bytesPerRow = this.getBytesPerRow(width);
+        return Math.ceil(bytesPerRow / 256) * 256;
+    }
+
+    /**
+     * Byte size of one 2D mip level.
+     *
+     * @param width - Level width, in pixels.
+     * @param height - Level height, in pixels.
+     * @returns Level size, in bytes.
+     */
+    public getDataSize(width: number, height: number): number {
+        const blocksX = this.getBlocksPerRow(width);
+        const blocksY = this.getBlocksPerColumn(height);
+
+        return blocksX * blocksY * this.bytesPerBlock;
+    }
+
+    /**
+     * Byte size of one 3D mip level.
+     *
+     * @param width - Level width, in pixels.
+     * @param height - Level height, in pixels.
+     * @param depth - Level depth, in pixels.
+     * @returns Level size, in bytes.
+     */
+    public getDataSize3D(
+        width: number,
+        height: number,
+        depth: number
+    ): number {
+        const blocksX = this.getBlocksPerRow(width);
+        const blocksY = this.getBlocksPerColumn(height);
+        const blocksZ = this.getBlocksPerSlice(depth);
+
+        return blocksX * blocksY * blocksZ * this.bytesPerBlock;
+    }
+
+    /**
+     * BC7 layout: 4×4 blocks, 16 bytes per block.
+     *
+     * @returns The BC7 {@link TextureFormatInfo}.
+     */
+    public static bc7(): TextureFormatInfo {
+        return new TextureFormatInfo(4, 4, 1, 16);
+    }
+
+    /**
+     * BC3 layout: 4×4 blocks, 16 bytes per block.
+     *
+     * @returns The BC3 {@link TextureFormatInfo}.
+     */
+    public static bc3(): TextureFormatInfo {
+        return new TextureFormatInfo(4, 4, 1, 16);
+    }
+
+    /**
+     * ETC2 RGBA layout: 4×4 blocks, 16 bytes per block.
+     *
+     * @returns The ETC2 RGBA {@link TextureFormatInfo}.
+     */
+    public static etc2rgba(): TextureFormatInfo {
+        return new TextureFormatInfo(4, 4, 1, 16);
+    }
+
+    /**
+     * ASTC 4×4 RGBA layout: 4×4 blocks, 16 bytes per block.
+     *
+     * @returns The ASTC 4×4 RGBA {@link TextureFormatInfo}.
+     */
+    public static astc4x4rgba(): TextureFormatInfo {
+        return new TextureFormatInfo(4, 4, 1, 16);
+    }
+
+    /**
+     * Uncompressed 8-bit 4-channel layout: 1×1 blocks, 4 bytes per pixel.
+     *
+     * Channel order does not change the size. `B8G8R8A8_*` and
+     * `A8B8G8R8_*_PACK32` use this same layout.
+     *
+     * @returns The 4-byte {@link TextureFormatInfo}.
+     */
+    public static rgba32(): TextureFormatInfo {
+        return new TextureFormatInfo(1, 1, 1, 4);
+    }
+
+    /**
+     * `D24_UNORM_S8_UINT` layout: 4 bytes per pixel.
+     *
+     * @returns The depth/stencil {@link TextureFormatInfo}.
+     */
+    public static depth24Stencil8(): TextureFormatInfo {
+        return new TextureFormatInfo(1, 1, 1, 4);
+    }
+
+    /**
+     * `D32_SFLOAT` layout: 4 bytes per pixel.
+     *
+     * @returns The 32-bit float depth {@link TextureFormatInfo}.
+     */
+    public static depth32float(): TextureFormatInfo {
+        return new TextureFormatInfo(1, 1, 1, 4);
+    }
+
+    /**
+     * Block layout for a Vulkan format this package knows how to size.
+     *
+     * sRGB, signed, integer, and scaled variants share the block size of the
+     * matching unsigned normalized format. Channel order does not change the
+     * byte size.
+     *
+     * - `R8G8B8A8_*`, `B8G8R8A8_*`, and `A8B8G8R8_*_PACK32` use {@link TextureFormatInfo.rgba32}.
+     * - `D24_UNORM_S8_UINT` uses {@link TextureFormatInfo.depth24Stencil8}.
+     * - `D32_SFLOAT` uses {@link TextureFormatInfo.depth32float}.
+     * - `BC3_UNORM_BLOCK` and `BC3_SRGB_BLOCK` use {@link TextureFormatInfo.bc3}.
+     * - `BC7_UNORM_BLOCK` and `BC7_SRGB_BLOCK` use {@link TextureFormatInfo.bc7}.
+     * - `ETC2_R8G8B8A8_UNORM_BLOCK` and `ETC2_R8G8B8A8_SRGB_BLOCK` use {@link TextureFormatInfo.etc2rgba}.
+     * - `ASTC_4X4_UNORM_BLOCK`, `ASTC_4X4_SRGB_BLOCK`, and `ASTC_4X4_SFLOAT_BLOCK`
+     *   use {@link TextureFormatInfo.astc4x4rgba}. `ASTC_4X4_SFLOAT_BLOCK_EXT`
+     *   is the same value as `ASTC_4X4_SFLOAT_BLOCK`.
+     *
+     * @param vkFormat - Vulkan format.
+     * @returns The matching layout.
+     * @throws {Error} When `vkFormat` has no layout in this package.
+     */
+    public static fromVkFormat(vkFormat: VkFormat): TextureFormatInfo {
+        switch (vkFormat) {
+            case VkFormat.R8G8B8A8_UNORM:
+            case VkFormat.R8G8B8A8_SNORM:
+            case VkFormat.R8G8B8A8_USCALED:
+            case VkFormat.R8G8B8A8_SSCALED:
+            case VkFormat.R8G8B8A8_UINT:
+            case VkFormat.R8G8B8A8_SINT:
+            case VkFormat.R8G8B8A8_SRGB:
+            case VkFormat.B8G8R8A8_UNORM:
+            case VkFormat.B8G8R8A8_SNORM:
+            case VkFormat.B8G8R8A8_USCALED:
+            case VkFormat.B8G8R8A8_SSCALED:
+            case VkFormat.B8G8R8A8_UINT:
+            case VkFormat.B8G8R8A8_SINT:
+            case VkFormat.B8G8R8A8_SRGB:
+            case VkFormat.A8B8G8R8_UNORM_PACK32:
+            case VkFormat.A8B8G8R8_SNORM_PACK32:
+            case VkFormat.A8B8G8R8_USCALED_PACK32:
+            case VkFormat.A8B8G8R8_SSCALED_PACK32:
+            case VkFormat.A8B8G8R8_UINT_PACK32:
+            case VkFormat.A8B8G8R8_SINT_PACK32:
+            case VkFormat.A8B8G8R8_SRGB_PACK32:
+                return this.rgba32();
+            case VkFormat.D24_UNORM_S8_UINT:
+                return this.depth24Stencil8();
+            case VkFormat.D32_SFLOAT:
+                return this.depth32float();
+            case VkFormat.ASTC_4X4_UNORM_BLOCK:
+            case VkFormat.ASTC_4X4_SRGB_BLOCK:
+            case VkFormat.ASTC_4X4_SFLOAT_BLOCK:
+                return this.astc4x4rgba();
+            case VkFormat.BC7_UNORM_BLOCK:
+            case VkFormat.BC7_SRGB_BLOCK:
+                return this.bc7();
+            case VkFormat.BC3_UNORM_BLOCK:
+            case VkFormat.BC3_SRGB_BLOCK:
+                return this.bc3();
+            case VkFormat.ETC2_R8G8B8A8_UNORM_BLOCK:
+            case VkFormat.ETC2_R8G8B8A8_SRGB_BLOCK:
+                return this.etc2rgba();
+            default:
+                throw new Error(`TextureFormatInfo.fromVkFormat has no layout for VkFormat ${vkFormat}.`);
+        }
+    }
+}