Stable procotols¶

viewport¶

wp_viewport¶

Client Headers¶

group iface_wp_viewport

An additional interface to a wl_surface object, which allows the client to specify the cropping and scaling of the surface contents.

This interface works with two concepts: the source rectangle (src_x, src_y, src_width, src_height), and the destination size (dst_width, dst_height). The contents of the source rectangle are scaled to the destination size, and content outside the source rectangle is ignored. This state is double-buffered, and is applied on the next wl_surface.commit.

The two parts of crop and scale state are independent: the source rectangle, and the destination size. Initially both are unset, that is, no scaling is applied. The whole of the current wl_buffer is used as the source, and the surface size is as defined in wl_surface.attach.

If the destination size is set, it causes the surface size to become dst_width, dst_height. The source (rectangle) is scaled to exactly this size. This overrides whatever the attached wl_buffer size is, unless the wl_buffer is NULL. If the wl_buffer is NULL, the surface has no content and therefore no size. Otherwise, the size is always at least 1x1 in surface local coordinates.

If the source rectangle is set, it defines what area of the wl_buffer is taken as the source. If the source rectangle is set and the destination size is not set, then src_width and src_height must be integers, and the surface size becomes the source rectangle size. This results in cropping without scaling. If src_width or src_height are not integers and destination size is not set, the bad_size protocol error is raised when the surface state is applied.

The coordinate transformations from buffer pixel coordinates up to the surface-local coordinates happen in the following order:

buffer_transform (wl_surface.set_buffer_transform)
buffer_scale (wl_surface.set_buffer_scale)
crop and scale (wp_viewport.set*) This means, that the source rectangle coordinates of crop and scale are given in the coordinates after the buffer transform and scale, i.e. in the coordinates that would be the surface-local coordinates if the crop and scale was not applied.

If src_x or src_y are negative, the bad_value protocol error is raised. Otherwise, if the source rectangle is partially or completely outside of the non-NULL wl_buffer, then the out_of_buffer protocol error is raised when the surface state is applied. A NULL wl_buffer does not raise the out_of_buffer error.

The x, y arguments of wl_surface.attach are applied as normal to the surface. They indicate how many pixels to remove from the surface size from the left and the top. In other words, they are still in the surface-local coordinate system, just like dst_width and dst_height are.

If the wl_surface associated with the wp_viewport is destroyed, all wp_viewport requests except ‘destroy’ raise the protocol error no_surface.

If the wp_viewport object is destroyed, the crop and scale state is removed from the wl_surface. The change will be applied on the next wl_surface.commit.

Defines

WP_VIEWPORT_DESTROY_SINCE_VERSION¶

WP_VIEWPORT_SET_SOURCE_SINCE_VERSION¶

WP_VIEWPORT_SET_DESTINATION_SINCE_VERSION¶

Functions

static void wp_viewport_set_user_data(struct wp_viewport *wp_viewport, void *user_data)¶

static void *wp_viewport_get_user_data(struct wp_viewport *wp_viewport)¶

static void wp_viewport_destroy(struct wp_viewport *wp_viewport)¶

The associated wl_surface’s crop and scale state is removed.

The change is applied on the next wl_surface.commit.

static void wp_viewport_set_source(struct wp_viewport *wp_viewport, wl_fixed_t x, wl_fixed_t y, wl_fixed_t width, wl_fixed_t height)¶

Set the source rectangle of the associated wl_surface.

See wp_viewport for the description, and relation to the wl_buffer size.

If all of x, y, width and height are -1.0, the source rectangle is unset instead. Any other set of values where width or height are zero or negative, or x or y are negative, raise the bad_value protocol error.

The crop and scale state is double-buffered state, and will be applied on the next wl_surface.commit.

static void wp_viewport_set_destination(struct wp_viewport *wp_viewport, int32_t width, int32_t height)¶

Set the destination size of the associated wl_surface.

See wp_viewport for the description, and relation to the wl_buffer size.

If width is -1 and height is -1, the destination size is unset instead. Any other pair of values for width and height that contains zero or negative values raises the bad_value protocol error.

The crop and scale state is double-buffered state, and will be applied on the next wl_surface.commit.

Server Headers¶

group iface_wp_viewport

An additional interface to a wl_surface object, which allows the client to specify the cropping and scaling of the surface contents.

This interface works with two concepts: the source rectangle (src_x, src_y, src_width, src_height), and the destination size (dst_width, dst_height). The contents of the source rectangle are scaled to the destination size, and content outside the source rectangle is ignored. This state is double-buffered, and is applied on the next wl_surface.commit.

The two parts of crop and scale state are independent: the source rectangle, and the destination size. Initially both are unset, that is, no scaling is applied. The whole of the current wl_buffer is used as the source, and the surface size is as defined in wl_surface.attach.

If the destination size is set, it causes the surface size to become dst_width, dst_height. The source (rectangle) is scaled to exactly this size. This overrides whatever the attached wl_buffer size is, unless the wl_buffer is NULL. If the wl_buffer is NULL, the surface has no content and therefore no size. Otherwise, the size is always at least 1x1 in surface local coordinates.

If the source rectangle is set, it defines what area of the wl_buffer is taken as the source. If the source rectangle is set and the destination size is not set, then src_width and src_height must be integers, and the surface size becomes the source rectangle size. This results in cropping without scaling. If src_width or src_height are not integers and destination size is not set, the bad_size protocol error is raised when the surface state is applied.

The coordinate transformations from buffer pixel coordinates up to the surface-local coordinates happen in the following order:

buffer_transform (wl_surface.set_buffer_transform)
buffer_scale (wl_surface.set_buffer_scale)
crop and scale (wp_viewport.set*) This means, that the source rectangle coordinates of crop and scale are given in the coordinates after the buffer transform and scale, i.e. in the coordinates that would be the surface-local coordinates if the crop and scale was not applied.

If src_x or src_y are negative, the bad_value protocol error is raised. Otherwise, if the source rectangle is partially or completely outside of the non-NULL wl_buffer, then the out_of_buffer protocol error is raised when the surface state is applied. A NULL wl_buffer does not raise the out_of_buffer error.

