Support array / cubemap / cubemap array textures in KTX2 (#5325)

# Objective

- Fix / support KTX2 array / cubemap / cubemap array textures
- Fixes #4495 . Supersedes #4514 .

## Solution

- Add `Option<TextureViewDescriptor>` to `Image` to enable configuration of the `TextureViewDimension` of a texture.
  - This allows users to set `D2Array`, `D3`, `Cube`, `CubeArray` or whatever they need
  - Automatically configure this when loading KTX2
- Transcode all layers and faces instead of just one
- Use the UASTC block size of 128 bits, and the number of blocks in x/y for a given mip level in order to determine the offset of the layer and face within the KTX2 mip level data
- `wgpu` wants data ordered as layer 0 mip 0..n, layer 1 mip 0..n, etc. See https://docs.rs/wgpu/latest/wgpu/util/trait.DeviceExt.html#tymethod.create_texture_with_data
- Reorder the data KTX2 mip X layer Y face Z to `wgpu` layer Y face Z mip X order
- Add a `skybox` example to demonstrate / test loading cubemaps from PNG and KTX2, including ASTC 4x4, BC7, and ETC2 compression for support everywhere. Note that you need to enable the `ktx2,zstd` features to be able to load the compressed textures.

---

## Changelog

- Fixed: KTX2 array / cubemap / cubemap array textures
- Fixes: Validation failure for compressed textures stored in KTX2 where the width/height are not a multiple of the block dimensions.
- Added: `Image` now has an `Option<TextureViewDescriptor>` field to enable configuration of the texture view. This is useful for configuring the `TextureViewDimension` when it is not just a plain 2D texture and the loader could/did not identify what it should be.

Co-authored-by: Carter Anderson <mcanders1@gmail.com>

Cargo.toml

@@ -393,6 +393,17 @@ description = "Demonstrates how to prevent meshes from casting/receiving shadows
 category = "3D Rendering"
 wasm = true
 
+[[example]]
+name = "skybox"
+path = "examples/3d/skybox.rs"
+required-features = ["ktx2", "zstd"]
+
+[package.metadata.example.skybox]
+name = "Skybox"
+description = "Load a cubemap texture onto a cube like a skybox and cycle through different compressed texture formats."
+category = "3D Rendering"
+wasm = false
+
 [[example]]
 name = "spherical_area_lights"
 path = "examples/3d/spherical_area_lights.rs"

assets/shaders/cubemap_unlit.wgsl

@@ -0,0 +1,24 @@
+#import bevy_pbr::mesh_view_bindings
+
+#ifdef CUBEMAP_ARRAY
+@group(1) @binding(0)
+var base_color_texture: texture_cube_array<f32>;
+#else
+@group(1) @binding(0)
+var base_color_texture: texture_cube<f32>;
+#endif
+
+@group(1) @binding(1)
+var base_color_sampler: sampler;
+
+@fragment
+fn fragment(
+    #import bevy_pbr::mesh_vertex_output
+) -> @location(0) vec4<f32> {
+    let fragment_position_view_lh = world_position.xyz * vec3<f32>(1.0, 1.0, -1.0);
+    return textureSample(
+        base_color_texture,
+        base_color_sampler,
+        fragment_position_view_lh
+    );
+}

assets/textures/Ryfjallet_cubemap_readme.txt

@@ -0,0 +1,21 @@
+Modifications
+=============
+
+The original work, as attributed below, has been modified as follows using the ImageMagick tool:
+
+mogrify -resize 256x256 -format png *.jpg
+convert posx.png negx.png posy.png negy.png posz.png negz.png -gravity center -append cubemap.png
+
+Author
+======
+
+This is the work of Emil Persson, aka Humus.
+http://www.humus.name
+
+
+
+License
+=======
+
+This work is licensed under a Creative Commons Attribution 3.0 Unported License.
+http://creativecommons.org/licenses/by/3.0/

crates/bevy_render/src/texture/image.rs

@@ -110,6 +110,7 @@ pub struct Image {
     pub texture_descriptor: wgpu::TextureDescriptor<'static>,
     /// The [`ImageSampler`] to use during rendering.
     pub sampler_descriptor: ImageSampler,
+    pub texture_view_descriptor: Option<wgpu::TextureViewDescriptor<'static>>,
 }
 
 /// Used in [`Image`], this determines what image sampler to use when rendering. The default setting,
@@ -216,6 +217,7 @@ impl Default for Image {
                 usage: wgpu::TextureUsages::TEXTURE_BINDING | wgpu::TextureUsages::COPY_DST,
             },
             sampler_descriptor: ImageSampler::Default,
+            texture_view_descriptor: None,
         }
     }
 }
