The XrDeviceBackend class is responsible for managing the OpenXR device backend, including instance creation, session management, and frame processing. More...

#include <headers/evan/openxr/XrDeviceBackend.hpp>

Inheritance diagram for evan::XrDeviceBackend:

[legend]

Collaboration diagram for evan::XrDeviceBackend:

[legend]

Public Member Functions
	XrDeviceBackend (const IPlatform &platform)
	Constructs an XrDeviceBackend instance with the specified platform.

Error	preprocessFrame (ASwapchainContext &swapchainContext) override
	Prepares the current frame for rendering in an OpenXR session.

Error	processFrame (VkPresentInfoKHR presentInfo, ASwapchainImage &swapchainImage) override
	Processes a frame by releasing the OpenXR swapchain image.

Error	postprocessFrame (ASwapchainContext &swapchainContext) override
	Postprocesses a frame and submits it to the OpenXR compositor.

QueueFamilyIndices	findQueueFamilies () override
	Finds the queue family indices for graphics and presentation operations.

uint32_t	countSwapchainFormats () const override
	Count the number of available swapchain formats for the Vulkan device.

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

std::vector< XrViewConfigurationView >	enumerateViewConfigurations () const
	Enumerates the available view configurations for the OpenXR system.

std::vector< std::shared_ptr< utility::event::Event > >	pollActions ()
	Polls input actions for the OpenXR session.

XrSession	getSession () const
	Retrieves the OpenXR session handle.

XrViewConfigurationType	getViewConfigurationType () const
	Retrieves the primary view configuration type selected for this OpenXR system.

const OpenXrOptions &	getOpenXrOptions () const
	Retrieves the user-configurable OpenXR options.

std::vector< XrViewConfigurationType >	enumerateViewConfigurationTypes () const
	Enumerates the primary view configuration types supported by the OpenXR system.

Public Member Functions inherited from evan::ADeviceBackend
virtual	~ADeviceBackend ()
	Virtual destructor for the ADeviceBackend class.

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.

Static Public Member Functions
static XrViewConfigurationType	selectViewConfigurationType (const std::vector< XrViewConfigurationType > &configurations)
	Selects a primary view configuration type from the ones supported by the runtime.

Public Attributes
XrInstance	_XrInstance = XR_NULL_HANDLE

XrSystemId	_systemId = XR_NULL_SYSTEM_ID

XrSession	_session = XR_NULL_HANDLE

XrSpace	_space = XR_NULL_HANDLE

std::unique_ptr< XrManageActions >	_actionManager
	The action manager for handling input actions in the OpenXR session.

bool	_sessionRunning = false

XrTime	_predictedDisplayTime = 0

std::array< XrPath, _handCount >	_handActionSubactionPath

Static Public Attributes
static const size_t	_handCount = 2

Protected Member Functions
void	createInstance (const IPlatform &platform, const std::string &appName, Version &appVersion) override
	Creates an OpenXR instance with the specified application name and version.

void	createLogicalDevice () override
	Creates a logical device for the OpenXR session.

void	pickPhysicalDevice () override
	Picks a physical device that is compatible with the OpenXR session.

void	createVisualizedSpace ()
	Creates a visualized space for the XR session.

std::vector< VkExtensionProperties >	getInstanceExtensions () const

Protected Member Functions inherited from evan::ADeviceBackend
std::vector< VkLayerProperties >	getAvailableLayers ()
	Retrieves the available Vulkan layers on the system.

Additional Inherited Members
Static Protected Member Functions inherited from evan::ADeviceBackend
static bool	queryMultiviewSupport (VkPhysicalDevice physicalDevice, uint32_t apiVersion)
	Queries whether a physical device can run multiview passes.

Protected Attributes inherited from evan::ADeviceBackend
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

The XrDeviceBackend class is responsible for managing the OpenXR device backend, including instance creation, session management, and frame processing.

This class encapsulates the functionality required to interface with the OpenXR runtime, including creating an instance, picking a physical device, creating a logical device, and managing the rendering loop for XR applications. It also handles platform-specific configurations and extensions required for OpenXR on different platforms.

