Render Debug Overlay

Cargo.toml

@@ -252,6 +252,7 @@ common_api = [
   "bevy_anti_alias",
   "bevy_gltf",
   "bevy_pbr",
+  "bevy_render_debug",
   "bevy_post_process",
   "gltf_animation",
 ]
@@ -318,6 +319,9 @@ bevy_gltf = ["bevy_internal/bevy_gltf"]
 # Adds PBR rendering
 bevy_pbr = ["bevy_internal/bevy_pbr"]
 
+# Provides debug visualization for the PBR render pipeline
+bevy_render_debug = ["bevy_internal/bevy_render_debug"]
+
 # Provides picking functionality
 bevy_picking = ["bevy_internal/bevy_picking"]
 

crates/bevy_internal/Cargo.toml

@@ -246,6 +246,7 @@ bevy_pbr = [
   "bevy_core_pipeline",
   "bevy_gizmos_render?/bevy_pbr",
 ]
+bevy_render_debug = ["dep:bevy_render_debug", "bevy_pbr"]
 bevy_sprite_render = [
   "dep:bevy_sprite_render",
   "bevy_sprite",
@@ -507,6 +508,7 @@ bevy_input_focus = { path = "../bevy_input_focus", optional = true, version = "0
   "bevy_reflect",
 ] }
 bevy_pbr = { path = "../bevy_pbr", optional = true, version = "0.18.0-dev" }
+bevy_render_debug = { path = "../bevy_render_debug", optional = true, version = "0.18.0-dev" }
 bevy_picking = { path = "../bevy_picking", optional = true, version = "0.18.0-dev" }
 bevy_remote = { path = "../bevy_remote", optional = true, version = "0.18.0-dev" }
 bevy_render = { path = "../bevy_render", optional = true, version = "0.18.0-dev" }

crates/bevy_internal/src/default_plugins.rs

