A compositor target: where the compositor renders to. More...

#include <main/comp_target.h>

Collaboration diagram for comp_target:

[legend]

Static Public Member Functions
static bool	comp_target_init_pre_vulkan (struct comp_target *ct)
	Do any initialization that is required to happen before Vulkan has been loaded.

static bool	comp_target_init_post_vulkan (struct comp_target *ct, uint32_t preferred_width, uint32_t preferred_height)
	Do any initialization that requires Vulkan to be loaded, you need to call create_images after calling this function.

static bool	comp_target_check_ready (struct comp_target *ct)
	Is this target ready for image creation?

static void	comp_target_create_images (struct comp_target ct, const struct comp_target_create_images_info create_info, struct vk_bundle_queue *present_queue)
	Create or recreate the image(s) of the target, for swapchain based targets this will (re)create the swapchain.

static bool	comp_target_has_images (struct comp_target *ct)
	Has this target successfully had images created?

static VkResult	comp_target_acquire (struct comp_target ct, uint32_t out_index)
	Acquire the next image for rendering.

static VkResult	comp_target_present (struct comp_target ct, struct vk_bundle_queue present_queue, uint32_t index, uint64_t timeline_semaphore_value, int64_t desired_present_time_ns, int64_t present_slop_ns)
	Present the image at index to the screen.

static VkResult	comp_target_wait_for_present (struct comp_target *ct, time_duration_ns timeout)
	Wait for the latest presented image to be displayed to the user.

static void	comp_target_flush (struct comp_target *ct)
	Flush any WSI state before rendering.

static void	comp_target_calc_frame_pacing (struct comp_target ct, int64_t out_frame_id, int64_t out_wake_up_time_ns, int64_t out_desired_present_time_ns, int64_t out_present_slop_ns, int64_t out_predicted_display_time_ns)
	Predict when the next frame should be started and when it will be turned into photons by the hardware.

static void	comp_target_mark_wake_up (struct comp_target *ct, int64_t frame_id, int64_t when_woke_ns)
	Quick helper for marking wake up.

static void	comp_target_mark_begin (struct comp_target *ct, int64_t frame_id, int64_t when_began_ns)
	Quick helper for marking begin.

static void	comp_target_mark_submit_begin (struct comp_target *ct, int64_t frame_id, int64_t when_submit_began_ns)
	Quick helper for marking submit began.

static void	comp_target_mark_submit_end (struct comp_target *ct, int64_t frame_id, int64_t when_submit_end_ns)
	Quick helper for marking submit end.

static VkResult	comp_target_update_timings (struct comp_target *ct)
	Update timing information for this target, this function should be lightweight and is called multiple times during a frame to make sure that we get the timing data as soon as possible.

static void	comp_target_info_gpu (struct comp_target *ct, int64_t frame_id, int64_t gpu_start_ns, int64_t gpu_end_ns, int64_t when_ns)
	Provide frame timing information about GPU start and stop time.

static void	comp_target_set_title (struct comp_target ct, const char title)
	If the target can show a title (like a window) set the title.

static xrt_result_t	comp_target_get_refresh_rates (struct comp_target ct, uint32_t count, float *rates)
	Get the available refresh rates for the compositor target.

static xrt_result_t	comp_target_get_current_refresh_rate (struct comp_target ct, float out_display_refresh_rate_hz)
	Get the current refresh rate for the compositor target.

static xrt_result_t	comp_target_request_refresh_rate (struct comp_target *ct, float ratedisplay_refresh_rate_hz)
	Get the current refresh rate for the compositor target.

static VkResult	comp_target_queue_supports_present (struct comp_target ct, struct vk_bundle_queue queue, VkBool32 *out_supported)
	Queries if a particular queue supports presentation ops/cmds for the compositor target.

static void	comp_target_destroy (struct comp_target **ct_ptr)
	Destroys this target.

Data Fields
struct comp_compositor *	c
	Owning compositor.

const char *	name
	Name of the backing system.

uint32_t	width
	Current dimensions of the target.

uint32_t	height

VkFormat	format
	The format that the renderpass targeting this target should use.

VkImageLayout	final_layout
	The final layout that the renderpass should leave this target in.

