Monado OpenXR Runtime
comp_swapchain.h
Go to the documentation of this file.
1// Copyright 2019-2023, Collabora, Ltd.
2// SPDX-License-Identifier: BSL-1.0
3/*!
4 * @file
5 * @brief Independent swapchain implementation.
6 * @author Jakob Bornecrantz <jakob@collabora.com>
7 * @author Lubosz Sarnecki <lubosz.sarnecki@collabora.com>
8 * @ingroup comp_util
9 */
10
11#pragma once
12
14#include "vk/vk_cmd_pool.h"
15
16#include "util/u_threading.h"
17#include "util/u_index_fifo.h"
18
19
20#ifdef __cplusplus
21extern "C" {
22#endif
23
24
25struct comp_swapchain;
26
27/*!
28 * Callback for implementing own destroy function, should call
29 * @ref comp_swapchain_teardown and is responsible for memory.
30 *
31 * @ingroup comp_util
32 */
34
35/*!
36 * Shared resource(s) and garbage collector for swapchains. The garbage
37 * collector allows to delay the destruction until it's safe to destroy them.
38 * The lifetime of @p pool is handled by the compositor that implements this
39 * struct.
40 *
41 * @ingroup comp_util
42 */
44{
45 //! Thread object for safely destroying swapchain.
47
48 struct vk_cmd_pool pool;
49};
50
51/*!
52 * A single swapchain image, holds the needed state for tracking image usage.
53 *
54 * @ingroup comp_util
55 * @see comp_swapchain
56 */
58{
59 //! Views used by the renderer and distortion code, for each array layer.
60 struct
61 {
62 VkImageView *alpha;
63 VkImageView *no_alpha;
65 //! The number of array slices in a texture, 1 == regular 2D texture.
66 size_t array_size;
67
68 //! A usage counter, similar to a reference counter.
69 uint32_t use_count;
70
71 //! A condition variable per swapchain image that is notified when @ref use_count count reaches 0.
72 pthread_cond_t use_cond;
73
74 //! A mutex per swapchain image that is used with @ref use_cond.
76};
77
78/*!
79 * A swapchain that is almost a one to one mapping to a OpenXR swapchain.
80 *
81 * Not used by the window backend that uses the comp_target to render to.
82 *
83 * The vk_bundle is owned by the compositor, its the state trackers job to make
84 * sure that compositor lives for as long as the swapchain does and that all
85 * swapchains are destroyed before the compositor is destroyed.
86 *
87 * @ingroup comp_util
88 * @implements xrt_swapchain_native
89 * @see comp_compositor
90 */
92{
94
95 struct vk_bundle *vk;
96 struct comp_swapchain_shared *cscs;
97
98 struct vk_image_collection vkic;
100
101 /*!
102 * This fifo is used to always give out the oldest image to acquire
103 * image, this should probably be made even smarter.
104 */
106
107 //! Virtual real destroy function.
109};
110
111
112/*
113 *
114 * Helper functions.
115 *
116 */
117
118/*!
119 * Convenience function to convert an xrt_swapchain to a comp_swapchain.
120 *
121 * @ingroup comp_util
122 * @private @memberof comp_swapchain
123 */
124static inline struct comp_swapchain *
125comp_swapchain(struct xrt_swapchain *xsc)
126{
127 return (struct comp_swapchain *)xsc;
128}
129
130
131/*
132 *
133 * 'Exported' parent-class functions.
134 *
135 */
136
137/*!
138 * Helper to init a comp_swachain struct as if it was a create operation,
139 * useful for wrapping comp_swapchain within another struct. Ref-count is
140 * set to zero so the caller need to init it correctly.
141 *
142 * @ingroup comp_util
143 */
147 struct vk_bundle *vk,
148 struct comp_swapchain_shared *cscs,
149 const struct xrt_swapchain_create_info *info,
150 const struct xrt_swapchain_create_properties *xsccp);
151
152/*!
153 * Helper to init a comp_swachain struct as if it was a import operation,
154 * useful for wrapping comp_swapchain within another struct. Ref-count is
155 * set to zero so the caller need to init it correctly.
156 *
157 * @ingroup comp_util
158 */
162 struct vk_bundle *vk,
163 struct comp_swapchain_shared *cscs,
164 const struct xrt_swapchain_create_info *info,
165 struct xrt_image_native *native_images,
166 uint32_t native_image_count);
167
168/*!
169 * De-inits a comp_swapchain, usable for classes sub-classing comp_swapchain.
170 *
171 * @ingroup comp_util
172 */
173void
175
176
177/*
178 *
179 * 'Exported' shared struct functions.
180 *
181 */
182
183/*!
184 * Create the shared struct.
185 *
186 * @ingroup comp_util
187 */
188XRT_CHECK_RESULT xrt_result_t
190
191/*!
192 * Destroy the shared struct.
193 *
194 * @ingroup comp_util
195 */
196void
198
199/*!
200 * Do garbage collection, destroying any resources that has been scheduled for
201 * destruction from other threads.
202 *
203 * @ingroup comp_util
204 */
205void
207
208
209/*
210 *
211 * 'Exported' default implementation.
212 *
213 */
214
215/*!
216 * A compositor function that is implemented in the swapchain code.
217 *
218 * @ingroup comp_util
219 */
222 struct xrt_swapchain_create_properties *xsccp);
223
224/*!
225 * A compositor function that is implemented in the swapchain code.
226 *
227 * @ingroup comp_util
228 */
231 struct comp_swapchain_shared *cscs,
232 const struct xrt_swapchain_create_info *info,
233 const struct xrt_swapchain_create_properties *xsccp,
234 struct xrt_swapchain **out_xsc);
235
236/*!
237 * A compositor function that is implemented in the swapchain code.
238 *
239 * @ingroup comp_util
240 */
243 struct comp_swapchain_shared *cscs,
244 const struct xrt_swapchain_create_info *info,
245 struct xrt_image_native *native_images,
246 uint32_t image_count,
247 struct xrt_swapchain **out_xsc);
248
249
250#ifdef __cplusplus
251}
252#endif
void(* comp_swapchain_destroy_func_t)(struct comp_swapchain *sc)
Callback for implementing own destroy function, should call comp_swapchain_teardown and is responsibl...
Definition: comp_swapchain.h:33
void comp_swapchain_shared_garbage_collect(struct comp_swapchain_shared *cscs)
Do garbage collection, destroying any resources that has been scheduled for destruction from other th...
Definition: comp_swapchain.c:646
void comp_swapchain_teardown(struct comp_swapchain *sc)
De-inits a comp_swapchain, usable for classes sub-classing comp_swapchain.
Definition: comp_swapchain.c:591
xrt_result_t comp_swapchain_create_init(struct comp_swapchain *sc, comp_swapchain_destroy_func_t destroy_func, struct vk_bundle *vk, struct comp_swapchain_shared *cscs, const struct xrt_swapchain_create_info *info, const struct xrt_swapchain_create_properties *xsccp)
Helper to init a comp_swachain struct as if it was a create operation, useful for wrapping comp_swapc...
Definition: comp_swapchain.c:493
xrt_result_t comp_swapchain_import(struct vk_bundle *vk, struct comp_swapchain_shared *cscs, const struct xrt_swapchain_create_info *info, struct xrt_image_native *native_images, uint32_t image_count, struct xrt_swapchain **out_xsc)
A compositor function that is implemented in the swapchain code.
Definition: comp_swapchain.c:708
XRT_CHECK_RESULT xrt_result_t comp_swapchain_shared_init(struct comp_swapchain_shared *cscs, struct vk_bundle *vk)
Create the shared struct.
Definition: comp_swapchain.c:628
void comp_swapchain_shared_destroy(struct comp_swapchain_shared *cscs, struct vk_bundle *vk)
Destroy the shared struct.
Definition: comp_swapchain.c:640
xrt_result_t comp_swapchain_create(struct vk_bundle *vk, struct comp_swapchain_shared *cscs, const struct xrt_swapchain_create_info *info, const struct xrt_swapchain_create_properties *xsccp, struct xrt_swapchain **out_xsc)
A compositor function that is implemented in the swapchain code.
Definition: comp_swapchain.c:680
xrt_result_t comp_swapchain_import_init(struct comp_swapchain *sc, comp_swapchain_destroy_func_t destroy_func, struct vk_bundle *vk, struct comp_swapchain_shared *cscs, const struct xrt_swapchain_create_info *info, struct xrt_image_native *native_images, uint32_t native_image_count)
Helper to init a comp_swachain struct as if it was a import operation, useful for wrapping comp_swapc...
Definition: comp_swapchain.c:552
xrt_result_t comp_swapchain_get_create_properties(const struct xrt_swapchain_create_info *info, struct xrt_swapchain_create_properties *xsccp)
A compositor function that is implemented in the swapchain code.
Definition: comp_swapchain.c:663
#define XRT_MAX_SWAPCHAIN_IMAGES
Max swapchain images, artificial limit.
Definition: xrt_limits.h:34
enum xrt_result xrt_result_t
Result type used across Monado.
A single swapchain image, holds the needed state for tracking image usage.
Definition: comp_swapchain.h:58
struct os_mutex use_mutex
A mutex per swapchain image that is used with use_cond.
Definition: comp_swapchain.h:75
struct comp_swapchain_image::@113 views
Views used by the renderer and distortion code, for each array layer.
pthread_cond_t use_cond
A condition variable per swapchain image that is notified when use_count count reaches 0.
Definition: comp_swapchain.h:72
size_t array_size
The number of array slices in a texture, 1 == regular 2D texture.
Definition: comp_swapchain.h:66
uint32_t use_count
A usage counter, similar to a reference counter.
Definition: comp_swapchain.h:69
Shared resource(s) and garbage collector for swapchains.
Definition: comp_swapchain.h:44
struct u_threading_stack destroy_swapchains
Thread object for safely destroying swapchain.
Definition: comp_swapchain.h:46
A swapchain that is almost a one to one mapping to a OpenXR swapchain.
Definition: comp_swapchain.h:92
struct u_index_fifo fifo
This fifo is used to always give out the oldest image to acquire image, this should probably be made ...
Definition: comp_swapchain.h:105
comp_swapchain_destroy_func_t real_destroy
Virtual real destroy function.
Definition: comp_swapchain.h:108
A wrapper around a native mutex.
Definition: os_threading.h:55
Definition: u_worker.c:49
Definition: u_index_fifo.h:21
Definition: u_threading.h:17
A bundle of Vulkan functions and objects, used by both Compositor and Compositor client code.
Definition: vk_helpers.h:50
Small helper to manage lock around a command pool.
Definition: vk_cmd_pool.h:33
Definition: vk_image_allocator.h:36
A single image of a swapchain based on native buffer handles.
Definition: xrt_compositor.h:2150
Swapchain creation info.
Definition: xrt_compositor.h:876
Struct used to negotiate properties of a swapchain that is created outside of the compositor.
Definition: xrt_compositor.h:918
Base class for a swapchain that exposes a native buffer handle to be imported into a client API.
Definition: xrt_compositor.h:2191
struct xrt_swapchain base
Base.
Definition: xrt_compositor.h:2193
Common swapchain interface/base.
Definition: xrt_compositor.h:536
uint32_t image_count
Number of images.
Definition: xrt_compositor.h:547
A FIFO for indices.
Slightly higher level thread safe helpers.
Command pool helpers.
Vulkan image allocator helper.