1/**************************************************************************/
2/* openxr_extension_wrapper.h */
3/**************************************************************************/
4/* This file is part of: */
5/* GODOT ENGINE */
6/* https://godotengine.org */
7/**************************************************************************/
8/* Copyright (c) 2014-present Godot Engine contributors (see AUTHORS.md). */
9/* Copyright (c) 2007-2014 Juan Linietsky, Ariel Manzur. */
10/* */
11/* Permission is hereby granted, free of charge, to any person obtaining */
12/* a copy of this software and associated documentation files (the */
13/* "Software"), to deal in the Software without restriction, including */
14/* without limitation the rights to use, copy, modify, merge, publish, */
15/* distribute, sublicense, and/or sell copies of the Software, and to */
16/* permit persons to whom the Software is furnished to do so, subject to */
17/* the following conditions: */
18/* */
19/* The above copyright notice and this permission notice shall be */
20/* included in all copies or substantial portions of the Software. */
21/* */
22/* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, */
23/* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF */
24/* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. */
25/* IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY */
26/* CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, */
27/* TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE */
28/* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. */
29/**************************************************************************/
30
31#ifndef OPENXR_EXTENSION_WRAPPER_H
32#define OPENXR_EXTENSION_WRAPPER_H
33
34#include "core/error/error_macros.h"
35#include "core/math/projection.h"
36#include "core/templates/hash_map.h"
37#include "core/templates/rid.h"
38
39#include <openxr/openxr.h>
40
41class OpenXRAPI;
42class OpenXRActionMap;
43
44// `OpenXRExtensionWrapper` allows us to implement OpenXR extensions.
45class OpenXRExtensionWrapper {
46public:
47 // `get_requested_extensions` should return a list of OpenXR extensions related to this extension.
48 // If the bool * is a nullptr this extension is mandatory
49 // If the bool * points to a boolean, the boolean will be updated
50 // to true if the extension is enabled.
51 virtual HashMap<String, bool *> get_requested_extensions() = 0;
52
53 // These functions allow an extension to add entries to a struct chain.
54 // `p_next_pointer` points to the last struct that was created for this chain
55 // and should be used as the value for the `pNext` pointer in the first struct you add.
56 // You should return the pointer to the last struct you define as your result.
57 // If you are not adding any structs, just return `p_next_pointer`.
58 // See existing extensions for examples of this implementation.
59 virtual void *set_system_properties_and_get_next_pointer(void *p_next_pointer) { return p_next_pointer; } // Add additional data structures when we interogate OpenXRS system abilities.
60 virtual void *set_instance_create_info_and_get_next_pointer(void *p_next_pointer) { return p_next_pointer; } // Add additional data structures when we create our OpenXR instance.
61 virtual void *set_session_create_and_get_next_pointer(void *p_next_pointer) { return p_next_pointer; } // Add additional data structures when we create our OpenXR session.
62 virtual void *set_swapchain_create_info_and_get_next_pointer(void *p_next_pointer) { return p_next_pointer; } // Add additional data structures when creating OpenXR swap chains.
63
64 // `on_register_metadata` allows extensions to register additional controller metadata.
65 // This function is called even when OpenXRApi is not constructured as the metadata
66 // needs to be available to the editor.
67 // Also extensions should provide metadata regardless of whether they are supported
68 // on the host system as the controller data is used to setup action maps for users
69 // who may have access to the relevant hardware.
70 virtual void on_register_metadata() {}
71
72 virtual void on_before_instance_created() {} // `on_before_instance_created` is called before we create our OpenXR instance.
73 virtual void on_instance_created(const XrInstance p_instance) {} // `on_instance_created` is called right after we've successfully created our OpenXR instance.
74 virtual void on_instance_destroyed() {} // `on_instance_destroyed` is called right before we destroy our OpenXR instance.
75 virtual void on_session_created(const XrSession p_instance) {} // `on_session_created` is called right after we've successfully created our OpenXR session.
76 virtual void on_session_destroyed() {} // `on_session_destroyed` is called right before we destroy our OpenXR session.
77
78 // `on_process` is called as part of our OpenXR process handling,
79 // this happens right before physics process and normal processing is run.
80 // This is when controller data is queried and made available to game logic.
81 virtual void on_process() {}
82 virtual void on_pre_render() {} // `on_pre_render` is called right before we start rendering our XR viewports.
83 virtual void on_pre_draw_viewport(RID p_render_target) {} // `on_pre_draw_viewport` is called right before we start rendering this viewport
84 virtual void on_post_draw_viewport(RID p_render_target) {} // `on_port_draw_viewport` is called right after we start rendering this viewport (note that on Vulkan draw commands may only be queued)
85
86 virtual void on_state_idle() {} // `on_state_idle` is called when the OpenXR session state is changed to idle.
87 virtual void on_state_ready() {} // `on_state_ready` is called when the OpenXR session state is changed to ready, this means OpenXR is ready to setup our session.
88 virtual void on_state_synchronized() {} // `on_state_synchronized` is called when the OpenXR session state is changed to synchronized, note that OpenXR also returns to this state when our application looses focus.
89 virtual void on_state_visible() {} // `on_state_visible` is called when the OpenXR session state is changed to visible, OpenXR is now ready to receive frames.
90 virtual void on_state_focused() {} // `on_state_focused` is called when the OpenXR session state is changed to focused, this state is the active state when our game runs.
91 virtual void on_state_stopping() {} // `on_state_stopping` is called when the OpenXR session state is changed to stopping.
92 virtual void on_state_loss_pending() {} // `on_state_loss_pending` is called when the OpenXR session state is changed to loss pending.
93 virtual void on_state_exiting() {} // `on_state_exiting` is called when the OpenXR session state is changed to exiting.
94
95 // `on_event_polled` is called when there is an OpenXR event to process.
96 // Should return true if the event was handled, false otherwise.
97 virtual bool on_event_polled(const XrEventDataBuffer &event) {
98 return false;
99 }
100
101 OpenXRExtensionWrapper() = default;
102 virtual ~OpenXRExtensionWrapper() = default;
103};
104
105// `OpenXRGraphicsExtensionWrapper` implements specific logic for each supported graphics API.
106class OpenXRGraphicsExtensionWrapper : public OpenXRExtensionWrapper {
107public:
108 virtual void get_usable_swapchain_formats(Vector<int64_t> &p_usable_swap_chains) = 0; // `get_usable_swapchain_formats` should return a list of usable color formats.
109 virtual void get_usable_depth_formats(Vector<int64_t> &p_usable_swap_chains) = 0; // `get_usable_depth_formats` should return a list of usable depth formats.
110 virtual String get_swapchain_format_name(int64_t p_swapchain_format) const = 0; // `get_swapchain_format_name` should return the constant name of a given format.
111 virtual bool get_swapchain_image_data(XrSwapchain p_swapchain, int64_t p_swapchain_format, uint32_t p_width, uint32_t p_height, uint32_t p_sample_count, uint32_t p_array_size, void **r_swapchain_graphics_data) = 0; // `get_swapchain_image_data` extracts image IDs for the swapchain images and stores there in an implementation dependent data structure.
112 virtual void cleanup_swapchain_graphics_data(void **p_swapchain_graphics_data) = 0; // `cleanup_swapchain_graphics_data` cleans up the data held in our implementation dependent data structure and should free up its memory.
113 virtual bool create_projection_fov(const XrFovf p_fov, double p_z_near, double p_z_far, Projection &r_camera_matrix) = 0; // `create_projection_fov` creates a proper projection matrix based on asymmetric FOV data provided by OpenXR.
114 virtual RID get_texture(void *p_swapchain_graphics_data, int p_image_index) = 0; // `get_texture` returns a Godot texture RID for the current active texture in our swapchain.
115};
116
117#endif // OPENXR_EXTENSION_WRAPPER_H
118