Compositor utility code

General compositor utility code. More...

Collaboration diagram for Compositor utility code:

Files
file	comp_base.c
	Helper implementation for native compositors.
file	comp_base.h
	Helper implementation for native compositors.
file	comp_render.h
	Independent semaphore implementation.
file	comp_render_gfx.c
	Compositor gfx rendering code.
file	comp_render_helpers.h
	Compositor rendering code helpers.
file	comp_scratch.c
	Helper implementation for native compositors.
file	comp_scratch.h
	Helper implementation for native compositors.
file	comp_semaphore.c
	Independent semaphore implementation.
file	comp_semaphore.h
	Independent semaphore implementation.
file	comp_swapchain.c
	Independent swapchain implementation.
file	comp_swapchain.h
	Independent swapchain implementation.
file	comp_sync.c
	Independent xrt_compositor_fence implementation.
file	comp_sync.h
	Independent xrt_compositor_fence implementation.
file	comp_vulkan.c
	Vulkan code for compositors.
file	comp_vulkan.h
	Vulkan code for compositors.

Data Structures
struct	comp_layer
	A single layer. More...
struct	comp_layer_slot
	A stack of layers. More...
struct	comp_base
	A simple compositor base that handles a lot of things for you. More...
struct	comp_scratch_indices
	Small helper struct to deal with indices. More...
struct	comp_scratch_single_images
	Holds scratch images for a single view, designed to work with render code. More...
struct	comp_scratch_stereo_images
	Holds scartch images for a stereo views, designed to work with render code. More...
struct	comp_semaphore
	A simple implementation of the xrt_compositor_semaphore interface. More...
struct	comp_swapchain_shared
	Shared resource(s) and garbage collector for swapchains. More...
struct	comp_swapchain_image
	A single swapchain image, holds the needed state for tracking image usage. More...
struct	comp_swapchain
	A swapchain that is almost a one to one mapping to a OpenXR swapchain. More...

Typedefs
typedef void(*	comp_swapchain_destroy_func_t) (struct comp_swapchain *sc)
	Callback for implementing own destroy function, should call comp_swapchain_teardown and is responsible for memory. More...

Functions
void	comp_render_gfx_dispatch (struct render_gfx *rr, const struct comp_layer *layers, const uint32_t layer_count, const struct comp_render_dispatch_data *d)
	Helper function that takes a set of layers, new device poses, a scratch images with associated render_gfx_target_resources and writes the needed commands to the render_gfx to do a full composition with distortion. More...
void	comp_render_cs_layers (struct render_compute *crc, const struct comp_layer *layers, const uint32_t layer_count, const struct comp_render_dispatch_data *d, VkImageLayout transition_to)
	Helper function to dispatch the layer squasher, works on any number of views. More...
void	comp_render_cs_dispatch (struct render_compute *crc, const struct comp_layer *layers, const uint32_t layer_count, const struct comp_render_dispatch_data *d)
	Helper function that takes a set of layers, new device poses, a scratch images and writes the needed commands to the render_compute to do a full composition with distortion. More...
void	comp_scratch_single_images_init (struct comp_scratch_single_images *cssi)
	Init the struct, this function must be called before calling any other function on this struct, or variable tracking setup on unid. More...
bool	comp_scratch_single_images_ensure (struct comp_scratch_single_images *cssi, struct vk_bundle *vk, VkExtent2D extent)
	Ensure that the scratch images are allocated and match extent size. More...
void	comp_scratch_single_images_free (struct comp_scratch_single_images *cssi, struct vk_bundle *vk)
	Free all images allocated, init must be called before calling this function, is safe to call without any image allocated. More...
void	comp_scratch_single_images_get (struct comp_scratch_single_images *cssi, uint32_t *out_index)
	Get the next free image, after this function has been called you must call either done or discard before calling any other function. More...
void	comp_scratch_single_images_done (struct comp_scratch_single_images *cssi)
	After calling get and rendering to the image you call this function to signal that you are done with this function, the GPU work needs to be fully completed before calling done. More...
void	comp_scratch_single_images_discard (struct comp_scratch_single_images *cssi)
	Discard a @g get call, this clears the image debug part causing no image to be shown in the debug UI. More...
void	comp_scratch_single_images_clear_debug (struct comp_scratch_single_images *cssi)
	Clears the debug output, this causes nothing to be shown in the debug UI. More...
void	comp_scratch_single_images_destroy (struct comp_scratch_single_images *cssi)
	Destroys scratch image struct, if any images has been allocated must call free before as this function only destroys the mutex, and the unid must no longer be tracked. More...