@@ -684,7 +686,13 @@ impl RenderAsset for Image {
             texture
         };
 
-        let texture_view = texture.create_view(&TextureViewDescriptor::default());
+        let texture_view = texture.create_view(
+            image
+                .texture_view_descriptor
+                .or_else(|| Some(TextureViewDescriptor::default()))
+                .as_ref()
+                .unwrap(),
+        );
         let size = Vec2::new(
             image.texture_descriptor.size.width as f32,
             image.texture_descriptor.size.height as f32,

crates/bevy_render/src/texture/ktx2.rs

@@ -5,13 +5,17 @@ use std::io::Read;
 use basis_universal::{
     DecodeFlags, LowLevelUastcTranscoder, SliceParametersUastc, TranscoderBlockFormat,
 };
+use bevy_utils::default;
 #[cfg(any(feature = "flate2", feature = "ruzstd"))]
 use ktx2::SupercompressionScheme;
 use ktx2::{
     BasicDataFormatDescriptor, ChannelTypeQualifiers, ColorModel, DataFormatDescriptorHeader,
     Header, SampleInformation,
 };
-use wgpu::{AstcBlock, AstcChannel, Extent3d, TextureDimension, TextureFormat};
+use wgpu::{
+    AstcBlock, AstcChannel, Extent3d, TextureDimension, TextureFormat, TextureViewDescriptor,
+    TextureViewDimension,
+};
 
 use super::{CompressedImageFormats, DataFormat, Image, TextureError, TranscodeFormat};
 
@@ -28,10 +32,14 @@ pub fn ktx2_buffer_to_image(
         pixel_height: height,
         pixel_depth: depth,
         layer_count,
+        face_count,
         level_count,
         supercompression_scheme,
         ..
     } = ktx2.header();
+    let layer_count = layer_count.max(1);
+    let face_count = face_count.max(1);
+    let depth = depth.max(1);
 
     // Handle supercompression
     let mut levels = Vec::new();
@@ -80,25 +88,25 @@ pub fn ktx2_buffer_to_image(
     let texture_format = ktx2_get_texture_format(&ktx2, is_srgb).or_else(|error| match error {
         // Transcode if needed and supported
         TextureError::FormatRequiresTranscodingError(transcode_format) => {
-            let mut transcoded = Vec::new();
+            let mut transcoded = vec![Vec::default(); levels.len()];
             let texture_format = match transcode_format {
                 TranscodeFormat::Rgb8 => {
-                    let (mut original_width, mut original_height) = (width, height);
+                    let mut rgba = vec![255u8; width as usize * height as usize * 4];
+                    for (level, level_data) in levels.iter().enumerate() {
+                        let n_pixels = (width as usize >> level).max(1) * (height as usize >> level).max(1);
 
-                    for level_data in &levels {
-                        let n_pixels = (original_width * original_height) as usize;
-
-                        let mut rgba = vec![255u8; n_pixels * 4];
-                        for i in 0..n_pixels {
-                            rgba[i * 4] = level_data[i * 3];
-                            rgba[i * 4 + 1] = level_data[i * 3 + 1];
-                            rgba[i * 4 + 2] = level_data[i * 3 + 2];
+                        let mut offset = 0;
+                        for _layer in 0..layer_count {
+                            for _face in 0..face_count {
+                                for i in 0..n_pixels {
+                                    rgba[i * 4] = level_data[offset];
+                                    rgba[i * 4 + 1] = level_data[offset + 1];
+                                    rgba[i * 4 + 2] = level_data[offset + 2];
+                                    offset += 3;
+                                }
+                                transcoded[level].extend_from_slice(&rgba[0..n_pixels]);
+                            }
                         }
-                        transcoded.push(rgba);
-
-                        // Next mip dimensions are half the current, minimum 1x1
-                        original_width = (original_width / 2).max(1);
-                        original_height = (original_height / 2).max(1);
                     }
 
                     if is_srgb {
@@ -111,41 +119,54 @@ pub fn ktx2_buffer_to_image(
                 TranscodeFormat::Uastc(data_format) => {
                     let (transcode_block_format, texture_format) =
                         get_transcoded_formats(supported_compressed_formats, data_format, is_srgb);
-                    let (mut original_width, mut original_height) = (width, height);
-                    let (block_width_pixels, block_height_pixels) = (4, 4);
+                    let texture_format_info = texture_format.describe();
+                    let (block_width_pixels, block_height_pixels) = (
+                        texture_format_info.block_dimensions.0 as u32,
+                        texture_format_info.block_dimensions.1 as u32,
+                    );
+                    let block_bytes = texture_format_info.block_size as u32;
 
                     let transcoder = LowLevelUastcTranscoder::new();
                     for (level, level_data) in levels.iter().enumerate() {
-                        let slice_parameters = SliceParametersUastc {
-                            num_blocks_x: ((original_width + block_width_pixels - 1)
-                                / block_width_pixels)
-                                .max(1),
-                            num_blocks_y: ((original_height + block_height_pixels - 1)
-                                / block_height_pixels)
-                                .max(1),
-                            has_alpha: false,
-                            original_width,
-                            original_height,
-                        };
+                        let (level_width, level_height) = (
+                            (width >> level as u32).max(1),
+                            (height >> level as u32).max(1),
+                        );
+                        let (num_blocks_x, num_blocks_y) = (
+                            ((level_width + block_width_pixels - 1) / block_width_pixels) .max(1),
+                            ((level_height + block_height_pixels - 1) / block_height_pixels) .max(1),
+                        );
+                        let level_bytes = (num_blocks_x * num_blocks_y * block_bytes) as usize;
 
-                        transcoder
-                            .transcode_slice(
-                                level_data,
-                                slice_parameters,
-                                DecodeFlags::HIGH_QUALITY,
-                                transcode_block_format,
-                            )
-                            .map(|transcoded_level| transcoded.push(transcoded_level))
-                            .map_err(|error| {
-                                TextureError::SuperDecompressionError(format!(
-                                    "Failed to transcode mip level {} from UASTC to {:?}: {:?}",
-                                    level, transcode_block_format, error
-                                ))
-                            })?;
-
-                        // Next mip dimensions are half the current, minimum 1x1
-                        original_width = (original_width / 2).max(1);
-                        original_height = (original_height / 2).max(1);
+                        let mut offset = 0;
+                        for _layer in 0..layer_count {
+                            for _face in 0..face_count {
+                                // NOTE: SliceParametersUastc does not implement Clone nor Copy so
+                                // it has to be created per use
+                                let slice_parameters = SliceParametersUastc {
+                                    num_blocks_x,
+                                    num_blocks_y,
+                                    has_alpha: false,
+                                    original_width: level_width,
+                                    original_height: level_height,
+                                };
+                                transcoder
+                                    .transcode_slice(
+                                        &level_data[offset..(offset + level_bytes)],
+                                        slice_parameters,
+                                        DecodeFlags::HIGH_QUALITY,
+                                        transcode_block_format,
+                                    )
+                                    .map(|mut transcoded_level| transcoded[level].append(&mut transcoded_level))
+                                    .map_err(|error| {
+                                        TextureError::SuperDecompressionError(format!(
+                                            "Failed to transcode mip level {} from UASTC to {:?}: {:?}",
+                                            level, transcode_block_format, error
+                                        ))
+                                    })?;
+                                offset += level_bytes;
+                            }
+                        }
                     }
                     texture_format
                 }
@@ -178,16 +199,52 @@ pub fn ktx2_buffer_to_image(
         )));
     }
 
+    // Reorder data from KTX2 MipXLayerYFaceZ to wgpu LayerYFaceZMipX
+    let texture_format_info = texture_format.describe();
+    let (block_width_pixels, block_height_pixels) = (
+        texture_format_info.block_dimensions.0 as usize,
+        texture_format_info.block_dimensions.1 as usize,
+    );
+    let block_bytes = texture_format_info.block_size as usize;
+
+    let mut wgpu_data = vec![Vec::default(); (layer_count * face_count) as usize];
+    for (level, level_data) in levels.iter().enumerate() {
+        let (level_width, level_height) = (
+            (width as usize >> level).max(1),
+            (height as usize >> level).max(1),
+        );
+        let (num_blocks_x, num_blocks_y) = (
+            ((level_width + block_width_pixels - 1) / block_width_pixels).max(1),
+            ((level_height + block_height_pixels - 1) / block_height_pixels).max(1),
+        );
+        let level_bytes = num_blocks_x * num_blocks_y * block_bytes;
+
+        let mut index = 0;
+        for _layer in 0..layer_count {
+            for _face in 0..face_count {
+                let offset = index * level_bytes;
+                wgpu_data[index].extend_from_slice(&level_data[offset..(offset + level_bytes)]);
+                index += 1;
+            }
+        }
+    }
+
     // Assign the data and fill in the rest of the metadata now the possible
     // error cases have been handled
     let mut image = Image::default();
     image.texture_descriptor.format = texture_format;
-    image.data = levels.into_iter().flatten().collect::<Vec<_>>();
+    image.data = wgpu_data.into_iter().flatten().collect::<Vec<_>>();
     image.texture_descriptor.size = Extent3d {
         width,
         height,
-        depth_or_array_layers: if layer_count > 1 { layer_count } else { depth }.max(1),
-    };
+        depth_or_array_layers: if layer_count > 1 || face_count > 1 {
+            layer_count * face_count
+        } else {
+            depth
+        }
+        .max(1),
+    }
+    .physical_size(texture_format);
     image.texture_descriptor.mip_level_count = level_count;
     image.texture_descriptor.dimension = if depth > 1 {
         TextureDimension::D3
@@ -196,6 +253,24 @@ pub fn ktx2_buffer_to_image(
     } else {
         TextureDimension::D1
     };
+    let mut dimension = None;
+    if face_count == 6 {
+        dimension = Some(if layer_count > 1 {
+            TextureViewDimension::CubeArray
+        } else {
+            TextureViewDimension::Cube
+        });
+    } else if layer_count > 1 {
+        dimension = Some(TextureViewDimension::D2Array);
+    } else if depth > 1 {
+        dimension = Some(TextureViewDimension::D3);
+    }
+    if dimension.is_some() {
+        image.texture_view_descriptor = Some(TextureViewDescriptor {
+            dimension,
+            ..default()
+        });
+    }
     Ok(image)
 }
 

examples/3d/skybox.rs

@@ -0,0 +1,424 @@
+//! Load a cubemap texture onto a cube like a skybox and cycle through different compressed texture formats
+
+use bevy::{
+    asset::LoadState,
+    input::mouse::MouseMotion,
+    pbr::{MaterialPipeline, MaterialPipelineKey},
+    prelude::*,
+    reflect::TypeUuid,
+    render::{
+        mesh::MeshVertexBufferLayout,
+        render_asset::RenderAssets,
+        render_resource::{
+            AsBindGroup, AsBindGroupError, BindGroupDescriptor, BindGroupEntry, BindGroupLayout,
+            BindGroupLayoutDescriptor, BindGroupLayoutEntry, BindingResource, BindingType,
+            OwnedBindingResource, PreparedBindGroup, RenderPipelineDescriptor, SamplerBindingType,
+            ShaderRef, ShaderStages, SpecializedMeshPipelineError, TextureSampleType,
+            TextureViewDescriptor, TextureViewDimension,
+        },
+        renderer::RenderDevice,
+        texture::{CompressedImageFormats, FallbackImage},
+    },
+};
+
+const CUBEMAPS: &[(&str, CompressedImageFormats)] = &[
+    (
+        "textures/Ryfjallet_cubemap.png",
+        CompressedImageFormats::NONE,
+    ),
+    (
+        "textures/Ryfjallet_cubemap_astc4x4.ktx2",
+        CompressedImageFormats::ASTC_LDR,
+    ),
+    (
+        "textures/Ryfjallet_cubemap_bc7.ktx2",
+        CompressedImageFormats::BC,
+    ),
+    (
+        "textures/Ryfjallet_cubemap_etc2.ktx2",
+        CompressedImageFormats::ETC2,
+    ),
+];
+
+fn main() {
+    App::new()
+        .add_plugins(DefaultPlugins)
+        .add_plugin(MaterialPlugin::<CubemapMaterial>::default())
+        .add_startup_system(setup)
+        .add_system(cycle_cubemap_asset)
+        .add_system(asset_loaded.after(cycle_cubemap_asset))
+        .add_system(camera_controller)
+        .add_system(animate_light_direction)
+        .run();
+}
+
+struct Cubemap {
+    is_loaded: bool,
+    index: usize,
+    image_handle: Handle<Image>,
+}
+
+fn setup(mut commands: Commands, asset_server: Res<AssetServer>) {
+    // directional 'sun' light
+    commands.spawn_bundle(DirectionalLightBundle {
+        directional_light: DirectionalLight {
+            illuminance: 32000.0,
+            ..default()
+        },
+        transform: Transform {
+            translation: Vec3::new(0.0, 2.0, 0.0),
+            rotation: Quat::from_rotation_x(-std::f32::consts::FRAC_PI_4),
+            ..default()
+        },
+        ..default()
+    });
+
+    let skybox_handle = asset_server.load(CUBEMAPS[0].0);
+    // camera
+    commands
+        .spawn_bundle(Camera3dBundle {
+            transform: Transform::from_xyz(0.0, 0.0, 8.0).looking_at(Vec3::default(), Vec3::Y),
+            ..default()
+        })
+        .insert(CameraController::default());
+
+    // ambient light
+    // NOTE: The ambient light is used to scale how bright the environment map is so with a bright
+    // environment map, use an appropriate colour and brightness to match
+    commands.insert_resource(AmbientLight {
+        color: Color::rgb_u8(210, 220, 240),
+        brightness: 1.0,
+    });
+
+    commands.insert_resource(Cubemap {
+        is_loaded: false,
+        index: 0,
+        image_handle: skybox_handle,
+    });
+}
+
+const CUBEMAP_SWAP_DELAY: f64 = 3.0;
+
+fn cycle_cubemap_asset(
+    time: Res<Time>,
+    mut next_swap: Local<f64>,
+    mut cubemap: ResMut<Cubemap>,
+    asset_server: Res<AssetServer>,
+    render_device: Res<RenderDevice>,
+) {
+    let now = time.seconds_since_startup();
+    if *next_swap == 0.0 {
+        *next_swap = now + CUBEMAP_SWAP_DELAY;
+        return;
+    } else if now < *next_swap {
+        return;
+    }
+    *next_swap += CUBEMAP_SWAP_DELAY;
+
+    let supported_compressed_formats =
+        CompressedImageFormats::from_features(render_device.features());
+
+    let mut new_index = cubemap.index;
+    for _ in 0..CUBEMAPS.len() {
+        new_index = (new_index + 1) % CUBEMAPS.len();
+        if supported_compressed_formats.contains(CUBEMAPS[new_index].1) {
+            break;
+        }
+        info!("Skipping unsupported format: {:?}", CUBEMAPS[new_index]);
+    }
+
+    // Skip swapping to the same texture. Useful for when ktx2, zstd, or compressed texture support
+    // is missing
+    if new_index == cubemap.index {
+        return;
+    }
+
+    cubemap.index = new_index;
+    cubemap.image_handle = asset_server.load(CUBEMAPS[cubemap.index].0);
+    cubemap.is_loaded = false;
+}
+
+fn asset_loaded(
+    mut commands: Commands,
+    asset_server: Res<AssetServer>,
+    mut images: ResMut<Assets<Image>>,
+    mut meshes: ResMut<Assets<Mesh>>,
+    mut cubemap_materials: ResMut<Assets<CubemapMaterial>>,
+    mut cubemap: ResMut<Cubemap>,
+    cubes: Query<&Handle<CubemapMaterial>>,
+) {
+    if !cubemap.is_loaded
+        && asset_server.get_load_state(cubemap.image_handle.clone_weak()) == LoadState::Loaded
+    {
+        info!("Swapping to {}...", CUBEMAPS[cubemap.index].0);
+        let mut image = images.get_mut(&cubemap.image_handle).unwrap();
+        // NOTE: PNGs do not have any metadata that could indicate they contain a cubemap texture,
+        // so they appear as one texture. The following code reconfigures the texture as necessary.
+        if image.texture_descriptor.array_layer_count() == 1 {
+            image.reinterpret_stacked_2d_as_array(
+                image.texture_descriptor.size.height / image.texture_descriptor.size.width,
+            );
+            image.texture_view_descriptor = Some(TextureViewDescriptor {
+                dimension: Some(TextureViewDimension::Cube),
+                ..default()
+            });
+        }
+
+        // spawn cube
+        let mut updated = false;
+        for handle in cubes.iter() {
+            if let Some(material) = cubemap_materials.get_mut(handle) {
+                updated = true;
+                material.base_color_texture = Some(cubemap.image_handle.clone_weak());
+            }
+        }
+        if !updated {
+            commands.spawn_bundle(MaterialMeshBundle::<CubemapMaterial> {
+                mesh: meshes.add(Mesh::from(shape::Cube { size: 10000.0 })),
+                material: cubemap_materials.add(CubemapMaterial {
+                    base_color_texture: Some(cubemap.image_handle.clone_weak()),
+                }),
+                ..default()
+            });
+        }
+
+        cubemap.is_loaded = true;
+    }
+}
+
+fn animate_light_direction(
+    time: Res<Time>,
+    mut query: Query<&mut Transform, With<DirectionalLight>>,
+) {
+    for mut transform in &mut query {
+        transform.rotate_y(time.delta_seconds() * 0.5);
+    }
+}
+
+#[derive(Debug, Clone, TypeUuid)]
+#[uuid = "9509a0f8-3c05-48ee-a13e-a93226c7f488"]
+struct CubemapMaterial {
+    base_color_texture: Option<Handle<Image>>,
+}
+
+impl Material for CubemapMaterial {
+    fn fragment_shader() -> ShaderRef {
+        "shaders/cubemap_unlit.wgsl".into()
+    }
+
+    fn specialize(
+        _pipeline: &MaterialPipeline<Self>,
+        descriptor: &mut RenderPipelineDescriptor,
+        _layout: &MeshVertexBufferLayout,
+        _key: MaterialPipelineKey<Self>,
+    ) -> Result<(), SpecializedMeshPipelineError> {
+        descriptor.primitive.cull_mode = None;
+        Ok(())
+    }
+}
+
+impl AsBindGroup for CubemapMaterial {
+    type Data = ();
+
+    fn as_bind_group(
+        &self,
+        layout: &BindGroupLayout,
+        render_device: &RenderDevice,
+        images: &RenderAssets<Image>,
+        _fallback_image: &FallbackImage,
+    ) -> Result<PreparedBindGroup<Self>, AsBindGroupError> {
+        let base_color_texture = self
+            .base_color_texture
+            .as_ref()
+            .ok_or(AsBindGroupError::RetryNextUpdate)?;
+        let image = images
+            .get(base_color_texture)
+            .ok_or(AsBindGroupError::RetryNextUpdate)?;
+        let bind_group = render_device.create_bind_group(&BindGroupDescriptor {
+            entries: &[
+                BindGroupEntry {
+                    binding: 0,
+                    resource: BindingResource::TextureView(&image.texture_view),
+                },
+                BindGroupEntry {
+                    binding: 1,
+                    resource: BindingResource::Sampler(&image.sampler),
+                },
+            ],
+            label: Some("cubemap_texture_material_bind_group"),
+            layout,
+        });
+
+        Ok(PreparedBindGroup {
+            bind_group,
+            bindings: vec![
+                OwnedBindingResource::TextureView(image.texture_view.clone()),
+                OwnedBindingResource::Sampler(image.sampler.clone()),
+            ],
+            data: (),
+        })
+    }
+
+    fn bind_group_layout(render_device: &RenderDevice) -> BindGroupLayout {
+        render_device.create_bind_group_layout(&BindGroupLayoutDescriptor {
+            entries: &[
+                // Cubemap Base Color Texture
+                BindGroupLayoutEntry {
+                    binding: 0,
+                    visibility: ShaderStages::FRAGMENT,
+                    ty: BindingType::Texture {
+                        multisampled: false,
+                        sample_type: TextureSampleType::Float { filterable: true },
+                        view_dimension: TextureViewDimension::Cube,
+                    },
+                    count: None,
+                },
+                // Cubemap Base Color Texture Sampler
+                BindGroupLayoutEntry {
+                    binding: 1,
+                    visibility: ShaderStages::FRAGMENT,
+                    ty: BindingType::Sampler(SamplerBindingType::Filtering),
+                    count: None,
+                },
+            ],
+            label: None,
+        })
+    }
+}
+
+#[derive(Component)]
+pub struct CameraController {
+    pub enabled: bool,
+    pub initialized: bool,
+    pub sensitivity: f32,
+    pub key_forward: KeyCode,
+    pub key_back: KeyCode,
+    pub key_left: KeyCode,
+    pub key_right: KeyCode,
+    pub key_up: KeyCode,
+    pub key_down: KeyCode,
+    pub key_run: KeyCode,
+    pub mouse_key_enable_mouse: MouseButton,
+    pub keyboard_key_enable_mouse: KeyCode,
+    pub walk_speed: f32,
+    pub run_speed: f32,
+    pub friction: f32,
+    pub pitch: f32,
+    pub yaw: f32,
+    pub velocity: Vec3,
+}
+
+impl Default for CameraController {
+    fn default() -> Self {
+        Self {
+            enabled: true,
+            initialized: false,
+            sensitivity: 0.5,
+            key_forward: KeyCode::W,
+            key_back: KeyCode::S,
+            key_left: KeyCode::A,
+            key_right: KeyCode::D,
+            key_up: KeyCode::E,
+            key_down: KeyCode::Q,
+            key_run: KeyCode::LShift,
+            mouse_key_enable_mouse: MouseButton::Left,
+            keyboard_key_enable_mouse: KeyCode::M,
+            walk_speed: 2.0,
+            run_speed: 6.0,
+            friction: 0.5,
+            pitch: 0.0,
+            yaw: 0.0,
+            velocity: Vec3::ZERO,
+        }
+    }
+}
+
+pub fn camera_controller(
+    time: Res<Time>,
+    mut mouse_events: EventReader<MouseMotion>,
+    mouse_button_input: Res<Input<MouseButton>>,
+    key_input: Res<Input<KeyCode>>,
+    mut move_toggled: Local<bool>,
+    mut query: Query<(&mut Transform, &mut CameraController), With<Camera>>,
+) {
+    let dt = time.delta_seconds();
+
+    if let Ok((mut transform, mut options)) = query.get_single_mut() {
+        if !options.initialized {
+            let (yaw, pitch, _roll) = transform.rotation.to_euler(EulerRot::YXZ);
+            options.yaw = yaw;
+            options.pitch = pitch;
+            options.initialized = true;
+        }
+        if !options.enabled {
+            return;
+        }
+
+        // Handle key input
+        let mut axis_input = Vec3::ZERO;
+        if key_input.pressed(options.key_forward) {
+            axis_input.z += 1.0;
+        }
+        if key_input.pressed(options.key_back) {
+            axis_input.z -= 1.0;
+        }
+        if key_input.pressed(options.key_right) {
+            axis_input.x += 1.0;
+        }
+        if key_input.pressed(options.key_left) {
+            axis_input.x -= 1.0;
+        }
+        if key_input.pressed(options.key_up) {
+            axis_input.y += 1.0;
+        }
+        if key_input.pressed(options.key_down) {
+            axis_input.y -= 1.0;
+        }
+        if key_input.just_pressed(options.keyboard_key_enable_mouse) {
+            *move_toggled = !*move_toggled;
+        }
+
+        // Apply movement update
+        if axis_input != Vec3::ZERO {
+            let max_speed = if key_input.pressed(options.key_run) {
+                options.run_speed
+            } else {
+                options.walk_speed
+            };
+            options.velocity = axis_input.normalize() * max_speed;
+        } else {
+            let friction = options.friction.clamp(0.0, 1.0);
+            options.velocity *= 1.0 - friction;
+            if options.velocity.length_squared() < 1e-6 {
+                options.velocity = Vec3::ZERO;
+            }
+        }
+        let forward = transform.forward();
+        let right = transform.right();
+        transform.translation += options.velocity.x * dt * right
+            + options.velocity.y * dt * Vec3::Y
+            + options.velocity.z * dt * forward;
+
+        // Handle mouse input
+        let mut mouse_delta = Vec2::ZERO;
+        if mouse_button_input.pressed(options.mouse_key_enable_mouse) || *move_toggled {
+            for mouse_event in mouse_events.iter() {
+                mouse_delta += mouse_event.delta;
+            }
+        }
+
+        if mouse_delta != Vec2::ZERO {
+            // Apply look update
+            let (pitch, yaw) = (
+                (options.pitch - mouse_delta.y * 0.5 * options.sensitivity * dt).clamp(
+                    -0.99 * std::f32::consts::FRAC_PI_2,
+                    0.99 * std::f32::consts::FRAC_PI_2,
+                ),
+                options.yaw - mouse_delta.x * options.sensitivity * dt,
+            );
+            transform.rotation = Quat::from_euler(EulerRot::ZYX, 0.0, yaw, pitch);
+            options.pitch = pitch;
+            options.yaw = yaw;
+        }
+    }
+}

examples/README.md

@@ -116,6 +116,7 @@ Example | Description
 [Render to Texture](../examples/3d/render_to_texture.rs) | Shows how to render to a texture, useful for mirrors, UI, or exporting images
 [Shadow Biases](../examples/3d/shadow_biases.rs) | Demonstrates how shadow biases affect shadows in a 3d scene
 [Shadow Caster and Receiver](../examples/3d/shadow_caster_receiver.rs) | Demonstrates how to prevent meshes from casting/receiving shadows in a 3d scene
+[Skybox](../examples/3d/skybox.rs) | Load a cubemap texture onto a cube like a skybox and cycle through different compressed texture formats.
 [Spherical Area Lights](../examples/3d/spherical_area_lights.rs) | Demonstrates how point light radius values affect light behavior
 [Split Screen](../examples/3d/split_screen.rs) | Demonstrates how to render two cameras to the same window to accomplish "split screen"
 [Spotlight](../examples/3d/spotlight.rs) | Illustrates spot lights