uint32_t	image_count
	Number of images that this target has.

struct comp_target_image *	images
	Array of images and image views for rendering.

VkSurfaceTransformFlagBitsKHR	surface_transform
	Transformation of the current surface, required for pre-rotation.

struct comp_target_semaphores	semaphores
	Holds semaphore information.

bool	wait_for_present_supported
	Whether wait_for_present is supported by this comp_target.

bool(*	init_pre_vulkan )(struct comp_target *ct)
	Do any initialization that is required to happen before Vulkan has been loaded.

bool(*	init_post_vulkan )(struct comp_target *ct, uint32_t preferred_width, uint32_t preferred_height)
	Do any initialization that requires Vulkan to be loaded, you need to call create_images after calling this function.

bool(*	check_ready )(struct comp_target *ct)
	Is this target ready for image creation?

void(*	create_images )(struct comp_target ct, const struct comp_target_create_images_info create_info, struct vk_bundle_queue *present_queue)
	Create or recreate the image(s) of the target, for swapchain based targets this will (re)create the swapchain.

bool(*	has_images )(struct comp_target *ct)
	Has this target successfully had images created?

VkResult(*	acquire )(struct comp_target ct, uint32_t out_index)
	Acquire the next image for rendering.

VkResult(*	present )(struct comp_target ct, struct vk_bundle_queue present_queue, uint32_t index, uint64_t timeline_semaphore_value, int64_t desired_present_time_ns, int64_t present_slop_ns)
	Present the image at index to the screen.

VkResult(*	wait_for_present )(struct comp_target *ct, time_duration_ns timeout_ns)
	Wait for the latest presented image to be displayed to the user.

void(*	flush )(struct comp_target *ct)
	Flush any WSI state before rendering.

void(*	calc_frame_pacing )(struct comp_target ct, int64_t out_frame_id, int64_t out_wake_up_time_ns, int64_t out_desired_present_time_ns, int64_t out_present_slop_ns, int64_t out_predicted_display_time_ns)
	Predict when the next frame should be started and when it will be turned into photons by the hardware.

void(*	mark_timing_point )(struct comp_target *ct, enum comp_target_timing_point point, int64_t frame_id, int64_t when_ns)
	The compositor tells the target a timing information about a single timing point on the frames lifecycle.

VkResult(*	update_timings )(struct comp_target *ct)
	Update timing information for this target, this function should be lightweight and is called multiple times during a frame to make sure that we get the timing data as soon as possible.

void(*	info_gpu )(struct comp_target *ct, int64_t frame_id, int64_t gpu_start_ns, int64_t gpu_end_ns, int64_t when_ns)
	Provide frame timing information about GPU start and stop time.

void(*	set_title )(struct comp_target ct, const char title)
	If the target can show a title (like a window) set the title.

xrt_result_t(*	get_refresh_rates )(struct comp_target ct, uint32_t out_count, float *out_display_refresh_rates_hz)
	Get the available refresh rates for the compositor target.

xrt_result_t(*	get_current_refresh_rate )(struct comp_target ct, float out_display_refresh_rate_hz)
	Get the current refresh rate for the compositor target.

xrt_result_t(*	request_refresh_rate )(struct comp_target *ct, float display_refresh_rate_hz)
	Get the current refresh rate for the compositor target.

VkResult(*	queue_supports_present )(struct comp_target ct, struct vk_bundle_queue queue, VkBool32 *out_supported)
	Queries if a particular queue supports presentation ops/cmds for the compositor target.

void(*	destroy )(struct comp_target *ct)
	Destroys this target.

Detailed Description

A compositor target: where the compositor renders to.

A target is essentially a swapchain, but it is such a overloaded term so we are differentiating swapchains that the compositor provides to clients and swapchains that the compositor renders by naming the latter to target.

For design purposes, when amending this interface, remember that targets may not necessarily be backed by a swapchain in all cases, for instance with remote rendering.

Field Documentation

◆ acquire

VkResult(* comp_target::acquire) (struct comp_target *ct, uint32_t *out_index)

Acquire the next image for rendering.

If comp_target_semaphores::present_complete is not null, your use of this image should wait on it..

