KTX2/DDS/.basis compressed texture support (bevyengine#3884)

# Objective

- Support compressed textures including 'universal' formats (ETC1S, UASTC) and transcoding of them to 
- Support `.dds`, `.ktx2`, and `.basis` files

## Solution

- Fixes bevyengine#3608 Look there for more details.
- Note that the functionality is all enabled through non-default features. If it is desirable to enable some by default, I can do that.
- The `basis-universal` crate, used for `.basis` file support and for transcoding, is built on bindings against a C++ library. It's not feasible to rewrite in Rust in a short amount of time. There are no Rust alternatives of which I am aware and it's specialised code. In its current state it doesn't support the wasm target, but I don't know for sure. However, it is possible to build the upstream C++ library with emscripten, so there is perhaps a way to add support for web too with some shenanigans.
- There's no support for transcoding from BasisLZ/ETC1S in KTX2 files as it was quite non-trivial to implement and didn't feel important given people could use `.basis` files for ETC1S.

Cargo.toml

@@ -64,10 +64,15 @@ wgpu_trace = ["bevy_internal/wgpu_trace"]
 # Image format support for texture loading (PNG and HDR are enabled by default)
 hdr = ["bevy_internal/hdr"]
 png = ["bevy_internal/png"]
-dds = ["bevy_internal/dds"]
 tga = ["bevy_internal/tga"]
 jpeg = ["bevy_internal/jpeg"]
 bmp = ["bevy_internal/bmp"]
+basis-universal = ["bevy_internal/basis-universal"]
+dds = ["bevy_internal/dds"]
+ktx2 = ["bevy_internal/ktx2"]
+# For ktx2 supercompression
+zlib = ["bevy_internal/zlib"]
+zstd = ["bevy_internal/zstd"]
 
 # Audio format support (vorbis is enabled by default)
 flac = ["bevy_internal/flac"]

crates/bevy_gltf/src/loader.rs

@@ -3,7 +3,7 @@ use bevy_asset::{
     AssetIoError, AssetLoader, AssetPath, BoxedFuture, Handle, LoadContext, LoadedAsset,
 };
 use bevy_core::Name;
-use bevy_ecs::world::World;
+use bevy_ecs::{prelude::FromWorld, world::World};
 use bevy_hierarchy::{BuildWorldChildren, WorldChildBuilder};
 use bevy_log::warn;
 use bevy_math::{Mat4, Vec3};
@@ -18,10 +18,9 @@ use bevy_render::{
     color::Color,
     mesh::{Indices, Mesh, VertexAttributeValues},
     primitives::{Aabb, Frustum},
-    render_resource::{
-        AddressMode, FilterMode, PrimitiveTopology, SamplerDescriptor, TextureFormat,
-    },
-    texture::{Image, ImageType, TextureError},
+    render_resource::{AddressMode, FilterMode, PrimitiveTopology, SamplerDescriptor},
+    renderer::RenderDevice,
+    texture::{CompressedImageFormats, Image, ImageType, TextureError},
     view::VisibleEntities,
 };
 use bevy_scene::Scene;
@@ -60,27 +59,41 @@ pub enum GltfError {
 }
 
 /// Loads glTF files with all of their data as their corresponding bevy representations.
-#[derive(Default)]
-pub struct GltfLoader;
+pub struct GltfLoader {
+    supported_compressed_formats: CompressedImageFormats,
+}
 
 impl AssetLoader for GltfLoader {
     fn load<'a>(
         &'a self,
         bytes: &'a [u8],
         load_context: &'a mut LoadContext,
     ) -> BoxedFuture<'a, Result<()>> {
-        Box::pin(async move { Ok(load_gltf(bytes, load_context).await?) })
+        Box::pin(async move {
+            Ok(load_gltf(bytes, load_context, self.supported_compressed_formats).await?)
+        })
     }
 
     fn extensions(&self) -> &[&str] {
         &["gltf", "glb"]
     }
 }
 
+impl FromWorld for GltfLoader {
+    fn from_world(world: &mut World) -> Self {
+        Self {
+            supported_compressed_formats: CompressedImageFormats::from_features(
+                world.resource::<RenderDevice>().features(),
+            ),
+        }
+    }
+}
+
 /// Loads an entire glTF file.
 async fn load_gltf<'a, 'b>(
     bytes: &'a [u8],
     load_context: &'a mut LoadContext<'b>,
+    supported_compressed_formats: CompressedImageFormats,
 ) -> Result<(), GltfError> {
     let gltf = gltf::Gltf::from_slice(bytes)?;
     let buffer_data = load_buffers(&gltf, load_context, load_context.path()).await?;
@@ -251,8 +264,14 @@ async fn load_gltf<'a, 'b>(
     // to avoid https://github.com/bevyengine/bevy/pull/2725
     if gltf.textures().len() == 1 || cfg!(target_arch = "wasm32") {
         for gltf_texture in gltf.textures() {
-            let (texture, label) =
-                load_texture(gltf_texture, &buffer_data, &linear_textures, load_context).await?;
+            let (texture, label) = load_texture(
+                gltf_texture,
+                &buffer_data,
+                &linear_textures,
+                load_context,
+                supported_compressed_formats,
+            )
+            .await?;
             load_context.set_labeled_asset(&label, LoadedAsset::new(texture));
         }
     } else {
@@ -265,7 +284,14 @@ async fn load_gltf<'a, 'b>(
                     let load_context: &LoadContext = load_context;
                     let buffer_data = &buffer_data;
                     scope.spawn(async move {
-                        load_texture(gltf_texture, buffer_data, linear_textures, load_context).await
+                        load_texture(
+                            gltf_texture,
+                            buffer_data,
+                            linear_textures,
+                            load_context,
+                            supported_compressed_formats,
+                        )
+                        .await
                     });
                 });
             })
