StandardMaterial Light Transmission

Cargo.toml

@@ -71,7 +71,11 @@ bevy_asset = ["bevy_internal/bevy_asset"]
 bevy_audio = ["bevy_internal/bevy_audio"]
 
 # Provides cameras and other basic render pipeline features
-bevy_core_pipeline = ["bevy_internal/bevy_core_pipeline", "bevy_asset", "bevy_render"]
+bevy_core_pipeline = [
+ "bevy_internal/bevy_core_pipeline",
+ "bevy_asset",
+ "bevy_render",
+]
 
 # Plugin for dynamic loading (using [libloading](https://crates.io/crates/libloading))
 bevy_dynamic_plugin = ["bevy_internal/bevy_dynamic_plugin"]
@@ -83,7 +87,12 @@ bevy_gilrs = ["bevy_internal/bevy_gilrs"]
 bevy_gltf = ["bevy_internal/bevy_gltf", "bevy_asset", "bevy_scene", "bevy_pbr"]
 
 # Adds PBR rendering
-bevy_pbr = ["bevy_internal/bevy_pbr", "bevy_asset", "bevy_render", "bevy_core_pipeline"]
+bevy_pbr = [
+ "bevy_internal/bevy_pbr",
+ "bevy_asset",
+ "bevy_render",
+ "bevy_core_pipeline",
+]
 
 # Provides rendering functionality
 bevy_render = ["bevy_internal/bevy_render"]
@@ -98,7 +107,12 @@ bevy_sprite = ["bevy_internal/bevy_sprite", "bevy_render", "bevy_core_pipeline"]
 bevy_text = ["bevy_internal/bevy_text", "bevy_asset", "bevy_sprite"]
 
 # A custom ECS-driven UI framework
-bevy_ui = ["bevy_internal/bevy_ui", "bevy_core_pipeline", "bevy_text", "bevy_sprite"]
+bevy_ui = [
+ "bevy_internal/bevy_ui",
+ "bevy_core_pipeline",
+ "bevy_text",
+ "bevy_sprite",
+]
 
 # winit window and input backend
 bevy_winit = ["bevy_internal/bevy_winit"]
@@ -113,7 +127,11 @@ trace_chrome = ["trace", "bevy_internal/trace_chrome"]
 trace_tracy = ["trace", "bevy_internal/trace_tracy"]
 
 # Tracing support, with memory profiling, exposing a port for Tracy
-trace_tracy_memory = ["trace", "bevy_internal/trace_tracy", "bevy_internal/trace_tracy_memory"]
+trace_tracy_memory = [
+ "trace",
+ "bevy_internal/trace_tracy",
+ "bevy_internal/trace_tracy_memory",
+]
 
 # Tracing support
 trace = ["bevy_internal/trace"]
@@ -241,6 +259,9 @@ shader_format_glsl = ["bevy_internal/shader_format_glsl"]
 # Enable support for shaders in SPIR-V
 shader_format_spirv = ["bevy_internal/shader_format_spirv"]
 
+# Enable support for transmission-related textures in the `StandardMaterial`, at the risk of blowing past the global, per-shader texture limit on older/lower-end GPUs
+pbr_transmission_textures = ["bevy_internal/pbr_transmission_textures"]
+
 # Enable some limitations to be able to use WebGL2. If not enabled, it will default to WebGPU in Wasm. Please refer to the [WebGL2 and WebGPU](https://github.com/bevyengine/bevy/tree/latest/examples#webgl2-and-webgpu) section of the examples README for more information on how to run Wasm builds with WebGPU.
 webgl2 = ["bevy_internal/webgl"]
 
@@ -778,6 +799,16 @@ description = "Demonstrates transparency in 3d"
 category = "3D Rendering"
 wasm = true
 
+[[example]]
+name = "transmission"
+path = "examples/3d/transmission.rs"
+
+[package.metadata.example.transmission]
+name = "Transmission"
+description = "Showcases light transmission in the PBR material"
+category = "3D Rendering"
+wasm = true
+
 [[example]]
 name = "two_passes"
 path = "examples/3d/two_passes.rs"

assets/shaders/show_prepass.wgsl