xrt_result_t	comp_semaphore_create (struct vk_bundle *vk, xrt_graphics_sync_handle_t *out_handle, struct xrt_compositor_semaphore **out_xcsem)
	Creates a comp_semaphore, used to implement compositor functionality. More...
static void	really_destroy (struct comp_swapchain *sc)
	Swapchain destruct is delayed until it is safe to destroy them, this function does the actual destruction and is called from comp_swapchain_shared_garbage_collect. More...
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_swapchain within another struct. More...
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_swapchain within another struct. More...
void	comp_swapchain_teardown (struct comp_swapchain *sc)
	De-inits a comp_swapchain, usable for classes sub-classing comp_swapchain. More...
XRT_CHECK_RESULT xrt_result_t	comp_swapchain_shared_init (struct comp_swapchain_shared *cscs, struct vk_bundle *vk)
	Create the shared struct. More...
void	comp_swapchain_shared_destroy (struct comp_swapchain_shared *cscs, struct vk_bundle *vk)
	Destroy the shared struct. More...
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 threads. More...
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. More...
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. More...
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. More...
xrt_result_t	comp_fence_import (struct vk_bundle *vk, xrt_graphics_sync_handle_t handle, struct xrt_compositor_fence **out_xcf)
	For importing xrt_graphics_sync_handle_t and turn them into a xrt_compositor_fence. More...
bool	comp_vulkan_init_bundle (struct vk_bundle *vk, const struct comp_vulkan_arguments *vk_args, struct comp_vulkan_results *vk_res)
	Fully initialises a vk_bundle, by creating instance, device and queue. More...
void	comp_vulkan_formats_check (struct vk_bundle *vk, struct comp_vulkan_formats *formats)
	Fills in a comp_vulkan_formats struct with the supported formats, use comp_vulkan_formats_copy_to_info to fill a compositor info struct. More...
void	comp_vulkan_formats_copy_to_info (const struct comp_vulkan_formats *formats, struct xrt_compositor_info *info)
	Fills in a xrt_compositor_info struct with the formats listed from a comp_vulkan_formats. More...
void	comp_vulkan_formats_log (enum u_logging_level log_level, const struct comp_vulkan_formats *formats)
	Logs the formats at info level. More...

Detailed Description

General compositor utility code.

Typedef Documentation

comp_swapchain_destroy_func_t

typedef void(* comp_swapchain_destroy_func_t) (struct comp_swapchain *sc)

#include <compositor/util/comp_swapchain.h>

Callback for implementing own destroy function, should call comp_swapchain_teardown and is responsible for memory.

Function Documentation

comp_fence_import()

xrt_result_t comp_fence_import	(	struct vk_bundle *	vk,
		xrt_graphics_sync_handle_t	handle,
		struct xrt_compositor_fence **	out_xcf
	)

#include <compositor/util/comp_sync.h>

For importing xrt_graphics_sync_handle_t and turn them into a xrt_compositor_fence.

The vk_bundle is owned by the compositor, its the state trackers job to make sure that compositor lives for as long as the fence does and that all fences are destroyed before the compositor is destroyed.

comp_render_cs_dispatch()

void comp_render_cs_dispatch	(	struct render_compute *	crc,
		const struct comp_layer *	layers,
		const uint32_t	layer_count,
		const struct comp_render_dispatch_data *	d
	)

#include <compositor/util/comp_render.h>

Helper function that takes a set of layers, new device poses, a scratch images and writes the needed commands to the render_compute to do a full composition with distortion.

The scratch images are optionally used to squash layers should it not be possible to do a fast_path. Will insert barriers to change the scratch images and target images to the needed layout.

Expected layouts:

• Layer images: VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL
• Sratch images: Any
• Target image: Any

After call layouts:

• Layer images: VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL
• Sratch images: VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL
• Target image: VK_IMAGE_LAYOUT_PRESENT_SRC_KHR

References comp_render_dispatch_data::fast_path.

comp_render_cs_layers()

void comp_render_cs_layers	(	struct render_compute *	crc,
		const struct comp_layer *	layers,
		const uint32_t	layer_count,
		const struct comp_render_dispatch_data *	d,
		VkImageLayout	transition_to
	)

#include <compositor/util/comp_render.h>

Helper function to dispatch the layer squasher, works on any number of views.

All source layer images needs to be in the correct image layout, no barrier is inserted for them. The target images are barried from undefined to general so they can be written to, then to the laying defined by transition_to.

Expected layouts:

• Layer images: VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL
• Target images: Any

After call layouts:

• Layer images: VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL
• Target images: transition_to

comp_render_gfx_dispatch()

