swaywm / wlr-protocols Goto Github PK

It should be possible to change output resolution, scaling and rotation via a wayland protocol so that clients like gnome-control-center can do so without private protocol extensions. We could start simple with output transforms and scaling and refine the protocol in later revisions.

Things I'm unsure about:

• Manual positioning - this is there to support more use-cases but involves some iffy stuff (using output device physical coordinates)
• The list of defined layers
• Exclusivity - this is there to support, for example, panels that take up space on the bottom of the screen and shouldn't normally be occluded. But implementation-wise it's hairy. It may be better to make this a seperate protocol.

Once we have virtual keyboard and virtual pointer, a remote desktop (with its own dedicated output) could be implemented using a virtual output protocol.

See swaywm/wlroots#441

New protocols should go in wayland-protocols' ext namespace, which has no more inclusion requirements than this repo, but also offers reviews by non-wlroots people and allows to host all protocols in the same place.

Proposal: reject new protocols in wlr-protocols. Only accept updates for protocols not yet included in wayland-protocols.

cc @ddevault

The namespace of a surface is meant to also indicate how it should be positioned with respect to other layer-surfaces in the same layer, right? A particular example would be lockscreen and virtual-keyboard. Now I don't think this is the right way to solve the problem (why not just add a few more layers?), but if we're going to use namespaces, then we should also have a publicly accessible list of standard namespaces, so that both compositors and clients know what to use. For example, we should have namespaces for:

1. Lockscreens
2. On-screen keyboards
3. Notifications (like mako)
4. Various "widgets" like volume slidebar, brightness slidebar, etc. Perhaps also dialogues like "shutdown/restart" or "suspend/lock" also belong here.
5. Panels

Some of them are pretty trivial (like "panel" or "lockscreen"), but some aren't. Of course there might be also other use-cases which we also need to clarify.

Hello. In sway#3384 I opened a request for a way for applications to be able to detect if a user had gone idle. I got linked to KDE's wayland idle protocol, which seems like it might be good to incorporate here.

This is a proposed backward-compatible optimization to the wlr-screencopy-unstable-v1 protocol based on experience with similar interfaces in other systems:

The goal is to minimize the number of API round trips for repeated screen capture, such as for recording it to a video stream, or any other use.

In zwlr_screencopy_manager_v1:

• Add a setable property "repeatable" (defaults to false) which becomes an implicit argument to "capture_output". In the next incompatible protocol version, change "repeatable" to either an additional boolean argument to "capture_output" or a flag bit in a "flags" argument to "capture_output" (either is fine, a flags argument is more easily expandable for other future features).

In "zwlr_screencopy_frame_v1" change the following:

• In the overall description replace the last paragraph by:

A frame object may be created as repeatable by the screencopy_manager, it is permitted for a client to create more than one frame object, repeatable or not. A repeatable frame object may be more costly than a non-repeatable frame, but should be more efficient than repeatedly creating and destroying frame objects.

Once a "ready" event is received for a non-repeatable frame, the client should destroy the frame.

Once a "failed" event is received for a frame, the client should destroy the frame.

• In the flags enum, add a bit indicating that the frame object was created as repeatable.

• In the description of the "copy" request add this:

If the frame is marked as repeatable, this request can be repeated once the "ready" event has been received, as often as the client wants, each such request will return the next available composited frame, possibly (at the compositors discretion) waiting until a change occurs. If the frame is not repeatable, has already failed, or is no longer applicable to the underlying compositor state, such a repeated "copy" request will fail with the "already_used" error.

Repeated "copy" requests may specify the same wl_buffer arg value, the compositor may at its discretion consistently reject other values with the "invalid_buffer" error, clients may at their discretion adapt their behavior accordingly.

The "buffer" and "flags" events are not repeated for subsequent copy requests, reducing the continued interaction to "copy" requests and "ready" events until a "failed" event occurs or the client voluntarily makes a "destroy" request.

• In the description of the "ready" event change

After receiving this event, the client should destroy the object.

to

After receiving this event, the client should destroy the object, unless it is marked as repeatable, in which case the client may issue a fresh "copy" request

<enum name="input_devices"> does not state bitfield="true". Is this on purpose?

