The open source OpenXR runtime
xrt: add plane detection functions to xrt_device
Co-Authored-By: Christoph Haag <christoph.haag@collabora.com>
Part-of: <https://gitlab.freedesktop.org/monado/monado/-/merge_requests/2439>
authored by
Simon Zeni
Christoph Haag
and committed by
Korcan Hussein
0eb9fd5d
a041c616
+328
+101
src/xrt/include/xrt/xrt_device.h
+101
src/xrt/include/xrt/xrt_device.h
···
12
12
#pragma once
13
13
14
14
#include "xrt/xrt_defines.h"
15
+
#include "xrt/xrt_plane_detector.h"
15
16
#include "xrt/xrt_visibility_mask.h"
16
17
#include "xrt/xrt_limits.h"
17
18
···
284
285
bool face_tracking_supported;
285
286
bool body_tracking_supported;
286
287
bool battery_status_supported;
288
+
bool planes_supported;
289
+
enum xrt_plane_detection_capability_flags_ext plane_capability_flags;
287
290
288
291
/*
289
292
*
···
415
418
void (*set_output)(struct xrt_device *xdev, enum xrt_output_name name, const union xrt_output_value *value);
416
419
417
420
/*!
421
+
* Begin a plane detection request
422
+
*
423
+
* @param[in] xdev The device.
424
+
* @param[in] begin_info The query specifying what type of planes are requested.
425
+
* @param[in] plane_detection_id The id for a previous plane detection request to be replaced or 0.
426
+
* @param[out] out_plane_detection_id The id of the new plane detection request generated by the xdev.
427
+
* @return generally XRT_SUCCESS, except for internal runtime failures.
428
+
*/
429
+
enum xrt_result (*begin_plane_detection_ext)(struct xrt_device *xdev,
430
+
const struct xrt_plane_detector_begin_info_ext *begin_info,
431
+
uint64_t plane_detection_id,
432
+
uint64_t *out_plane_detection_id);
433
+
434
+
/*!
435
+
* Destroy internal resources associated with plane_detector_id.
436
+
*
437
+
* @param[in] xdev The device.
438
+
* @param[in] plane_detection_id An id generated by the xdev.
439
+
* @return generally XRT_SUCCESS, except for internal runtime failures.
440
+
*/
441
+
enum xrt_result (*destroy_plane_detection_ext)(struct xrt_device *xdev, uint64_t plane_detection_id);
442
+
443
+
/*!
444
+
* Get the state of a plane detection request.
445
+
*
446
+
* @param[in] xdev The device.
447
+
* @param[in] plane_detector_id An id generated by the xdev.
448
+
* @param[out] out_state The state of the plane detection.
449
+
* @return generally XRT_SUCCESS, except for internal runtime failures.
450
+
*/
451
+
enum xrt_result (*get_plane_detection_state_ext)(struct xrt_device *xdev,
452
+
uint64_t plane_detection_id,
453
+
enum xrt_plane_detector_state_ext *out_state);
454
+
455
+
/*!
456
+
* Get results of a plane detection request.
457
+
*
458
+
* @param[in] xdev The device.
459
+
* @param[in] plane_detector_id An id generated by the xdev.
460
+
* @param[out] detections The detected planes, if any.
461
+
* @return generally XRT_SUCCESS, except for internal runtime failures.
462
+
*/
463
+
enum xrt_result (*get_plane_detections_ext)(struct xrt_device *xdev,
464
+
uint64_t plane_detection_id,
465
+
struct xrt_plane_detections_ext *out_detections);
466
+
467
+
/*!
418
468
* @brief Get the per-view pose in relation to the view space.
419
469
*
420
470
* On most devices with coplanar displays and no built-in eye tracking
···
661
711
xrt_device_set_output(struct xrt_device *xdev, enum xrt_output_name name, const union xrt_output_value *value)
662
712
{
663
713
xdev->set_output(xdev, name, value);
714
+
}
715
+
716
+
/*!
717
+
* Helper function for @ref xrt_device::begin_plane_detection.
718
+
*
719
+
* @public @memberof xrt_device
720
+
*/
721
+
static inline enum xrt_result
722
+
xrt_device_begin_plane_detection_ext(struct xrt_device *xdev,
723
+
const struct xrt_plane_detector_begin_info_ext *begin_info,
724
+
uint64_t plane_detection_id,
725
+
uint64_t *out_plane_detection_id)
726
+
{
727
+
return xdev->begin_plane_detection_ext(xdev, begin_info, plane_detection_id, out_plane_detection_id);
728
+
}
729
+
730
+
/*!
731
+
* Helper function for @ref xrt_device::destroy_plane_detection.
732
+
*
733
+
* @public @memberof xrt_device
734
+
*/
735
+
static inline enum xrt_result
736
+
xrt_device_destroy_plane_detection_ext(struct xrt_device *xdev, uint64_t plane_detection_id)
737
+
{
738
+
return xdev->destroy_plane_detection_ext(xdev, plane_detection_id);
739
+
}
740
+
741
+
/*!
742
+
* Helper function for @ref xrt_device::get_plane_detections.
743
+
*
744
+
* @public @memberof xrt_device
745
+
*/
746
+
static inline enum xrt_result
747
+
xrt_device_get_plane_detection_state_ext(struct xrt_device *xdev,
748
+
uint64_t plane_detection_id,
749
+
enum xrt_plane_detector_state_ext *out_state)
750
+
{
751
+
return xdev->get_plane_detection_state_ext(xdev, plane_detection_id, out_state);
752
+
}
753
+
754
+
/*!
755
+
* Helper function for @ref xrt_device::get_plane_detections.
756
+
*
757
+
* @public @memberof xrt_device
758
+
*/
759
+
static inline enum xrt_result
760
+
xrt_device_get_plane_detections_ext(struct xrt_device *xdev,
761
+
uint64_t plane_detection_id,
762
+
struct xrt_plane_detections_ext *out_detections)
763
+
{
764
+
return xdev->get_plane_detections_ext(xdev, plane_detection_id, out_detections);
664
765
}
665
766
666
767
/*!
+10
src/xrt/include/xrt/xrt_limits.h
+10
src/xrt/include/xrt/xrt_limits.h
···
39
39
#define XRT_MAX_SWAPCHAIN_FORMATS 16
40
40
41
41
/*!
42
+
* Max number of plane orientations that can be requested at a time.
43
+
*/
44
+
#define XRT_MAX_PLANE_ORIENTATIONS_EXT 256
45
+
46
+
/*!
47
+
* Max number of plane semantic types that can be requested at a time.
48
+
*/
49
+
#define XRT_MAX_PLANE_SEMANTIC_TYPE_EXT 256
50
+
51
+
/*!
42
52
* Max formats in the swapchain creation info formats list, artificial limit.
43
53
*/
44
54
#define XRT_MAX_SWAPCHAIN_CREATE_INFO_FORMAT_LIST_COUNT 8
+217
src/xrt/include/xrt/xrt_plane_detector.h
+217
src/xrt/include/xrt/xrt_plane_detector.h
···
1
+
// Copyright 2023-2025, Collabora, Ltd.
2
+
// SPDX-License-Identifier: BSL-1.0
3
+
/*!
4
+
* @file
5
+
* @brief Header defining planes detector enum and structs.
6
+
* @author Christoph Haag <christoph.haag@collabora.com>
7
+
* @ingroup xrt_iface
8
+
*/
9
+
10
+
11
+
#pragma once
12
+
13
+
#include "xrt/xrt_defines.h"
14
+
#include "xrt/xrt_limits.h"
15
+
16
+
#include <stdlib.h>
17
+
#include <string.h>
18
+
19
+
#ifdef __cplusplus
20
+
extern "C" {
21
+
#endif
22
+
23
+
24
+
/*!
25
+
* Caps for a plane detector, see @ref xrt_device.
26
+
*
27
+
* @ingroup xrt_iface
28
+
*/
29
+
enum xrt_plane_detection_capability_flags_ext
30
+
{
31
+
XRT_PLANE_DETECTION_CAPABILITY_PLANE_DETECTION_BIT_EXT = 0x00000001,
32
+
XRT_PLANE_DETECTION_CAPABILITY_PLANE_HOLES_BIT_EXT = 0x00000002,
33
+
XRT_PLANE_DETECTION_CAPABILITY_SEMANTIC_CEILING_BIT_EXT = 0x00000004,
34
+
XRT_PLANE_DETECTION_CAPABILITY_SEMANTIC_FLOOR_BIT_EXT = 0x00000008,
35
+
XRT_PLANE_DETECTION_CAPABILITY_SEMANTIC_WALL_BIT_EXT = 0x00000010,
36
+
XRT_PLANE_DETECTION_CAPABILITY_SEMANTIC_PLATFORM_BIT_EXT = 0x00000020,
37
+
XRT_PLANE_DETECTION_CAPABILITY_ORIENTATION_BIT_EXT = 0x00000040,
38
+
};
39
+
40
+
/*!
41
+
* Flags used when running plane detection.
42
+
*
43
+
* @ingroup xrt_iface
44
+
*/
45
+
enum xrt_plane_detector_flags_ext
46
+
{
47
+
XRT_PLANE_DETECTOR_FLAGS_CONTOUR_EXT = 1,
48
+
};
49
+
50
+
/*!
51
+
* Orientation of a plane.
52
+
*
53
+
* @ingroup xrt_iface
54
+
*/
55
+
enum xrt_plane_detector_orientation_ext
56
+
{
57
+
XRT_PLANE_DETECTOR_ORIENTATION_HORIZONTAL_UPWARD_EXT = 0,
58
+
XRT_PLANE_DETECTOR_ORIENTATION_HORIZONTAL_DOWNWARD_EXT = 1,
59
+
XRT_PLANE_DETECTOR_ORIENTATION_VERTICAL_EXT = 2,
60
+
XRT_PLANE_DETECTOR_ORIENTATION_ARBITRARY_EXT = 3,
61
+
};
62
+
63
+
/*!
64
+
* Has this plane any semantic meaning?
65
+
*
66
+
* @ingroup xrt_iface
67
+
*/
68
+
enum xrt_plane_detector_semantic_type_ext
69
+
{
70
+
XRT_PLANE_DETECTOR_SEMANTIC_TYPE_UNDEFINED_EXT = 0,
71
+
XRT_PLANE_DETECTOR_SEMANTIC_TYPE_CEILING_EXT = 1,
72
+
XRT_PLANE_DETECTOR_SEMANTIC_TYPE_FLOOR_EXT = 2,
73
+
XRT_PLANE_DETECTOR_SEMANTIC_TYPE_WALL_EXT = 3,
74
+
XRT_PLANE_DETECTOR_SEMANTIC_TYPE_PLATFORM_EXT = 4,
75
+
};
76
+
77
+
/*!
78
+
* State of a plane detector, see @ref xrt_device.
79
+
*
80
+
* @ingroup xrt_iface
81
+
*/
82
+
enum xrt_plane_detector_state_ext
83
+
{
84
+
XRT_PLANE_DETECTOR_STATE_NONE_EXT = 0,
85
+
XRT_PLANE_DETECTOR_STATE_PENDING_EXT = 1,
86
+
XRT_PLANE_DETECTOR_STATE_DONE_EXT = 2,
87
+
XRT_PLANE_DETECTOR_STATE_ERROR_EXT = 3,
88
+
XRT_PLANE_DETECTOR_STATE_FATAL_EXT = 4,
89
+
};
90
+
91
+
/*!
92
+
* A query for a plane. Corresponds to XrPlaneDetectorBeginInfoEXT.
93
+
*
94
+
* @ingroup xrt_iface
95
+
*/
96
+
struct xrt_plane_detector_begin_info_ext
97
+
{
98
+
enum xrt_plane_detector_flags_ext detector_flags;
99
+
uint32_t orientation_count;
100
+
enum xrt_plane_detector_orientation_ext orientations[XRT_MAX_PLANE_ORIENTATIONS_EXT];
101
+
uint32_t semantic_type_count;
102
+
enum xrt_plane_detector_semantic_type_ext semantic_types[XRT_MAX_PLANE_SEMANTIC_TYPE_EXT];
103
+
uint32_t max_planes;
104
+
float min_area;
105
+
struct xrt_pose bounding_box_pose;
106
+
//! width, height, depth
107
+
struct xrt_vec3 bounding_box_extent;
108
+
};
109
+
110
+
/*!
111
+
* Location and other info for a plane.
112
+
*
113
+
* @ingroup xrt_iface
114
+
*/
115
+
struct xrt_plane_detector_location_ext
116
+
{
117
+
uint64_t planeId;
118
+
struct xrt_space_relation relation;
119
+
//! x = width, y = height
120
+
struct xrt_vec2 extents;
121
+
enum xrt_plane_detector_orientation_ext orientation;
122
+
enum xrt_plane_detector_semantic_type_ext semantic_type;
123
+
uint32_t polygon_buffer_count;
124
+
};
125
+
126
+
/*!
127
+
* Helper struct to pair up metadata for one polygon.
128
+
*
129
+
* @ingroup xrt_iface
130
+
*/
131
+
struct xrt_plane_polygon_info_ext
132
+
{
133
+
uint32_t vertex_count;
134
+
135
+
//! Index into the continuous array of vertices for all planes of a query.
136
+
uint32_t vertices_start_index;
137
+
};
138
+
139
+
/*!
140
+
* Each plane has n polygons; ultimately plane metadata from @ref locations and @ref vetices is
141
+
* reconstructed. Therefore lay out the data in flattened arrays:
142
+
*
143
+
* @ref locations stores continuous metadata for each plane:
144
+
* location 1 | location 2 | location 3 | location 4 | ...
145
+
*
146
+
* @ref polygon_info_start_index is a helper array to go from a location entry to a polygon_info entry.
147
+
*
148
+
* @ref polygon_info stores info (metadata) for each polygon, flattened:
149
+
* plane 1 polygon 1 info | plane 1 polygon 2 info | ... | plane 2 polygon 1 info | ...
150
+
*
151
+
* @ref polygon_info.vertices_start_index is a helper array to go from a polygon_info entry to vertices
152
+
* entry.
153
+
*
154
+
* @ref vertices stores vertex data for each polygon, for each plane, flattened:
155
+
* plane 1 polygon 1 vertex 1 | plane 1 polygon 1 vertex 2 | ... | plane 1 polygon 2 vertex 1 | ...
156
+
*
157
+
* To reconstruct the vertices of a certain plane polygon:
158
+
* - Find the index i of the plane with the requested plane_id in the locations array.
159
+
* - Use this index i to generate a new index j = polygon_info_start_index[i].
160
+
* - polygon_info[j] is the info of the first polygon of the locations[i] plane.
161
+
* - polygon_info[j + polygonBufferIndex] is the info of the requested polygon.
162
+
* - polygon_info[j + polygonBufferIndex].vertex_count is the vertex count of this polygon.
163
+
* - polygon_info[j + polygonBufferIndex].vertices_start_index is another new index k.
164
+
* - vertices[k] is the first vertex of the requested polygon.
165
+
*
166
+
* Convention: Whoever writes to this struct checks the size values first and reallocates arrays if necessary.
167
+
*
168
+
* @ingroup xrt_iface
169
+
*/
170
+
struct xrt_plane_detections_ext
171
+
{
172
+
//! How many locations were found.
173
+
uint32_t location_count;
174
+
175
+
//! size of @ref locations and @ref polygon_info_start_index arrays.
176
+
uint32_t location_size;
177
+
178
+
///! array of detected locations.
179
+
struct xrt_plane_detector_location_ext *locations;
180
+
181
+
//! Parallel array to @ref locations.
182
+
//! Index into @ref polygon_info of polygon_infos for all planes of a query.
183
+
uint32_t *polygon_info_start_index;
184
+
185
+
//! size of @ref polygon_infos array.
186
+
uint32_t polygon_info_size;
187
+
188
+
//! Continuous array of polygon_infos of all polygons for all planes of a query.
189
+
struct xrt_plane_polygon_info_ext *polygon_infos;
190
+
191
+
//! size of @ref vertices array.
192
+
uint32_t vertex_size;
193
+
194
+
//! Continuous array of polygon vertices of all polygons for all planes of a query.
195
+
struct xrt_vec2 *vertices;
196
+
};
197
+
198
+
/*!
199
+
* Small helper to free any data of a @ref xrt_plane_detections_ext struct,
200
+
* does not free the struct itself.
201
+
*
202
+
* @ingroup xrt_iface
203
+
*/
204
+
static inline void
205
+
xrt_plane_detections_ext_clear(struct xrt_plane_detections_ext *detections)
206
+
{
207
+
free(detections->locations);
208
+
free(detections->polygon_info_start_index);
209
+
free(detections->polygon_infos);
210
+
free(detections->vertices);
211
+
memset(detections, 0, sizeof(*detections));
212
+
}
213
+
214
+
215
+
#ifdef __cplusplus
216
+
}
217
+
#endif