Abstract base class for Vulkan device backends. More...

#include <headers/evan/ADeviceBackend.hpp>

Inheritance diagram for evan::ADeviceBackend:

[legend]

Collaboration diagram for evan::ADeviceBackend:

Classes
struct	CopyBufferProperties
	Encapsulates properties required for copying data between Vulkan buffers. More...

struct	CopyBufferToImageProperties
	Properties required to copy data from a buffer to an image in Vulkan. More...

struct	CreateBufferProperties
	Properties required for creating a Vulkan buffer and allocating its memory. More...

struct	CreateImageProperties
	Encapsulates the properties required to create a Vulkan image and allocate its memory. More...

struct	TransitionImageLayoutProperties
	Encapsulates the properties required to perform an image layout transition in Vulkan. More...

Public Member Functions
virtual	~ADeviceBackend ()
	Virtual destructor for the ADeviceBackend class.

virtual uint32_t	countSwapchainFormats () const =0
	Counts the number of available swapchain formats for the Vulkan device.

virtual std::vector< int64_t >	enumerateSwapchainFormats (uint32_t swapchainFormatCount) const =0
	Enumerates the available swapchain formats for the Vulkan device.

virtual evan::QueueFamilyIndices	findQueueFamilies ()=0
	Finds the queue family indices for the Vulkan physical device.

virtual Error	preprocessFrame (ASwapchainContext &swapchainContext)=0
	Preprocesses a frame before presentation.

virtual Error	processFrame (VkPresentInfoKHR presentInfo, ASwapchainImage &swapchainImage)=0
	Processes a frame for presentation.

virtual Error	postprocessFrame (ASwapchainContext &swapchainContext)=0
	Postprocesses a frame after presentation.

Error	createBuffer (const CreateBufferProperties &properties) const
	Creates a Vulkan buffer and allocates memory for it.

Error	transitionImageLayout (const TransitionImageLayoutProperties &properties) const
	Transitions the layout of a Vulkan image.

VkCommandBuffer	beginSingleTimeCommands (VkCommandPool commandPool) const
	Begins recording a single-use command buffer for one-time operations.

void	endSingleTimeCommands (VkCommandPool commandPool, VkQueue graphicsQueue, VkCommandBuffer commandBuffer) const
	Ends recording of a single-use command buffer and submits it for execution.

Error	createImage (const CreateImageProperties &properties) const
	Creates a Vulkan image and allocates memory for it.

Error	copyBufferToImage (const CopyBufferToImageProperties &properties) const
	Copies data from a Vulkan buffer to a Vulkan image.

Error	copyBuffer (const CopyBufferProperties &properties) const
	Copies data from one Vulkan buffer to another.

Result< VkImageView >	createImageView (VkImage image, VkFormat format, VkImageAspectFlags aspectFlags, uint32_t mipLevels, uint32_t layerCount=1) const
	Creates a Vulkan image view for a given image.

virtual VkDevice	getDevice () const
	Retrieves the Vulkan logical device handle.

virtual VkInstance	getInstance () const
	Retrieves the Vulkan instance handle.

virtual VkPhysicalDevice	getPhysicalDevice () const
	Retrieves the Vulkan physical device handle.

bool	supportsMultiview () const
	Indicates whether multiview rendering is available.

bool	supportsTimestampQueries ()
	Indicates whether GPU timestamp queries can be used.

float	getTimestampPeriod () const
	Nanoseconds per timestamp tick.

uint32_t	getTimestampValidBits ()
	Number of valid bits in a timestamp value.

Protected Member Functions
virtual void	createInstance (const IPlatform &platform, const std::string &appName, Version &appVersion)=0
	Creates a Vulkan instance and initializes the device backend.

virtual void	createLogicalDevice ()=0
	Creates a Vulkan logical device and selects a physical device for rendering.

virtual void	pickPhysicalDevice ()=0
	Selects a suitable Vulkan physical device for rendering.

