river-layout: create and implement protocol

Replace the current layout mechanism based on passing args to a child
process and parsing it's stdout with a new wayland protocol. This much
more robust and allows for more featureful layout generators.

Co-authored-by: Isaac Freund <ifreund@ifreund.xyz>

1 files changed, 201 insertions, 0 deletions

diff --git a/protocol/river-layout-v1.xml b/protocol/river-layout-v1.xml
new file mode 100644
index 0000000..2ddcea3
--- /dev/null
+++ b/protocol/river-layout-v1.xml
@@ -0,0 +1,201 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="river_layout_v1">
+  <copyright>
+    Copyright 2020-2021 The River Developers
+
+    Permission to use, copy, modify, and/or distribute this software for any
+    purpose with or without fee is hereby granted, provided that the above
+    copyright notice and this permission notice appear in all copies.
+
+    THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+    WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+    MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+    ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+    WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+    ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+    OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+  </copyright>
+
+  <description summary="let clients propose view positions and dimensions">
+    This protocol specifies a way for clients to propose arbitrary positions and
+    dimensions for a set of views on a specific output of a compositor through
+    the river_layout_v1 object.
+
+    This set of views is logically structured as a simple list. Views
+    in this list cannot be individually addressed, instead the order of
+    requests/events is significant.
+
+    The entire set of proposed positions and dimensions for the views in the
+    list are called a layout. Due to their list heritage, layouts are also
+    logically strictly linear; Any complex underlying data structure a client
+    may use when generating the layout is lost in transmission. This is an
+    intentional limitation.
+
+    Note that the client may need to handle multiple layout demands per
+    river_layout_v1 object simultaneously.
+
+    Warning! The protocol described in this file is currently in the testing
+    phase. Backward compatible changes may be added together with the
+    corresponding interface version bump. Backward incompatible changes can
+    only be done by creating a new major version of the extension.
+  </description>
+
+  <interface name="river_layout_manager_v1" version="1">
+    <description summary="manage river layout objects">
+      A global factory for river_layout_v1 objects.
+    </description>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy the river_layout_manager object">
+        This request indicates that the client will not use the
+        river_layout_manager object any more. Objects that have been created
+        through this instance are not affected.
+      </description>
+    </request>
+
+    <request name="get_layout">
+      <description summary="create a river_layout_v1 object">
+        This creates a new river_layout_v1 object for the given wl_output.
+
+        All layout related communication is done through this interface.
+
+        The namespace is used by the compositor to decide which river_layout_v1
+        object will receive layout demands for the output.
+
+        The namespace is required to be be unique per-output. Furthermore,
+        two separate clients may not share a namespace on separate outputs. If
+        these conditions are not upheld, the the namespace_in_use event will
+        be sent directly after creation of the river_layout_v1 object.
+      </description>
+      <arg name="id" type="new_id" interface="river_layout_v1"/>
+      <arg name="output" type="object" interface="wl_output"/>
+      <arg name="namespace" type="string" summary="namespace of the layout object"/>
+    </request>
+  </interface>
+
+  <interface name="river_layout_v1" version="1">
+    <description summary="receive and respond to layout demands">
+      This interface allows clients to receive layout demands from the
+      compositor for a specific output and subsequently propose positions and
+      dimensions of individual views.
+    </description>
+
+    <enum name="error">
+      <entry name="count_mismatch" value="0" summary="number of
+        proposed dimensions does not match number of views in layout"/>
+      <entry name="already_committed" value="1" summary="the layout demand with
+        the provided serial was already committed"/>
+    </enum>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy the river_layout_v1 object">
+        This request indicates that the client will not use the river_layout_v1
+        object any more.
+      </description>
+    </request>
+
+    <event name="namespace_in_use">
+      <description summary="the requested namespace is already in use">
+        After this event is sent, all requests aside from the destroy event
+        will be ignored by the server. If the client wishes to try again with
+        a different namespace they must create a new river_layout_v1 object.
+      </description>
+    </event>
+
+    <event name="layout_demand">
+      <description summary="the compositor requires a layout">
+        The compositor sends this event to inform the client that it requires a
+        layout for a set of views.
+
+        The usable width and height height indicate the space in which the
+        client can safely position views without interfering with desktop
+        widgets such as panels.
+
+        The serial of this event is used to identify subsequent events and
+        request as belonging to this layout demand. Beware that the client
+        might need to handle multiple layout demands at the same time.
+
+        The server will ignore responses to all but the most recent
+        layout demand. Thus, clients are only required to respond to the most
+        recent layout_demand received. If a newer layout_demand is received
+        before the client has finished responding to an old demand, the client
+        may abort work on the old demand as any further work would be wasted.
+      </description>
+      <arg name="view_count" type="uint" summary="number of views in the layout"/>
+      <arg name="usable_width" type="uint" summary="width of the usable area"/>
+      <arg name="usable_height" type="uint" summary="height of the usable area"/>
+      <arg name="tags" type="uint" summary="tags of the output, 32-bit bitfield"/>
+      <arg name="serial" type="uint" summary="serial of the layout demand"/>
+    </event>
+
+    <event name="advertise_view">
+      <description summary="make layout client aware of view">
+        This event is sent by the server as part of the layout demand with
+        matching serial. It provides additional information about one of
+        the views to be arranged.
+
+        Every view part of the layout demand is advertised exactly once,
+        in the order of the view list.
+      </description>
+      <arg name="tags" type="uint" summary="tags of the view, 32-bit bitfield"/>
+      <arg name="app_id" type="string" summary="view app-id" allow-null="true"/>
+      <arg name="serial" type="uint" summary="serial of the layout demand"/>
+    </event>
+
+    <event name="advertise_done">
+      <description summary="all views have been advertised">
+        This event is sent by the server as the last event of the layout
+        demand with matching serial, after all advertise_view events.
+      </description>
+      <arg name="serial" type="uint" summary="serial of the layout demand"/>
+    </event>
+
+    <request name="push_view_dimensions">
+      <description summary="propose dimensions of the next view">
+        This request proposes a size and position of a view in the layout demand
+        with matching serial.
+
+        Pushed view dimensions apply to the views in the same order they were
+        advertised. That is, the first push_view_dimensions request applies
+        to the first view advertised, the second to the second, and so on.
+
+        A client must propose position and dimensions for the entire set of
+        views. Proposing too many or too few view dimensions is a protocol error.
+
+        This request may be sent before the corresponding view has been
+        advertised.
+
+        The x and y coordinates are relative to the usable area of the output,
+        with (0,0) as the top left corner.
+      </description>
+      <arg name="serial" type="uint" summary="serial of layout demand"/>
+      <arg name="x" type="int" summary="x coordinate of view"/>
+      <arg name="y" type="int" summary="y coordinate of view"/>
+      <arg name="width" type="uint" summary="width of view"/>
+      <arg name="height" type="uint" summary="height of view"/>
+    </request>
+
+    <request name="commit">
+      <description summary="commit a layout">
+        This request indicates that the client is done pushing dimensions
+        and the compositor may apply the layout. This completes the layout
+        demand with matching serial, any other requests sent with the serial
+        are a protocol error.
+
+        The compositor is free to use this proposed layout however it chooses,
+        including ignoring it.
+      </description>
+      <arg name="serial" type="uint" summary="serial of layout demand"/>
+    </request>
+
+    <request name="parameters_changed">
+      <description summary="parameters of layout have changed">
+        The client may use this request to inform the compositor that one or
+        muliple of the parameters it uses to generate layouts have changed.
+
+        If the client is responsible for the current view layout, the compositor
+        may decide to send a new layout demand to update the layout.
+      </description>
+    </request>
+  </interface>
+</protocol>