KTX2 file without mipmaps does not load

[hybridherbst]

Description

The attached file does not load with three.js KTX2Loader at the moment, probably because of an incorrect check in the loader.

The attached file does not have mipmaps – it was generated using:

toktx --t2 --assign_oetf srgb --automipmap --encode etc1s  testimage4k.ktx2 inputimage.jpg 

--automipmap according to the docs "causes the KTX file to be marked to request generation of a mipmap pyramid when the file is loaded", so should load the file and then request mipmaps to be generated on the GPU side automatically (without adding them in the file).

Reproduction steps

1. Load this image with KTX2Loader: testimage4k.ktx2.zip
2. Note file does not load with Error: THREE.KTX2Loader: Invalid texture

Screenshots

Seems the check here is wrong, it should probably check levelCount for undefined or null or "not a number" and not !levelCount?

Version

r177

[donmccurdy]

From https://registry.khronos.org/KTX/specs/2.0/ktxspec.v2.html#levelCount —

levelCount = 1 means that a file contains only the base level and the texture isn’t meant to have > other levels. E.g., this could be a LUT rather than a natural image.

levelCount = 0 is allowed, except for block-compressed formats, and means that a file contains only the base level and consumers, particularly loaders, should generate other levels if needed.

BasisLZ / ETC1S is a block-compressed format, so this isn't a valid file, as ktx validate confirms:

error-3017: Invalid levelCount. levelCount cannot be 0 for block-compressed formats.
levelCount is 0 but for block-compressed KTX_SS_BASIS_LZ it must not be 0.

I don't believe it's possible for us to compute mipmaps on compressed textures, without using proprietary software. That said, it is likely that KTX2Loader also doesn't handle this case for uncompressed formats, where mipmap generation would be possible... that could certainly be fixed.

[hybridherbst]

Thanks for looking into it!

So in other words, toktx silently generates an invalid file here? Sounds like --automipmap and --encode should be mutually exclusive.

For future reference,

• here's one that with --automipmap but not block-compressed: testimage.unencoded.ktx2.zip
• and here's one with --genmipmap: testimage.unencoded.mips.ktx2.zip

Both don't load either (but pass in ktx validate). Seems loading fails earlier though, KTX2Loader logs [ERROR] Failed to load KTX2 file: THREE.KTX2Loader: Unsupported vkFormat..

ktx info says:

vkFormat: VK_FORMAT_R8G8B8_SRGB
supercompressionScheme: KTX_SS_NONE

[donmccurdy]

List of vkFormats supported in THREE.KTX2Loader:

three.js/examples/jsm/loaders/KTX2Loader.js

Lines 44 to 73 in 67b9093

	VK_FORMAT_ASTC_4x4_SFLOAT_BLOCK_EXT,
	VK_FORMAT_ASTC_4x4_SRGB_BLOCK,
	VK_FORMAT_ASTC_4x4_UNORM_BLOCK,
	VK_FORMAT_ASTC_6x6_SRGB_BLOCK,
	VK_FORMAT_ASTC_6x6_UNORM_BLOCK,
	VK_FORMAT_BC1_RGBA_SRGB_BLOCK,
	VK_FORMAT_BC1_RGBA_UNORM_BLOCK,
	VK_FORMAT_BC1_RGB_SRGB_BLOCK,
	VK_FORMAT_BC1_RGB_UNORM_BLOCK,
	VK_FORMAT_BC3_SRGB_BLOCK,
	VK_FORMAT_BC3_UNORM_BLOCK,
	VK_FORMAT_BC5_SNORM_BLOCK,
	VK_FORMAT_BC5_UNORM_BLOCK,
	VK_FORMAT_BC7_SRGB_BLOCK,
	VK_FORMAT_BC7_UNORM_BLOCK,
	VK_FORMAT_ETC2_R8G8B8_SRGB_BLOCK,
	VK_FORMAT_ETC2_R8G8B8A8_SRGB_BLOCK,
	VK_FORMAT_R16G16B16A16_SFLOAT,
	VK_FORMAT_R16G16_SFLOAT,
	VK_FORMAT_R16_SFLOAT,
	VK_FORMAT_R32G32B32A32_SFLOAT,
	VK_FORMAT_R32G32_SFLOAT,
	VK_FORMAT_R32_SFLOAT,
	VK_FORMAT_R8G8B8A8_SRGB,
	VK_FORMAT_R8G8B8A8_UNORM,
	VK_FORMAT_R8G8_SRGB,
	VK_FORMAT_R8G8_UNORM,
	VK_FORMAT_R8_SRGB,
	VK_FORMAT_R8_UNORM,
	VK_FORMAT_UNDEFINED

VK_FORMAT_R8G8B8_SRGB is missing because we don't officially support RGB8 in three.js anymore, only R8, RG8, or RGBA8. If you're interested in how we've created the samples used in the KTX2Loader example, see:

https://github.com/donmccurdy/KTX2-Samples/blob/e428865c6266daa3f77b974eb567997cbc7509e9/encode.sh#L20-L38

I agree that KTX Software allowing --automipmap without an error or warning is a bit confusing, and arguably a bug, yes.

[donmccurdy]

Oops, I'd missed #27992 ... I guess we could go ahead and handle RGB8 in KTX2Loader, too? /cc @Mugen87

[donmccurdy]

Proposed:

• KTX2Loader: Support .generateMipmaps=true #31621
• KTX2Loader: Support RGB8 #31619