Run wayland-scanner on XML files to ensure they're valid.

This would perform a GPU copy instead of a CPU one. screencopy already uses wl_buffer so it shouldn't be too hard.

• Indicate which device to allocate buffers on
• Indicate the modifier
• (Future issue) How does that play with explicit sync?

xdg-output isn't enough:

• Racy
• Sometimes the buffer might come from a client, which has a different transform

We might want to send e.g. a matrix through these two protocols instead.

10:45 <jadahl> maybe we should just split up xdg_output and move parts only consumed by xwayland in a protocol maintained in xserver/hw/xwayland/
10:46 <jadahl> then we can have a logical transform that clients that care about that can use (maybe your screenshooter, but also maybe UI's for selecting where to fullscreen something)
10:47 <emersion> but a UI to select where to fullscreen doesn't acre about orientation?
10:47 <emersion> care*
10:47 <emersion> only cares about the logical position and size?
10:48 <emersion> maybe our screenshooting things should use a separate protocol instead
10:50 <jadahl> emersion: yea, maybe not. I assume your screenshooting thing provides buffers that are not transformed some how. maybe what you need is meta data of how to transform it to get the "natural" orientation instead?
10:50 <emersion> yes, exactly
10:51 <jadahl> if you have properties on the output, and screenshot separately, its racy
10:50 <emersion> we get per-output raw buffers, we want to draw them in the layout coordinate space
10:52 <jadahl> then to me it sounds like meta data sent together with the buffer might make more sense
10:52 <emersion> indeed, that might be the case
10:52 <jadahl> would make sense if you take buffers from clients too
10:53 <jadahl> because they'll have independent orientation
10:53 <emersion> what do you mean?
10:53 <emersion> "take buffers from clients"?
10:54 <jadahl> with wl_output::transform a client might pre-transform. if you hand over a buffer from such a client directly to the screenshooter, it'll have a hard time to know how to transform it to make it "natural" without orientation meta data
10:54 <emersion> ah, interesting
10:54 <jadahl> (or copy it without transforming it)
10:54 <emersion> yeah, that's true

A null output is currently defined as being the compositor chooses which output, but sometimes we want to arrange it with respect to the whole desktop instead.

First of all, this is a bit confusing. Should the exclusive zone the client sends include the margin, or does the exclusive zone the server uses include the exclusive zone the client sends + the margin? (sway is currently implemented as the latter)

I can clarify this, but before I do, why is it like this? If I am 20px tall, I'm anchored to the bottom and I want 10 px space below me and 5px above, I would imagine I'd do the following:

layer_surface.set_size(0, 20)
layer_surface.set_anchor(bottom & left & right)
layer_surface.set_margin(0, 0, 10, 0)
layer_surface.set_exclusive_zone(35)

Or, if margin was used by the compositor when calculating exclusive zone:

layer_surface.set_size(0, 20)
layer_surface.set_anchor(bottom & left & right)
layer_surface.set_margin(0, 0, 10, 5)
layer_surface.set_exclusive_zone(20)

However, I instead have to do this (which IMO makes less sense):

layer_surface.set_size(0, 20)
layer_surface.set_anchor(bottom & left & right)
layer_surface.set_margin(0, 0, 10, 0)
layer_surface.set_exclusive_zone(25)

According to a recent discussion on dri-devel, userspace should provide a way to force a full reprobe of the DRM connectors:

User opens the screen configuration tool -> usually at that point the
tool/compositor force a full reprobe, which then often triggers the
automatic reconfiguring. E.g. on one laptop I have here when I plug in
random shit projectors at conferences nothing happens, until I run
xrandr, which triggers the full reprobe, which then makes the kernel
realize something change, sending and uevent, which starts the
automatic reconfigure machinery.

This is really not great, but the kernel folks say there's no way around that.

Hello,

Currently, layer-shell has no signal to indicate that some surface has gone full-screen and will cover the panel. For simple panels, this is fine. I, however, am trying to build a DE with Wayfire, and it would be great to use layer-shell (if my users want to run my DE's components on Sway for tiling, for example). I have functionality where the super key will open the application menu, and the panel pops up temporarily over fullscreened surfaces. I also have a Super + T binding that pops up the panel for a few hundred ms to check the time or whatnot. layer-shell does not allow me in any way to know when a surface has gone fullscreen, so I cannot do any of this. If this is implemented separately from layer-shell, there needs to be some way for clients to tell the compositor that they handle fullscreen windows and shouldn't be forced below them.

It also seems fitting that layer-shell could notify the panel when a client is maximized. My panel is translucent when nothing is tiled/maximized, but should go fully opaque when something is. I'm certain this is a common usecase (Pantheon, GNOME, etc). This could go into a separate protocol if need be.

Thank you!

Why are output and layer in particular the only two properties that can't be changed after initial surface creation? In GTK Layer Shell I just recreate the surface when those properties are changed, but why is this necessary?

Similar to how wayland-protocols is an installable package, we should investigate whether or not it would be better to have this as an installable package as well.

This way people could bring it in as a dependency into their projects. The alternative is to have people copy it over which makes updates hard and subjects us to protocol drift.

Required:

• Gather feedback from wlr-protocols users to determine whether or not this is a good idea.
• Add a build system (meson or autotools) that simply installs the protocols probably in some directory in /usr/share.

Hi, as far I can tell there isn't an event for the compositor to give to the client all the previous opened toplevels info. I mean if I have a taskbar that I opened after I opened some windows, the taskbar doesn't have a way to know that they exist, right?

To fix the race:

• Add a way for the client to signal to the compositor that they're done with the buffer
• Maybe add a way for the compositor to tell the client that they're too slow

(How does that play with explicit sync?)

The idea is to use the change in modifiers information to be notified about the change in keyboard layout.
This is useful for applications like status bar to show the current keyboard layout. Please see swaywm/wlroots#1360 for more information.

XDG shell has a set_app_id request:

Set an application identifier for the surface.

The app ID identifies the general class of applications to which
the surface belongs. The compositor can use this to group multiple
surfaces together, or to determine how to launch a new application.

For D-Bus activatable applications, the app ID is used as the D-Bus
service name.

The compositor shell will try to group application surfaces together
by their app ID. As a best practice, it is suggested to select app
ID's that match the basename of the application's .desktop file.
For example, "org.freedesktop.FooViewer" where the .desktop file is
"org.freedesktop.FooViewer.desktop".

See the desktop-entry specification [0] for more details on
application identifiers and how they relate to well-known D-Bus
names and .desktop files.

[0] http://standards.freedesktop.org/desktop-entry-spec/

Is there any reason Layer surfaces shouldn't also have this request? Could this replace the somewhat confusing namespace argument in the constructor?

When plugging out an output, this sequence of events can happen (and happens in practice, see emersion/kanshi#55):

1. Compositor sends zwlr_output_head_v1.finished and destroys the object immediately. Compositor also sends a zwlr_output_manager_v1.done event with a fresh serial to apply the changes.
2. Client hasn't received the events yet. It creates a new zwlr_output_configuration_v1 with an (outdated) serial. It issues a zwlr_output_configuration_v1.enable_head request with the object that has just been destroyed by the compositor.
3. Compositor receives the request and libwayland disconnects the client with wl_display@1: error 1: invalid arguments for [email protected]_head.

This is a race in the protocol itself. The only thing I can think of to fix it is to stop destroying immediately the zwlr_output_head_v1 objects. Instead, let the client issue a destroy request.

It's not clear what the distinction between surfaces anchored to a single edge and 3 edges.

The statements seem to specify them as separate cases sometimes (configure):

If the client picks a smaller size and
is anchored to two opposite anchors (e.g. 'top' and 'bottom'), the
surface will be centered on this axis.

Sometimes they are the same (set_anchor):

If two orthoginal edges are specified (e.g. 'top' and
'left'), then the anchor point will be the intersection of the edges
(e.g. the top left corner of the output); otherwise the anchor point
will be centered on that edge, or in the center if none is specified.

There is no indication how the values for the configure event should be derived, possibly leading to some confusion between "area reserved by the compositor" and "total available area" when it comes to positioning.

Below appears to affect all wayland compositors / environments (and X),
respectively any panel / dock that has the ability to pin an
application for quick
launching when all it's surfaces are closed.

wayland api provides the appId / title (IIRC this is the xdg-shell protocol)
X api provides the appId / title / icon
custom wayland wlroots protocol wlr-foreign-toplevel-management
provides the same

The implementation of all desktops environments face the following problem,
they need to match the appId to a desktop file to create a launcher,
which is done by looking up in all the directories $XDG_DATA_DIRS
until a desktop file matching the appId is found.

This is completely broken by design, especially in the times of
flatpak and snap.
As an example take $application, it can be installed

1. from system package - desktop file goes into /usr/share/applications/
2. from local build - desktop file goes into
   /usr/local/share/applications/
3. from flatpak(system wide) - desktop file goes into
   /var/lib/flatpak/share/applications/
4. from flatpak(user wide) - desktop file goes into
   $HOME/.local/share/applications/
5. from flatpak(custom loc) - desktop file goes into $custom
6. from snap - desktop file goes into snap directory

All of the above are exposed as $XDG_DATA_DIRS whatever application you pin
depends on the priority the lookup is done, very often it will not pin
the application it should!

A solution is to provide the PID and than being able to find the binary.
Consider adding the PID to wlr-foreign-toplevels

Below appears to affect all wayland compositors / environments (and X),
respectively any panel / dock that has the ability to pin an
application for quick
launching when all it's surfaces are closed.

wayland api provides the appId / title (IIRC this is the xdg-shell protocol)
X api provides the appId / title / icon
custom wayland wlroots protocol wlr-foreign-toplevel-management
provides the same

The implementation of all desktops environments face the following problem,
they need to match the appId to a desktop file to create a launcher,
which is done by looking up in all the directories $XDG_DATA_DIRS
until a desktop file matching the appId is found.

This is completely broken by design, especially in the times of
flatpak and snap.
As an example take $application, it can be installed

from system package - desktop file goes into /usr/share/applications/
from local build - desktop file goes into
/usr/local/share/applications/
from flatpak(system wide) - desktop file goes into
/var/lib/flatpak/share/applications/
from flatpak(user wide) - desktop file goes into
$HOME/.local/share/applications/
from flatpak(custom loc) - desktop file goes into $custom
from snap - desktop file goes into snap directory
All of the above are exposed as $XDG_DATA_DIRS whatever application you pin
depends on the priority the lookup is done, very often it will not pin
the application it should!

A solution is to provide the PID and than being able to find the binary,
which was suggested by the mailing thread to wayland-devel

appId title / Iconic dock launchers

Consider adding the PID to wlr-foreign-toplevels

These would be useful for utilities matching make/model/serial against a configuration file, to recognize a screen even if it doesn't use the same connector. These would be optional (not all backends support it) and not intended to be displayed to the user (see "description").

Right now if a client tries to copy a buffer with invalid params, a protocol error is sent.

This makes it mandatory for the client to wait for the buffer event containing the buffer params prior to sending the copy request. If invalid buffer params caused a failed event, a client could only wait for buffer params on the first frame and then re-use the previous params (retrying on failure if the buffer params changed). This would avoid one roundtrip per frame.

This would not be a breaking change.

The current keyboard_interactivity allows clients to only notify the compositor they want exclusive keyboard access. It would make much more sense to allow clients to specify they want one of the following:

1. No keyboard interaction - backgrounds, some docks, etc
2. keyboard-focus-on-click - such could be panels that have a search field or that can be navigated with they keyboard, but don't want to lock focus to their layer
3. exclusive keyboard focus - like the current 1 value - can be used for ex. by lockscreens

Note that adding this doesn't have to break existing clients - the protocol currently says what happens when the value is 1 (and afaik it is implicitly understood the only other reasonable value is 0). We can just specify what happens when the value is 2 (focus-on-click)

Let's say we have a stable layer shell protocol. wayland-scanner would export symbols like wlr_layer_shell. However we'd like to use this name for the wlroots implementation too.

Wayland uses a different prefix to address this issue: wp_ (instead of wl_). Maybe we should consider switching to something like wlrp_.

No rush though, we're nowhere near standardizing stable protocols and wayland-protocols is changing.

Hi!

This repository is linked from the sway homepage yet it only contains a raw XML document which, while actually readable, is not exactly user-friendly. Is there a (HTML?) rendered version of the document somewhere that could be a little more readable?

or am I misunderstanding the point of this repository? :)

unstable/wlr-output-management-unstable-v1.xml

      <arg name="refresh" type="int" summary="vertical refresh rate in mHz"/>
...
      <arg name="refresh" type="int" summary="vertical refresh rate in mHz or zero"/>

s/mHz/MHz/ ?

unstable/wlr-output-power-management-unstable-v1.xml

      <entry name="invalid_mode" value="1" summary="inexistent power save mode"/>

s/inexistent/nonexistent/ ?

Hey,

I'm currently a bit unsure about which layer should be used for the different programs I'm using.
I'm using sway with waybar and bemenu. For waybar, there is a pull request to use the layer shell protocol for proper popup placing. Now I'm in the following situation: bemenu uses top as a layer (hardcoded). To make sure bemenu displays over waybar, I have to set the waybar layer to bottom. But the popups opened by waybar (for example when hovering over an item such as CPU) also open at that layer therefore showing beneath the windows.
I could now go ahead and just change the code of bemenu to use overlay as a layer and then set waybars layer to top but first, I wanted to hear whether there's some recommended way of handling this situation.

Thanks in advance and have a nice day :)

The gamma-control protocol could have an improved precision, e.g. with a 3D LUT. We'll most likely want to wait for color management and HDR to settle down before doing anything, though.

Nearly every window manager has a concept of a "virtual desktop" in their operation.

i3 has the concept of "workspaces" and Awesome has "tags" which are nearly identical concepts. Each output has a currently active workspace that has its own set of visible windows, and inactive workspaces that are hidden. Many workspaces can exist on an output and each output has its own set of workspaces. Outputs can switch workspaces independently of each other.

Xfce and Gnome have "virtual desktops". There is a single set of virtual desktops for the whole screen. This nomenclature comes from the _NET_DESKTOP_* EWMH root window properties and client requests.

I would like to support both paradigms if possible.

The goal of this protocol is to support out of process bars that can be run on any window manager. This was never possible on X11 because EWMH only supported the "virtual desktop" paradigm.

Required of the protocol:

List all of the workspaces for each output.

This is to display the workspaces on the bar and their active status.

A way to request a change in the active workspace or a create a new workspace

A bar might request this when the user interacts with the bar like clicking a button. The compositor should be able to deny the request.

Workspaces on multiple outputs at once

This is to support the traditional virtual desktop paradigm. This might require desktop status to be double buffered to support changing workspaces on several outputs at once.

The first target compositors are sway and way-cooler.

Let me know if you have concerns. If you like the idea, I'll write some XML.

Locations respect to xdg-output, and the protocol should assume a surface could be rendered in several places.

Breaking change. See https://gitlab.freedesktop.org/wayland/wayland-protocols/commit/048102f21ad3783f64c4996704b07a13a010fd19

While at it, also make it optional for symmetry with xdg-output.

The governance model for wayland-protcols has been established. We should start moving our stuff into wayland-protocols accordingly.

The wrl-foreign-toplevel protocol does not give panel clients a PID, so it is really just a guess based on the app-id to decide if a window comes from a given application or not. The problem with this is that applications don't do the right thing™ and send really odd things.

For example: LibreOffice's paste dialog does not have the same app-id as the LibreOffice window itself (Writer's id: org.libreoffice, paste dialog id: soffice). They should, however, have the same PID, and my panel should be able to notice this and group them under one icon.

