Documentation for <wlr/types/wlr_output.h>

Back to index

Table of contents

struct wlr_output 

struct wlr_output {
	const struct wlr_output_impl *impl;
	struct wlr_backend *backend;
	struct wl_event_loop *event_loop;
	
	struct wl_global *global;
	struct wl_list resources;
	
	char *name;
	char *description; // may be NULL
	char *make, *model, *serial; // may be NULL
	int32_t phys_width, phys_height; // mm
	
	// Note: some backends may have zero modes
	struct wl_list modes; // wlr_output_mode.link
	struct wlr_output_mode *current_mode;
	int32_t width, height;
	int32_t refresh; // mHz, may be zero
	
	bool enabled;
	float scale;
	enum wl_output_subpixel subpixel;
	enum wl_output_transform transform;
	enum wlr_output_adaptive_sync_status adaptive_sync_status;
	uint32_t render_format;
	
	bool needs_frame;
	// damage for cursors and fullscreen surface, in output-local coordinates
	 bool frame_pending;
	
	// true for example with VR headsets
	 bool non_desktop;
	
	// Commit sequence number. Incremented on each commit, may overflow.
	uint32_t commit_seq;
	
	struct {
		// Request to render a frame
		struct wl_signal frame;
		// Emitted when software cursors or backend-specific logic damage the
		// output
		struct wl_signal damage; // struct wlr_output_event_damage
		// Emitted when a new frame needs to be committed (because of
		// backend-specific logic)
		struct wl_signal needs_frame;
		// Emitted right before commit
		struct wl_signal precommit; // struct wlr_output_event_precommit
		// Emitted right after commit
		struct wl_signal commit; // struct wlr_output_event_commit
		// Emitted right after a commit has been presented to the user for
		// enabled outputs
		struct wl_signal present; // struct wlr_output_event_present
		// Emitted after a client bound the wl_output global
		struct wl_signal bind; // struct wlr_output_event_bind
		struct wl_signal description;
		struct wl_signal request_state; // struct wlr_output_event_request_state
		struct wl_signal destroy;
	} events;
	
	struct wl_event_source *idle_frame;
	struct wl_event_source *idle_done;
	
	int attach_render_locks; // number of locks forcing rendering
	
	struct wl_list cursors; // wlr_output_cursor.link
	struct wlr_output_cursor *hardware_cursor;
	struct wlr_swapchain *cursor_swapchain;
	struct wlr_buffer *cursor_front_buffer;
	int software_cursor_locks; // number of locks forcing software cursors
	
	struct wl_list layers; // wlr_output_layer.link
	
	struct wlr_allocator *allocator;
	struct wlr_renderer *renderer;
	struct wlr_swapchain *swapchain;
	
	struct wl_listener display_destroy;
	
	struct wlr_addon_set addons;
	
	void *data;
};

A compositor output region. This typically corresponds to a monitor that displays part of the compositor space.

The `frame` event will be emitted when it is a good time for the compositor to submit a new frame.

To render a new frame, compositors should call wlr_output_begin_render_pass(), perform rendering on that render pass and finally call wlr_output_commit().

enum wlr_output_adaptive_sync_status 

enum wlr_output_adaptive_sync_status {
	WLR_OUTPUT_ADAPTIVE_SYNC_DISABLED,
	WLR_OUTPUT_ADAPTIVE_SYNC_ENABLED,
};

wlr_output_add_software_cursors_to_render_pass() 

void wlr_output_add_software_cursors_to_render_pass(​struct wlr_output *output, struct wlr_render_pass *render_pass, const pixman_region32_t *damage);

Render software cursors.

This is a utility function that can be called when compositors render.

wlr_output_begin_render_pass() 

struct wlr_render_pass *wlr_output_begin_render_pass(​struct wlr_output *output, struct wlr_output_state *state, int *buffer_age, struct wlr_buffer_pass_options *render_options);

