opengl-basisu 0.1.0a1__tar.gz

opengl_basisu-0.1.0a1/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 0.1.0a1
+
+- `open()` reads a KTX 2 file with an ETC1S or UASTC payload, or a `.basis` file, from a path or bytes.
+- `Texture.transcode()` writes BC1, BC3, BC4, BC5, BC7, ETC1, ETC2, ASTC 4x4, RGBA8 or RGB565 as a NumPy array.
+- `Target.info` carries each format's GL enums; `choose_target()` picks one from a context's extensions and version.
+- Transcoder: basis_universal v2_50 (commit 9bebe167).

opengl_basisu-0.1.0a1/LICENSE

@@ -0,0 +1,60 @@
+MIT License
+
+Python wrapper Copyright (c) 2026 Mike C. Fletcher and Contributors
+
+All rights reserved except as granted under the [Apache 2.0 license](https://github.com/BinomialLLC/basis_universal/blob/master/LICENSE).
+
+NOTE ON AUTHORSHIP
+
+This wrapper was generated by a large language model under human direction.
+Jurisdictions differ on whether such material attracts copyright at all: some
+require human authorship for a work to be protected, some extend protection to
+computer-generated works, and in others the question is unsettled. Where no
+copyright subsists in part or all of this software, the permission granted
+above has nothing to operate on there and that material may be used freely;
+where copyright does subsist, the terms above govern it. The disclaimer of
+warranty and limitation of liability apply in either case.
+
+Basis Universal™ Supercompressed GPU Texture Compression Library
+
+Copyright © 2016–2026 Binomial LLC. 
+All rights reserved except as granted under the [Apache 2.0 license](https://github.com/BinomialLLC/basis_universal/blob/master/LICENSE).
+"Basis Universal" is a trademark of Binomial LLC.
+
+The documents in the Basis Universal wiki, and the Basis Universal library, example, and tool source code, fall under the Apache 2.0 license, unless otherwise explicitly indicated. 
+
+Redistributions or derivative works must include a readable copy of the attribution notices from this NOTICE file (see Apache License 2.0 §4(d)).
+
+If you modify the Basis Universal source code, specifications, or wiki documents and redistribute the files, you must cause any modified files to carry prominent notices stating that you changed the files (see Apache 2.0 §4(b)).
+
+**This software, documentation and specifications are provided "as is", without warranty of any kind (see Apache 2.0 §§7–8).**
+
+For Zstandard software
+
+Copyright (c) 2016-present, Facebook, Inc. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+ * Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+ * Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+ * Neither the name Facebook nor the names of its contributors may be used to
+   endorse or promote products derived from this software without specific
+   prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+

opengl_basisu-0.1.0a1/MANIFEST.in

@@ -0,0 +1,11 @@
+# The vendored transcoder is compiled by every source build, so the sdist
+# carries all of it, with its licence and notice files.
+graft vendor
+include NOTICE
+include tox.ini
+include CHANGELOG.md
+recursive-include docs *.md
+recursive-include tests *.py
+recursive-include tests/fixtures *.ktx2 *.basis *.json
+recursive-include tools *.py
+include src/opengl_basisu/_shim.hpp

opengl_basisu-0.1.0a1/NOTICE

@@ -0,0 +1,27 @@
+opengl_basisu
+Copyright (c) 2026 Mike C. Fletcher and Contributors
+Licensed under the MIT License; see LICENSE.
+
+The compiled extension contains third-party code, copied unmodified into
+vendor/basis_universal from basis_universal, tag v2_50
+(commit 9bebe16726b3a61c8c213eeee3b7cffb462ef34e,
+https://github.com/BinomialLLC/basis_universal):
+
+* The Basis Universal transcoder (vendor/basis_universal/transcoder).
+  Licensed under the Apache License, Version 2.0; see
+  vendor/basis_universal/LICENSE. Its attribution notice, reproduced as
+  Apache 2.0 section 4(d) requires:
+
+    Basis Universal(TM) Supercompressed GPU Texture Compression Library
+    Copyright (c) 2016-2026 Binomial LLC.
+    All rights reserved except as granted under the Apache 2.0 license.
+    "Basis Universal" is a trademark of Binomial LLC.
+
+  The full notice is vendor/basis_universal/NOTICE.
+
+* The Zstandard single-file decoder (vendor/basis_universal/zstd).
+  Copyright (c) Meta Platforms, Inc. and affiliates. Zstandard is offered
+  under a choice of the BSD license or the GPLv2; this package takes it under
+  the BSD license in vendor/basis_universal/zstd/LICENSE.
+
+No basis_universal encoder code is included.

opengl_basisu-0.1.0a1/PKG-INFO

@@ -0,0 +1,182 @@
+Metadata-Version: 2.4
+Name: opengl_basisu
+Version: 0.1.0a1
+Summary: Basis Universal KTX 2 and .basis transcoding to GPU texture formats, as NumPy arrays
+Author-email: "Mike C. Fletcher" <mcfletch@vrplumber.com>
+License-Expression: MIT AND Apache-2.0 AND BSD-3-Clause
+Project-URL: Homepage, https://github.com/mcfletch/opengl_basisu
+Project-URL: Repository, https://github.com/mcfletch/opengl_basisu
+Keywords: basis,basisu,ktx2,KHR_texture_basisu,etc1s,uastc,texture,compression,glTF,numpy,BC7,ASTC
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: C++
+Classifier: Topic :: Multimedia :: Graphics :: 3D Rendering
+Classifier: Topic :: Multimedia :: Graphics :: Graphics Conversion
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+License-File: vendor/basis_universal/LICENSE
+License-File: vendor/basis_universal/NOTICE
+License-File: vendor/basis_universal/zstd/LICENSE
+Requires-Dist: numpy>=1.24
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Provides-Extra: dev
+Requires-Dist: opengl_basisu[test]; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: tox>=4.0; extra == "dev"
+Requires-Dist: Cython>=3.0; extra == "dev"
+Dynamic: license-file
+
+# opengl_basisu: Basis Universal transcoding as NumPy arrays
+
+Transcode a KTX 2 file with a Basis Universal payload (ETC1S or UASTC, the two
+codecs glTF's `KHR_texture_basisu` allows), or a `.basis` file, to a GPU
+texture format: BC1, BC3, BC4, BC5, BC7, ETC1, ETC2 or ASTC 4x4 blocks, or
+RGBA8 or RGB565 pixels. Input is a path or bytes; output is a NumPy array with
+the OpenGL enums to upload it, as integers. Nothing here imports OpenGL.
+
+```python
+import opengl_basisu
+
+texture = opengl_basisu.open('albedo.ktx2')
+texture.width, texture.height, texture.levels   # 1024, 1024, 11
+texture.codec, texture.srgb, texture.has_alpha  # Codec.ETC1S, True, False
+
+target = opengl_basisu.choose_target(
+    extensions,                  # the names the GL context reports
+    codec=texture.codec,
+    has_alpha=texture.has_alpha,
+    srgb=texture.srgb,
+    version=(4, 6),
+)
+for image in texture.transcode_levels(target):
+    if image.compressed:
+        glCompressedTexImage2D(
+            GL_TEXTURE_2D, image.level, image.gl_internal_format,
+            image.width, image.height, 0, image.nbytes, image.data,
+        )
+    else:
+        glTexImage2D(
+            GL_TEXTURE_2D, image.level, image.gl_internal_format,
+            image.width, image.height, 0, image.gl_format, image.gl_type, image.data,
+        )
+```
+
+NumPy is the only runtime dependency.
+
+## Install
+
+```
+pip install opengl_basisu
+```
+
+Wheels are published for CPython 3.10 to 3.14 on Linux, Windows and macOS
+(arm64 and x86_64). A source build needs Cython and a C++17 compiler.
+
+## What a texture reports
+
+| Attribute | Meaning |
+|---|---|
+| `container` | `'ktx2'` or `'basis'` |
+| `width`, `height` | level 0, in pixels |
+| `levels` | mip levels, at least 1 |
+| `faces` | 1, or 6 for a cube map |
+| `layers`, `is_array` | array layers (at least 1), and whether the file declares an array |
+| `codec` | a `Codec`: `ETC1S`, `UASTC_LDR_4x4`, or a newer basis_universal codec |
+| `has_alpha` | the file stores alpha |
+| `srgb` | the colour space is sRGB rather than linear |
+| `is_video`, `y_flipped` | a video's frames are its layers; `y_flipped` is a `.basis` flag |
+
+`texture.transcode(target, level=0, face=0, layer=0)` returns an `Image`.
+`transcode_levels(target, face, layer)` returns the mip chain, largest first,
+and `images(target)` yields every image in the file.
+
+## Targets
+
+| `Target` | Array | GL internal format (linear / sRGB) | Provided by |
+|---|---|---|---|
+| `BC1` | (rows, cols, 8) | `0x83F0` / `0x8C4C` | `GL_EXT_texture_compression_s3tc`; sRGB also `GL_EXT_texture_sRGB` |
+| `BC3` | (rows, cols, 16) | `0x83F3` / `0x8C4F` | as BC1 |
+| `BC4` | (rows, cols, 8) | `0x8DBB` / none | GL 3.0, `GL_ARB_texture_compression_rgtc` |
+| `BC5` | (rows, cols, 16) | `0x8DBD` / none | GL 3.0, `GL_ARB_texture_compression_rgtc` |
+| `BC7` | (rows, cols, 16) | `0x8E8C` / `0x8E8D` | GL 4.2, `GL_ARB_texture_compression_bptc`, `GL_EXT_texture_compression_bptc` |
+| `ETC1` | (rows, cols, 8) | `0x9274` / `0x9275` (ETC2 RGB8) | GL 4.3, GLES 3.0, `GL_ARB_ES3_compatibility` |
+| `ETC2` | (rows, cols, 16) | `0x9278` / `0x9279` | GL 4.3, GLES 3.0, `GL_ARB_ES3_compatibility` |
+| `ASTC_4x4` | (rows, cols, 16) | `0x93B0` / `0x93D0` | GLES 3.2, `GL_KHR_texture_compression_astc_ldr` |
+| `RGBA8` | (height, width, 4) uint8 | `GL_RGBA8` / `GL_SRGB8_ALPHA8` | always |
+| `RGB565` | (height, width) uint16 | `GL_RGB565` / none | GL 4.1, GLES 2.0 |
+
+Block arrays are uint8, one 4x4 block per `(row, column)`, rows of blocks top
+to bottom; `rows` and `cols` round the pixel size up to whole blocks.
+`Target.X.info` is the `TargetFormat` with these values, and
+`TargetFormat.available(extensions, version, es, srgb)` answers whether a
+context provides it.
+
+`choose_target()` takes the extension names, version and `es` flag of a
+context, and the texture's codec, alpha and colour space. It walks
+`preferences(codec, es, channels)` and returns the first target the context
+provides, or `RGBA8`. On desktop GL the BC formats come before ETC because
+desktop drivers commonly decode ETC2 to RGBA8 at upload. UASTC prefers ASTC
+4x4, which it transcodes to without re-encoding; ETC1S on GLES prefers ETC1
+for the same reason. `channels='r'` or `'rg'` puts BC4 or BC5 first, for
+single and two-channel data.
+
+## Errors
+
+- `BasisuError` (a `ValueError`): truncated or corrupt data, or bytes that are
+  neither KTX 2 nor `.basis`.
+- `UnsupportedError` (a `BasisuError`): a KTX 2 file whose payload is not a
+  Basis Universal codec (an uncompressed or a plain BCn KTX 2, for example), or
+  a high dynamic range codec asked for an 8-bit target.
+- `ValueError`: an unknown target name. `IndexError`: a level, face or layer
+  the texture does not have.
+
+The test suite truncates every fixture at every length and transcodes 5,000
+randomly corrupted copies of each; corrupt input raises. `docs/API.md` has the
+AddressSanitizer run of the same tests.
+
+## Limits
+
+- High dynamic range codecs (UASTC HDR 4x4, ASTC HDR 6x6) open and report
+  their header, and have no target here.
+- The layers of an ETC1S video are P-frames: transcode them in order from
+  layer 0.
+- One `Texture` transcodes one image at a time (a lock serialises threads);
+  separate textures transcode in parallel with the GIL released.
+- The transcoder addresses files of up to 4 GiB.
+
+## The transcoder
+
+The compiled extension is Binomial's
+[basis_universal](https://github.com/BinomialLLC/basis_universal) transcoder,
+tag `v2_50` (commit `9bebe167`), with the Zstandard decoder it bundles. Both
+are copied unmodified into `vendor/basis_universal`; `vendor/basis_universal/VERSION`
+records the tag and commit, and `tools/vendor_basisu.py` repeats the copy for
+another tag. No encoder code is included.
+
+## Test fixtures
+
+`tests/fixtures` holds six files of under 600 bytes each, written by the
+basis_universal `v2_50` encoder from flat-colour images by
+`tools/make_fixtures.py`; its docstring has the build and the encoder flags
+for each file. `tests/fixtures/colours.json` lists the colours the tests
+compare against.
+
+## Licence
+
+This package is Apache License 2.0. The extension also contains the
+basis_universal transcoder under the Apache License 2.0
+(`vendor/basis_universal/LICENSE`, `vendor/basis_universal/NOTICE`) and the
+Zstandard decoder under the BSD licence (`vendor/basis_universal/zstd/LICENSE`).
+`NOTICE` lists both.

opengl_basisu-0.1.0a1/README.md

@@ -0,0 +1,142 @@
+# opengl_basisu: Basis Universal transcoding as NumPy arrays
+
+Transcode a KTX 2 file with a Basis Universal payload (ETC1S or UASTC, the two
+codecs glTF's `KHR_texture_basisu` allows), or a `.basis` file, to a GPU
+texture format: BC1, BC3, BC4, BC5, BC7, ETC1, ETC2 or ASTC 4x4 blocks, or
+RGBA8 or RGB565 pixels. Input is a path or bytes; output is a NumPy array with
+the OpenGL enums to upload it, as integers. Nothing here imports OpenGL.
+
+```python
+import opengl_basisu
+
+texture = opengl_basisu.open('albedo.ktx2')
+texture.width, texture.height, texture.levels   # 1024, 1024, 11
+texture.codec, texture.srgb, texture.has_alpha  # Codec.ETC1S, True, False
+
+target = opengl_basisu.choose_target(
+    extensions,                  # the names the GL context reports
+    codec=texture.codec,
+    has_alpha=texture.has_alpha,
+    srgb=texture.srgb,
+    version=(4, 6),
+)
+for image in texture.transcode_levels(target):
+    if image.compressed:
+        glCompressedTexImage2D(
+            GL_TEXTURE_2D, image.level, image.gl_internal_format,
+            image.width, image.height, 0, image.nbytes, image.data,
+        )
+    else:
+        glTexImage2D(
+            GL_TEXTURE_2D, image.level, image.gl_internal_format,
+            image.width, image.height, 0, image.gl_format, image.gl_type, image.data,
+        )
+```
+
+NumPy is the only runtime dependency.
+
+## Install
+
+```
+pip install opengl_basisu
+```
+
+Wheels are published for CPython 3.10 to 3.14 on Linux, Windows and macOS
+(arm64 and x86_64). A source build needs Cython and a C++17 compiler.
+
+## What a texture reports
+
+| Attribute | Meaning |
+|---|---|
+| `container` | `'ktx2'` or `'basis'` |
+| `width`, `height` | level 0, in pixels |
+| `levels` | mip levels, at least 1 |
+| `faces` | 1, or 6 for a cube map |
+| `layers`, `is_array` | array layers (at least 1), and whether the file declares an array |
+| `codec` | a `Codec`: `ETC1S`, `UASTC_LDR_4x4`, or a newer basis_universal codec |
+| `has_alpha` | the file stores alpha |
+| `srgb` | the colour space is sRGB rather than linear |
+| `is_video`, `y_flipped` | a video's frames are its layers; `y_flipped` is a `.basis` flag |
+
+`texture.transcode(target, level=0, face=0, layer=0)` returns an `Image`.
+`transcode_levels(target, face, layer)` returns the mip chain, largest first,
+and `images(target)` yields every image in the file.
+
+## Targets
+
+| `Target` | Array | GL internal format (linear / sRGB) | Provided by |
+|---|---|---|---|
+| `BC1` | (rows, cols, 8) | `0x83F0` / `0x8C4C` | `GL_EXT_texture_compression_s3tc`; sRGB also `GL_EXT_texture_sRGB` |
+| `BC3` | (rows, cols, 16) | `0x83F3` / `0x8C4F` | as BC1 |
+| `BC4` | (rows, cols, 8) | `0x8DBB` / none | GL 3.0, `GL_ARB_texture_compression_rgtc` |
+| `BC5` | (rows, cols, 16) | `0x8DBD` / none | GL 3.0, `GL_ARB_texture_compression_rgtc` |
+| `BC7` | (rows, cols, 16) | `0x8E8C` / `0x8E8D` | GL 4.2, `GL_ARB_texture_compression_bptc`, `GL_EXT_texture_compression_bptc` |
+| `ETC1` | (rows, cols, 8) | `0x9274` / `0x9275` (ETC2 RGB8) | GL 4.3, GLES 3.0, `GL_ARB_ES3_compatibility` |
+| `ETC2` | (rows, cols, 16) | `0x9278` / `0x9279` | GL 4.3, GLES 3.0, `GL_ARB_ES3_compatibility` |
+| `ASTC_4x4` | (rows, cols, 16) | `0x93B0` / `0x93D0` | GLES 3.2, `GL_KHR_texture_compression_astc_ldr` |
+| `RGBA8` | (height, width, 4) uint8 | `GL_RGBA8` / `GL_SRGB8_ALPHA8` | always |
+| `RGB565` | (height, width) uint16 | `GL_RGB565` / none | GL 4.1, GLES 2.0 |
+
+Block arrays are uint8, one 4x4 block per `(row, column)`, rows of blocks top
+to bottom; `rows` and `cols` round the pixel size up to whole blocks.
+`Target.X.info` is the `TargetFormat` with these values, and
+`TargetFormat.available(extensions, version, es, srgb)` answers whether a
+context provides it.
+
+`choose_target()` takes the extension names, version and `es` flag of a
+context, and the texture's codec, alpha and colour space. It walks
+`preferences(codec, es, channels)` and returns the first target the context
+provides, or `RGBA8`. On desktop GL the BC formats come before ETC because
+desktop drivers commonly decode ETC2 to RGBA8 at upload. UASTC prefers ASTC
+4x4, which it transcodes to without re-encoding; ETC1S on GLES prefers ETC1
+for the same reason. `channels='r'` or `'rg'` puts BC4 or BC5 first, for
+single and two-channel data.
+
+## Errors
+
+- `BasisuError` (a `ValueError`): truncated or corrupt data, or bytes that are
+  neither KTX 2 nor `.basis`.
+- `UnsupportedError` (a `BasisuError`): a KTX 2 file whose payload is not a
+  Basis Universal codec (an uncompressed or a plain BCn KTX 2, for example), or
+  a high dynamic range codec asked for an 8-bit target.
+- `ValueError`: an unknown target name. `IndexError`: a level, face or layer
+  the texture does not have.
+
+The test suite truncates every fixture at every length and transcodes 5,000
+randomly corrupted copies of each; corrupt input raises. `docs/API.md` has the
+AddressSanitizer run of the same tests.
+
+## Limits
+
+- High dynamic range codecs (UASTC HDR 4x4, ASTC HDR 6x6) open and report
+  their header, and have no target here.
+- The layers of an ETC1S video are P-frames: transcode them in order from
+  layer 0.
+- One `Texture` transcodes one image at a time (a lock serialises threads);
+  separate textures transcode in parallel with the GIL released.
+- The transcoder addresses files of up to 4 GiB.
+
+## The transcoder
+
+The compiled extension is Binomial's
+[basis_universal](https://github.com/BinomialLLC/basis_universal) transcoder,
+tag `v2_50` (commit `9bebe167`), with the Zstandard decoder it bundles. Both
+are copied unmodified into `vendor/basis_universal`; `vendor/basis_universal/VERSION`
+records the tag and commit, and `tools/vendor_basisu.py` repeats the copy for
+another tag. No encoder code is included.
+
+## Test fixtures
+
+`tests/fixtures` holds six files of under 600 bytes each, written by the
+basis_universal `v2_50` encoder from flat-colour images by
+`tools/make_fixtures.py`; its docstring has the build and the encoder flags
+for each file. `tests/fixtures/colours.json` lists the colours the tests
+compare against.
+
+## Licence
+
+This package is Apache License 2.0. The extension also contains the
+basis_universal transcoder under the Apache License 2.0
+(`vendor/basis_universal/LICENSE`, `vendor/basis_universal/NOTICE`) and the
+Zstandard decoder under the BSD licence (`vendor/basis_universal/zstd/LICENSE`).
+`NOTICE` lists both.

opengl_basisu-0.1.0a1/docs/API.md

@@ -0,0 +1,101 @@
+# opengl_basisu API
+
+Everything below is importable from `opengl_basisu`.
+
+## Reading a file
+
+`open(source) -> Texture`
+: `source` is a path (`str` or `os.PathLike`) or the file's bytes (`bytes`,
+  `bytearray`, `memoryview`; the data is copied). Raises `BasisuError` for data
+  that is not a KTX 2 or `.basis` file the transcoder accepts, and
+  `UnsupportedError` for a KTX 2 file whose `vkFormat` is set and whose payload
+  the transcoder does not read.
+
+`container_of(data) -> 'ktx2' | 'basis' | None`
+: The container named by the first 12 bytes, without parsing the rest.
+
+`Texture`
+: `container`, `width`, `height`, `levels`, `faces`, `layers`, `is_array`,
+  `codec`, `has_alpha`, `srgb`, `is_video`, `y_flipped`, as in the README.
+
+  `level_size(level=0) -> (width, height)` in pixels.
+
+  `supports(target) -> bool`: whether the codec transcodes to `target`.
+
+  `transcode(target, level=0, face=0, layer=0) -> Image`. `target` is a
+  `Target` or its value (`'bc7'`). Raises `IndexError` for an index out of
+  range, `ValueError` for an unknown target name, `UnsupportedError` for a
+  codec and target the transcoder does not pair (any HDR codec with any target
+  here), and `BasisuError` when the transcoder rejects the image data.
+
+  `transcode_levels(target, face=0, layer=0) -> list[Image]`, largest first.
+
+  `images(target) -> Iterator[Image]`, by layer, then face, then level.
+
+`Image`
+: A frozen dataclass: `target`, `width`, `height` (pixels), `level`, `face`,
+  `layer`, `srgb` and `data` (a NumPy array). Properties: `compressed`,
+  `gl_internal_format` (the sRGB enum when `srgb` and the target has one),
+  `gl_format` and `gl_type` (uncompressed targets only, else `None`) and
+  `nbytes` (the `imageSize` argument of `glCompressedTexImage2D`).
+
+## Choosing a target
+
+`Target`
+: `BC1`, `BC3`, `BC4`, `BC5`, `BC7`, `ETC1`, `ETC2`, `ASTC_4x4`, `RGBA8`,
+  `RGB565`. A `str` enum: `Target('etc2') is Target.ETC2`. `Target.X.info` is
+  its `TargetFormat`.
+
+`TargetFormat`
+: `basis` (the transcoder's format number), `block` (`(4, 4)`, or `(1, 1)` for
+  pixels), `bytes_per_block` (per pixel when uncompressed), `channels`,
+  `gl_internal_format`, `gl_srgb_internal_format`, `extensions`, `gl_version`,
+  `gles_version`, `srgb_extensions`, `gl_format`, `gl_type`. Properties
+  `compressed` and `has_alpha`. `internal_format(srgb=False)` returns the enum
+  to upload with. `available(extensions, version=(0, 0), es=False, srgb=False)`
+  returns whether a context with those extensions and that version provides
+  the format.
+
+`preferences(codec, es=False, channels='rgba') -> tuple[Target, ...]`
+: The order `choose_target` tries, ending with `RGBA8`.
+
+`choose_target(extensions, codec=Codec.ETC1S, has_alpha=False, version=(0, 0), es=False, srgb=False, channels='rgba') -> Target`
+: The first target in `preferences` the context provides, skipping formats
+  without alpha when `has_alpha` is set and formats without an sRGB enum when
+  `srgb` is set. Returns `RGBA8` when nothing compressed is available.
+
+`Codec`
+: An `IntEnum` of the transcoder's `basis_tex_format` values. `Codec.X.is_hdr`
+  is true for `UASTC_HDR_4x4`, `ASTC_HDR_6x6` and `UASTC_HDR_6x6`.
+
+## Errors
+
+`BasisuError(ValueError)`, and its subclass `UnsupportedError`.
+
+## Versions
+
+`__version__` is this package's version. `BASISU_VERSION` is the
+basis_universal tag compiled in; `vendor/basis_universal/VERSION` has the
+commit.
+
+## Sanitizer run
+
+The fuzz tests in `tests/test_errors.py` corrupt and truncate every fixture.
+To run them against an AddressSanitizer and UndefinedBehaviorSanitizer build,
+copy the project to a scratch directory, change the non-Windows `CXX_FLAGS`
+and `C_FLAGS` in its `setup.py` to `-O1 -g -fsanitize=address,undefined
+-fno-omit-frame-pointer`, then:
+
+```
+LDFLAGS=-fsanitize=address,undefined python setup.py build_ext --inplace
+LD_PRELOAD="$(gcc -print-file-name=libasan.so) $(gcc -print-file-name=libubsan.so)" \
+ASAN_OPTIONS=detect_leaks=0 \
+UBSAN_OPTIONS=print_stacktrace=1:halt_on_error=1:suppressions=ubsan.supp \
+PYTHONPATH=src python -m pytest -s tests -o addopts=
+```
+
+`ubsan.supp` holds one line, `alignment:basisu_transcoder.cpp`. The UASTC
+bit reader in the transcoder loads 16-bit words from odd addresses inside a
+block, which x86-64 and arm64 execute; UBSan reports each such load. With that
+suppression, 30,000 corrupted copies of each fixture run clean on basis_universal
+`v2_50`.