[PATCHv3] Add surface-layers protocol
Drew DeVault
sir at cmpwn.com
Wed Jan 25 00:47:30 UTC 2017
Signed-off-by: Drew DeVault <sir at cmpwn.com>
---
This revision addresses much of Yong's feedback. It changes some of the
language to more closely match other protocols, fixes a few typos, and
clarifies some descriptions. I disagree with the use of a bitfield for
anchors in xdg-shell et al, but I chose to reuse that design per Yong's
suggestion, for the sake of consistency. I chose not to add many
descriptions as Yong suggested, where I felt that the nature of the
fields were self-evident.
Cheers!
unstable/surface-layers/README | 4 +
unstable/surface-layers/surface-layers.xml | 151 +++++++++++++++++++++++++++++
2 files changed, 155 insertions(+)
create mode 100644 unstable/surface-layers/README
create mode 100644 unstable/surface-layers/surface-layers.xml
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 at cmpwn.com>
diff --git a/unstable/surface-layers/surface-layers.xml b/unstable/surface-layers/surface-layers.xml
new file mode 100644
index 0000000..fe621ef
--- /dev/null
+++ b/unstable/surface-layers/surface-layers.xml
@@ -0,0 +1,151 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<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
+ wl_surfaces. Such surfaces are assigned to a "layer" of the output and
+ rendered with a defined z-depth respective to each other. They may also be
+ anchored to the edges and corners of a screen and specify input handling
+ semantics. This interface should be suitable for the implementation of
+ many desktop shell components, and a broad number of other applications
+ that interact with the desktop.
+ </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. Traditional shell surfaces
+ will typically 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>
+
+ <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-dependent. Any events from input devices you do not
+ ask for will be passed along to other clients, also in an
+ implementation-dependent 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" bitfield="true">
+ <entry name="none" value="0"
+ summary="the center of the anchor rectangle"/>
+ <entry name="top" value="1"
+ summary="the top edge of the anchor rectangle"/>
+ <entry name="bottom" value="2"
+ summary="the bottom edge of the anchor rectangle"/>
+ <entry name="left" value="4"
+ summary="the left edge of the anchor rectangle"/>
+ <entry name="right" value="8"
+ summary="the right edge of the anchor rectangle"/>
+ </enum>
+
+ <request name="set_anchor">
+ <description summary="configures the anchor point of the surface">
+ Requests that the compositor anchor the surface to the specified edges
+ and corners. 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.
+ </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-dependent - do not assume that this region will not
+ actually be occluded.
+
+ This value is only meaningful if the surface is anchored to an edge,
+ rather than a corner. 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>
--
2.11.0
More information about the wayland-devel
mailing list