Represents the context for managing the swapchain in the rendering system. More...
#include <headers/evan/ASwapchainContext.hpp>
Classes | |
| struct | SwapChainSupportDetails |
| Struct to encapsulate details about swap chain support. More... | |
Public Member Functions | |
| virtual void | destroy (VkDevice device)=0 |
| Destroys the swapchain and releases associated resources. | |
| virtual void | recreateSwapchain (const DeviceContext &deviceContext, VkRenderPass renderpass)=0 |
| Recreates the swapchain and associated resources. | |
| VkRenderPass | getRenderPass () const |
| Retrieves the render pass associated with the swapchain context. | |
| virtual VkSampleCountFlagBits | getMsaaSamples () const =0 |
| Retrieves the MSAA sample count used by this swapchain context. | |
| virtual VkResult | aquireImage (uint32_t index, VkDevice device, VkSemaphore imageAvailableSemaphore, VkFence inFlightFence, uint32_t &imageIndex)=0 |
| Acquires the next available image from the swapchain for rendering. | |
| virtual void | waitForImage (uint32_t index)=0 |
| Waits for the specified image in the swapchain to become available for rendering. | |
| virtual ViewSet & | getViewSet ()=0 |
| Retrieves the set of views to render for this swapchain context. | |
| virtual const ViewSet & | getViewSet () const =0 |
| Retrieves the set of views to render (const version). | |
| std::size_t | getSwapchainCount () const |
| Retrieves the number of swapchain image sets in the context. | |
| virtual bool | usesImageAvailableSemaphore () const |
| Indicates whether aquireImage signals the image-available semaphore. | |
| virtual bool | needsSwapchainRecreation () const |
| Indicates whether the swapchain needs to be recreated. | |
| virtual bool | usesMultiview () const |
| Indicates whether the frame renders every view in one pass. | |
| utility::graphic::ViewF | getView (std::size_t index) const |
| Retrieves the view matrix for the specified view index. | |
| virtual void | setView (std::size_t index, const utility::graphic::ViewF &view) |
| Sets the view state for the specified view index. | |
| const utility::graphic::PoseF & | getViewOffset (void) const |
| Retrieves the persistent world-space view offset. | |
| std::size_t | getViewCount (void) const |
| Retrieves the number of views in the swapchain context. | |
| glm::mat4 | getProjection (std::size_t index) const |
| Retrieves the projection matrix for the specified view index. | |
| utility::math::Vector2F | getViewportSize () const |
| Retrieves the current viewport size in pixels. | |
Static Public Member Functions | |
| static void | updateViewForExtent (utility::graphic::ViewF &view, VkExtent2D extent) |
| Updates a view's viewport size and perspective for a new swapchain extent. | |
Public Attributes | |
| std::vector< std::shared_ptr< ASwapchainImage > > | _swapchainImages |
Protected Member Functions | |
| void | createRenderPass (const std::shared_ptr< ADeviceBackend > &deviceBackend, VkSampleCountFlagBits msaaSamples, ColorAttachmentMode mode, uint32_t viewMask=0) |
| Creates the Vulkan render pass for the swapchain context. | |
| VkFormat | selectSwapchainFormat (VkPhysicalDevice physicalDevice, const std::vector< int64_t > &swapchainFormats) |
| Selects the appropriate swapchain format from the available formats. | |
| VkFormat | findSupportedFormat (VkPhysicalDevice physicalDevice, const std::vector< VkFormat > &candidates, VkImageTiling tiling, VkFormatFeatureFlags features) |
| Finds a supported format from a list of candidates based on the specified tiling and feature requirements. | |
Protected Attributes | |
| VkRenderPass | _renderPass |
| utility::graphic::PoseF | _viewOffset {} |
| Persistent world-space offset applied on top of the tracked poses. | |
Detailed Description
Represents the context for managing the swapchain in the rendering system.
The ASwapchainContext class encapsulates the functionality related to managing the swapchain in the rendering system. It is responsible for handling the creation, configuration, and management of the swapchain, which is a series of images used for presenting rendered frames to the display. This class serves as a central point for managing swapchain-related operations in the engine.
Definition at line 41 of file ASwapchainContext.hpp.
Member Function Documentation
◆ aquireImage()
|
pure virtual |
Acquires the next available image from the swapchain for rendering.
This pure virtual function must be implemented by derived classes to handle the acquisition of the next available image from the swapchain for rendering. The function takes several parameters, including the index of the image to acquire, the Vulkan device, a semaphore to signal when the image is available, a fence to signal when the image is in flight, and a reference to store the index of the acquired image. Implement this function to ensure that the rendering system can acquire images from the swapchain for rendering operations.
- Parameters
-
index The index of the image to acquire from the swapchain. device The Vulkan device used to perform the acquisition operation. imageAvailableSemaphore A Vulkan semaphore that will be signaled when the image is available for rendering. inFlightFence A Vulkan fence that will be signaled when the image is in flight (i.e., being rendered). imageIndex A reference to store the index of the acquired image from the swapchain.
- Returns
- A Vulkan result indicating the success or failure of the image acquisition operation.
- Note
- This function is pure virtual and must be implemented by derived classes to handle the specific logic for acquiring images from the swapchain in the context of the rendering system.
Implemented in evan::DesktopSwapchainContext, and evan::XrSwapchainContext.
◆ createRenderPass()
|
protected |
Creates the Vulkan render pass for the swapchain context.
This function is responsible for creating the Vulkan render pass that will be used in the swapchain context. The render pass defines the structure of the rendering operations, including the attachments, subpasses, and dependencies. The function takes a shared pointer to an ADeviceBackend instance, which provides access to the Vulkan device and other resources needed for render pass creation, as well as the number of samples for multisampling (MSAA). Implement this function to ensure that the render pass is properly configured and created according to the requirements of the rendering system and the swapchain configuration.
- Parameters
-
deviceBackend A shared pointer to an ADeviceBackend instance, which provides access to the Vulkan device and other resources needed for render pass creation. msaaSamples The number of samples for multisampling (MSAA) to be used in the render pass. This parameter is essential for configuring the render pass to support multisampling if required by the rendering system. mode How the render pass obtains its single-sampled color attachment: - ColorAttachmentMode::ResolveToSwapchain adds a multisampled color attachment resolved into the swapchain image;
- ColorAttachmentMode::DirectToSwapchain makes the swapchain image the color attachment and presents from it;
- ColorAttachmentMode::SwapchainImageAttachment makes the swapchain image the color attachment and leaves it in the color attachment layout, for runtimes that own and present the image themselves (OpenXR).
- Note
- Implement this function to ensure that the render pass is properly created and configured according to the specific requirements of the rendering system and the swapchain configuration, including support for multisampling if necessary.
- Parameters
-
viewMask Multiview mask for the render pass subpass. A value of 0 keeps a regular single-view render pass; a non-zero mask (for example 0b11 for stereo) chains a VkRenderPassMultiviewCreateInfo and requires the device multiview feature to be enabled and the attachments to have one array layer per view. The default keeps every existing call site on the single-view path.
- See also
- VkRenderPass, ADeviceBackend
◆ destroy()
Destroys the swapchain and releases associated resources.
This pure virtual function must be implemented by derived classes to handle the destruction of the swapchain and the release of any resources associated with it. The function takes a Vulkan device as a parameter, which is used to perform the necessary cleanup operations. Implement this function to ensure that all resources related to the swapchain are properly released when the swapchain is no longer needed.
- Parameters
-
device The Vulkan device used to perform cleanup operations for the swapchain.
- Note
- This function is pure virtual and must be implemented by derived classes to handle the specific cleanup logic for the swapchain in the context of the rendering system.
Implemented in evan::DesktopSwapchainContext, and evan::XrSwapchainContext.
◆ findSupportedFormat()
|
protected |
Finds a supported format from a list of candidates based on the specified tiling and feature requirements.
This function is responsible for finding a supported format from a list of candidate formats based on the specified tiling and feature requirements. The function takes a Vulkan physical device, a vector of candidate VkFormat values, the desired VkImageTiling, and the required VkFormatFeatureFlags as parameters. It queries the Vulkan physical device to determine which of the candidate formats is supported with the specified tiling and features, and returns the first suitable format found. Implement this function to ensure that a compatible format is selected for use in the swapchain context or other rendering operations that require specific format support.
- Parameters
-
physicalDevice The Vulkan physical device used to query the available formats and their support for the specified tiling and feature requirements. This device should be properly initialized and should support the necessary features to ensure that a suitable format can be found. candidates A vector of candidate VkFormat values that should be evaluated to determine which format is supported with the specified tiling and features. These candidates should be chosen based on the requirements of the rendering system and the capabilities of the Vulkan physical device. tiling The desired VkImageTiling that the selected format should support. This parameter specifies the tiling arrangement for images using the selected format and should be chosen based on the intended usage of the images in the rendering system. features The required VkFormatFeatureFlags that the selected format should support. This parameter specifies the features that the format must support, such as sampling, filtering, or rendering capabilities, and should be chosen based on the specific requirements of the rendering operations that will utilize the selected format.
- Returns
- The selected VkFormat that is supported with the specified tiling and features from the list of candidates. This format should be compatible with the rendering operations and provide optimal performance for the intended usage in the swapchain context or other rendering operations.
◆ getMsaaSamples()
|
pure virtual |
Retrieves the MSAA sample count used by this swapchain context.
This is the effective sample count used for the render pass, framebuffer attachments and graphics pipelines. Desktop contexts return the device-level sample count, while OpenXR contexts return the count derived from the runtime's recommended swapchain sample count.
- Returns
- The MSAA sample count used by this swapchain context.
Implemented in evan::DesktopSwapchainContext, and evan::XrSwapchainContext.
◆ getProjection()
| glm::mat4 evan::ASwapchainContext::getProjection | ( | std::size_t | index | ) | const |
Retrieves the projection matrix for the specified view index.
This is a convenience accessor delegating to the ViewSet. The projection matrix is used in rendering operations to transform view space coordinates into clip space for the corresponding view.
- Parameters
-
index The index of the view.
- Returns
- The projection matrix for the specified view.
◆ getRenderPass()
| VkRenderPass evan::ASwapchainContext::getRenderPass | ( | ) | const |
Retrieves the render pass associated with the swapchain context.
This function returns the Vulkan render pass that is associated with the swapchain context. The render pass defines the structure of the rendering operations, including the attachments, subpasses, and dependencies. It is essential for configuring the graphics pipeline and ensuring that rendering operations are performed correctly. Implement this function to provide access to the render pass used in the swapchain context.
- Returns
- The Vulkan render pass associated with the swapchain context.
◆ getSwapchainCount()
| std::size_t evan::ASwapchainContext::getSwapchainCount | ( | ) | const |
Retrieves the number of swapchain image sets in the context.
- Returns
- The number of swapchain image sets.
◆ getView()
| utility::graphic::ViewF evan::ASwapchainContext::getView | ( | std::size_t | index | ) | const |
Retrieves the view matrix for the specified view index.
This is a convenience accessor delegating to the ViewSet. The view matrix is used in rendering operations to transform world coordinates into view space for the corresponding view.
- Parameters
-
index The index of the view.
- Returns
- The view matrix for the specified view.
◆ getViewCount()
| std::size_t evan::ASwapchainContext::getViewCount | ( | void | ) | const |
Retrieves the number of views in the swapchain context.
This is a convenience accessor delegating to the ViewSet.
- Returns
- The number of views.
◆ getViewOffset()
Retrieves the persistent world-space view offset.
Backends that track the viewer independently of the virtual body (OpenXR) store locomotion in this offset so it survives the per-frame pose refresh. The engine reads it to keep tracked hands attached to the virtual body. Backends that do not use it return the identity pose.
- Returns
- The current view offset.
◆ getViewportSize()
| utility::math::Vector2F evan::ASwapchainContext::getViewportSize | ( | ) | const |
Retrieves the current viewport size in pixels.
This function returns the current size of the viewport in pixels, represented as a utility::math::Vector2F object containing the width and height. The viewport size is essential for configuring the rendering pipeline and ensuring that rendered content is correctly sized for presentation. Implement this function to provide access to the current viewport size, which may be determined based on the surface capabilities, window size, or other factors that affect the rendering area.
- Returns
- A utility::math::Vector2F object containing the width and height of the viewport in pixels.
◆ getViewSet() [1/2]
Retrieves the set of views to render (const version).
- Returns
- A const reference to the ViewSet.
Implemented in evan::DesktopSwapchainContext, and evan::XrSwapchainContext.
◆ getViewSet() [2/2]
Retrieves the set of views to render for this swapchain context.
The ViewSet decouples the views (camera poses + projections) from the swapchain image sets. Each view references the swapchain image set it renders into. This pure virtual function must be implemented by derived classes to expose their view configuration.
- Returns
- A mutable reference to the ViewSet.
Implemented in evan::DesktopSwapchainContext, and evan::XrSwapchainContext.
◆ needsSwapchainRecreation()
Indicates whether the swapchain needs to be recreated.
Derived classes signal this when a platform event (such as a window resize) invalidates the current swapchain. The renderer checks this before acquiring images so recreation can happen proactively rather than only after a failed present or acquire.
- Returns
- True when the swapchain must be recreated.
Reimplemented in evan::DesktopSwapchainContext.
◆ recreateSwapchain()
|
pure virtual |
Recreates the swapchain and associated resources.
This pure virtual function must be implemented by derived classes to handle the recreation of the swapchain and any associated resources when the swapchain becomes out of date or needs to be recreated due to changes in the window size or other factors. The function takes a reference to the DeviceContext instance, which provides access to Vulkan resources and synchronization mechanisms, a pointer to the GLFW window, and the Vulkan render pass used for rendering operations. Implement this function to ensure that the swapchain is properly recreated and that all necessary resources are reinitialized for rendering operations.
- Parameters
-
deviceContext A reference to the DeviceContext instance that provides access to Vulkan resources and synchronization mechanisms. renderpass The Vulkan render pass that will be used with the swapchain images during rendering operations.
Implemented in evan::DesktopSwapchainContext, and evan::XrSwapchainContext.
◆ selectSwapchainFormat()
|
protected |
Selects the appropriate swapchain format from the available formats.
This function is responsible for selecting the most suitable swapchain format from the list of available formats provided by the Vulkan physical device. The function takes a vector of int64_t values representing the available swapchain formats and returns the selected VkFormat that best matches the requirements of the rendering system. Implement this function to ensure that the selected swapchain format is compatible with the rendering operations and provides optimal performance for presenting rendered frames to the display.
Reported values are treated as untrusted: preferred formats are matched exactly, other candidates are range-checked before being narrowed to VkFormat, and are only accepted when the physical device supports them as color attachments. An empty or fully invalid list falls back to a format the device is required to support.
- Parameters
-
physicalDevice The Vulkan physical device used to validate that a candidate format is usable as a color attachment. Pass VK_NULL_HANDLE to skip the device support query. swapchainFormats A vector of int64_t values representing the available swapchain formats provided by the runtime or Vulkan physical device. These formats should be evaluated to determine the most suitable format for the swapchain.
- Returns
- The selected VkFormat that best matches the requirements of the rendering system for the swapchain. This format should be compatible with the rendering operations and provide optimal performance for presenting rendered frames to the display. When no candidate is usable, a guaranteed color-attachment format is returned.
- Note
- Implement this function to ensure that the selected swapchain format is chosen based on the specific requirements of the rendering system and the capabilities of the Vulkan physical device, taking into consideration factors such as color space, pixel format, and performance characteristics.
- See also
- VkFormat, Vulkan physical device swapchain formats
◆ setView()
|
virtual |
Sets the view state for the specified view index.
Derived classes that maintain additional view state (such as OpenXR clipping planes) may override this method. The default implementation stores the view in the ViewSet.
- Parameters
-
index The index of the view to set. view The view state to store.
Reimplemented in evan::XrSwapchainContext.
◆ updateViewForExtent()
|
static |
Updates a view's viewport size and perspective for a new swapchain extent.
The viewport size is set to the full extent (width, height). The existing vertical field of view is preserved so the camera transform survives swapchain recreation; when no field of view has been set yet (vertical FOV is zero), a default of 90 degrees (pi/2) is applied.
- Parameters
-
view The view to update in place. extent The new swapchain extent in pixels.
◆ usesImageAvailableSemaphore()
Indicates whether aquireImage signals the image-available semaphore.
Desktop swapchains signal the semaphore through vkAcquireNextImageKHR, while OpenXR swapchains do not (availability is handled by waitForImage). The renderer uses this to decide whether to wait on the semaphore before submitting.
- Returns
- True when the image-available semaphore is signaled.
Reimplemented in evan::DesktopSwapchainContext.
◆ usesMultiview()
Indicates whether the frame renders every view in one pass.
True when this context uses a single layered swapchain with a non-zero render-pass view mask, so all views share one framebuffer and one draw submission. The renderer records one command buffer for the whole frame instead of one per view, and the vertex shader picks the per-view matrices through gl_ViewIndex. Contexts that keep the two-pass path (desktop, or runtime without layered swapchain support) report false.
- Returns
- True when the renderer must record a single multiview pass.
Reimplemented in evan::XrSwapchainContext.
◆ waitForImage()
Waits for the specified image in the swapchain to become available for rendering.
This pure virtual function must be implemented by derived classes to handle waiting for a specific image in the swapchain to become available for rendering. The function takes the index of the image to wait for as a parameter. Implement this function to ensure that the rendering system can synchronize rendering operations with the availability of images in the swapchain.
- Parameters
-
index The index of the image in the swapchain to wait for.
- Note
- This function is pure virtual and must be implemented by derived classes to handle the specific synchronization logic for waiting on images in the swapchain in the context of the rendering system.
Implemented in evan::DesktopSwapchainContext, and evan::XrSwapchainContext.
Member Data Documentation
◆ _renderPass
|
protected |
The Vulkan render pass associated with the swapchain context. The render pass defines the structure of the rendering operations, including the attachments, subpasses, and dependencies. It is essential for configuring the graphics pipeline and ensuring that rendering operations are performed correctly. This member variable should be properly initialized and managed to provide access to the render pass used in the swapchain context.
- Note
- The render pass should be created and configured according to the specific requirements of the rendering system and the swapchain configuration to ensure optimal performance and compatibility with the rendering operations being performed.
Definition at line 393 of file ASwapchainContext.hpp.
◆ _swapchainImages
| std::vector<std::shared_ptr<ASwapchainImage> > evan::ASwapchainContext::_swapchainImages |
A list of shared pointers to ASwapchainImage instances, which represent the images in the swapchain. Each ASwapchainImage encapsulates the properties and resources associated with a single image in the swapchain, such as the image itself, its view, and any associated memory. This vector is used to manage and access the images in the swapchain for rendering operations.
- Note
- The ASwapchainImage instances in this vector should be properly initialized and managed to ensure that the rendering system can effectively utilize the swapchain images for presenting rendered frames to the display.
Definition at line 218 of file ASwapchainContext.hpp.
◆ _viewOffset
|
protected |
Persistent world-space offset applied on top of the tracked poses.
Defaults to the identity pose. Backends that refresh tracked poses every frame (OpenXR) use it to carry locomotion across frames, and the engine reads it to offset tracked hands so they move with the viewer.
Definition at line 404 of file ASwapchainContext.hpp.
The documentation for this class was generated from the following file:
- headers/evan/ASwapchainContext.hpp
