Add broad support for texture access (#560)

Add support for accessing most types of WGSL textures, both with
filtering
(sampler in fragment shader) and without (direct value loading). The
former
extends the existing `TextureSampleExpr` while the latter adds a new
`TextureLoadExpr`.

This change forces the `TextureSampleExpr` slot back into a CPU
constant. To dynamically switch between texture, use an array texture
with a `layer_index` expression instead.

Add a new `lut.rs` example showing how to use a `TextureLoadExpr` inside
the
Update pass to read a 2D array texture used as a look-up table (LUT).

Author: djeedai

CHANGELOG.md

@@ -12,6 +12,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added `HanabiMainCamera`, a component to tag the "main" camera that Hanabi uses
   for camera-specific features. Add to exactly one `Camera` to tag it.
 - Added `KillFrustumModifier` to kill particles outside of the main camera frustum.
+- Added the ability to access the effect's material (the user bound textures) from all passes.
+- Added support for 1D and 3D textures, and 2D array textures, as well as cube textures
+  and depth textures, to the `TextureSampleExpr`. See `SlotDimension` for all supported variants.
+- Added a new `TextureLoadExpr` doing a non-sampling texture load (`textureLoad()` in WGSL).
+  This can be used in all passes (all modifier contexts).
+- Added a new `lut.rs` example that demonstrates using a 2D array texture as a look-up table (LUT).
+  This can be used to approximate any kind of curve or gradient.
 
 ### Changed
 
@@ -22,6 +29,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   available for GPU particle spawning.
 - Parallelized most of the GPU sort. This dramatically improves performance when using ribbon effects.
 - `EvalContext::make_fn()` now takes an optional return token for the function return value.
+- Renamed `TextureSampleExpr::image` to `slot_index`, and changed its type to be a `u32` slot index
+  defined at module build time. Dynamically switching between texture with a slot expression
+  was broken, and is explicitly not supported anymore. If you want to dynamically switch between textures,
+  consider using an array texture instead, which is a better way to achieve the same result.
+- Added `TextureSlot::dimension` to specify the type of texture that a texture slot accepts.
+- Added `TextureSampleExpr::slot_dimension` to specify the type of texture being sampled.
+  This must match the associated slot's `TextureSlot::dimension` when bound.
+- `TextureSamplerExpr` now correctly returns an error if used from any pass but the Render one,
+  instead of generating invalid WGSL code. This is a restriction of the WGSL language itself
+  (sampled texture read, via `textureSample()`, can only be used in the fragment shader).
 
 ### Fixed
 

Cargo.toml

@@ -165,6 +165,9 @@ name = "puffs"
 [[example]]
 name = "lightning"
 
+[[example]]
+name = "lut"
+
 [[test]]
 name = "empty_effect"
 path = "gpu_tests/empty_effect.rs"

build_examples_wasm.bat

@@ -6,7 +6,6 @@ echo Setting RUSTFLAGS to enable unstable web_sys APIs...
 set RUSTFLAGS=--cfg web_sys_unstable_apis --cfg getrandom_backend="wasm_js"
 
 echo Build all examples for WASM...
-REM 3D
 cargo b --release --example lightning --target wasm32-unknown-unknown --features="bevy/webgpu"
 cargo b --release --example firework --target wasm32-unknown-unknown --features="bevy/webgpu"
 cargo b --release --example portal --target wasm32-unknown-unknown --features="bevy/webgpu"
@@ -22,14 +21,13 @@ cargo b --release --example init --target wasm32-unknown-unknown --features="bev
 cargo b --release --example lifetime --target wasm32-unknown-unknown --features="bevy/webgpu"
 cargo b --release --example ordering --target wasm32-unknown-unknown --features="bevy/webgpu"
 cargo b --release --example ribbon --target wasm32-unknown-unknown --features="bevy/webgpu"
-REM 3D + PNG
 cargo b --release --example gradient --target wasm32-unknown-unknown --features="bevy/webgpu"
 cargo b --release --example circle --target wasm32-unknown-unknown --features="bevy/webgpu"
 cargo b --release --example billboard --target wasm32-unknown-unknown --features="bevy/webgpu"
 cargo b --release --example worms --target wasm32-unknown-unknown --features="bevy/webgpu"
 cargo b --release --example instancing --target wasm32-unknown-unknown --features="bevy/webgpu"
 cargo b --release --example puffs --target wasm32-unknown-unknown --features="bevy/webgpu"
-REM 2D
+cargo b --release --example lut --target wasm32-unknown-unknown --features="bevy/webgpu"
 cargo b --release --example 2d --target wasm32-unknown-unknown --features="bevy/webgpu"
 
 wasm-bindgen --out-name wasm_lightning --no-typescript --out-dir examples/wasm/target --target web target/wasm32-unknown-unknown/release/examples/lightning.wasm
@@ -53,6 +51,7 @@ wasm-bindgen --out-name wasm_billboard --no-typescript --out-dir examples/wasm/t
 wasm-bindgen --out-name wasm_worms --no-typescript --out-dir examples/wasm/target --target web target/wasm32-unknown-unknown/release/examples/worms.wasm
 wasm-bindgen --out-name wasm_instancing --no-typescript --out-dir examples/wasm/target --target web target/wasm32-unknown-unknown/release/examples/instancing.wasm
 wasm-bindgen --out-name wasm_puffs --out-dir examples/wasm/target --target web target/wasm32-unknown-unknown/release/examples/puffs.wasm
+wasm-bindgen --out-name wasm_lut --out-dir examples/wasm/target --target web target/wasm32-unknown-unknown/release/examples/lut.wasm
 wasm-bindgen --out-name wasm_2d --no-typescript --out-dir examples/wasm/target --target web target/wasm32-unknown-unknown/release/examples/2d.wasm
 
 echo Done. See docs/wasm.md for help on running the examples locally.

build_examples_wasm.sh

@@ -4,7 +4,6 @@ echo Setting RUSTFLAGS to enable unstable web_sys APIs...
 export RUSTFLAGS=--cfg=web_sys_unstable_apis
 
 echo Build all examples for WASM...
-# 3D
 cargo b --release --example lightning --target wasm32-unknown-unknown
 cargo b --release --example firework --target wasm32-unknown-unknown
 cargo b --release --example portal --target wasm32-unknown-unknown
@@ -20,14 +19,13 @@ cargo b --release --example init --target wasm32-unknown-unknown
 cargo b --release --example lifetime --target wasm32-unknown-unknown
 cargo b --release --example ordering --target wasm32-unknown-unknown
 cargo b --release --example ribbon --target wasm32-unknown-unknown
-# 3D + PNG
-cargo b --release --example
+cargo b --release --example gradient --target wasm32-unknown-unknown
 cargo b --release --example circle --target wasm32-unknown-unknown
 cargo b --release --example billboard --target wasm32-unknown-unknown
 cargo b --release --example worms --target wasm32-unknown-unknown
 cargo b --release --example instancing --target wasm32-unknown-unknown
 cargo b --release --example puffs --target wasm32-unknown-unknown
-# 2D
+cargo b --release --example lut --target wasm32-unknown-unknown
 cargo b --release --example 2d --target wasm32-unknown-unknown
 
 echo Bindgen all examples...
@@ -52,6 +50,7 @@ wasm-bindgen --out-name wasm_billboard --out-dir examples/wasm/target --target w
 wasm-bindgen --out-name wasm_worms --out-dir examples/wasm/target --target web target/wasm32-unknown-unknown/release/examples/worms.wasm
 wasm-bindgen --out-name wasm_instancing --out-dir examples/wasm/target --target web target/wasm32-unknown-unknown/release/examples/instancing.wasm
 wasm-bindgen --out-name wasm_puffs --out-dir examples/wasm/target --target web target/wasm32-unknown-unknown/release/examples/puffs.wasm
+wasm-bindgen --out-name wasm_lut --out-dir examples/wasm/target --target web target/wasm32-unknown-unknown/release/examples/lut.wasm
 wasm-bindgen --out-name wasm_2d --out-dir examples/wasm/target --target web target/wasm32-unknown-unknown/release/examples/2d.wasm
 
 echo Done. See docs/wasm.md for help on running the examples locally.

examples/billboard.rs

@@ -113,10 +113,8 @@ fn setup(
     // per-particle rotation)
     let rotation_attr = writer.attr(Attribute::F32_0).expr();
 
-    let texture_slot = writer.lit(0u32).expr();
-
     let mut module = writer.finish();
-    module.add_texture_slot("color");
+    module.add_texture_slot("color", SlotDimension::D2);
 
     let effect = effects.add(
         EffectAsset::new(32768, SpawnerSettings::rate(64.0.into()), module)
@@ -129,7 +127,7 @@ fn setup(
             .init(init_rotation)
             .init(init_color)
             .render(ParticleTextureModifier {
-                texture_slot,
+                texture_slot: 0,
                 sample_mapping: ImageSampleMapping::ModulateOpacityFromR,
             })
             .render(OrientModifier {

examples/circle.rs

@@ -112,12 +112,9 @@ fn setup(
         .expr();
     let update_sprite_index = SetAttributeModifier::new(Attribute::SPRITE_INDEX, sprite_index);
 
-    let texture_slot = writer.lit(0u32).expr();
-    let texture_slot2 = writer.lit(1u32).expr();
-
     let mut module = writer.finish();
-    module.add_texture_slot("color");
-    module.add_texture_slot("shape");
+    module.add_texture_slot("color", SlotDimension::D2);
+    module.add_texture_slot("shape", SlotDimension::D2);
 
     let effect = effects.add(
         EffectAsset::new(
@@ -132,11 +129,11 @@ fn setup(
         .init(init_lifetime)
         .update(update_sprite_index)
         .render(ParticleTextureModifier {
-            texture_slot,
+            texture_slot: 0,
             sample_mapping: ImageSampleMapping::ModulateOpacityFromR,
         })
         .render(ParticleTextureModifier {
-            texture_slot: texture_slot2,
+            texture_slot: 1,
             sample_mapping: ImageSampleMapping::ModulateRGB,
         })
         .render(FlipbookModifier { sprite_grid_size })

examples/gradient.rs

@@ -68,12 +68,9 @@ fn setup(
         speed: writer.lit(2.).expr(),
     };
 
-    // Use texture slot #0 in ParticleTextureModifier
-    let texture_slot = writer.lit(0u32).expr();
-
     // Define that texture slot (giving it a name for convenience)
     let mut module = writer.finish();
-    module.add_texture_slot("color");
+    module.add_texture_slot("color", SlotDimension::D2);
 
     let effect = effects.add(
         EffectAsset::new(32768, SpawnerSettings::rate(1000.0.into()), module)
@@ -83,7 +80,7 @@ fn setup(
             .init(init_age)
             .init(init_lifetime)
             .render(ParticleTextureModifier {
-                texture_slot,
+                texture_slot: 0,
                 sample_mapping: ImageSampleMapping::ModulateOpacityFromR,
             })
             .render(ColorOverLifetimeModifier::new(gradient)),

examples/instancing.rs

@@ -281,14 +281,12 @@ fn setup(
     let radial_accel =
         RadialAccelModifier::new(writer.lit(Vec3::ZERO).expr(), writer.lit(-3).expr());
 
-    let texture_slot = writer.lit(0u32).expr();
-
     let prop_color = writer.add_property("prop_color", 0xFFFFFFFFu32.into());
     let prop_color = writer.prop(prop_color);
     let update_col = SetAttributeModifier::new(Attribute::COLOR, prop_color.expr());
 
     let mut module = writer.finish();
-    module.add_texture_slot("color");
+    module.add_texture_slot("color", SlotDimension::D2);
 
     let alt_effect = effects.add(
         EffectAsset::new(512, SpawnerSettings::rate(102.0.into()), module)
@@ -300,7 +298,7 @@ fn setup(
             .update(radial_accel)
             .update(update_col)
             .render(ParticleTextureModifier {
-                texture_slot,
+                texture_slot: 0,
                 sample_mapping: ImageSampleMapping::Modulate,
             }),
     );