Our clipboard manager (klipper) works as follows:

• On a new clipboard, we copy any text
• If the clipboard becomes empty (typically because a client died), we paste our previously copied text
• A user can also explicitly select an item from the history

We had this on X, and I've retrofitted wlr_data_control into it.

I've implemented wlr_data_control and all of wl-copy, wl-paste work perfectly, to some extent klipper works, but there's a race I can't fix neatly, which I think would happen for all other clipboard managers trying to do the same thing.

My race is:

first copy:

• firefox creates a wl_data_offer
• kwin sees it forwards it klipper which copies the text...
  (all good so far)

second copy:

• firefox deletes its old wl_data_offer before creating a new one (unlike other toolkits, but still a valid thing to do)

• kwin forwards this update to klipper

• klipper knows the clipboard is empty and starts its operation to prevent an empty clipboard

• firefox creates a new wl_data_offer and calls set_selection

• klipper creates a new wlr_data_offer (with the old clipboard text) and calls set_selection

The compositor gets these in any order, and we end up replacing our new clipboard content with out-of-date previous clipboard contents.

Ultimately to prevent a race I think we need an additional fence like:

    <event name="selection">
        <arg name="id" type="object" interface="zwlr_data_control_offer_v1" allow_null=true>
         An integer value that increases, like the xdg_shell configure events
        <arg name="serial" type="int">
    </event>
    
    <request name="set_selection">
          <arg name="source" type="object" interface="zwlr_data_control_source_v1"
        allow-null="true"/>
        Optional serial which matches the clipboard event we're responding to. If this is out-of-date this selection will be immediately cancelled and ignored. If negative, we always apply the new selection.
        <arg name="serial" type="int"> 
    </request>