@@ -334,13 +360,20 @@ async fn load_texture<'a>(
     buffer_data: &[Vec<u8>],
     linear_textures: &HashSet<usize>,
     load_context: &LoadContext<'a>,
+    supported_compressed_formats: CompressedImageFormats,
 ) -> Result<(Image, String), GltfError> {
+    let is_srgb = !linear_textures.contains(&gltf_texture.index());
     let mut texture = match gltf_texture.source().source() {
         gltf::image::Source::View { view, mime_type } => {
             let start = view.offset() as usize;
             let end = (view.offset() + view.length()) as usize;
             let buffer = &buffer_data[view.buffer().index()][start..end];
-            Image::from_buffer(buffer, ImageType::MimeType(mime_type))?
+            Image::from_buffer(
+                buffer,
+                ImageType::MimeType(mime_type),
+                supported_compressed_formats,
+                is_srgb,
+            )?
         }
         gltf::image::Source::Uri { uri, mime_type } => {
             let uri = percent_encoding::percent_decode_str(uri)
@@ -363,13 +396,12 @@ async fn load_texture<'a>(
             Image::from_buffer(
                 &bytes,
                 mime_type.map(ImageType::MimeType).unwrap_or(image_type),
+                supported_compressed_formats,
+                is_srgb,
             )?
         }
     };
     texture.sampler_descriptor = texture_sampler(&gltf_texture);
-    if (linear_textures).contains(&gltf_texture.index()) {
-        texture.texture_descriptor.format = TextureFormat::Rgba8Unorm;
-    }
 
     Ok((texture, texture_label(&gltf_texture)))
 }

crates/bevy_internal/Cargo.toml

@@ -19,10 +19,15 @@ debug_asset_server = ["bevy_asset/debug_asset_server"]
 # Image format support for texture loading (PNG and HDR are enabled by default)
 hdr = ["bevy_render/hdr"]
 png = ["bevy_render/png"]
-dds = ["bevy_render/dds"]
 tga = ["bevy_render/tga"]
 jpeg = ["bevy_render/jpeg"]
 bmp = ["bevy_render/bmp"]
+basis-universal = ["bevy_render/basis-universal"]
+dds = ["bevy_render/dds"]
+ktx2 = ["bevy_render/ktx2"]
+# For ktx2 supercompression
+zlib = ["bevy_render/zlib"]
+zstd = ["bevy_render/zstd"]
 
 # Audio format support (vorbis is enabled by default)
 flac = ["bevy_audio/flac"]

crates/bevy_internal/src/default_plugins.rs

