matrixfurry.com / monado
The open source OpenXR runtime
0
fork

Configure Feed

Select the types of activity you want to include in your feed.

c/util: Improve docs for renderers substantially

Part-of: <https://gitlab.freedesktop.org/monado/monado/-/merge_requests/2322>

Rylie Pavlik 7d061ca7 59b8b2db

+204 -32
+204 -32
src/xrt/compositor/util/comp_render.h
··· 2 2 // SPDX-License-Identifier: BSL-1.0 3 3 /*! 4 4 * @file 5 - * @brief Independent semaphore implementation. 5 + * @brief Compositor render implementation. 6 6 * @author Jakob Bornecrantz <jakob@collabora.com> 7 + * @author Rylie Pavlik <rylie.pavlik@collabora.com> 7 8 * @ingroup comp_util 8 9 */ 9 10 ··· 22 23 struct comp_layer; 23 24 24 25 26 + /*! 27 + * @defgroup comp_render 28 + * @brief Renders, aka "layer squashers" and distortion application. 29 + * 30 + * Two parallel implementations of the render module exist: 31 + * 32 + * - one uses graphics shaders (aka GFX, @ref comp_render_gfx, @ref comp_render_gfx.c) 33 + * - the other uses compute shaders (aka CS, @ref comp_render_cs, @ref comp_render_cs.c) 34 + * 35 + * Their abilities are effectively equivalent, although the graphics version disregards depth 36 + * data, while the compute shader does use it somewhat. 37 + * 38 + * @note In general this module requires that swapchains in your supplied @ref comp_layer layers 39 + * implement @ref comp_swapchain in addition to just @ref xrt_swapchain. 40 + */ 41 + 25 42 /* 26 43 * 27 44 * Input data struct. ··· 29 46 */ 30 47 31 48 /*! 32 - * The input data needed for a single view, it shared between both GFX and CS 33 - * paths. To fully render a single view two "rendering" might be needed, the 49 + * @name Input data structs 50 + * @{ 51 + */ 52 + 53 + /*! 54 + * The input data needed for a single view, shared between both GFX and CS 55 + * paths. 56 + * 57 + * To fully render a single view two "rendering" might be needed, the 34 58 * first being the layer squashing, and the second is the distortion step. The 35 59 * target for the layer squashing is referred to as "layer" or "scratch" and 36 60 * prefixed with `layer` if needs be. The other final step is referred to as 37 61 * "distortion target" or just "target", and is prefixed with `target`. 62 + * 63 + * @ingroup comp_render 38 64 */ 39 65 struct comp_render_view_data 40 66 { ··· 99 125 /*! 100 126 * The input data needed for a complete layer squashing distortion rendering 101 127 * to a target. This struct is shared between GFX and CS paths. 128 + * 129 + * @ingroup comp_render 102 130 */ 103 131 struct comp_render_dispatch_data 104 132 { ··· 113 141 //! Very often true, can be disabled for debugging. 114 142 bool do_timewarp; 115 143 144 + //! Members used only by GFX @ref comp_render_gfx 116 145 struct 117 146 { 118 - // The resources needed for the target. 147 + //! The resources needed for the target. 119 148 struct render_gfx_target_resources *rtr; 120 149 } gfx; 121 150 151 + //! Members used only by CS @ref comp_render_cs 122 152 struct 123 153 { 124 - // Target image for distortion, used for barrier. 154 + //! Target image for distortion, used for barrier. 125 155 VkImage target_image; 126 156 127 - // Target image view for distortion. 157 + //! Target image view for distortion. 128 158 VkImageView target_unorm_view; 129 159 } cs; 130 160 }; 131 161 132 162 163 + /*! @} */ 164 + 133 165 /* 134 166 * 135 167 * Gfx functions. 136 168 * 137 169 */ 138 170 171 + /*! 172 + * 173 + * @defgroup comp_render_gfx 174 + * 175 + * GFX renderer control and dispatch - uses graphics shaders. 176 + * 177 + * Depends on the common @ref comp_render_dispatch_data, as well as the resources 178 + * @ref render_gfx_target_resources (often called `rtr`), and @ref render_gfx. 179 + * 180 + * @ingroup comp_render 181 + * @{ 182 + */ 183 + 184 + /*! 185 + * Initialize structure for use of the GFX renderer. 186 + * 187 + * @param[out] data Common render dispatch data. Will be zeroed and initialized. 188 + * @param rtr GFX-specific resources for the entire frameedg. Must be populated before call. 189 + * @param fast_path Whether we will use the "fast path" avoiding layer squashing. 190 + * @param do_timewarp Whether timewarp (reprojection) will be performed. 191 + */ 139 192 static inline void 140 193 comp_render_gfx_initial_init(struct comp_render_dispatch_data *data, 141 194 struct render_gfx_target_resources *rtr, ··· 149 202 data->gfx.rtr = rtr; 150 203 } 151 204 205 + /*! 206 + * Add view to the common data, as required by the GFX renderer. 207 + * 208 + * @param[in,out] data Common render dispatch data, will be updated 209 + * @param world_pose New world pose of this view. 210 + * Populates @ref comp_render_view_data::world_pose 211 + * @param eye_pose New eye pose of this view 212 + * Populates @ref comp_render_view_data::eye_pose 213 + * @param fov Assigned to fov in the view data, and used to 214 + * compute @ref comp_render_view_data::target_pre_transform - also 215 + * populates @ref comp_render_view_data::fov 216 + * @param rtr Will be associated with this view. GFX-specific 217 + * @param layer_viewport_data Where in the image to render the view 218 + * Populates @ref comp_render_view_data::layer_viewport_data 219 + * @param layer_norm_rect How to transform when sampling from the scratch image. 220 + * Populates @ref comp_render_view_data::layer_norm_rect 221 + * @param image Scratch image for this view 222 + * Populates @ref comp_render_view_data::image 223 + * @param srgb_view SRGB image view into the scratch image 224 + * Populates @ref comp_render_view_data::srgb_view 225 + * @param vertex_rot 226 + * @param target_viewport_data Distortion target viewport data (aka target) 227 + * Populates @ref comp_render_view_data::target_viewport_data 228 + */ 152 229 static inline void 153 230 comp_render_gfx_add_view(struct comp_render_dispatch_data *data, 154 231 const struct xrt_pose *world_pose, ··· 184 261 } 185 262 186 263 /*! 187 - * Helper function that takes a set of layers, new device poses, a scratch 264 + * Writes the needed commands to the @ref render_gfx to do a full composition with distortion. 265 + * 266 + * Takes a set of layers, new device poses, scratch 188 267 * images with associated @ref render_gfx_target_resources and writes the needed 189 268 * commands to the @ref render_gfx to do a full composition with distortion. 190 269 * The scratch images are optionally used to squash layers should it not be ··· 192 271 * passes of the targets which set the layout. 193 272 * 194 273 * The render passes of @p comp_render_dispatch_data::views::rtr must be created 195 - * with a final_layout of VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL or there will 274 + * with a final_layout of `VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL` or there will 196 275 * be validation errors. 197 276 * 198 277 * Expected layouts: 199 - * * Layer images: VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL 200 - * * Scratch images: Any (as per the @ref render_gfx_render_pass) 201 - * * Target image: Any (as per the @ref render_gfx_render_pass) 278 + * 279 + * - Layer images: `VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL` 280 + * - Scratch images: Any (as per the @ref render_gfx_render_pass) 281 + * - Target image: Any (as per the @ref render_gfx_render_pass) 202 282 * 203 283 * After call layouts: 204 - * * Layer images: VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL 205 - * * Scratch images: VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL 206 - * * Target image: What the render pass of @p rtr specifies. 284 + * 285 + * - Layer images: `VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL` 286 + * - Scratch images: `VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL` 287 + * - Target image: What the render pass of @p rtr specifies. 207 288 * 208 - * @ingroup comp_util 289 + * @note Swapchains in the @p layers must implement @ref comp_swapchain in 290 + * addition to just @ref xrt_swapchain, as this function downcasts to @ref comp_swapchain ! 291 + * 292 + * @param rr GFX render object 293 + * @param[in] layers Layers to render, see note. 294 + * @param[in] layer_count Number of elements in @p layers array. 295 + * @param[in] d Common render dispatch data 209 296 */ 210 297 void 211 298 comp_render_gfx_dispatch(struct render_gfx *rr, ··· 213 300 const uint32_t layer_count, 214 301 const struct comp_render_dispatch_data *d); 215 302 303 + /* end of comp_render_gfx group */ 304 + 305 + /*! @} */ 306 + 216 307 217 308 /* 218 309 * ··· 220 311 * 221 312 */ 222 313 314 + /*! 315 + * 316 + * @defgroup comp_render_cs 317 + * 318 + * CS renderer control and dispatch - uses compute shaders 319 + * 320 + * Depends on @ref render_compute (often called `crc`) 321 + * 322 + * @ingroup comp_render 323 + * @{ 324 + */ 325 + 326 + /*! 327 + * Initialize structure for use of the CS renderer. 328 + * 329 + * @param data Common render dispatch data. Will be zeroed and initialized. 330 + * @param target_image Image to render into 331 + * @param target_unorm_view Corresponding image view 332 + * @param fast_path Whether we will use the "fast path" avoiding layer squashing. 333 + * @param do_timewarp Whether timewarp (reprojection) will be performed. 334 + */ 223 335 static inline void 224 336 comp_render_cs_initial_init(struct comp_render_dispatch_data *data, 225 337 VkImage target_image, ··· 236 348 data->cs.target_unorm_view = target_unorm_view; 237 349 } 238 350 351 + /*! 352 + * Add view to the common data, as required by the CS renderer. 353 + * 354 + * @param[in,out] data Common render dispatch data, will be updated 355 + * @param world_pose New world pose of this view. 356 + * Populates @ref comp_render_view_data::world_pose 357 + * @param eye_pose New eye pose of this view 358 + * Populates @ref comp_render_view_data::eye_pose 359 + * @param fov Assigned to fov in the view data, and used to compute @ref comp_render_view_data::target_pre_transform 360 + * Populates @ref comp_render_view_data::fov 361 + * @param layer_viewport_data Where in the image to render the view 362 + * Populates @ref comp_render_view_data::layer_viewport_data 363 + * @param layer_norm_rect How to transform when sampling from the scratch image. 364 + * Populates @ref comp_render_view_data::layer_norm_rect 365 + * @param image Scratch image for this view 366 + * Populates @ref comp_render_view_data::image 367 + * @param srgb_view SRGB image view into the scratch image 368 + * Populates @ref comp_render_view_data::srgb_view 369 + * @param unorm_view UNORM image view into the scratch image, CS specific 370 + * @param target_viewport_data Distortion target viewport data (aka target) 371 + * Populates @ref comp_render_view_data::target_viewport_data 372 + */ 239 373 static inline void 240 374 comp_render_cs_add_view(struct comp_render_dispatch_data *data, 241 375 const struct xrt_pose *world_pose, ··· 269 403 } 270 404 271 405 /*! 272 - * Helper to dispatch the layer squasher for a single view. 406 + * Dispatch the layer squasher for a single view. 273 407 * 274 408 * All source layer images and target image needs to be in the correct image 275 409 * layout, no barrier is inserted at all. The @p view_index argument is needed ··· 277 411 * select left/right data from various layers. 278 412 * 279 413 * Expected layouts: 280 - * * Layer images: VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL 281 - * * Target images: VK_IMAGE_LAYOUT_GENERAL 414 + * 415 + * - Layer images: `VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL` 416 + * - Target images: `VK_IMAGE_LAYOUT_GENERAL` 417 + * 418 + * @note Swapchains in the @p layers must implement @ref comp_swapchain in 419 + * addition to just @ref xrt_swapchain, as this function downcasts to @ref comp_swapchain ! 420 + * 421 + * @param crc Compute renderer object 422 + * @param view_index Index of the view 423 + * @param layers Layers to render, see note. 424 + * @param layer_count Number of elements in @p layers array. 425 + * @param pre_transform 426 + * @param world_pose 427 + * @param eye_pose 428 + * @param target_image 429 + * @param target_image_view 430 + * @param target_view 431 + * @param do_timewarp 282 432 */ 283 433 void 284 434 comp_render_cs_layer(struct render_compute *crc, ··· 294 444 bool do_timewarp); 295 445 296 446 /*! 297 - * Helper function to dispatch the layer squasher, works on any number of views. 447 + * Dispatch the layer squasher, on any number of views. 298 448 * 299 449 * All source layer images needs to be in the correct image layout, no barrier 300 - * is inserted for them. The target images are barried from undefined to general 450 + * is inserted for them. The target images are barriered from undefined to general 301 451 * so they can be written to, then to the laying defined by @p transition_to. 302 452 * 303 453 * Expected layouts: 304 - * * Layer images: VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL 305 - * * Target images: Any 454 + * 455 + * - Layer images: `VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL` 456 + * - Target images: Any 306 457 * 307 458 * After call layouts: 308 - * * Layer images: VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL 309 - * * Target images: @p transition_to 459 + * 460 + * - Layer images: `VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL` 461 + * - Target images: @p transition_to 462 + * 463 + * @note Swapchains in the @p layers must implement @ref comp_swapchain in 464 + * addition to just @ref xrt_swapchain, as this function downcasts to @ref comp_swapchain ! 310 465 * 311 - * @ingroup comp_util 466 + * @param crc Compute renderer object 467 + * @param[in] layers Layers to render, see note. 468 + * @param[in] layer_count Number of elements in @p layers array. 469 + * @param[in] d Common render dispatch data 470 + * @param[in] transition_to Desired image layout for target images 312 471 */ 313 472 void 314 473 comp_render_cs_layers(struct render_compute *crc, ··· 318 477 VkImageLayout transition_to); 319 478 320 479 /*! 480 + * Write commands to @p crc to do a full composition with distortion. 481 + * 321 482 * Helper function that takes a set of layers, new device poses, a scratch 322 483 * images and writes the needed commands to the @ref render_compute to do a full 323 484 * composition with distortion. The scratch images are optionally used to squash ··· 326 487 * 327 488 * 328 489 * Expected layouts: 329 - * * Layer images: VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL 330 - * * Scratch images: Any 331 - * * Target image: Any 490 + * 491 + * - Layer images: `VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL` 492 + * - Scratch images: Any 493 + * - Target image: Any 332 494 * 333 495 * After call layouts: 334 - * * Layer images: VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL 335 - * * Scratch images: VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL 336 - * * Target image: VK_IMAGE_LAYOUT_PRESENT_SRC_KHR 496 + * 497 + * - Layer images: `VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL` 498 + * - Scratch images: `VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL` 499 + * - Target image: `VK_IMAGE_LAYOUT_PRESENT_SRC_KHR` 500 + * 501 + * @note Swapchains in the @p layers must implement @ref comp_swapchain in 502 + * addition to just @ref xrt_swapchain, as this function downcasts to @ref comp_swapchain ! 337 503 * 338 - * @ingroup comp_util 504 + * @param crc Compute renderer object 505 + * @param[in] layers Layers to render, see note. 506 + * @param[in] layer_count Number of elements in @p layers array. 507 + * @param[in] d Common render dispatch data 508 + * 339 509 */ 340 510 void 341 511 comp_render_cs_dispatch(struct render_compute *crc, ··· 343 513 const uint32_t layer_count, 344 514 const struct comp_render_dispatch_data *d); 345 515 516 + /* end of comp_render_cs group */ 517 + /*! @} */ 346 518 347 519 #ifdef __cplusplus 348 520 }