CompressedImageSaver revamp

.gitignore

@@ -20,6 +20,7 @@ Cargo.lock
 
 # Bevy Assets
 assets/**/*.meta
+!assets/textures/GroundSand005/*.meta
 crates/bevy_asset/imported_assets
 imported_assets
 .web-asset-cache

Cargo.toml

@@ -436,7 +436,12 @@ 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
+# Texture compression asset processor (cross-platform, transcodes to any GPU format at load time)
+compressed_image_saver_universal = [
+  "bevy_internal/compressed_image_saver_universal",
+]
+
+# Texture compression asset processor (BCn for desktop, ASTC for mobile via env var)
 compressed_image_saver = ["bevy_internal/compressed_image_saver"]
 
 # Enables system-level clipboard support.
@@ -2080,6 +2085,18 @@ description = "Demonstrates loading a compressed asset"
 category = "Assets"
 wasm = false
 
+[[example]]
+name = "compressed_image_saver"
+path = "examples/asset/compressed_image_saver.rs"
+doc-scrape-examples = true
+required-features = ["compressed_image_saver", "asset_processor", "jpeg"]
+
+[package.metadata.example.compressed_image_saver]
+name = "Compressed Image Saver"
+description = "Demonstrates compressing textures and generating mipmaps using CompressedImageSaver"
+category = "Assets"
+wasm = false
+
 [[example]]
 name = "custom_asset"
 path = "examples/asset/custom_asset.rs"

_release-content/migration-guides/compressed_image_saver.md

@@ -0,0 +1,20 @@
+---
+title: "`CompressedImageSaver` improvements"
+pull_requests: [23567]
+---
+
+The `compressed_image_saver` Cargo feature has been reworked. The old behavior (Basis Universal UASTC compression) has been moved to a new feature called `compressed_image_saver_universal`, and the `compressed_image_saver` feature now uses the `ctt` library to compress textures into BCn (desktop) or ASTC (mobile) formats instead.
+
+If you were using the `compressed_image_saver` feature and want to keep the previous Basis Universal behavior, rename the feature in your `Cargo.toml`:
+
+```toml
+# Before
+bevy = { version = "0.18", features = ["compressed_image_saver"] }
+
+# After (keeps old Basis Universal behavior)
+bevy = { version = "0.19", features = ["compressed_image_saver_universal"] }
+```
+
+Alternatively, keep using `compressed_image_saver` to get the new BCn/ASTC compression backend. This produces higher-quality output and supports a wider range of input formats, but does not support all platforms in a single file like UASTC does. We recommend sticking to `compressed_image_saver_universal` when targeting the web.
+
+`CompressedImageSaverError` has a new variant `CompressionFailed`. If you were matching exhaustively on this enum, add a branch for it.

_release-content/release-notes/compressed_image_saver.md

@@ -0,0 +1,23 @@
+---
+title: CompressedImageSaver Improvements
+authors: ["@JMS55", "@cwfitzgerald"]
+pull_requests: [23567]
+---
+
+Bevy's `CompressedImageSaver` asset processor has been significantly upgraded with a new compression backend powered by the [`ctt`](https://github.com/cwfitzgerald/ctt) library.
+
+The new `compressed_image_saver` feature compresses textures into BCn formats (for desktop GPUs) or ASTC formats (for mobile GPUs), producing higher-quality output than the previous Basis Universal approach. The compressor automatically selects the best output format based on the input texture's channel count and type — for example, single-channel textures get BC4, HDR textures get BC6H, and standard RGBA textures get BC7.
+
+Try out the new `compressed_image_saver` example to see it in action.
+
+## Automatic Mipmap Generation
+
+No more manually generating mipmaps! The new backend automatically produces a full mip chain during compression. This means less aliasing when textures are viewed at a distance and better GPU cache utilization — all for free, just by running your textures through the asset processor.
+
+## ASTC for Mobile
+
+To target mobile GPUs, set the `BEVY_COMPRESSED_IMAGE_SAVER_ASTC` environment variable with your desired block size (e.g. `4x4`, `6x6`, `8x8`). Larger blocks give smaller files at the cost of quality. All 14 ASTC block sizes are supported.
+
+## Basis Universal is Still Available
+
+The previous Basis Universal compression behavior has been moved to the `compressed_image_saver_universal` feature. This remains the best choice for cross-platform distribution (including WebGPU), since UASTC can be transcoded at load time to whatever format the target GPU supports.

assets/textures/GroundSand005/GroundSand005_COL_2K.jpg.meta

@@ -0,0 +1,16 @@
+(
+    meta_format_version: "1.0",
+    asset: Process(
+        processor: "LoadTransformAndSave<ImageLoader, IdentityAssetTransformer<Image>, CompressedImageSaver>",
+        settings: (
+            loader_settings: (
+                format: FromExtension,
+                is_srgb: true,
+                sampler: Default,
+                asset_usage: ("RENDER_WORLD"),
+            ),
+            transformer_settings: (),
+            saver_settings: (),
+        ),
+    ),
+)

assets/textures/GroundSand005/GroundSand005_DISP_2K.jpg.meta

@@ -0,0 +1,17 @@
+(
+    meta_format_version: "1.0",
+    asset: Process(
+        processor: "LoadTransformAndSave<ImageLoader, IdentityAssetTransformer<Image>, CompressedImageSaver>",
+        settings: (
+            loader_settings: (
+                format: FromExtension,
+                is_srgb: false,
+                sampler: Default,
+                asset_usage: ("RENDER_WORLD"),
+                texture_format: Some("r8unorm"),
+            ),
+            transformer_settings: (),
+            saver_settings: (),
+        ),
+    ),
+)

assets/textures/GroundSand005/GroundSand005_NRM_2K.jpg.meta

@@ -0,0 +1,16 @@
+(
+    meta_format_version: "1.0",
+    asset: Process(
+        processor: "LoadTransformAndSave<ImageLoader, IdentityAssetTransformer<Image>, CompressedImageSaver>",
+        settings: (
+            loader_settings: (
+                format: FromExtension,
+                is_srgb: false,
+                sampler: Default,
+                asset_usage: ("RENDER_WORLD"),
+            ),
+            transformer_settings: (),
+            saver_settings: (),
+        ),
+    ),
+)

assets/textures/GroundSand005/GroundSand005_ORM_2K.png.meta

@@ -0,0 +1,16 @@
+(
+    meta_format_version: "1.0",
+    asset: Process(
+        processor: "LoadTransformAndSave<ImageLoader, IdentityAssetTransformer<Image>, CompressedImageSaver>",
+        settings: (
+            loader_settings: (
+                format: FromExtension,
+                is_srgb: false,
+                sampler: Default,
+                asset_usage: ("RENDER_WORLD"),
+            ),
+            transformer_settings: (),
+            saver_settings: (),
+        ),
+    ),
+)

assets/textures/GroundSand005/source.txt

@@ -0,0 +1 @@
+https://www.poliigon.com/texture/rippled-wet-sand-texture/6997

crates/bevy_image/Cargo.toml

@@ -45,8 +45,11 @@ zstd_rust = ["zstd", "dep:ruzstd"]
 # Binding to zstd C implementation (faster)
 zstd_c = ["zstd", "dep:zstd"]
 
-# Enables compressed KTX2 UASTC texture output on the asset processor
-compressed_image_saver = ["basis-universal"]
+# Texture compression asset processor (cross-platform, transcodes to any GPU format at load time)
+compressed_image_saver_universal = ["basis-universal"]
+
+# Texture compression asset processor (BCn for desktop, ASTC for mobile via env var)
+compressed_image_saver = ["dep:ctt", "ktx2", "zstd"]
 
 [dependencies]
 # bevy
@@ -88,6 +91,7 @@ ruzstd = { version = "0.8.0", optional = true }
 basis-universal = { version = "0.3.0", optional = true }
 tracing = { version = "0.1", default-features = false, features = ["std"] }
 half = { version = "2.4.1" }
+ctt = { version = "0.3", optional = true }
 
 [dev-dependencies]
 bevy_ecs = { path = "../bevy_ecs", version = "0.19.0-dev" }

crates/bevy_image/src/compressed_image_saver/ctt.rs

@@ -0,0 +1,107 @@
+use bevy_asset::{io::Writer, saver::SavedAsset, AssetPath, AsyncWriteExt};
+
+use super::{
+    ctt_helpers::{
+        bevy_to_ctt_alpha_mode, choose_ctt_compressed_format, wgpu_to_ctt_texture_format,
+    },
+    CompressedImageSaverError, CompressedImageSaverSettings,
+};
+use crate::{Image, ImageFormat, ImageFormatSetting, ImageLoaderSettings};
+
+#[derive(Default)]
+pub struct CompressedImageSaverCtt;
+
+impl CompressedImageSaverCtt {
+    pub async fn save(
+        &self,
+        writer: &mut Writer,
+        image: SavedAsset<'_, '_, Image>,
+        settings: &CompressedImageSaverSettings,
+        _asset_path: AssetPath<'_>,
+    ) -> Result<ImageLoaderSettings, CompressedImageSaverError> {
+        let Some(ref data) = image.data else {
+            return Err(CompressedImageSaverError::UninitializedImage);
+        };
+
+        if image.texture_descriptor.mip_level_count != 1 {
+            return Err(CompressedImageSaverError::CompressionFailed(
+                "Expected texture_descriptor.mip_level_count to be 1".into(),
+            ));
+        }
+
+        let input_format = wgpu_to_ctt_texture_format(image.texture_descriptor.format)?;
+        let output_format = choose_ctt_compressed_format(image.texture_descriptor.format)?;
+
+        let is_srgb = image.texture_descriptor.format.is_srgb();
+        let color_space = if is_srgb {
+            ctt::ColorSpace::Srgb
+        } else {
+            ctt::ColorSpace::Linear
+        };
+
+        let is_cubemap = matches!(
+            image.texture_view_descriptor,
+            Some(wgpu_types::TextureViewDescriptor {
+                dimension: Some(wgpu_types::TextureViewDimension::Cube),
+                ..
+            })
+        );
+
+        let bytes_per_pixel =
+            crate::TextureFormatPixelInfo::pixel_size(&image.texture_descriptor.format).map_err(
+                |_| CompressedImageSaverError::UnsupportedFormat(image.texture_descriptor.format),
+            )? as u32;
+
+        let surfaces = data
+            .chunks_exact((image.width() * image.height() * bytes_per_pixel) as usize)
+            .map(|layer_data| {
+                vec![ctt::Surface {
+                    data: layer_data.to_vec(),
+                    width: image.width(),
+                    height: image.height(),
+                    stride: image.width() * bytes_per_pixel,
+                    format: input_format,
+                    color_space,
+                    alpha: bevy_to_ctt_alpha_mode(settings.input_alpha_mode),
+                }]
+            })
+            .collect();
+        let ctt_image = ctt::Image {
+            surfaces,
+            is_cubemap,
+        };
+
+        let settings = ctt::ConvertSettings {
+            format: Some(output_format),
+            container: ctt::Container::ktx2_zstd(0),
+            quality: ctt::Quality::default(),
+            output_color_space: None,
+            output_alpha: Some(bevy_to_ctt_alpha_mode(settings.output_alpha_mode)),
+            swizzle: None,
+            mipmap: true,
+            mipmap_count: None,
+            mipmap_filter: ctt::MipmapFilter::default(),
+            encoder_settings: None,
+            registry: None,
+        };
+
+        let output = ctt::convert(ctt_image, settings)
+            .map_err(|e| CompressedImageSaverError::CompressionFailed(Box::new(e)))?;
+        let ctt::PipelineOutput::Encoded(compressed_bytes) = &output else {
+            return Err(CompressedImageSaverError::CompressionFailed(
+                "Expected encoded output from ctt".into(),
+            ));
+        };
+
+        writer.write_all(compressed_bytes).await?;
+
+        Ok(ImageLoaderSettings {
+            format: ImageFormatSetting::Format(ImageFormat::Ktx2),
+            is_srgb,
+            sampler: image.sampler.clone(),
+            asset_usage: image.asset_usage,
+            texture_format: None,
+            array_layout: None,
+        })
+    }
+}