simvx.graphics.cook

simvx cook: offline texture cooking for shipped assets.

Pre-bakes textures so the runtime does no per-load transcode work: a UASTC .ktx2 interchange texture (the recommended authoring format, see docs/graphics/compressed_textures.md) is transcoded once, offline, to an explicit GPU block format (BC7 by default; ASTC-4x4 / ETC2 via --target) with its full mip chain baked into the cooked container. Cooked files load through the ordinary explicit-format KTX2 path with no native transcoder present, which also makes them safe to ship to installs that never ran simvx build-textures.

Inputs are individual texture files or a .gltf scene, in which case every externally referenced buffer and image is carried across (relative layout preserved) and each UASTC .ktx2 among them is cooked in place of a copy. Everything else (raw PNG/JPG, explicit-BC KTX2/DDS, .bin buffers) is copied unchanged: raw colour maps get their mip chains from the runtime mip generator (RM-A12a), and explicit-format containers are already cooked.

Degrades gracefully, mirroring simvx build-textures: when the vendored basis_universal transcoder is absent (no C++ compiler, or opted out via SIMVX_SKIP_TEXTURE_BUILD) the source file passes through unchanged and the report says so; the cook never fails the batch over a missing native extension.

Pure tooling: nothing in the engine imports this module.

Module Contents

Classes

CookReport

One input file’s cook outcome.

Functions

full_mip_count	Number of levels in a full mip chain down to 1x1 (RM-A12a semantics).
write_ktx2	Serialize explicit-format block-compressed mips into a KTX2 container.
cook_ktx2_bytes	Cook one KTX2 file’s bytes; returns (out_bytes, action, detail).
cook_file	Cook one input (texture file or .gltf scene) into out_dir.

Data

log
__all__

API

simvx.graphics.cook.log

‘getLogger(…)’

simvx.graphics.cook.__all__

[‘CookError’, ‘CookReport’, ‘cook_file’, ‘cook_ktx2_bytes’, ‘full_mip_count’, ‘write_ktx2’]

exception simvx.graphics.cook.CookError

Bases: RuntimeError

A cook cannot proceed (bad input path, output would clobber a source).

Initialization

Initialize self. See help(type(self)) for accurate signature.

class __cause__

class __context__

__delattr__()

__dir__()

__eq__()

__format__()

__ge__()

__getattribute__()

__getstate__()

__gt__()

__hash__()

__le__()

__lt__()

__ne__()

__new__()

__reduce__()

__reduce_ex__()

__repr__()

__setattr__()

__setstate__()

__sizeof__()

__str__()

__subclasshook__()

class __suppress_context__

class __traceback__

add_note()

class args

with_traceback()

class simvx.graphics.cook.CookReport

One input file’s cook outcome.

Attributes: source: input file path. output: written file path (equal content to source for copies). action: "cooked" (transcoded + mips baked), "copied" (already cooked / not cookable, content unchanged), "pass-through" (cookable but degraded, content unchanged), or "missing". detail: human-readable reason / summary for the action.

source: pathlib.Path

None

output: pathlib.Path | None

None

action: str

None

detail: str

None

simvx.graphics.cook.full_mip_count(width: int, height: int) → int

Number of levels in a full mip chain down to 1x1 (RM-A12a semantics).

simvx.graphics.cook.write_ktx2(vk_format: int, width: int, height: int, mips: list[bytes], *, block_size: int = 16) → bytes

Serialize explicit-format block-compressed mips into a KTX2 container.

mips is level 0 (largest) first, matching :class:KTX2Texture. Writes an uncompressed (supercompressionScheme = 0) container in the engine reader’s layout (see the module-level layout note): level payloads stored smallest level first, each aligned to block_size, with a well-formed basic DFD. Round-trips through assets.ktx2_loader.load_ktx2 byte-for-byte on every level.

simvx.graphics.cook.cook_ktx2_bytes(data: bytes, *, target: str = 'bc7') → tuple[bytes, str, str]

Cook one KTX2 file’s bytes; returns (out_bytes, action, detail).

A UASTC (vkFormat 0) container is transcoded level-by-level to target ("bc7" / "astc4x4" / "etc2") via the vendored basis_universal transcoder and rewritten as an explicit-format KTX2 with the source’s mip chain baked in. An explicit-format container is already cooked and copies unchanged. Any degradation (transcoder absent or missing the target, unsupported flavour such as ETC1S) passes the input through unchanged with the reason in detail: cooking never raises over a bad texture.

simvx.graphics.cook.cook_file(src: pathlib.Path, out_dir: pathlib.Path, *, target: str = 'bc7', transcode: bool = True) → list[simvx.graphics.cook.CookReport]

Cook one input (texture file or .gltf scene) into out_dir.

A .gltf input is copied along with every externally referenced buffer and image (relative layout preserved, so the copied scene stays loadable), cooking each UASTC .ktx2 reference along the way. A .glb copies unchanged (its images live inside the binary chunk). Any other file cooks or copies per :func:_cook_one. Raises :class:CookError only for hard misuse (missing input scene, output clobbering a source).