Gate LTC LUTs behind a feature and merge them to a texture array (#24065)

# Objective

Alternative to #24004.

#23288 adds ltc luts for rect
light support which implicitly requires `bevy_image/ktx2` and
`bevy_image/zstd` otherwise loading ltc luts will panic.

We either accept to always enable area light supoort (#24004), or add a
feature to opt out it (this PR).

## Solution

Gate ltc luts behind a feature and merge them to a texture array.

## Testing

`rect_light` example works.

---------

Co-authored-by: Kevin Chen <chen.kevin.f@gmail.com>

Author: beicause

.github/workflows/example-run.yml

@@ -52,7 +52,7 @@ jobs:
             example_name=`basename $example .ron`
             echo -n $example_name > last_example_run
             echo "running $example_name - "`date`
-            time TRACE_CHROME=trace-$example_name.json CI_TESTING_CONFIG=$example cargo run --example $example_name --features "bevy_ci_testing,trace,trace_chrome,bevy_ui_debug"
+            time TRACE_CHROME=trace-$example_name.json CI_TESTING_CONFIG=$example cargo run --example $example_name --features "bevy_ci_testing,trace,trace_chrome,bevy_ui_debug,area_light_luts"
             sleep 10
             if [ `find ./ -maxdepth 1 -name 'screenshot-*.png' -print -quit` ]; then
               mkdir screenshots-$example_name
@@ -132,7 +132,7 @@ jobs:
             example_name=`basename $example .ron`
             echo -n $example_name > last_example_run
             echo "running $example_name - "`date`
-            time TRACE_CHROME=trace-$example_name.json CI_TESTING_CONFIG=$example xvfb-run cargo run --example $example_name --features "bevy_ci_testing,trace,trace_chrome,bevy_ui_debug"
+            time TRACE_CHROME=trace-$example_name.json CI_TESTING_CONFIG=$example xvfb-run cargo run --example $example_name --features "bevy_ci_testing,trace,trace_chrome,bevy_ui_debug,area_light_luts"
             sleep 10
             if [ `find ./ -maxdepth 1 -name 'screenshot-*.png' -print -quit` ]; then
               mkdir screenshots-$example_name
@@ -202,7 +202,7 @@ jobs:
             example_name=`basename $example .ron`
             echo -n $example_name > last_example_run
             echo "running $example_name - "`date`
-            time WGPU_BACKEND=dx12 TRACE_CHROME=trace-$example_name.json CI_TESTING_CONFIG=$example cargo run --example $example_name --features "statically-linked-dxc,bevy_ci_testing,trace,trace_chrome,bevy_ui_debug"
+            time WGPU_BACKEND=dx12 TRACE_CHROME=trace-$example_name.json CI_TESTING_CONFIG=$example cargo run --example $example_name --features "statically-linked-dxc,bevy_ci_testing,trace,trace_chrome,bevy_ui_debug,area_light_luts"
             sleep 10
             if [ `find ./ -maxdepth 1 -name 'screenshot-*.png' -print -quit` ]; then
               mkdir screenshots-$example_name

Cargo.toml

@@ -579,6 +579,9 @@ bluenoise_texture = ["bevy_internal/bluenoise_texture"]
 # Include a preintegrated BRDF Look Up Table for more accurate specular shading.
 dfg_lut = ["bevy_internal/dfg_lut"]
 
+# Include Look Up Tables that are required for area lights.
+area_light_luts = ["bevy_internal/area_light_luts"]
+
 # NVIDIA Deep Learning Super Sampling
 dlss = ["bevy_internal/dlss"]
 
@@ -1195,7 +1198,7 @@ wasm = true
 name = "rect_light"
 path = "examples/3d/rect_light.rs"
 doc-scrape-examples = true
-required-features = ["free_camera"]
+required-features = ["free_camera", "area_light_luts"]
 
 [package.metadata.example.rect_light]
 name = "Rectangular Area Light"
@@ -5209,6 +5212,7 @@ hidden = true
 name = "testbed_3d"
 path = "examples/testbed/3d.rs"
 doc-scrape-examples = true
+required-features = ["area_light_luts"]
 
 [package.metadata.example.testbed_3d]
 hidden = true

_release-content/release-notes/area_lights.md

@@ -12,4 +12,6 @@ The implementation uses [Linearly Transformed Cosines](https://eheitzresearch.wo
 
 Rectangular lights currently don't cast shadows or have support for anisotropic materials.
 
+You need to enable the `area_light_luts` cargo feature to use it.
+
 Check out [the new example](https://github.com/bevyengine/bevy/tree/latest/examples/3d/rect_light.rs) to see them in action.

crates/bevy_internal/Cargo.toml

@@ -90,6 +90,9 @@ bluenoise_texture = ["bevy_pbr?/bluenoise_texture", "ktx2", "bevy_image/zstd"]
 # Include a preintegrated BRDF Look Up Table for more accurate specular shading.
 dfg_lut = ["bevy_pbr?/dfg_lut", "ktx2", "bevy_image/zstd"]
 
+# Include Look Up Tables that are required for area lights.
+area_light_luts = ["bevy_pbr?/area_light_luts", "ktx2", "bevy_image/zstd"]
+
 # NVIDIA Deep Learning Super Sampling
 dlss = ["bevy_anti_alias/dlss", "bevy_solari?/dlss"]
 

crates/bevy_light/src/rect_light.rs

@@ -13,6 +13,8 @@ use crate::light_consts;
 ///
 /// Shadow maps are currently unsupported, objects illuminated by a
 /// ``RectLight`` will not cast shadows.
+///
+/// Note: Requires the `area_light_luts` cargo feature.
 #[derive(Component, Debug, Clone, Copy, Reflect)]
 #[reflect(Component, Default, Debug, Clone)]
 #[require(Transform, Visibility, VisibilityClass)]

crates/bevy_pbr/Cargo.toml

@@ -22,6 +22,7 @@ pbr_clustered_decals = []
 pbr_light_textures = []
 bluenoise_texture = ["bevy_image/ktx2", "bevy_image/zstd"]
 dfg_lut = ["bevy_image/ktx2", "bevy_image/zstd"]
+area_light_luts = ["bevy_image/ktx2", "bevy_image/zstd"]
 shader_format_glsl = ["bevy_shader/shader_format_glsl"]
 trace = ["bevy_render/trace"]
 # Enables the meshlet renderer for dense high-poly scenes (experimental)

crates/bevy_pbr/src/lib.rs

@@ -107,14 +107,14 @@ use bevy_asset::{AssetApp, AssetPath, Assets, Handle, RenderAssetUsages};
 use bevy_core_pipeline::mip_generation::experimental::depth::early_downsample_depth;
 use bevy_core_pipeline::schedule::{Core3d, Core3dSystems};
 use bevy_ecs::prelude::*;
-use bevy_image::{CompressedImageFormats, Image, ImageSampler, ImageType};
+use bevy_image::{Image, ImageSampler};
 use bevy_material::AlphaMode;
 use bevy_render::{
     camera::sort_cameras,
     extract_resource::ExtractResourcePlugin,
     render_resource::{
         Extent3d, TextureDataOrder, TextureDescriptor, TextureDimension, TextureFormat,
-        TextureUsages,
+        TextureUsages, TextureViewDescriptor, TextureViewDimension,
     },
     sync_component::SyncComponentPlugin,
     ExtractSchedule, GpuResourceAppExt, Render, RenderApp, RenderDebugFlags, RenderStartup,
@@ -169,14 +169,14 @@ pub struct Bluenoise {
 
 /// LTC (Linearly Transformed Cosines) LUT textures for area light shading.
 ///
-/// `ltc_1` encodes the 4 non-trivial elements of the inverse GGX LTC matrix.
-/// `ltc_2` encodes amplitude and Fresnel-related weights.
+/// It is a texture array containing 2 LUT textures:
+/// The first entry encodes the 4 non-trivial elements of the inverse GGX LTC matrix.
+/// The second entry encodes amplitude and Fresnel-related weights.
 ///
 /// [LUT source and fitting code](https://github.com/selfshadow/ltc_code/blob/master/fit/results)
 #[derive(Resource, Clone)]
-pub struct LtcLuts {
-    pub ltc_1: Handle<Image>,
-    pub ltc_2: Handle<Image>,
+pub struct AreaLightLuts {
+    pub image: Handle<Image>,
 }
 
 // See https://github.com/bevyengine/bevy/pull/23737 for information on how the LUT was generated.
@@ -282,15 +282,16 @@ impl Plugin for PbrPlugin {
             let mut images = app.world_mut().resource_mut::<Assets<Image>>();
             #[cfg(feature = "bluenoise_texture")]
             let handle = {
-                let image = Image::from_buffer(
+                let mut image = Image::from_buffer(
                     include_bytes!("bluenoise/stbn.ktx2"),
-                    ImageType::Extension("ktx2"),
-                    CompressedImageFormats::NONE,
+                    bevy_image::ImageType::Extension("ktx2"),
+                    bevy_image::CompressedImageFormats::NONE,
                     false,
                     ImageSampler::Default,
                     RenderAssetUsages::RENDER_WORLD,
                 )
                 .expect("Failed to decode embedded blue-noise texture");
+                image.texture_descriptor.label = Some("bluenoise");
                 images.add(image)
             };
 
@@ -304,39 +305,32 @@ impl Plugin for PbrPlugin {
             }
         }
 
-        let has_ltc_luts = app
+        let has_area_light_luts = app
             .get_sub_app(RenderApp)
-            .is_some_and(|render_app| render_app.world().is_resource_added::<LtcLuts>());
+            .is_some_and(|render_app| render_app.world().is_resource_added::<AreaLightLuts>());
 
-        if !has_ltc_luts {
+        if !has_area_light_luts {
             let mut images = app.world_mut().resource_mut::<Assets<Image>>();
-            let ltc_luts = LtcLuts {
-                ltc_1: images.add(
-                    Image::from_buffer(
-                        include_bytes!("ltc/ltc1.ktx2"),
-                        ImageType::Extension("ktx2"),
-                        CompressedImageFormats::NONE,
-                        false,
-                        ImageSampler::linear(),
-                        RenderAssetUsages::RENDER_WORLD,
-                    )
-                    .expect("Failed to decode embedded LTC LUT 1"),
-                ),
-                ltc_2: images.add(
-                    Image::from_buffer(
-                        include_bytes!("ltc/ltc2.ktx2"),
-                        ImageType::Extension("ktx2"),
-                        CompressedImageFormats::NONE,
-                        false,
-                        ImageSampler::linear(),
-                        RenderAssetUsages::RENDER_WORLD,
-                    )
-                    .expect("Failed to decode embedded LTC LUT 2"),
-                ),
+            #[cfg(feature = "area_light_luts")]
+            let handle = {
+                let mut image = Image::from_buffer(
+                    include_bytes!("ltc/ltc.ktx2"),
+                    bevy_image::ImageType::Extension("ktx2"),
+                    bevy_image::CompressedImageFormats::NONE,
+                    false,
+                    ImageSampler::linear(),
+                    RenderAssetUsages::RENDER_WORLD,
+                )
+                .expect("Failed to decode embedded LTC LUTs");
+                image.texture_descriptor.label = Some("area_light_luts");
+                images.add(image)
             };
+            #[cfg(not(feature = "area_light_luts"))]
+            let handle = images.add(area_light_luts_placeholder());
 
+            let area_light_luts = AreaLightLuts { image: handle };
             if let Some(render_app) = app.get_sub_app_mut(RenderApp) {
-                render_app.world_mut().insert_resource(ltc_luts);
+                render_app.world_mut().insert_resource(area_light_luts);
             }
         }
 
@@ -349,8 +343,8 @@ impl Plugin for PbrPlugin {
             let texture = app.world_mut().resource_mut::<Assets<Image>>().add(
                 Image::from_buffer(
                     include_bytes!("environment_map/dfg.ktx2"),
-                    ImageType::Extension("ktx2"),
-                    CompressedImageFormats::NONE,
+                    bevy_image::ImageType::Extension("ktx2"),
+                    bevy_image::CompressedImageFormats::NONE,
                     false,
                     ImageSampler::linear(),
                     RenderAssetUsages::RENDER_WORLD,
@@ -468,7 +462,7 @@ pub fn stbn_placeholder() -> Image {
             size: Extent3d::default(),
             format,
             dimension: TextureDimension::D2,
-            label: None,
+            label: Some("bluenoise_placeholder"),
             mip_level_count: 1,
             sample_count: 1,
             usage: TextureUsages::TEXTURE_BINDING,
@@ -481,6 +475,36 @@ pub fn stbn_placeholder() -> Image {
     }
 }
 
+pub fn area_light_luts_placeholder() -> Image {
+    let format = TextureFormat::Rgba16Float;
+    let data = vec![0; 16];
+    Image {
+        data: Some(data),
+        data_order: TextureDataOrder::default(),
+        texture_descriptor: TextureDescriptor {
+            size: Extent3d {
+                width: 1,
+                height: 1,
+                depth_or_array_layers: 2,
+            },
+            format,
+            dimension: TextureDimension::D2,
+            label: Some("area_light_luts_placeholder"),
+            mip_level_count: 1,
+            sample_count: 1,
+            usage: TextureUsages::TEXTURE_BINDING,
+            view_formats: &[],
+        },
+        sampler: ImageSampler::Default,
+        texture_view_descriptor: Some(TextureViewDescriptor {
+            dimension: Some(TextureViewDimension::D2Array),
+            ..Default::default()
+        }),
+        asset_usage: RenderAssetUsages::RENDER_WORLD,
+        copy_on_resize: false,
+    }
+}
+
 impl SyncComponent<PbrPlugin> for DirectionalLight {
     type Target = (
         Self,