@@ -23,7 +23,11 @@ fn fragment(
  let sample_index = 0u;
 #endif
  if settings.show_depth == 1u {
+#ifdef WEBGL2
+ let depth = 0.0;
+#else
  let depth = bevy_pbr::prepass_utils::prepass_depth(mesh.position, sample_index);
+#endif
  return vec4(depth, depth, depth, 1.0);
  } else if settings.show_normals == 1u {
  let normal = bevy_pbr::prepass_utils::prepass_normal(mesh.position, sample_index);

crates/bevy_core_pipeline/src/core_3d/camera_3d.rs

@@ -20,11 +20,33 @@ use serde::{Deserialize, Serialize};
 #[reflect(Component)]
 pub struct Camera3d {
  /// The clear color operation to perform for the main 3d pass.
+ ///
+ /// **Note:** When [`Camera3d::screen_space_specular_transmission_steps`] > `0`, a fully opaque clear
+ /// color will “cover” the environment map light's texture, preventing it from
+ /// being refracted “through” transmissive objects, even if there are no opaque
+ /// objects behind them. To work around this issue, consider using a clear color
+ /// with an alpha value of `0.0`.
  pub clear_color: ClearColorConfig,
  /// The depth clear operation to perform for the main 3d pass.
  pub depth_load_op: Camera3dDepthLoadOp,
  /// The texture usages for the depth texture created for the main 3d pass.
  pub depth_texture_usages: Camera3dDepthTextureUsage,
+ /// How many individual steps should be performed in the [`Transmissive3d`](crate::core_3d::Transmissive3d) pass.
+ ///
+ /// Roughly corresponds to how many “layers of transparency” are rendered for screen space
+ /// specular transmissive objects. Each step requires making one additional
+ /// texture copy, so it's recommended to keep this number to a resonably low value. Defaults to `1`.
+ ///
+ /// Setting this to `0` disables the screen-space refraction effect entirely, and falls
+ /// back to refracting only the environment map light's texture.
+ pub screen_space_specular_transmission_steps: usize,
+ /// The quality of the screen space specular transmission blur effect, applied to the whatever's “behind” transmissive
+ /// objects when their `roughness` is greater than `0.0`.
+ ///
+ /// Higher qualities are more GPU-intensive.
+ ///
+ /// **Note:** You can get better-looking results at any quality level by enabling TAA. See: [`TemporalAntiAliasPlugin`](crate::experimental::taa::TemporalAntiAliasPlugin).
+ pub screen_space_specular_transmission_quality: ScreenSpaceTransmissionQuality,
 }
 
 impl Default for Camera3d {
@@ -33,6 +55,8 @@ impl Default for Camera3d {
  clear_color: ClearColorConfig::Default,
  depth_load_op: Default::default(),
  depth_texture_usages: TextureUsages::RENDER_ATTACHMENT.into(),
+ screen_space_specular_transmission_steps: 1,
+ screen_space_specular_transmission_quality: Default::default(),
  }
  }
 }
@@ -77,6 +101,37 @@ impl From<Camera3dDepthLoadOp> for LoadOp<f32> {
  }
 }
 