The x, y arguments of wl_surface.attach are applied as normal to the surface. They indicate how many pixels to remove from the surface size from the left and the top. In other words, they are still in the surface-local coordinate system, just like dst_width and dst_height are.

If the wl_surface associated with the wp_viewport is destroyed, all wp_viewport requests except ‘destroy’ raise the protocol error no_surface.

If the wp_viewport object is destroyed, the crop and scale state is removed from the wl_surface. The change will be applied on the next wl_surface.commit.

Defines

WP_VIEWPORT_DESTROY_SINCE_VERSION

WP_VIEWPORT_SET_SOURCE_SINCE_VERSION

WP_VIEWPORT_SET_DESTINATION_SINCE_VERSION

struct wp_viewport_interface¶

#include <viewporter-server-protocol.h>

Public Members

void (*destroy)(struct wl_client *client, struct wl_resource *resource)¶

remove scaling and cropping from the surface

The associated wl_surface’s crop and scale state is removed. The change is applied on the next wl_surface.commit.

void (*set_source)(struct wl_client *client, struct wl_resource *resource, wl_fixed_t x, wl_fixed_t y, wl_fixed_t width, wl_fixed_t height)¶

set the source rectangle for cropping

Set the source rectangle of the associated wl_surface. See wp_viewport for the description, and relation to the wl_buffer size.

If all of x, y, width and height are -1.0, the source rectangle is unset instead. Any other set of values where width or height are zero or negative, or x or y are negative, raise the bad_value protocol error.

The crop and scale state is double-buffered state, and will be applied on the next wl_surface.commit.

Parameters

x: source rectangle x
y: source rectangle y
width: source rectangle width
height: source rectangle height

void (*set_destination)(struct wl_client *client, struct wl_resource *resource, int32_t width, int32_t height)¶

set the surface size for scaling

Set the destination size of the associated wl_surface. See wp_viewport for the description, and relation to the wl_buffer size.

If width is -1 and height is -1, the destination size is unset instead. Any other pair of values for width and height that contains zero or negative values raises the bad_value protocol error.

The crop and scale state is double-buffered state, and will be applied on the next wl_surface.commit.

Parameters

width: surface width
height: surface height

wp_viewporter¶

Client Headers¶

group iface_wp_viewporter

The global interface exposing surface cropping and scaling capabilities is used to instantiate an interface extension for a wl_surface object.

This extended interface will then allow cropping and scaling the surface contents, effectively disconnecting the direct relationship between the buffer and the surface size.

Defines

WP_VIEWPORTER_DESTROY_SINCE_VERSION¶

WP_VIEWPORTER_GET_VIEWPORT_SINCE_VERSION¶

Functions

static void wp_viewporter_set_user_data(struct wp_viewporter *wp_viewporter, void *user_data)¶

static void *wp_viewporter_get_user_data(struct wp_viewporter *wp_viewporter)¶

static void wp_viewporter_destroy(struct wp_viewporter *wp_viewporter)¶

Informs the server that the client will not be using this protocol object anymore.

This does not affect any other objects, wp_viewport objects included.

static struct wp_viewport *wp_viewporter_get_viewport(struct wp_viewporter *wp_viewporter, struct wl_surface *surface)¶

Instantiate an interface extension for the given wl_surface to crop and scale its content.

If the given wl_surface already has a wp_viewport object associated, the viewport_exists protocol error is raised.

Server Headers¶

group iface_wp_viewporter

The global interface exposing surface cropping and scaling capabilities is used to instantiate an interface extension for a wl_surface object.

This extended interface will then allow cropping and scaling the surface contents, effectively disconnecting the direct relationship between the buffer and the surface size.

Defines

WP_VIEWPORTER_DESTROY_SINCE_VERSION

WP_VIEWPORTER_GET_VIEWPORT_SINCE_VERSION

struct wp_viewporter_interface¶

#include <viewporter-server-protocol.h>

Public Members

void (*destroy)(struct wl_client *client, struct wl_resource *resource)¶

unbind from the cropping and scaling interface

Informs the server that the client will not be using this protocol object anymore. This does not affect any other objects, wp_viewport objects included.

void (*get_viewport)(struct wl_client *client, struct wl_resource *resource, uint32_t id, struct wl_resource *surface)¶

extend surface interface for crop and scale

Instantiate an interface extension for the given wl_surface to crop and scale its content. If the given wl_surface already has a wp_viewport object associated, the viewport_exists protocol error is raised.

Parameters

id: the new viewport interface id
surface: the surface

presentation-time¶

wp_presentation¶

Client Headers¶

group iface_wp_presentation

The main feature of this interface is accurate presentation timing feedback to ensure smooth video playback while maintaining audio/video synchronization.

Some features use the concept of a presentation clock, which is defined in the presentation.clock_id event.

A content update for a wl_surface is submitted by a wl_surface.commit request. Request ‘feedback’ associates with the wl_surface.commit and provides feedback on the content update, particularly the final realized presentation time.

When the final realized presentation time is available, e.g. after a framebuffer flip completes, the requested presentation_feedback.presented events are sent. The final presentation time can differ from the compositor’s predicted display update time and the update’s target time, especially when the compositor misses its target vertical blanking period.

Defines

WP_PRESENTATION_CLOCK_ID_SINCE_VERSION¶

WP_PRESENTATION_DESTROY_SINCE_VERSION¶

WP_PRESENTATION_FEEDBACK_SINCE_VERSION¶

Enums

enum wp_presentation_error¶

fatal presentation errors

These fatal protocol errors may be emitted in response to illegal presentation requests.

Values:

WP_PRESENTATION_ERROR_INVALID_TIMESTAMP = 0¶: invalid value in tv_nsec

WP_PRESENTATION_ERROR_INVALID_FLAG = 1¶: invalid flag

Functions

static int wp_presentation_add_listener(struct wp_presentation *wp_presentation, const struct wp_presentation_listener *listener, void *data)¶

static void wp_presentation_set_user_data(struct wp_presentation *wp_presentation, void *user_data)¶

static void *wp_presentation_get_user_data(struct wp_presentation *wp_presentation)¶