void comp_render_gfx_dispatch	(	struct render_gfx *	rr,
		const struct comp_layer *	layers,
		const uint32_t	layer_count,
		const struct comp_render_dispatch_data *	d
	)

#include <compositor/util/comp_render.h>

Helper function that takes a set of layers, new device poses, a scratch images with associated render_gfx_target_resources and writes the needed commands to the render_gfx to do a full composition with distortion.

The scratch images are optionally used to squash layers should it not be possible to do a comp_render_dispatch_data::fast_path. Will use the render passes of the targets which set the layout.

The render passes of comp_render_dispatch_data::views::rtr must be created with a final_layout of VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL or there will be validation errors.

Expected layouts:

• Layer images: VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL
• Scratch images: Any (as per the render_gfx_render_pass)
• Target image: Any (as per the render_gfx_render_pass)

After call layouts:

• Layer images: VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL
• Scratch images: VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL
• Target image: What the render pass of rtr specifies.

References comp_layer::data, comp_render_dispatch_data::fast_path, and xrt_layer_data::type.

comp_scratch_single_images_clear_debug()

void comp_scratch_single_images_clear_debug

(

struct comp_scratch_single_images *

cssi

)

#include <compositor/util/comp_scratch.h>

Clears the debug output, this causes nothing to be shown in the debug UI.

References u_native_images_debug_clear(), and comp_scratch_single_images::unid.

comp_scratch_single_images_destroy()

void comp_scratch_single_images_destroy

(

struct comp_scratch_single_images *

cssi

)

#include <compositor/util/comp_scratch.h>

Destroys scratch image struct, if any images has been allocated must call free before as this function only destroys the mutex, and the unid must no longer be tracked.

References u_native_images_debug_destroy(), and comp_scratch_single_images::unid.

comp_scratch_single_images_discard()

void comp_scratch_single_images_discard

(

struct comp_scratch_single_images *

cssi

)

#include <compositor/util/comp_scratch.h>

Discard a @g get call, this clears the image debug part causing no image to be shown in the debug UI.

comp_scratch_single_images_done()

void comp_scratch_single_images_done

(

struct comp_scratch_single_images *

cssi

)

#include <compositor/util/comp_scratch.h>

After calling get and rendering to the image you call this function to signal that you are done with this function, the GPU work needs to be fully completed before calling done.

comp_scratch_single_images_ensure()

bool comp_scratch_single_images_ensure	(	struct comp_scratch_single_images *	cssi,
		struct vk_bundle *	vk,
		VkExtent2D	extent
	)

#include <compositor/util/comp_scratch.h>

Ensure that the scratch images are allocated and match extent size.

References comp_scratch_single_images::info, and XRT_STRUCT_INIT.

comp_scratch_single_images_free()

void comp_scratch_single_images_free	(	struct comp_scratch_single_images *	cssi,
		struct vk_bundle *	vk
	)

#include <compositor/util/comp_scratch.h>

Free all images allocated, init must be called before calling this function, is safe to call without any image allocated.

References COMP_SCRATCH_NUM_IMAGES, u_native_images_debug_clear(), and comp_scratch_single_images::unid.

comp_scratch_single_images_get()

void comp_scratch_single_images_get	(	struct comp_scratch_single_images *	cssi,
		uint32_t *	out_index
	)

#include <compositor/util/comp_scratch.h>

Get the next free image, after this function has been called you must call either done or discard before calling any other function.

comp_scratch_single_images_init()

void comp_scratch_single_images_init

(

struct comp_scratch_single_images *

cssi

)

#include <compositor/util/comp_scratch.h>

Init the struct, this function must be called before calling any other function on this struct, or variable tracking setup on unid.

Zero init is not enough as it has a mutex in it and has native handles which on some platforms zero is a valid handle.

References U_ZERO.

comp_semaphore_create()

xrt_result_t comp_semaphore_create	(	struct vk_bundle *	vk,
		xrt_graphics_sync_handle_t *	out_handle,
		struct xrt_compositor_semaphore **	out_xcsem
	)

#include <compositor/util/comp_semaphore.h>

Creates a comp_semaphore, used to implement compositor functionality.

References vk_bundle::timeline_semaphore, and XRT_ERROR_VULKAN.

comp_swapchain_create()

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
	)

#include <compositor/util/comp_swapchain.h>

A compositor function that is implemented in the swapchain code.

References xrt_swapchain_native::base, comp_swapchain_create_init(), really_destroy(), U_TYPED_CALLOC, XRT_SUCCESS, and xrt_swapchain::xrt_swapchain_reference().

comp_swapchain_create_init()

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
	)