@@ -58,6 +58,8 @@ impl PluginGroup for DefaultPlugins {
         #[cfg(feature = "bevy_pbr")]
         group.add(bevy_pbr::PbrPlugin::default());
 
+        // NOTE: Load this after renderer initialization so that it knows about the supported
+        // compressed texture formats
         #[cfg(feature = "bevy_gltf")]
         group.add(bevy_gltf::GltfPlugin::default());
 

crates/bevy_pbr/src/pbr_material.rs

@@ -123,6 +123,7 @@ bitflags::bitflags! {
         const ALPHA_MODE_OPAQUE          = (1 << 6);
         const ALPHA_MODE_MASK            = (1 << 7);
         const ALPHA_MODE_BLEND           = (1 << 8);
+        const TWO_COMPONENT_NORMAL_MAP   = (1 << 9);
         const NONE                       = 0;
         const UNINITIALIZED              = 0xFFFF;
     }
@@ -246,6 +247,22 @@ impl RenderAsset for StandardMaterial {
             flags |= StandardMaterialFlags::UNLIT;
         }
         let has_normal_map = material.normal_map_texture.is_some();
+        if has_normal_map {
+            match gpu_images
+                .get(material.normal_map_texture.as_ref().unwrap())
+                .unwrap()
+                .texture_format
+            {
+                // All 2-component unorm formats
+                TextureFormat::Rg8Unorm
+                | TextureFormat::Rg16Unorm
+                | TextureFormat::Bc5RgUnorm
+                | TextureFormat::EacRg11Unorm => {
+                    flags |= StandardMaterialFlags::TWO_COMPONENT_NORMAL_MAP
+                }
+                _ => {}
+            }
+        }
         // NOTE: 0.5 is from the glTF default - do we want this?
         let mut alpha_cutoff = 0.5;
         match material.alpha_mode {

crates/bevy_pbr/src/render/mesh.rs

@@ -327,6 +327,7 @@ impl FromWorld for MeshPipeline {
             GpuImage {
                 texture,
                 texture_view,
+                texture_format: image.texture_descriptor.format,
                 sampler,
                 size: Size::new(
                     image.texture_descriptor.size.width as f32,

crates/bevy_pbr/src/render/pbr.wgsl

@@ -58,6 +58,7 @@ let STANDARD_MATERIAL_FLAGS_UNLIT_BIT: u32                      = 32u;
 let STANDARD_MATERIAL_FLAGS_ALPHA_MODE_OPAQUE: u32              = 64u;
 let STANDARD_MATERIAL_FLAGS_ALPHA_MODE_MASK: u32                = 128u;
 let STANDARD_MATERIAL_FLAGS_ALPHA_MODE_BLEND: u32               = 256u;
+let STANDARD_MATERIAL_FLAGS_TWO_COMPONENT_NORMAL_MAP: u32       = 512u;
 
 [[group(1), binding(0)]]
 var<uniform> material: StandardMaterial;
@@ -515,7 +516,16 @@ fn fragment(in: FragmentInput) -> [[location(0)]] vec4<f32> {
 #ifdef VERTEX_TANGENTS
 #ifdef STANDARDMATERIAL_NORMAL_MAP
         let TBN = mat3x3<f32>(T, B, N);
-        N = TBN * normalize(textureSample(normal_map_texture, normal_map_sampler, in.uv).rgb * 2.0 - 1.0);
+        // Nt is the tangent-space normal.
+        var Nt: vec3<f32>;
+        if ((material.flags & STANDARD_MATERIAL_FLAGS_TWO_COMPONENT_NORMAL_MAP) != 0u) {
+            // Only use the xy components and derive z for 2-component normal maps.
+            Nt = vec3<f32>(textureSample(normal_map_texture, normal_map_sampler, in.uv).rg * 2.0 - 1.0, 0.0);
+            Nt.z = sqrt(1.0 - Nt.x * Nt.x - Nt.y * Nt.y);
+        } else {
+            Nt = textureSample(normal_map_texture, normal_map_sampler, in.uv).rgb * 2.0 - 1.0;
+        }
+        N = normalize(TBN * Nt);
 #endif
 #endif
 

crates/bevy_render/Cargo.toml

@@ -11,10 +11,15 @@ keywords = ["bevy"]
 [features]
 png = ["image/png"]
 hdr = ["image/hdr"]
-dds = ["image/dds"]
 tga = ["image/tga"]
 jpeg = ["image/jpeg"]
 bmp = ["image/bmp"]
+dds = ["ddsfile"]
+
+# For ktx2 supercompression
+zlib = ["flate2"]
+zstd = ["ruzstd"]
+
 trace = []
 wgpu_trace = ["wgpu/trace"]
 ci_limits = []
@@ -54,3 +59,10 @@ hexasphere = "7.0.0"
 parking_lot = "0.11.0"
 regex = "1.5"
 copyless = "0.1.5"
+ddsfile = { version = "0.5.0", optional = true }
+ktx2 = { version = "0.3.0", optional = true }
+# For ktx2 supercompression
+flate2 = { version = "1.0.22", optional = true }
+ruzstd = { version = "0.2.4", optional = true }
+# For transcoding of UASTC/ETC1S universal formats, and for .basis file support
+basis-universal = { version = "0.2.0", optional = true }

crates/bevy_render/src/lib.rs

@@ -289,6 +289,8 @@ impl Plugin for RenderPlugin {
             .add_plugin(CameraPlugin)
             .add_plugin(ViewPlugin)
             .add_plugin(MeshPlugin)
+            // NOTE: Load this after renderer initialization so that it knows about the supported
+            // compressed texture formats
             .add_plugin(ImagePlugin);
     }
 }

crates/bevy_render/src/renderer/render_device.rs

@@ -6,6 +6,8 @@ use futures_lite::future;
 use std::sync::Arc;
 use wgpu::util::DeviceExt;
 
+use super::RenderQueue;
+
 /// This GPU device is responsible for the creation of most rendering and compute resources.
 #[derive(Clone)]
 pub struct RenderDevice {
@@ -121,6 +123,22 @@ impl RenderDevice {
         Buffer::from(wgpu_buffer)
     }
 
+    /// Creates a new [`Texture`] and initializes it with the specified data.
+    ///
+    /// `desc` specifies the general format of the texture.
+    /// `data` is the raw data.
+    pub fn create_texture_with_data(
+        &self,
+        render_queue: &RenderQueue,
+        desc: &wgpu::TextureDescriptor,
+        data: &[u8],
+    ) -> Texture {
+        let wgpu_texture = self
+            .device
+            .create_texture_with_data(render_queue.as_ref(), desc, data);
+        Texture::from(wgpu_texture)
+    }
+
     /// Creates a new [`Texture`].
     ///
     /// `desc` specifies the general format of the texture.