[Batch 5] Double-buffer upload pipeline

[MichaelFisher1997]

Summary

Implement a double-buffered staging + upload pipeline that overlaps mesh uploads with rendering. Chunk mesh data is written to one staging buffer while the GPU reads from the previous frame's buffer, eliminating upload stalls.

Depends on: #384 (dedicated transfer queue + staging ring)

Current State (after #384)

The transfer queue and staging ring exist, but uploads are submitted one-at-a-time and may still cause synchronization points. The main thread submits uploads, waits for completion, then renders. At high chunk throughput (128+ chunks loading simultaneously), upload bandwidth is limited.

Target Architecture

Double-Buffer Strategy

Frame N:
  Staging Buffer A: GPU is copying from this → megabuffer (previous frame's uploads)
  Staging Buffer B: CPU is writing new mesh data into this
  
Frame N+1:
  Swap: A becomes write target, B becomes GPU read source
  GPU copies B → megabuffer while CPU writes A

Upload Pipeline

1. Collect: Worker threads produce mesh vertex data
2. Stage: Main thread allocates from staging buffer B (current write buffer), copies data
3. Submit: End of frame: submit transfer commands for buffer B → megabuffer
4. Swap: Next frame: buffer B becomes GPU source, buffer A becomes CPU write target
5. Fence: Previous frame's transfer must complete before staging buffer A is reused

Per-Chunk Flow

Worker thread: Build mesh → pending_solid/pending_cutout/pending_fluid arrays
Main thread (beginFrame):
  - Check previous frame's transfer fence
  - If complete: swap staging buffers, reclaim space
Main thread (update):
  - For each pending upload:
    - Allocate from current staging buffer
    - Copy vertex data
    - Record copy command (staging → megabuffer offset)
Main thread (endFrame):
  - Submit accumulated transfer commands
  - Signal fence

Implementation Plan

Step 1: Double-buffered staging

• Two StagingRing instances (or one ring split in half)
• write_staging and gpu_staging pointers, swapped each frame
• Frame N writes to write_staging, GPU reads from gpu_staging
• After swap: gpu_staging is the just-written buffer, write_staging is the just-completed buffer

Step 2: Batch upload submission

• Accumulate multiple chunk uploads per frame
• Single vkQueueSubmit with all copy commands batched
• One fence per frame (not per chunk)
• vkCmdCopyBuffer for each chunk: staging offset → megabuffer offset

Step 3: Integration with WorldStreamer

• WorldStreamer currently has max_uploads_per_frame limit
• With double-buffer pipeline, this limit can be raised significantly
• Upload queue: FIFO of chunks with completed meshes awaiting upload
• Main thread drains the queue into staging buffer

Step 4: Backpressure

• If staging buffer is >80% full: pause new uploads (backpressure to streamer)
• If GPU is consistently behind on transfers: log warning, reduce upload rate
• Monitor: show staging buffer utilization in debug overlay

Files to Modify

• src/engine/graphics/vulkan/transfer_queue.zig — double-buffer logic
• src/world/world_streamer.zig — upload queue integration
• src/world/chunk_mesh.zig — pending upload handling
• src/engine/ui/timing_overlay.zig — staging buffer utilization stat

Testing

• No frame stalls during heavy chunk streaming (128+ chunks)
• Upload throughput scales with available staging buffer size
• Backpressure prevents staging overflow
• All chunk passes (solid/cutout/fluid) upload correctly
• LOD mesh uploads use same pipeline
• Timing overlay shows upload metrics

Roadmap: docs/PERFORMANCE_ROADMAP.md — Batch 5, Issue 3B-2

[opencode-agent]

Analysis Summary

Classification: Feature Request (Performance Enhancement)

Current State Assessment:

Good news - the codebase already has the foundation for double-buffering:

1. MAX_FRAMES_IN_FLIGHT = 2 (src/engine/graphics/rhi_types.zig:37) - Double-buffering already exists
2. Per-frame staging buffers (resource_manager.zig:104) - staging_buffers: [MAX_FRAMES_IN_FLIGHT]StagingBuffer with 64MB per buffer
3. Frame-indexed access - updateBuffer() at resource_manager.zig:329 already uses staging_buffers[self.current_frame_index]

The current implementation already provides the double-buffer semantics described in the issue:

• Frame N writes to staging buffer N % 2
• Frame N+1 writes to staging buffer (N+1) % 2 while GPU reads from buffer N % 2

Gap Analysis - What's Actually Missing:

1. No batching: Each chunk upload calls updateBuffer() which records individual vkCmdCopyBuffer + pipeline barrier. No accumulation of multiple uploads per frame.

2. Transfer queue underutilized: The transfer command pool exists (transfer_command_pool, transfer_command_buffers) but uploads are submitted inline, not batched via a dedicated transfer queue submit.

3. Sync point issues: The transfer_fence exists but isn't used to overlap CPU writes with GPU reads across frames.

4. Limited throughput: max_uploads_per_frame defaults to 32 (world.zig:136), which may be too conservative for 128+ chunks.

Scope Recommendation:

This issue should be broken down into 3 smaller, focused issues:

1. Issue A: Upload batching - Accumulate multiple chunk uploads into a single command buffer submission per frame, one pipeline barrier at the end
2. Issue B: Transfer queue overlap - Use the existing transfer fence to properly overlap CPU writes (frame N+1) with GPU transfers (frame N)
3. Issue C: Upload metrics & backpressure - Add staging buffer utilization to the timing overlay and implement backpressure when >80% full

Key Files Status:

• ✅ resource_manager.zig - Staging buffers already double-buffered
• ⚠️ world_streamer.zig - Sequential uploads, needs batching
• ⚠️ chunk_mesh.zig - Ready, just needs integration
• ❓ timing_overlay.zig - Needs staging buffer metrics

Question: Does #384 implement the dedicated transfer queue with proper async submission, or is that still pending? Understanding the delta between current state and #384's implementation would help clarify what remains to be done here.

opencode session  |  github run