Precondition: has_images() returns true

Referenced by comp_target_acquire(), and comp_target_swapchain::comp_target_swapchain_init_and_set_fnptrs().

◆ c

struct comp_compositor* comp_target::c

Owning compositor.

Referenced by comp_target_factory::comp_target_factory_create_target(), comp_target_factory::comp_target_factory_detect(), comp_target_swapchain::comp_target_swapchain_override_extents(), comp_window_direct_create_surface(), comp_window_direct_nvidia::comp_window_direct_nvidia_create(), comp_window_direct_nvidia_init(), comp_window_direct_randr::comp_window_direct_randr_create(), comp_window_direct_wayland_create(), comp_window_mswin_init_swapchain(), comp_window_mswin_thread(), comp_window_wayland::comp_window_wayland_create(), and comp_window_xcb::comp_window_xcb_create().

◆ calc_frame_pacing

void(* comp_target::calc_frame_pacing) (struct comp_target *ct, int64_t *out_frame_id, int64_t *out_wake_up_time_ns, int64_t *out_desired_present_time_ns, int64_t *out_present_slop_ns, int64_t *out_predicted_display_time_ns)

Predict when the next frame should be started and when it will be turned into photons by the hardware.

Referenced by comp_target_calc_frame_pacing(), and comp_target_swapchain::comp_target_swapchain_init_and_set_fnptrs().

◆ check_ready

bool(* comp_target::check_ready) (struct comp_target *ct)

Is this target ready for image creation?

Call before calling create_images

Referenced by comp_target_check_ready(), and comp_target_swapchain::comp_target_swapchain_init_and_set_fnptrs().

◆ create_images

void(* comp_target::create_images) (struct comp_target *ct, const struct comp_target_create_images_info *create_info, struct vk_bundle_queue *present_queue)

Create or recreate the image(s) of the target, for swapchain based targets this will (re)create the swapchain.

Parameters

ct	self
create_info	Image creation parameters
present_queue	The queue that will be used for presentation operations (must not be NULL)

Precondition: check_ready returns true

Referenced by comp_target_create_images(), and comp_target_swapchain::comp_target_swapchain_init_and_set_fnptrs().

◆ destroy

void(* comp_target::destroy) (struct comp_target *ct)

Destroys this target.

Referenced by comp_target_destroy(), comp_window_direct_nvidia::comp_window_direct_nvidia_create(), comp_window_direct_randr::comp_window_direct_randr_create(), comp_window_direct_wayland_create(), comp_window_wayland::comp_window_wayland_create(), and comp_window_xcb::comp_window_xcb_create().

◆ final_layout

VkImageLayout comp_target::final_layout

The final layout that the renderpass should leave this target in.

Referenced by renderer_create_renderings_and_fences().

◆ flush

void(* comp_target::flush) (struct comp_target *ct)

Flush any WSI state before rendering.

Referenced by comp_target_flush(), comp_window_direct_nvidia::comp_window_direct_nvidia_create(), comp_window_direct_randr::comp_window_direct_randr_create(), comp_window_direct_wayland_create(), comp_window_wayland::comp_window_wayland_create(), and comp_window_xcb::comp_window_xcb_create().

◆ format

VkFormat comp_target::format

The format that the renderpass targeting this target should use.

Referenced by renderer_create_renderings_and_fences().

◆ get_current_refresh_rate

xrt_result_t(* comp_target::get_current_refresh_rate) (struct comp_target *ct, float *out_display_refresh_rate_hz)

Get the current refresh rate for the compositor target.

Parameters

ct	The compositor target.
out_display_refresh_rate_hz	The current refresh rate, in Hz

Referenced by comp_target_get_current_refresh_rate().

◆ get_refresh_rates

xrt_result_t(* comp_target::get_refresh_rates) (struct comp_target *ct, uint32_t *out_count, float *out_display_refresh_rates_hz)

Get the available refresh rates for the compositor target.

Parameters

ct	The compositor target.
count	The number or refresh rates.
refresh_rates_hz	The refresh rates, in Hz. Must be allocated by caller, and have at least XRT_MAX_SUPPORTED_REFRESH_RATES elements