std::vector< VkLayerProperties >	getAvailableLayers ()
	Retrieves the available Vulkan layers on the system.

Static Protected Member Functions
static bool	queryMultiviewSupport (VkPhysicalDevice physicalDevice, uint32_t apiVersion)
	Queries whether a physical device can run multiview passes.

Protected Attributes
VkPhysicalDevice	_physicalDevice = VK_NULL_HANDLE

VkDevice	_device = VK_NULL_HANDLE

VkInstance	_VkInstance = VK_NULL_HANDLE

bool	_multiviewSupported = false
	Whether the multiview feature was enabled on the logical device created by this backend.

Detailed Description

Abstract base class for Vulkan device backends.

This class defines the interface for Vulkan device backends, providing common functionality for managing Vulkan resources such as buffers, images, and command buffers. It also includes structures for encapsulating properties required for various Vulkan operations, such as copying buffers and transitioning image layouts. Concrete implementations of this class will provide platform-specific logic for creating Vulkan instances, devices, and handling frame processing.

Note: This class is designed to be extended by platform-specific Vulkan device backends, which will implement the pure virtual functions defined here.

Definition at line 45 of file ADeviceBackend.hpp.

Member Function Documentation

◆ beginSingleTimeCommands()

VkCommandBuffer evan::ADeviceBackend::beginSingleTimeCommands ( VkCommandPool commandPool ) const

Begins recording a single-use command buffer for one-time operations.

This function allocates a command buffer from the specified command pool and begins recording it with the VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT flag. The returned command buffer can be used for short operations such as copying buffers or transitioning image layouts, and should be ended and submitted for execution after recording.

Parameters

commandPool The Vulkan command pool from which to allocate the command buffer.

Returns: VkCommandBuffer A handle to the allocated and begun command buffer ready for recording

◆ copyBuffer()

Error evan::ADeviceBackend::copyBuffer ( const CopyBufferProperties & properties ) const

Copies data from one Vulkan buffer to another.

This function is responsible for copying data from a source Vulkan buffer to a destination Vulkan buffer based on the provided properties, which include the logical device, command pool, graphics queue, source buffer destination buffer, and the size of the data to copy. The function will record and submit a command buffer that performs the copy operation, ensuring that the data is transferred correctly from the source buffer to the destination buffer.

Parameters

properties A structure containing all necessary parameters for copying data from a buffer to another buffer, including device handles, command pool, graphics queue, source buffer, destination buffer, and the size of the data to copy.

Returns: evan::Error::Ok on success, or a mapped error otherwise.

◆ copyBufferToImage()

Error evan::ADeviceBackend::copyBufferToImage ( const CopyBufferToImageProperties & properties ) const

Copies data from a Vulkan buffer to a Vulkan image.

This function is responsible for copying data from a Vulkan buffer to a Vulkan image based on the provided properties, which include the logical device, command pool, graphics queue, source buffer, destination image, and the dimensions of the image. The function will record and submit a command buffer that performs the copy operation, ensuring that the data is transferred correctly from the buffer to the image.

Parameters

properties A structure containing all necessary parameters for copying data from a buffer to an image, including device handles, command pool, graphics queue, source buffer, destination image, and image dimensions.

Returns: evan::Error::Ok on success, or a mapped error otherwise.

◆ countSwapchainFormats()

virtual uint32_t evan::ADeviceBackend::countSwapchainFormats ( ) const

pure virtual

Counts the number of available swapchain formats for the Vulkan device.

This function queries the Vulkan API to determine how many swapchain formats are supported by the physical device. The count of swapchain formats is essential for creating a swapchain that is compatible with the device's capabilities.

Returns: uint32_t The number of available swapchain formats supported by the Vulkan device.

Implemented in evan::DesktopBackend, and evan::XrDeviceBackend.

◆ createBuffer()

Error evan::ADeviceBackend::createBuffer ( const CreateBufferProperties & properties ) const

Creates a Vulkan buffer and allocates memory for it.