static void wp_presentation_destroy(struct wp_presentation *wp_presentation)¶

Informs the server that the client will no longer be using this protocol object.

Existing objects created by this object are not affected.

static struct wp_presentation_feedback *wp_presentation_feedback(struct wp_presentation *wp_presentation, struct wl_surface *surface)¶

Request presentation feedback for the current content submission on the given surface.

This creates a new presentation_feedback object, which will deliver the feedback information once. If multiple presentation_feedback objects are created for the same submission, they will all deliver the same information.

For details on what information is returned, see the presentation_feedback interface.

struct wp_presentation_listener¶

#include <presentation-time-client-protocol.h>

Public Members

void (*clock_id)(void *data, struct wp_presentation *wp_presentation, uint32_t clk_id)¶

clock ID for timestamps

This event tells the client in which clock domain the compositor interprets the timestamps used by the presentation extension. This clock is called the presentation clock.

The compositor sends this event when the client binds to the presentation interface. The presentation clock does not change during the lifetime of the client connection.

The clock identifier is platform dependent. On Linux/glibc, the identifier value is one of the clockid_t values accepted by clock_gettime(). clock_gettime() is defined by POSIX.1-2001.

Timestamps in this clock domain are expressed as tv_sec_hi, tv_sec_lo, tv_nsec triples, each component being an unsigned 32-bit value. Whole seconds are in tv_sec which is a 64-bit value combined from tv_sec_hi and tv_sec_lo, and the additional fractional part in tv_nsec as nanoseconds. Hence, for valid timestamps tv_nsec must be in [0, 999999999].

Note that clock_id applies only to the presentation clock, and implies nothing about e.g. the timestamps used in the Wayland core protocol input events.

Compositors should prefer a clock which does not jump and is not slewed e.g. by NTP. The absolute value of the clock is irrelevant. Precision of one millisecond or better is recommended. Clients must be able to query the current clock value directly, not by asking the compositor.

Parameters

clk_id: platform clock identifier

Server Headers¶

group iface_wp_presentation

The main feature of this interface is accurate presentation timing feedback to ensure smooth video playback while maintaining audio/video synchronization.

Some features use the concept of a presentation clock, which is defined in the presentation.clock_id event.

A content update for a wl_surface is submitted by a wl_surface.commit request. Request ‘feedback’ associates with the wl_surface.commit and provides feedback on the content update, particularly the final realized presentation time.

When the final realized presentation time is available, e.g. after a framebuffer flip completes, the requested presentation_feedback.presented events are sent. The final presentation time can differ from the compositor’s predicted display update time and the update’s target time, especially when the compositor misses its target vertical blanking period.

Defines

WP_PRESENTATION_CLOCK_ID_SINCE_VERSION

WP_PRESENTATION_DESTROY_SINCE_VERSION

WP_PRESENTATION_FEEDBACK_SINCE_VERSION

Enums

enum wp_presentation_error

fatal presentation errors

These fatal protocol errors may be emitted in response to illegal presentation requests.

Values:

WP_PRESENTATION_ERROR_INVALID_TIMESTAMP = 0: invalid value in tv_nsec

WP_PRESENTATION_ERROR_INVALID_FLAG = 1: invalid flag

Functions

static void wp_presentation_send_clock_id(struct wl_resource *resource_, uint32_t clk_id)¶

Sends an clock_id event to the client owning the resource.

Parameters

resource_: The client’s resource
clk_id: platform clock identifier

struct wp_presentation_interface¶

#include <presentation-time-server-protocol.h>

Public Members

void (*destroy)(struct wl_client *client, struct wl_resource *resource)¶

unbind from the presentation interface

Informs the server that the client will no longer be using this protocol object. Existing objects created by this object are not affected.

void (*feedback)(struct wl_client *client, struct wl_resource *resource, struct wl_resource *surface, uint32_t callback)¶

request presentation feedback information

Request presentation feedback for the current content submission on the given surface. This creates a new presentation_feedback object, which will deliver the feedback information once. If multiple presentation_feedback objects are created for the same submission, they will all deliver the same information.

For details on what information is returned, see the presentation_feedback interface.

Parameters

surface: target surface
callback: new feedback object

wp_presentation_feedback¶

Client Headers¶

group iface_wp_presentation_feedback

A presentation_feedback object returns an indication that a wl_surface content update has become visible to the user.

One object corresponds to one content update submission (wl_surface.commit). There are two possible outcomes: the content update is presented to the user, and a presentation timestamp delivered; or, the user did not see the content update because it was superseded or its surface destroyed, and the content update is discarded.

Once a presentation_feedback object has delivered a ‘presented’ or ‘discarded’ event it is automatically destroyed.

Defines

WP_PRESENTATION_FEEDBACK_SYNC_OUTPUT_SINCE_VERSION¶

WP_PRESENTATION_FEEDBACK_PRESENTED_SINCE_VERSION¶

WP_PRESENTATION_FEEDBACK_DISCARDED_SINCE_VERSION¶

Enums

enum wp_presentation_feedback_kind¶

bitmask of flags in presented event

These flags provide information about how the presentation of the related content update was done. The intent is to help clients assess the reliability of the feedback and the visual quality with respect to possible tearing and timings. The flags are:

VSYNC: The presentation was synchronized to the “vertical retrace” by the display hardware such that tearing does not happen. Relying on user space scheduling is not acceptable for this flag. If presentation is done by a copy to the active frontbuffer, then it must guarantee that tearing cannot happen.

HW_CLOCK: The display hardware provided measurements that the hardware driver converted into a presentation timestamp. Sampling a clock in user space is not acceptable for this flag.

HW_COMPLETION: The display hardware signalled that it started using the new image content. The opposite of this is e.g. a timer being used to guess when the display hardware has switched to the new image content.

ZERO_COPY: The presentation of this update was done zero-copy. This means the buffer from the client was given to display hardware as is, without copying it. Compositing with OpenGL counts as copying, even if textured directly from the client buffer. Possible zero-copy cases include direct scanout of a fullscreen surface and a surface on a hardware overlay.

Values:

WP_PRESENTATION_FEEDBACK_KIND_VSYNC = 0x1¶: presentation was vsync’d

WP_PRESENTATION_FEEDBACK_KIND_HW_CLOCK = 0x2¶: hardware provided the presentation timestamp

WP_PRESENTATION_FEEDBACK_KIND_HW_COMPLETION = 0x4¶: hardware signalled the start of the presentation

: presentation was done zero-copy

Functions

static int wp_presentation_feedback_add_listener(struct wp_presentation_feedback *wp_presentation_feedback, const struct wp_presentation_feedback_listener *listener, void *data)¶

static void wp_presentation_feedback_set_user_data(struct wp_presentation_feedback *wp_presentation_feedback, void *user_data)¶

static void *wp_presentation_feedback_get_user_data(struct wp_presentation_feedback *wp_presentation_feedback)¶

static void wp_presentation_feedback_destroy(struct wp_presentation_feedback *wp_presentation_feedback)¶

struct wp_presentation_feedback_listener¶

#include <presentation-time-client-protocol.h>

Public Members

void (*sync_output)(void *data, struct wp_presentation_feedback *wp_presentation_feedback, struct wl_output *output)¶

presentation synchronized to this output

As presentation can be synchronized to only one output at a time, this event tells which output it was. This event is only sent prior to the presented event.

As clients may bind to the same global wl_output multiple times, this event is sent for each bound instance that matches the synchronized output. If a client has not bound to the right wl_output global at all, this event is not sent.

Parameters

output: presentation output

void (*presented)(void *data, struct wp_presentation_feedback *wp_presentation_feedback, uint32_t tv_sec_hi, uint32_t tv_sec_lo, uint32_t tv_nsec, uint32_t refresh, uint32_t seq_hi, uint32_t seq_lo, uint32_t flags)¶

the content update was displayed

The associated content update was displayed to the user at the indicated time (tv_sec_hi/lo, tv_nsec). For the interpretation of the timestamp, see presentation.clock_id event.

The timestamp corresponds to the time when the content update turned into light the first time on the surface’s main output. Compositors may approximate this from the framebuffer flip completion events from the system, and the latency of the physical display path if known.

This event is preceded by all related sync_output events telling which output’s refresh cycle the feedback corresponds to, i.e. the main output for the surface. Compositors are recommended to choose the output containing the largest part of the wl_surface, or keeping the output they previously chose. Having a stable presentation output association helps clients predict future output refreshes (vblank).

The ‘refresh’ argument gives the compositor’s prediction of how many nanoseconds after tv_sec, tv_nsec the very next output refresh may occur. This is to further aid clients in predicting future refreshes, i.e., estimating the timestamps targeting the next few vblanks. If such prediction cannot usefully be done, the argument is zero.

If the output does not have a constant refresh rate, explicit video mode switches excluded, then the refresh argument must be zero.

The 64-bit value combined from seq_hi and seq_lo is the value of the output’s vertical retrace counter when the content update was first scanned out to the display. This value must be compatible with the definition of MSC in GLX_OML_sync_control specification. Note, that if the display path has a non-zero latency, the time instant specified by this counter may differ from the timestamp’s.

If the output does not have a concept of vertical retrace or a refresh cycle, or the output device is self-refreshing without a way to query the refresh count, then the arguments seq_hi and seq_lo must be zero.

Parameters

tv_sec_hi: high 32 bits of the seconds part of the presentation timestamp
tv_sec_lo: low 32 bits of the seconds part of the presentation timestamp
tv_nsec: nanoseconds part of the presentation timestamp
refresh: nanoseconds till next refresh
seq_hi: high 32 bits of refresh counter
seq_lo: low 32 bits of refresh counter
flags: combination of ‘kind’ values

void (*discarded)(void *data, struct wp_presentation_feedback *wp_presentation_feedback)¶

the content update was not displayed

The content update was never displayed to the user.

Server Headers¶

group iface_wp_presentation_feedback

A presentation_feedback object returns an indication that a wl_surface content update has become visible to the user.

One object corresponds to one content update submission (wl_surface.commit). There are two possible outcomes: the content update is presented to the user, and a presentation timestamp delivered; or, the user did not see the content update because it was superseded or its surface destroyed, and the content update is discarded.

Once a presentation_feedback object has delivered a ‘presented’ or ‘discarded’ event it is automatically destroyed.

Defines

WP_PRESENTATION_FEEDBACK_SYNC_OUTPUT_SINCE_VERSION

WP_PRESENTATION_FEEDBACK_PRESENTED_SINCE_VERSION

WP_PRESENTATION_FEEDBACK_DISCARDED_SINCE_VERSION

Enums

enum wp_presentation_feedback_kind

bitmask of flags in presented event

These flags provide information about how the presentation of the related content update was done. The intent is to help clients assess the reliability of the feedback and the visual quality with respect to possible tearing and timings. The flags are:

VSYNC: The presentation was synchronized to the “vertical retrace” by the display hardware such that tearing does not happen. Relying on user space scheduling is not acceptable for this flag. If presentation is done by a copy to the active frontbuffer, then it must guarantee that tearing cannot happen.

HW_CLOCK: The display hardware provided measurements that the hardware driver converted into a presentation timestamp. Sampling a clock in user space is not acceptable for this flag.

HW_COMPLETION: The display hardware signalled that it started using the new image content. The opposite of this is e.g. a timer being used to guess when the display hardware has switched to the new image content.

ZERO_COPY: The presentation of this update was done zero-copy. This means the buffer from the client was given to display hardware as is, without copying it. Compositing with OpenGL counts as copying, even if textured directly from the client buffer. Possible zero-copy cases include direct scanout of a fullscreen surface and a surface on a hardware overlay.

Values:

WP_PRESENTATION_FEEDBACK_KIND_VSYNC = 0x1: presentation was vsync’d

WP_PRESENTATION_FEEDBACK_KIND_HW_CLOCK = 0x2: hardware provided the presentation timestamp

WP_PRESENTATION_FEEDBACK_KIND_HW_COMPLETION = 0x4: hardware signalled the start of the presentation

: presentation was done zero-copy

