[HIGH] Simplify RHI composite - Split into focused subsystem interfaces

[MichaelFisher1997]

Problem

The RHI struct in src/engine/graphics/rhi.zig (754 lines) is a composite God Object that combines 8+ interface vtables into a single struct:

• IResourceFactory (buffer/texture/shader creation)
• IRenderContext (frame/render pass management)
• IShadowContext (shadow mapping)
• IUIContext (2D/UI rendering)
• IGraphicsCommandEncoder (draw commands)
• IRenderStateContext (uniforms/state)
• ISSAOContext (SSAO computation)
• IDeviceQuery/IDeviceTiming (device queries)

This violates SRP and makes the code difficult to maintain and test.

Current State

RHI struct acts as a monolithic facade over many concerns.

Proposed Solution

Keep the segregated interfaces (which are well-designed!) but refactor how they're composed:

1. Option A: Keep separate interface instances instead of one composite
2. Option B: Create focused subsystem wrappers:
   • ResourceManager - owns IResourceFactory
   • RenderContext - owns IRenderContext + IGraphicsCommandEncoder
   • ShadowSystem - owns IShadowContext
   • UIRenderer - owns IUIContext

Benefits

• Clients depend only on interfaces they actually use
• Easier to mock for unit testing
• Clearer dependencies between subsystems
• Reduced cognitive load per module

Acceptance Criteria

• Split RHI composite into focused subsystems
• Update all callers to use appropriate subsystem
• No change to underlying Vulkan implementation
• All tests pass
• Document the new architecture

Related Files

• src/engine/graphics/rhi.zig
• src/engine/graphics/rhi_vulkan.zig

SOLID Principles

• Single Responsibility Principle (SRP)
• Interface Segregation Principle (ISP)

[opencode-agent]

Classification

Type: Architecture Refactoring / Feature Request
Priority: Valid technical debt reduction that improves maintainability

Validation

Issue Quality: ✅ Well-documented

• Clear problem statement with specific line count
• Two viable solution options provided
• Acceptance criteria defined
• SOLID principles justification

Scope Assessment: ✅ Appropriate for single issue
While this touches many files (~20+), it's a single cohesive refactoring with a clear boundary: splitting the composite without changing the underlying Vulkan implementation.

Analysis

Current Impact: Found 100+ usages of RHI across:

• Core rendering: app.zig, session.zig, world_renderer.zig
• World systems: world.zig, chunk_mesh.zig, lod_renderer.zig
• UI/Settings: screen.zig, settings/apply.zig
• Resources: texture.zig, material_system.zig, render_graph.zig

Recommendation: Proceed with Option B (focused subsystem wrappers) because:

1. Provides clear ownership boundaries
2. Allows incremental migration (update callers subsystem by subsystem)
3. Maintains the existing segregated interfaces (no breaking change to Vulkan backend)
4. Enables better testability through interface injection

Implementation Strategy:

1. Create new wrapper structs in rhi.zig (keep them in same file initially)
2. Migrate one subsystem at a time (ResourceManager → RenderContext → ShadowSystem → UIRenderer)
3. Update callers progressively to reduce PR size
4. Remove the monolithic RHI struct once all callers migrated

No additional info needed - the issue is ready for implementation.

opencode session  |  github run