New Features in Version 4.3

Command Line Tools Suite

v4.3 contains a new suite of command line tools accessed via an umbrella ktx command.

Equivalent old tools will be removed in a subsequent release soon.

Some features of the old tools are not currently available in the new equivalent.

The command-line syntax and semantics differ from the old tools including, but not limited to:

• KTX 1.0 files are not supported by the new tools.

• Words in multi-word option names are connected with - instead of _.

• Individual option names may differ between the old and new tools.

• The ktx validate tool may be stricter than ktx2check or otherwise differ in behavior, as the new tool enforces all rules of the KTX 2.0 specification. In addition, all new tools that accept KTX 2.0 files as input will be validated in a similar fashion as they would be with the ktx validate tool and will fail on the first specification rule violation, if there is one. It also has the option to output the validation results in human readable text format or in JSON format (both formatted and minified options are available), as controlled by the --format command-line option.

• The ktx validate tool also supports validating KTX 2.0 files against the additional restrictions defined by the KHR_texture_basisu extension. Use the --gltf-basisu command-line option to verify glTF and WebGL compatibility.

• The new ktx info tool produces a unified and complete output of all metadata in KTX 2.0 files and can provide output in human readable text format or in JSON format (both formatted and minified options are available), as controlled by the --format command-line option.

• The source repository also includes the JSON schemas that the JSON outputs of the ktx info and ktx validate tools comply to.

• The ktx create tool takes an explicit Vulkan format argument (--format) instead of inferring the format based on the provided input files as toktx, and thus doesn't perform any implicit color-space conversions except gamma 2.2 to sRGB. Use the --assign-oetf, --convert-oetf, --assign-primaries, and the new --convert-primaries for fine grained control over color-space interpretation and conversion.

• The ktx create tool does not support resizing or scaling like toktx, and, in general, does not perform any image transformations except the optional color-space conversion and mipmap generation options. Users should resize input images to the appropriate resolution before converting them to KTX 2.0 files.

• The ktx create and ktx extract tools consume and produce, respectively, image file formats that best suit the used Vulkan format. In general, barring special cases, 8-bit and 16-bit normalized integer formats are imported from and exported to PNG files, while integer and floating point formats are imported from and exported to EXR files based on predefined rules. This may be extended in the future using additional command line options and in response to support for other image file formats.

• The new tools and updated libktx support ZLIB supercompression besides the BasisLZ and Zstd supercompression schemes supported previously.

Please refer to the manual pages or use the --help command-line option for further details on the options available and associated semantics for each individual command.

Thanks to @aqnuep and @VaderY of RasterGrid for their excellent work on the new tool suite.

Python Binding

A Python binding for libktx has been added. Applications written in Python can now use libktx functions. The package can be installed via pip install pyktx[==4.3.0]. Huge thanks to @ShukantPal.

Notable Changes since v4.3.1

• The ktx tool suite and libktx have been made compliant with Revision 3 of the KTX v2 specification:
  • typeSize for formats with _mPACKxx suffix has been fixed. It is now xx/8.
  • YCbCr 2-plane 4:4:4 formats recently added to Vulkan have been prohibited.
  • A8B8G8R8_PACK32 and R16G16_S10_5_NV formats are now allowed.

Notable Changes in v4.3

• libktx has been made much more robust to errors in KTX files.
• libktx now validates checksums when present in a Zstd data stream.
• libktx has two new error codes it can return: KTX_DECOMPRESS_LENGTH_ERROR and KTX_DECOMPRESS_CHECKSUM_ERROR.
• All tools and libktx now correctly process on all platforms utf8 file names
  with multi-byte code-points. Previously such names did not work on Windows.
• The Vulkan texture uploader can now optionally be used with an extenal memory allocator such as VulkanMemoryAllocator.

Known Issues

• Some image bits in output files encoded to ASTC, ETC1S/Basis-LZ or UASTC on arm64 devices may differ from those encoded from the same input images on x86_64 devices. The differences will not be human visible and will only show up in bit-exact comparisons.

• 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.1 (by part)

libktx

