DebugPass

DebugPass is a tooling pass for renderer introspection. It renders G-buffer-style diagnostic overlays - depth, normals, albedo, and metallic/roughness - each as an independent subpass that can be toggled at runtime.

Render Graph Role

Attribute	Value
Group	Tooling
Reads	mesh_context, mesh_collector_storage, shadow_map
Read-Write	scene_color
Cullable	Yes

Subpasses

Only one subpass is active at a time. Switching between them is a zero-cost toggle - no re-compilation of the render graph is required.

Depth Map

Linearizes and visualizes the scene depth buffer. Near values appear white; far values appear black. Useful for diagnosing depth precision issues and shadow map coverage.

Normals

Encodes the world-space normal vector as an RGB color (N * 0.5 + 0.5). Flat surfaces show solid colors; smooth normals produce smooth gradients.

Albedo

Renders the raw albedo texture of each mesh, bypassing lighting. Useful for verifying texture assignment and UV mapping.

Metallic / Roughness

Renders the metallic channel as red and the roughness channel as green, with blue fixed at 0. Useful for diagnosing PBR material authoring issues.

Enabling at Runtime

auto* debug = render_graph->get_pass<DebugPass>();
debug->set_mode(DebugMode::Normals);  // Depth, Normals, Albedo, MetallicRoughness

Setting DebugMode::None disables the pass output and lets scene_color pass through unmodified.

Overlay vs Replace

By default, debug output replaces scene_color. Set overlay = true to composite the debug visualization as a picture-in-picture inset instead:

debug->overlay        = true;
debug->overlay_rect   = { 0.0f, 0.0f, 0.3f, 0.3f }; // normalized screen rect