Skip to content

v4.4.0

Latest
Latest
Compare
Choose a tag to compare
@github-actions github-actions released this 30 Mar 07:48
· 14 commits to main since this release
v4.4.0
This tag was signed with the committer’s verified signature.
MarkCallow Mark Callow
GPG key ID: 1136C9EC3F001063
Verified
Learn about vigilant mode.
beef801

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. ktxTexture 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

Tools

JS Bindings

Java Binding

Python Binding

Contributors

MarkCallow, Honeybunch, and 10 other contributors
Assets 33
Loading
2 Join discussion