Add lightweight render pass orchestration (render graph) and shell integration

CMakeLists.txt

@@ -124,6 +124,8 @@ add_library(render_renderer STATIC
   engine/render/lighting.hpp
   engine/render/lighting.cpp
   engine/render/texture_types.hpp
+  engine/render/render_pass_system.hpp
+  engine/render/render_pass_system.cpp
   engine/render/vfx.hpp
   engine/render/vfx.cpp
   engine/render/bgfx/renderer_bgfx.cpp
@@ -228,6 +230,12 @@ if(RENDER_BUILD_TESTS)
   render_apply_project_options(render_debug_renderer_tests)
   render_apply_warnings(render_debug_renderer_tests)
 
+
+  add_executable(render_render_pass_system_tests tests/render/render_pass_system_tests.cpp)
+  target_link_libraries(render_render_pass_system_tests PRIVATE render::renderer)
+  render_apply_project_options(render_render_pass_system_tests)
+  render_apply_warnings(render_render_pass_system_tests)
+
   add_executable(render_scene_tests tests/scene/scene_tests.cpp)
   target_link_libraries(render_scene_tests PRIVATE render::scene)
   render_apply_project_options(render_scene_tests)
@@ -256,6 +264,8 @@ if(RENDER_BUILD_TESTS)
   set_tests_properties(unit.renderer.lighting_pipeline PROPERTIES LABELS "unit;renderer;lighting")
   add_test(NAME unit.renderer.debug_views COMMAND render_debug_renderer_tests)
   set_tests_properties(unit.renderer.debug_views PROPERTIES LABELS "unit;renderer;debug")
+  add_test(NAME unit.renderer.render_pass_system COMMAND render_render_pass_system_tests)
+  set_tests_properties(unit.renderer.render_pass_system PROPERTIES LABELS "unit;renderer;graph")
   add_test(NAME unit.scene.runtime COMMAND render_scene_tests)
   set_tests_properties(unit.scene.runtime PROPERTIES LABELS "unit;scene")
   add_test(NAME unit.renderer.vfx_system COMMAND render_vfx_system_tests)

docs/rendering.md

@@ -268,3 +268,56 @@ Highlights:
 - shader pipeline integration through `vfx/ambient_sprite` manifest entries and variants
 
 Detailed design and current limits are documented in `docs/vfx.md`.
+
+## Structured render pass system (Statement 16)
+
+Statement 16 adds a lightweight, engine-owned render graph under `engine/render/render_pass_system.*`.
+
+### Core model
+
+- `RenderPassRegistry` owns per-frame pass/resource declarations and orchestration.
+- `RenderPassDefinition` encodes pass name, dependencies, explicit resource usage, optional enable predicate, and execution callback.
+- `RenderResourceDesc` encodes frame resources (shadow map, scene color, bloom intermediates, UI/debug overlays, imported backbuffer).
+- `RenderPassExecutionContext` passes frame metadata, renderer access, registry access, and user payload pointer into pass execution.
+
+### Validation and ordering
+
+Build-time checks fail clearly for:
+
+- duplicate pass/resource names
+- missing pass dependencies
+- undeclared resource usage
+- resource write conflicts
+- reads with no producer (unless resource is imported)
+- dependency cycles
+
+Execution order is resolved by topological sorting over explicit `depends_on` edges plus inferred producer->consumer edges from resource reads.
+
+### Current shell frame layout
+
+`engine/shell/main.cpp` now assembles the frame through the pass system, with explicit passes:
+
+1. `shadow-pass`
+2. `main-lit-pass`
+3. `bloom-extract-pass`
+4. `bloom-blur-pass`
+5. `bloom-composite-pass`
+6. `outline-pass`
+7. `ui-pass`
+8. `debug-pass`
+9. `present-pass`
+
+This removes ad hoc scattered manual ordering and creates a single inspectable orchestration path.
+
+### Diagnostics
+
+- `RenderPassRegistry::dump_graph()` provides a textual pass/resource dump for logs.
+- `RenderPassDiagnostics` exposes execution order and active/inactive pass sets.
+- Pass execution integrates with renderer debug timing rows (`RendererPassTiming`) for per-pass CPU visibility.
+
+### Deferred follow-ups
+
+- physical render-target allocation/aliasing and transient memory optimization
+- backend GPU timer query integration for real GPU timings
+- richer pass-level debug UI (resource producers/consumers overlay)
+- optional pass plugin registration for editor/runtime extension modules

engine/render/README.md

@@ -89,3 +89,16 @@ Current debug view behavior:
 - category toggles (`VfxToggleMask`) for profiling and debug isolation
 
 Scene-level attachment is handled by `scene::VfxAttachmentComponent` (in `engine/scene`) so effects can follow node transforms without exposing backend-specific handles.
+
+## Structured render-pass orchestration (Statement 16)
+
+`render_pass_system.hpp/.cpp` introduces the canonical engine-owned pass orchestration layer.
+
+- Passes are first-class definitions (`RenderPassDefinition`) with a stable name, dependency list, explicit resource usage declarations, enable predicates, and execute hooks.
+- Frame resources are explicitly declared through `RenderResourceDesc` (`RenderTarget`, `DepthTarget`, `ShadowMap`, post-process textures, UI targets, and imported `Backbuffer`).
+- Build-time validation checks undeclared resources, missing dependencies, duplicate names, write conflicts, read-without-producer misuse, and dependency cycles.
+- Build step computes a deterministic execution order from explicit dependencies plus producer->consumer resource edges.
+- Runtime execution tracks active/inactive passes and emits pass timing rows through renderer debug timing hooks.
+- `dump_graph()` exposes a human-readable frame graph/resource layout for logs and inspection.
+
+This is intentionally a lightweight engine-owned render graph: explicit and extensible now, without introducing a heavyweight AAA framegraph scheduler.