simvx.graphics._native.basis_transcoder

Python wrapper around the compiled _simvx_basis_transcoder cffi extension.

Exposes a tiny Pythonic surface over the vendored basis_universal transcoder:

func:

transcode_uastc_to_bc7 / :func:transcode_uastc_to_astc4x4 /

func:

transcode_uastc_to_etc2 turn one UASTC level’s packed 16-byte blocks into BC7 / ASTC-4x4 / ETC2-RGBA blocks (all 16 B/block). Used by simvx.graphics.assets.ktx2_loader to load single-source UASTC KTX2 textures on the desktop, with TextureManager picking the target per device caps.

Build the extension once after install:

uv run python -m simvx.graphics._native.basis_transcoder_build

If the .so is missing, this module still imports cleanly (the ImportError is swallowed): callers check :func:is_available and fall through to a warn + -1 sentinel, never a crash. Mirrors simvx.core._native.miniaudio_engine.

Module Contents

Functions

is_available	True if the native extension was built, loaded, and ships the BC7 target.
astc_available	True if the extension shipped the UASTC->ASTC-4x4 target (BASISD_SUPPORT_ASTC).
etc2_available	True if the extension shipped the UASTC->ETC2-RGBA target (BASISD_SUPPORT_ETC2_EAC_A8).
refresh	Re-run the extension import, e.g. after a successful auto-build.
ensure_built	Attempt a one-shot build of the extension if it is not already available.
transcode_uastc_to_bc7	Transcode one UASTC level’s packed blocks to BC7 (16 B/block).
transcode_uastc_to_astc4x4	Transcode one UASTC level’s packed blocks to ASTC LDR 4x4 (16 B/block).
transcode_uastc_to_etc2	Transcode one UASTC level’s packed blocks to ETC2 RGBA (EAC_A8, 16 B/block).

Data

log
__all__

API

simvx.graphics._native.basis_transcoder.log

‘getLogger(…)’

simvx.graphics._native.basis_transcoder.__all__

[‘BasisTranscoderUnavailable’, ‘is_available’, ‘astc_available’, ‘etc2_available’, ‘refresh’, ‘trans…

exception simvx.graphics._native.basis_transcoder.BasisTranscoderUnavailable

Bases: RuntimeError

The compiled _simvx_basis_transcoder extension was not found.

Run uv run python -m simvx.graphics._native.basis_transcoder_build (or simvx build-textures) to compile it once, with a C++ compiler present.

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()

simvx.graphics._native.basis_transcoder.is_available() → bool

True if the native extension was built, loaded, and ships the BC7 target.

simvx.graphics._native.basis_transcoder.astc_available() → bool

True if the extension shipped the UASTC->ASTC-4x4 target (BASISD_SUPPORT_ASTC).

A BC7-only build (the stale define-set) returns False here, so callers can verify the full-matrix .so actually shipped rather than silently skipping.

simvx.graphics._native.basis_transcoder.etc2_available() → bool

True if the extension shipped the UASTC->ETC2-RGBA target (BASISD_SUPPORT_ETC2_EAC_A8).

simvx.graphics._native.basis_transcoder.refresh() → bool

Re-run the extension import, e.g. after a successful auto-build.

simvx.graphics._native.basis_transcoder.ensure_built() → bool

Attempt a one-shot build of the extension if it is not already available.

Honours SIMVX_SKIP_TEXTURE_BUILD: when set, the build is skipped and the current availability is returned unchanged. Any build failure (no compiler, missing cffi/setuptools, etc.) is swallowed: the extension simply stays unavailable and the caller degrades gracefully. Returns the post-attempt availability.

simvx.graphics._native.basis_transcoder.transcode_uastc_to_bc7(uastc_bytes: bytes, width: int, height: int) → bytes

Transcode one UASTC level’s packed blocks to BC7 (16 B/block).

uastc_bytes is the tightly-packed 16-byte UASTC blocks for a level of width x height texels. Returns num_blocks * 16 bytes of BC7.

simvx.graphics._native.basis_transcoder.transcode_uastc_to_astc4x4(uastc_bytes: bytes, width: int, height: int) → bytes

Transcode one UASTC level’s packed blocks to ASTC LDR 4x4 (16 B/block).

Requires the .so to have shipped the ASTC target (:func:astc_available).

simvx.graphics._native.basis_transcoder.transcode_uastc_to_etc2(uastc_bytes: bytes, width: int, height: int) → bytes

Transcode one UASTC level’s packed blocks to ETC2 RGBA (EAC_A8, 16 B/block).

Requires the .so to have shipped the ETC2 target (:func:etc2_available).