Functions

static void wp_presentation_feedback_send_sync_output(struct wl_resource *resource_, struct wl_resource *output)¶

Sends an sync_output event to the client owning the resource.

Parameters

resource_: The client’s resource
output: presentation output

static void wp_presentation_feedback_send_presented(struct wl_resource *resource_, uint32_t tv_sec_hi, uint32_t tv_sec_lo, uint32_t tv_nsec, uint32_t refresh, uint32_t seq_hi, uint32_t seq_lo, uint32_t flags)¶

Sends an presented event to the client owning the resource.

Parameters

resource_: The client’s resource
tv_sec_hi: high 32 bits of the seconds part of the presentation timestamp
tv_sec_lo: low 32 bits of the seconds part of the presentation timestamp
tv_nsec: nanoseconds part of the presentation timestamp
refresh: nanoseconds till next refresh
seq_hi: high 32 bits of refresh counter
seq_lo: low 32 bits of refresh counter
flags: combination of ‘kind’ values

static void wp_presentation_feedback_send_discarded(struct wl_resource *resource_)¶

Sends an discarded event to the client owning the resource.

Parameters

resource_: The client’s resource

xdg-shell¶

xdg_wm_base¶

Client Headers¶

group iface_xdg_wm_base

The xdg_wm_base interface is exposed as a global object enabling clients to turn their wl_surfaces into windows in a desktop environment.

It defines the basic functionality needed for clients and the compositor to create windows that can be dragged, resized, maximized, etc, as well as creating transient windows such as popup menus.

Defines

XDG_WM_BASE_PING_SINCE_VERSION¶

XDG_WM_BASE_DESTROY_SINCE_VERSION¶

XDG_WM_BASE_CREATE_POSITIONER_SINCE_VERSION¶

XDG_WM_BASE_GET_XDG_SURFACE_SINCE_VERSION¶

XDG_WM_BASE_PONG_SINCE_VERSION¶

Functions

static int xdg_wm_base_add_listener(struct xdg_wm_base *xdg_wm_base, const struct xdg_wm_base_listener *listener, void *data)¶

static void xdg_wm_base_set_user_data(struct xdg_wm_base *xdg_wm_base, void *user_data)¶

static void *xdg_wm_base_get_user_data(struct xdg_wm_base *xdg_wm_base)¶

static void xdg_wm_base_destroy(struct xdg_wm_base *xdg_wm_base)¶

Destroy this xdg_wm_base object.

Destroying a bound xdg_wm_base object while there are surfaces still alive created by this xdg_wm_base object instance is illegal and will result in a protocol error.

static struct xdg_positioner *xdg_wm_base_create_positioner(struct xdg_wm_base *xdg_wm_base)¶

Create a positioner object.

A positioner object is used to position surfaces relative to some parent surface. See the interface description and xdg_surface.get_popup for details.

static struct xdg_surface *xdg_wm_base_get_xdg_surface(struct xdg_wm_base *xdg_wm_base, struct wl_surface *surface)¶

This creates an xdg_surface for the given surface.

While xdg_surface itself is not a role, the corresponding surface may only be assigned a role extending xdg_surface, such as xdg_toplevel or xdg_popup.

This creates an xdg_surface for the given surface. An xdg_surface is used as basis to define a role to a given surface, such as xdg_toplevel or xdg_popup. It also manages functionality shared between xdg_surface based surface roles.

See the documentation of xdg_surface for more details about what an xdg_surface is and how it is used.

static void xdg_wm_base_pong(struct xdg_wm_base *xdg_wm_base, uint32_t serial)¶

A client must respond to a ping event with a pong request or the client may be deemed unresponsive.

See xdg_wm_base.ping.

struct xdg_wm_base_listener¶

#include <xdg-shell-client-protocol.h>

Public Members

void (*ping)(void *data, struct xdg_wm_base *xdg_wm_base, uint32_t serial)¶

check if the client is alive

The ping event asks the client if it’s still alive. Pass the serial specified in the event back to the compositor by sending a “pong” request back with the specified serial. See xdg_wm_base.pong.

Compositors can use this to determine if the client is still alive. It’s unspecified what will happen if the client doesn’t respond to the ping request, or in what timeframe. Clients should try to respond in a reasonable amount of time.

A compositor is free to ping in any way it wants, but a client must always respond to any xdg_wm_base object it created.

Parameters

serial: pass this to the pong request

Server Headers¶

group iface_xdg_wm_base

The xdg_wm_base interface is exposed as a global object enabling clients to turn their wl_surfaces into windows in a desktop environment.

It defines the basic functionality needed for clients and the compositor to create windows that can be dragged, resized, maximized, etc, as well as creating transient windows such as popup menus.

Defines

XDG_WM_BASE_PING_SINCE_VERSION

XDG_WM_BASE_DESTROY_SINCE_VERSION

XDG_WM_BASE_CREATE_POSITIONER_SINCE_VERSION

XDG_WM_BASE_GET_XDG_SURFACE_SINCE_VERSION

XDG_WM_BASE_PONG_SINCE_VERSION

Functions

static void xdg_wm_base_send_ping(struct wl_resource *resource_, uint32_t serial)¶

Sends an ping event to the client owning the resource.

Parameters

resource_: The client’s resource
serial: pass this to the pong request

struct xdg_wm_base_interface¶

#include <xdg-shell-server-protocol.h>

Public Members

void (*destroy)(struct wl_client *client, struct wl_resource *resource)¶

destroy xdg_wm_base

Destroy this xdg_wm_base object.

Destroying a bound xdg_wm_base object while there are surfaces still alive created by this xdg_wm_base object instance is illegal and will result in a protocol error.

void (*create_positioner)(struct wl_client *client, struct wl_resource *resource, uint32_t id)¶

create a positioner object

Create a positioner object. A positioner object is used to position surfaces relative to some parent surface. See the interface description and xdg_surface.get_popup for details.

void (*get_xdg_surface)(struct wl_client *client, struct wl_resource *resource, uint32_t id, struct wl_resource *surface)¶

create a shell surface from a surface

