KTX2 Updates: ETC1s/BasisLZ, ASTC HDR, and faster Zstd

Cargo.toml

@@ -160,6 +160,7 @@ default = [
   "smaa_luts",
   "sysinfo_plugin",
   "tonemapping_luts",
+  "zstd_native",
   "vorbis",
   "webgl2",
   "x11",
@@ -319,6 +320,9 @@ trace = ["bevy_internal/trace", "dep:tracing"]
 # Basis Universal compressed texture support
 basis-universal = ["bevy_internal/basis-universal"]
 
+# Enables compressed KTX2 UASTC texture output on the asset processor
+compressed_image_saver = ["bevy_internal/compressed_image_saver"]
+
 # BMP image format support
 bmp = ["bevy_internal/bmp"]
 
@@ -367,8 +371,11 @@ webp = ["bevy_internal/webp"]
 # For KTX2 supercompression
 zlib = ["bevy_internal/zlib"]
 
-# For KTX2 supercompression
-zstd = ["bevy_internal/zstd"]
+# For KTX2 Zstandard decompression using pure rust [ruzstd](https://crates.io/crates/ruzstd)
+zstd_rust = ["bevy_internal/zstd_rust"]
+
+# For KTX2 Zstandard decompression using [zstd](https://crates.io/crates/zstd)
+zstd_native = ["bevy_internal/zstd_native"]
 
 # FLAC audio format support
 flac = ["bevy_internal/flac"]
@@ -437,7 +444,7 @@ android_shared_stdcxx = ["bevy_internal/android_shared_stdcxx"]
 detailed_trace = ["bevy_internal/detailed_trace"]
 
 # Include tonemapping Look Up Tables KTX2 files. If everything is pink, you need to enable this feature or change the `Tonemapping` method for your `Camera2d` or `Camera3d`.
-tonemapping_luts = ["bevy_internal/tonemapping_luts", "ktx2", "zstd"]
+tonemapping_luts = ["bevy_internal/tonemapping_luts", "ktx2"]
 
 # Include SMAA Look Up Tables KTX2 Files
 smaa_luts = ["bevy_internal/smaa_luts"]
@@ -1847,6 +1854,34 @@ description = "How to configure the texture to repeat instead of the default cla
 category = "Assets"
 wasm = true
 
+[[example]]
+name = "texture_support"
+path = "examples/asset/texture_support.rs"
+doc-scrape-examples = true
+required-features = [
+  "basis-universal",
+  "bmp",
+  "dds",
+  "gif",
+  "exr",
+  "hdr",
+  "ico",
+  "jpeg",
+  "ktx2",
+  "png",
+  "pnm",
+  "qoi",
+  "tga",
+  "tiff",
+  "webp",
+]
+
+[package.metadata.example.texture_support]
+name = "Texture Support"
+description = "Demonstrates supported texture formats (KTX2 ASTC, KTX2 ETC1S, Basis, DDS, etc)"
+category = "Assets"
+wasm = false
+
 # Assets
 [[example]]
 name = "multi_asset_sync"

assets/shaders/texture2d_array_mip_material.wgsl

@@ -0,0 +1,33 @@
+#import bevy_sprite::{
+    mesh2d_vertex_output::VertexOutput,
+    mesh2d_view_bindings::view,
+}
+
+#ifdef TONEMAP_IN_SHADER
+#import bevy_core_pipeline::tonemapping
+#endif
+
+struct TextureMipMaterial {
+    texture_available: u32,
+    mip_level: f32,
+    layer_index: u32,
+}
+
+@group(2) @binding(0) var<uniform> material: TextureMipMaterial;
+@group(2) @binding(1) var texture: texture_2d_array<f32>;
+@group(2) @binding(2) var texture_sampler: sampler;
+
+@fragment
+fn fragment(
+    mesh: VertexOutput,
+) -> @location(0) vec4<f32> {
+    var output_color: vec4<f32> = vec4<f32>(0.0);
+    if (material.texture_available != 0u) {
+        output_color = textureSampleLevel(texture, texture_sampler, mesh.uv, material.layer_index, material.mip_level);
+    }
+
+#ifdef TONEMAP_IN_SHADER
+    output_color = tonemapping::tone_mapping(output_color, view.color_grading);
+#endif
+    return output_color;
+}

assets/shaders/texture2d_mip_material.wgsl

