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. More...

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. More...

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

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

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

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

static VkResult	comp_target_present (struct comp_target *ct, VkQueue 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. More...

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

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. More...

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. More...

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

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. More...

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. More...

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. More...

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. More...

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. More...

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

Data Fields
struct comp_compositor *	c
	Owning compositor. More...

const char *	name
	Name of the backing system. More...

uint32_t	width
	Current dimensions of the target. More...

uint32_t	height

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

uint32_t	image_count
	Number of images that this target has. More...

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

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

struct comp_target_semaphores	semaphores

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

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. More...

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

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

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

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

VkResult(*	present )(struct comp_target *ct, VkQueue 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. More...

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

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. More...

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. More...

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. More...

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. More...

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

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

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

◆ c

struct comp_compositor* comp_target::c

Owning compositor.

Referenced by comp_target_swapchain::comp_target_swapchain_override_extents().

◆ 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.

◆ 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_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)

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

Precondition: check_ready returns true

◆ destroy

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

Destroys this target.

Referenced by comp_target_destroy().

◆ flush

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

Flush any WSI state before rendering.

◆ format

VkFormat comp_target::format

The format that the renderpass targeting this target should use.

Referenced by renderer_create_renderings_and_fences().

◆ 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.

◆ 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.

◆ 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.

◆ 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.

◆ 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.

◆ 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.

◆ 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(), 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, VkQueue 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
queue	The Vulkan queue being used
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

◆ 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.

◆ 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.

◆ width

uint32_t comp_target::width

Current dimensions of the target.

Referenced by comp_window_mswin_thread().

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

compositor/main/comp_target.h

Static Public Member Functions

Data Fields