Definition at line 38 of file XrDeviceBackend.hpp.

Constructor & Destructor Documentation

◆ XrDeviceBackend()

evan::XrDeviceBackend::XrDeviceBackend ( const IPlatform & platform )

Constructs an XrDeviceBackend instance with the specified platform.

Initializes the OpenXR instance and retrieves the system ID for the XR device. It also sets up the necessary resources for managing the XR session and rendering loop.

Parameters

platform The platform interface providing required extensions and configurations for OpenXR instance creation.

Definition at line 15 of file XrDeviceBackend.cpp.

Here is the call graph for this function:

◆ ~XrDeviceBackend()

evan::XrDeviceBackend::~XrDeviceBackend ( )

override

Definition at line 46 of file XrDeviceBackend.cpp.

Member Function Documentation

◆ countSwapchainFormats()

uint32_t evan::XrDeviceBackend::countSwapchainFormats ( ) const

overridevirtual

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

This method queries the OpenXR runtime 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.

Implements evan::ADeviceBackend.

Definition at line 207 of file XrDeviceBackend.cpp.

◆ createInstance()

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

overrideprotectedvirtual

Creates an OpenXR instance with the specified application name and version.

This method initializes the OpenXR instance by configuring the necessary parameters, including the application name and version. It also retrieves the required instance extensions from the platform and includes them in the instance creation process. The created instance is stored in the member variable _XrInstance for later use in managing the XR session and rendering.

Parameters

platform	The platform interface providing required extensions and configurations for OpenXR instance creation.
appName	The name of the application, used for identifying the application to the OpenXR runtime.
appVersion	The version of the application, used for identifying the application to the

Implements evan::ADeviceBackend.

Definition at line 320 of file XrDeviceBackend.cpp.

Here is the caller graph for this function:

◆ createLogicalDevice()

void evan::XrDeviceBackend::createLogicalDevice ( )

overrideprotectedvirtual

Creates a logical device for the OpenXR session.

This method sets up the necessary resources and configurations to create a logical device that can be used for rendering and interacting with the OpenXR session. It involves selecting appropriate queue families, configuring device features, and creating the logical device using the OpenXR runtime. The created logical device is essential for submitting rendering commands and managing resources within the XR environment.

Note: The implementation of this method may involve platform-specific configurations and may require additional parameters depending on the requirements of the OpenXR runtime and the capabilities of the underlying hardware.

Implements evan::ADeviceBackend.

Definition at line 429 of file XrDeviceBackend.cpp.

Here is the caller graph for this function:

◆ createVisualizedSpace()

void evan::XrDeviceBackend::createVisualizedSpace ( )

protected

Creates a visualized space for the XR session.

This method sets up a reference space that can be used for rendering and tracking within the XR environment. It defines the coordinate system for the application and allows for accurate tracking of the XR device's position and orientation in the virtual space.

Note: This function should be called after creating the OpenXR session and before starting the rendering loop to ensure that the application has a valid space for rendering and tracking.

Definition at line 554 of file XrDeviceBackend.cpp.

Here is the caller graph for this function:

◆ enumerateSwapchainFormats()

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

overridevirtual

Enumerates the available swapchain formats for the Vulkan device.

This method retrieves the list of supported swapchain formats from the OpenXR runtime. 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.

Implements evan::ADeviceBackend.

Definition at line 214 of file XrDeviceBackend.cpp.

◆ enumerateViewConfigurations()

std::vector< XrViewConfigurationView > evan::XrDeviceBackend::enumerateViewConfigurations ( ) const

Enumerates the available view configurations for the OpenXR system.

This method queries the OpenXR runtime to retrieve the list of supported view configurations for the XR system. It returns a vector of XrViewConfigurationView structures, each containing information about a specific view configuration, such as recommended image rect dimensions and swapchain sample counts. This information is essential for setting up the rendering pipeline to match the capabilities of the XR device.

Returns: std::vector<XrViewConfigurationView> A vector containing the enumerated view configurations supported by the OpenXR system. Each entry in the vector provides details about a specific view configuration, which can be used to configure the rendering pipeline accordingly.

