1/**************************************************************************/
2/* openxr_fb_passthrough_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_FB_PASSTHROUGH_EXTENSION_WRAPPER_H
32#define OPENXR_FB_PASSTHROUGH_EXTENSION_WRAPPER_H
33
34#include "../openxr_api.h"
35#include "../util.h"
36#include "openxr_composition_layer_provider.h"
37#include "openxr_extension_wrapper.h"
38
39#include <map>
40
41class Viewport;
42
43// Wrapper for the set of Facebook XR passthrough extensions.
44class OpenXRFbPassthroughExtensionWrapper : public OpenXRExtensionWrapper, public OpenXRCompositionLayerProvider {
45public:
46 OpenXRFbPassthroughExtensionWrapper();
47 ~OpenXRFbPassthroughExtensionWrapper();
48
49 virtual HashMap<String, bool *> get_requested_extensions() override;
50
51 void on_instance_created(const XrInstance instance) override;
52
53 void on_session_created(const XrSession session) override;
54
55 void on_session_destroyed() override;
56
57 void on_instance_destroyed() override;
58
59 XrCompositionLayerBaseHeader *get_composition_layer() override;
60
61 bool is_passthrough_supported() {
62 return fb_passthrough_ext;
63 }
64
65 bool is_passthrough_enabled();
66
67 bool start_passthrough();
68
69 void stop_passthrough();
70
71 static OpenXRFbPassthroughExtensionWrapper *get_singleton();
72
73private:
74 // Create a passthrough feature
75 EXT_PROTO_XRRESULT_FUNC3(xrCreatePassthroughFB,
76 (XrSession), session,
77 (const XrPassthroughCreateInfoFB *), create_info,
78 (XrPassthroughFB *), feature_out)
79
80 // Destroy a previously created passthrough feature
81 EXT_PROTO_XRRESULT_FUNC1(xrDestroyPassthroughFB, (XrPassthroughFB), feature)
82
83 //*** Passthrough feature state management functions *********
84 // Start the passthrough feature
85 EXT_PROTO_XRRESULT_FUNC1(xrPassthroughStartFB, (XrPassthroughFB), passthrough)
86 // Pause the passthrough feature
87 EXT_PROTO_XRRESULT_FUNC1(xrPassthroughPauseFB, (XrPassthroughFB), passthrough)
88
89 EXT_PROTO_XRRESULT_FUNC3(xrCreatePassthroughLayerFB, (XrSession), session,
90 (const XrPassthroughLayerCreateInfoFB *), config,
91 (XrPassthroughLayerFB *), layer_out)
92
93 EXT_PROTO_XRRESULT_FUNC1(xrDestroyPassthroughLayerFB, (XrPassthroughLayerFB), layer)
94
95 EXT_PROTO_XRRESULT_FUNC1(xrPassthroughLayerPauseFB, (XrPassthroughLayerFB), layer)
96 EXT_PROTO_XRRESULT_FUNC1(xrPassthroughLayerResumeFB, (XrPassthroughLayerFB), layer)
97
98 // Set the style of an existing passthrough layer. If the enabled feature set
99 // doesn’t change, this is a lightweight operation that can be called in every
100 // frame to animate the style. Changes that may incur a bigger cost:
101 // - Enabling/disabling the color mapping, or changing the type of mapping
102 // (monochromatic to RGBA or back).
103 // - Changing `textureOpacityFactor` from 0 to non-zero or vice versa
104 // - Changing `edgeColor[3]` from 0 to non-zero or vice versa
105 // NOTE: For XR_FB_passthrough, all color values are treated as linear.
106 EXT_PROTO_XRRESULT_FUNC2(xrPassthroughLayerSetStyleFB,
107 (XrPassthroughLayerFB), layer,
108 (const XrPassthroughStyleFB *), style)
109
110 // Create a geometry instance to be used as a projection surface for passthrough.
111 // A geometry instance assigns a triangle mesh as part of the specified layer's
112 // projection surface.
113 // The operation is only valid if the passthrough layer's purpose has been set to
114 // `XR_PASSTHROUGH_LAYER_PURPOSE_PROJECTED_FB`. Otherwise, the call this function will
115 // result in an error. In the specified layer, Passthrough will be visible where the view
116 // is covered by the user-specified geometries.
117 //
118 // A triangle mesh object can be instantiated multiple times - in the same or different layers'
119 // projection surface. Each instantiation has its own transformation, which
120 // can be updated using `xrGeometryInstanceSetTransformFB`.
121 EXT_PROTO_XRRESULT_FUNC3(xrCreateGeometryInstanceFB,
122 (XrSession), session,
123 (const XrGeometryInstanceCreateInfoFB *), create_info,
124 (XrGeometryInstanceFB *), out_geometry_instance)
125
126 // Destroys a previously created geometry instance from passthrough rendering.
127 // This removes the geometry instance from passthrough rendering.
128 // The operation has no effect on other instances or the underlying mesh.
129 EXT_PROTO_XRRESULT_FUNC1(xrDestroyGeometryInstanceFB, (XrGeometryInstanceFB), instance)
130
131 // Update the transformation of a passthrough geometry instance.
132 EXT_PROTO_XRRESULT_FUNC2(xrGeometryInstanceSetTransformFB,
133 (XrGeometryInstanceFB), instance,
134 (const XrGeometryInstanceTransformFB *), transformation)
135
136 // Create a triangle mesh geometry object.
137 // Depending on the behavior flags, the mesh could be created immutable (data is assigned
138 // at creation and cannot be changed) or mutable (the mesh is created empty and can be updated
139 // by calling begin/end update functions).
140 EXT_PROTO_XRRESULT_FUNC3(xrCreateTriangleMeshFB,
141 (XrSession), session,
142 (const XrTriangleMeshCreateInfoFB *), create_info,
143 (XrTriangleMeshFB *), out_triangle_mesh)
144
145 // Destroy an `XrTriangleMeshFB` object along with its data. The mesh buffers must not be
146 // accessed anymore after their parent mesh object has been destroyed.
147 EXT_PROTO_XRRESULT_FUNC1(xrDestroyTriangleMeshFB, (XrTriangleMeshFB), mesh)
148
149 // Retrieve a pointer to the vertex buffer. The vertex buffer is structured as an array of 3 floats
150 // per vertex representing x, y, and z: `[x0, y0, z0, x1, y1, z1, ...]`. The size of the buffer is
151 // `maxVertexCount * 3` floats. The application must call `xrTriangleMeshBeginUpdateFB` or
152 // `xrTriangleMeshBeginVertexBufferUpdateFB` before making modifications to the vertex
153 // buffer. The buffer location is guaranteed to remain constant over the lifecycle of the mesh
154 // object.
155 EXT_PROTO_XRRESULT_FUNC2(xrTriangleMeshGetVertexBufferFB,
156 (XrTriangleMeshFB), mesh,
157 (XrVector3f **), out_vertex_buffer)
158
159 // Retrieve the index buffer that defines the topology of the triangle mesh. Each triplet of
160 // consecutive elements point to three vertices in the vertex buffer and thus form a triangle. The
161 // size of each element is `indexElementSize` bytes, and thus the size of the buffer is
162 // `maxTriangleCount * 3 * indexElementSize` bytes. The application must call
163 // `xrTriangleMeshBeginUpdateFB` before making modifications to the index buffer. The buffer
164 // location is guaranteed to remain constant over the lifecycle of the mesh object.
165 EXT_PROTO_XRRESULT_FUNC2(xrTriangleMeshGetIndexBufferFB,
166 (XrTriangleMeshFB), mesh,
167 (uint32_t **), out_index_buffer)
168
169 // Begin updating the mesh buffer data. The application must call this function before it makes any
170 // modifications to the buffers retrieved by `xrTriangleMeshGetVertexBufferFB` and
171 // `xrTriangleMeshGetIndexBufferFB`. If only the vertex buffer needs to be updated,
172 // `xrTriangleMeshBeginVertexBufferUpdateFB` can be used instead. To commit the
173 // modifications, the application must call `xrTriangleMeshEndUpdateFB`.
174 EXT_PROTO_XRRESULT_FUNC1(xrTriangleMeshBeginUpdateFB, (XrTriangleMeshFB), mesh)
175
176 // Signal the API that the application has finished updating the mesh buffers after a call to
177 // `xrTriangleMeshBeginUpdateFB`. `vertexCount` and `triangleCount` specify the actual
178 // number of primitives that make up the mesh after the update. They must be larger than zero but
179 // smaller or equal to the maximum counts defined at create time. Buffer data beyond these counts
180 // is ignored.
181 EXT_PROTO_XRRESULT_FUNC3(xrTriangleMeshEndUpdateFB,
182 (XrTriangleMeshFB), mesh,
183 (uint32_t), vertexCount,
184 (uint32_t), triangle_count)
185
186 // Update the vertex positions of a triangle mesh. Can only be called once the mesh topology has
187 // been set using `xrTriangleMeshBeginUpdateFB`/`xrTriangleMeshEndUpdateFB`. The
188 // vertex count is defined by the last invocation to `xrTriangleMeshEndUpdateFB`. Once the
189 // modification is done, `xrTriangleMeshEndVertexBufferUpdateFB` must be called.
190 EXT_PROTO_XRRESULT_FUNC2(xrTriangleMeshBeginVertexBufferUpdateFB,
191 (XrTriangleMeshFB), mesh,
192 (uint32_t *), out_vertex_count)
193
194 // Signal the API that the contents of the vertex buffer data has been updated
195 // after a call to `xrTriangleMeshBeginVertexBufferUpdateFB`.
196 EXT_PROTO_XRRESULT_FUNC1(xrTriangleMeshEndVertexBufferUpdateFB, (XrTriangleMeshFB), mesh)
197
198 bool initialize_fb_passthrough_extension(const XrInstance instance);
199
200 bool initialize_fb_triangle_mesh_extension(const XrInstance instance);
201
202 void cleanup();
203
204 // TODO: Temporary workaround (https://github.com/GodotVR/godot_openxr/issues/138)
205 // Address a bug in the passthrough api where XR_ERROR_UNEXPECTED_STATE_PASSTHROUGH_FB is
206 // returned even when the operation is valid on Meta Quest devices.
207 // The issue should be addressed on that platform in OS release v37.
208 inline bool is_valid_passthrough_result(XrResult result, const char *format) {
209 return OpenXRAPI::get_singleton()->xr_result(result, format) || result == XR_ERROR_UNEXPECTED_STATE_PASSTHROUGH_FB;
210 }
211
212 Viewport *get_main_viewport();
213
214 static OpenXRFbPassthroughExtensionWrapper *singleton;
215
216 bool fb_passthrough_ext = false; // required for any passthrough functionality
217 bool fb_triangle_mesh_ext = false; // only use for projected passthrough
218
219 XrPassthroughFB passthrough_handle = XR_NULL_HANDLE;
220 XrPassthroughLayerFB passthrough_layer = XR_NULL_HANDLE;
221
222 XrCompositionLayerPassthroughFB composition_passthrough_layer = {
223 XR_TYPE_COMPOSITION_LAYER_PASSTHROUGH_FB,
224 nullptr,
225 XR_COMPOSITION_LAYER_BLEND_TEXTURE_SOURCE_ALPHA_BIT,
226 XR_NULL_HANDLE,
227 XR_NULL_HANDLE,
228 };
229};
230
231#endif // OPENXR_FB_PASSTHROUGH_EXTENSION_WRAPPER_H
232