Phase 4: WorldRenderer Dependency Inversion Cleanup

[MichaelFisher1997]

Phase 4: WorldRenderer Dependency Inversion Cleanup

Goal

Remove direct concrete coupling from WorldRenderer so it depends on rendering abstractions rather than backend-specific implementation details.

Why this matters

WorldRenderer still reaches into Vulkan-specific types and concrete culling behavior. That weakens DIP and makes renderer refactors harder than they need to be.

Parallel Tasks

Issue 4.1: Introduce an ICullingSystem abstraction

• Type: refactor / solid
• Scope: src/world/world_renderer.zig, src/engine/graphics/vulkan/culling_system.zig
• Problem: culling is consumed as a concrete system instead of a stable interface.
• Work:
  • Define a focused culling interface with the methods WorldRenderer actually needs
  • Keep the current implementation as the first adapter behind the interface
  • Avoid exposing Vulkan details through the new abstraction
• Acceptance criteria:
  • WorldRenderer can compile against the interface only
  • The interface is small and purpose-built
• Parallel-safe: yes

Issue 4.2: Adapt the current culling implementation behind the new interface

• Type: refactor / solid
• Scope: src/engine/graphics/vulkan/culling_system.zig
• Problem: the existing culling system needs to become the concrete implementation behind the abstraction.
• Work:
  • Implement the new interface on top of the current culling system
  • Preserve all current CPU/GPU fallback behavior
  • Keep frame-indexed read/write semantics stable
• Acceptance criteria:
  • Existing culling behavior remains unchanged
  • The adapter compiles cleanly with the new interface
• Parallel-safe: yes

Issue 4.3: Remove direct VulkanContext coupling from WorldRenderer

• Type: refactor / solid
• Scope: src/world/world_renderer.zig
• Problem: the renderer still reaches into VulkanContext and raw native handles for culling and frame data.
• Work:
  • Replace direct VulkanContext access with the minimal interface data required
  • Reduce or eliminate @ptrCast use against Vulkan context internals
  • Keep MDI, CPU culling, and GPU culling paths working
• Acceptance criteria:
  • WorldRenderer no longer depends on backend internals directly
  • Rendering output is unchanged
• Parallel-safe: yes

Dependencies

• Phase 3 should land first if GPU block/meshing ownership moves affect the renderer input path

Verification

• nix develop --command zig build test
• nix develop --command zig build run

[github-actions]

The issue correctly identifies two concrete coupling problems in WorldRenderer:

1. Direct VulkanContext usage (src/world/world_renderer.zig:56,137,422-424):

   • vk_ctx.gpass.g_pass_extent and vk_ctx.depth_pyramid.isValid() are accessed directly in renderGpuCull() (lines 422-424)
   • This forces WorldRenderer to know about Vulkan-specific frame data structures

2. Concrete CullingSystem dependency (src/world/world_renderer.zig:70):

   • culling_system: ?*CullingSystem stores the concrete Vulkan implementation
   • WorldRenderer.init() calls CullingSystem.init() directly (line 109)

For the interface abstraction (Issue 4.1), WorldRenderer only needs:

• updateAABBData(frame_index, chunks)
• dispatch(view_proj, chunk_count, screen_width, screen_height, prev_frame_valid)
• readVisibleCount(frame_index) u32
• readVisibleIndices(frame_index, count, out)

For Issue 4.3, the minimal interface data WorldRenderer truly needs from the backend is screen_width, screen_height, and previous_frame_valid — these could be passed as parameters rather than extracted from VulkanContext.

The three parallel tasks are well-scoped with clear boundaries. Recommend starting with Issue 4.1 since Issues 4.2 and 4.3 depend on having the interface defined first.

opencode session  |  github run