This function is responsible for creating a Vulkan buffer based on the provided properties, which include the logical device, physical device, buffer size, usage flags, memory properties, and references to the resulting buffer and its memory. The function will create the buffer and allocate the necessary memory for it, ensuring that it is ready for use in Vulkan operations.

Parameters

properties A structure containing all necessary parameters for buffer creation and memory allocation, including device handles, buffer size, usage flags, memory properties, and references to the resulting buffer and memory objects.

Returns: evan::Error::Ok on success, or a mapped error otherwise.

◆ createImage()

Error evan::ADeviceBackend::createImage ( const CreateImageProperties & properties ) const

Creates a Vulkan image and allocates memory for it.

This function is responsible for creating a Vulkan image based on the provided properties, which include the logical device, physical device, image dimensions, format, tiling, usage flags, memory properties, and references to the resulting image and its memory. The function will create the image and allocate the necessary memory for it, ensuring that it is ready for use in Vulkan operations.

Parameters

properties A structure containing all necessary parameters for image creation and memory allocation, including device handles, image dimensions, format, usage flags, and references to the resulting image and memory objects.

Returns: evan::Error::Ok on success, or a mapped error otherwise.

◆ createImageView()

Result< VkImageView > evan::ADeviceBackend::createImageView	(	VkImage	image,
		VkFormat	format,
		VkImageAspectFlags	aspectFlags,
		uint32_t	mipLevels,
		uint32_t	layerCount = `1`
	)		const

Creates a Vulkan image view for a given image.

This function sets up and creates a Vulkan image view, which is used to describe how an image resource should be accessed. It specifies the format, view type, and subresource range for the image view.

Parameters

image	The Vulkan image for which the image view is created.
format	The format of the image view (e.g., VK_FORMAT_R8G8B8A8_SRGB).
aspectFlags	Specifies which aspect(s) of the image are included in the view (e.g., VK_IMAGE_ASPECT_COLOR_BIT for color images).
mipLevels	The number of mipmap levels in the image, which determines the range of mip levels included in the image view.
layerCount	The number of array layers included in the view. A value greater than one creates a VK_IMAGE_VIEW_TYPE_2D_ARRAY view, used by multiview attachments; the default keeps plain 2D views.

Returns: A Result holding the created image view, or a mapped error.

◆ createInstance()

virtual void evan::ADeviceBackend::createInstance	(	const IPlatform &	platform,
		const std::string &	appName,
		Version &	appVersion
	)

protectedpure virtual

Creates a Vulkan instance and initializes the device backend.

This function is responsible for creating a Vulkan instance and performing any necessary initialization for the device backend. It takes the platform information, application name, and application version as parameters to set up the Vulkan instance with the appropriate application info and extensions.

Parameters

platform	The platform information used to determine required Vulkan instance extensions.
appName	The name of the application, used in the Vulkan application info.
appVersion	The version of the application, used in the Vulkan application info.

Exceptions

std::runtime_error If instance creation fails or required extensions are not available.

Note: This function is pure virtual and must be implemented by derived classes to provide platform-specific Vulkan instance creation logic.

Implemented in evan::DesktopBackend, and evan::XrDeviceBackend.

◆ createLogicalDevice()

virtual void evan::ADeviceBackend::createLogicalDevice ( )

protectedpure virtual

Creates a Vulkan logical device and selects a physical device for rendering.

This function is responsible for selecting a suitable Vulkan physical device (GPU) and creating a logical device that can be used for rendering operations. It typically involves querying the available physical devices, checking their capabilities, and creating a logical device with the necessary queues and features enabled.

Exceptions

std::runtime_error If no suitable physical device is found or if logical device creation fails.

Note: This function is pure virtual and must be implemented by derived classes to provide platform-specific logic for physical device selection and logical device creation.

Implemented in evan::DesktopBackend, and evan::XrDeviceBackend.

◆ endSingleTimeCommands()