@@ -0,0 +1,33 @@
+#import bevy_sprite::{
+    mesh2d_vertex_output::VertexOutput,
+    mesh2d_view_bindings::view,
+}
+
+#ifdef TONEMAP_IN_SHADER
+#import bevy_core_pipeline::tonemapping
+#endif
+
+struct TextureMipMaterial {
+    texture_available: u32,
+    mip_level: f32,
+    layer_index: u32,
+}
+
+@group(2) @binding(0) var<uniform> material: TextureMipMaterial;
+@group(2) @binding(1) var texture: texture_2d<f32>;
+@group(2) @binding(2) var texture_sampler: sampler;
+
+@fragment
+fn fragment(
+    mesh: VertexOutput,
+) -> @location(0) vec4<f32> {
+    var output_color: vec4<f32> = vec4<f32>(0.0);
+    if (material.texture_available != 0u) {
+        output_color = textureSampleLevel(texture, texture_sampler, mesh.uv, material.mip_level);
+    }
+
+#ifdef TONEMAP_IN_SHADER
+    output_color = tonemapping::tone_mapping(output_color, view.color_grading);
+#endif
+    return output_color;
+}

assets/textures/texture_support/README.md

@@ -0,0 +1,166 @@
+# Texture Format Sample Image Generation
+
+## Required Software
+
+- [**toktx**](https://github.khronos.org/KTX-Software/ktxtools/toktx.html)
+- [**basisu**](https://github.com/BinomialLLC/basis_universal)
+
+## Instructions
+
+The files in this directory are generated from [png-srgb-rgb.png](./png-srgb-rgb.png) using the following commands:
+
+### Misc LDR Formats
+
+```sh
+pip install pillow imageio qoi numpy
+python ./scripts/export-ldr-formats.py
+```
+
+### EXR / HDR
+
+```sh
+pip install imageio numpy OpenEXR
+python ./scripts/export-hdr-formats.py
+```
+
+### KTX2
+
+```sh
+rm -f ./*.ktx2
+
+# KTX2: Uncompressed
+toktx --t2 --assign_oetf srgb srgb8.ktx2 png-srgb-rgb.png
+
+# KTX2: Uncompressed HDR
+# https://github.khronos.org/KTX-Software/ktxtools/ktx_create.html
+# https://registry.khronos.org/vulkan/specs/latest/man/html/VkFormat.html
+ktx create --format R32_SFLOAT exr-hdr.exr ktx2-hdr-r32.ktx2
+ktx create --format R32G32B32_SFLOAT exr-hdr.exr ktx2-hdr-rgb32.ktx2
+ktx create --format R32G32B32A32_SFLOAT exr-hdr.exr ktx2-hdr-rgba32.ktx2
+
+# KTX2: ASTC sRGB w/Mips
+toktx --t2 --genmipmap --assign_oetf srgb --encode astc --astc_blk_d 4x4 ktx2-astc-4x4-srgb-mips.ktx2 png-srgb-rgb.png
+
+# KTX2: ASTC sRGB
+toktx --t2 --assign_oetf srgb --encode astc --astc_blk_d 4x4 ktx2-astc-4x4-srgb.ktx2 png-srgb-rgb.png
+toktx --t2 --assign_oetf srgb --encode astc --astc_blk_d 5x4 ktx2-astc-5x4-srgb.ktx2 png-srgb-rgb.png
+toktx --t2 --assign_oetf srgb --encode astc --astc_blk_d 5x5 ktx2-astc-5x5-srgb.ktx2 png-srgb-rgb.png
+toktx --t2 --assign_oetf srgb --encode astc --astc_blk_d 6x5 ktx2-astc-6x5-srgb.ktx2 png-srgb-rgb.png
+toktx --t2 --assign_oetf srgb --encode astc --astc_blk_d 6x6 ktx2-astc-6x6-srgb.ktx2 png-srgb-rgb.png
+toktx --t2 --assign_oetf srgb --encode astc --astc_blk_d 8x5 ktx2-astc-8x5-srgb.ktx2 png-srgb-rgb.png
+toktx --t2 --assign_oetf srgb --encode astc --astc_blk_d 8x6 ktx2-astc-8x6-srgb.ktx2 png-srgb-rgb.png
+toktx --t2 --assign_oetf srgb --encode astc --astc_blk_d 10x5 ktx2-astc-10x5-srgb.ktx2 png-srgb-rgb.png
+toktx --t2 --assign_oetf srgb --encode astc --astc_blk_d 10x6 ktx2-astc-10x6-srgb.ktx2 png-srgb-rgb.png
+toktx --t2 --assign_oetf srgb --encode astc --astc_blk_d 8x8 ktx2-astc-8x8-srgb.ktx2 png-srgb-rgb.png
+toktx --t2 --assign_oetf srgb --encode astc --astc_blk_d 10x8 ktx2-astc-10x8-srgb.ktx2 png-srgb-rgb.png
+toktx --t2 --assign_oetf srgb --encode astc --astc_blk_d 10x10 ktx2-astc-10x10-srgb.ktx2 png-srgb-rgb.png
+toktx --t2 --assign_oetf srgb --encode astc --astc_blk_d 12x10 ktx2-astc-12x10-srgb.ktx2 png-srgb-rgb.png
+toktx --t2 --assign_oetf srgb --encode astc --astc_blk_d 12x12 ktx2-astc-12x12-srgb.ktx2 png-srgb-rgb.png
+
+# KTX2: ASTC Linear
+toktx --t2 --assign_oetf srgb --convert_oetf linear --encode astc --astc_blk_d 4x4 ktx2-astc-4x4-linear.ktx2 png-srgb-rgb.png
+toktx --t2 --assign_oetf srgb --convert_oetf linear --encode astc --astc_blk_d 5x4 ktx2-astc-5x4-linear.ktx2 png-srgb-rgb.png
+toktx --t2 --assign_oetf srgb --convert_oetf linear --encode astc --astc_blk_d 5x5 ktx2-astc-5x5-linear.ktx2 png-srgb-rgb.png
+toktx --t2 --assign_oetf srgb --convert_oetf linear --encode astc --astc_blk_d 6x5 ktx2-astc-6x5-linear.ktx2 png-srgb-rgb.png
+toktx --t2 --assign_oetf srgb --convert_oetf linear --encode astc --astc_blk_d 6x6 ktx2-astc-6x6-linear.ktx2 png-srgb-rgb.png
+toktx --t2 --assign_oetf srgb --convert_oetf linear --encode astc --astc_blk_d 8x5 ktx2-astc-8x5-linear.ktx2 png-srgb-rgb.png
+toktx --t2 --assign_oetf srgb --convert_oetf linear --encode astc --astc_blk_d 8x6 ktx2-astc-8x6-linear.ktx2 png-srgb-rgb.png
+toktx --t2 --assign_oetf srgb --convert_oetf linear --encode astc --astc_blk_d 10x5 ktx2-astc-10x5-linear.ktx2 png-srgb-rgb.png
+toktx --t2 --assign_oetf srgb --convert_oetf linear --encode astc --astc_blk_d 10x6 ktx2-astc-10x6-linear.ktx2 png-srgb-rgb.png
+toktx --t2 --assign_oetf srgb --convert_oetf linear --encode astc --astc_blk_d 8x8 ktx2-astc-8x8-linear.ktx2 png-srgb-rgb.png
+toktx --t2 --assign_oetf srgb --convert_oetf linear --encode astc --astc_blk_d 10x8 ktx2-astc-10x8-linear.ktx2 png-srgb-rgb.png
+toktx --t2 --assign_oetf srgb --convert_oetf linear --encode astc --astc_blk_d 10x10 ktx2-astc-10x10-linear.ktx2 png-srgb-rgb.png
+toktx --t2 --assign_oetf srgb --convert_oetf linear --encode astc --astc_blk_d 12x10 ktx2-astc-12x10-linear.ktx2 png-srgb-rgb.png
+toktx --t2 --assign_oetf srgb --convert_oetf linear --encode astc --astc_blk_d 12x12 ktx2-astc-12x12-linear.ktx2 png-srgb-rgb.png
+
+# KTX2: ASTC w/Zstd Supercompression
+toktx --t2 --assign_oetf srgb --encode astc --zcmp 10 --astc_blk_d 4x4 ktx2-zstd-astc-4x4-srgb.ktx2 png-srgb-rgb.png
+toktx --t2 --assign_oetf srgb --convert_oetf linear --encode astc --zcmp 10 --astc_blk_d 4x4 ktx2-zstd-astc-4x4-linear.ktx2 png-srgb-rgb.png
+
+# KTX2: UASTC
+toktx --t2 --assign_oetf srgb --encode uastc ktx2-uastc-srgb.ktx2 png-srgb-rgb.png
+toktx --t2 --assign_oetf srgb --encode uastc --uastc_rdo_l 1.0 ktx2-uastc-srgb-rdo.ktx2 png-srgb-rgb.png
+toktx --t2 --assign_oetf srgb --convert_oetf linear --encode uastc ktx2-uastc-linear.ktx2 png-srgb-rgb.png
+toktx --t2 --assign_oetf srgb --convert_oetf linear --encode uastc --uastc_rdo_l 1.0 ktx2-uastc-linear-rdo.ktx2 png-srgb-rgb.png
+
+# KTX2: UASTC w/Zstd Supercompression
+toktx --t2 --assign_oetf srgb --encode uastc --zcmp 10 --uastc_rdo_l 1.0 ktx2-zstd-uastc-srgb-rdo.ktx2 png-srgb-rgb.png
+
+# KTX2: ETC1S/BasisLZ
+toktx --t2 --assign_oetf srgb --encode etc1s ktx2-etc1s-srgb.ktx2 png-srgb-rgb.png
+toktx --t2 --assign_oetf srgb --convert_oetf linear --encode etc1s ktx2-etc1s-linear.ktx2 png-srgb-rgb.png
+
+# KTX2: Multi-layer with Mipmaps
+toktx --t2 --layers 6 --genmipmap --assign_oetf srgb --encode astc --astc_blk_d 4x4 ktx2-astc-4x4-srgb-multilayer-mips.ktx2 \
+    png-layer-0.png \
+    png-layer-1.png \
+    png-layer-2.png \
+    png-layer-3.png \
+    png-layer-4.png \
+    png-layer-5.png
+
+# KTX2: Cubemap
+# toktx --t2 --cubemap --assign_oetf srgb --encode astc --astc_blk_d 4x4 ktx2-astc-4x4-srgb-cubemap.ktx2 \
+#     png-layer-0.png \
+#     png-layer-1.png \
+#     png-layer-2.png \
+#     png-layer-3.png \
+#     png-layer-4.png \
+#     png-layer-5.png
+
+# KTX2: Cubemap with Mipmaps
+# toktx --t2 --cubemap --genmipmap --assign_oetf srgb --encode astc --astc_blk_d 4x4 ktx2-astc-4x4-srgb-cubemap-mips.ktx2 \
+#     png-layer-0.png \
+#     png-layer-1.png \
+#     png-layer-2.png \
+#     png-layer-3.png \
+#     png-layer-4.png \
+#     png-layer-5.png
+```
+
+### Basis
+
+```sh
+rm -f ./*.basis
+
+# Basis: ETC1S
+basisu -basis -etc1s png-srgb-rgb.png -output_file ./basis-etc1s-srgb.basis
+basisu -basis -etc1s -linear png-srgb-rgb.png -output_file ./basis-etc1s-linear.basis
+
+# Basis: ETC1S Video / Cubemap / 2darray
+# basisu -basis -etc1s -tex_type video ./png-layer-0.png png-layer-1.png png-layer-2.png png-layer-3.png png-layer-4.png png-layer-5.png -output_file ./basis-etc1s-srgb-video.basis
+# basisu -basis -etc1s -tex_type cubemap png-layer-0.png png-layer-1.png png-layer-2.png png-layer-3.png png-layer-4.png png-layer-5.png -output_file ./basis-etc1s-srgb-cubemap.basis
+
+# Basis: ETC1S Video / Cubemap / 2darray (with mips)
+# basisu -basis -mipmap -etc1s -tex_type video ./png-layer-0.png png-layer-1.png png-layer-2.png png-layer-3.png png-layer-4.png png-layer-5.png -output_file ./basis-etc1s-srgb-video-mips.basis
+# basisu -basis -mipmap -etc1s -tex_type cubemap png-layer-0.png png-layer-1.png png-layer-2.png png-layer-3.png png-layer-4.png png-layer-5.png -output_file ./basis-etc1s-srgb-cubemap-mips.basis
+# basisu -basis -mipmap -etc1s -tex_type 2darray png-layer-0.png png-layer-1.png png-layer-2.png png-layer-3.png png-layer-4.png png-layer-5.png -output_file ./basis-etc1s-srgb-multilayer-mips.basis
+
+# Basis: UASTC 4x4 LDR
+basisu -basis -uastc png-srgb-rgb.png -output_file ./basis-uastc-4x4-srgb.basis
+basisu -basis -uastc -uastc_rdo_l 2.0 png-srgb-rgb.png -output_file ./basis-uastc-4x4-rdo-srgb.basis
+basisu -basis -uastc -mipmap png-srgb-rgb.png -output_file ./basis-uastc-4x4-srgb-mips.basis
+
+# Basis: UASTC 4x4 LDR w/Mips
+basisu -basis -mipmap -uastc -tex_type 2darray png-layer-0.png png-layer-1.png png-layer-2.png png-layer-3.png png-layer-4.png png-layer-5.png -output_file ./basis-uastc-4x4-srgb-multilayer-mips.basis
+
+# Basis: KTX2 HDR
+basisu -hdr_4x4 exr-hdr.exr -output_file ./ktx2-astc-4x4-hdr.ktx2
+basisu -hdr_6x6 exr-hdr.exr -output_file ./ktx2-astc-6x6-hdr.ktx2
+basisu -hdr_6x6i exr-hdr.exr -output_file ./ktx2-astc-6x6i-hdr.ktx2
+
+# Basis: Basis HDR
+basisu -basis -hdr_4x4 exr-hdr.exr -output_file ./basis-astc-4x4-hdr.basis
+basisu -basis -hdr_6x6 exr-hdr.exr -output_file ./basis-astc-6x6-hdr.basis
+basisu -basis -hdr_6x6i exr-hdr.exr -output_file ./basis-astc-6x6i-hdr.basis
+```
+
+## For Benches
+
+```sh
+ktx create --generate-mipmap --format R32G32B32A32_SFLOAT exr-hdr.exr ../../../benches/benches/bevy_image/assets/ktx2-rgba32-mips.ktx2
+
+toktx --t2 -resize 555x555 --genmipmap --assign_oetf srgb --encode uastc ../../../benches/benches/bevy_image/assets/ktx2-uastc-srgb-mips.ktx2 png-srgb-rgb.png
+
+toktx --t2 --zcmp 10 -resize 555x555 --genmipmap --assign_oetf srgb --encode uastc ../../../benches/benches/bevy_image/assets/ktx2-zstd-uastc-srgb-mips.ktx2 png-srgb-rgb.png
+```

assets/textures/texture_support/scripts/export-hdr-formats.py

@@ -0,0 +1,45 @@
+# python ./scripts/export-hdr-formats.py
+
+import numpy as np
+import OpenEXR
+import Imath
+import imageio.v3 as iio
+
+def srgb_to_linear(srgb):
+    """ Convert sRGB to linear using the standard formula. """
+    return np.where(srgb <= 0.04045,
+                    srgb / 12.92,
+                    ((srgb + 0.055) / 1.055) ** 2.4)
+
+# Load PNG image (sRGB)
+input_filename = "png-srgb-rgb.png"
+img_srgb = iio.imread(input_filename).astype(np.float32) / 255.0  # Normalize to [0,1]
+
+# Convert sRGB to linear space
+img_linear = srgb_to_linear(img_srgb)
+
+# Identify pure-white pixels in sRGB space (R, G, B all == 1.0 in sRGB)
+pure_white_mask = np.all(img_srgb == 1.0, axis=-1)  # True where pixels are exactly (1,1,1) in sRGB
+
+# Apply boost only to pure-white pixels in linear space
+img_linear[pure_white_mask] *= 10.0  # Multiply only the pure white pixels
+
+# Ensure shape is (3, height, width) for OpenEXR
+img_exr = img_linear.transpose(2, 0, 1)
+
+# Define EXR output
+height, width = img_exr.shape[1], img_exr.shape[2]
+output_exr_filename = "exr-hdr.exr"
+header = OpenEXR.Header(width, height)
+channels = ["R", "G", "B"]
+pixel_type = Imath.PixelType(Imath.PixelType.FLOAT)
+
+# Prepare the image data for OpenEXR
+exr_file = OpenEXR.OutputFile(output_exr_filename, header)
+exr_file.writePixels({ch: img_exr[i].astype(np.float32).tobytes() for i, ch in enumerate(channels)})
+print(f"Saved linear HDR image to {output_exr_filename}")
+
+# Export HDR file (Radiance HDR)
+output_hdr_filename = "hdr.hdr"
+iio.imwrite(output_hdr_filename, img_linear.astype(np.float32))
+print(f"Saved HDR image to {output_hdr_filename}")