Begin a render pass on this output.

Compositors can call this function to begin rendering. After the render pass has been submitted, they should call wlr_output_commit_state() to submit the new frame.

On error, NULL is returned. Creating a render pass on a disabled output is an error.

The state describes the output changes the rendered frame will be committed with. A NULL state indicates no change.

If non-NULL, buffer_age is set to the drawing buffer age in number of frames or -1 if unknown. This is useful for damage tracking.

wlr_output_commit_state() 

bool wlr_output_commit_state(​struct wlr_output *output, const struct wlr_output_state *state);

wlr_output_configure_primary_swapchain() 

bool wlr_output_configure_primary_swapchain(​struct wlr_output *output, const struct wlr_output_state *state, struct wlr_swapchain **swapchain);

wlr_output_create_global() 

void wlr_output_create_global(​struct wlr_output *output, struct wl_display *display);

struct wlr_output_cursor 

struct wlr_output_cursor {
	struct wlr_output *output;
	double x, y;
	bool enabled;
	bool visible;
	uint32_t width, height;
	struct wlr_fbox src_box;
	enum wl_output_transform transform;
	int32_t hotspot_x, hotspot_y;
	struct wlr_texture *texture;
	bool own_texture;
	struct wl_list link;
};

wlr_output_cursor_create() 

struct wlr_output_cursor *wlr_output_cursor_create(​struct wlr_output *output);

wlr_output_cursor_destroy() 

void wlr_output_cursor_destroy(​struct wlr_output_cursor *cursor);

wlr_output_cursor_move() 

bool wlr_output_cursor_move(​struct wlr_output_cursor *cursor, double x, double y);

wlr_output_cursor_set_buffer() 

bool wlr_output_cursor_set_buffer(​struct wlr_output_cursor *cursor, struct wlr_buffer *buffer, int32_t hotspot_x, int32_t hotspot_y);

wlr_output_destroy() 

void wlr_output_destroy(​struct wlr_output *output);

wlr_output_destroy_global() 

void wlr_output_destroy_global(​struct wlr_output *output);

wlr_output_effective_resolution() 

void wlr_output_effective_resolution(​struct wlr_output *output, int *width, int *height);

Computes the transformed and scaled output resolution.

struct wlr_output_event_bind 

struct wlr_output_event_bind {
	struct wlr_output *output;
	struct wl_resource *resource;
};

struct wlr_output_event_commit 

struct wlr_output_event_commit {
	struct wlr_output *output;
	struct timespec *when;
	const struct wlr_output_state *state;
};

struct wlr_output_event_damage 

struct wlr_output_event_damage {
	struct wlr_output *output;
	const pixman_region32_t *damage; // output-buffer-local coordinates
};

struct wlr_output_event_precommit 

struct wlr_output_event_precommit {
	struct wlr_output *output;
	struct timespec *when;
	const struct wlr_output_state *state;
};

struct wlr_output_event_present 

struct wlr_output_event_present {
	struct wlr_output *output;
	// Frame submission for which this presentation event is for (see
	// wlr_output.commit_seq).
	uint32_t commit_seq;
	// Whether the frame was presented at all.
	 bool presented;
	// Time when the content update turned into light the first time.
	struct timespec *when;
	// Vertical retrace counter. Zero if unavailable.
	unsigned seq;
	// Prediction of how many nanoseconds after `when` the very next output
	// refresh may occur. Zero if unknown.
	int refresh; // nsec
	uint32_t flags; // enum wlr_output_present_flag
};

struct wlr_output_event_request_state 

struct wlr_output_event_request_state {
	struct wlr_output *output;
	const struct wlr_output_state *state;
};

wlr_output_from_resource() 

struct wlr_output *wlr_output_from_resource(​struct wl_resource *resource);

Returns the wlr_output matching the provided wl_output resource. If the resource isn't a wl_output, it aborts. If the resource is inert (because the wlr_output has been destroyed), NULL is returned.