void evan::ADeviceBackend::endSingleTimeCommands	(	VkCommandPool	commandPool,
		VkQueue	graphicsQueue,
		VkCommandBuffer	commandBuffer
	)		const

Ends recording of a single-use command buffer and submits it for execution.

This function ends the recording of the provided command buffer, submits it to the specified graphics queue, and waits for the queue to become idle before returning. It is typically used in conjunction with beginSingleTimeCommands() for short operations that require immediate execution, such as copying buffers or transitioning image layouts.

Parameters

commandPool	The Vulkan command pool from which the command buffer was allocated.
graphicsQueue	The Vulkan graphics queue to which the command buffer will be submitted for execution.
commandBuffer	The Vulkan command buffer that has been recorded and is ready to be ended and submitted.

Note: TODO: Remove useless properties (such as the logical device which is already a member of the class).

◆ enumerateSwapchainFormats()

virtual std::vector< int64_t > evan::ADeviceBackend::enumerateSwapchainFormats ( uint32_t swapchainFormatCount ) const

pure virtual

Enumerates the available swapchain formats for the Vulkan device.

This function retrieves the list of supported swapchain formats from the Vulkan API. It takes the count of swapchain formats as a parameter and returns a vector of int64_t values representing the available formats. These formats are crucial for configuring the swapchain to ensure compatibility with the device's capabilities.

Parameters

swapchainFormatCount The number of swapchain formats to enumerate, typically obtained from countSwapchainFormats().

Returns: std::vector<int64_t> A vector containing the enumerated swapchain formats supported by the Vulkan device.

Implemented in evan::DesktopBackend, and evan::XrDeviceBackend.

◆ findQueueFamilies()

virtual evan::QueueFamilyIndices evan::ADeviceBackend::findQueueFamilies ( )

pure virtual

Finds the queue family indices for the Vulkan physical device.

This function queries the Vulkan API to find the indices of the queue families that support graphics and presentation operations. It returns a QueueFamilyIndices structure containing the indices of the graphics and presentation queue families, if they are found. If the required queue families are not found, the corresponding optional values in the QueueFamilyIndices structure will be empty.

Returns: evan::QueueFamilyIndices A structure containing the indices of the graphics and presentation queue families for the Vulkan physical device.

Implemented in evan::DesktopBackend, and evan::XrDeviceBackend.

◆ getAvailableLayers()

std::vector< VkLayerProperties > evan::ADeviceBackend::getAvailableLayers ( )

protected

Retrieves the available Vulkan layers on the system.

Returns: std::vector<VkLayerProperties> A vector containing the properties of the available Vulkan layers.

This function queries the Vulkan API to enumerate the available instance layers and returns a vector of VkLayerProperties structures containing information about each layer.

◆ getDevice()

virtual VkDevice evan::ADeviceBackend::getDevice ( ) const

inlinevirtual

Retrieves the Vulkan logical device handle.

This narrow accessor exposes the logical device to consumers without allowing them to mutate it or bypass the abstraction. Backends that do not own a Vulkan device (e.g., headless or non-Vulkan) may override it to return VK_NULL_HANDLE or throw.

Returns: VkDevice The logical device used for rendering operations.

Definition at line 562 of file ADeviceBackend.hpp.

◆ getInstance()

virtual VkInstance evan::ADeviceBackend::getInstance ( ) const

inlinevirtual

Retrieves the Vulkan instance handle.

Returns: VkInstance The Vulkan instance owned by this backend.

Definition at line 572 of file ADeviceBackend.hpp.

◆ getPhysicalDevice()

virtual VkPhysicalDevice evan::ADeviceBackend::getPhysicalDevice ( ) const

inlinevirtual

Retrieves the Vulkan physical device handle.

Returns: VkPhysicalDevice The physical device selected by this backend.

Definition at line 583 of file ADeviceBackend.hpp.

◆ getTimestampPeriod()

float evan::ADeviceBackend::getTimestampPeriod ( ) const