This creates an xdg_surface for the given surface. While xdg_surface itself is not a role, the corresponding surface may only be assigned a role extending xdg_surface, such as xdg_toplevel or xdg_popup.

This creates an xdg_surface for the given surface. An xdg_surface is used as basis to define a role to a given surface, such as xdg_toplevel or xdg_popup. It also manages functionality shared between xdg_surface based surface roles.

See the documentation of xdg_surface for more details about what an xdg_surface is and how it is used.

void (*pong)(struct wl_client *client, struct wl_resource *resource, uint32_t serial)¶

respond to a ping event

A client must respond to a ping event with a pong request or the client may be deemed unresponsive. See xdg_wm_base.ping.

Parameters

serial: serial of the ping event

xdg_positioner¶

Client Headers¶

group iface_xdg_positioner

The xdg_positioner provides a collection of rules for the placement of a child surface relative to a parent surface.

Rules can be defined to ensure the child surface remains within the visible area’s borders, and to specify how the child surface changes its position, such as sliding along an axis, or flipping around a rectangle. These positioner-created rules are constrained by the requirement that a child surface must intersect with or be at least partially adjacent to its parent surface.

See the various requests for details about possible rules.

At the time of the request, the compositor makes a copy of the rules specified by the xdg_positioner. Thus, after the request is complete the xdg_positioner object can be destroyed or reused; further changes to the object will have no effect on previous usages.

For an xdg_positioner object to be considered complete, it must have a non-zero size set by set_size, and a non-zero anchor rectangle set by set_anchor_rect. Passing an incomplete xdg_positioner object when positioning a surface raises an error.

Defines

XDG_POSITIONER_DESTROY_SINCE_VERSION¶

XDG_POSITIONER_SET_SIZE_SINCE_VERSION¶

XDG_POSITIONER_SET_ANCHOR_RECT_SINCE_VERSION¶

XDG_POSITIONER_SET_ANCHOR_SINCE_VERSION¶

XDG_POSITIONER_SET_GRAVITY_SINCE_VERSION¶

XDG_POSITIONER_SET_CONSTRAINT_ADJUSTMENT_SINCE_VERSION¶

XDG_POSITIONER_SET_OFFSET_SINCE_VERSION¶

Enums

enum xdg_positioner_constraint_adjustment¶

vertically resize the surface

Resize the surface vertically so that it is completely unconstrained.

Values:

XDG_POSITIONER_CONSTRAINT_ADJUSTMENT_NONE = 0¶

XDG_POSITIONER_CONSTRAINT_ADJUSTMENT_SLIDE_X = 1¶

XDG_POSITIONER_CONSTRAINT_ADJUSTMENT_SLIDE_Y = 2¶

XDG_POSITIONER_CONSTRAINT_ADJUSTMENT_FLIP_X = 4¶

XDG_POSITIONER_CONSTRAINT_ADJUSTMENT_FLIP_Y = 8¶

XDG_POSITIONER_CONSTRAINT_ADJUSTMENT_RESIZE_X = 16¶

XDG_POSITIONER_CONSTRAINT_ADJUSTMENT_RESIZE_Y = 32¶

Functions

static void xdg_positioner_set_user_data(struct xdg_positioner *xdg_positioner, void *user_data)¶

static void *xdg_positioner_get_user_data(struct xdg_positioner *xdg_positioner)¶

static void xdg_positioner_destroy(struct xdg_positioner *xdg_positioner)¶: Notify the compositor that the xdg_positioner will no longer be used.

static void xdg_positioner_set_size(struct xdg_positioner *xdg_positioner, int32_t width, int32_t height)¶

Set the size of the surface that is to be positioned with the positioner object.

The size is in surface-local coordinates and corresponds to the window geometry. See xdg_surface.set_window_geometry.

If a zero or negative size is set the invalid_input error is raised.

static void xdg_positioner_set_anchor_rect(struct xdg_positioner *xdg_positioner, int32_t x, int32_t y, int32_t width, int32_t height)¶

Specify the anchor rectangle within the parent surface that the child surface will be placed relative to.

The rectangle is relative to the window geometry as defined by xdg_surface.set_window_geometry of the parent surface.

When the xdg_positioner object is used to position a child surface, the anchor rectangle may not extend outside the window geometry of the positioned child’s parent surface.

If a negative size is set the invalid_input error is raised.

static void xdg_positioner_set_anchor(struct xdg_positioner *xdg_positioner, uint32_t anchor)¶

Defines the anchor point for the anchor rectangle.

The specified anchor is used derive an anchor point that the child surface will be positioned relative to. If a corner anchor is set (e.g. ‘top_left’ or ‘bottom_right’), the anchor point will be at the specified corner; otherwise, the derived anchor point will be centered on the specified edge, or in the center of the anchor rectangle if no edge is specified.

static void xdg_positioner_set_gravity(struct xdg_positioner *xdg_positioner, uint32_t gravity)¶

Defines in what direction a surface should be positioned, relative to the anchor point of the parent surface.

If a corner gravity is specified (e.g. ‘bottom_right’ or ‘top_left’), then the child surface will be placed towards the specified gravity; otherwise, the child surface will be centered over the anchor point on any axis that had no gravity specified.

static void xdg_positioner_set_constraint_adjustment(struct xdg_positioner *xdg_positioner, uint32_t constraint_adjustment)¶

Specify how the window should be positioned if the originally intended position caused the surface to be constrained, meaning at least partially outside positioning boundaries set by the compositor.

The adjustment is set by constructing a bitmask describing the adjustment to be made when the surface is constrained on that axis.

If no bit for one axis is set, the compositor will assume that the child surface should not change its position on that axis when constrained.

If more than one bit for one axis is set, the order of how adjustments are applied is specified in the corresponding adjustment descriptions.

The default adjustment is none.

static void xdg_positioner_set_offset(struct xdg_positioner *xdg_positioner, int32_t x, int32_t y)¶

Specify the surface position offset relative to the position of the anchor on the anchor rectangle and the anchor on the surface.

For example if the anchor of the anchor rectangle is at (x, y), the surface has the gravity bottom|right, and the offset is (ox, oy), the calculated surface position will be (x + ox, y + oy). The offset position of the surface is the one used for constraint testing. See set_constraint_adjustment.

