simvx.graphics.assets.dds_loader

Pure-Python DDS (DirectDraw Surface) parser for block-compressed textures.

Parses a .dds container into a :class:DDSTexture: the target VkFormat int, dimensions, the format’s block size (8 or 16 bytes), and the list of tightly-packed mip-level block bytes ready for Engine.upload_texture_blocks.

No new dependency: just struct + numpy (numpy only for the byte slicing helper). Vulkan is referenced for its VK_FORMAT_BC* integer constants at call time only, never at import, so this module imports cleanly with no device.

Scope (foundation phase): 2D single-array BC1-BC7. Cubemaps, texture arrays, and non-BC formats raise ValueError (the caller converts that to a one-time WARNING + a -1 “couldn’t resolve” sentinel).

Module Contents

Classes

DDSTexture

A parsed block-compressed DDS texture.

Functions

vk_format_block_size	Return the 4x4 block size (8 or 16 bytes) for a BC/ASTC-4x4/ETC2 VkFormat int.
load_dds	Parse a DDS file path or raw bytes into a :class:DDSTexture.

Data

__all__
log

API

simvx.graphics.assets.dds_loader.__all__

[‘DDSTexture’, ‘load_dds’, ‘vk_format_block_size’]

simvx.graphics.assets.dds_loader.log

‘getLogger(…)’

class simvx.graphics.assets.dds_loader.DDSTexture

A parsed block-compressed DDS texture.

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 first.

vk_format: int

None

width: int

None

height: int

None

block_size: int

None

mips: list[bytes]

None

simvx.graphics.assets.dds_loader.vk_format_block_size(vk_format: int) → int

Return the 4x4 block size (8 or 16 bytes) for a BC/ASTC-4x4/ETC2 VkFormat int.

Shared by both the DDS reader (which maps a name first) and the KTX2 reader (which carries the VkFormat int directly). Covers the BC family plus ASTC-4x4 and ETC2-RGBA (all 4-texel footprint @ 16 B/block). Raises ValueError for any other int (e.g. non-4x4 ASTC, whose larger footprint would break the 4-texel block-row math) so the caller degrades to warn + -1.

simvx.graphics.assets.dds_loader.load_dds(source: str | pathlib.Path | bytes) → simvx.graphics.assets.dds_loader.DDSTexture

Parse a DDS file path or raw bytes into a :class:DDSTexture.

Raises ValueError for a bad magic, an unknown FourCC/DXGI format, or an unsupported container shape (cubemap / volume / array). The caller converts that to a one-time WARNING + -1 sentinel.