QuaternionEngine/docs/ResourceManager.md

Resource Manager: Buffers, Images, Uploads, and Lifetime

Central allocator and uploader built on VMA. Provides creation helpers, an immediate submit path, and a deferred upload queue that is converted into a Render Graph transfer pass each frame.

Responsibilities

• Create/destroy GPU buffers and images (with mapped memory for CPU‑to‑GPU when requested).
• Stage and upload mesh/texture data either immediately or via a per‑frame deferred path.
• Integrate with FrameResources deletion queues to match lifetimes to the frame.
• Expose a Render Graph pass that batches all pending uploads.

Key APIs (src/core/frame/resource.h)

• Creation

  • AllocatedBuffer create_buffer(size, usage, memUsage)
  • AllocatedImage create_image(extent3D, format, usage[, mipmapped])
  • AllocatedImage create_image(data, extent3D, format, usage[, mipmapped])
  • Destroy with destroy_buffer, destroy_image.

• Uploads

  • Deferred mode toggle: set_deferred_uploads(bool); when true, mesh/texture uploads enqueue staging work.
  • Query queues: pending_buffer_uploads(), pending_image_uploads(); clear via clear_pending_uploads().
  • Immediate path: process_queued_uploads_immediate() or immediate_submit(lambda) for custom commands.
  • Render Graph integration: register_upload_pass(RenderGraph&, FrameResources&) builds a single Transfer pass that:
    • Imports staging buffers and destination resources into the graph.
    • Inserts the appropriate TransferSrc/Dst declarations.
    • Records vkCmdCopyBuffer / vkCmdCopyBufferToImage and optional mip generation.
    • Schedules deletion of staging buffers at end of frame.

• Mesh upload convenience

  • GPUMeshBuffers uploadMesh(span<uint32_t> indices, span<Vertex> vertices) — returns device buffers and device address.

Per‑Frame Lifetime

• FrameResources::_deletionQueue owns per‑frame cleanups for transient buffers/images created during rendering passes.
• The upload pass registers cleanups for staging buffers on the frame queue.

Render Graph Interaction

• register_upload_pass is called during frame build before other passes (see src/core/engine.cpp:315).
• It uses graph import_buffer / import_image to deduplicate external resources and attach initial stage/layout.
• Barriers and final layouts for uploaded images are handled in the pass recording (generate_mipmaps path transitions to SHADER_READ_ONLY_OPTIMAL).

Guidelines

• Prefer deferred uploads (set_deferred_uploads(true)) for frame‑coherent synchronization under the Render Graph.
• For tooling and one‑off setup, use immediate_submit(lambda) to avoid per‑frame queuing.
• When creating transient images/buffers used only inside a pass, prefer the Render Graph’s create_* so destruction is automatic at frame end.

Known Issue (transition after mip generation)

• In the Render Graph upload pass, the mipmap path should leave the image in VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL after vkutil::generate_mipmaps(...). If you see an extra transition back to TRANSFER_DST_OPTIMAL after mip generation, remove it. The helper already transitions to the final sampled layout.