An example use case is placing a popup menu on top of a user interface element, while aligning the user interface element of the parent surface with some user interface element placed somewhere in the popup surface.

Server Headers¶

group iface_xdg_positioner

The xdg_positioner provides a collection of rules for the placement of a child surface relative to a parent surface.

Rules can be defined to ensure the child surface remains within the visible area’s borders, and to specify how the child surface changes its position, such as sliding along an axis, or flipping around a rectangle. These positioner-created rules are constrained by the requirement that a child surface must intersect with or be at least partially adjacent to its parent surface.

See the various requests for details about possible rules.

At the time of the request, the compositor makes a copy of the rules specified by the xdg_positioner. Thus, after the request is complete the xdg_positioner object can be destroyed or reused; further changes to the object will have no effect on previous usages.

For an xdg_positioner object to be considered complete, it must have a non-zero size set by set_size, and a non-zero anchor rectangle set by set_anchor_rect. Passing an incomplete xdg_positioner object when positioning a surface raises an error.

Defines

XDG_POSITIONER_DESTROY_SINCE_VERSION

XDG_POSITIONER_SET_SIZE_SINCE_VERSION

XDG_POSITIONER_SET_ANCHOR_RECT_SINCE_VERSION

XDG_POSITIONER_SET_ANCHOR_SINCE_VERSION

XDG_POSITIONER_SET_GRAVITY_SINCE_VERSION

XDG_POSITIONER_SET_CONSTRAINT_ADJUSTMENT_SINCE_VERSION

XDG_POSITIONER_SET_OFFSET_SINCE_VERSION

Enums

enum xdg_positioner_constraint_adjustment

vertically resize the surface

Resize the surface vertically so that it is completely unconstrained.

Values:

XDG_POSITIONER_CONSTRAINT_ADJUSTMENT_NONE = 0

XDG_POSITIONER_CONSTRAINT_ADJUSTMENT_SLIDE_X = 1

XDG_POSITIONER_CONSTRAINT_ADJUSTMENT_SLIDE_Y = 2

XDG_POSITIONER_CONSTRAINT_ADJUSTMENT_FLIP_X = 4

XDG_POSITIONER_CONSTRAINT_ADJUSTMENT_FLIP_Y = 8

XDG_POSITIONER_CONSTRAINT_ADJUSTMENT_RESIZE_X = 16

XDG_POSITIONER_CONSTRAINT_ADJUSTMENT_RESIZE_Y = 32

struct xdg_positioner_interface¶

#include <xdg-shell-server-protocol.h>

Public Members

void (*destroy)(struct wl_client *client, struct wl_resource *resource)¶

destroy the xdg_positioner object

Notify the compositor that the xdg_positioner will no longer be used.

void (*set_size)(struct wl_client *client, struct wl_resource *resource, int32_t width, int32_t height)¶

set the size of the to-be positioned rectangle

Set the size of the surface that is to be positioned with the positioner object. The size is in surface-local coordinates and corresponds to the window geometry. See xdg_surface.set_window_geometry.

If a zero or negative size is set the invalid_input error is raised.

Parameters

width: width of positioned rectangle
height: height of positioned rectangle

void (*set_anchor_rect)(struct wl_client *client, struct wl_resource *resource, int32_t x, int32_t y, int32_t width, int32_t height)¶

set the anchor rectangle within the parent surface

Specify the anchor rectangle within the parent surface that the child surface will be placed relative to. The rectangle is relative to the window geometry as defined by xdg_surface.set_window_geometry of the parent surface.

When the xdg_positioner object is used to position a child surface, the anchor rectangle may not extend outside the window geometry of the positioned child’s parent surface.

If a negative size is set the invalid_input error is raised.

Parameters

x: x position of anchor rectangle
y: y position of anchor rectangle
width: width of anchor rectangle
height: height of anchor rectangle

void (*set_anchor)(struct wl_client *client, struct wl_resource *resource, uint32_t anchor)¶

set anchor rectangle anchor

Defines the anchor point for the anchor rectangle. The specified anchor is used derive an anchor point that the child surface will be positioned relative to. If a corner anchor is set (e.g. ‘top_left’ or ‘bottom_right’), the anchor point will be at the specified corner; otherwise, the derived anchor point will be centered on the specified edge, or in the center of the anchor rectangle if no edge is specified.

Parameters

anchor: anchor

void (*set_gravity)(struct wl_client *client, struct wl_resource *resource, uint32_t gravity)¶

set child surface gravity

Defines in what direction a surface should be positioned, relative to the anchor point of the parent surface. If a corner gravity is specified (e.g. ‘bottom_right’ or ‘top_left’), then the child surface will be placed towards the specified gravity; otherwise, the child surface will be centered over the anchor point on any axis that had no gravity specified.

Parameters

gravity: gravity direction

void (*set_constraint_adjustment)(struct wl_client *client, struct wl_resource *resource, uint32_t constraint_adjustment)¶

set the adjustment to be done when constrained

Specify how the window should be positioned if the originally intended position caused the surface to be constrained, meaning at least partially outside positioning boundaries set by the compositor. The adjustment is set by constructing a bitmask describing the adjustment to be made when the surface is constrained on that axis.

If no bit for one axis is set, the compositor will assume that the child surface should not change its position on that axis when constrained.

If more than one bit for one axis is set, the order of how adjustments are applied is specified in the corresponding adjustment descriptions.

The default adjustment is none.

Parameters

constraint_adjustment: bit mask of constraint adjustments

void (*set_offset)(struct wl_client *client, struct wl_resource *resource, int32_t x, int32_t y)¶

set surface position offset

Specify the surface position offset relative to the position of the anchor on the anchor rectangle and the anchor on the surface. For example if the anchor of the anchor rectangle is at (x, y), the surface has the gravity bottom|right, and the offset is (ox, oy), the calculated surface position will be (x + ox, y

oy). The offset position of the surface is the one used for constraint testing. See set_constraint_adjustment.

