[PATCHv3] Add surface-layers protocol

Wed Jan 25 01:54:57 UTC 2017

Hi,

By the looks of it, this is a protocol extension that aims to enable
desktop environments to be built of interoperable components (i.e. a
"background" process to draw a (live?) wallpaper, an "overlay" thing
could be used to create a panel, popup launcher or alt-tab view or
something). Is this correct?

If so, I believe this type of protocols, and probably many others
similar to this one (there have been others passing by wayland-devel as
well), would be best suited "wayland-wall"[0] or something similar,
where modular compositor developers who want to choose what type of
modularity they want to support can pick at their discretion.

Thus, I don't think it is suitable for wayland-protocols, as I think the
focus of it should rather be an extension of Wayland proper
(wayland.xml) where client and compositor developers can look for
protocols that can be considered relatively portable. "Modular
compositor" protocols mostly cannot be portable in the same sense.

If I misunderstood the intention of the protocol, do let me know. I
didn't see any use cases spelled out, so I am just assuming.

Maybe it would make sense to link wayland-wall from
wayland.freedesktop.org as a possible path to take for "modular
compositor" developers looking for protocols for components? Are there
any other projects trying to do the same?

Jonas

[0] https://github.com/wayland-wall/wayland-wall

On Tue, Jan 24, 2017 at 07:47:30PM -0500, Drew DeVault wrote:
> 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
> 