Weston backend ABI

Weston_backend_ABI.md

Overview

The Weston backend ABI (Application Binary Interface) defines the internal interfaces that Weston backends must implement to integrate with the core compositor. This documentation covers the key structures, functions, and protocols used by backends.

Core Structures

struct weston_backend

The main backend structure that all backends must implement. Key fields:

• link: Used to link the backend into the compositor's list of backends
• supported_presentation_clocks: Bitfield of supported clock types (CLOCK_MONOTONIC, etc)
• will_repaint: Flag indicating if outputs will be repainted
• Function pointers:
  • shutdown: Called before compositor shutdown
  • destroy: Cleanup function
  • create_output: Creates a new output
  • repaint_begin/repaint_cancel/repaint_flush: Repaint sequence management
  • device_changed: Notification of device changes
  • can_scanout_dmabuf: Checks if a dmabuf can be scanned out directly
  • backend_type: Identifies the backend type

struct weston_head

Represents a physical display head. Backend-specific implementations extend this.

struct weston_output

Represents an output (display). Backend-specific implementations extend this.

Key Functions

Head Management

void weston_head_init(struct weston_head *head, const char *name);
void weston_head_release(struct weston_head *head);
void weston_head_set_connection_status(struct weston_head *head, bool connected);
void weston_head_set_internal(struct weston_head *head);
void weston_head_set_monitor_strings(struct weston_head *head, const char *make, const char *model, const char *serialno);
void weston_head_set_non_desktop(struct weston_head *head, bool non_desktop);
void weston_head_set_physical_size(struct weston_head *head, int32_t mm_width, int32_t mm_height);
void weston_head_set_subpixel(struct weston_head *head, enum wl_output_subpixel sp);
void weston_head_set_transform(struct weston_head *head, uint32_t transform);
void weston_head_set_supported_eotf_mask(struct weston_head *head, uint32_t eotf_mask);
void weston_head_set_supported_colorimetry_mask(struct weston_head *head, uint32_t colorimetry_mask);
void weston_head_set_supported_vrr_modes_mask(struct weston_head *head, uint32_t vrr_modes_mask);

Output Management

void weston_output_init(struct weston_output *output, struct weston_compositor *compositor, const char *name);
void weston_output_damage(struct weston_output *output);
void weston_output_release(struct weston_output *output);
void weston_output_finish_frame(struct weston_output *output, const struct timespec *stamp, uint32_t presented_flags);
void weston_output_repaint_failed(struct weston_output *output);
int weston_output_mode_set_native(struct weston_output *output, struct weston_mode *mode, int32_t scale);
struct weston_coord_global weston_coord_global_from_output_point(double x, double y, const struct weston_output *output);
void weston_region_global_to_output(pixman_region32_t *dst, struct weston_output *output, pixman_region32_t *src);
void weston_output_arm_frame_timer(struct weston_output *output, struct wl_event_source *frame_timer);
void weston_output_finish_frame_from_timer(struct weston_output *output);

Seat/Input Management

void notify_axis(struct weston_seat *seat, const struct timespec *time, struct weston_pointer_axis_event *event);
void notify_axis_source(struct weston_seat *seat, uint32_t source);
void notify_button(struct weston_seat *seat, const struct timespec *time, int32_t button, enum wl_pointer_button_state state);
void notify_key(struct weston_seat *seat, const struct timespec *time, uint32_t key, enum wl_keyboard_key_state state, enum weston_key_state_update update_state);
void notify_keyboard_focus_in(struct weston_seat *seat, struct wl_array *keys, enum weston_key_state_update update_state);
void notify_keyboard_focus_out(struct weston_seat *seat);
void notify_motion(struct weston_seat *seat, const struct timespec *time, struct weston_pointer_motion_event *event);
void notify_motion_absolute(struct weston_seat *seat, const struct timespec *time, struct weston_coord_global pos);
void notify_modifiers(struct weston_seat *seat, uint32_t serial);
void notify_pointer_frame(struct weston_seat *seat);
void notify_pointer_focus(struct weston_seat *seat, struct weston_output *output, struct weston_coord_global pos);
void clear_pointer_focus(struct weston_seat *seat);

Touch Device Management

void notify_touch_normalized(struct weston_touch_device *device, const struct timespec *time, int touch_id, const struct weston_coord_global *pos, const struct weston_point2d_device_normalized *norm, int touch_type);
void notify_touch(struct weston_touch_device *device, const struct timespec *time, int touch_id, const struct weston_coord_global *pos, int touch_type);
void notify_touch_frame(struct weston_touch_device *device);
void notify_touch_cancel(struct weston_touch_device *device);
void notify_touch_calibrator(struct weston_touch_device *device, const struct timespec *time, int32_t slot, const struct weston_point2d_device_normalized *norm, int touch_type);
void notify_touch_calibrator_cancel(struct weston_touch_device *device);
void notify_touch_calibrator_frame(struct weston_touch_device *device);

Tablet/Tool Management

void notify_tablet_added(struct weston_tablet *tablet);
void notify_tablet_tool_added(struct weston_tablet_tool *tool);
void notify_tablet_tool_proximity_in(struct weston_tablet_tool *tool, const struct timespec *time, struct weston_tablet *tablet);
void notify_tablet_tool_proximity_out(struct weston_tablet_tool *tool, const struct timespec *time);
void notify_tablet_tool_motion(struct weston_tablet_tool *tool, const struct timespec *time, struct weston_coord_global pos);
void notify_tablet_tool_pressure(struct weston_tablet_tool *tool, const struct timespec *time, uint32_t pressure);
void notify_tablet_tool_distance(struct weston_tablet_tool *tool, const struct timespec *time, uint32_t distance);
void notify_tablet_tool_tilt(struct weston_tablet_tool *tool, const struct timespec *time, int32_t tilt_x, int32_t tilt_y);
void notify_tablet_tool_button(struct weston_tablet_tool *tool, const struct timespec *time, uint32_t button, uint32_t state);
void notify_tablet_tool_up(struct weston_tablet_tool *tool, const struct timespec *time);
void notify_tablet_tool_down(struct weston_tablet_tool *tool, const struct timespec *time);
void notify_tablet_tool_frame(struct weston_tablet_tool *tool, const struct timespec *time);

Plane Management

bool weston_output_flush_damage_for_plane(struct weston_output *output, struct weston_plane *plane, pixman_region32_t *damage);
void weston_output_flush_damage_for_primary_plane(struct weston_output *output, pixman_region32_t *damage);

Implementation Requirements

Backends must:

1. Initialize all required fields in weston_backend
2. Implement all required function pointers
3. Properly manage output and head lifecycle
4. Handle input device notifications
5. Support repaint scheduling and frame callbacks
6. Manage display buffers and damage regions
7. Handle device hotplug events