@flighthq/texture-formats 0.1.0

package/src/parseAtf.test.ts

@@ -0,0 +1,288 @@
+import type { TextureContainer } from '@flighthq/types';
+import { describe, expect, it } from 'vitest';
+
+import { parseAtf } from './parseAtf';
+import { selectTextureContainer } from './selectTextureContainer';
+
+interface AtfOptions {
+  version: number;
+  formatCode: number;
+  cube?: boolean;
+  log2Width: number;
+  log2Height: number;
+  mipCount: number;
+  // Block byte-lengths in the file's stored order: side-major, then mip level, then GPU-format slot
+  // (0 = DXT, 1 = ETC1, 2 = PVRTC, 3 = ETC2). A zero length marks an absent encoding — the length prefix
+  // is still written. The caller supplies exactly `sides * mipCount * slotCount` entries.
+  blockLengths: readonly number[];
+}
+
+// Builds a minimal ATF byte buffer to the OpenFL `ATFReader` framing and reports the absolute data
+// byteOffset of each block, so a test asserts the parser reproduces the builder's own bookkeeping rather
+// than a hand-computed number. A versioned file (version != 0) uses the 12-byte header + 32-bit block
+// lengths; version 0 uses the 6-byte header + 24-bit block lengths.
+function buildAtf(opts: AtfOptions): { bytes: Uint8Array; blockOffsets: number[] } {
+  const { version, formatCode, cube = false, log2Width, log2Height, mipCount, blockLengths } = opts;
+  const versioned = version !== 0;
+  const headerOffset = versioned ? 12 : 6;
+  const lengthWidth = versioned ? 4 : 3;
+  const bodySize = blockLengths.reduce((sum, length) => sum + lengthWidth + length, 0);
+  const bytes = new Uint8Array(headerOffset + 4 + bodySize);
+
+  bytes[0] = 0x41; // 'A'
+  bytes[1] = 0x54; // 'T'
+  bytes[2] = 0x46; // 'F'
+
+  // Declared payload = everything from the format header (tdata) to the end of the buffer.
+  const payloadLength = bytes.byteLength - headerOffset;
+  if (versioned) {
+    bytes[6] = 0xff; // version marker
+    bytes[7] = version;
+    writeUintBigEndian(bytes, 8, payloadLength, 4);
+  } else {
+    writeUintBigEndian(bytes, 3, payloadLength, 3);
+  }
+
+  bytes[headerOffset] = (cube ? 0x80 : 0) | formatCode;
+  bytes[headerOffset + 1] = log2Width;
+  bytes[headerOffset + 2] = log2Height;
+  bytes[headerOffset + 3] = mipCount;
+
+  const blockOffsets: number[] = [];
+  let offset = headerOffset + 4;
+  for (const length of blockLengths) {
+    writeUintBigEndian(bytes, offset, length, lengthWidth);
+    offset += lengthWidth;
+    blockOffsets.push(offset);
+    for (let i = 0; i < length; i += 1) bytes[offset + i] = (offset + i) & 0xff;
+    offset += length;
+  }
+  return { blockOffsets, bytes };
+}
+
+function writeUintBigEndian(bytes: Uint8Array, offset: number, value: number, width: number): void {
+  for (let i = 0; i < width; i += 1) bytes[offset + i] = (value >>> ((width - 1 - i) * 8)) & 0xff;
+}
+
+// Asserts every located level range lies inside the buffer and no two ranges overlap (gaps for the
+// length prefixes between data blocks are expected).
+function expectLevelRangesInBounds(containers: readonly TextureContainer[], byteLength: number): void {
+  const ranges: [number, number][] = [];
+  for (const container of containers) {
+    for (const level of container.levels) ranges.push([level.byteOffset, level.byteOffset + level.byteLength]);
+  }
+  ranges.sort((a, b) => a[0] - b[0]);
+  let previousEnd = 0;
+  for (const [start, end] of ranges) {
+    expect(start).toBeGreaterThanOrEqual(previousEnd); // non-overlapping
+    expect(end).toBeLessThanOrEqual(byteLength); // in-bounds
+    previousEnd = end;
+  }
+}
+
+describe('parseAtf', () => {
+  it('parses a cross-platform ATF as one peer container per populated GPU-format slot', () => {
+    // Version 3, format 5 (RAW_COMPRESSED_ALPHA), 8x8, 3 mips, all four slots populated.
+    // Slot sizes per level, in side -> level -> slot order:
+    //   level0: bc3=64  etc1=32  pvrtc=24  etc2=64
+    //   level1: bc3=16  etc1=8   pvrtc=6   etc2=16
+    //   level2: bc3=16  etc1=8   pvrtc=6   etc2=16
+    const { blockOffsets, bytes } = buildAtf({
+      blockLengths: [64, 32, 24, 64, 16, 8, 6, 16, 16, 8, 6, 16],
+      formatCode: 5,
+      log2Height: 3,
+      log2Width: 3,
+      mipCount: 3,
+      version: 3,
+    });
+
+    const containers = parseAtf(bytes);
+    expect(containers).not.toBeNull();
+    expect(containers).toHaveLength(4);
+    expect(containers!.map((c) => c.format)).toEqual(['bc3', 'etc1', 'pvrtc4bppRgba', 'etc2Rgba']);
+    for (const container of containers!) {
+      expect(container.width).toBe(8);
+      expect(container.height).toBe(8);
+      expect(container.mipLevels).toBe(3);
+      expect(container.faces).toBe(1);
+      expect(container.levels).toHaveLength(3);
+    }
+
+    // The DXT5 (bc3) slot owns blocks 0, 4, 8; its level0 byteLength is the DXT5 size emitted (64).
+    expect(containers![0].levels).toEqual([
+      { byteLength: 64, byteOffset: blockOffsets[0], height: 8, width: 8 },
+      { byteLength: 16, byteOffset: blockOffsets[4], height: 4, width: 4 },
+      { byteLength: 16, byteOffset: blockOffsets[8], height: 2, width: 2 },
+    ]);
+    expect(containers![0].levels[0].byteLength).toBe(64);
+    // ETC2 slot owns blocks 3, 7, 11.
+    expect(containers![3].levels).toEqual([
+      { byteLength: 64, byteOffset: blockOffsets[3], height: 8, width: 8 },
+      { byteLength: 16, byteOffset: blockOffsets[7], height: 4, width: 4 },
+      { byteLength: 16, byteOffset: blockOffsets[11], height: 2, width: 2 },
+    ]);
+
+    expectLevelRangesInBounds(containers!, bytes.byteLength);
+    expect(selectTextureContainer(containers!, ['bc3'])).toBe(containers![0]);
+  });
+
+  it('drops all-zero slots, yielding a single-format array', () => {
+    // Version 3, format 5, 8x8, 3 mips, but only the DXT5 slot carries data (slots 1-3 length-0).
+    const { blockOffsets, bytes } = buildAtf({
+      blockLengths: [64, 0, 0, 0, 16, 0, 0, 0, 16, 0, 0, 0],
+      formatCode: 5,
+      log2Height: 3,
+      log2Width: 3,
+      mipCount: 3,
+      version: 3,
+    });
+
+    const containers = parseAtf(bytes);
+    expect(containers).not.toBeNull();
+    expect(containers).toHaveLength(1);
+    expect(containers![0].format).toBe('bc3');
+    expect(containers![0].levels).toEqual([
+      { byteLength: 64, byteOffset: blockOffsets[0], height: 8, width: 8 },
+      { byteLength: 16, byteOffset: blockOffsets[4], height: 4, width: 4 },
+      { byteLength: 16, byteOffset: blockOffsets[8], height: 2, width: 2 },
+    ]);
+  });
+
+  it('reports mipLevels as the POPULATED count, not the declared mipCount (empty-mipmaps files)', () => {
+    // png2atf "empty mipmaps": the header declares the full chain (3) but only the base level is
+    // stored; mips 1-2 are length-0 across every slot. mipLevels must be 1, matching levels.length —
+    // this is the case the real Starling compressed_texture.atf exercises and synthetic slot-drop
+    // tests missed.
+    const { blockOffsets, bytes } = buildAtf({
+      blockLengths: [64, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
+      formatCode: 5,
+      log2Height: 3,
+      log2Width: 3,
+      mipCount: 3,
+      version: 3,
+    });
+
+    const containers = parseAtf(bytes);
+    expect(containers).toHaveLength(1);
+    expect(containers![0].format).toBe('bc3');
+    expect(containers![0].mipLevels).toBe(1);
+    expect(containers![0].levels).toEqual([{ byteLength: 64, byteOffset: blockOffsets[0], height: 8, width: 8 }]);
+  });
+
+  it('exposes only three GPU-format slots before version 3 (no ETC2)', () => {
+    // Version 2, format 3 (RAW_COMPRESSED, opaque), 4x4, 1 mip, three slots populated. A four-slot walk
+    // would read a phantom fourth length prefix and overrun; three containers proves the 3-slot stride.
+    const { bytes } = buildAtf({
+      blockLengths: [8, 8, 8],
+      formatCode: 3,
+      log2Height: 2,
+      log2Width: 2,
+      mipCount: 1,
+      version: 2,
+    });
+
+    const containers = parseAtf(bytes);
+    expect(containers).not.toBeNull();
+    expect(containers).toHaveLength(3);
+    expect(containers!.map((c) => c.format)).toEqual(['bc1', 'etc1', 'pvrtc4bppRgb']);
+  });
+
+  it('reports six faces for a cube ATF, sides as the container levels', () => {
+    // Cube flag set, version 3, format 3, 2x2, 1 mip, four slots. 6 sides * 1 level * 4 slots = 24 blocks.
+    // Each slot's container carries the six same-slot sides as its levels (side-major for the single mip).
+    const { bytes } = buildAtf({
+      blockLengths: new Array(24).fill(8),
+      cube: true,
+      formatCode: 3,
+      log2Height: 1,
+      log2Width: 1,
+      mipCount: 1,
+      version: 3,
+    });
+
+    const containers = parseAtf(bytes);
+    expect(containers).not.toBeNull();
+    expect(containers).toHaveLength(4);
+    for (const container of containers!) {
+      expect(container.faces).toBe(6);
+      expect(container.levels).toHaveLength(6); // 6 sides * 1 mip
+    }
+  });
+
+  it('reads the legacy version-0 header and 24-bit block lengths', () => {
+    // Version 0: 6-byte header at offset 6, 24-bit big-endian block-length prefixes, three slots.
+    const { blockOffsets, bytes } = buildAtf({
+      blockLengths: [16, 0, 0, 16, 0, 0],
+      formatCode: 5,
+      log2Height: 2,
+      log2Width: 2,
+      mipCount: 2,
+      version: 0,
+    });
+
+    const containers = parseAtf(bytes);
+    expect(containers).not.toBeNull();
+    expect(containers).toHaveLength(1);
+    expect(containers![0].format).toBe('bc3');
+    expect(containers![0].width).toBe(4);
+    expect(containers![0].height).toBe(4);
+    expect(containers![0].levels).toEqual([
+      { byteLength: 16, byteOffset: blockOffsets[0], height: 4, width: 4 },
+      { byteLength: 16, byteOffset: blockOffsets[3], height: 2, width: 2 },
+    ]);
+  });
+
+  it('returns null for non-ATF or too-short bytes', () => {
+    expect(parseAtf(new Uint8Array([0x44, 0x44, 0x53, 0x20, 0, 0, 0]))).toBeNull(); // 'DDS '
+    expect(parseAtf(new Uint8Array([0x41, 0x54]))).toBeNull(); // too short for the signature
+  });
+
+  it('returns null for unsupported format codes', () => {
+    // Code 0 (raw BGRA) and code 1 (raw RGBA) are unsupported; only 2/3/12 and 4/5/13 are.
+    const zero = buildAtf({
+      blockLengths: [0, 0, 0, 0],
+      formatCode: 0,
+      log2Height: 2,
+      log2Width: 2,
+      mipCount: 1,
+      version: 3,
+    });
+    const one = buildAtf({
+      blockLengths: [0, 0, 0, 0],
+      formatCode: 1,
+      log2Height: 2,
+      log2Width: 2,
+      mipCount: 1,
+      version: 3,
+    });
+    expect(parseAtf(zero.bytes)).toBeNull();
+    expect(parseAtf(one.bytes)).toBeNull();
+  });
+
+  it('returns null when a block length overruns the buffer', () => {
+    // Truncating the tail drops declared payload → null.
+    const valid = buildAtf({
+      blockLengths: [64, 32, 24, 64, 16, 8, 6, 16, 16, 8, 6, 16],
+      formatCode: 5,
+      log2Height: 3,
+      log2Width: 3,
+      mipCount: 3,
+      version: 3,
+    });
+    expect(parseAtf(valid.bytes.subarray(0, valid.bytes.byteLength - 8))).toBeNull();
+
+    // A block-length prefix that claims more than the buffer holds, with the header length left intact,
+    // is caught by the per-block bounds check during the walk.
+    const patched = buildAtf({
+      blockLengths: [64, 0, 0, 0, 16, 0, 0, 0, 16, 0, 0, 0],
+      formatCode: 5,
+      log2Height: 3,
+      log2Width: 3,
+      mipCount: 3,
+      version: 3,
+    });
+    // First block's 4-byte prefix sits at offset 16 (12-byte header + 4-byte format block).
+    writeUintBigEndian(patched.bytes, 16, 0xffffff, 4);
+    expect(parseAtf(patched.bytes)).toBeNull();
+  });
+});

package/src/parseBasis.test.ts

@@ -0,0 +1,124 @@
+import { describe, expect, it } from 'vitest';
+
+import { parseBasis } from './parseBasis';
+
+interface BasisSlice {
+  imageIndex: number;
+  levelIndex: number;
+  width: number;
+  height: number;
+  fileOfs: number;
+  fileSize: number;
+}
+
+interface BasisOptions {
+  totalImages?: number;
+  texFormat?: number;
+  slices: readonly BasisSlice[];
+}
+
+const basisHeaderSize = 77;
+const basisSliceDescSize = 22;
+
+function buildBasis(opts: BasisOptions): Uint8Array {
+  const { totalImages = 1, texFormat = 0, slices } = opts;
+  const sliceTableOffset = basisHeaderSize;
+  const dataStart = sliceTableOffset + slices.length * basisSliceDescSize;
+  const total = slices.reduce((max, s) => Math.max(max, s.fileOfs + s.fileSize), dataStart);
+  const bytes = new Uint8Array(total);
+  const dv = new DataView(bytes.buffer);
+  bytes[0] = 0x73; // 's'
+  bytes[1] = 0x42; // 'B'
+  dv.setUint16(12, slices.length, true); // m_total_slices
+  dv.setUint16(14, totalImages, true); // m_total_images
+  bytes[16] = texFormat; // m_tex_format
+  dv.setUint32(61, sliceTableOffset, true); // m_slice_desc_file_ofs
+  let off = sliceTableOffset;
+  for (const slice of slices) {
+    dv.setUint16(off + 0, slice.imageIndex, true);
+    bytes[off + 2] = slice.levelIndex;
+    dv.setUint16(off + 4, slice.width, true);
+    dv.setUint16(off + 6, slice.height, true);
+    dv.setUint32(off + 12, slice.fileOfs, true);
+    dv.setUint32(off + 16, slice.fileSize, true);
+    off += basisSliceDescSize;
+  }
+  return bytes;
+}
+
+describe('parseBasis', () => {
+  it('parses a single-slice ETC1S image', () => {
+    const container = parseBasis(
+      buildBasis({ slices: [{ fileOfs: 99, fileSize: 8, height: 4, imageIndex: 0, levelIndex: 0, width: 4 }] }),
+    );
+    expect(container).not.toBeNull();
+    expect(container!.format).toBe('etc1s');
+    expect(container!.width).toBe(4);
+    expect(container!.height).toBe(4);
+    expect(container!.mipLevels).toBe(1);
+    expect(container!.layers).toBe(1);
+    expect(container!.faces).toBe(1);
+    expect(container!.supercompression).toBe('None');
+    expect(container!.levels).toEqual([{ byteLength: 8, byteOffset: 99, height: 4, width: 4 }]);
+  });
+
+  it('reports a mip chain from the slice level indices', () => {
+    const container = parseBasis(
+      buildBasis({
+        slices: [
+          { fileOfs: 121, fileSize: 8, height: 4, imageIndex: 0, levelIndex: 0, width: 4 },
+          { fileOfs: 129, fileSize: 4, height: 2, imageIndex: 0, levelIndex: 1, width: 2 },
+        ],
+      }),
+    );
+    expect(container).not.toBeNull();
+    expect(container!.mipLevels).toBe(2);
+    expect(container!.levels.map((l) => l.width)).toEqual([4, 2]);
+    expect(container!.levels.map((l) => l.byteOffset)).toEqual([121, 129]);
+  });
+
+  it('maps the UASTC texture format', () => {
+    const container = parseBasis(
+      buildBasis({
+        slices: [{ fileOfs: 99, fileSize: 16, height: 4, imageIndex: 0, levelIndex: 0, width: 4 }],
+        texFormat: 1,
+      }),
+    );
+    expect(container!.format).toBe('uastc');
+  });
+
+  it('reports each image as an array layer', () => {
+    const container = parseBasis(
+      buildBasis({
+        slices: [
+          { fileOfs: 121, fileSize: 8, height: 4, imageIndex: 0, levelIndex: 0, width: 4 },
+          { fileOfs: 129, fileSize: 8, height: 4, imageIndex: 1, levelIndex: 0, width: 4 },
+        ],
+        totalImages: 2,
+      }),
+    );
+    expect(container!.layers).toBe(2);
+    expect(container!.levels).toHaveLength(2);
+  });
+
+  it('returns null for a non-Basis, truncated, or unknown-format buffer', () => {
+    expect(parseBasis(new Uint8Array([0x44, 0x44, 0x53, 0x20]))).toBeNull();
+    expect(parseBasis(new Uint8Array([0x73, 0x42, 0, 0]))).toBeNull();
+    expect(
+      parseBasis(
+        buildBasis({
+          slices: [{ fileOfs: 99, fileSize: 8, height: 4, imageIndex: 0, levelIndex: 0, width: 4 }],
+          texFormat: 5,
+        }),
+      ),
+    ).toBeNull();
+  });
+
+  it('returns null when the slice table runs past the buffer', () => {
+    const bytes = buildBasis({
+      slices: [{ fileOfs: 99, fileSize: 8, height: 4, imageIndex: 0, levelIndex: 0, width: 4 }],
+    });
+    new DataView(bytes.buffer).setUint32(61, 1_000_000, true); // corrupt m_slice_desc_file_ofs
+    expect(parseBasis(bytes)).toBeNull();
+  });
+});

package/src/parseDds.test.ts

@@ -0,0 +1,146 @@
+import { describe, expect, it } from 'vitest';
+
+import { parseDds } from './parseDds';
+
+function fourCC(text: string): number {
+  return (
+    (text.charCodeAt(0) | (text.charCodeAt(1) << 8) | (text.charCodeAt(2) << 16) | (text.charCodeAt(3) << 24)) >>> 0
+  );
+}
+
+interface Dx10Options {
+  dxgiFormat: number;
+  miscFlag?: number;
+  arraySize?: number;
+}
+
+interface DdsOptions {
+  width: number;
+  height: number;
+  mipMapCount?: number;
+  pfFlags: number;
+  fourCC?: number;
+  rgbBitCount?: number;
+  masks?: readonly [number, number, number, number];
+  caps2?: number;
+  dx10?: Dx10Options;
+  dataBytes?: number;
+}
+
+function buildDds(opts: DdsOptions): Uint8Array {
+  const {
+    width,
+    height,
+    mipMapCount = 1,
+    pfFlags,
+    fourCC: fourCCValue = 0,
+    rgbBitCount = 0,
+    masks = [0, 0, 0, 0],
+    caps2 = 0,
+    dx10,
+    dataBytes = 256,
+  } = opts;
+  const headerEnd = 128 + (dx10 ? 20 : 0);
+  const bytes = new Uint8Array(headerEnd + dataBytes);
+  const dv = new DataView(bytes.buffer);
+  bytes.set([0x44, 0x44, 0x53, 0x20], 0);
+  dv.setUint32(4, 124, true);
+  dv.setUint32(12, height, true);
+  dv.setUint32(16, width, true);
+  dv.setUint32(28, mipMapCount, true);
+  dv.setUint32(76, 32, true);
+  dv.setUint32(80, pfFlags, true);
+  dv.setUint32(84, fourCCValue, true);
+  dv.setUint32(88, rgbBitCount, true);
+  dv.setUint32(92, masks[0], true);
+  dv.setUint32(96, masks[1], true);
+  dv.setUint32(100, masks[2], true);
+  dv.setUint32(104, masks[3], true);
+  dv.setUint32(112, caps2, true);
+  if (dx10) {
+    dv.setUint32(128, dx10.dxgiFormat, true);
+    dv.setUint32(132, 3, true); // resourceDimension = TEXTURE2D
+    dv.setUint32(136, dx10.miscFlag ?? 0, true);
+    dv.setUint32(140, dx10.arraySize ?? 1, true);
+  }
+  return bytes;
+}
+
+describe('parseDds', () => {
+  it('parses a single-mip BC1 (DXT1) texture', () => {
+    const container = parseDds(buildDds({ fourCC: fourCC('DXT1'), height: 4, pfFlags: 0x4, width: 4 }));
+    expect(container).not.toBeNull();
+    expect(container!.format).toBe('bc1');
+    expect(container!.width).toBe(4);
+    expect(container!.height).toBe(4);
+    expect(container!.mipLevels).toBe(1);
+    expect(container!.faces).toBe(1);
+    expect(container!.layers).toBe(1);
+    expect(container!.supercompression).toBe('None');
+    expect(container!.levels).toEqual([{ byteLength: 8, byteOffset: 128, height: 4, width: 4 }]);
+  });
+
+  it('maps uncompressed RGBA channel masks to bgra8unorm and rgba8unorm', () => {
+    const bgra = parseDds(
+      buildDds({
+        height: 2,
+        masks: [0x00ff0000, 0x0000ff00, 0x000000ff, 0xff000000],
+        pfFlags: 0x40,
+        rgbBitCount: 32,
+        width: 2,
+      }),
+    );
+    expect(bgra!.format).toBe('bgra8unorm');
+    expect(bgra!.levels).toEqual([{ byteLength: 16, byteOffset: 128, height: 2, width: 2 }]);
+    const rgba = parseDds(
+      buildDds({
+        height: 2,
+        masks: [0x000000ff, 0x0000ff00, 0x00ff0000, 0xff000000],
+        pfFlags: 0x40,
+        rgbBitCount: 32,
+        width: 2,
+      }),
+    );
+    expect(rgba!.format).toBe('rgba8unorm');
+  });
+
+  it('reports six faces for a cubemap and a full mip chain per face', () => {
+    const container = parseDds(buildDdsCube());
+    expect(container).not.toBeNull();
+    expect(container!.faces).toBe(6);
+    expect(container!.levels).toHaveLength(6);
+    expect(container!.levels.map((l) => l.byteLength)).toEqual([16, 16, 16, 16, 16, 16]);
+    expect(container!.levels.map((l) => l.byteOffset)).toEqual([128, 144, 160, 176, 192, 208]);
+  });
+
+  it('computes descending byte ranges for a multi-mip BC1 texture', () => {
+    const container = parseDds(buildDds({ fourCC: fourCC('DXT1'), height: 8, mipMapCount: 4, pfFlags: 0x4, width: 8 }));
+    expect(container).not.toBeNull();
+    expect(container!.mipLevels).toBe(4);
+    expect(container!.levels.map((l) => l.width)).toEqual([8, 4, 2, 1]);
+    expect(container!.levels.map((l) => l.byteLength)).toEqual([32, 8, 8, 8]);
+    expect(container!.levels.map((l) => l.byteOffset)).toEqual([128, 160, 168, 176]);
+  });
+
+  it('reads a DX10 extension header and its DXGI format', () => {
+    const container = parseDds(
+      buildDds({ dx10: { dxgiFormat: 98 }, fourCC: fourCC('DX10'), height: 4, pfFlags: 0x4, width: 4 }),
+    );
+    expect(container).not.toBeNull();
+    expect(container!.format).toBe('bc7');
+    expect(container!.levels[0].byteOffset).toBe(148); // data follows the 20-byte DX10 header
+  });
+
+  it('returns null for a non-DDS, truncated, unknown-format, or volume texture', () => {
+    expect(parseDds(new Uint8Array([0xab, 0x4b, 0x54, 0x58]))).toBeNull();
+    expect(parseDds(new Uint8Array([0x44, 0x44, 0x53, 0x20, 0, 0, 0, 0]))).toBeNull();
+    expect(parseDds(buildDds({ fourCC: fourCC('ZZZZ'), height: 4, pfFlags: 0x4, width: 4 }))).toBeNull();
+    expect(
+      parseDds(buildDds({ caps2: 0x200000, fourCC: fourCC('DXT1'), height: 4, pfFlags: 0x4, width: 4 })),
+    ).toBeNull();
+  });
+});
+
+function buildDdsCube(): Uint8Array {
+  return buildDds({ caps2: 0x200, fourCC: fourCC('DXT5'), dataBytes: 96, height: 4, pfFlags: 0x4, width: 4 });
+}

package/src/parseKtx2.test.ts

@@ -0,0 +1,135 @@
+import { describe, expect, it } from 'vitest';
+
+import { parseKtx2 } from './parseKtx2';
+
+const ktx2Magic = [0xab, 0x4b, 0x54, 0x58, 0x20, 0x32, 0x30, 0xbb, 0x0d, 0x0a, 0x1a, 0x0a];
+
+interface Ktx2Level {
+  byteOffset: number;
+  byteLength: number;
+}
+
+interface Ktx2Options {
+  vkFormat: number;
+  width: number;
+  height: number;
+  depth?: number;
+  layerCount?: number;
+  faceCount?: number;
+  scheme?: number;
+  levels: readonly Ktx2Level[];
+}
+
+function buildKtx2(opts: Ktx2Options): Uint8Array {
+  const { vkFormat, width, height, depth = 0, layerCount = 0, faceCount = 1, scheme = 0, levels } = opts;
+  const dataStart = 80 + levels.length * 24;
+  const total = levels.reduce((max, l) => Math.max(max, l.byteOffset + l.byteLength), dataStart);
+  const bytes = new Uint8Array(total);
+  const dv = new DataView(bytes.buffer);
+  bytes.set(ktx2Magic, 0);
+  dv.setUint32(12, vkFormat, true);
+  dv.setUint32(16, 4, true); // typeSize
+  dv.setUint32(20, width, true);
+  dv.setUint32(24, height, true);
+  dv.setUint32(28, depth, true);
+  dv.setUint32(32, layerCount, true);
+  dv.setUint32(36, faceCount, true);
+  dv.setUint32(40, levels.length, true);
+  dv.setUint32(44, scheme, true);
+  let off = 80;
+  for (const level of levels) {
+    dv.setBigUint64(off, BigInt(level.byteOffset), true);
+    dv.setBigUint64(off + 8, BigInt(level.byteLength), true);
+    dv.setBigUint64(off + 16, BigInt(level.byteLength), true);
+    off += 24;
+  }
+  return bytes;
+}
+
+describe('parseKtx2', () => {
+  it('parses a single-mip uncompressed 2D texture', () => {
+    const container = parseKtx2(
+      buildKtx2({ vkFormat: 37, width: 4, height: 4, levels: [{ byteLength: 64, byteOffset: 104 }] }),
+    );
+    expect(container).not.toBeNull();
+    expect(container!.format).toBe('rgba8unorm');
+    expect(container!.width).toBe(4);
+    expect(container!.height).toBe(4);
+    expect(container!.depth).toBe(1);
+    expect(container!.mipLevels).toBe(1);
+    expect(container!.layers).toBe(1);
+    expect(container!.faces).toBe(1);
+    expect(container!.supercompression).toBe('None');
+    expect(container!.levels).toEqual([{ byteLength: 64, byteOffset: 104, height: 4, width: 4 }]);
+  });
+
+  it('splits an uncompressed cubemap level into six per-face sub-images', () => {
+    const container = parseKtx2(
+      buildKtx2({ vkFormat: 37, width: 4, height: 4, faceCount: 6, levels: [{ byteLength: 384, byteOffset: 104 }] }),
+    );
+    expect(container).not.toBeNull();
+    expect(container!.faces).toBe(6);
+    expect(container!.levels).toHaveLength(6);
+    expect(container!.levels.map((l) => l.byteLength)).toEqual([64, 64, 64, 64, 64, 64]);
+    expect(container!.levels.map((l) => l.byteOffset)).toEqual([104, 168, 232, 296, 360, 424]);
+  });
+
+  it('reports each mip of a mip chain from the level index', () => {
+    const container = parseKtx2(
+      buildKtx2({
+        vkFormat: 37,
+        width: 8,
+        height: 8,
+        levels: [
+          { byteLength: 256, byteOffset: 176 },
+          { byteLength: 64, byteOffset: 432 },
+          { byteLength: 16, byteOffset: 496 },
+          { byteLength: 4, byteOffset: 512 },
+        ],
+      }),
+    );
+    expect(container).not.toBeNull();
+    expect(container!.mipLevels).toBe(4);
+    expect(container!.levels.map((l) => l.width)).toEqual([8, 4, 2, 1]);
+    expect(container!.levels.map((l) => l.byteOffset)).toEqual([176, 432, 496, 512]);
+  });
+
+  it('reports a BasisLZ-supercompressed level as one compressed blob (etc1s)', () => {
+    const container = parseKtx2(
+      buildKtx2({ vkFormat: 0, width: 4, height: 4, scheme: 1, levels: [{ byteLength: 48, byteOffset: 104 }] }),
+    );
+    expect(container).not.toBeNull();
+    expect(container!.format).toBe('etc1s');
+    expect(container!.supercompression).toBe('BasisLZ');
+    expect(container!.levels).toHaveLength(1);
+    expect(container!.levels[0].byteLength).toBe(48);
+  });
+
+  it('maps an undefined vkFormat with no supercompression to uastc', () => {
+    const container = parseKtx2(
+      buildKtx2({ vkFormat: 0, width: 4, height: 4, scheme: 0, levels: [{ byteLength: 64, byteOffset: 104 }] }),
+    );
+    expect(container!.format).toBe('uastc');
+  });
+
+  it('returns null for a non-KTX2 buffer', () => {
+    expect(parseKtx2(new Uint8Array([0x44, 0x44, 0x53, 0x20]))).toBeNull();
+  });
+
+  it('returns null for an unmapped vkFormat', () => {
+    expect(
+      parseKtx2(buildKtx2({ vkFormat: 9999, width: 4, height: 4, levels: [{ byteLength: 64, byteOffset: 104 }] })),
+    ).toBeNull();
+  });
+
+  it('returns null when a level range runs past the buffer', () => {
+    const bytes = buildKtx2({ vkFormat: 37, width: 4, height: 4, levels: [{ byteLength: 64, byteOffset: 104 }] });
+    const dv = new DataView(bytes.buffer);
+    dv.setBigUint64(80 + 8, BigInt(1_000_000), true); // corrupt the level byteLength
+    expect(parseKtx2(bytes)).toBeNull();
+  });
+
+  it('returns null for a truncated header', () => {
+    expect(parseKtx2(new Uint8Array([...ktx2Magic, 0, 0, 0, 0]))).toBeNull();
+  });
+});