#include <compositor/util/comp_swapchain.h>

Helper to init a comp_swachain struct as if it was a create operation, useful for wrapping comp_swapchain within another struct.

Ref-count is set to zero so the caller need to init it correctly.

Referenced by comp_swapchain_create().

comp_swapchain_get_create_properties()

xrt_result_t comp_swapchain_get_create_properties	(	const struct xrt_swapchain_create_info *	info,
		struct xrt_swapchain_create_properties *	xsccp
	)

#include <compositor/util/comp_swapchain.h>

A compositor function that is implemented in the swapchain code.

References xrt_swapchain_create_properties::extra_bits, xrt_swapchain::image_count, xrt_swapchain_create_properties::image_count, U_ZERO, and XRT_SWAPCHAIN_CREATE_STATIC_IMAGE.

comp_swapchain_import()

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
	)

#include <compositor/util/comp_swapchain.h>

A compositor function that is implemented in the swapchain code.

References xrt_swapchain_native::base, comp_swapchain_import_init(), really_destroy(), U_TYPED_CALLOC, XRT_SUCCESS, and xrt_swapchain::xrt_swapchain_reference().

comp_swapchain_import_init()

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
	)

#include <compositor/util/comp_swapchain.h>

Helper to init a comp_swachain struct as if it was a import operation, useful for wrapping comp_swapchain within another struct.

Ref-count is set to zero so the caller need to init it correctly.

Referenced by comp_swapchain_import().

comp_swapchain_shared_destroy()

void comp_swapchain_shared_destroy	(	struct comp_swapchain_shared *	cscs,
		struct vk_bundle *	vk
	)

#include <compositor/util/comp_swapchain.h>

Destroy the shared struct.

References vk_cmd_pool::vk_cmd_pool_destroy().

comp_swapchain_shared_garbage_collect()

void comp_swapchain_shared_garbage_collect

(

struct comp_swapchain_shared *

cscs

)

#include <compositor/util/comp_swapchain.h>

Do garbage collection, destroying any resources that has been scheduled for destruction from other threads.

comp_swapchain_shared_init()

XRT_CHECK_RESULT xrt_result_t comp_swapchain_shared_init	(	struct comp_swapchain_shared *	cscs,
		struct vk_bundle *	vk
	)

#include <compositor/util/comp_swapchain.h>

Create the shared struct.

References vk_cmd_pool::vk_cmd_pool_init().

comp_swapchain_teardown()

void comp_swapchain_teardown

(

struct comp_swapchain *

sc

)

#include <compositor/util/comp_swapchain.h>

De-inits a comp_swapchain, usable for classes sub-classing comp_swapchain.

Referenced by really_destroy().

comp_vulkan_formats_check()

void comp_vulkan_formats_check	(	struct vk_bundle *	vk,
		struct comp_vulkan_formats *	formats
	)

#include <compositor/util/comp_vulkan.h>

Fills in a comp_vulkan_formats struct with the supported formats, use comp_vulkan_formats_copy_to_info to fill a compositor info struct.

References VK_CSCI_FORMATS.

comp_vulkan_formats_copy_to_info()

void comp_vulkan_formats_copy_to_info	(	const struct comp_vulkan_formats *	formats,
		struct xrt_compositor_info *	info
	)

#include <compositor/util/comp_vulkan.h>

Fills in a xrt_compositor_info struct with the formats listed from a comp_vulkan_formats.

This and comp_vulkan_formats_check are split to allow the compositor to allow/deny certain formats.

References VK_CSCI_FORMATS.

comp_vulkan_formats_log()

void comp_vulkan_formats_log	(	enum u_logging_level	log_level,
		const struct comp_vulkan_formats *	formats
	)

#include <compositor/util/comp_vulkan.h>

Logs the formats at info level.

comp_vulkan_init_bundle()

bool comp_vulkan_init_bundle	(	struct vk_bundle *	vk,
		const struct comp_vulkan_arguments *	vk_args,
		struct comp_vulkan_results *	vk_res
	)

#include <compositor/util/comp_vulkan.h>

Fully initialises a vk_bundle, by creating instance, device and queue.

References comp_vulkan_arguments::get_instance_proc_address, comp_vulkan_arguments::log_level, and vk_get_loader_functions().

really_destroy()

static void really_destroy ( struct comp_swapchain *  sc )

static

#include <compositor/util/comp_swapchain.c>

Swapchain destruct is delayed until it is safe to destroy them, this function does the actual destruction and is called from comp_swapchain_shared_garbage_collect.

References comp_swapchain_teardown().

Referenced by comp_swapchain_create(), and comp_swapchain_import().