v5.0.0-rc1 #1163

MarkCallow · 2026-05-01T11:09:37Z

MarkCallow
May 1, 2026
Maintainer

Summary

This is a major release. Although the reason for bumping the major number is a small but incompatible change in the libktx API, there are major changes throughout the software:

ktxBasisParams API has two incompatible changes.
Support for the Binomial UASTC HDR formats has been added to all supported API bindings and relevant tools.
The ktx tool suite is now a superset of the legacy tools.
The legacy tools have been removed.
A CMake project has been added to build libktx.
Source code of dependencies is no longer included in CMake target source lists. All dependencies are now built by their own CMake projects and linked to libktx.

This is a pre-release because the version of the KTX specification with which it is compliant, Document Revision 5, has not yet been published. The source of the draft is available at KhronosGroup/KTX-Specification#216.

New Features in v5.0

Tools

Images can be encoded to the Binomial UASTC HDR 4x4 and UASTC HDR 6x6 Intermediate formats in ktx create and ktx encode. Images in these formats can be transcoded to ASTC HDR or BC6H Unsigned formats.
ktx extract can extract images in ASTC HDR formats from KTX v2 files. It writes them to .exr files. It will apply KTXmapRange during extraction.
ktx create accepts a --premultiply-alpha option.
ktx create can resize or scale its input files, except .raw.
ktx create accepts file name listing files as input. Prefix the name of such a file with @ or @@.
ktx convert for converting KTX v1 files.

This shows the equivalent new tool for each removed legacy tool.

Legacy Tool	`ktx` tool
ktx2ktx2	convert -t ktx
ktx2check	validate
ktxinfo	info
ktxsc	deflate or encode
toktx	create

libktx functions

ktxTexture2_CompressBasisEx can now encode to Binomial UASTC HDR 4x4 and UASTC HDR 6x6 Intermediate formats. There are two incompatible changes in the struct ktxBasisParams passed to this function:
- ktx_bool_t uastc is now ktx_basis_codec_e codec which accepts the following values
  - KTX_BASIS_CODEC_NONE
  - KTX_BASIS_CODEC_ETC1S
  - KTX_BASIS_CODEC_UASTC_LDR_4x4
  - KTX_BASIS_CODEC_UASTC_HDR_4x4
  - KTX_BASIS_CODEC_UASTC_HDR_6x6_INTERMEDIATE
- compressionLevel is now named etc1sCompressionLevel
ktxTexture2_DecodeAstc can now decode ASTC HDR files.
ktxTexture2_TranscodeBasis can transcode images in UASTC HDR 4x4 and UASTC HDR 6x6 Intermediate formats to ASTC HDR or BC6H Unsigned.

The new functionality is exposed in the Java, JavaScript and Python bindings.

Notable Fixes in v5.0

A crash in ktx create when reading tiled .exr files has been fixed.
An extra swizzle, when generating mip levels when the output image components are not in RGBA order, leading to incorrect colors in some mip levels has been
fixed.
The default wrap mode when generating mip levels in ktx create has been changed to CLAMP, the same default that was set in toktx.
When loading .exr files in ktx create, the default primaries are set to BT709 instead of UNSPECIFIED.
Non-sRGB ASTC format KTX v1 files are mapped to the VK_FORMAT_ASTC_*_SFLOAT_BLOCK format with the same block dimensions when uploaded to Vulkan or converted to KTX v2 instead of the VK_FORMAT_ASTC_*_UNORM_BLOCK format.
Per a bug fix in the Khronos Data Format Specification, the Data Format Descriptor's channelType field is now called channelId. This change is visible in the outputs of ktx info and ktx compare. New schema versions have been published for their JSON outputs.

Known Issues

Files deflated with zlib using libktx compiled with GCC and run on x86_64 may not be bit-identical with those using libktx compiled with GCC and run on arm64.
Users making Basis Universal encoded or GPU block compressed textures for WebGL must be aware of WebGL restrictions with regard to texture size and may need to resize input images appropriately before using ktx create, or use the --resize feature to produce an appropriately sized texture. In general, the dimensions of block compressed textures must be a multiple of the block size in WebGL and for WebGL 1.0 textures must have power-of-two dimensions. Additional portability restrictions apply for glTF per the KHR_texture_basisu extension which can be verified using the --gltf-basisu command-line option of ktx validate.
UASTC RDO results differ from run to run unless multi-threading or RDO multi-threading is disabled. In ktx create or ktx encode use --threads 1 for the former or --uastc_rdo_m for the latter. Results are valid but level sizes will differ slightly. See issue #151 in the basis_universal repository.
Neither the Vulkan nor GL loaders support depth/stencil textures.

Acknowledgements

Thanks to all who have contributed to this release. Their GitHub handles are included in the list of commits below. Particluar thanks to:

Rich Geldreich (@richgel999) for creating the transcodable HDR technology.
Phasmatic (@ViNeek and @agkar) who did the bulk of the HDR-related work under
contract from Khronos.
Google for funding that work.
Marco Hutter (@javagl) for adding the HDR api to the Java binding.
@jiangzhhhh for adding pre-multiplied alpha support to ktx create.

Commits since v4.4.2 (by part with details)

Note: commits will appear in each part they affected.

libktx