@@ -67,6 +67,8 @@ plugin_group! {
         bevy_ui_render:::UiRenderPlugin,
         #[cfg(feature = "bevy_pbr")]
         bevy_pbr:::PbrPlugin,
+        #[cfg(feature = "bevy_render_debug")]
+        bevy_render_debug:::DebugOverlayPlugin,
         // NOTE: Load this after renderer initialization so that it knows about the supported
         // compressed texture formats.
         #[cfg(feature = "bevy_gltf")]

crates/bevy_internal/src/lib.rs

@@ -74,6 +74,8 @@ pub use bevy_reflect as reflect;
 pub use bevy_remote as remote;
 #[cfg(feature = "bevy_render")]
 pub use bevy_render as render;
+#[cfg(feature = "bevy_render_debug")]
+pub use bevy_render_debug as render_debug;
 #[cfg(feature = "bevy_scene")]
 pub use bevy_scene as scene;
 #[cfg(feature = "bevy_shader")]

crates/bevy_render_debug/Cargo.toml

@@ -0,0 +1,26 @@
+[package]
+name = "bevy_render_debug"
+version = "0.18.0-dev"
+edition = "2024"
+description = "Adds debug visualization to Bevy Engine"
+homepage = "https://bevy.org"
+repository = "https://github.com/bevyengine/bevy"
+license = "MIT OR Apache-2.0"
+keywords = ["bevy"]
+
+[dependencies]
+bevy_app = { path = "../bevy_app", version = "0.18.0-dev" }
+bevy_asset = { path = "../bevy_asset", version = "0.18.0-dev" }
+bevy_core_pipeline = { path = "../bevy_core_pipeline", version = "0.18.0-dev" }
+bevy_ecs = { path = "../bevy_ecs", version = "0.18.0-dev" }
+bevy_image = { path = "../bevy_image", version = "0.18.0-dev" }
+bevy_input = { path = "../bevy_input", version = "0.18.0-dev" }
+bevy_log = { path = "../bevy_log", version = "0.18.0-dev" }
+bevy_pbr = { path = "../bevy_pbr", version = "0.18.0-dev" }
+bevy_reflect = { path = "../bevy_reflect", version = "0.18.0-dev" }
+bevy_render = { path = "../bevy_render", version = "0.18.0-dev" }
+bevy_shader = { path = "../bevy_shader", version = "0.18.0-dev" }
+bevy_camera = { path = "../bevy_camera", version = "0.18.0-dev" }
+
+[lints]
+workspace = true

crates/bevy_render_debug/src/debug_overlay.wgsl

@@ -0,0 +1,74 @@
+#import bevy_pbr::mesh_view_bindings::view
+#import bevy_pbr::mesh_view_bindings::depth_prepass_texture
+#import bevy_pbr::mesh_view_bindings::normal_prepass_texture
+#import bevy_pbr::mesh_view_bindings::motion_vector_prepass_texture
+#import bevy_pbr::mesh_view_bindings::deferred_prepass_texture
+#import bevy_pbr::view_transformations::depth_ndc_to_view_z
+
+struct DebugBufferConfig {
+    opacity: f32,
+    mip_level: u32,
+}
+
+@group(1) @binding(0) var<uniform> config: DebugBufferConfig;
+
+#ifdef DEBUG_DEPTH_PYRAMID
+@group(1) @binding(1) var depth_pyramid_texture: texture_2d<f32>;
+@group(1) @binding(2) var depth_pyramid_sampler: sampler;
+#endif
+
+@fragment
+fn fragment(@builtin(position) frag_coord: vec4<f32>) -> @location(0) vec4<f32> {
+    let uv = frag_coord.xy / view.viewport.zw;
+    var output_color: vec4<f32> = vec4(0.0);
+
+#ifdef DEBUG_DEPTH
+#ifdef DEPTH_PREPASS
+    let depth = textureLoad(depth_prepass_texture, vec2<i32>(frag_coord.xy), 0);
+    // Linearize depth for visualization
+    let linearized_depth = -depth_ndc_to_view_z(depth);
+    // Use a reasonable range for visualization, e.g. 0 to 20 units
+    output_color = vec4(vec3(linearized_depth / 20.0), 1.0);
+#else
+    output_color = vec4(1.0, 0.0, 1.0, 1.0);
+#endif
+#endif
+
+#ifdef DEBUG_NORMAL
+#ifdef NORMAL_PREPASS
+    let normal_sample = textureLoad(normal_prepass_texture, vec2<i32>(frag_coord.xy), 0);
+    output_color = vec4(normal_sample.xyz, 1.0);
+#else
+    output_color = vec4(1.0, 0.0, 1.0, 1.0);
+#endif
+#endif
+
+#ifdef DEBUG_MOTION_VECTORS
+#ifdef MOTION_VECTOR_PREPASS
+    let motion_vector = textureLoad(motion_vector_prepass_texture, vec2<i32>(frag_coord.xy), 0).rg;
+    // These motion vectors are stored in a format where 1.0 represents full-screen movement.
+    // We use a power curve to amplify small movements while keeping them centered.
+    let mapped_motion = sign(motion_vector) * pow(abs(motion_vector), vec2(0.2)) * 0.5 + 0.5;
+    output_color = vec4(mapped_motion, 0.5, 1.0);
+#else
+    output_color = vec4(1.0, 0.0, 1.0, 1.0);
+#endif
+#endif
+
+#ifdef DEBUG_DEFERRED
+#ifdef DEFERRED_PREPASS
+    let deferred = textureLoad(deferred_prepass_texture, vec2<i32>(frag_coord.xy), 0);
+    // Just show raw bits as colors for now
+    output_color = vec4(vec3(f32(deferred.x) / 255.0, f32(deferred.y) / 255.0, f32(deferred.z) / 255.0), 1.0);
+#else
+    output_color = vec4(1.0, 0.0, 1.0, 1.0);
+#endif
+#endif
+
+#ifdef DEBUG_DEPTH_PYRAMID
+    let depth_pyramid = textureSampleLevel(depth_pyramid_texture, depth_pyramid_sampler, uv, f32(config.mip_level)).r;
+    output_color = vec4(vec3(depth_pyramid), 1.0);
+#endif
+
+    return vec4(output_color.rgb, output_color.a * config.opacity);
+}