• Flesh out support for VK_FORMAT_R16G16_S10_5_NV. (#864) (42dfae5) (@MarkCallow)

• Allow A8B8G8R8 formats. (#861) (5ac5cf1) (@MarkCallow)

• Fix recreateBytesPlane0 and add test (#856) (83b6386) (@MarkCallow)

• Fix mPACKn formats (#858) (dacd993) (@aqnuep)

• Prevent warning if VK_NO_PROTOTYPES is already defined (#855) (d2d63f0) (@jherico)

Tools

• Allow A8B8G8R8 formats. (#861) (5ac5cf1) (@MarkCallow)

• Fix mPACKn formats (#858) (dacd993) (@aqnuep)

Java Wrapper

• Allow A8B8G8R8 formats. (#861) (5ac5cf1) (@MarkCallow)

Version 4.3.1

Changes since v4.3.0 (by part)

Tools

• Fix lingering KTXwriterScParams metadata from encode/transcode inputs (#852) (d3010bd) (@aqnuep)

Version 4.3.0

Changes since v4.3.0-beta1 (by part)

libktx

• Rename branch to match upstream. (aaba104) (@MarkCallow)

• Add option to enable mkvk targets (VkFormat-related file generation). (#840) (e77a531) (@MarkCallow)

Tools

• Report error on excess filenames (#843) (c32d99a) (@aqnuep)

• Fix error message typo (#837) (7dedd7e) (@aqnuep)

• Fix creating 3D textures and add KTXwriterScParams support to transcode (#833) (01d220c) (@aqnuep)

• Move buffer size check to base class. (dab91cf) (@MarkCallow)

Version 4.3.0-beta1

Changes since v4.3.0-alpha3 (by part)

libktx

• git subrepo push lib/dfdutils (ab9c277) (@MarkCallow)

• Reenable build of loadtest apps on Windows arm64 CI (#802) (6c131f7) (@MarkCallow)

• Utf-8/unicode support in legacy tools and lib. (#800) (1c5dc9c) (@MarkCallow)

• Do not redefine NOMINMAX (#801) (6dbb246) (@corporateshark)

• libktx: update ktxTexture2_setImageFromStream to allow setting the entire level's data in one call (#794) (88fc7a6) (@AlexRouSg)

• Update dfdutils-included vulkan_core.h. (#783) (9c223d9) (@MarkCallow)

• Support for A8 and A1B5G5R5 formats (#785) (eeac620) (@aqnuep)

• Major non-content documentation fixes. (#773) (e6a6a3b) (@MarkCallow)

• Fix vendor-specific/tied memory property flag detection (#771) (a100217) (@toomuchvoltage)

• Return KTX_NOT_FOUND when a GPU proc is not found. (#770) (aeca5e6) (@MarkCallow)

• Support for external allocators: (#748) (6856fdb) (@toomuchvoltage)

• Fix ktx_strncasecmp (#741) (1ae04f8) (@VaderY)

• Use correct counter for indexing sample. (#739) (3153e94) (@MarkCallow)

Tools

• Disallow ASTC options when format is not ASTC (#809) (d3ef5ed) (@aqnuep)

• Remove unnecessary nullptr checks. ...

New Features in Version 4.3

Command Line Tools Suite

v4.3.0 contains a new suite of command line tools accessed via an umbrella ktx command.

Equivalent old tools will be removed in a subsequent release soon.

Some features of the old tools are not currently available in the new equivalent.

The command-line syntax and semantics differ from the old tools including, but not limited to:

• KTX 1.0 files are not supported by the new tools.

• Words in multi-word option names are connected with - instead of _.

• Individual option names may differ between the old and new tools.

• The ktx validate tool may be stricter than ktx2check or otherwise differ in behavior, as the new tool enforces all rules of the KTX 2.0 specification. In addition, all new tools that accept KTX 2.0 files as input will be validated in a similar fashion as they would be with the ktx validate tool and will fail on the first specification rule violation, if there is one. It also has the option to output the validation results in human readable text format or in JSON format (both formatted and minified options are available), as controlled by the --format command-line option.

• The ktx validate tool also supports validating KTX 2.0 files against the additional restrictions defined by the KHR_texture_basisu extension. Use the --gltf-basisu command-line option to verify glTF and WebGL compatibility.

• The new ktx info tool produces a unified and complete output of all metadata in KTX 2.0 files and can provide output in human readable text format or in JSON format (both formatted and minified options are available), as controlled by the --format command-line option.

• The source repository also includes the JSON schemas that the JSON outputs of the ktx info and ktx validate tools comply to.

• The ktx create tool takes an explicit Vulkan format argument (--format) instead of inferring the format based on the provided input files as toktx, and thus doesn't perform any implicit color-space conversions except gamma 2.2 to sRGB. Use the --assign-oetf, --convert-oetf, --assign-primaries, and the new --convert-primaries for fine grained control over color-space interpretation and conversion.

• The ktx create tool does not support resizing or scaling like toktx, and, in general, does not perform any image transformations except the optional color-space conversion and mipmap generation options. Users should resize input images to the appropriate resolution before converting them to KTX 2.0 files.

• The ktx create and ktx extract tools consume and produce, respectively, image file formats that best suit the used Vulkan format. In general, barring special cases, 8-bit and 16-bit normalized integer formats are imported from and exported to PNG files, while integer and floating point formats are imported from and exported to EXR files based on predefined rules. This may be extended in the future using additional command line options and in response to support for other image file formats.

• The new tools and updated libktx support ZLIB supercompression besides the BasisLZ and Zstd supercompression schemes supported previously.

Please refer to the manual pages or use the --help command-line option for further details on the options available and associated semantics for each individual command.

Thanks to @aqnuep and @VaderY of RasterGrid for their excellent work on the new tool suite.

Python Binding

A Python binding for libktx has been added. Applications written in Python can now use libktx functions. The package can be installed via pip install pyktx[==4.3.0]. Huge thanks to @ShukantPal.

Changes

• libktx has been made much more robust to errors in KTX files.
• libktx now validates checksums when present in a Zstd data stream.
• libktx has two new error codes it can return: KTX_DECOMPRESS_LENGTH_ERROR and KTX_DECOMPRESS_CHECKSUM_ERROR.
• All tools and libktx now correctly process on all platforms utf8 file names
  with multi-byte code-points. Previously such names did not work on Windows.
• The Vulkan texture uploader can now optionally be used with an extenal memory allocator such as VulkanMemoryAllocator.

Known Issues

• Some image bits in output files encoded to ASTC, ETC1S/Basis-LZ or UASTC on arm64 devices may differ from those encoded from the same input images on x86_64 devices. The differences will not be human visible and will only show up in bit-exact comparisons.

• 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.0 (by part)

Tools

• Fix lingering KTXwriterScParams metadata from encode/transcode inputs (#852) (d3010bd) (@aqnuep)

Version 4.3.0

Changes since v4.3.0-beta1 (by part)

libktx

• Rename branch to match upstream. (aaba104) (@MarkCallow)

• Add option to enable mkvk targets (VkFormat-related file generation). (#840) (e77a531) (@MarkCallow)

Tools

• Report error on excess filenames (#843) (c32d99a) (@aqnuep)

• Fix error message typo (#837) (7dedd7e) (@aqnuep)

• Fix creating 3D textures and add KTXwriterScParams support to transcode (#833) (01d220c) (@aqnuep)

• Move buffer size check to base class. (dab91cf) (@MarkCallow)

Version 4.3.0-beta1

Changes since v4.3.0-alpha3 (by part)

libktx

• git subrepo push lib/dfdutils (ab9c277) (@MarkCallow)

• Reenable build of loadtest apps on Windows arm64 CI (#802) (6c131f7) (@MarkCallow)

• Utf-8/unicode support in legacy tools and lib. (#800) (1c5dc9c) (@MarkCallow)

• Do not redefine NOMINMAX (#801) (6dbb246) (@corporateshark)

• libktx: update ktxTexture2_setImageFromStream to allow setting the entire level's data in one call (#794) (88fc7a6) (@AlexRouSg)

• Update dfdutils-included vulkan_core.h. (#783) (9c223d9) (@MarkCallow)

• Support for A8 and A1B5G5R5 formats (#785) (eeac620) (@aqnuep)

• Major non-content documentation fixes. (#773) (e6a6a3b) (@MarkCallow)

• Fix vendor-specific/tied memory property flag detection (#771) (a100217) (@toomuchvoltage)

• Return KTX_NOT_FOUND when a GPU proc is not found. (#770) (aeca5e6) (@MarkCallow)

• Support for external allocators: (#748) (6856fdb) (@toomuchvoltage)

• Fix ktx_strncasecmp (#741) (1ae04f8) (@VaderY)

• Use correct counter for indexing sample. (#739) (3153e94) (@MarkCallow)

Tools

• Disallow ASTC options when format is not ASTC (#809) (d3ef5ed) (@aqnuep)

• Remove unnecessary nullptr checks. (#807) (072a4eb) (@MarkCallow)

• Set tools and tests rpath on Linux. (#804) (928612a) (@MarkCallow)

• Utf-8/unicode support in legacy tools and lib. (#800) (1c5dc9c) (@MarkCallow)

• Support building of loadtest apps with locally installed dependencies (#799) (84ee59d) (@MarkCallow)

• Update dfdutils-included vulkan_core.h. (#783) (9c223d9) (@MarkCallow)

• Add UTF-8 filename support on Windows to ktxtools (#788) (7b6eab5) (@aqnuep)

• Support for A8 and A1B5G5R5 formats (#785) (eeac620) (@aqnuep)

• KTXwriterScParams support (#779) (f8691ff) (@aqnuep)

• Use -- in doc. to get -- not n-dash in output. (#767) (7247900) (@MarkCallow)

• Document convert_primaries option in toktx. (#765) (3049f5b) (@MarkCallow)

• Do target_type changes only in toktx (#757) (2cf053c) (@MarkCallow)

• Add support for fewer components in input files (#755) (adcccf1) (@aqnuep)

• Fix --convert-primaries (#753) (e437ec4) (@aqnuep)

• Fix legacy app input from pipes on Windows. (#749) (3e7fd0a) (@MarkCallow...

New Features in Version 4.3.0

Command Line Tools Suite

v4.3.0 contains a new suite of command line tools accessed via an umbrella ktx command.

Equivalent old tools will be removed in a subsequent release soon.

Some features of the old tools are not currently available in the new equivalent.

The command-line syntax and semantics differ from the old tools including, but not limited to:

• KTX 1.0 files are not supported by the new tools.

• Words in multi-word option names are connected with - instead of _.

• Individual option names may differ between the old and new tools.

• The ktx validate tool may be stricter than ktx2check or otherwise differ in behavior, as the new tool enforces all rules of the KTX 2.0 specification. In addition, all new tools that accept KTX 2.0 files as input will be validated in a similar fashion as they would be with the ktx validate tool and will fail on the first specification rule violation, if there is one. It also has the option to output the validation results in human readable text format or in JSON format (both formatted and minified options are available), as controlled by the --format command-line option.

• The ktx validate tool also supports validating KTX 2.0 files against the additional restrictions defined by the KHR_texture_basisu extension. Use the --gltf-basisu command-line option to verify glTF and WebGL compatibility.

• The new ktx info tool produces a unified and complete output of all metadata in KTX 2.0 files and can provide output in human readable text format or in JSON format (both formatted and minified options are available), as controlled by the --format command-line option.

• The source repository also includes the JSON schemas that the JSON outputs of the ktx info and ktx validate tools comply to.

• The ktx create tool takes an explicit Vulkan format argument (--format) instead of inferring the format based on the provided input files as toktx, and thus doesn't perform any implicit color-space conversions except gamma 2.2 to sRGB. Use the --assign-oetf, --convert-oetf, --assign-primaries, and the new --convert-primaries for fine grained control over color-space interpretation and conversion.

• The ktx create tool does not support resizing or scaling like toktx, and, in general, does not perform any image transformations except the optional color-space conversion and mipmap generation options. Users should resize input images to the appropriate resolution before converting them to KTX 2.0 files.

• The ktx create and ktx extract tools consume and produce, respectively, image file formats that best suit the used Vulkan format. In general, barring special cases, 8-bit and 16-bit normalized integer formats are imported from and exported to PNG files, while integer and floating point formats are imported from and exported to EXR files based on predefined rules. This may be extended in the future using additional command line options and in response to support for other image file formats.

• The new tools and updated libktx support ZLIB supercompression besides the BasisLZ and Zstd supercompression schemes supported previously.

Please refer to the manual pages or use the --help command-line option for further details on the options available and associated semantics for each individual command.

Python Binding

A Python binding for libktx has been added. Applications written in Python can now use libktx functions. Huge thanks to @ShukantPal. Please download the appropriate pyktx package from Releases as publishing to PyPI is not yet established.

Changes

• libktx has been made much more robust to errors KTX files.
• libktx now validates checksums when present in a Zstd data stream.
• libktx has two new error codes it can return: KTX_DECOMPRESS_LENGTH_ERROR and KTX_DECOMPRESS_CHECKSUM_ERROR.
• All tools and libktx now correctly process on all platforms utf8 file names
  with multi-byte code-points. Previously such names did not work on Windows.
• The Vulkan texture uploader can now optionally be used with an extenal memory allocator such as VulkanMemoryAllocator.

Known Issues

• Some image bits in output files encoded to ASTC, ETC1S/Basis-LZ or UASTC on arm64 devices may differ from those encoded from the same input images on x86_64 devices. The differences will not be human visible and will only show up in bit-exact comparisons.

• 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.0-alpha3 (by part)

libktx

• git subrepo push lib/dfdutils (ab9c277) (@MarkCallow)

• Reenable build of loadtest apps on Windows arm64 CI (#802) (6c131f7) (@MarkCallow)

• Utf-8/unicode support in legacy tools and lib. (#800) (1c5dc9c) (@MarkCallow)

• Do not redefine NOMINMAX (#801) (6dbb246) (@corporateshark)

• libktx: update ktxTexture2_setImageFromStream to allow setting the entire level's data in one call (#794) (88fc7a6) (@AlexRouSg)

• Update dfdutils-included vulkan_core.h. (#783) (9c223d9) (@MarkCallow)

• Support for A8 and A1B5G5R5 formats (#785) (eeac620) (@aqnuep)

• Major non-content documentation fixes. (#773) (e6a6a3b) (@MarkCallow)

• Fix vendor-specific/tied memory property flag detection (#771) (a100217) (@toomuchvoltage)

• Return KTX_NOT_FOUND when a GPU proc is not found. (#770) (aeca5e6) (@MarkCallow)

• Support for external allocators: (#748) (6856fdb) (@toomuchvoltage)

• Fix ktx_strncasecmp (#741) (1ae04f8) (@VaderY)

• Use correct counter for indexing sample. (#739) (3153e94) (@MarkCallow)

Tools

• Disallow ASTC options when format is not ASTC (#809) (d3ef5ed) (@aqnuep)

• Remove unnecessary nullptr checks. (#807) (072a4eb) (@MarkCallow)

• Set tools and tests rpath on Linux. (#804) (928612a) (@MarkCallow)

• Utf-8/unicode support in legacy tools and lib. (#800) (1c5dc9c) (@MarkCallow)

• Support building of loadtest apps with locally installed dependencies (#799) (84ee59d) (@MarkCallow)

• Update dfdutils-included vulkan_core.h. (#783) (9c223d9) (@MarkCallow)

• Add UTF-8 filename support on Windows to ktxtools (#788) (7b6eab5) (@aqnuep)

• Support for A8 and A1B5G5R5 formats (#785) (eeac620) (@aqnuep)

• KTXwriterScParams support (#779) (f8691ff) (@aqnuep)

• Use -- in doc. to get -- not n-dash in output. (#767) (7247900) (@MarkCallow)

• Document convert_primaries option in toktx. (#765) (3049f5b) (@MarkCallow)

• Do target_type changes only in toktx (#757) (2cf053c) (@MarkCallow)

• Add support for fewer components in input files (#755) (adcccf1) (@aqnuep)

• Fix --convert-primaries (#753) (e437ec4) (@aqnuep)

• Fix legacy app input from pipes on Windows. (#749) (3e7fd0a) (@MarkCallow)

• Improve output determinism and add internal ktxdiff tool for comparing test outputs (#745) (7f67af7) (@VaderY)

• Add KTX_WERROR config option (#746) (dab32db) (@MarkCallow)

• Fix incorrect index calculations in image conversions (#735) (682f456) (@VaderY)

• Color-space and documentation related improvements for ktx create (#732) (8b12216) (@VaderY)

Java Wrapper

• Update dfdutils-included vulkan_core.h. (#783) (9c223d9) (@MarkCallow)

Version 4.3.0-alpha3

Changes since v4.3.0-alpha2 (by part)

libktx

• Improve documentation (#730) (69b1685) (@MarkCallow)

  • Rework navigation among the multiple Doxygen projects for much easier use.
  • Rename new ktx tool man pages from ktxtools\_* to ktx\_*
  • Add ktx tool mainpage based on RELEASE_NOTES info.
  • Make minor ...

Changes since v4.2.0 (by part)

libktx

• Fix memory leak of input_image in ktxTexture2_CompressAstcEx (fa1fe4d) (@null)

Version 4.2.0

Overview

v4.2.0 has few user-facing changes. Most of the work has been behind the scenes improving the build system and fixing warnings across the many supported compilers. User-facing changes are detailed below.

New Features in v4.2.0

• Install packages for GNU/Linux on Arm64 have been added.

• The Java wrapper is now included in the Windows Arm64 install package.

Significant Changes since v4.1.0

• The following behavioral changes have been made to toktx:

  • If the input PNG file has a gAMA chunk with a value 45460 the image data is now converted to the sRGB transfer function intead of just assigning sRGB as the transfer function of the output file.
  • If the gAMA chunk has a value other than 45640 or 100000 toktx will now exit with an error. Previously it used heuristics to decide whether to transform the input to linear or sRGB. Use --convert_oetf or --assign_oetf to specified the desired behavior.

• The Khronos Data Format header file KHR/khr_df.h has been added to the install packages and is included in ktx.h. A new transfer function query ktxTexture2_GetOETF_e that returns a khr_df_transfer_e replaces ktxTexture2_GetOETF that returned a ktx_uint32_t. The latter is still available for backward compatibility, A new ktxTexture2_GetColorModel_e query has been added returning a khr_df_model_e.

Known Issues in v4.2.0.

• Some image bits in output files encoded to ASTC, ETC1S/Basis-LZ or UASTC on arm64 devices may differ from those encoded from the same input images on x86_64 devices. The differences will not be human visible and will only show up in bit-exact comparisons.

• toktx will not read JPEG files with a width or height > 32768 pixels.

• toktx will not read 4-component JPEG files such as those sometimes created by Adobe software where the 4th component can be used to re-create a CMYK image.

• Users making Basisu encoded or block compressed textures for WebGL must be aware of WebGL restrictions with regard to texture size and may need to resize images appropriately using the --resize feature of toktx. In general the dimensions of block compressed textures must be a multiple of the block size and for WebGL 1.0 must be a power of 2. For portability glTF's KHR_texture_basisu extension requires texture dimensions to be a multiple of 4, the block size of the Universal texture formats.

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

Notice

• Building with Visual Studio 2015 and 2017 is no longer supported.

Changes since v4.1.0 (by part)

libktx

• Pull upstream ASTC encoder for FP option setting fixes. (#713) (8e68fe0) (@MarkCallow)

• Pull upstream ASTC for fixes building with GCC 11 for arm64, (#700) (514051c) (@MarkCallow)

• Update Vulkan SDK for macOS CI. (#688) (f57dc8f) (@MarkCallow)

• CI and Build Improvements (#687) (38f4858) (@MarkCallow)

Tools

• Pull upstream ASTC for fixes building with GCC 11 for arm64, (#700) (514051c) (@MarkCallow)

• Reimplement image input handling for toktx. (#702) (1646c4d) (@MarkCallow)

• Fix normalization when the result overflows (#701) (f81330b) (@wasimabbas-arm)

Java Wrapper

• Fix outdated references to master. (e724f18) (@MarkCallow)

• Miscellaneous CI script and build fixes (#692) (fefd4a6) (@MarkCallow)

• Remove pinned buffer list in JNI wrapper to avoid segmentation faults (#697) (9b084d5) (@ShukantPal)

Overview

v4.2.0 has few user-facing changes. Most of the work has been behind the scenes improving the build system and fixing warnings across the many supported compilers. User-facing changes are detailed below.

New Features in v4.2.0

• Install packages for GNU/Linux on Arm64 have been added.

• The Java wrapper is now included in the Windows Arm64 install package.

Significant Changes since v4.1.0

• The following behavioral changes have been made to toktx:

  • If the input PNG file has a gAMA chunk with a value 45460 the image data is now converted to the sRGB transfer function intead of just assigning sRGB as the transfer function of the output file.
  • If the gAMA chunk has a value other than 45640 or 100000 toktx will now exit with an error. Previously it used heuristics to decide whether to transform the input to linear or sRGB. Use --convert_oetf or --assign_oetf to specified the desired behavior.

• The Khronos Data Format header file KHR/khr_df.h has been added to the install packages and is included in ktx.h. A new transfer function query ktxTexture2_GetOETF_e that returns a khr_df_transfer_e replaces ktxTexture2_GetOETF that returned a ktx_uint32_t. The latter is still available for backward compatibility, A new ktxTexture2_GetColorModel_e query has been added returning a khr_df_model_e.

Known Issues in v4.2.0.

• Some image bits in output files encoded to ASTC, ETC1S/Basis-LZ or UASTC on arm64 devices may differ from those encoded from the same input images on x86_64 devices. The differences will not be human visible and will only show up in bit-exact comparisons.

• toktx will not read JPEG files with a width or height > 32768 pixels.

• toktx will not read 4-component JPEG files such as those sometimes created by Adobe software where the 4th component can be used to re-create a CMYK image.

• Users making Basisu encoded or block compressed textures for WebGL must be aware of WebGL restrictions with regard to texture size and may need to resize images appropriately using the --resize feature of toktx. In general the dimensions of block compressed textures must be a multiple of the block size and for WebGL 1.0 must be a power of 2. For portability glTF's KHR_texture_basisu extension requires texture dimensions to be a multiple of 4, the block size of the Universal texture formats.

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

Notice

• Building with Visual Studio 2015 and 2017 is no longer supported.

Changes since v4.1.0 (by part)

libktx

• Pull upstream ASTC encoder for FP option setting fixes. (#713) (8e68fe0) (@MarkCallow)

• Pull upstream ASTC for fixes building with GCC 11 for arm64, (#700) (514051c) (@MarkCallow)

• Update Vulkan SDK for macOS CI. (#688) (f57dc8f) (@MarkCallow)

• CI and Build Improvements (#687) (38f4858) (@MarkCallow)

Tools

• Pull upstream ASTC for fixes building with GCC 11 for arm64, (#700) (514051c) (@MarkCallow)

• Reimplement image input handling for toktx. (#702) (1646c4d) (@MarkCallow)

• Fix normalization when the result overflows (#701) (f81330b) (@wasimabbas-arm)

Java Wrapper

• Fix outdated references to master. (e724f18) (@MarkCallow)

• Miscellaneous CI script and build fixes (#692) (fefd4a6) (@MarkCallow)

• Remove pinned buffer list in JNI wrapper to avoid segmentation faults (#697) (9b084d5) (@ShukantPal)

New Features in v4.1.0

• ARM's ASTC encoder has been added to libktx. As a result you can now use toktx to create KTX files with ASTC encoded payloads. Thanks to @wasimabbas-arm.

• Full normal map handling has been added. 3-component normal maps can be
  converted to 2-component and the components separated into the RGB and alpha channels of ASTC, ETC1S or UASTC compressed textures. A --normalize option has been added to toktx to convert an input normal map to unit normals which are needed to allow the third component to be recreated in a shader.
  Thanks to @wasimabbas-arm.

• A Java wrapper and JNI module for libktx has been added. Thanks to @ShukantPal.

• An install package for Apple Silicon has been added.

• An install package for Windows Arm-64 has been added. Thanks to @Honeybunch.

• The formerly internal ktxStream class has been exposed enabling possibilities such as wrapping a ktxStream around a C++ stream so that textures can be created from the C++ stream's content. See sbufstream.h. Thanks to @UberLambda.

• ktx2check now verifies BasisLZ supercompression data by performing a transcode.

Significant Changes since v4.0.0

• Basis Universal has been updated to version 1.16.3.

  • The ETC1S encoder performance is now approximately 30% faster.
  • Optional OpenCL support has been added to the ETC1S encoder. Add -D SUPPORT_OPENCL when configuring the CMake build to enable it. As OpenCL may not be any faster when encoding individual files - it highly depends on your hardware - it is disabled in the default build and release packages.

• Windows install packages are now signed with an Extended Validation certificate eliminating scary warnings when starting installation.

• Textures with Depth-stencil formats are now created with DFDs and alignments matching the KTX v2 specification.

• Specifying --layers 1 to toktx now creates an array texture with 1 layer. Previously it created a non-array texture.

• Specifying --depth 1 to toktx now creates a 3d texture with depth of 1. Previously it created a 2d texture.

• --normal_map in ktxsc and toktx has been replaced by --normal_mode which converts 3-component maps to 2-component as well as optimizing the encoding. To prevent the conversion, also specify --input_swizzle rgb1.

Known Issues in v4.1.0.

• toktx will not read JPEG files with a width or height > 32768 pixels.

• toktx will not read 4-component JPEG files such as those sometimes created by Adobe software where the 4th component can be used to re-create a CMYK image.

• Users making Basisu encoded or block compressed textures for WebGL must be aware of WebGL restrictions with regard to texture size and may need to resize images appropriately using the --resize feature of toktx. In general the dimensions of block compressed textures must be a multiple of the block size and for WebGL 1.0 must be a power of 2. For portability glTF's KHR_texture_basisu extension requires texture dimensions to be a multiple of 4, the block size of the Universal texture formats.

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

Notice

• Following this release Visual Studio 2015 and 2017 will no longer be supported. The CI builds with these will be disabled. You may still be able to build with these for a while but don't rely on it.

Changes since v4.0.0 (by part)

libktx

• Fix warnings newly raised by Doxygen 1.9.6. (#676) (c5c24a4) (@MarkCallow)

• Fix new warnings from Xcode 14.2 building for macOS. (#659) (a5bbfe7) (@MarkCallow)

• fix typo in lib/info.c (#657) (784ed9a) (@simi)

• Fix mingw-w64:llvm-mingw error: unknown type name 'pthread_t' (#653) (7d57639) (@FuXiii)

• Include padding in inflatedByteLength (#647) (a64ebd4) (@MarkCallow)

• Fixing support for mingw toolchains that target the newer ucrt (#642) (0251377) (@Honeybunch)

• Document required queue properties. Fixes #627. (#639) (f4feff2) (@MarkCallow)

• Fix ktxTexture_VkUpload documentation. (691e9ca) (@MarkCallow)

• Fix: Use time.h not timex.h for __GNUC__ (a0b1806) (@MarkCallow)

• Fix gcc warnings in appendLibId. (#626) (895799d) (@MarkCallow)

• Fix warnings in appendLibId. (#625) (9bd2f9b) (@MarkCallow)

• Cherry-pick change from astcenc 4.1.0 (#623) (f8dc35f) (@solidpixel)

• Check for existing libktx version string (#620) (a2f1ac2) (@MarkCallow)

• Set isCompressed at end of CompressBasisEx. (#618) (c63b4c9) (@MarkCallow)

• Allow creation of 3d textures with --depth 1. (#610) (3a5d09a) (@MarkCallow)

• Fix newly emerged warning from clang (#608) (cd394d6) (@MarkCallow)

• Update for UASTC and ASTC. (727de5e) (@MarkCallow)

• git subrepo push lib/dfdutils (dd799a9) (@MarkCallow)

• Remove incorrect use of ktxTexture2_WriteTo... (7d91d62) (@MarkCallow)

• Regularize Tools (#594) (870b9ff) (@MarkCallow)

• Fixing build for arm64 Windows (#582) (b995ac3) (@Honeybunch)

• Update astc-encoder (#592) (a6bcd33) (@MarkCallow)

• Fix missing documentation and compile warning. (#591) (ed9e725) (@MarkCallow)

• Update astc encoder (#586) (1cb9751) (@MarkCallow)

• Release memory before early exit. (#584) (a4fddf6) (@kacprzak)

• Introduce proper vulkan initialization (#570) (bb9babc) (@rHermes)

• Using cmake's MINGW variable to detect proper ABI (#579) (a70e831) (@Honeybunch)

• Fix handling of combined depth-stencil textures (#575) (e4bf1aa) (@MarkCallow)

• Fix build on Mingw (#574) (1f07cb0) (@Honeybunch)

• Prepare Release 4.1. (#571) (4a52fe4) (@MarkCallow)

• git subrepo pull (merge) lib/astc-encoder (51f4763) (@MarkCallow)

• git subrepo pull (merge) lib/dfdutils (7c24a98) (@MarkCallow)

• git subrepo pull (merge) lib/dfdutils (c5abc16) (@MarkCallow)

• Farewell GYP. :-( (f1f04a7) (@MarkCallow)

• Miscellaneous fixes (#558) (66f6d75) (@MarkCallow)

• Fix new in clang 13.1 (Xcode13.3) warnings (#553) (b8d462b) (@MarkCallow)

• Fix non-clang warnings (#549) (4e7e40a) (@MarkCallow)

• Split each build configuration into a separate CI job. (#546) (9d1204c) (@MarkCallow)

• Update to Basis1.16.3 (#543) (c65cfd0) (@MarkCallow)

• Remove image.hpp dependency (#542) (9fde96b) (@wasimabbas-arm)

• Update to Basis 1.16.1 (#541) (cb45ead) (@MarkCallow)

• git subrepo pull (merge) lib/astc-encoder (#540) (d98aa68) (@wasimabbas-arm)

• git subrepo pull (merge) lib/astc-encoder (#537) (dbfeb82) (@wasimabbas-arm)

• Add astc perceptual mode support (#534) (57e62de) (@wasimabbas-arm)

• Improve Astc & BasisU normal map support (#493) (2d6ff94) (@wasimabbas-arm)

• git subrepo pull lib/dfdutils (5ff4811) (@MarkCallow)

• git subrepo push lib/dfdutils (ce2a461) (@MarkCallow)

• Calculate dst buffer size with ZSTD_compressBound. (#527) (81d2be5) (@MarkCallow)

• Remove extraneous token concatenation operator. (a8f4a71) (@MarkCallow)

• Fix malloc/delete pair. (0a3fe5b) (@sergeyext)

• Manually update git-subrepo parent (929c75c) (@wasimabbas-arm)

• git subrepo pull (merge) lib/astc-encoder (f5daffe) (@wasimabbas-arm)

• Fix parent commit pointer. (1a356d0) (@MarkCallow)

• git subrepo pull (merge) lib/basisu (24c9f7b) (@MarkCallow)

• Move common params out from ETC1S case. (a2ccc90) (@MarkCallow)

• Remove transferFunction from astc options (#482) (1f085d3) (@wasimabbas-arm)

• Fix leak in zstd inflation. Fixes #465. (720b6cf) (@MarkCallow)

• Support array and 3d textures. (#468) (b053253) (@MarkCallow)

• Add more astc tests (#460) (14284e7) (@wasimabbas-arm)

• Add astc support (#433) (da435de) (@wasimabbas-arm)

• Actually byte swap keyAndValueByteSize values. Fix issue #447. (0011808) (@MarkCallow)

• Add KTXmetalPixelFormat to valid list used by ktxTexture2_WriteToStream. (871f111) (@MarkCallow)

• Fix astc-encoder/.gitrepo parent after latest pull. (f99221e) (@MarkCallow)

• git subrepo pull (merge) lib/astc-encoder (6669245) (@MarkCallow)

• Fix astc-encoder/.gitrepo parent pointer. (f39b13b) (@MarkCallow)

• Fix memory leak in VkUpload (#448) (2b2b48f) (@bin)

• Fix: if ("GL_EXT_texture_sRGB") is supported,then srgb should be supported (#446) (13f1741) (@dusthand)

• git subrepo commit (merge) lib/astc-encoder (1264f86) (@MarkCallow)

• git subrepo pull (merge) lib/astc-encoder (1536966) (@MarkCallow)

• Make ktxStream public (#438) (78929f8) (@UberLambda)

• git subrepo pull (merge) lib/astc-encoder (535c883) (@MarkCallow)

• Fix mismatched malloc and delete (#440) (9d42b86) (@cperthuisoc)

• Cleanup Vulkan SDK environment variables. (354f640) (@MarkCallow)

• git subrepo pull (merge) lib/astc-encoder (3e75b6a) (@MarkCallow)

• Remove unneeded parts of astc-encoder. (360d10b) (@MarkCallow)

• git subrepo clone https://github.com/ARM-software/astc-encoder.git lib/astc-encoder (db35959) (@MarkCallow)

• Raise warning levels to /W4 & -Wall -Wextra (#418) (ca6f6e7) (@MarkCallow)

• Minor build tweaks (#407) (6a38a06) (@MarkCallow)

Tools

• Fix ktx2check handling of supercompressed files. (#646) (0057c76) (@MarkCallow)

• Fix: Remove inco...

Release Notes

Version 4.0.0

Significant Changes since Release Candidate 1

• Basis Universal has been updated to version 1.15.

• Errors in both ktx2check and ktxinfo causing bogus out of memory messages when there is no metadata or an empty value have been fixed.

• An issue in msc_basis_transcoder causing intermittent Javascript "Cannot perform Construct on a detached ArrayBuffer" errors has been fixed. NOTE: that msc_basis_transcoder is deprecated and will be replaced by the transcoder wrapper from the Basis Universal repository.

Known Issues in v4.0.0.

• toktx will not read JPEG files with a width or height > 32768 pixels.

• toktx will not read 4-component JPEG files such as those sometimes created by Adobe software where the 4th component can be used to re-create a CMYK image.

• Emscripten versions greater than 2.0.15 have an issue that causes the Javascript wrapper for libktx to fail. The downloadable package KTX-Software-4.0.0-rc1-Web-libktx.zip has been built with Emscripten 2.0.15. You only need to be aware of this if building the wrapper yourself with your own installed emsdk.

• Users making Basisu encoded or block compressed textures for WebGL must be aware of WebGL restrictions with regard to texture size and may need to resize images appropriately using the --resize feature of toktx. In general the dimensions of block compressed textures must be a multiple of the block size and, if WEBGL_compressed_texture_s3tc on WebGL 1.0 is expected to be one of the targets, then the dimensions must be a power of 2. For portability glTF's KHR_texture_basisu extension requires texture dimensions to be a multiple of 4, the block size of the Universal texture formats.

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

Changes since v4.0.0-rc1 (by part)

libktx

• Adapt for Basisu 1.15. (a0642fa) (@MarkCallow)

  • Use zstd included in basisu.
  • Regen reference images with updated ETC1S encoder and newer zstd version.

• git subrepo pull lib/basisu (c721133) (@MarkCallow)

  subrepo:
  subdir: "lib/basisu"
  merged: "5337227c"
  upstream:
  origin: "https://github.com/BinomialLLC/basis\_universal.git"
  branch: "master"
  commit: "5337227c"
  git-subrepo:
  version: "0.4.3"
  origin: "https://github.com/MarkCallow/git-subrepo.git"
  commit: "c1f1132"

• Point .gitsubrepo at correct parent. (02c43d5) (@MarkCallow)

• Minor reformat (#399) (a78c3b4) (@lexaknyazev)

• Handle PVRTC1 minimum 2 block requirement. Fixes issue #390. (#398) (2034ce7) (@MarkCallow)

• Fix: Handle metadata with empty values. (0265230) (@MarkCallow)

  Incidental to the main fix, fix memory leaks in texturetests.

• Fix: properly handle 0 length kvdata. (aee7a1c) (@MarkCallow)

• Fix error in example. (b7563ea) (@MarkCallow)

• 2 small fixes: (50000ca) (@MarkCallow)

  • Raise error in GLUpload on attempted upload of universal texture.
  • In ktx2check don't combine FLOAT & NORM when checking VK_FORMAT name.

Tools

• Copy all image attributes when resampling. (83518cd) (@MarkCallow)

• Skip mipPadding also when no sgd or kvd. Fixes #395. (#396) (fa739a2) (@MarkCallow)

• 2 small fixes: (50000ca) (@MarkCallow)

  • Raise error in GLUpload on attempted upload of universal texture.
  • In ktx2check don't combine FLOAT & NORM when checking VK_FORMAT name.

JS Wrappers

• Obtain HEAP references after resizing vectors. (5bf11d8) (@MarkCallow)

  Possible fix for issue #371.