Refactor of mipmapping support and vsgXchange::ktx and dds loaders

[robertosfield]

Hi All,

For the past 3 weeks I've went down a KTX image loader rabbit hole, now finally I've got it all working and have updated the dds and the VSG's mipping mapping support and created a vsgsampler example as part of this work. Changes are now checked into respective masters:

1. VulkanSceneGraph changes: Refactored mipmap layout handling with introduction of dedicated vsg::MipmapLayout class. #1604
2. vsgXchange changes: [https://github.com/Moved to use libktx as an external dependency, updated ktx and dds readers to use new vsg::MipmapLayout class vsgXchange#244]
3. vsgExamples changes: Created vsgsampler example to test mipmappng and vsg::Sampler usage. vsgExamples#376

The big change is refactoring vsgXchange::ktx support so that rather than including an old version of KTX-Software source directly in vsgXchange/src/ktx I have instead moved to linking to libktx as a 3rd party library. The main motivation behind this was to enable full use of ktx2 along with basisu support, which means we'll be able to read imagery that is highly compressed on disk that is directly trans-coded into compressed GPU block textures. This makes it perfect for streaming such as when using paged databases.

Over the past 4 months I've also done a lot of work using .dds image format and came across rendering problems when combining .dds files that used GPU block textures and mipmaps, this issue would show itself on screen as corrupted mipmaps. The refactor of vsgXchange::ktx also tripped up on this same rendering problem once I started loading GPU block textures with mipmaps. I tracked down the the cause of the rendering issues to .dds and .ktx2 files that used GPU block compression and started off with image sizes that weren't a multiple of the block size, such as a 511x511 texture that used 4x4 block compression and mipmaps, the actual data is always round up to the nearest 4 so you get some very odd mipmap sizes on the way down. This curious edge case broke the VSG's assumption of mipmaps halving in size on each successive mipmap.

To resolve this issue I had to rewrite how the VSG handled mipmap layout, providing the option to explicitly specify the layout using a new vsg::MipmapLayout class that provides the pixel size { width, height, depth} along with the offset into the memory used for the texture image. For backwards compatibility the VSG's image related classes also retain the ability to compute the mipmap sizes implicitly when an explicit MipmapLayout isn't provided.

The help test the changes to vsgXchange::dds, vsgXchange::ktx and the mipmapping support I wrote a [vsgsample] example. Here's in it action rendering the testimages that can be found in the KTX-Software repo.

cd KTX-Software/tests/testimages/
$ vsgsampler *.ktx2 *.ktx

Not all the target VkFormats specified in all test KTX images are supported by all graphics hardware/drivers so I've added a runtime query into the vsgsampler example to check for support and report to the console about lack of support. So expect console output like the following:

etc1.ktx : Image format 147 not supported by Vulkan driver/hardware.
etc2-rgb.ktx : Image format 147 not supported by Vulkan driver/hardware.
etc2-rgba1.ktx : Image format 149 not supported by Vulkan driver/hardware.
etc2-rgba8.ktx : Image format 151 not supported by Vulkan driver/hardware.

I have bumped the versions to VulkanSceneGraph-1.1.12, vsgXchange-1.1.8 and vsgExamples-1.1.13 and once we've done more testing across a wider range of OS and build combinations and resolved any issues I'll push ahead and make developer releases for these version numbers. I'd appreciate testing and feedback so we can get these tagged quickly, potentially this week.

[ArepMM]

Without external KTX library, building vsgXchange from master fails: "undefined reference to vsgXchange::ktx::~ktx()"

[AnyOldName3]

You should be able to fix that with this patch.

ktx.patch

diff --git a/src/ktx/ktx_fallback.cpp b/src/ktx/ktx_fallback.cpp
index c510833..5640b9e 100644
--- a/src/ktx/ktx_fallback.cpp
+++ b/src/ktx/ktx_fallback.cpp
@@ -24,6 +24,8 @@ ktx::ktx() :
     vsg::info("ktx::ktx() FALLBACK");
 }
 
+ktx::~ktx() = default;
+
 vsg::ref_ptr<vsg::Object> ktx::read(const vsg::Path&, vsg::ref_ptr<const vsg::Options>) const
 {
     return {};

I'll open a PR for this once I've checked for other problems.

[AnyOldName3]

libktx doesn't like my computer today, so I'll need to submit a patch there before checking this branch further, so I'm going to submit the PR now.

[AnyOldName3]

Nevermind, it looks like Robert's already fixed it.

[robertosfield]

What's the problem you are having with libktx?

FYI, I did the development on Kubuntu 22.04 using libktx built from the KTX-Software repo on github. This morning I booted up my Windows 11 machine and pulled in libktx from vcpkg using:

vcpkg install ktx[vulkan]

[AnyOldName3]

Three weeks ago they updated one of the build scripts to compare two paths with [[ $path1 =~ $path2 ]] without regex-escaping them, and I cloned the repo to C:\C++Libraries, so the ++ was interpreted as invalid regex and broke their script. I've submitted a patch that should make it more robust, but I suspect that it won't get accepted as it might not work on MacOS as I used realpath, which I think is from GNU Coreutils rather than pure posix.

[rainergericke]

Test on MacOS 26.1 / M4 Max / Vulkan 1.4.238.1 / VSG latest commits:

cd KTX-Software/tests/testimages/
$ vsgsampler *.ktx2 *.ktx

is running very well.

Doing this leads to a problem:
$ vsgtextureprojection bear.png

See attachments.

texproj_mac.txt

[robertosfield]

That's a lovely pic, but I don't think the issue with the shader is related to my work on mipmapping/ktx/dds.

I tried with an textures/lz.vsgb from vsgExamples and see the same verbose debug output and shader error:

$ vsgtextureprojection textures/lz.vsgb
....
Warning: Program failed to link.
Warning: glslang info log: ERROR: Linking vertex and fragment stages: Layout location qualifier must match:
    vertex stage: texCoord "layout( location=4) smooth out"
    fragment stage: texCoord "layout( location=3) smooth in"
ERROR: Linking vertex and fragment stages: Layout location qualifier must match:
    vertex stage: viewDir "layout( location=3) smooth out"
    fragment stage: viewDir "layout( location=6) smooth in"

This looks to be down to one of the texture projection example shaders being out of date. I'll look into it.

[robertosfield]

Fixes checked into VSG to quieten debug messages and vsgExample for the shader mismatch.

[rainergericke]

Thanks!