Definition at line 227 of file XrDeviceBackend.cpp.

◆ enumerateViewConfigurationTypes()

std::vector< XrViewConfigurationType > evan::XrDeviceBackend::enumerateViewConfigurationTypes ( ) const

Enumerates the primary view configuration types supported by the OpenXR system.

Returns: std::vector<XrViewConfigurationType> The supported primary view configuration types, or an empty vector on failure.

Definition at line 251 of file XrDeviceBackend.cpp.

Here is the caller graph for this function:

◆ findQueueFamilies()

evan::QueueFamilyIndices evan::XrDeviceBackend::findQueueFamilies ( )

overridevirtual

Finds the queue family indices for graphics and presentation operations.

This method queries the OpenXR runtime to determine the queue family indices 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: QueueFamilyIndices A structure containing the indices of the graphics and presentation queue families, if available.

Implements evan::ADeviceBackend.

Definition at line 183 of file XrDeviceBackend.cpp.

◆ getInstanceExtensions()

std::vector< VkExtensionProperties > evan::XrDeviceBackend::getInstanceExtensions ( ) const

protected

Retrieves the list of Vulkan instance extensions available for the validation layer.

This function enumerates all instance extension properties supported by the VK_LAYER_KHRONOS_validation layer. It performs two queries: first to determine the number of available extensions, then to retrieve the full extension list.

Returns: A vector of VkExtensionProperties containing all available instance extensions. Returns an empty vector if enumeration fails at any step.

Note: The function queries extensions specifically for the "VK_LAYER_KHRONOS_validation" layer.

Definition at line 581 of file XrDeviceBackend.cpp.

◆ getOpenXrOptions()

const OpenXrOptions & evan::XrDeviceBackend::getOpenXrOptions ( ) const

inline

Retrieves the user-configurable OpenXR options.

These are copied from the platform when the backend is constructed.

Returns: A const reference to the OpenXR options used by this backend.

Definition at line 263 of file XrDeviceBackend.hpp.

◆ getSession()

XrSession evan::XrDeviceBackend::getSession ( ) const

inline

Retrieves the OpenXR session handle.

Returns: XrSession The active OpenXR session, or XR_NULL_HANDLE if the session has not been created.

Definition at line 236 of file XrDeviceBackend.hpp.

◆ getViewConfigurationType()

XrViewConfigurationType evan::XrDeviceBackend::getViewConfigurationType ( ) const

inline

Retrieves the primary view configuration type selected for this OpenXR system.

The value is chosen during construction by enumerating the view configurations supported by the runtime and preferring stereo over mono.

Returns: XrViewConfigurationType The selected view configuration type.

Definition at line 251 of file XrDeviceBackend.hpp.

◆ pickPhysicalDevice()

void evan::XrDeviceBackend::pickPhysicalDevice ( )

overrideprotectedvirtual

Picks a physical device that is compatible with the OpenXR session.

This method queries the OpenXR runtime to identify and select a physical device (e.g., GPU) that is compatible with the requirements of the XR session. It evaluates the available devices based on their capabilities, such as support for required features and extensions, and selects the most suitable device for rendering and interaction within the XR environment. The selected physical device is essential for creating a logical device and managing resources for the XR session.

Note: The implementation of this method may involve platform-specific considerations and may require additional parameters to evaluate the capabilities of the available devices effectively.

Implements evan::ADeviceBackend.

Definition at line 518 of file XrDeviceBackend.cpp.

Here is the caller graph for this function:

◆ pollActions()

std::vector< std::shared_ptr< utility::event::Event > > evan::XrDeviceBackend::pollActions ( )

Polls input actions for the OpenXR session.

This method is responsible for polling the input actions defined for the OpenXR session, including actions for the left and right hands. It interacts with the action manager to retrieve the current state of input actions and to handle any user interactions within the XR environment. Polling actions is essential for enabling responsive and interactive experiences in the XR application.

Note: The implementation of this method may involve querying the action manager for the state of various input actions and generating events based on the retrieved state, which can then be processed by the application to respond to user input in the XR environment.

Returns: A vector of shared pointers to events representing the current state of all managed actions, which can be used by the application to respond to user input in the XR environment.

