Add surface-layers protocol

Submitted by Drew DeVault on Jan. 2, 2017, 2:09 a.m.

Details

Message ID 20170102020944.GA10304@homura
State Superseded
Headers show
Series "Add surface-layers protocol" ( rev: 1 ) in Wayland

Not browsing as part of any series.

Commit Message

Drew DeVault Jan. 2, 2017, 2:09 a.m.
Signed-off-by: Drew DeVault <sir@cmpwn.com>
---
This patch introduces the concept of surface layers, which are used to
make desktop shell components. This should be suitable for your own
desktop shells, but also leaves the option for the user to bring along
their own shell components. Note that this leaves aside the issue of
authenticating clients that are permitted to use this protocol.

This protocol should be able to handle all sorts of use-cases, including:

- Wallpapers
- Desktop icons
- Panels/bars
- Screen lockers
- On screen keyboard (not including injecting input events)
- Notifications
- dmenu/rofi style stuff
- slop style stuff (interactive screen region selection)

And I'm sure there are quite a few more.

 unstable/surface-layers/README             |   4 +
 unstable/surface-layers/surface-layers.xml | 157 +++++++++++++++++++++++++++++
 2 files changed, 161 insertions(+)
 create mode 100644 unstable/surface-layers/README
 create mode 100644 unstable/surface-layers/surface-layers.xml

Patch hide | download patch | download mbox

diff --git a/unstable/surface-layers/README b/unstable/surface-layers/README
new file mode 100644
index 0000000..662f488
--- /dev/null
+++ b/unstable/surface-layers/README
@@ -0,0 +1,4 @@ 
+Surface layers protocol
+
+Maintainers:
+Drew DeVault <sir@cmpwn.com>
diff --git a/unstable/surface-layers/surface-layers.xml b/unstable/surface-layers/surface-layers.xml
new file mode 100644
index 0000000..d4338dd
--- /dev/null
+++ b/unstable/surface-layers/surface-layers.xml
@@ -0,0 +1,157 @@ 
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- vim: set ts=2 sw=2 et tw=80 formatoptions+=t : -->
+<protocol name="surface_layers">
+
+  <copyright>
+    Copyright © 2017 Drew DeVault
+
+    Permission to use, copy, modify, distribute, and sell this
+    software and its documentation for any purpose is hereby granted
+    without fee, provided that the above copyright notice appear in
+    all copies and that both that copyright notice and this permission
+    notice appear in supporting documentation, and that the name of
+    the copyright holders not be used in advertising or publicity
+    pertaining to distribution of the software without specific,
+    written prior permission.  The copyright holders make no
+    representations about the suitability of this software for any
+    purpose.  It is provided "as is" without express or implied
+    warranty.
+
+    THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS
+    SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+    FITNESS, IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY
+    SPECIAL, 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>
+
+  <interface name="surface_layers" version="1">
+    <description summary="create surfaces that are layers of the desktop">
+      Clients can use this interface to assign the surface_layer role to a
+      wl_surfaces. These surfaces are assigned a size by the compositor
+      (generally understood to be the size of the output) and are rendered with
+      a z-depth that corresponds to the layer they are among.
+    </description>
+
+    <enum name="surface_layer">
+      <description summary="available layers for surfaces">
+        These values indicate which layers a surface can be rendered in. They
+        are ordered by z depth, bottom-most first. Typically shell surfaces will
+        be rendered between the bottom and top layers. Multiple surfaces can
+        share a single layer.
+      </description>
+
+      <entry name="background" value="0"/>
+      <entry name="bottom" value="1"/>
+      <entry name="top" value="2"/>
+      <entry name="overlay" value="3"/>
+    </enum>
+
+    <request name="get_layer_surface">
+      <descripton summary="create a layer_surface from a surface">
+        Create a layer surface for an existing surface. This assigns the role of
+        layer_surface, or raises a protocol error if another role is already
+        assigned.
+      </description>
+      <arg name="id" type="new_id" interface="layer_surface"/>
+      <arg name="surface" type="object" interface="wl_surface"/>
+      <arg name="output" type="object" interface="wl_output"/>
+      <arg name="layer" type="uint" summary="surface_layer to add this surface to"/>
+    </request>
+  </interface>
+
+  <interface name="layer_surface" version="1">
+    <description summary="layer metadata interface">
+      An interface that may be implemented by a wl_surface, for surfaces that
+      are designed to be rendered as a layer of a stacked desktop-like
+      environment.
+    </description>
+
+    <request name="destroy" type="destructor">
+      <description summary="remove xdg_surface interface">
+        The layer_surface interface is removed from the wl_surface object and
+        the surface loses the layer_surface role.
+      </description>
+    </request>
+
+    <enum name="input_devices">
+      <descripton summary="types of input devices">
+        These flags are a bitfield and are used by set_interactive to specify
+        what sorts of input the surface should interact with.
+      </description>
+      <arg name="none" value="0x0" />
+      <arg name="pointer" value="0x1" />
+      <arg name="keyboard" value="0x2" />
+      <arg name="touch" value="0x4" />
+    </enum>
+
+    <request name="set_interactivity">
+      <description summary="indicates that this surface is interactive">
+        This request indicates to the compositor what kind of interactivity this
+        surface requires. This may be changed at runtime. Note that whether or
+        not the compositor chooses to send the surface input events at any given
+        time is implementation defined. Any events from input devices you do not
+        ask for will be passed along to other clients, also in an implementation
+        defined way.
+
+        By convention, conventional compositors will send input events to
+        surfaces below the shell surface layer when there are no shell surfaces
+        or when the surface is clicked (and thus receives focus). Above the
+        shell surface layer, the topmost surface receives all input of the types
+        it requests.
+      </description>
+      <arg name="types" type="uint" summary="mask of input devices to use"/>
+    </request>
+
+    <enum name="anchor">
+      <description summary="corners to anchor surfaces to">
+        Specifies the corners and edges of an output that you may anchor the
+        surface to.
+      </description>
+
+      <entry name="top_left" value="1"/>
+      <entry name="top" value="2"/>
+      <entry name="top_right" value="3"/>
+      <entry name="right" value="4"/>
+      <entry name="bottom_right" value="5"/>
+      <entry name="bottom" value="6"/>
+      <entry name="bottom_left" value="7"/>
+      <entry name="left" value="8"/>
+    </enum>
+
+    <request name="set_anchor">
+      <description summary="configures the anchor point of the surface">
+        Requests that the compositor anchor the surface to the specified corner
+        or edge. If your surface is not exclusive, it will be positioned with
+        respect to other exclusive surfaces (that is, it won't occlude them).
+      </description>
+      <arg name="anchor" type="uint"/>
+    </request>
+
+    <request name="set_exclusive_zone">
+      <description summary="configures the exclusive geometry of this surface">
+        Requests that the compositor avoids occluding an area of the surface
+        with other surfaces. The compositor's use of this information is
+        implementation defined - do not assume that this region will not
+        actually be occluded.
+
+        This value is only meaningful if the surface is anchored to an edge. The
+        zone is the number of pixels from the edge that are considered
+        exclusive.
+      </description>
+      <arg name="zone" type="uint"/>
+    </request>
+
+    <request name="set_margin">
+      <description summary="sets a margin from the anchor point">
+        Requests that the surface be placed some distance away from the anchor
+        point on the output, in pixels.
+      </description>
+      <arg name="horizontal" type="uint"/>
+      <arg name="vertical" type="uint"/>
+    </request>
+  </interface>
+
+</protocol>