Phase 4 / Task 1: Introduce ICullingSystem abstraction

[MichaelFisher1997]

Goal

Introduce a focused culling abstraction for WorldRenderer.

Scope

• src/world/world_renderer.zig
• culling implementation files

Work

• Define a small interface with only the methods WorldRenderer needs
• Keep the current implementation as the first adapter behind it
• Avoid exposing Vulkan details through the new abstraction

Acceptance criteria

• WorldRenderer can compile against the interface only
• The interface stays small and purpose-built

Parallel-safe

Yes

[github-actions]

Classification: Feature Request

Analysis:

The culling implementation resides in src/engine/graphics/vulkan/culling_system.zig (528 lines) with GPU-based compute culling using frustum + occlusion tests. WorldRenderer uses these methods:

• init() / deinit()
• updateAABBData() - uploads chunk AABBs
• dispatch() - runs GPU culling compute shader
• readVisibleCount() / readVisibleIndices() - retrieves results

The codebase already has a well-established COM-style VTable abstraction pattern in the RHI layer (IResourceFactory, IRenderContext, IShadowContext, etc.). Following this pattern keeps the codebase consistent.

Suggested interface (mirroring existing patterns):

pub const ICullingSystem = struct {
    ptr: *anyopaque,
    vtable: *const VTable,

    pub const VTable = struct {
        updateAABBData: *const fn (ptr: *anyopaque, frame_index: usize, chunks: []const ChunkCullData) void,
        dispatch: *const fn (ptr: *anyopaque, view_proj: Mat4, chunk_count: u32, screen_width: f32, screen_height: f32, previous_frame_valid: bool) void,
        readVisibleCount: *const fn (ptr: *anyopaque, frame_index: usize) u32,
        readVisibleIndices: *const fn (ptr: *anyopaque, frame_index: usize, count: u32, out: []u32) void,
        deinit: *const fn (ptr: *anyopaque) void,
    };
    // ... wrapper methods
};

What stays Vulkan-private: vk_ctx, VkDescriptorPool, VkDescriptorSet, VkPipeline, VkPipelineLayout, pipeline barriers

What stays public (backend-agnostic): ChunkCullData, MAX_CULLABLE_CHUNKS, WORKGROUP_SIZE

Scope assessment: This is well-scoped — single file creation + adapter pattern. The existing renderCpuCull() path could optionally use the same interface for CPU fallback.

Next steps (if implemented):

1. Create src/engine/graphics/culling.zig with ICullingSystem interface + CullingSystemAdapter type alias
2. Refactor WorldRenderer to hold ICullingSystem instead of *CullingSystem
3. Rename existing culling_system.zig to culling_vulkan.zig and add the adapter vtable

Would you like me to proceed with implementation?

opencode session  |  github run