`simvx.graphics.assets.ktx2_loader`¶

Pure-Python KTX2 (Khronos Texture 2.0) parser for block-compressed textures.

Parses a .ktx2 container into a :class:KTX2Texture whose field set mirrors

class:: ~simvx.graphics.assets.dds_loader.DDSTexture exactly, so the texture manager treats both identically (sibling types, no shim, no unification).

KTX2 is the easy container: it stores the target VkFormat as an int in the header, so there is no DXGI translation table to maintain. Block sizing reuses

func:: ~simvx.graphics.assets.dds_loader.vk_format_block_size.

Scope: 2D single-array BC1-BC7 with supercompressionScheme of 0 (none) or 2 (Zstd). vkFormat == 0 with a UASTC LDR Data Format Descriptor is transcoded to a device-chosen block target (BC7 / ASTC-4x4 / ETC2) via the native basis_universal transcoder when available, then handed to the same compressed-upload path as explicit-BC textures. ETC1S / BasisLZ (scheme == 1) remains out of scope and raises a ValueError naming basis_universal. Cubemaps, arrays, 3D, and ZLIB supercompression also raise ValueError (the caller converts that to a one-time WARNING + a -1 “couldn’t resolve” sentinel).

Pure stdlib (struct + pathlib) plus a LAZY zstandard import inside the Zstd branch and a LAZY native-transcoder import inside the UASTC branch, so this module imports cleanly with neither the GPU, the optional zstandard package, nor the native transcoder extension present.

Module Contents¶

Classes¶

`KTX2Texture`	A parsed block-compressed KTX2 texture.
`UASTCSource`	Raw UASTC LDR 4x4 source levels, untranscoded.

Functions¶

`load_ktx2`	Parse a KTX2 file path or raw bytes into a :class:`KTX2Texture`.
`load_ktx2_uastc_source`	Parse a UASTC LDR KTX2 into raw (untranscoded) :class:`UASTCSource` levels.

Data¶

`__all__`
`log`
`KTX2_MAGIC`

API¶

simvx.graphics.assets.ktx2_loader.__all__¶: [‘KTX2Texture’, ‘KTX2_MAGIC’, ‘UASTCSource’, ‘load_ktx2’, ‘load_ktx2_uastc_source’]

simvx.graphics.assets.ktx2_loader.log¶: ‘getLogger(…)’

simvx.graphics.assets.ktx2_loader.KTX2_MAGIC¶: b’\xabKTX 20\xbb\r\n\x1a\n’

class simvx.graphics.assets.ktx2_loader.KTX2Texture[source]¶

A parsed block-compressed KTX2 texture.

Field set and order DELIBERATELY match

Class:: ~simvx.graphics.assets.dds_loader.DDSTexture so the texture manager can feed either to the same compressed-upload path.

Attributes: vk_format: VkFormat integer (a VK_FORMAT_BC* constant). width / height: top-level mip dimensions in texels. block_size: bytes per 4x4 block (8 for BC1/BC4, 16 otherwise). mips: tightly-packed block bytes per mip level, level 0 (largest) first.

vk_format: int¶: None

width: int¶: None

height: int¶: None

block_size: int¶: None

mips: list[bytes]¶: None

class simvx.graphics.assets.ktx2_loader.UASTCSource[source]¶

Raw UASTC LDR 4x4 source levels, untranscoded.

The web backend ships these bytes to the browser, where the basis_universal WebAssembly transcoder picks the GPU’s preferred block format (BC7 / ASTC / ETC2) per-device, or decodes to RGBA8 when no block family is present. The desktop loader transcodes UASTC->BC7 at parse time instead (one fixed target), which is why the web path needs the raw levels rather than KTX2Texture.

Attributes: width / height: top-level mip dimensions in texels. srgb: True when the DFD transfer function is sRGB (colour textures). mips: tightly-packed UASTC block bytes per mip level, level 0 first.

width: int¶: None

height: int¶: None

srgb: bool¶: None

mips: list[bytes]¶: None

simvx.graphics.assets.ktx2_loader.load_ktx2(source: str | pathlib.Path | bytes, *, target: str = 'bc7') → simvx.graphics.assets.ktx2_loader.KTX2Texture[source]¶

Parse a KTX2 file path or raw bytes into a :class:KTX2Texture.

target selects the UASTC transcode target for vkFormat == 0 files: "bc7" (default, preserves all existing callers byte-for-byte), "astc4x4", or "etc2". It is ignored for explicit-format (BC) KTX2s, which carry their own VkFormat. TextureManager picks target from the device’s compressed-texture caps; the loader stays device-agnostic.

Raises ValueError (never crashes) for: bad magic, truncation, a cubemap / array / 3D container, an explicit non-BC format, BasisLZ / ZLIB supercompression, or a missing zstandard package on a Zstd file. The caller converts that to a one-time WARNING + -1 sentinel.

simvx.graphics.assets.ktx2_loader.load_ktx2_uastc_source(source: str | pathlib.Path | bytes) → simvx.graphics.assets.ktx2_loader.UASTCSource[source]¶

Parse a UASTC LDR KTX2 into raw (untranscoded) :class:UASTCSource levels.

For the web backend, which ships UASTC to the browser instead of transcoding to a single fixed block format on the CPU. Raises ValueError (the same contract as :func:load_ktx2) for anything that is not a plain or Zstd-supercompressed UASTC LDR 4x4 texture: explicit-BC vkFormats, ETC1S / BasisLZ, cubemaps / arrays / 3D, ZLIB, or a missing zstandard package.

simvx.graphics.assets.ktx2_loader¶