Referenced by xrt_system_compositor::comp_main_create_system_compositor(), and comp_target_get_refresh_rates().

◆ has_images

bool(* comp_target::has_images) (struct comp_target *ct)

Has this target successfully had images created?

Call before calling acquire - if false but check_ready is true, you'll need to call create_images.

Referenced by comp_target_has_images(), and comp_target_swapchain::comp_target_swapchain_init_and_set_fnptrs().

◆ image_count

uint32_t comp_target::image_count

Number of images that this target has.

◆ images

struct comp_target_image* comp_target::images

Array of images and image views for rendering.

Referenced by comp_renderer::comp_renderer_draw(), dispatch_compute(), and renderer_build_rendering_target_resources().

◆ info_gpu

void(* comp_target::info_gpu) (struct comp_target *ct, int64_t frame_id, int64_t gpu_start_ns, int64_t gpu_end_ns, int64_t when_ns)

Provide frame timing information about GPU start and stop time.

Depend on when the information is delivered this can be called at any point of the following frames.

Parameters

[in]	ct	The compositor target.
[in]	frame_id	The frame ID to record for.
[in]	gpu_start_ns	When the GPU work startred.
[in]	gpu_end_ns	When the GPU work stopped.
[in]	when_ns	When the informatioon collected, nominally from os_monotonic_get_ns.

See also: Frame Pacing/Timing.

Referenced by comp_target_info_gpu(), and comp_target_swapchain::comp_target_swapchain_init_and_set_fnptrs().

◆ init_post_vulkan

bool(* comp_target::init_post_vulkan) (struct comp_target *ct, uint32_t preferred_width, uint32_t preferred_height)

Do any initialization that requires Vulkan to be loaded, you need to call create_images after calling this function.

Referenced by comp_target_init_post_vulkan(), comp_window_direct_nvidia::comp_window_direct_nvidia_create(), comp_window_direct_randr::comp_window_direct_randr_create(), comp_window_direct_wayland_create(), comp_window_wayland::comp_window_wayland_create(), and comp_window_xcb::comp_window_xcb_create().

◆ init_pre_vulkan

bool(* comp_target::init_pre_vulkan) (struct comp_target *ct)

Do any initialization that is required to happen before Vulkan has been loaded.

Referenced by comp_target_init_pre_vulkan(), comp_window_direct_nvidia::comp_window_direct_nvidia_create(), comp_window_direct_randr::comp_window_direct_randr_create(), comp_window_direct_wayland_create(), comp_window_wayland::comp_window_wayland_create(), and comp_window_xcb::comp_window_xcb_create().

◆ mark_timing_point

void(* comp_target::mark_timing_point) (struct comp_target *ct, enum comp_target_timing_point point, int64_t frame_id, int64_t when_ns)

The compositor tells the target a timing information about a single timing point on the frames lifecycle.

Referenced by comp_target_mark_begin(), comp_target_mark_submit_begin(), comp_target_mark_submit_end(), comp_target_mark_wake_up(), and comp_target_swapchain::comp_target_swapchain_init_and_set_fnptrs().

◆ name

const char* comp_target::name

Name of the backing system.

Referenced by ipcproto.common.Arg::__init__(), ipcproto.common.Call::__init__(), bindings.Profile::__init__(), comp_target_swapchain::comp_target_swapchain_override_extents(), comp_window_direct_nvidia::comp_window_direct_nvidia_create(), comp_window_direct_randr::comp_window_direct_randr_create(), comp_window_direct_wayland_create(), comp_window_wayland::comp_window_wayland_create(), comp_window_xcb::comp_window_xcb_create(), ipcproto.common.Arg::dump(), ipcproto.common.Call::dump(), ipcproto.common.Arg::get_func_argument_in(), ipcproto.common.Arg::get_func_argument_out(), ipcproto.common.Arg::get_struct_field(), ipcproto.common.Call::write_call_decl(), ipcproto.common.Call::write_handler_decl(), ipcproto.common.Call::write_receive_decl(), and ipcproto.common.Call::write_send_decl().

◆ present

VkResult(* comp_target::present) (struct comp_target *ct, struct vk_bundle_queue *present_queue, uint32_t index, uint64_t timeline_semaphore_value, int64_t desired_present_time_ns, int64_t present_slop_ns)

