First part of the per-level streaming API discussed in #1224. This draft carries the truncated-stream regression test, the source-side query and the public surface of the level processor, so the header can be reviewed against what was agreed in the thread before the codec work lands. ktxLevelProcessor_ProcessLevel is intentionally a stub here: argument validation per the final contract, then KTX_UNSUPPORTED_FEATURE.

To answer the question in #1224 first: yes, the truncated-stream regression test was successful. A ktxTexture2 constructs from exactly the serialized metadata prefix without KTX_TEXTURE_CREATE_LOAD_IMAGE_DATA_BIT on unmodified main, for BasisLZ, Zstd-supercompressed and unsupercompressed sources, and the constructor never reads past that prefix. No prerequisite fix to the constructor was needed; the test is the first commit.

What is in the three commits

1. Metadata-only construction tests (test-only). Construction from the prefix through the end of SGD/KVD, as applicable, checked against an instrumented bounded custom ktxStream on all platforms and, on POSIX, a PROT_NONE guard page immediately after the prefix. Also covers the clean failure modes: LOAD bit on a prefix, late ktxTexture2_LoadImageData on a shell, metadata cut one byte into the last section. Files are generated in-process; no new binary resources.

2. ktxTexture2_GetLevelFileInfo — where a level's stored payload lives in the serialized source: absolute byteOffset, byteLength, and the Level Index uncompressedByteLength. A thin public exposure of the existing rebased level index plus _firstLevelFileOffset. Per the thread, ktxTexture2_levelFileOffset() itself is left private and unchanged; the public query wraps its logic and returns KTX_INVALID_OPERATION once the texture no longer has serialized-source state (created with ktxTexture2_Create, or after image data has been loaded). If you would rather expose ktxTexture2_levelFileOffset() directly, in addition or instead, that is a small change.

3. ktxLevelProcessor skeleton — the header as drafted in Feature request: transcode individual mip levels from a partially-downloaded KTX2 file (progressive texture streaming) #1224: opaque type, ktxLevelProcessor_CreateBasis, GetOutputVkFormat, the three layout queries (GetLevelSize / GetImageSize / GetImageOffset, level-relative), ProcessLevel, Destroy. CreateBasis validates the source the same way ktxTexture2_TranscodeBasis does, rejects video with KTX_UNSUPPORTED_FEATURE (follow-up, as agreed), builds the private KTX_TEXTURE_CREATE_NO_STORAGE prototype the queries delegate to, and performs the transcoder's process-wide initialization through the same guarded mechanism TranscodeBasis uses — once, never per processor. To make both paths validate sources, resolve targets and initialize identically, three pieces of TranscodeBasis are factored into internal helpers declared in a new basis_transcode.h: the source gate (transcodable color model, SGD presence), the target resolution (alpha content, automatic-selection mapping, VkFormat with transfer function, PVRTC1 pow2 check, transcoder-availability check) and the guarded basisu_transcoder_init() call. Mechanical; no behavior change to TranscodeBasis. CreateBasis requires the source to retain its serialized-source state and rejects a texture whose image data has been loaded (or one created with ktxTexture2_Create) with KTX_INVALID_OPERATION: ProcessLevel consumes the serialized level payload that only such a source can describe, and loading a Zstd/Zlib source rewrites its level index to the inflated sizes. ProcessLevel re-checks that state through GetLevelFileInfo and validates srcSize against the byteLength it reports; the three layout queries report out-of-range arguments uniformly as KTX_INVALID_VALUE. The processor struct lives in a private header, as texture2.h does for ktxTexture2_private, and level_processor.cpp is added to the libktx Doxygen inputs, so the generated reference documents the ktxLevelProcessor class with its functions and nothing internal.

Settled in #1224 and reflected here

• Caller-provided destination; a complete level (all layers, faces, slices) with no inter-level padding; layout from the queries, not derived from the transcode enum.
• Opaque, reusable processor: generic type ktxLevelProcessor, codec-specific factory ktxLevelProcessor_CreateBasis. The prototype texture stays private.
• ProcessLevel takes exactly the bytes GetLevelFileInfo describes, as stored (BasisLZ / raw or Zstd/Zlib UASTC / HDR 6x6 intermediate); srcSize must equal byteLength. No second mode where src is a slice of loaded pData; no partial payloads.
• ktxTexture2_levelFileOffset() behavior unchanged; the serialized layout is considered discarded once image data has been loaded.
• Video rejected in this PR, supported in a follow-up before release.
• Out of this PR: single-level GL/Vulkan upload; JS binding as a small follow-up (sketch in the thread); Java and Python bindings needed before release.

Still open — your call

1. Processor lifetime. The processor currently borrows the source: it must stay alive and unmodified until ktxLevelProcessor_Destroy (documented on the type and on CreateBasis). This keeps the PR small and avoids duplicating DFD/SGD/level index; bindings retain the source until all processors are gone. Is borrowing acceptable for the C API, or should the processor own a copy of the codec/container metadata from the start?
2. Sharing with the whole-texture path. Plan for the next commits: a private per-level primitive shared by a serialized public adapter (ProcessLevel) and a loaded-data private adapter used by ktxTexture2_TranscodeBasis, so the public contract stays serialized-only while the codec logic is single-sourced; the UASTC HDR 4x4 → ASTC relabel stays a metadata-only fast path; the existing ETC1S video orchestration in TranscodeBasis is preserved. Does that satisfy "usable and called by TranscodeBasisEx for each level it processes", or would you prefer TranscodeBasis to literally call the public function?

Tests

32 new gtest cases in transcodetests, all generated in-process: the construction/over-read/truncation matrix × 3 source variants; GetLevelFileInfo values byte-for-byte against the serialized index, availability before and invalidation after load, invalid arguments, no-serialized-source; processor creation validation and every layout query cross-checked against the actual output of ktxTexture2_TranscodeBasis on an ETC1S 2D-array source. Full library/tools/tests build clean on Linux; libktx.doc builds without new warnings.

Out of scope here (per the thread)

Batch level ranges, cancellation, caching, single-level GL/Vulkan upload, format-property queries, JS/Java/Python bindings (follow-ups), video (follow-up before release), XUASTC sources (rejected by the same source-family gate as TranscodeBasis).