Bump default version number. (Bump default version number. #1161) (6c474d8) (@MarkCallow)

Various other issues were encountered and fixed while checking the
version number related changes.
1. Fix -a option of mkversion. It did not visit lib/src and ended
  with an error due to a misplaced fi.
2. Fix RE in ktx convert that resulted in an extra space in an edited
  KTXwriterScParams when the original zcmp option had a parameter.
3. Fix ktxTexture2_IsHDR which was only checking for a FLOAT qualifier
  on DFD samples for the ASTC color model. Add a test for it.
Fixes Update default version when major version is updated #1112.
Fix build issues (Fix build issues #1160) (f2d222d) (@MarkCallow)
1. Suppress what looks to be a bogus stringop-overflow warning from GCC,
  observed with both versions 13 and 15.
2. Change outdated SSE and OPENCL option names to current names so they
  are acted on properly.
Given the issues being fixed here, I am unable to understand why our CI
builds have been green.
Remove --rec2020 flag and add range mapping functionality to ktx create and ktx extract (Remove --rec2020 flag and add range mapping functionality to ktx create and ktx extract #1157) (20211a2) (@ViNeek)

This PR fixes Improve handling of KTXmapRange metadata #1142 and fixes Remove --rec2020 option; set encoder param automatically from the DFD values #1127.

For Remove --rec2020 option; set encoder param automatically from the DFD values #1127, it removes the flag from ktx create and ktx encode and
makes sure that the profile is automatically inferred from the loaded
EXR file.

For Improve handling of KTXmapRange metadata #1142 It adds 3 knew flags to ktx create, namely,
map-range-auto, map-range-offset and map-range-scale to be used
for mapping of floating point values in HDR formats.

ktx extract is also updated to handle inverse mapping of values when
the KTXmapRange key/value pair is present in a KTX2 file.

Currenlty, offset and scale are not used for the alpha channel.
Currently, range mapping only works with floating point data types and
the new HDR formats.
Proper handling of --uastc-quality and --uastc-hdr-6x6i-level option values (Proper handling of --uastc-quality and --uastc-hdr-6x6i-level option values #1149) (de9a41a) (@ViNeek)

This PR fixes --uastc-quality and --uastc-hdr-6x6i-level option values not passed to basisu_encoder #1146. The values are properly forwarded to the basis
encoder.

Includes fix to make ktxdiff properly compare half-float files.
Ensure enums with ktx_uint32_t equivalents really are unsigned. (Ensure enums with ktx_uint32_t equivalents really are unsigned. #1152) (23f560d) (@MarkCallow)
Update basisu for fixes backported from 2.0 (Update basisu for fixes backported from 2.0 #1151) (43c716c) (@MarkCallow)

These are:
- Critical fixes for extreme inputs/outputs
- Compiler warning
- Fix parsing of uint64 in KTX2 header
- Fix initialization of astc_helper tables for transcoding.
Remove our workaround for the astc_helper tables not being initialized.

Fix ktxdiff to choose correct transcode target when comparing HDR
payloads.
Expose HDR support in Python binding (Expose HDR support in Python binding #1150) (5444378) (@MarkCallow)

Fixes Add HDR support to Python binding #1145.

Additional fixes:
- Adds num_layers property that was curiously missing.
- Exposes ktxTexture[12]_IsHDR in the c API.
- Reformats documentation comments for UASTC HDR ktxBasisParams to
  reduce line width.
Fix dumping of encoder input data (7ad1889) (@MarkCallow)

for compilers supporting std::filesystem and for HDR.
Fix validation warning for VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL c… (Fix validation warning for VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL c… #1148) (2914abe) (@MarkCallow)

…ase.

For the VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL case of
setImageLayout, where dstAccessMask is VK_ACCESS_SHADER_READ_BIT,
settingdestStageFlags to VK_PIPELINE_STAGE_ALL_COMMANDS_BIT is
invalid usage and is flagged by the validator in recent Vulkan SDKs.
Change dstStageFlags for this case to
VK_PIPELINE_STAGE_ALL_GRAPHICS_BIT | VK_PIPELINE_STAGE_COMPUTE_SHADER_BIT.

Fixes Using 'ktxTexture_VkUpload' with an image layout of 'VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL' causes an validation error. #1092.

Includes completely unrelated fixes for warnings that are new in
Emscripten 5.0.3 so that CI builds are successful.
- Set -Wno-experimental to disable compile- and link-time warnings that
  sdl3 is still experimental.
- Change EMSCRIPTEN pre-processor macro to __EMSCRIPTEN__ to stop
  deprecation warnings.
Document that GL_COMPRESSED_RGBA_ASTC formats are converted to SFLOAT equivalents. (1499a55) (@MarkCallow)
Enable decode and extraction of ASTC HDR. (Enable decode and extraction of ASTC HDR. #1143) (af3039c) (@MarkCallow)

Fixes extraction of ASTC HDR 6x6: fatal message from ktx tool #1140.
Remove dead code. (535c77d) (@MarkCallow)
CMake improvements for installing and dependencies (CMake improvements for installing and dependencies #1133) (8b925f2) (@MarkCallow)
- Handle installation of KHR/khr_df.h for KTX-Software in KTX-Software
  (lib/CMakeLists.txt) avoiding some confusion and making installation
  in a framework possible.
- Use add_lib_dependency macro to add dfdutils dependency to libktx and
  remove unnecessary PUBLIC export.
- Use FILE_SETs for installation of both dfdutils and libktx include
  files to handle the KHR subdirectory, with a workaround for framework
  installation.
- Up the cmake minimum version to 3.23 in both dfdutils CMakeLists and
  lib CMakeLists.txt This is so
  - FILE_SET can be used
  - KTX-Software can override options settings with ordinary variables
    thus hiding unnecessary DFDUTILS options from the CMake GUI.
- Add option to turn off dfdutils docs build so lib/CMakeLists.txt can
  do so.
- Update dfdutils install to install library and dfd.h in addition to
  KHR/khr_df.h. This is behind an option so the KTX-Software build can
  turn it off.
- Include GNUInstallDirs to get proper values for CMAKE_INSTALL_.
- Normalize the indentation in dfdutils/CMakeLists.txt.
- Improve command clarity.
cmake --build ... --target install and the installable packages have
been tested on all 3 desktop platforms and the framework in the iOS .zip
file and content of the Android .zip file have been verified. All have
the expected content.

Fixes khr_df.h is not included in the install packages #1121. Fixes Don't configure dfdutils docs target when building KTX-Software #1123.
Fix issue with HDR transcode and extract (Fix issue with HDR transcode and extract #1139) (5d29c57) (@ViNeek)

The PR should fix the issues with ktx extract for both UASTC 4x4 and
UASTC 6x6i (see issue Can't extract UASTC_HDR_4x4 files, with potential fix #1134). The code has also been patched to properly
extract mip map levels. Thank you @richgel999 for providing the code
snippet.

Extraction from regular ASTC data ktx extract --all astc_hdr_6x6.ktx2
won't work. Direct encoding/decoding of VK_FORMAT_ASTC_6x6_SFLOAT_BLOCK
and VK_FORMAT_ASTC_4x4_SFLOAT_BLOCK (or any other SFLOAT block size) is
not supported by the current version of the software. Same goes with
ktx create:

A command like ktx create --format VK_FORMAT_ASTC_4x4_SFLOAT_BLOCK input.exr output.ktx2 does not support the creation of an
VK_FORMAT_ASTC_4x4_SFLOAT_BLOCK-encoded ktx2 file.

Fixes Can't extract UASTC_HDR_4x4 files, with potential fix #1134.
Add HDR support to vkloadtests (Add HDR support to vkloadtests #1130) (dcc4346) (@MarkCallow)

Invoke with --hdr to get an R16G16B16 HDR rendering surface.
- Add support for transcoding the new HDR formats.
- Add a sample in each of UASTC HDR 4x4 and UASTC HDR 6x6i.
Improved HDR support (Improved HDR support #1124) (35d9f8d) (@ViNeek)

Fixes Implement KTXmapRange #1122, Add an early out to ktxTexture2_TranscodeBasis when outputFormat is ASTC_HDR_4x4 and the texture format is UASTC_HDR_4X4 #1119, Use NxN consistently for format size in tokens #1120 and Crash when transcoding UASTC HDR 6x6i to ASTC HDR 6x6 #1125.
HDR Support for libktx and tools (HDR Support for libktx and tools #1100) (c0a32ef) (@ViNeek)

The pull request adds initial support for HDR data in libktx and tools

In particular,
1. The CLI ktx tool is updated so that:
- the ktx info command supports UASTC HDR payload formats as
  defined in the KTX Specification.
- the ktx validate command implements new validation clauses related
  to the UASTC HDR payload formats
- the ktx encode command now accepts uastc-hdr-4x4 and
  uastc-hdr-6x6i as codec strings.
- These codecs require the input file format to be either
  R16G16B16_SFLOAT or R16G16B16A16_SFLOAT.
- the ktx create command when the encode parameter is used,
  accepts uastc-hdr-4x4 and uastc-hdr-6x6i for the codec
  parameter
- if the input is raw, these codecs require the format parameter to be
  either R16G16B16_SFLOAT or R16G16B16A16_SFLOAT;
- if the input is not raw, the input files must be EXR with half-float
  data type
- the ktx transcode supports the two new codecs for input files:
- uastc-hdr-4x4 inputs must accept three targets: rgba16f,
  astc-hdr-4x4, and bc6hu
- uastc-hdr-6x6i inputs must accept three targets: rgba16f,
  astc-hdr-6x6, and bc6hu
- if an input file is neither of these two formats, the targets are
  rejected,
- the ktx extract command supports the two new codecs for input files
- uastc-hdr-4x4 inputs may be extracted as raw, or transcoded as in
  ktx transcode
- uastc-hdr-6x6i inputs require transcoding as in ktx transcode
  when used with this command
- the ktx compare command, when used with UASTC HDR 4x4 or UASTC
  HDR 6x6 data and pixel comparison is requested, the image is
  transcoded to uncompressed half-float values prior to comparison
1. The existing JavaScript bindings is updated to support the new
  functionality, specifically transcoding of UASTC HDR payloads
Incidentally fixes Option to build tools could be more visible #1109.
Remove legacy tools (Remove legacy tools #1110) (05b0e02) (@MarkCallow)
- Remove legacy tools, documentation and references to them.
- Reorganize and normalize the names of still needed test images (now
  under tests/resources).
- Rewrite genktx2 script to generate needed .ktx2 resources using ktx
  suite.
- Fix missing features and bugs in suite discovered when rewriting
  genktx2:
  - Fix default imageio scanline reader to only buffer and rescale a
    scanline's worth of pixels.
  - Add channel add/remove functionality to default scanline reader
    as ktx create always requests 4 channels.
  - Fix ImageT::yflip to not attempt to yflip a 1 row image thus not
    crash.
  - Add listing file support to ktx create so multiple input files names
    can be provided as a list in another file
  - Fix so sample qualifierLinear does not cause sameUnitAllChannels not
    to be set.
- Fix unit tests to compile with c++20 and simplify file handling by
  using std::filesystem.
  - texturetests, transcodetests, streamtests & threadtests now use
    std::format. This PR works around GCC 11's (the GCC version on
    Ubuntu 22.04 CI runners) lack of support for std::format by using
    fmt::format in that case.
Add lock around transcoder initialization (Add lock around transcoder initialization #1098) (964acdc) (@MarkCallow)

Fixes Concurrency issues when call ktxTexture2_TranscodeBasis in multithreading. #1087.

Add threadtests - though unsure how useful they are.

Update all libktx tests for c++20 as new tests need it for std::barrier.

Fixes basisu_c_binding build when ktx_read target is not included in
build.

Big thanks to @vmwalker for reporting the problem and providing the fix.
Combine lib dependencies into static libktx on all desktop platforms (Combine lib dependencies into static libktx on all desktop platforms #1090) (5a07bc6) (@MarkCallow)

Previously this was only done on macOS - using libtool. Changed to
a simple, though hard to find, cross-platform way to do this via CMake.

Add CI test of build and use of a static library.

Remove macOS 13 build from CI as these runner images have been
retired from GitHub Actions.
Fix use of libktx project as subproject outside of KTX-Software (Fix use of libktx project as subproject outside of KTX-Software #1089) (7f0f889) (@MarkCallow)

The Fix
- Always include cmake/codesign.cmake and cmake/cputypetest.cmake.
  Add include_guard() to them to prevent multiple inclusion.
- Add host project for testing sub-project use and update workflow
  to build and run it and libktx.
Other Changes
- Add options to select building of full or read-only libktx.
- Fix macOS build when CODE_SIGN_IDENTITY not set. Fixes
  both libktx and the larger KTX-Software project.
Fixes Unable to use lib/CMakeLists.txt directly because of PROJECT_IS_TOP_LEVEL CMake variable #1083

Fix creating static ktx_read convenience lib (Fix creating static ktx_read convenience lib #1081) (4b46cda) (@dg0yt)

Fixes "duplicate member name" warnings:

[130/148] : [...] libtool -static -o
/Users/vcpkg/Data/b/ktx/x64-osx-rel/libktx\_read.a
/Users/vcpkg/Data/b/ktx/x64-osx-rel/libktx.a
/Users/vcpkg/Data/b/ktx/x64-osx-rel/external/astc-encoder/Source/libastcenc-avx2-static.a

/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/libtool:
warning for architecture: x86\_64h duplicate member name
'astcenc\_averages\_and\_directions.cpp.o' from '/Users/vcpkg/Data/b/ktx/x64-osx-rel/external/astc-encoder/Source/libastcenc-avx2-static.a(astcenc\_averages\_and\_directions.cpp.o)'
and
'/Users/vcpkg/Data/b/ktx/x64-osx-rel/libktx.a(astcenc\_averages\_and\_directions.cpp.o)'

Update basis_universal (Update basis_universal #1080) (422f501) (@MarkCallow)

master, in the fork from which we pull basis_universal, has been updated
to basis_universal master as of 2025.11.22, which includes all our
previous warning fixes. The changes there have been merged to the
cmake_fixes branch we pull from.

Also included:
- fix: change basis-related cmake option names to match those in
  basis_universal and update workflows to set the new names;
- fix: deploy x86_64 package, broken when build moved to x86_64 runner;
- enhancement: apply changes resulting from a review of the cmake_fixes
  PR for basis_universal.
git subrepo clone --branch=cmake_fixes --force https://github.com/KhronosGroup/basis\_universal.git external/basis_universal

subrepo:
subdir: "external/basis_universal"
merged: "daf79c6ee"
upstream:
origin: "https://github.com/KhronosGroup/basis\_universal.git"
branch: "cmake_fixes"
commit: "daf79c6ee"
git-subrepo:
version: "0.4.9"
origin: "https://github.com/MarkCallow/git-subrepo.git"
commit: "4f60dd7"

Fixes FMT dependency in ktx is causing a lot issues while compiling. #1079.
Required changes to work with basis_universal release 1.60+. (ac2edf1) (@MarkCallow)
- Stop direct inclusion of sources. Use their cmake project to build the
  library as a subproject.
- Adapt to renamed functions.
- Update reference files for changed encoder results.
Unrelated but necessary fixes:
- fix bug in build_macos_sh that preventing running of tests when
  cross-compiling for x86_64 on arm64;
- fix CI to build x86_64 macOS package on an x86_64 runner as the
  x86_64 Java and Python tests will not run via Rosetta
Create libktx project (Create libktx project #1071) (6765255) (@MarkCallow)

Move the libktx build from the root CMakeLists.txt to its own in the
lib directory. Although still within KTX-Software, the new libktx
project CMakeLists.txt can be used as either a sub-project of
KTX-Software or as a standalone project to build just libktx.

This has been done due to both direct requests, such as
How do I integrate building (just) libktx(_read) into my own software? #995 and
indirect requests such as complaints that the root CMakeLists is too
complicated. The effort has led to some useful cleanup and better
modularization.

The following FEATURE options have been moved to the libktx project and
consequently renamed with a LIBKTX prefix:
- LIBKTX_FEATURE_KTX1
- LIBKTX_FEATURE_KTX2
- LIBKTX_FEATURE_VK_UPLOAD
- LIBKTX_FEATURE_GL_UPLOAD
- LIBKTX_FEATURE_ETC_UNPACK
These options have been duplicated in the libktx project so they can be
set when it is the top-level project:
- LIBKTX_EMBED_BITCODE
- LIBKTX_WERROR
When libktx is used as a sub-project, they are set from the similarly
named KTX-Software options.

Add a workflow to test configuring and building a standalone libktx.

Along the way, fixed a bug, that caused configurations in the linux.yml
workflow that were supposed to incorporate OpenCL to not do so. However
it is not possible to run the tests on those configurations as the
Actions runners report the cpu type as "generic" so Portable OpenCL
(POCL) can't figure out what to do.

Also along the way, update the ignore lists in all the workflow files to
include newer workflows files.
Fix potential buffer read overflow in ktxTexture2_WriteToStream. (14bc6f0) (@MarkCallow)

This was caused on Android (Linux also?) by memchr trying to read n bytes where n is the guard length passed to it before searching for the wanted character. Fix is to avoid memchr and any other external function in the homegrown strnlen used on Android, Linux, Windows and the web.

Fixes ktxTexture_WriteToMemory() Buffer Overflow #1064.
ktx create: add premultiply alpha option (ktx create: add premultiply alpha option #1049) (83d84dc) (@jiangzhhhh)
- Add alpha pre-multiply function to image.hpp.
- Update base Texture load test to check for pre-multiplied textures
  and add a sample to the tests.

Tools

Bump default version number. (Bump default version number. #1161) (6c474d8) (@MarkCallow)

Various other issues were encountered and fixed while checking the
version number related changes.
1. Fix -a option of mkversion. It did not visit lib/src and ended
  with an error due to a misplaced fi.
2. Fix RE in ktx convert that resulted in an extra space in an edited
  KTXwriterScParams when the original zcmp option had a parameter.
3. Fix ktxTexture2_IsHDR which was only checking for a FLOAT qualifier
  on DFD samples for the ASTC color model. Add a test for it.
Fixes Update default version when major version is updated #1112.
Fix build issues (Fix build issues #1160) (f2d222d) (@MarkCallow)
1. Suppress what looks to be a bogus stringop-overflow warning from GCC,
  observed with both versions 13 and 15.
2. Change outdated SSE and OPENCL option names to current names so they
  are acted on properly.
Given the issues being fixed here, I am unable to understand why our CI
builds have been green.
Fix handling of DFD linear qualifier (Fix handling of DFD linear qualifier #1158) (3148f72) (@MarkCallow)

Fix ktx create to set the linear qualifier according to the transfer
function and channel id, instead of always setting it to the default
value for the output VkFormat.

Fix the validator to allow values that differ from the default provided
they comply with the KTX specification.

Fixes Problems with handling of DFD linear qualifier #1156.
Change channelType to channelId to match latest KDFS. (Change channelType to channelId to match latest KDFS. #1155) (57ef740) (@MarkCallow)
Remove --rec2020 flag and add range mapping functionality to ktx create and ktx extract (Remove --rec2020 flag and add range mapping functionality to ktx create and ktx extract #1157) (20211a2) (@ViNeek)

This PR fixes Improve handling of KTXmapRange metadata #1142 and fixes Remove --rec2020 option; set encoder param automatically from the DFD values #1127.

For Remove --rec2020 option; set encoder param automatically from the DFD values #1127, it removes the flag from ktx create and ktx encode and
makes sure that the profile is automatically inferred from the loaded
EXR file.

For Improve handling of KTXmapRange metadata #1142 It adds 3 knew flags to ktx create, namely,
map-range-auto, map-range-offset and map-range-scale to be used
for mapping of floating point values in HDR formats.

ktx extract is also updated to handle inverse mapping of values when
the KTXmapRange key/value pair is present in a KTX2 file.

Currenlty, offset and scale are not used for the alpha channel.
Currently, range mapping only works with floating point data types and
the new HDR formats.
Fix typo in comment. (bc8ec6c) (@MarkCallow)
Reinstate ktxtools_mainpage. (4ffa3f0) (@MarkCallow)

Fix issues in its content.
Document that GL_COMPRESSED_RGBA_ASTC formats are converted to SFLOAT equivalents. (1499a55) (@MarkCallow)
Enable decode and extraction of ASTC HDR. (Enable decode and extraction of ASTC HDR. #1143) (af3039c) (@MarkCallow)

Fixes extraction of ASTC HDR 6x6: fatal message from ktx tool #1140.
CMake improvements for installing and dependencies (CMake improvements for installing and dependencies #1133) (8b925f2) (@MarkCallow)
- Handle installation of KHR/khr_df.h for KTX-Software in KTX-Software
  (lib/CMakeLists.txt) avoiding some confusion and making installation
  in a framework possible.
- Use add_lib_dependency macro to add dfdutils dependency to libktx and
  remove unnecessary PUBLIC export.
- Use FILE_SETs for installation of both dfdutils and libktx include
  files to handle the KHR subdirectory, with a workaround for framework
  installation.
- Up the cmake minimum version to 3.23 in both dfdutils CMakeLists and
  lib CMakeLists.txt This is so
  - FILE_SET can be used
  - KTX-Software can override options settings with ordinary variables
    thus hiding unnecessary DFDUTILS options from the CMake GUI.
- Add option to turn off dfdutils docs build so lib/CMakeLists.txt can
  do so.
- Update dfdutils install to install library and dfd.h in addition to
  KHR/khr_df.h. This is behind an option so the KTX-Software build can
  turn it off.
- Include GNUInstallDirs to get proper values for CMAKE_INSTALL_.
- Normalize the indentation in dfdutils/CMakeLists.txt.
- Improve command clarity.
cmake --build ... --target install and the installable packages have
been tested on all 3 desktop platforms and the framework in the iOS .zip
file and content of the Android .zip file have been verified. All have
the expected content.

Fixes khr_df.h is not included in the install packages #1121. Fixes Don't configure dfdutils docs target when building KTX-Software #1123.
Fix issue with HDR transcode and extract (Fix issue with HDR transcode and extract #1139) (5d29c57) (@ViNeek)

The PR should fix the issues with ktx extract for both UASTC 4x4 and
UASTC 6x6i (see issue Can't extract UASTC_HDR_4x4 files, with potential fix #1134). The code has also been patched to properly
extract mip map levels. Thank you @richgel999 for providing the code
snippet.

Extraction from regular ASTC data ktx extract --all astc_hdr_6x6.ktx2
won't work. Direct encoding/decoding of VK_FORMAT_ASTC_6x6_SFLOAT_BLOCK
and VK_FORMAT_ASTC_4x4_SFLOAT_BLOCK (or any other SFLOAT block size) is
not supported by the current version of the software. Same goes with
ktx create:

A command like ktx create --format VK_FORMAT_ASTC_4x4_SFLOAT_BLOCK input.exr output.ktx2 does not support the creation of an
VK_FORMAT_ASTC_4x4_SFLOAT_BLOCK-encoded ktx2 file.

Fixes Can't extract UASTC_HDR_4x4 files, with potential fix #1134.
Fix: stop extra swizzle when generating mipmaps. (Fix: stop extra swizzle when generating mipmaps. #1137) (29a149c) (@MarkCallow)

And generate all mip levels from the base level instead of
the previous level.

Fixes ktx create bug #1116.
Change default wrap mode to CLAMP. Remove deprecated oetf options. (dcd0e93) (@MarkCallow)

Fixes [ktx create] Cubemap and --generate-mipmap creates seams in mipmaps due to not sampling adjacent faces #1118.
Support loading tiled EXR files. (Support loading tiled EXR files. #1135) (3abe70a) (@MarkCallow)

Add face order info to --cubemap info in command_create.

Fixes issue Segmentation fault when trying to create a cubemap from .exr files #1111.
Change default primaries for EXR (Change default primaries for EXR #1128) (f1c169d) (@MarkCallow)

from UNSPECIFIED to BT709, per the EXR spec.
Improved HDR support (Improved HDR support #1124) (35d9f8d) (@ViNeek)

Fixes Implement KTXmapRange #1122, Add an early out to ktxTexture2_TranscodeBasis when outputFormat is ASTC_HDR_4x4 and the texture format is UASTC_HDR_4X4 #1119, Use NxN consistently for format size in tokens #1120 and Crash when transcoding UASTC HDR 6x6i to ASTC HDR 6x6 #1125.
HDR Support for libktx and tools (HDR Support for libktx and tools #1100) (c0a32ef) (@ViNeek)

The pull request adds initial support for HDR data in libktx and tools

In particular,
1. The CLI ktx tool is updated so that:
- the ktx info command supports UASTC HDR payload formats as
  defined in the KTX Specification.
- the ktx validate command implements new validation clauses related
  to the UASTC HDR payload formats
- the ktx encode command now accepts uastc-hdr-4x4 and
  uastc-hdr-6x6i as codec strings.
- These codecs require the input file format to be either
  R16G16B16_SFLOAT or R16G16B16A16_SFLOAT.
- the ktx create command when the encode parameter is used,
  accepts uastc-hdr-4x4 and uastc-hdr-6x6i for the codec
  parameter
- if the input is raw, these codecs require the format parameter to be
  either R16G16B16_SFLOAT or R16G16B16A16_SFLOAT;
- if the input is not raw, the input files must be EXR with half-float
  data type
- the ktx transcode supports the two new codecs for input files:
- uastc-hdr-4x4 inputs must accept three targets: rgba16f,
  astc-hdr-4x4, and bc6hu
- uastc-hdr-6x6i inputs must accept three targets: rgba16f,
  astc-hdr-6x6, and bc6hu
- if an input file is neither of these two formats, the targets are
  rejected,
- the ktx extract command supports the two new codecs for input files
- uastc-hdr-4x4 inputs may be extracted as raw, or transcoded as in
  ktx transcode
- uastc-hdr-6x6i inputs require transcoding as in ktx transcode
  when used with this command
- the ktx compare command, when used with UASTC HDR 4x4 or UASTC
  HDR 6x6 data and pixel comparison is requested, the image is
  transcoded to uncompressed half-float values prior to comparison
1. The existing JavaScript bindings is updated to support the new
  functionality, specifically transcoding of UASTC HDR payloads
Incidentally fixes Option to build tools could be more visible #1109.
Fix build problems w/ fmt and C++23 (Fix build problems w/ fmt and C++23 #1102) (b3619b2) (@ltjax)

Fixes Tools do not compile with CMAKE_CXX_STANDARD set to 23 #1101 .
Remove legacy tools (Remove legacy tools #1110) (05b0e02) (@MarkCallow)
- Remove legacy tools, documentation and references to them.
- Reorganize and normalize the names of still needed test images (now
  under tests/resources).
- Rewrite genktx2 script to generate needed .ktx2 resources using ktx
  suite.
- Fix missing features and bugs in suite discovered when rewriting
  genktx2:
  - Fix default imageio scanline reader to only buffer and rescale a
    scanline's worth of pixels.
  - Add channel add/remove functionality to default scanline reader
    as ktx create always requests 4 channels.
  - Fix ImageT::yflip to not attempt to yflip a 1 row image thus not
    crash.
  - Add listing file support to ktx create so multiple input files names
    can be provided as a list in another file
  - Fix so sample qualifierLinear does not cause sameUnitAllChannels not
    to be set.
- Fix unit tests to compile with c++20 and simplify file handling by
  using std::filesystem.
  - texturetests, transcodetests, streamtests & threadtests now use
    std::format. This PR works around GCC 11's (the GCC version on
    Ubuntu 22.04 CI runners) lack of support for std::format by using
    fmt::format in that case.
Fix C++20 build issues. (Fix C++20 build issues. #1104) (9d8594b) (@MarkCallow)
- Remove OutputString:: prefix from in class definition of constructor.
- Add u8string overload of InputStream constructor.
- Fix return type of from_u8string.
- Add from_u8string and to_u8string overloads that take u8string_view
  and string_view respectively.
- Provide overloads of fmtInFile and fmtOutFile that take u8string_view.
- Avoid use of filesystem::path::u8path in c++20 to avoid deprecation
  warning.
Support listing files for multiple inputs and u8string utf8 utilities. (Support listing files for multiple inputs and u8string utf8 utilities. #1103) (bb7c7d1) (@MarkCallow)

This is a piece of legacy tool functionality, used in our asset
generation script, that was missing.

This PR also adds a u8string version of the utf8 utilities in
platform_utils.h and u8string constructors to OutputStream{,Ex} to make
things work when building with c++20 and newer. All is protected by
macro checks for u8string support.
Add convert command (Add convert command #1099) (0eaebb0) (@MarkCallow)

For converting ktx v1 files.

Fixes formatting error in encode man page (doxygen).
Add lock around transcoder initialization (Add lock around transcoder initialization #1098) (964acdc) (@MarkCallow)

Fixes Concurrency issues when call ktxTexture2_TranscodeBasis in multithreading. #1087.

Add threadtests - though unsure how useful they are.

Update all libktx tests for c++20 as new tests need it for std::barrier.

Fixes basisu_c_binding build when ktx_read target is not included in
build.

Big thanks to @vmwalker for reporting the problem and providing the fix.
Required changes to work with basis_universal release 1.60+. (ac2edf1) (@MarkCallow)
- Stop direct inclusion of sources. Use their cmake project to build the
  library as a subproject.
- Adapt to renamed functions.
- Update reference files for changed encoder results.
Unrelated but necessary fixes:
- fix bug in build_macos_sh that preventing running of tests when
  cross-compiling for x86_64 on arm64;
- fix CI to build x86_64 macOS package on an x86_64 runner as the
  x86_64 Java and Python tests will not run via Rosetta
Create libktx project (Create libktx project #1071) (6765255) (@MarkCallow)

Move the libktx build from the root CMakeLists.txt to its own in the
lib directory. Although still within KTX-Software, the new libktx
project CMakeLists.txt can be used as either a sub-project of
KTX-Software or as a standalone project to build just libktx.

This has been done due to both direct requests, such as
How do I integrate building (just) libktx(_read) into my own software? #995 and
indirect requests such as complaints that the root CMakeLists is too
complicated. The effort has led to some useful cleanup and better
modularization.

The following FEATURE options have been moved to the libktx project and
consequently renamed with a LIBKTX prefix:
- LIBKTX_FEATURE_KTX1
- LIBKTX_FEATURE_KTX2
- LIBKTX_FEATURE_VK_UPLOAD
- LIBKTX_FEATURE_GL_UPLOAD
- LIBKTX_FEATURE_ETC_UNPACK
These options have been duplicated in the libktx project so they can be
set when it is the top-level project:
- LIBKTX_EMBED_BITCODE
- LIBKTX_WERROR
When libktx is used as a sub-project, they are set from the similarly
named KTX-Software options.

Add a workflow to test configuring and building a standalone libktx.

Along the way, fixed a bug, that caused configurations in the linux.yml
workflow that were supposed to incorporate OpenCL to not do so. However
it is not possible to run the tests on those configurations as the
Actions runners report the cpu type as "generic" so Portable OpenCL
(POCL) can't figure out what to do.

Also along the way, update the ignore lists in all the workflow files to
include newer workflows files.
ktx create: add premultiply alpha option (ktx create: add premultiply alpha option #1049) (83d84dc) (@jiangzhhhh)
- Add alpha pre-multiply function to image.hpp.
- Update base Texture load test to check for pre-multiplied textures
  and add a sample to the tests.

JS Bindings

Remove --rec2020 flag and add range mapping functionality to ktx create and ktx extract (Remove --rec2020 flag and add range mapping functionality to ktx create and ktx extract #1157) (20211a2) (@ViNeek)

This PR fixes Improve handling of KTXmapRange metadata #1142 and fixes Remove --rec2020 option; set encoder param automatically from the DFD values #1127.

For Remove --rec2020 option; set encoder param automatically from the DFD values #1127, it removes the flag from ktx create and ktx encode and
makes sure that the profile is automatically inferred from the loaded
EXR file.

For Improve handling of KTXmapRange metadata #1142 It adds 3 knew flags to ktx create, namely,
map-range-auto, map-range-offset and map-range-scale to be used
for mapping of floating point values in HDR formats.

ktx extract is also updated to handle inverse mapping of values when
the KTXmapRange key/value pair is present in a KTX2 file.

Currenlty, offset and scale are not used for the alpha channel.
Currently, range mapping only works with floating point data types and
the new HDR formats.
Improved HDR support (Improved HDR support #1124) (35d9f8d) (@ViNeek)

Fixes Implement KTXmapRange #1122, Add an early out to ktxTexture2_TranscodeBasis when outputFormat is ASTC_HDR_4x4 and the texture format is UASTC_HDR_4X4 #1119, Use NxN consistently for format size in tokens #1120 and Crash when transcoding UASTC HDR 6x6i to ASTC HDR 6x6 #1125.
HDR Support for libktx and tools (HDR Support for libktx and tools #1100) (c0a32ef) (@ViNeek)

The pull request adds initial support for HDR data in libktx and tools

In particular,
1. The CLI ktx tool is updated so that:
- the ktx info command supports UASTC HDR payload formats as
  defined in the KTX Specification.
- the ktx validate command implements new validation clauses related
  to the UASTC HDR payload formats
- the ktx encode command now accepts uastc-hdr-4x4 and
  uastc-hdr-6x6i as codec strings.
- These codecs require the input file format to be either
  R16G16B16_SFLOAT or R16G16B16A16_SFLOAT.
- the ktx create command when the encode parameter is used,
  accepts uastc-hdr-4x4 and uastc-hdr-6x6i for the codec
  parameter
- if the input is raw, these codecs require the format parameter to be
  either R16G16B16_SFLOAT or R16G16B16A16_SFLOAT;
- if the input is not raw, the input files must be EXR with half-float
  data type
- the ktx transcode supports the two new codecs for input files:
- uastc-hdr-4x4 inputs must accept three targets: rgba16f,
  astc-hdr-4x4, and bc6hu
- uastc-hdr-6x6i inputs must accept three targets: rgba16f,
  astc-hdr-6x6, and bc6hu
- if an input file is neither of these two formats, the targets are
  rejected,
- the ktx extract command supports the two new codecs for input files
- uastc-hdr-4x4 inputs may be extracted as raw, or transcoded as in
  ktx transcode
- uastc-hdr-6x6i inputs require transcoding as in ktx transcode
  when used with this command
- the ktx compare command, when used with UASTC HDR 4x4 or UASTC
  HDR 6x6 data and pixel comparison is requested, the image is
  transcoded to uncompressed half-float values prior to comparison
1. The existing JavaScript bindings is updated to support the new
  functionality, specifically transcoding of UASTC HDR payloads
Incidentally fixes Option to build tools could be more visible #1109.
Required changes to work with basis_universal release 1.60+. (ac2edf1) (@MarkCallow)
- Stop direct inclusion of sources. Use their cmake project to build the
  library as a subproject.
- Adapt to renamed functions.
- Update reference files for changed encoder results.
Unrelated but necessary fixes:
- fix bug in build_macos_sh that preventing running of tests when
  cross-compiling for x86_64 on arm64;
- fix CI to build x86_64 macOS package on an x86_64 runner as the
  x86_64 Java and Python tests will not run via Rosetta

Java Bindings

Update Java bindings for HDR support (Update Java bindings for HDR support #1147) (459c0a9) (@javagl)

The PR HDR Support for libktx and tools #1100 added HDR
support.

This PR updates the Java bindings accordingly so fixes Add HDR support to Java binding #1144.

What it does:
- Adds the UASTC_HDR_6X6_INTERMEDIATE supercompression scheme enum
  value
- Adds the RGBA_HALF/ASTC_HDR_4x4_RGBA/ASTC_HDR_6x6_RGBA transcode
  format enum values
- Adds a new KtxBasisCodec class, corresponding to the codec enum, as
  requested in a review
  comment
- Adds the new fields that have been added to ktxBasisParams (like
  uastcHDRUltraQuant etc) to the KtxBasisParams class
- (Minor corresponding cleanups)
- Wires the new fields to the native side accordingly, e.g.
  initialize
  and fills the native
  struct
- Adds native versions of the
  KTX_API ktx_bool_t KTX_APIENTRY ktxTexture1_IsTranscodable(ktxTexture1* This);
  functions (for KtxTexture1 and KtxTexture2)
- Adds getColorModel, getTransferFunction, isHDR.
- Adds a couple of tests.
HDR Support for libktx and tools (HDR Support for libktx and tools #1100) (c0a32ef) (@ViNeek)

The pull request adds initial support for HDR data in libktx and tools

In particular,
1. The CLI ktx tool is updated so that:
- the ktx info command supports UASTC HDR payload formats as
  defined in the KTX Specification.
- the ktx validate command implements new validation clauses related
  to the UASTC HDR payload formats
- the ktx encode command now accepts uastc-hdr-4x4 and
  uastc-hdr-6x6i as codec strings.
- These codecs require the input file format to be either
  R16G16B16_SFLOAT or R16G16B16A16_SFLOAT.
- the ktx create command when the encode parameter is used,
  accepts uastc-hdr-4x4 and uastc-hdr-6x6i for the codec
  parameter
- if the input is raw, these codecs require the format parameter to be
  either R16G16B16_SFLOAT or R16G16B16A16_SFLOAT;
- if the input is not raw, the input files must be EXR with half-float
  data type
- the ktx transcode supports the two new codecs for input files:
- uastc-hdr-4x4 inputs must accept three targets: rgba16f,
  astc-hdr-4x4, and bc6hu
- uastc-hdr-6x6i inputs must accept three targets: rgba16f,
  astc-hdr-6x6, and bc6hu
- if an input file is neither of these two formats, the targets are
  rejected,
- the ktx extract command supports the two new codecs for input files
- uastc-hdr-4x4 inputs may be extracted as raw, or transcoded as in
  ktx transcode
- uastc-hdr-6x6i inputs require transcoding as in ktx transcode
  when used with this command
- the ktx compare command, when used with UASTC HDR 4x4 or UASTC
  HDR 6x6 data and pixel comparison is requested, the image is
  transcoded to uncompressed half-float values prior to comparison
1. The existing JavaScript bindings is updated to support the new
  functionality, specifically transcoding of UASTC HDR payloads
Incidentally fixes Option to build tools could be more visible #1109.
Remove legacy tools (Remove legacy tools #1110) (05b0e02) (@MarkCallow)
- Remove legacy tools, documentation and references to them.
- Reorganize and normalize the names of still needed test images (now
  under tests/resources).
- Rewrite genktx2 script to generate needed .ktx2 resources using ktx
  suite.
- Fix missing features and bugs in suite discovered when rewriting
  genktx2:
  - Fix default imageio scanline reader to only buffer and rescale a
    scanline's worth of pixels.
  - Add channel add/remove functionality to default scanline reader
    as ktx create always requests 4 channels.
  - Fix ImageT::yflip to not attempt to yflip a 1 row image thus not
    crash.
  - Add listing file support to ktx create so multiple input files names
    can be provided as a list in another file
  - Fix so sample qualifierLinear does not cause sameUnitAllChannels not
    to be set.
- Fix unit tests to compile with c++20 and simplify file handling by
  using std::filesystem.
  - texturetests, transcodetests, streamtests & threadtests now use
    std::format. This PR works around GCC 11's (the GCC version on
    Ubuntu 22.04 CI runners) lack of support for std::format by using
    fmt::format in that case.
Required changes to work with basis_universal release 1.60+. (ac2edf1) (@MarkCallow)
- Stop direct inclusion of sources. Use their cmake project to build the
  library as a subproject.
- Adapt to renamed functions.
- Update reference files for changed encoder results.
Unrelated but necessary fixes:
- fix bug in build_macos_sh that preventing running of tests when
  cross-compiling for x86_64 on arm64;
- fix CI to build x86_64 macOS package on an x86_64 runner as the
  x86_64 Java and Python tests will not run via Rosetta
Create libktx project (Create libktx project #1071) (6765255) (@MarkCallow)

Move the libktx build from the root CMakeLists.txt to its own in the
lib directory. Although still within KTX-Software, the new libktx
project CMakeLists.txt can be used as either a sub-project of
KTX-Software or as a standalone project to build just libktx.

This has been done due to both direct requests, such as
How do I integrate building (just) libktx(_read) into my own software? #995 and
indirect requests such as complaints that the root CMakeLists is too
complicated. The effort has led to some useful cleanup and better
modularization.

The following FEATURE options have been moved to the libktx project and
consequently renamed with a LIBKTX prefix:
- LIBKTX_FEATURE_KTX1
- LIBKTX_FEATURE_KTX2
- LIBKTX_FEATURE_VK_UPLOAD
- LIBKTX_FEATURE_GL_UPLOAD
- LIBKTX_FEATURE_ETC_UNPACK
These options have been duplicated in the libktx project so they can be
set when it is the top-level project:
- LIBKTX_EMBED_BITCODE
- LIBKTX_WERROR
When libktx is used as a sub-project, they are set from the similarly
named KTX-Software options.

Add a workflow to test configuring and building a standalone libktx.

Along the way, fixed a bug, that caused configurations in the linux.yml
workflow that were supposed to incorporate OpenCL to not do so. However
it is not possible to run the tests on those configurations as the
Actions runners report the cpu type as "generic" so Portable OpenCL
(POCL) can't figure out what to do.

Also along the way, update the ignore lists in all the workflow files to
include newer workflows files.

Python Bindings

Bump default version number. (Bump default version number. #1161) (6c474d8) (@MarkCallow)

Various other issues were encountered and fixed while checking the
version number related changes.
1. Fix -a option of mkversion. It did not visit lib/src and ended
  with an error due to a misplaced fi.
2. Fix RE in ktx convert that resulted in an extra space in an edited
  KTXwriterScParams when the original zcmp option had a parameter.
3. Fix ktxTexture2_IsHDR which was only checking for a FLOAT qualifier
  on DFD samples for the ASTC color model. Add a test for it.
Fixes Update default version when major version is updated #1112.
Remove --rec2020 flag and add range mapping functionality to ktx create and ktx extract (Remove --rec2020 flag and add range mapping functionality to ktx create and ktx extract #1157) (20211a2) (@ViNeek)

This PR fixes Improve handling of KTXmapRange metadata #1142 and fixes Remove --rec2020 option; set encoder param automatically from the DFD values #1127.

For Remove --rec2020 option; set encoder param automatically from the DFD values #1127, it removes the flag from ktx create and ktx encode and
makes sure that the profile is automatically inferred from the loaded
EXR file.

For Improve handling of KTXmapRange metadata #1142 It adds 3 knew flags to ktx create, namely,
map-range-auto, map-range-offset and map-range-scale to be used
for mapping of floating point values in HDR formats.

ktx extract is also updated to handle inverse mapping of values when
the KTXmapRange key/value pair is present in a KTX2 file.

Currenlty, offset and scale are not used for the alpha channel.
Currently, range mapping only works with floating point data types and
the new HDR formats.
Expose HDR support in Python binding (Expose HDR support in Python binding #1150) (5444378) (@MarkCallow)

Fixes Add HDR support to Python binding #1145.

Additional fixes:
- Adds num_layers property that was curiously missing.
- Exposes ktxTexture[12]_IsHDR in the c API.
- Reformats documentation comments for UASTC HDR ktxBasisParams to
  reduce line width.
CMake improvements for installing and dependencies (CMake improvements for installing and dependencies #1133) (8b925f2) (@MarkCallow)
- Handle installation of KHR/khr_df.h for KTX-Software in KTX-Software
  (lib/CMakeLists.txt) avoiding some confusion and making installation
  in a framework possible.
- Use add_lib_dependency macro to add dfdutils dependency to libktx and
  remove unnecessary PUBLIC export.
- Use FILE_SETs for installation of both dfdutils and libktx include
  files to handle the KHR subdirectory, with a workaround for framework
  installation.
- Up the cmake minimum version to 3.23 in both dfdutils CMakeLists and
  lib CMakeLists.txt This is so
  - FILE_SET can be used
  - KTX-Software can override options settings with ordinary variables
    thus hiding unnecessary DFDUTILS options from the CMake GUI.
- Add option to turn off dfdutils docs build so lib/CMakeLists.txt can
  do so.
- Update dfdutils install to install library and dfd.h in addition to
  KHR/khr_df.h. This is behind an option so the KTX-Software build can
  turn it off.
- Include GNUInstallDirs to get proper values for CMAKE_INSTALL_.
- Normalize the indentation in dfdutils/CMakeLists.txt.
- Improve command clarity.
cmake --build ... --target install and the installable packages have
been tested on all 3 desktop platforms and the framework in the iOS .zip
file and content of the Android .zip file have been verified. All have
the expected content.

Fixes khr_df.h is not included in the install packages #1121. Fixes Don't configure dfdutils docs target when building KTX-Software #1123.
Improved HDR support (Improved HDR support #1124) (35d9f8d) (@ViNeek)

Fixes Implement KTXmapRange #1122, Add an early out to ktxTexture2_TranscodeBasis when outputFormat is ASTC_HDR_4x4 and the texture format is UASTC_HDR_4X4 #1119, Use NxN consistently for format size in tokens #1120 and Crash when transcoding UASTC HDR 6x6i to ASTC HDR 6x6 #1125.
HDR Support for libktx and tools (HDR Support for libktx and tools #1100) (c0a32ef) (@ViNeek)

The pull request adds initial support for HDR data in libktx and tools

In particular,
1. The CLI ktx tool is updated so that:
- the ktx info command supports UASTC HDR payload formats as
  defined in the KTX Specification.
- the ktx validate command implements new validation clauses related
  to the UASTC HDR payload formats
- the ktx encode command now accepts uastc-hdr-4x4 and
  uastc-hdr-6x6i as codec strings.
- These codecs require the input file format to be either
  R16G16B16_SFLOAT or R16G16B16A16_SFLOAT.
- the ktx create command when the encode parameter is used,
  accepts uastc-hdr-4x4 and uastc-hdr-6x6i for the codec
  parameter
- if the input is raw, these codecs require the format parameter to be
  either R16G16B16_SFLOAT or R16G16B16A16_SFLOAT;
- if the input is not raw, the input files must be EXR with half-float
  data type
- the ktx transcode supports the two new codecs for input files:
- uastc-hdr-4x4 inputs must accept three targets: rgba16f,
  astc-hdr-4x4, and bc6hu
- uastc-hdr-6x6i inputs must accept three targets: rgba16f,
  astc-hdr-6x6, and bc6hu
- if an input file is neither of these two formats, the targets are
  rejected,
- the ktx extract command supports the two new codecs for input files
- uastc-hdr-4x4 inputs may be extracted as raw, or transcoded as in
  ktx transcode
- uastc-hdr-6x6i inputs require transcoding as in ktx transcode
  when used with this command
- the ktx compare command, when used with UASTC HDR 4x4 or UASTC
  HDR 6x6 data and pixel comparison is requested, the image is
  transcoded to uncompressed half-float values prior to comparison
1. The existing JavaScript bindings is updated to support the new
  functionality, specifically transcoding of UASTC HDR payloads
Incidentally fixes Option to build tools could be more visible #1109.
Remove legacy tools (Remove legacy tools #1110) (05b0e02) (@MarkCallow)
- Remove legacy tools, documentation and references to them.
- Reorganize and normalize the names of still needed test images (now
  under tests/resources).
- Rewrite genktx2 script to generate needed .ktx2 resources using ktx
  suite.
- Fix missing features and bugs in suite discovered when rewriting
  genktx2:
  - Fix default imageio scanline reader to only buffer and rescale a
    scanline's worth of pixels.
  - Add channel add/remove functionality to default scanline reader
    as ktx create always requests 4 channels.
  - Fix ImageT::yflip to not attempt to yflip a 1 row image thus not
    crash.
  - Add listing file support to ktx create so multiple input files names
    can be provided as a list in another file
  - Fix so sample qualifierLinear does not cause sameUnitAllChannels not
    to be set.
- Fix unit tests to compile with c++20 and simplify file handling by
  using std::filesystem.
  - texturetests, transcodetests, streamtests & threadtests now use
    std::format. This PR works around GCC 11's (the GCC version on
    Ubuntu 22.04 CI runners) lack of support for std::format by using
    fmt::format in that case.
Required changes to work with basis_universal release 1.60+. (ac2edf1) (@MarkCallow)
- Stop direct inclusion of sources. Use their cmake project to build the
  library as a subproject.
- Adapt to renamed functions.
- Update reference files for changed encoder results.
Unrelated but necessary fixes:
- fix bug in build_macos_sh that preventing running of tests when
  cross-compiling for x86_64 on arm64;
- fix CI to build x86_64 macOS package on an x86_64 runner as the
  x86_64 Java and Python tests will not run via Rosetta
Create libktx project (Create libktx project #1071) (6765255) (@MarkCallow)

Move the libktx build from the root CMakeLists.txt to its own in the
lib directory. Although still within KTX-Software, the new libktx
project CMakeLists.txt can be used as either a sub-project of
KTX-Software or as a standalone project to build just libktx.

This has been done due to both direct requests, such as
How do I integrate building (just) libktx(_read) into my own software? #995 and
indirect requests such as complaints that the root CMakeLists is too
complicated. The effort has led to some useful cleanup and better
modularization.

The following FEATURE options have been moved to the libktx project and
consequently renamed with a LIBKTX prefix:
- LIBKTX_FEATURE_KTX1
- LIBKTX_FEATURE_KTX2
- LIBKTX_FEATURE_VK_UPLOAD
- LIBKTX_FEATURE_GL_UPLOAD
- LIBKTX_FEATURE_ETC_UNPACK
These options have been duplicated in the libktx project so they can be
set when it is the top-level project:
- LIBKTX_EMBED_BITCODE
- LIBKTX_WERROR
When libktx is used as a sub-project, they are set from the similarly
named KTX-Software options.

Add a workflow to test configuring and building a standalone libktx.

Along the way, fixed a bug, that caused configurations in the linux.yml
workflow that were supposed to incorporate OpenCL to not do so. However
it is not possible to run the tests on those configurations as the
Actions runners report the cpu type as "generic" so Portable OpenCL
(POCL) can't figure out what to do.

Also along the way, update the ignore lists in all the workflow files to
include newer workflows files.

Build Scripts and CMake files

Fix syntax error. (ba74b8b) (@MarkCallow)
Force primary CTS platform for testing. (368132f) (@MarkCallow)

This is a hack. If it is decided to keep this feature it needs to be
done properly, e.g. by passing an argument from the manual workflow
to the those it is using.
Add explanatory note. (0bb8a0b) (@MarkCallow)
Bump default version number. (Bump default version number. #1161) (6c474d8) (@MarkCallow)

Various other issues were encountered and fixed while checking the
version number related changes.
1. Fix -a option of mkversion. It did not visit lib/src and ended
  with an error due to a misplaced fi.
2. Fix RE in ktx convert that resulted in an extra space in an edited
  KTXwriterScParams when the original zcmp option had a parameter.
3. Fix ktxTexture2_IsHDR which was only checking for a FLOAT qualifier
  on DFD samples for the ASTC color model. Add a test for it.
Fixes Update default version when major version is updated #1112.
Fix build issues (Fix build issues #1160) (f2d222d) (@MarkCallow)
1. Suppress what looks to be a bogus stringop-overflow warning from GCC,
  observed with both versions 13 and 15.
2. Change outdated SSE and OPENCL option names to current names so they
  are acted on properly.
Given the issues being fixed here, I am unable to understand why our CI
builds have been green.
Remove --rec2020 flag and add range mapping functionality to ktx create and ktx extract (Remove --rec2020 flag and add range mapping functionality to ktx create and ktx extract #1157) (20211a2) (@ViNeek)

This PR fixes Improve handling of KTXmapRange metadata #1142 and fixes Remove --rec2020 option; set encoder param automatically from the DFD values #1127.

For Remove --rec2020 option; set encoder param automatically from the DFD values #1127, it removes the flag from ktx create and ktx encode and
makes sure that the profile is automatically inferred from the loaded
EXR file.

For Improve handling of KTXmapRange metadata #1142 It adds 3 knew flags to ktx create, namely,
map-range-auto, map-range-offset and map-range-scale to be used
for mapping of floating point values in HDR formats.

ktx extract is also updated to handle inverse mapping of values when
the KTXmapRange key/value pair is present in a KTX2 file.

Currenlty, offset and scale are not used for the alpha channel.
Currently, range mapping only works with floating point data types and
the new HDR formats.
Set link option only for Emscripten. (Set link option only for Emscripten. #1153) (cbdc1a6) (@MarkCallow)
Fix escaping of underbars in variable names (e2e6d46) (@MarkCallow)

so it only happens if the name is not in a backquoted section.
Reinstate ktxtools_mainpage. (4ffa3f0) (@MarkCallow)

Fix issues in its content.
Fix validation warning for VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL c… (Fix validation warning for VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL c… #1148) (2914abe) (@MarkCallow)

…ase.

For the VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL case of
setImageLayout, where dstAccessMask is VK_ACCESS_SHADER_READ_BIT,
settingdestStageFlags to VK_PIPELINE_STAGE_ALL_COMMANDS_BIT is
invalid usage and is flagged by the validator in recent Vulkan SDKs.
Change dstStageFlags for this case to
VK_PIPELINE_STAGE_ALL_GRAPHICS_BIT | VK_PIPELINE_STAGE_COMPUTE_SHADER_BIT.

Fixes Using 'ktxTexture_VkUpload' with an image layout of 'VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL' causes an validation error. #1092.

Includes completely unrelated fixes for warnings that are new in
Emscripten 5.0.3 so that CI builds are successful.
- Set -Wno-experimental to disable compile- and link-time warnings that
  sdl3 is still experimental.
- Change EMSCRIPTEN pre-processor macro to __EMSCRIPTEN__ to stop
  deprecation warnings.
Remove dead code. (535c77d) (@MarkCallow)
CMake improvements for installing and dependencies (CMake improvements for installing and dependencies #1133) (8b925f2) (@MarkCallow)
- Handle installation of KHR/khr_df.h for KTX-Software in KTX-Software
  (lib/CMakeLists.txt) avoiding some confusion and making installation
  in a framework possible.
- Use add_lib_dependency macro to add dfdutils dependency to libktx and
  remove unnecessary PUBLIC export.
- Use FILE_SETs for installation of both dfdutils and libktx include
  files to handle the KHR subdirectory, with a workaround for framework
  installation.
- Up the cmake minimum version to 3.23 in both dfdutils CMakeLists and
  lib CMakeLists.txt This is so
  - FILE_SET can be used
  - KTX-Software can override options settings with ordinary variables
    thus hiding unnecessary DFDUTILS options from the CMake GUI.
- Add option to turn off dfdutils docs build so lib/CMakeLists.txt can
  do so.
- Update dfdutils install to install library and dfd.h in addition to
  KHR/khr_df.h. This is behind an option so the KTX-Software build can
  turn it off.
- Include GNUInstallDirs to get proper values for CMAKE_INSTALL_.
- Normalize the indentation in dfdutils/CMakeLists.txt.
- Improve command clarity.
cmake --build ... --target install and the installable packages have
been tested on all 3 desktop platforms and the framework in the iOS .zip
file and content of the Android .zip file have been verified. All have
the expected content.

Fixes khr_df.h is not included in the install packages #1121. Fixes Don't configure dfdutils docs target when building KTX-Software #1123.
Add HDR support to vkloadtests (Add HDR support to vkloadtests #1130) (dcc4346) (@MarkCallow)

Invoke with --hdr to get an R16G16B16 HDR rendering surface.
- Add support for transcoding the new HDR formats.
- Add a sample in each of UASTC HDR 4x4 and UASTC HDR 6x6i.
HDR Support for libktx and tools (HDR Support for libktx and tools #1100) (c0a32ef) (@ViNeek)

The pull request adds initial support for HDR data in libktx and tools

In particular,
1. The CLI ktx tool is updated so that:
- the ktx info command supports UASTC HDR payload formats as
  defined in the KTX Specification.
- the ktx validate command implements new validation clauses related
  to the UASTC HDR payload formats
- the ktx encode command now accepts uastc-hdr-4x4 and
  uastc-hdr-6x6i as codec strings.
- These codecs require the input file format to be either
  R16G16B16_SFLOAT or R16G16B16A16_SFLOAT.
- the ktx create command when the encode parameter is used,
  accepts uastc-hdr-4x4 and uastc-hdr-6x6i for the codec
  parameter
- if the input is raw, these codecs require the format parameter to be
  either R16G16B16_SFLOAT or R16G16B16A16_SFLOAT;
- if the input is not raw, the input files must be EXR with half-float
  data type
- the ktx transcode supports the two new codecs for input files:
- uastc-hdr-4x4 inputs must accept three targets: rgba16f,
  astc-hdr-4x4, and bc6hu
- uastc-hdr-6x6i inputs must accept three targets: rgba16f,
  astc-hdr-6x6, and bc6hu
- if an input file is neither of these two formats, the targets are
  rejected,
- the ktx extract command supports the two new codecs for input files
- uastc-hdr-4x4 inputs may be extracted as raw, or transcoded as in
  ktx transcode
- uastc-hdr-6x6i inputs require transcoding as in ktx transcode
  when used with this command
- the ktx compare command, when used with UASTC HDR 4x4 or UASTC
  HDR 6x6 data and pixel comparison is requested, the image is
  transcoded to uncompressed half-float values prior to comparison
1. The existing JavaScript bindings is updated to support the new
  functionality, specifically transcoding of UASTC HDR payloads
Incidentally fixes Option to build tools could be more visible #1109.
Fix installation of test ktx files to resources on Windows. (Fix installation of test ktx files to resources on Windows. #1117) (d58b713) (@MarkCallow)

ensure_runtime_dependencies_win was still trying copy a whole directory
which is no longer true after the reorganization.
Remove legacy tools (Remove legacy tools #1110) (05b0e02) (@MarkCallow)
- Remove legacy tools, documentation and references to them.
- Reorganize and normalize the names of still needed test images (now
  under tests/resources).
- Rewrite genktx2 script to generate needed .ktx2 resources using ktx
  suite.
- Fix missing features and bugs in suite discovered when rewriting
  genktx2:
  - Fix default imageio scanline reader to only buffer and rescale a
    scanline's worth of pixels.
  - Add channel add/remove functionality to default scanline reader
    as ktx create always requests 4 channels.
  - Fix ImageT::yflip to not attempt to yflip a 1 row image thus not
    crash.
  - Add listing file support to ktx create so multiple input files names
    can be provided as a list in another file
  - Fix so sample qualifierLinear does not cause sameUnitAllChannels not
    to be set.
- Fix unit tests to compile with c++20 and simplify file handling by
  using std::filesystem.
  - texturetests, transcodetests, streamtests & threadtests now use
    std::format. This PR works around GCC 11's (the GCC version on
    Ubuntu 22.04 CI runners) lack of support for std::format by using
    fmt::format in that case.
Add convert command (Add convert command #1099) (0eaebb0) (@MarkCallow)

For converting ktx v1 files.

Fixes formatting error in encode man page (doxygen).
Add lock around transcoder initialization (Add lock around transcoder initialization #1098) (964acdc) (@MarkCallow)

Fixes Concurrency issues when call ktxTexture2_TranscodeBasis in multithreading. #1087.

Add threadtests - though unsure how useful they are.

Update all libktx tests for c++20 as new tests need it for std::barrier.

Fixes basisu_c_binding build when ktx_read target is not included in
build.

Big thanks to @vmwalker for reporting the problem and providing the fix.
Combine lib dependencies into static libktx on all desktop platforms (Combine lib dependencies into static libktx on all desktop platforms #1090) (5a07bc6) (@MarkCallow)

Previously this was only done on macOS - using libtool. Changed to
a simple, though hard to find, cross-platform way to do this via CMake.

Add CI test of build and use of a static library.

Remove macOS 13 build from CI as these runner images have been
retired from GitHub Actions.
Fix use of libktx project as subproject outside of KTX-Software (Fix use of libktx project as subproject outside of KTX-Software #1089) (7f0f889) (@MarkCallow)

The Fix
- Always include cmake/codesign.cmake and cmake/cputypetest.cmake.
  Add include_guard() to them to prevent multiple inclusion.
- Add host project for testing sub-project use and update workflow
  to build and run it and libktx.
Other Changes
- Add options to select building of full or read-only libktx.
- Fix macOS build when CODE_SIGN_IDENTITY not set. Fixes
  both libktx and the larger KTX-Software project.
Fixes Unable to use lib/CMakeLists.txt directly because of PROJECT_IS_TOP_LEVEL CMake variable #1083
mkversion fix: make RE treat $(pwd) value literally. (mkversion fix: make RE treat $(pwd) value literally. #1088) (998a719) (@MarkCallow)

Fixes #1071 broke builds in directories with characters that contain special characters #1084.
Revise mkversion invocation (Revise mkversion invocation #1085) (2aa509d) (@dg0yt)

This is an untested rewrite of the line invoking mkversion on
Windows, based on past vcpkg experience. (The current port version 4.4.2
doesn't invoke mkversion.)

The original "\"...\" ...." fails for some configurations.
It is a single CMake list item, with embedded quotes which go into a
build system rule which may or may not get the inner quotes correctly
for the actual invocation of the command.

The rule of thumb is:
- Quote for CMake.
  There is only outer quotes for items in a cmake list.
- Do not assume a particular shell for commands executed by the build
  system.
  There are different generators for different build systems.
  With ninja build files, commands may be executed via a shell or
  directly, depending on the system.
  With any type of inner quotes, portability will be limited.
The new line is a CMake list of command and items, with quoting for
CMake when items can expand with special characters inside.
(Now this newest version contains an embedded CMake variable
${MKV_VERSION_OPT} which I didn't quote because I assume it is of list
type, i.e. potentially expanding to multiple command line arguments.)

Fix creating static ktx_read convenience lib (Fix creating static ktx_read convenience lib #1081) (4b46cda) (@dg0yt)

Fixes "duplicate member name" warnings:

[130/148] : [...] libtool -static -o
/Users/vcpkg/Data/b/ktx/x64-osx-rel/libktx\_read.a
/Users/vcpkg/Data/b/ktx/x64-osx-rel/libktx.a
/Users/vcpkg/Data/b/ktx/x64-osx-rel/external/astc-encoder/Source/libastcenc-avx2-static.a

/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/libtool:
warning for architecture: x86\_64h duplicate member name
'astcenc\_averages\_and\_directions.cpp.o' from '/Users/vcpkg/Data/b/ktx/x64-osx-rel/external/astc-encoder/Source/libastcenc-avx2-static.a(astcenc\_averages\_and\_directions.cpp.o)'
and
'/Users/vcpkg/Data/b/ktx/x64-osx-rel/libktx.a(astcenc\_averages\_and\_directions.cpp.o)'

Update basis_universal (Update basis_universal #1080) (422f501) (@MarkCallow)

master, in the fork from which we pull basis_universal, has been updated
to basis_universal master as of 2025.11.22, which includes all our
previous warning fixes. The changes there have been merged to the
cmake_fixes branch we pull from.

Also included:
- fix: change basis-related cmake option names to match those in
  basis_universal and update workflows to set the new names;
- fix: deploy x86_64 package, broken when build moved to x86_64 runner;
- enhancement: apply changes resulting from a review of the cmake_fixes
  PR for basis_universal.
git subrepo clone --branch=cmake_fixes --force https://github.com/KhronosGroup/basis\_universal.git external/basis_universal

subrepo:
subdir: "external/basis_universal"
merged: "daf79c6ee"
upstream:
origin: "https://github.com/KhronosGroup/basis\_universal.git"
branch: "cmake_fixes"
commit: "daf79c6ee"
git-subrepo:
version: "0.4.9"
origin: "https://github.com/MarkCallow/git-subrepo.git"
commit: "4f60dd7"

Fixes FMT dependency in ktx is causing a lot issues while compiling. #1079.
Required changes to work with basis_universal release 1.60+. (ac2edf1) (@MarkCallow)
- Stop direct inclusion of sources. Use their cmake project to build the
  library as a subproject.
- Adapt to renamed functions.
- Update reference files for changed encoder results.
Unrelated but necessary fixes:
- fix bug in build_macos_sh that preventing running of tests when
  cross-compiling for x86_64 on arm64;
- fix CI to build x86_64 macOS package on an x86_64 runner as the
  x86_64 Java and Python tests will not run via Rosetta
Add KTX_FEATURE_JS option controlling whether ktx_js[_read] are built. (Add KTX_FEATURE_JS option controlling whether ktx_js[_read] are built. #1073) (952d74f) (@kring)

(Reopening Add KTX_FEATURE_JS option controlling whether ktx_js[_read] are built. #1072, now targeting main)

Adds a new CMake option called KTX_FEATURE_JS. It defaults to ON, but
when set to OFF, ktx_js and ktx_js_read are not built, even under
Emscripten.

My use-case for this is compiling Cesium for
Unity for the web. Compiling
Unity applications to WebAssembly requires using Unity's version of
Emscripten, which is quite old (v3.1.39), and is not able to compile
ktx_js successfully. This isn't really worth fixing because the
JavaScript bindings aren't used in this context anyway. KTX
functionality is only called from Emscripten'd native code, never from
regular JS code.

So with this low-impact PR, it's easy to disable this unnecessary part
of the KTX software suite in order to get a successful build.

The slightly bigger picture here is to then expose this via a vcpkg
feature flag.
Create libktx project (Create libktx project #1071) (6765255) (@MarkCallow)

Move the libktx build from the root CMakeLists.txt to its own in the
lib directory. Although still within KTX-Software, the new libktx
project CMakeLists.txt can be used as either a sub-project of
KTX-Software or as a standalone project to build just libktx.

This has been done due to both direct requests, such as
How do I integrate building (just) libktx(_read) into my own software? #995 and
indirect requests such as complaints that the root CMakeLists is too
complicated. The effort has led to some useful cleanup and better
modularization.

The following FEATURE options have been moved to the libktx project and
consequently renamed with a LIBKTX prefix:
- LIBKTX_FEATURE_KTX1
- LIBKTX_FEATURE_KTX2
- LIBKTX_FEATURE_VK_UPLOAD
- LIBKTX_FEATURE_GL_UPLOAD
- LIBKTX_FEATURE_ETC_UNPACK
These options have been duplicated in the libktx project so they can be
set when it is the top-level project:
- LIBKTX_EMBED_BITCODE
- LIBKTX_WERROR
When libktx is used as a sub-project, they are set from the similarly
named KTX-Software options.

Add a workflow to test configuring and building a standalone libktx.

Along the way, fixed a bug, that caused configurations in the linux.yml
workflow that were supposed to incorporate OpenCL to not do so. However
it is not possible to run the tests on those configurations as the
Actions runners report the cpu type as "generic" so Portable OpenCL
(POCL) can't figure out what to do.

Also along the way, update the ignore lists in all the workflow files to
include newer workflows files.
ktx create: add premultiply alpha option (ktx create: add premultiply alpha option #1049) (83d84dc) (@jiangzhhhh)
- Add alpha pre-multiply function to image.hpp.
- Update base Texture load test to check for pre-multiplied textures
  and add a sample to the tests.
Determine tools version at build time not config time (Determine tools version at build time not config time #1068) (0b3fad6) (@MarkCallow)

Otherwise the tools version may not reflect recent changes in
the worktree.

Add comments pointing to docs for git describe output.

This discussion was created from the release v5.0.0-rc1.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

v5.0.0-rc1 #1163

Uh oh!

{{title}}

Uh oh!

The Fix

Other Changes

The Fix

Other Changes

Replies: 0 comments

Select a reply

Uh oh!

v5.0.0-rc1 #1163

Uh oh!

MarkCallow May 1, 2026 Maintainer

Summary

New Features in v5.0

Tools

libktx functions

Notable Fixes in v5.0

Known Issues

Acknowledgements

Commits since v4.4.2 (by part with details)

libktx

The Fix

Other Changes

Tools

JS Bindings

Java Bindings

Python Bindings

Build Scripts and CMake files

The Fix

Other Changes

Replies: 0 comments

MarkCallow
May 1, 2026
Maintainer