Definition at line 299 of file XrDeviceBackend.cpp.

◆ postprocessFrame()

evan::Error evan::XrDeviceBackend::postprocessFrame ( ASwapchainContext & swapchainContext )

overridevirtual

Postprocesses a frame and submits it to the OpenXR compositor.

This method updates the projection layer views for the given swapchain context, constructs a composition layer with the updated views, and submits the frame to the OpenXR runtime via xrEndFrame().

Parameters

swapchainContext Reference to the swapchain context to postprocess. Must be a valid evan::XrSwapchainContext instance.

Returns: evan::Error::Ok if the frame was successfully submitted to the OpenXR runtime, or a mapped error if xrEndFrame() failed.

Updates projection layer views in the swapchain context
Constructs an XrCompositionLayerProjection with the updated views
Sets the frame end info with predicted display time and opaque blend mode
Submits the frame to the OpenXR session
Logs errors to stderr if frame submission fails

Note: The swapchain context is cast to evan::XrSwapchainContext during processing. Ensure the provided context is of the correct derived type.

Implements evan::ADeviceBackend.

Definition at line 153 of file XrDeviceBackend.cpp.

◆ preprocessFrame()

evan::Error evan::XrDeviceBackend::preprocessFrame ( ASwapchainContext & swapchainContext )

overridevirtual

Prepares the current frame for rendering in an OpenXR session.

This method performs frame synchronization and view localization for OpenXR rendering. It waits for the next frame, begins frame processing, and retrieves the current view configurations. If the runtime indicates rendering should be skipped, the frame is properly concluded without processing.

Parameters

[in,out] swapchainContext Reference to the swapchain context that will be populated with view information for rendering.

Returns: evan::Error::Ok if rendering should proceed, evan::Error::NotReady if the session is not running or the runtime indicates rendering should be skipped, or a mapped error if an OpenXR call fails.

The method performs the following operations:

Verifies the XR session is running
Waits for the next frame from the runtime
Begins frame processing
Stores the predicted display time for rendering
Checks if rendering is required for this frame
If rendering is skipped, ends the frame with empty layer data
Locates and stores the current view poses and positions

Note: The swapchainContext must be castable to evan::XrSwapchainContext.; On early return (evan::Error::NotReady), the frame may still be submitted to the runtime with empty content if shouldRender is false.

See also: xrWaitFrame, xrBeginFrame, xrEndFrame, xrLocateViews

Implements evan::ADeviceBackend.

Definition at line 76 of file XrDeviceBackend.cpp.

◆ processFrame()

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

overridevirtual

Processes a frame by releasing the OpenXR swapchain image.

This function releases the swapchain image associated with the given presentation information back to the OpenXR runtime for reuse.

Parameters

presentInfo	The Vulkan present information for the frame (currently unused).
swapchainImage	Reference to the swapchain image to be released. Must be castable to evan::XrSwapchainImage.

Returns: evan::Error::Ok if the swapchain image was released successfully, or a mapped error otherwise.

See also: XrSwapchainImageReleaseInfo; xrReleaseSwapchainImage

Implements evan::ADeviceBackend.

Definition at line 133 of file XrDeviceBackend.cpp.

◆ selectViewConfigurationType()

XrViewConfigurationType evan::XrDeviceBackend::selectViewConfigurationType ( const std::vector< XrViewConfigurationType > & configurations )

static

Selects a primary view configuration type from the ones supported by the runtime.

Prefers XR_VIEW_CONFIGURATION_TYPE_PRIMARY_STEREO, then XR_VIEW_CONFIGURATION_TYPE_PRIMARY_MONO, then the first entry. If no configuration is provided, PRIMARY_MONO is returned as a safe fallback.

Parameters

configurations The view configuration types enumerated from the OpenXR system.

Returns: XrViewConfigurationType The most appropriate configuration for a head-mounted display.

Definition at line 279 of file XrDeviceBackend.cpp.

Here is the caller graph for this function:

Member Data Documentation

◆ _actionManager

std::unique_ptr<XrManageActions> evan::XrDeviceBackend::_actionManager