Present the image at index to the screen.

Precondition: acquire succeeded for the same semaphore and index you are passing

Parameters

ct	self
present_queue	The Vulkan queue bundle being used for presentation (must not be NULL)
index	The swapchain image index to present
timeline_semaphore_value	The value to await on comp_target_semaphores::render_complete if comp_target_semaphores::render_complete_is_timeline is true.
desired_present_time_ns	The timestamp to present at, ideally.
present_slop_ns	TODO

Referenced by comp_target_present(), and comp_target_swapchain::comp_target_swapchain_init_and_set_fnptrs().

◆ queue_supports_present

VkResult(* comp_target::queue_supports_present) (struct comp_target *ct, struct vk_bundle_queue *queue, VkBool32 *out_supported)

Queries if a particular queue supports presentation ops/cmds for the compositor target.

Parameters

ct	The compositor target.
queue	The vulkan queue to query
out_supported	If the queue supports presentation ops/cmds for ct present surface.

Referenced by comp_target_queue_supports_present(), and comp_target_swapchain::comp_target_swapchain_init_and_set_fnptrs().

◆ request_refresh_rate

xrt_result_t(* comp_target::request_refresh_rate) (struct comp_target *ct, float display_refresh_rate_hz)

Get the current refresh rate for the compositor target.

Parameters

ct	The compositor target.
display_refresh_rate_hz	The requested refresh rate, in Hz.

Referenced by comp_target_request_refresh_rate().

◆ semaphores

struct comp_target_semaphores comp_target::semaphores

Holds semaphore information.

Referenced by comp_target_swapchain_acquire_next_image().

◆ set_title

void(* comp_target::set_title) (struct comp_target *ct, const char *title)

If the target can show a title (like a window) set the title.

Referenced by comp_target_set_title(), comp_window_direct_nvidia::comp_window_direct_nvidia_create(), comp_window_direct_randr::comp_window_direct_randr_create(), comp_window_direct_wayland_create(), comp_window_wayland::comp_window_wayland_create(), and comp_window_xcb::comp_window_xcb_create().

◆ surface_transform

VkSurfaceTransformFlagBitsKHR comp_target::surface_transform

Transformation of the current surface, required for pre-rotation.

◆ update_timings

VkResult(* comp_target::update_timings) (struct comp_target *ct)

Update timing information for this target, this function should be lightweight and is called multiple times during a frame to make sure that we get the timing data as soon as possible.

Referenced by comp_target_swapchain::comp_target_swapchain_init_and_set_fnptrs(), and comp_target_update_timings().

◆ wait_for_present

VkResult(* comp_target::wait_for_present) (struct comp_target *ct, time_duration_ns timeout_ns)

Wait for the latest presented image to be displayed to the user.

Parameters

ct	self
timeout_ns	The amount of time to wait for presentation to succeed.

Referenced by comp_target_swapchain::comp_target_swapchain_init_and_set_fnptrs(), and comp_target_wait_for_present().

◆ wait_for_present_supported

bool comp_target::wait_for_present_supported

Whether wait_for_present is supported by this comp_target.

◆ width

uint32_t comp_target::width

Current dimensions of the target.

Referenced by comp_renderer::comp_renderer_draw(), comp_window_mswin_thread(), and renderer_build_rendering_target_resources().

The documentation for this struct was generated from the following file:

compositor/main/comp_target.h

Static Public Member Functions

Data Fields

Detailed Description

Field Documentation

◆ acquire

◆ c

◆ calc_frame_pacing

◆ check_ready

◆ create_images

◆ destroy

◆ final_layout

◆ flush

◆ format

◆ get_current_refresh_rate

◆ get_refresh_rates

◆ has_images

◆ image_count

◆ images

◆ info_gpu

◆ init_post_vulkan

◆ init_pre_vulkan

◆ mark_timing_point

◆ name

◆ present

◆ queue_supports_present

◆ request_refresh_rate

◆ semaphores

◆ set_title

◆ surface_transform

◆ update_timings

◆ wait_for_present

◆ wait_for_present_supported

◆ width