Metadata-Version: 2.5
Name: SimVX-Textures-Basis
Version: 0.0.0.dev3104
Summary: Native texture transcoding for SimVX: basis_universal turns UASTC textures into GPU block formats.
Project-URL: Homepage, https://simvx.com
Project-URL: Documentation, https://simvx.com/docs/graphics/compressed_textures.html
Project-URL: Source, https://git.simvx.com/simvx/simvx
Project-URL: Issues, https://git.simvx.com/simvx/simvx/issues
Project-URL: Changelog, https://git.simvx.com/simvx/simvx/commits/branch/main
Author-email: SimVX <contact@simvx.com>
License-Expression: AGPL-3.0-or-later
License-File: LICENSE
License-File: NOTICE
License-File: THIRD_PARTY_LICENSES.md
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: C++
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.14
Requires-Dist: cffi>=1.17
Description-Content-Type: text/markdown

# SimVX Textures Basis

SimVX's native texture transcoder: [basis_universal](https://github.com/BinomialLLC/basis_universal)
turns UASTC `.ktx2` textures into the block format the GPU samples (BC7, ASTC 4x4 or ETC2). Most
users want `simvx`, which includes it where a wheel exists.

> **Pre-alpha.** SimVX publishes development releases only (`0.0.0.devN`) and is under active
> development; the API changes between builds. Once stable versions ship to PyPI, development
> builds continue on pypi.simvx.com.

## Install

```bash
pip install --pre simvx                    # the whole engine (recommended)
pip install --pre simvx-textures-basis     # the transcoder alone; it needs only cffi
```

Latest development build: add `--extra-index-url https://pypi.simvx.com/`.

## Use

Nothing to configure: `simvx-graphics` uses it to load a UASTC `.ktx2` texture, and `simvx cook`
uses it to transcode one ahead of shipping:

```bash
simvx cook hero.ktx2 -o cooked/
```

Without it loading a UASTC texture raises `ValueError` and `simvx cook`
copies the file unchanged. Textures already in an explicit block format load without it.

## Use it directly

The package needs nothing from the engine. Each function takes one mip level's packed UASTC
blocks (16 bytes per 4x4 block) with its size in texels, and returns the transcoded blocks:

```python
from simvx.textures.basis import is_available, transcode_uastc_to_bc7

uastc = bytes(16 * 4)  # one 8x8 level: four 4x4 blocks, here all zero
if is_available():
    bc7 = transcode_uastc_to_bc7(uastc, 8, 8)
```

`transcode_uastc_to_astc4x4` and `transcode_uastc_to_etc2` take the same arguments, behind
`astc_available()` and `etc2_available()`. A level of the wrong size raises `ValueError`.

Platforms: wheels for Linux x86_64 and aarch64, Windows x86_64, and macOS x86_64 and arm64; only
Linux x86_64 is tested. The library is loaded through cffi's ABI mode and the wheel is tagged
`py3-none-<platform>`, so one wheel per platform serves every CPython 3.14 build, free-threaded
included.

[Documentation](https://simvx.com/docs/graphics/compressed_textures.html) ·
[Source](https://git.simvx.com/simvx/simvx/src/branch/main/packages/textures-basis) ·
Licence: AGPL-3.0-or-later with [Additional Terms](https://git.simvx.com/simvx/simvx/src/branch/main/LICENSE-ADDENDUM.md),
including the Game-Distribution Exception. Vendored: basis_universal (Apache-2.0).