Nanoseconds per timestamp tick.

VkPhysicalDeviceLimits::timestampPeriod; may be fractional (e.g. 2 ns on some devices). Only meaningful when supportsTimestampQueries() is true.

Returns: The tick period in nanoseconds.

◆ getTimestampValidBits()

uint32_t evan::ADeviceBackend::getTimestampValidBits ( )

Number of valid bits in a timestamp value.

The high bits are undefined when the device reports fewer than 64 valid bits. Only meaningful when supportsTimestampQueries() is true.

Returns: The number of valid bits, up to 64.

◆ pickPhysicalDevice()

virtual void evan::ADeviceBackend::pickPhysicalDevice ( )

protectedpure virtual

Selects a suitable Vulkan physical device for rendering.

This function is responsible for picking a Vulkan physical device (GPU) that meets the requirements of the application. It typically involves enumerating the available physical devices, checking their properties and features, and selecting one that is compatible with the application's needs (e.g., supports required queue families, extensions, and features).

Exceptions

std::runtime_error If no suitable physical device is found.

Note: This function is pure virtual and must be implemented by derived classes to provide platform-specific logic for physical device selection.

Implemented in evan::DesktopBackend, and evan::XrDeviceBackend.

◆ postprocessFrame()

virtual Error evan::ADeviceBackend::postprocessFrame ( ASwapchainContext & swapchainContext )

pure virtual

Postprocesses a frame after presentation.

This function is called after the presentation of a frame and allows for any necessary postprocessing steps to be performed on the swapchain context. It takes a reference to an ASwapchainContext object, which contains information about the current state of the swapchain and the images being presented. The function returns a boolean value indicating whether the postprocessing was successful.

Parameters

swapchainContext A reference to the ASwapchainContext object containing information about the swapchain and images for the current frame.

Returns: true if postprocessing was successful, false otherwise.

Implemented in evan::DesktopBackend, and evan::XrDeviceBackend.

◆ preprocessFrame()

virtual Error evan::ADeviceBackend::preprocessFrame ( ASwapchainContext & swapchainContext )

pure virtual

Preprocesses a frame before presentation.

This function is called before the presentation of a frame and allows for any necessary preprocessing steps to be performed on the swapchain context. It takes a reference to an ASwapchainContext object, which contains information about the current state of the swapchain and the images being presented. The function returns a boolean value indicating whether the preprocessing was successful and if the frame is ready for presentation.

Parameters

swapchainContext A reference to the ASwapchainContext object containing information about the swapchain and images for the current frame.

Returns: true if preprocessing was successful and the frame is ready for presentation, false otherwise

Implemented in evan::DesktopBackend, and evan::XrDeviceBackend.

◆ processFrame()

virtual Error evan::ADeviceBackend::processFrame	(	VkPresentInfoKHR	presentInfo,
		ASwapchainImage &	swapchainImage
	)

pure virtual

Processes a frame for presentation.

This function is called to process a frame for presentation and handles the actual presentation logic. It takes the presentation information and the swapchain image to be presented.

Parameters

presentInfo	The presentation information for the frame.
swapchainImage	The swapchain image to be presented.

Returns: true if the frame was processed successfully, false otherwise.

Implemented in evan::DesktopBackend, and evan::XrDeviceBackend.

◆ queryMultiviewSupport()

static bool evan::ADeviceBackend::queryMultiviewSupport	(	VkPhysicalDevice	physicalDevice,
		uint32_t	apiVersion
	)

staticprotected

Queries whether a physical device can run multiview passes.

Checks VkPhysicalDeviceMultiviewFeatures::multiview and requires at least two supported views (maxMultiviewViewCount). The feature queries are core Vulkan 1.1 commands, so an instance API version below 1.1 reports unsupported.

Parameters

physicalDevice	The physical device to query.
apiVersion	The Vulkan API version of the instance the device belongs to.

Returns: True when multiview is supported and can be enabled.

◆ supportsMultiview()

