v4.4.0

[MarkCallow]

Summary

• Aligns with [KTX Specification](https://registry.khronos.org/KTX/specs/2.0 ktxspec.v2.html) Revision 4 and Khronos Data Format Specification version 1.4.
• Adds new tools and features to the KTX suite. Of particular note is
  ktx compare.
• Has a largely rewritten JavaScript binding which gives access to read and
  write functionality of libktx and includes an expanded test suite.
• Has a refactored and greatly improved Java binding thanks to @javagl.

With the new tools and features the KTX tool suite now provides a superset of the functionality found in the legacy tools with the exception of ktx2ktx2. The legacy tools, except ktx2ktx2 will be removed in Release 4.5. Adjust your workflows accordingly.

New Features in 4.4

Command Line Tools Suite

Two tools have been added to the ktx suite in v4.4 and two tools have significant new functionality.

Tool	Description	Equivalent lgeacy tool
ktx compare	Compare KTX2 files	-
ktx deflate	Deflate a KTX2 file with Zlib or Zstd	ktxsc
ktx create	Added --assign-texcoord-origin, --convert-texcoord-origin, --normalize, --scale	toktx
ktx encode	Can now encode a KTX2 file to an ASTC format	ktxsc

libktx functions

• ktxTexture2_DecodeAstc decodes an ASTC format texture to an uncompressed format.

• ktxLoadOpenGL so an application can explicitly make the library load the GL function pointers, that it uses, using an application provided GetProcAddress function. Use of this is recommended on any platform but it is most helpful on platforms such as Fedora where generic function queries are unable to find OpenGL functions.

• ktxTexture2_Write* and ktxTexture[12]_Destroy functions are now part of the public API.

Notable Changes in 4.4

Alignment with KTX Specification Revision 4

• Transfer function handling in ktx create has been revamped to support the flexibility of using almost any transfer function with non-sRGB formats that was introduced in Revision 1 of the KTX Specification.

• ktx create now allows setting a primaries value of "none", KTX_DF_PRIMARIES_UNSPECIFIED, which is required for certain formats in Revision 4 of the KTX Specification.

• libktx now retains the values of the bytesPlane[0-7] fields in the DFD when supercompressing files as required following alignment of KTX Specification Revision 4 with Khronos Data Format Specification version 1.4. It will load supercompressed files with either zero or non-zero bytesPlane values. ktx validator will report a warning on files with zero bytesPlane values.

Command Line Tools Suite

The following functionality has changed.

Tool	Changed
ktx create	--assign-oetf → --assign-tf*, --convert-oetf → --convert-tf.* --compare-ssim and --compare-psnr can be used when encoding to ASTC. Non-raw input images can be resized by specifying the desired size with --width or --height.
ktx encode	--compare-ssim and --compare-psnr can be used when encoding to ASTC.

* Options renamed due to revamped functionality.

Javascript binding

The Javascript binding has been almost completely rewritten to support the read and write functionality of libktx. A test suite has been added that also serves as an example of how to use the functions.

• The name of the factory function for creating the ktx module has been changed from LIBKTX to createKtxModule (and createKtxReadModule). The old name is provided as an alias. Be aware that using the alias corresponds to createKtxModule so you will get the full functionality.
• The ktx prefixes have been removed from the only existing class that had it, ktxTexture. None of the new classes have a prefix. ktcTexture is provided as an alias to texture. Recommended usage is to assign the module instance returned by the factory function to window.ktx or other ktx variable making the prefixes unnecessary.
• Enumerator names are now the same as the libktx names minus the ktx{,_} prefixes and _e suffixes for consistency and to make it easier to recall what the JS name will be.
• Similarly constant names are the libktx names minus all prefixes as an enum or class name must be used when referencing them in JS. For example KTX_PACK_UASTC_LEVEL_FASTEST is simply LEVEL_FASTEST and is referenced in JS as pack_uastc_flag_bits.LEVEL_FASTEST.

Java binding

The Java binding has been greatly improved by a large refactoring focussing on error handling, documentation, completeness, and usability improvements ( #886 ). This includes several breaking changes. Not all breaking changes can be listed here explicitly. But in all cases, it should be easy for clients to update their code to the new state. The most important changes for the Java Wrapper are listed below.

• Made deflateZstd, deflateZLIB, and createFromMemory available in the KtxTexture2 class.
• Fixed a bug where the KtxBasisParams#setInputSwizzle function caused data corruption.
• Increased the consistency of the naming and handling of constants:
  • all constant names are UPPER_SNAKE_CASE, omitting common prefixes;
  • classes that define constants offer a stringFor function that returns the string representation of a constant;
  • the KtxCreateStorage class was renamed to KtxTextureCreateStorage;
  • the KtxPackUASTCFlagBits class was renamed to KtxPackUastcFlagBits.
• Improved error handling:
  • when functions receive a parameter that is null, then this will no longer crash the JVM, but will throw a NullPointerException;
  • when setInputSwizzle receives invalid arguments, then an IllegalArgumentException will be thrown;
  • when one of the create... family of functions causes an error, meaning that the respective KtxTexture2 object cannot be created, then a KtxException will be thrown.
• Added JavaDocs, and enabled the generation of JavaDocs as part of the Maven build process.
• Internal improvements (like JNI field caching, and avoiding calling JNI functions with pending exceptions).
• Supercompression functions exposed in the binding.
• `ktxTexture_GLUpload function exposed in the binding.

Massive thanks to @javagl for this work.

ASTC Encoder

• Updated to 5.2.0.

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 the ktx create tool, or use the --resize feature of the old toktx tool 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 the new ktx validate tool.

• Basis Universal encoding results (both ETC1S/LZ and UASTC) are non-deterministic across platforms. Results are valid but level sizes and data will differ slightly. See issue #60 in the basis_universal repository.

• UASTC RDO results differ from run to run unless multi-threading or RDO multi-threading is disabled. In toktx use --threads 1 for the former or --uastc_rdo_m for the latter. As with the preceeding issue 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.

Changes since v4.3.2 (by part)

libktx

• Fix memory leaks. (Fix memory leaks. #1003) (0f0e065) (@MarkCallow)

• Fix issues with ktxLoadOpenGL documentation. (0c1922d) (@MarkCallow)

• Fix incorrect data types in libktx_mainpage.md examples (Fix incorrect data types in libktx_mainpage.md examples #992) (b35a478) (@Lephar)

• Set bytes planes to non-zero for supercompressed formats. (Set bytes planes to non-zero for supercompressed formats. #988) (d4cad5f) (@MarkCallow)

• Fix memory leak. (Fix memory leak. #991) (e0cf193) (@MarkCallow)

• Add normalise option to command create (Add normalise option to command create #977) (2f69183) (@wasimabbas-arm)

• Make ktxTexture2_Write functions public. (Make ktxTexture2_Write functions public. #985) (b330a2e) (@MarkCallow)

• ktx create: Update transfer function handling (ktx create: Update transfer function handling #982) (7356c0d) (@MarkCallow)

• Add vkformat checks to ktxTexture2_DecodeAstc (Add vkformat checks to ktxTexture2_DecodeAstc #967) (aa6af91) (@wasimabbas-arm)

• Fix ktxTexture2_DecodeAstc error returns and document them. (Fix ktxTexture2_DecodeAstc error returns and document them. #961) (b619004) (@MarkCallow)

• Fix ktxTexture2_DecodeAstc documentation. (c16537c) (@MarkCallow)

• Encode astc support (Encode astc support #952) (d1ad5cd) (@wasimabbas-arm)

• Expose ktxTexture2_GetImageOffset. (Expose ktxTexture2_GetImageOffset. #954) (99c324f) (@MarkCallow)

• JNI improvements (JNI improvements #886) (2ee4332) (@javagl)

• Add clang-format support (Add clang-format support #913) (110f049) (@MathiasMagnus)

• Fix issues newly flagged by Doxygen 1.11.0 (Fix issues newly flagged by Doxygen 1.11.0 #925) (19c2f75) (@MarkCallow)

• docs: clarify pointer lifetimes for ktxTexture_SetImageFromMemory (docs: clarify pointer lifetimes for ktxTexture_SetImageFromMemory #917) (b2cad1a) (@mjrister)

• Update R16G16_S10_5_NV format to R16G16_SFIXED5_NV (Update R16G16_S10_5_NV format to R16G16_SFIXED5_NV #921) (7f3adf1) (@MarkCallow)

• Add JS bindings for full libktx (Add JS bindings for full libktx #874) (562509c) (@aqnuep)

• Fixes for strnlen and unicode string literals (Fix for strnlen #916) (759f49d) (@rGovers)

• INVALID_OPERATION if generateMipmaps set when block compressing. (e5585e3) (@MarkCallow)

• Expose ktxTexture[12]_Destroy. (7132048) (@MarkCallow)

• Move self-hosted dependencies to external folder (Move self-hosted dependencies to external folder #909) (5fc739c) (@MathiasMagnus)

• Fix various issues surfaced by fuzzer (Fix various issues surfaced by fuzzer #900) (6063e47) (@florczyk-fb)

• Expose supercompression functions via JNI (Expose supercompression functions via JNI #879) (7abffbd) (@javagl)

• Add function for app to explicitly make libktx load its GL function pointers. (Add function for app to explicitly make libktx load its GL function pointers. #894) (0bca55a) (@MarkCallow)

• Miscellaneous fixes (Miscellaneous fixes #893) (e31b3e5) (@MarkCallow)

• Minor documentation fixes (Minor documentation fixes #890) (e7d2d71) (@javagl)

• Merge ktx compare to main (Merge ktx compare to main #868) (6fcd95a) (@aqnuep)

Tools

• Add resize and scale support to create Add resize and scale support to create #999 (75d8d04) (@MarkCallow)

• Update for new commands and features. (350a631) (@MarkCallow)

• Set bytes planes to non-zero for supercompressed formats. (Set bytes planes to non-zero for supercompressed formats. #988) (d4cad5f) (@MarkCallow)

• Add normalise option to command create (Add normalise option to command create #977) (2f69183) (@wasimabbas-arm)

• ktx create: Update transfer function handling (ktx create: Update transfer function handling #982) (7356c0d) (@MarkCallow)

• Add --{assign.convert}-texcoord-origin option to ktx create (Add --{assign.convert}-texcoord-origin option to ktx create #976) (91e61d6) (@MarkCallow)

• fix: INSTALL_RPATH for linux using lib64 (fix: INSTALL_RPATH for linux using lib64 #975) (ba97833) (@MinGyuJung1996)

• Add vkformat checks to ktxTexture2_DecodeAstc (Add vkformat checks to ktxTexture2_DecodeAstc #967) (aa6af91) (@wasimabbas-arm)

• Fix crash on loading EXR 2.0 input (Fix crash on loading EXR 2.0 input #973) (7a8cd47) (@MathiasMagnus)

• Encode astc support (Encode astc support #952) (d1ad5cd) (@wasimabbas-arm)

• Always use same method to set language version. (Always use same method to set language version. #947) (3439daf) (@MarkCallow)

• Fix: ensure ktxdiff runs on macOS and enable CTS in Linux arm64 CI. (Fix: ensure ktxdiff runs on macOS and enable CTS in Linux arm64 CI. #946) (ffb9152) (@MarkCallow)

• Fixing build on Ubuntu 24.04 w/ Clang 20 (Fixing build on Ubuntu 24.04 w/ Clang 20 #936) (33813d7) (@Honeybunch)

• Fix issues newly flagged by Doxygen 1.11.0 (Fix issues newly flagged by Doxygen 1.11.0 #925) (19c2f75) (@MarkCallow)

• Update R16G16_S10_5_NV format to R16G16_SFIXED5_NV (Update R16G16_S10_5_NV format to R16G16_SFIXED5_NV #921) (7f3adf1) (@MarkCallow)

• Update astc-encoder to 4.8.0 (subrepo pull). (Update astc-encoder to 4.8.0. #918) (7fb646c) (@MarkCallow)

• Move self-hosted dependencies to external folder (Move self-hosted dependencies to external folder #909) (5fc739c) (@MathiasMagnus)

• Fix man page issues introduced by PR Refactor common options #817 (Fix man page issues introduced by PR #817 #903) (0d1ebc1) (@MarkCallow)

• Refactor common options (Refactor common options #817) (0a16df8) (@wasimabbas-arm)

• Add ktx deflate command (Add ktx deflate command #896) (da97911) (@MarkCallow)

• Fixes to CLI error messages (Fixes to CLI error messages #891) (eac4b98) (@aqnuep)

• Minor documentation fixes (Minor documentation fixes #890) (e7d2d71) (@javagl)

• Merge ktx compare to main (Merge ktx compare to main #868) (6fcd95a) (@aqnuep)

• Clarify description of --format argument for create when used with --encode (Clarify description of --format argument for create when used with --encode #873) (5414bd0) (@aqnuep)

JS Bindings

• Align naming (Align naming #938) (a3cf1d5) (@MarkCallow)

• Remove long ago deprecated items. (Remove long ago deprecated items. #926) (b1a115f) (@MarkCallow)

• Update R16G16_S10_5_NV format to R16G16_SFIXED5_NV (Update R16G16_S10_5_NV format to R16G16_SFIXED5_NV #921) (7f3adf1) (@MarkCallow)

• Add JS bindings for full libktx (Add JS bindings for full libktx #874) (562509c) (@aqnuep)

• Move self-hosted dependencies to external folder (Move self-hosted dependencies to external folder #909) (5fc739c) (@MathiasMagnus)

Java Binding

• Java swizzle and constant fixes (Java swizzle and constant fixes #972) (3038f7c) (@javagl)

• Add GL upload function to Java interface (Add GL upload function to Java interface #959) (bd8ae31) (@javagl)

• Fix JNI function name for getDataSizeUncompressed (Fix JNI function name for getDataSizeUncompressed #957) (f3902db) (@javagl)

• JNI improvements (JNI improvements #886) (2ee4332) (@javagl)

• Update R16G16_S10_5_NV format to R16G16_SFIXED5_NV (Update R16G16_S10_5_NV format to R16G16_SFIXED5_NV #921) (7f3adf1) (@MarkCallow)

• Expose supercompression functions via JNI (Expose supercompression functions via JNI #879) (7abffbd) (@javagl)

• Properly convert Java char to C char in inputSwizzle (Properly convert Java char to C char in inputSwizzle #876) (cc56485) (@javagl)

Python Binding

• Set up workflow to build just the documentation. (Set up workflow to build just the documentation. #989) (a45ffed) (@MarkCallow)

• Workaround removal of Python virtualenv in Actions runner 20240929.1. (Attempt to workaround venv failure in Actions runner 20240929.1. #950) (e304057) (@MarkCallow)

• Bump setuptools from 69.0.2 to 70.0.0 in /interface/python_binding (Bump setuptools from 69.0.2 to 70.0.0 in /interface/python_binding #930) (f389108) (@dependabot[bot])

• Update R16G16_S10_5_NV format to R16G16_SFIXED5_NV (Update R16G16_S10_5_NV format to R16G16_SFIXED5_NV #921) (7f3adf1) (@MarkCallow)

---

This discussion was created from the release v4.4.0.

[Raffaello]

@MarkCallow Thank you very much! 🙂

[MarkCallow]

You are welcome.

[oliverzx]

Hey,

the assets contain tarball releases for Linux but only a NSIS installer for Windows ? To be integrate into a build pipeline, this would need to be installed or extracted via 7-zip. Is there a reason to not also publish a zip for the windows assets ?

The vcpkg package would work but apprently it doesn't contain include/ktxvulkan.h or symbols for i.e. ktxTexture_GetVkFormat. Is that intended ?

Thanks

[Raffaello]

Hey,

the assets contain tarball releases for Linux but only a NSIS installer for Windows ? To be integrate into a build pipeline, this would need to be installed or extracted via 7-zip. Is there a reason to not also publish a zip for the windows assets ?

The vcpkg package would work but apprently it doesn't contain include/ktxvulkan.h or symbols for i.e. ktxTexture_GetVkFormat. Is that intended ?

Thanks

Hey @oliverzx not sure if you knew it already, but you could try to use these parameters to install in the CI pipeline:

• /S

-ref: https://nsis.sourceforge.io/Docs/Chapter3.html#installerusagecommon

[Honeybunch]

Vulkan support in the vcpkg package is behind the vulkan feature. If you make sure to use that feature the headers and symbols you're looking for should be there. If not, that's unexpected

[oliverzx]

Hey @oliverzx not sure if you knew it already, but you could try to use these parameters to install in the CI pipeline:

* `/S`

-ref: https://nsis.sourceforge.io/Docs/Chapter3.html#installerusagecommon

Oh, I was looking for such arguments yesterday but haven't seen them. facepalm
Will go the vcpkg route but good to know. Thanks.