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,22 @@ 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_universal",
+  "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"]
 
 [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" }