wlr_output_get_gamma_size() 

size_t wlr_output_get_gamma_size(​struct wlr_output *output);

Returns the maximum length of each gamma ramp, or 0 if unsupported.

wlr_output_get_primary_formats() 

const struct wlr_drm_format_set *wlr_output_get_primary_formats(​struct wlr_output *output, uint32_t buffer_caps);

Get the set of DRM formats suitable for the primary buffer, assuming a buffer with the specified capabilities.

NULL is returned if the backend doesn't have any format constraint, ie. all formats are supported. An empty set is returned if the backend doesn't support any format.

wlr_output_init_render() 

bool wlr_output_init_render(​struct wlr_output *output, struct wlr_allocator *allocator, struct wlr_renderer *renderer);

wlr_output_is_direct_scanout_allowed() 

bool wlr_output_is_direct_scanout_allowed(​struct wlr_output *output);

wlr_output_lock_attach_render() 

void wlr_output_lock_attach_render(​struct wlr_output *output, bool lock);

Locks the output to only use rendering instead of direct scan-out. This is useful if direct scan-out needs to be temporarily disabled (e.g. during screen capture). There must be as many unlocks as there have been locks to restore the original state. There should never be an unlock before a lock.

wlr_output_lock_software_cursors() 

void wlr_output_lock_software_cursors(​struct wlr_output *output, bool lock);

Locks the output to only use software cursors instead of hardware cursors. This is useful if hardware cursors need to be temporarily disabled (e.g. during screen capture). There must be as many unlocks as there have been locks to restore the original state. There should never be an unlock before a lock.

struct wlr_output_mode 

struct wlr_output_mode {
	int32_t width, height;
	int32_t refresh; // mHz
	bool preferred;
	enum wlr_output_mode_aspect_ratio picture_aspect_ratio;
	struct wl_list link;
};

enum wlr_output_mode_aspect_ratio 

enum wlr_output_mode_aspect_ratio {
	WLR_OUTPUT_MODE_ASPECT_RATIO_NONE,
	WLR_OUTPUT_MODE_ASPECT_RATIO_4_3,
	WLR_OUTPUT_MODE_ASPECT_RATIO_16_9,
	WLR_OUTPUT_MODE_ASPECT_RATIO_64_27,
	WLR_OUTPUT_MODE_ASPECT_RATIO_256_135,
};

wlr_output_preferred_mode() 

struct wlr_output_mode *wlr_output_preferred_mode(​struct wlr_output *output);

Returns the preferred mode for this output. If the output doesn't support modes, returns NULL.

enum wlr_output_present_flag 

enum wlr_output_present_flag {
	// The presentation was synchronized to the "vertical retrace" by the
	// display hardware such that tearing does not happen.
	WLR_OUTPUT_PRESENT_VSYNC,
	// The display hardware provided measurements that the hardware driver
	// converted into a presentation timestamp.
	WLR_OUTPUT_PRESENT_HW_CLOCK,
	// The display hardware signalled that it started using the new image
	// content.
	WLR_OUTPUT_PRESENT_HW_COMPLETION,
	// The presentation of this update was done zero-copy.
	WLR_OUTPUT_PRESENT_ZERO_COPY,
};

wlr_output_render_software_cursors() 

void wlr_output_render_software_cursors(​struct wlr_output *output, const pixman_region32_t *damage);

Renders software cursors. This is a utility function that can be called when compositors render.

wlr_output_schedule_done() 

void wlr_output_schedule_done(​struct wlr_output *output);

Schedule a done event.

This is intended to be used by wl_output add-on interfaces.

wlr_output_schedule_frame() 

void wlr_output_schedule_frame(​struct wlr_output *output);

Manually schedules a `frame` event. If a `frame` event is already pending, it is a no-op.

wlr_output_set_description() 

void wlr_output_set_description(​struct wlr_output *output, const char *desc);