+/// The quality of the screen space transmission blur effect, applied to the whatever's “behind” transmissive
+/// objects when their `roughness` is greater than `0.0`.
+///
+/// Higher qualities are more GPU-intensive.
+///
+/// **Note:** You can get better-looking results at any quality level by enabling TAA. See: [`TemporalAntiAliasPlugin`](crate::experimental::taa::TemporalAntiAliasPlugin).
+#[derive(Resource, Default, Clone, Copy, Reflect, PartialEq, PartialOrd, Debug)]
+#[reflect(Resource)]
+pub enum ScreenSpaceTransmissionQuality {
+ /// Best performance at the cost of quality. Suitable for lower end GPUs. (e.g. Mobile)
+ ///
+ /// `num_taps` = 4
+ Low,
+
+ /// A balanced option between quality and performance.
+ ///
+ /// `num_taps` = 8
+ #[default]
+ Medium,
+
+ /// Best quality. Suitable for high end GPUs. (e.g. Desktop)
+ ///
+ /// `num_taps` = 16
+ High,
+
+ /// The highest quality, suitable for non-realtime rendering. (e.g. Pre-rendered cinematics and photo mode)
+ ///
+ /// `num_taps` = 32
+ Ultra,
+}
+
 #[derive(Bundle)]
 pub struct Camera3dBundle {
  pub camera: Camera,

crates/bevy_core_pipeline/src/core_3d/main_transmissive_pass_3d_node.rs

@@ -0,0 +1,148 @@
+use super::{Camera3d, ViewTransmissionTexture};
+use crate::core_3d::Transmissive3d;
+use bevy_ecs::{prelude::*, query::QueryItem};
+use bevy_render::{
+ camera::ExtractedCamera,
+ render_graph::{NodeRunError, RenderGraphContext, ViewNode},
+ render_phase::RenderPhase,
+ render_resource::{
+ Extent3d, LoadOp, Operations, RenderPassDepthStencilAttachment, RenderPassDescriptor,
+ },
+ renderer::RenderContext,
+ view::{ViewDepthTexture, ViewTarget},
+};
+#[cfg(feature = "trace")]
+use bevy_utils::tracing::info_span;
+use std::ops::Range;
+
+/// A [`bevy_render::render_graph::Node`] that runs the [`Transmissive3d`] [`RenderPhase`].
+#[derive(Default)]
+pub struct MainTransmissivePass3dNode;
+
+impl ViewNode for MainTransmissivePass3dNode {
+ type ViewQuery = (
+ &'static ExtractedCamera,
+ &'static Camera3d,
+ &'static RenderPhase<Transmissive3d>,
+ &'static ViewTarget,
+ Option<&'static ViewTransmissionTexture>,
+ &'static ViewDepthTexture,
+ );
+
+ fn run(
+ &self,
+ graph: &mut RenderGraphContext,
+ render_context: &mut RenderContext,
+ (camera, camera_3d, transmissive_phase, target, transmission, depth): QueryItem<
+ Self::ViewQuery,
+ >,
+ world: &World,
+ ) -> Result<(), NodeRunError> {
+ let view_entity = graph.view_entity();
+
+ let physical_target_size = camera.physical_target_size.unwrap();
+
+ let render_pass_descriptor = RenderPassDescriptor {
+ label: Some("main_transmissive_pass_3d"),
+ // NOTE: The transmissive pass loads the color buffer as well as overwriting it where appropriate.
+ color_attachments: &[Some(target.get_color_attachment(Operations {
+ load: LoadOp::Load,
+ store: true,
+ }))],
+ depth_stencil_attachment: Some(RenderPassDepthStencilAttachment {
+ view: &depth.view,
+ // NOTE: The transmissive main pass loads the depth buffer and possibly overwrites it
+ depth_ops: Some(Operations {
+ load: LoadOp::Load,
+ store: true,
+ }),
+ stencil_ops: None,
+ }),
+ };
+
+ // Run the transmissive pass, sorted back-to-front
+ // NOTE: Scoped to drop the mutable borrow of render_context
+ #[cfg(feature = "trace")]
+ let _main_transmissive_pass_3d_span = info_span!("main_transmissive_pass_3d").entered();
+
+ if !transmissive_phase.items.is_empty() {
+ let screen_space_specular_transmission_steps =
+ camera_3d.screen_space_specular_transmission_steps;
+ if screen_space_specular_transmission_steps > 0 {
+ let transmission =
+ transmission.expect("`ViewTransmissionTexture` should exist at this point");
+
+ // `transmissive_phase.items` are depth sorted, so we split them into N = `screen_space_specular_transmission_steps`
+ // ranges, rendering them back-to-front in multiple steps, allowing multiple levels of transparency.
+ //
+ // Note: For the sake of simplicity, we currently split items evenly among steps. In the future, we
+ // might want to use a more sophisticated heuristic (e.g. based on view bounds, or with an exponential
+ // falloff so that nearby objects have more levels of transparency available to them)
+ for range in split_range(
+ 0..transmissive_phase.items.len(),
+ screen_space_specular_transmission_steps,
+ ) {
+ // Copy the main texture to the transmission texture, allowing to use the color output of the
+ // previous step (or of the `Opaque3d` phase, for the first step) as a transmissive color input
+ render_context.command_encoder().copy_texture_to_texture(
+ target.main_texture().as_image_copy(),
+ transmission.texture.as_image_copy(),
+ Extent3d {
+ width: physical_target_size.x,
+ height: physical_target_size.y,
+ depth_or_array_layers: 1,
+ },
+ );
+
+ let mut render_pass =
+ render_context.begin_tracked_render_pass(render_pass_descriptor.clone());
+
+ if let Some(viewport) = camera.viewport.as_ref() {
+ render_pass.set_camera_viewport(viewport);
+ }
+
+ // render items in range
+ transmissive_phase.render_range(&mut render_pass, world, view_entity, range);
+ }
+ } else {
+ let mut render_pass =
+ render_context.begin_tracked_render_pass(render_pass_descriptor);
+
+ if let Some(viewport) = camera.viewport.as_ref() {
+ render_pass.set_camera_viewport(viewport);
+ }
+
+ transmissive_phase.render(&mut render_pass, world, view_entity);
+ }
+ }
+
+ Ok(())
+ }
+}
+
+/// Splits a [`Range`] into at most `max_num_splits` sub-ranges without overlaps
+///
+/// Properly takes into account remainders of inexact divisions (by adding extra
+/// elements to the initial sub-ranges as needed)
+fn split_range(range: Range<usize>, max_num_splits: usize) -> impl Iterator<Item = Range<usize>> {
+ let len = range.end - range.start;
+ assert!(len > 0, "to be split, a range must not be empty");
+ assert!(max_num_splits > 0, "max_num_splits must be at least 1");
+ let num_splits = max_num_splits.min(len);
+ let step = len / num_splits;
+ let mut rem = len % num_splits;
+ let mut start = range.start;
+
+ (0..num_splits).map(move |_| {
+ let extra = if rem > 0 {
+ rem -= 1;
+ 1
+ } else {
+ 0
+ };
+ let end = (start + step + extra).min(range.end);
+ let result = start..end;
+ start = end;
+ result
+ })
+}