Frame class representing a single frame of rendering in the Vulkan application. More...
#include <headers/evan/Frame.hpp>
Classes | |
| struct | UniformBufferObject |
| Uniform buffer object structure. More... | |
| struct | ViewUniform |
| Per-view matrices consumed by the vertex shader. More... | |
Public Member Functions | |
| Frame (std::shared_ptr< DeviceContext > deviceContext, std::size_t perFrameSlotCount) | |
| Constructs a Frame object. | |
| void | destroy (VkDevice device) |
| Destroys the Vulkan resources associated with this frame. | |
| void | resetCommandBuffer (std::size_t viewSlot) |
| Resets the command buffer of the given view slot. | |
| VkCommandBuffer | getCommandBuffer (std::size_t viewSlot) const |
| Gets the command buffer of the given view slot. | |
| std::size_t | getPerFrameSlotCount () const |
| Gets the number of view/swapchain slots this frame was allocated for. | |
| VkBuffer | getUniformBuffer () const |
| Gets the Vulkan uniform buffer associated with this frame. | |
| VkDeviceSize | getUniformBufferAlignedSize () const |
| Gets the aligned byte size of one uniform buffer slot. | |
| void * | getUniformBufferMapped (std::size_t viewSlot) const |
| Gets the mapped CPU pointer of a view's uniform slot. | |
| VkBuffer | getInstanceBuffer () const |
| Gets the Vulkan instance buffer associated with this frame. | |
| void * | getInstanceBufferMapped (std::size_t viewSlot) const |
| Gets the mapped CPU pointer of a view's instance slot. | |
| VkDeviceSize | getInstanceBufferAlignedSize () const |
| Gets the aligned byte size of one instance buffer slot. | |
| std::size_t | getInstanceCapacity () const |
| Gets the number of model matrices one instance slot holds. | |
| bool | ensureInstanceCapacity (std::size_t transforms) |
Makes sure one instance slot can hold transforms matrices. | |
| VkBuffer | getIndirectBuffer () const |
| Gets the Vulkan indirect draw buffer associated with this frame. | |
| void * | getIndirectBufferMapped (std::size_t viewSlot) const |
| Gets the mapped CPU pointer of a view's indirect slot. | |
| VkDeviceSize | getIndirectBufferAlignedSize () const |
| Gets the aligned byte size of one indirect buffer slot. | |
| bool | hasTimestampQueries () const noexcept |
| Indicates whether this frame owns GPU timestamp queries. | |
| VkQueryPool | getTimestampQueryPool () const noexcept |
| Gets the timestamp query pool of this frame. | |
Public Attributes | |
| VkFence | _inFlight = VK_NULL_HANDLE |
| VkQueryPool | _timestampQueryPool = VK_NULL_HANDLE |
| std::vector< VkSemaphore > | _imageAvailable |
| std::vector< VkCommandBuffer > | _commandBuffers |
| std::vector< VkSemaphore > | _renderFinished |
| std::size_t | _perFrameSlotCount = 1 |
| void * | _uniformBufferMapped = nullptr |
| Pointer to the mapped memory of the uniform buffer. | |
Protected Member Functions | |
| void | cleanup () |
| Releases the synchronization objects, command buffer and uniform buffer owned by this frame. | |
| void | createCommandBuffer (VkDevice device, VkCommandPool commandPool) |
| Creates the Vulkan command buffer for this frame. | |
| void | createSyncObjects (VkDevice device) |
| Creates the synchronization objects for this frame. | |
| void | createUniformBuffer (const ADeviceBackend &deviceBackend) |
| Creates the uniform buffer for this frame. | |
| void | createInstanceBuffer (const ADeviceBackend &deviceBackend) |
| Creates the instance buffer for this frame. | |
| void | createIndirectBuffer (const ADeviceBackend &deviceBackend) |
| Creates the indirect draw buffer for this frame. | |
| void | createTimestampQueryPool (VkDevice device) |
| Creates the timestamp query pool for this frame. | |
Protected Attributes | |
| VkBuffer | _uniformBuffer = VK_NULL_HANDLE |
| Vulkan buffer for the uniform buffer object (UBO) used in this frame. | |
| VkDeviceMemory | _uniformBufferMemory = VK_NULL_HANDLE |
| Vulkan device memory associated with the uniform buffer. | |
| VkDeviceSize | _uniformBufferAlignedSize = 0 |
| Aligned byte size of one view's uniform buffer slot. | |
| VkBuffer | _instanceBuffer = VK_NULL_HANDLE |
| Vulkan buffer storing per-instance model matrices. | |
| VkDeviceMemory | _instanceBufferMemory = VK_NULL_HANDLE |
| Vulkan device memory associated with the instance buffer. | |
| void * | _instanceBufferMapped = nullptr |
| Pointer to the mapped memory of the instance buffer. | |
| VkDeviceSize | _instanceBufferAlignedSize = 0 |
| Aligned byte size of one view's instance buffer slot. | |
| std::size_t | _instanceCapacity = 0 |
| Number of model matrices one instance buffer slot currently holds. Grown on demand by ensureInstanceCapacity(). | |
| VkBuffer | _indirectBuffer = VK_NULL_HANDLE |
| Vulkan buffer storing indirect draw commands. | |
| VkDeviceMemory | _indirectBufferMemory = VK_NULL_HANDLE |
| Vulkan device memory associated with the indirect buffer. | |
| void * | _indirectBufferMapped = nullptr |
| Pointer to the mapped memory of the indirect buffer. | |
| VkDeviceSize | _indirectBufferAlignedSize = 0 |
| Aligned byte size of one view's indirect buffer slot. | |
| std::shared_ptr< DeviceContext > | _deviceContext |
| The device context used to create this frame, kept alive for the lifetime of the frame so that cleanup can safely destroy its Vulkan resources. | |
Detailed Description
Frame class representing a single frame of rendering in the Vulkan application.
This class encapsulates the Vulkan resources and synchronization objects needed for rendering a single frame, such as command buffers, fences, semaphores, and uniform buffers. It provides functions to create and manage these resources, as well as to reset the command buffer for recording new commands each frame. The Frame class is designed to be used in a multi-frame rendering loop, where each frame has its own set of resources to ensure proper synchronization and efficient rendering.
- Note
- The Frame class is closely tied to the ADeviceBackend class, which provides access to Vulkan resources and functions needed for creating buffers and synchronization objects. It is important to ensure that the Frame class is properly integrated with the device backend to manage Vulkan resources effectively.
Constructor & Destructor Documentation
◆ Frame()
| evan::Frame::Frame | ( | std::shared_ptr< DeviceContext > | deviceContext, |
| std::size_t | perFrameSlotCount | ||
| ) |
Constructs a Frame object.
This constructor initializes the synchronization objects and command buffer for the frame. It takes a command pool and a reference to the device backend to set up the necessary Vulkan resources for rendering.
- Parameters
-
commandPool The Vulkan command pool used to allocate command buffers for this frame. deviceBackend A reference to the device backend that provides access to Vulkan resources and functions needed to create synchronization objects and uniform buffers. perFrameSlotCount Number of view/swapchain slots to allocate per-frame resources for, normally frameSlotCount(viewCount, swapchainCount). Clamped to [1, MAX_SWAPCHAINS].
Member Function Documentation
◆ cleanup()
|
protected |
Releases the synchronization objects, command buffer and uniform buffer owned by this frame.
Idempotent: every handle is null-checked and reset after being destroyed, making it safe to call from both the destructor and the public destroy() method.
◆ createCommandBuffer()
|
protected |
Creates the Vulkan command buffer for this frame.
This function allocates a command buffer from the specified command pool and initializes it for recording rendering commands.
- Parameters
-
device The Vulkan logical device used to create the command buffer. commandPool The Vulkan command pool from which to allocate the
◆ createIndirectBuffer()
|
protected |
Creates the indirect draw buffer for this frame.
This buffer stores VkDrawIndexedIndirectCommand entries used to batch the sorted draws, with one aligned slot per view.
- Parameters
-
deviceBackend A reference to the device backend used to create the buffer and allocate memory.
◆ createInstanceBuffer()
|
protected |
Creates the instance buffer for this frame.
This buffer stores per-instance model matrices for instanced rendering, with one aligned slot per view. Each slot holds _instanceCapacity matrices; ensureInstanceCapacity() is the only caller and sets that capacity before allocating.
- Parameters
-
deviceBackend A reference to the device backend used to create the buffer and allocate memory.
◆ createSyncObjects()
Creates the synchronization objects for this frame.
This function creates the Vulkan synchronization objects (fences and semaphores) needed for rendering this frame, such as the in-flight fence, image available semaphore, and render finished semaphore.
- Parameters
-
device The Vulkan logical device used to create the synchronization objects.
◆ createTimestampQueryPool()
Creates the timestamp query pool for this frame.
Only called when frame statistics ask for GPU timings and the device supports timestamp queries; the pool holds two queries per view slot and is destroyed in cleanup().
- Parameters
-
device The Vulkan logical device used to create the pool.
◆ createUniformBuffer()
|
protected |
Creates the uniform buffer for this frame.
This function allocates a Vulkan buffer and its associated memory for the uniform buffer object (UBO) used in this frame. It sets up the buffer to be used for passing data to the vertex shader during rendering.
- Parameters
-
deviceBackend A reference to the device backend that provides access to Vulkan resources and functions needed to create the buffer and allocate memory for the uniform buffer.
◆ destroy()
Destroys the Vulkan resources associated with this frame.
This function cleans up the synchronization objects, command buffer, and uniform buffer associated with this frame. It should be called when the frame is no longer needed to free up Vulkan resources.
- Parameters
-
device The Vulkan logical device used to destroy the resources.
◆ ensureInstanceCapacity()
| bool evan::Frame::ensureInstanceCapacity | ( | std::size_t | transforms | ) |
Makes sure one instance slot can hold transforms matrices.
Grows the instance buffer on demand instead of dropping meshes past a fixed bound. If the current capacity already covers the request this is a no-op. Otherwise the buffer and its memory are released and reallocated at the capacity returned by nextInstanceCapacity(), which grows geometrically so reallocation happens rarely.
The caller must not hold a mapped pointer across this call, and must not call it while a recorded command buffer of this frame still references the previous buffer: the handle changes. The renderer therefore calls it once per frame, before recording any view.
- Parameters
-
transforms Number of model matrices the frame needs per view.
- Returns
- True when the buffer was reallocated.
◆ getCommandBuffer()
| VkCommandBuffer evan::Frame::getCommandBuffer | ( | std::size_t | viewSlot | ) | const |
Gets the command buffer of the given view slot.
- Parameters
-
viewSlot Index of the view whose command buffer is returned.
- Returns
- The Vulkan command buffer for this view.
◆ getIndirectBuffer()
| VkBuffer evan::Frame::getIndirectBuffer | ( | ) | const |
Gets the Vulkan indirect draw buffer associated with this frame.
This buffer holds one slot per view, each slot storing up to MAX_INDIRECT_COMMANDS_PER_VIEW indirect draw commands used to batch the sorted draws when indirect drawing is enabled.
- Returns
- The Vulkan buffer for this frame.
◆ getIndirectBufferAlignedSize()
| VkDeviceSize evan::Frame::getIndirectBufferAlignedSize | ( | ) | const |
Gets the aligned byte size of one indirect buffer slot.
- Returns
- The aligned size, a multiple of minUniformBufferOffsetAlignment.
◆ getIndirectBufferMapped()
| void * evan::Frame::getIndirectBufferMapped | ( | std::size_t | viewSlot | ) | const |
Gets the mapped CPU pointer of a view's indirect slot.
- Parameters
-
viewSlot Index of the view slot.
- Returns
- Mapped pointer to the slot, ready for a memcpy of VkDrawIndexedIndirectCommand entries.
◆ getInstanceBuffer()
| VkBuffer evan::Frame::getInstanceBuffer | ( | ) | const |
Gets the Vulkan instance buffer associated with this frame.
This buffer holds one slot per view, each slot storing the model matrices consumed by the vertex shader as per-instance attributes. One matrix is stored per drawn mesh, so every draw addresses its transform with firstInstance and the engine never bakes a transform into vertex data. The slot capacity grows on demand; see ensureInstanceCapacity().
- Returns
- The Vulkan buffer for this frame.
◆ getInstanceBufferAlignedSize()
| VkDeviceSize evan::Frame::getInstanceBufferAlignedSize | ( | ) | const |
Gets the aligned byte size of one instance buffer slot.
- Returns
- The aligned size, a multiple of minUniformBufferOffsetAlignment.
◆ getInstanceBufferMapped()
| void * evan::Frame::getInstanceBufferMapped | ( | std::size_t | viewSlot | ) | const |
Gets the mapped CPU pointer of a view's instance slot.
- Parameters
-
viewSlot Index of the view slot.
- Returns
- Mapped pointer to the slot, ready for a memcpy of instance transforms.
◆ getInstanceCapacity()
| std::size_t evan::Frame::getInstanceCapacity | ( | ) | const |
Gets the number of model matrices one instance slot holds.
- Returns
- The per-view transform capacity.
◆ getPerFrameSlotCount()
| std::size_t evan::Frame::getPerFrameSlotCount | ( | ) | const |
Gets the number of view/swapchain slots this frame was allocated for.
- Returns
- The per-frame slot count.
◆ getTimestampQueryPool()
|
inlinenoexcept |
Gets the timestamp query pool of this frame.
The pool holds two queries per view slot (begin and end of the render pass). vkCmdResetQueryPool is recorded at the start of every command buffer, so a query is only read after the in-flight fence of the frame slot has signalled.
- Returns
- The query pool, or VK_NULL_HANDLE when timestamps are off.
◆ getUniformBuffer()
| VkBuffer evan::Frame::getUniformBuffer | ( | ) | const |
Gets the Vulkan uniform buffer associated with this frame.
This buffer holds one aligned slot per view. Descriptor sets bind it as a dynamic uniform buffer and select the view slot through a dynamic offset at bind time.
- Returns
- The Vulkan buffer for this frame.
◆ getUniformBufferAlignedSize()
| VkDeviceSize evan::Frame::getUniformBufferAlignedSize | ( | ) | const |
Gets the aligned byte size of one uniform buffer slot.
- Returns
- The aligned size, a multiple of minUniformBufferOffsetAlignment.
◆ getUniformBufferMapped()
| void * evan::Frame::getUniformBufferMapped | ( | std::size_t | viewSlot | ) | const |
Gets the mapped CPU pointer of a view's uniform slot.
- Parameters
-
viewSlot Index of the view slot.
- Returns
- Mapped pointer to the slot, ready for a memcpy of one UniformBufferObject.
◆ hasTimestampQueries()
|
inlinenoexcept |
Indicates whether this frame owns GPU timestamp queries.
True when EVAN_STATS and EVAN_STATS_GPU are enabled and the device supports timestamp queries; the renderer only writes and reads timestamps when it is true.
- Returns
- True when timestamp queries are available on this frame.
◆ resetCommandBuffer()
| void evan::Frame::resetCommandBuffer | ( | std::size_t | viewSlot | ) |
Resets the command buffer of the given view slot.
Each view owns its own command buffer so that stereo views can be recorded back-to-back without waiting for the GPU between them.
- Parameters
-
viewSlot Index of the view whose command buffer is reset.
Member Data Documentation
◆ _commandBuffers
| std::vector<VkCommandBuffer> evan::Frame::_commandBuffers |
◆ _deviceContext
|
protected |
◆ _imageAvailable
| std::vector<VkSemaphore> evan::Frame::_imageAvailable |
◆ _indirectBuffer
|
protected |
◆ _indirectBufferAlignedSize
|
protected |
◆ _indirectBufferMapped
◆ _indirectBufferMemory
|
protected |
◆ _inFlight
| VkFence evan::Frame::_inFlight = VK_NULL_HANDLE |
In-flight fence ensuring that a frame's resources (command buffer, uniform buffer and semaphores) are not reused until the previous frame using them has finished on the GPU. One fence is kept per in-flight frame, signaled by the frame's queue submission and waited on before the frame is reused.
◆ _instanceBuffer
|
protected |
◆ _instanceBufferAlignedSize
|
protected |
◆ _instanceBufferMapped
◆ _instanceBufferMemory
|
protected |
◆ _instanceCapacity
|
protected |
Number of model matrices one instance buffer slot currently holds. Grown on demand by ensureInstanceCapacity().
◆ _perFrameSlotCount
| std::size_t evan::Frame::_perFrameSlotCount = 1 |
◆ _renderFinished
| std::vector<VkSemaphore> evan::Frame::_renderFinished |
◆ _timestampQueryPool
| VkQueryPool evan::Frame::_timestampQueryPool = VK_NULL_HANDLE |
◆ _uniformBuffer
|
protected |
◆ _uniformBufferAlignedSize
|
protected |
◆ _uniformBufferMapped
◆ _uniformBufferMemory
|
protected |
The documentation for this class was generated from the following file:
- headers/evan/Frame.hpp