The action manager for handling input actions in the OpenXR session.

This member variable is responsible for managing the input actions defined for the OpenXR session, including actions for the left and right hands. It encapsulates the functionality required to create and manage action sets, as well as to handle input from various input sources such as controllers and hand tracking. The action manager is essential for enabling interactive experiences in the XR environment by allowing the application to respond to user input in a flexible and extensible manner.

Definition at line 343 of file XrDeviceBackend.hpp.

◆ _handActionSubactionPath

std::array<XrPath, _handCount> evan::XrDeviceBackend::_handActionSubactionPath

Subaction paths for hand input actions, used to differentiate between left and right hand actions in the OpenXR session. These paths are used when polling input actions to determine which hand is associated with a particular action state, allowing for accurate handling of user input from both hands in the XR environment.

Definition at line 378 of file XrDeviceBackend.hpp.

◆ _handCount

const size_t evan::XrDeviceBackend::_handCount = 2

static

The count of view configurations available for the XR system, which indicates how many different ways the application can render content based on the capabilities of the XR device. This count is used to manage rendering for multiple views, such as for stereo rendering in VR applications.

Definition at line 369 of file XrDeviceBackend.hpp.

◆ _predictedDisplayTime

XrTime evan::XrDeviceBackend::_predictedDisplayTime = 0

The predicted display time for the next frame, used for synchronizing rendering with the XR device's display refresh cycle. It is updated each frame to ensure smooth and responsive rendering in the XR environment.

Definition at line 360 of file XrDeviceBackend.hpp.

◆ _session

XrSession evan::XrDeviceBackend::_session = XR_NULL_HANDLE

The OpenXR session, which represents an active connection to the XR system. It is used to manage the lifecycle of the XR experience and to submit rendering commands for display on the XR device.

Definition at line 319 of file XrDeviceBackend.hpp.

◆ _sessionRunning

bool evan::XrDeviceBackend::_sessionRunning = false

Flag to track if the session is currently running.

This is used to determine if the application should continue running or if it should exit based on the session state changes received from the OpenXR runtime.

Definition at line 352 of file XrDeviceBackend.hpp.

◆ _space

XrSpace evan::XrDeviceBackend::_space = XR_NULL_HANDLE

The OpenXR space, which defines a coordinate system for the application. It is used to track the position and orientation of the XR device and to render content in the correct location within the XR environment.

Definition at line 328 of file XrDeviceBackend.hpp.

◆ _systemId

XrSystemId evan::XrDeviceBackend::_systemId = XR_NULL_SYSTEM_ID

The OpenXR system ID, which represents the specific XR system (e.g., VR headset) that the application is targeting. It is used to query the capabilities of the XR system and to create sessions for rendering.

Definition at line 311 of file XrDeviceBackend.hpp.

◆ _XrInstance

XrInstance evan::XrDeviceBackend::_XrInstance = XR_NULL_HANDLE

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

Definition at line 302 of file XrDeviceBackend.hpp.

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

headers/evan/openxr/XrDeviceBackend.hpp
sources/openxr/XrDeviceBackend.cpp

Public Member Functions

Static Public Member Functions

Public Attributes

Static Public Attributes

Protected Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ XrDeviceBackend()

◆ ~XrDeviceBackend()

Member Function Documentation

◆ countSwapchainFormats()

◆ createInstance()

◆ createLogicalDevice()

◆ createVisualizedSpace()

◆ enumerateSwapchainFormats()

◆ enumerateViewConfigurations()

◆ enumerateViewConfigurationTypes()

◆ findQueueFamilies()

◆ getInstanceExtensions()

◆ getOpenXrOptions()

◆ getSession()

◆ getViewConfigurationType()

◆ pickPhysicalDevice()

◆ pollActions()

◆ postprocessFrame()

◆ preprocessFrame()

◆ processFrame()

◆ selectViewConfigurationType()

Member Data Documentation

◆ _actionManager

◆ _handActionSubactionPath

◆ _handCount

◆ _predictedDisplayTime

◆ _session

◆ _sessionRunning

◆ _space

◆ _systemId

◆ _XrInstance