We're building a protocol for DMA-BUF exporting (#11). In case it's not possible to use it (because the backend doesn't support it, eg. Wayland/X11/headless), we need a fallback which involves copying to a client buffer. Currently this is done with an old version of the Orbital screenshooter protocol. However, this doesn't let the client request to capture other clients or regions. Also the buffer setup is a little hacky because it requires the client to guess the buffer settings from the output mode. The protocol doesn't let us add flags (like "inverted_y") that would speed up the copy operation.

Since the outdated protocol doesn't seem to be used by anyone except wlroots, I'd like to improve it and improve the integration with the DMA-BUF export protocol to make automatic fallback easier.

Prior art:

• Orbital: https://github.com/giucam/orbital/blob/master/protocol/screenshooter.xml
• KDE (it's closer to our DMA-BUF export interface, but with GBM FDs): https://github.com/KDE/kwayland/blob/master/src/client/protocols/remote-access.xml

See #43 (comment)

We have a virtual keyboard protocol, but we're missing a virtual pointer one. Could be useful for remote control and remote desktop.

Since #38 doesn't deal with output DPMS it would be good to be able to toggle an output's power save mode via a wayland protocol. I have put together a prototype in phoc/phosh to see how things go:

https://source.puri.sm/Librem5/phoc/merge_requests/60/diffs#808a606abe792c793cb5ed64b63f99d6dcb86a60_77_82

If it makes sense I'd like to turn it into a wlr-output-dpms so phosh can continue to run with other compositors and other shell's/daemons don't need to grow custom protocol. In this case should we still call it DPMS? Modern drm mostly treats it as legacy and does on/off only. However keeping different states gives the compositor more room like e.g. only turning off the backlight on standby and fully turning off the display pipeline on off. This is something e.g. needed on a phone since the time to bring back the display pipeline from off is too long when the user expects a quick unblank.

Eventually this could be extended to support simulating other input devices, but the only use-cases I can think of are just keyboard-based. If there are good uses cases for simulating pointer input, it might be difficult to do given how wayland handles pointers.

The wl_touch_listener events are passed a touch id originating from libinput. This is used to delineate between multiple touch events on the same device.
The negative value (i.e. -1) originates from a call to libinput_event_touch_get_slot which returns -1 when the touch device is a single touch device. This confuses a particular wayland client that I run (cog) but it is unclear whether a negative id is in fact allowed or not according to the protocol.
Weston uses a different call libinput_event_touch_get_seat_slot which is always a non-negative number, but it is per seat. Should wlroots perhaps also use libinput_event_touch_get_seat_slot?

Add an optional hint for the output the virtual pointer could be mapped to.

gtk apps have a way to request to be presented to the user (https://github.com/GNOME/gtk/blob/mainline/gdk/wayland/protocol/gtk-shell.xml#L46) which allows e.g. for 'one instance' applications if launched a second time to be brought to foreground on second launch. This e.g happens when an application is already running and a mail client spawns gnumeric foo.odt.

I looked around in xdg_* and did not see anything matching, should we add something like that to wlr-*, should that be a separate protocol? I'm happy to cook up something but don't want to duplicate things.