wlr_output_set_name() 

void wlr_output_set_name(​struct wlr_output *output, const char *name);

Set the output name.

Output names are subject to the following rules:

- Each output name must be unique. - The name cannot change after the output has been advertised to clients.

For more details, see the protocol documentation for wl_output.name.

struct wlr_output_state 

struct wlr_output_state {
	uint32_t committed; // enum wlr_output_state_field
	// Set to true to allow output reconfiguration to occur which may result
	// in temporary output disruptions and content misrepresentations.
	 bool allow_reconfiguration;
	pixman_region32_t damage; // output-buffer-local coordinates
	bool enabled;
	float scale;
	enum wl_output_transform transform;
	bool adaptive_sync_enabled;
	uint32_t render_format;
	enum wl_output_subpixel subpixel;
	
	struct wlr_buffer *buffer;
	/* Request a tearing page-flip. When enabled, this may cause the output to
	 * display a part of the previous buffer and a part of the current buffer at
	 * the same time. The backend may reject the commit if a tearing page-flip
	 * cannot be performed, in which case the caller should fall back to a
	 * regular page-flip at the next wlr_output.frame event. */
	 bool tearing_page_flip;
	
	enum wlr_output_state_mode_type mode_type;
	struct wlr_output_mode *mode;
	struct {
		int32_t width, height;
		int32_t refresh; // mHz, may be zero
	} custom_mode;
	
	uint16_t *gamma_lut;
	size_t gamma_lut_size;
	
	struct wlr_output_layer_state *layers;
	size_t layers_len;
};

Holds the double-buffered output state.

wlr_output_state_copy() 

bool wlr_output_state_copy(​struct wlr_output_state *dst, const struct wlr_output_state *src);

enum wlr_output_state_field 

enum wlr_output_state_field {
	WLR_OUTPUT_STATE_BUFFER,
	WLR_OUTPUT_STATE_DAMAGE,
	WLR_OUTPUT_STATE_MODE,
	WLR_OUTPUT_STATE_ENABLED,
	WLR_OUTPUT_STATE_SCALE,
	WLR_OUTPUT_STATE_TRANSFORM,
	WLR_OUTPUT_STATE_ADAPTIVE_SYNC_ENABLED,
	WLR_OUTPUT_STATE_GAMMA_LUT,
	WLR_OUTPUT_STATE_RENDER_FORMAT,
	WLR_OUTPUT_STATE_SUBPIXEL,
	WLR_OUTPUT_STATE_LAYERS,
};

wlr_output_state_finish() 

void wlr_output_state_finish(​struct wlr_output_state *state);

Releases all resources associated with an output state.

wlr_output_state_init() 

void wlr_output_state_init(​struct wlr_output_state *state);

Initialize an output state.

enum wlr_output_state_mode_type 

enum wlr_output_state_mode_type {
	WLR_OUTPUT_STATE_MODE_FIXED,
	WLR_OUTPUT_STATE_MODE_CUSTOM,
};

wlr_output_state_set_adaptive_sync_enabled() 

void wlr_output_state_set_adaptive_sync_enabled(​struct wlr_output_state *state, bool enabled);

Enables or disable adaptive sync for an output (ie. variable refresh rate). Compositors can inspect `wlr_output.adaptive_sync_status` to query the effective status. Backends that don't support adaptive sync will reject the output commit.

This state will be applied once wlr_output_commit_state() is called.

wlr_output_state_set_buffer() 

void wlr_output_state_set_buffer(​struct wlr_output_state *state, struct wlr_buffer *buffer);

Sets the buffer for an output. The buffer contains the contents of the screen. If the compositor wishes to present a new frame, they must commit with a buffer.

This state will be applied once wlr_output_commit_state() is called.

wlr_output_state_set_custom_mode() 

void wlr_output_state_set_custom_mode(​struct wlr_output_state *state, int32_t width, int32_t height, int32_t refresh);

