[SOLID] [M12] Allow backends to implement individual RHI sub-interfaces (drop composite bundling)

[MichaelFisher1997]

Part of #776 — SOLID architecture debt umbrella.
Phase: P2 · Finding: M12

Problem

modules/engine-rhi/src/rhi.zig:1028-1046 composite RHI.VTable re-bundles all 14 sub-vtables (comment: (temp)). A backend must implement all 14 even to do resource creation only — no way to ship a headless asset-baking backend. rhi_vulkan.zig:959-1067 is one 100+-function literal.

Evidence

rhi.zig:1028-1046:

pub const VTable = struct {
  init, deinit,
  // Composition of all vtables (temp)
  resources: IResourceFactory.VTable,
  render: IRenderContext.VTable,
  passes: IPassOrchestrationContext.VTable,
  ... all 14 ...
};

Fix

Allow backends to implement individual sub-interfaces and compose them at the seam. A backend that only creates resources implements only IResourceFactory.

Verification

• nix develop --command zig build test (includes shader validation)
• If rendering-touching: capture headless screenshot baseline before/after (-Dskip-present)
• If behavior-preserving refactor: golden-output test must stay green

Constraints

• Small reviewable PR targeting dev; conventional commit (refactor: / feat:)
• Preserve current behavior unless this issue explicitly changes it
• Keep worker-thread RHI isolation intact (no RHI calls off main thread)

Notes

Coordinate with M11 (split of IRenderOptionsContext). Both touch the vtable structure. Large, invasive — sequence after the P1 splits.

Tracking: #776

[github-actions]

Classification: Feature Request / Refactor (architecture debt under the #776 umbrella; sub-issue M12).

Audit validation: ✅ The finding is accurate. I cross-checked the cited sites:

• modules/engine-rhi/src/rhi.zig:1028-1046 — the RHI.VTable composite struct, the (temp) marker is on line 1032, and the literal indeed composes 14 sub-vtables (resources, render, passes, post_process, native, ssao, debug_overlay, shadow, water, ui, query, timing, options). The deprecation banner on line 1012 explicitly labels this struct as a temporary composition root.
• modules/engine-graphics/src/rhi_vulkan.zig:959-1067 — confirmed VULKAN_RHI_VTABLE is a single ~108-field literal. Minor nit: the issue calls it a "100+-function literal" — it is a struct literal whose fields are function pointers; functionally the same complaint, just so the PR description doesn't get nit-picked.

Related / duplicate work:

• Closed precursor [HIGH] Simplify RHI composite - Split into focused subsystem interfaces #272 ("Simplify RHI composite — Split into focused subsystem interfaces") already drove the wrapper migration (ResourceManager/RenderContext/ShadowSystem/UIRenderer sub-issues [HIGH] #272-A: RHI - ResourceManager wrapper #288–[HIGH] #272-D: RHI - UIRenderer wrapper + remove monolithic RHI #291). It landed wrappers around the segregated interfaces but left RHI.VTable itself composite — exactly what M12 now proposes to dissolve. So this is not a duplicate, it is the natural follow-on after [HIGH] Simplify RHI composite - Split into focused subsystem interfaces #272's wrappers stabilized.
• Open sibling [SOLID] [M11] Split IRenderOptionsContext into 4 role interfaces #793 (M11) wants to split IRenderOptionsContext into 4 role interfaces. Both touch the vtable region around rhi.zig:907–1046. Sequencing note already in the body is correct: do M11 first or merge them together, otherwise M12 will be rebased twice.
• Prerequisite [SOLID] [M3] Split rhi.zig into interfaces/wrappers; decompose VulkanContext god-struct #787 (M3, P1) splits rhi.zig into interfaces.zig + wrappers.zig and deletes the ~50 deprecated passthroughs. M12 is much cleaner if it lands after M3 — once the deprecated (temp) composite is the only remaining composite field, the diff for M12 becomes a single targeted change instead of fighting 50 passthroughs.
• Umbrella [Audit][Umbrella] SOLID architecture debt: RHI seam leakage, god-objects, and extension-safety gaps #776 — keep the parent updated with a one-line progress note when this lands.

Scope: ✅ Appropriately scoped — single cohesive refactor, no need to break into sub-issues. Suggested implementation sketch (do not implement here, just for design discussion):

1. Replace RHI.VTable with an anyopaque-keyed registry of optional sub-vtable pointers, e.g.

   pub const SubVTable = union(enum) {
       resources: *const IResourceFactory.VTable,
       render: *const IRenderContext.VTable,
       // ...
   };

   …or simpler: a struct of ?*const IXXX.VTable optionals, set to null for backends that opt out. RHI.factory() / RHI.shadow() etc. return ?IResourceFactory / ?IShadowContext and surface a clear "sub-interface not implemented" error at the call site rather than silently dereferencing a zero vtable.
2. Vulkan backend (rhi_vulkan.zig:959-1067) keeps implementing all 14 — no behavior change — but the literal moves from "fill every slot" to "fill only the slots it implements" (which today is all 14, so this is zero-cost for Vulkan).
3. Add a smoke test in modules/engine-rhi/src/ that constructs an RHI with resources populated and every other slot null, then verifies rhi.factory() works and rhi.shadow() returns an error / null instead of UB. This is the regression test that locks the "headless asset-baking backend" use case in.

Verification ask: please add to the PR description whether the headless screenshot baseline (-Dskip-present) is required. My read: this is a pure structural change with no rendering output change, so shader validation + zig build test should be sufficient. If reviewers disagree, capture the baseline anyway.

No additional info needed from the author — issue is implementation-ready as written. Awaiting M3 (#787) and/or M11 (#793) to land first per the existing sequencing note.

[github-actions]

Posted validation comment on issue #797 — confirms the audit citations (rhi.zig:1028-1046 and rhi_vulkan.zig:959-1067), flags related work (#272 closed precursor, #793 M11 sibling, #787 M3 prerequisite), and proposes an implementation sketch plus a regression-test idea. Comment: #797 (comment)

opencode session  |  github run