An example use case is placing a popup menu on top of a user interface element, while aligning the user interface element of the parent surface with some user interface element placed somewhere in the popup surface.

Parameters

x: surface position x offset
y: surface position y offset

xdg_surface¶

Client Headers¶

group iface_xdg_surface

An interface that may be implemented by a wl_surface, for implementations that provide a desktop-style user interface.

It provides a base set of functionality required to construct user interface elements requiring management by the compositor, such as toplevel windows, menus, etc. The types of functionality are split into xdg_surface roles.

Creating an xdg_surface does not set the role for a wl_surface. In order to map an xdg_surface, the client must create a role-specific object using, e.g., get_toplevel, get_popup. The wl_surface for any given xdg_surface can have at most one role, and may not be assigned any role not based on xdg_surface.

A role must be assigned before any other requests are made to the xdg_surface object.

The client must call wl_surface.commit on the corresponding wl_surface for the xdg_surface state to take effect.

Creating an xdg_surface from a wl_surface which has a buffer attached or committed is a client error, and any attempts by a client to attach or manipulate a buffer prior to the first xdg_surface.configure call must also be treated as errors.

Mapping an xdg_surface-based role surface is defined as making it possible for the surface to be shown by the compositor. Note that a mapped surface is not guaranteed to be visible once it is mapped.

For an xdg_surface to be mapped by the compositor, the following conditions must be met: (1) the client has assigned an xdg_surface-based role to the surface (2) the client has set and committed the xdg_surface state and the role-dependent state to the surface (3) the client has committed a buffer to the surface

A newly-unmapped surface is considered to have met condition (1) out of the 3 required conditions for mapping a surface if its role surface has not been destroyed.

Defines

XDG_SURFACE_CONFIGURE_SINCE_VERSION¶

XDG_SURFACE_DESTROY_SINCE_VERSION¶

XDG_SURFACE_GET_TOPLEVEL_SINCE_VERSION¶

XDG_SURFACE_GET_POPUP_SINCE_VERSION¶

XDG_SURFACE_SET_WINDOW_GEOMETRY_SINCE_VERSION¶

XDG_SURFACE_ACK_CONFIGURE_SINCE_VERSION¶

Functions

static int xdg_surface_add_listener(struct xdg_surface *xdg_surface, const struct xdg_surface_listener *listener, void *data)¶

static void xdg_surface_set_user_data(struct xdg_surface *xdg_surface, void *user_data)¶

static void *xdg_surface_get_user_data(struct xdg_surface *xdg_surface)¶

static void xdg_surface_destroy(struct xdg_surface *xdg_surface)¶

Destroy the xdg_surface object.

An xdg_surface must only be destroyed after its role object has been destroyed.

static struct xdg_toplevel *xdg_surface_get_toplevel(struct xdg_surface *xdg_surface)¶

This creates an xdg_toplevel object for the given xdg_surface and gives the associated wl_surface the xdg_toplevel role.

See the documentation of xdg_toplevel for more details about what an xdg_toplevel is and how it is used.

static struct xdg_popup *xdg_surface_get_popup(struct xdg_surface *xdg_surface, struct xdg_surface *parent, struct xdg_positioner *positioner)¶

This creates an xdg_popup object for the given xdg_surface and gives the associated wl_surface the xdg_popup role.

If null is passed as a parent, a parent surface must be specified using some other protocol, before committing the initial state.

See the documentation of xdg_popup for more details about what an xdg_popup is and how it is used.

static void xdg_surface_set_window_geometry(struct xdg_surface *xdg_surface, int32_t x, int32_t y, int32_t width, int32_t height)¶

The window geometry of a surface is its “visible bounds” from the user’s perspective.

Client-side decorations often have invisible portions like drop-shadows which should be ignored for the purposes of aligning, placing and constraining windows.

The window geometry is double buffered, and will be applied at the time wl_surface.commit of the corresponding wl_surface is called.

When maintaining a position, the compositor should treat the (x, y) coordinate of the window geometry as the top left corner of the window. A client changing the (x, y) window geometry coordinate should in general not alter the position of the window.

Once the window geometry of the surface is set, it is not possible to unset it, and it will remain the same until set_window_geometry is called again, even if a new subsurface or buffer is attached.

If never set, the value is the full bounds of the surface, including any subsurfaces. This updates dynamically on every commit. This unset is meant for extremely simple clients.

The arguments are given in the surface-local coordinate space of the wl_surface associated with this xdg_surface.

The width and height must be greater than zero. Setting an invalid size will raise an error. When applied, the effective window geometry will be the set window geometry clamped to the bounding rectangle of the combined geometry of the surface of the xdg_surface and the associated subsurfaces.

static void xdg_surface_ack_configure(struct xdg_surface *xdg_surface, uint32_t serial)¶

When a configure event is received, if a client commits the surface in response to the configure event, then the client must make an ack_configure request sometime before the commit request, passing along the serial of the configure event.

For instance, for toplevel surfaces the compositor might use this information to move a surface to the top left only when the client has drawn itself for the maximized or fullscreen state.

If the client receives multiple configure events before it can respond to one, it only has to ack the last configure event.

A client is not required to commit immediately after sending an ack_configure request - it may even ack_configure several times before its next surface commit.

A client may send multiple ack_configure requests before committing, but only the last request sent before a commit indicates which configure event the client really is responding to.

struct xdg_surface_listener¶

#include <xdg-shell-client-protocol.h>

Public Members

void (*configure)(void *data, struct xdg_surface *xdg_surface, uint32_t serial)¶

suggest a surface change

The configure event marks the end of a configure sequence. A configure sequence is a set of one or more events configuring the state of the xdg_surface, including the final xdg_surface.configure event.

Where applicable, xdg_surface surface roles will during a configure sequence extend this event as a latched state sent as events before the xdg_surface.configure event. Such events should be considered to make up a set of atomically applied configuration states, where the xdg_surface.configure commits the accumulated state.

Clients should arrange their surface for the new states, and then send an ack_configure request with the serial sent in this configure event at some point before committing the new surface.

If the client receives multiple configure events before it can respond to one, it is free to discard all but the last event it received.

Parameters

serial: serial of the configure event