Sets a custom output mode for an output. See wlr_output_state_set_mode() for details.

When the output advertises fixed modes, custom modes are not guaranteed to work correctly, they may result in visual artifacts. If a suitable fixed mode is available, compositors should prefer it and use wlr_output_state_set_mode() instead of custom modes.

Setting `refresh` to zero lets the backend pick a preferred value. The output needs to be enabled.

This state will be applied once wlr_output_commit_state() is called.

wlr_output_state_set_damage() 

void wlr_output_state_set_damage(​struct wlr_output_state *state, const pixman_region32_t *damage);

Sets the damage region for an output. This is used as a hint to the backend and can be used to reduce power consumption or increase performance on some devices.

This should be called in along with wlr_output_state_set_buffer(). This state will be applied once wlr_output_commit_state() is called.

wlr_output_state_set_enabled() 

void wlr_output_state_set_enabled(​struct wlr_output_state *state, bool enabled);

Enables or disables an output. A disabled output is turned off and doesn't emit `frame` events.

This state will be applied once wlr_output_commit_state() is called.

wlr_output_state_set_gamma_lut() 

bool wlr_output_state_set_gamma_lut(​struct wlr_output_state *state, size_t ramp_size, const uint16_t *r, const uint16_t *g, const uint16_t *b);

wlr_output_state_set_layers() 

void wlr_output_state_set_layers(​struct wlr_output_state *state, struct wlr_output_layer_state *layers, size_t layers_len);

Set the output layers for an output. Output layers are used to try and take advantage of backend features that may reduce the amount of things that need to be composited.

The array must be kept valid by the caller until wlr_output_state_finish() and all copies of the state have been finished as well. This state will be applied once wlr_output_commit_state() is called.

wlr_output_state_set_mode() 

void wlr_output_state_set_mode(​struct wlr_output_state *state, struct wlr_output_mode *mode);

Sets the output mode of an output. An output mode will specify the resolution and refresh rate, among other things.

This state will be applied once wlr_output_commit_state() is called.

wlr_output_state_set_render_format() 

void wlr_output_state_set_render_format(​struct wlr_output_state *state, uint32_t format);

Sets the render format for an output.

The default value is DRM_FORMAT_XRGB8888.

While high bit depth render formats are necessary for a monitor to receive useful high bit data, they do not guarantee it; a DRM_FORMAT_XBGR2101010 buffer will only lead to sending 10-bpc image data to the monitor if hardware and software permit this.

This only affects the format of the output buffer used when rendering using the output's own swapchain as with wlr_output_begin_render_pass(). It has no impact on the cursor buffer format, or on the formats supported for direct scan-out (see also wlr_output_state_set_buffer()).

This state will be applied once wlr_output_commit_state() is called.

wlr_output_state_set_scale() 

void wlr_output_state_set_scale(​struct wlr_output_state *state, float scale);

Sets the scale of an output. The scale is used to increase the size of UI elements to aid users who use high DPI outputs.

This state will be applied once wlr_output_commit_state() is called.

wlr_output_state_set_subpixel() 

void wlr_output_state_set_subpixel(​struct wlr_output_state *state, enum wl_output_subpixel subpixel);

Sets the subpixel layout hint for an output. Note that this is only a hint and may be ignored. The default value depends on the backend.

This state will be applied once wlr_output_commit_state() is called.

wlr_output_state_set_transform() 

void wlr_output_state_set_transform(​struct wlr_output_state *state, enum wl_output_transform transform);

Sets the transform of an output. The transform is used to rotate or flip the contents of the screen.

This state will be applied once wlr_output_commit_state() is called.

wlr_output_test_state() 

bool wlr_output_test_state(​struct wlr_output *output, const struct wlr_output_state *state);

wlr_output_transformed_resolution() 

void wlr_output_transformed_resolution(​struct wlr_output *output, int *width, int *height);

Computes the transformed output resolution.