bool evan::ADeviceBackend::supportsMultiview ( ) const

inline

Indicates whether multiview rendering is available.

True when the physical device supports VkPhysicalDeviceMultiviewFeatures::multiview with at least two views and the backend enabled the feature on its logical device. The swapchain contexts only use a non-zero render-pass view mask when this is true, because the ViewIndex shader input requires the feature; renderers may use the same signal to pick multiview shaders.

Returns: True when multiview may be used.

Definition at line 601 of file ADeviceBackend.hpp.

◆ supportsTimestampQueries()

bool evan::ADeviceBackend::supportsTimestampQueries ( )

Indicates whether GPU timestamp queries can be used.

True when the physical device reports graphics-capable timestamps (VkPhysicalDeviceLimits::timestampComputeAndGraphics) with at least one valid bit and a known tick period. The frame statistics use this to decide whether per-pass GPU timings can be collected; the CPU instrumentation works regardless.

Returns: True when timestamp queries are supported.

◆ transitionImageLayout()

Error evan::ADeviceBackend::transitionImageLayout ( const TransitionImageLayoutProperties & properties ) const

Transitions the layout of a Vulkan image.

This function is responsible for transitioning the layout of a Vulkan image from one state to another. It takes the necessary properties for the layout transition and performs the operation on the specified image.

Parameters

properties A structure containing all necessary parameters for the image layout transition, including device, command pool, queue, image, format, old and new layouts, and the number of mipmap levels.

Returns: evan::Error::Ok on success, or a mapped error otherwise.

Member Data Documentation

◆ _device

VkDevice evan::ADeviceBackend::_device = VK_NULL_HANDLE

protected

The logical device, which represents an instance of a physical device and is used to perform rendering operations. It is created from a physical device and provides access to the GPU's resources and capabilities.

Definition at line 656 of file ADeviceBackend.hpp.

◆ _multiviewSupported

bool evan::ADeviceBackend::_multiviewSupported = false

protected

Whether the multiview feature was enabled on the logical device created by this backend.

Set by the concrete backends during device creation through queryMultiviewSupport(); exposed through supportsMultiview().

Definition at line 672 of file ADeviceBackend.hpp.

◆ _physicalDevice

VkPhysicalDevice evan::ADeviceBackend::_physicalDevice = VK_NULL_HANDLE

protected

The physical device, which represents a Vulkan-compatible GPU. It is used to query the capabilities of the GPU and to create logical devices for rendering operations.

Definition at line 648 of file ADeviceBackend.hpp.

◆ _VkInstance

VkInstance evan::ADeviceBackend::_VkInstance = VK_NULL_HANDLE

protected

The Vulkan instance, which is the connection between the application and the Vulkan library. It is used to create and manage Vulkan resources and to query the capabilities of the Vulkan implementation.

Definition at line 663 of file ADeviceBackend.hpp.

The documentation for this class was generated from the following file:

headers/evan/ADeviceBackend.hpp

Classes

Public Member Functions

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Detailed Description

Member Function Documentation

◆ beginSingleTimeCommands()

◆ copyBuffer()

◆ copyBufferToImage()

◆ countSwapchainFormats()

◆ createBuffer()

◆ createImage()

◆ createImageView()

◆ createInstance()

◆ createLogicalDevice()

◆ endSingleTimeCommands()

◆ enumerateSwapchainFormats()

◆ findQueueFamilies()

◆ getAvailableLayers()

◆ getDevice()

◆ getInstance()

◆ getPhysicalDevice()

◆ getTimestampPeriod()

◆ getTimestampValidBits()

◆ pickPhysicalDevice()

◆ postprocessFrame()

◆ preprocessFrame()

◆ processFrame()

◆ queryMultiviewSupport()

◆ supportsMultiview()

◆ supportsTimestampQueries()

◆ transitionImageLayout()

Member Data Documentation

◆ _device

◆ _multiviewSupported

◆ _physicalDevice

◆ _VkInstance