[PATCHv2] Add surface-layers protocol

[Yong Bakos]

Hi Drew,
Some nits and errors indicated inline below.
Across the board, would be nice to have summary attributes where they
are missing.


> On Jan 7, 2017, at 11:27 AM, Drew DeVault <sir at cmpwn.com> wrote:
> 
> Signed-off-by: Drew DeVault <sir at cmpwn.com>
> ---
> Changes based on the (minimal) discussion this patch has recieved -
> removes the destroy function and adds a center anchor.
> 
> 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..bdf9819
> --- /dev/null
> +++ b/unstable/surface-layers/surface-layers.xml
> @@ -0,0 +1,151 @@
> +<?xml version="1.0" encoding="UTF-8"?>
> +<!-- vim: set ts=2 sw=2 et tw=80 formatoptions+=t : -->

I don't object to the editor config here but it's not in any other protocol xml.
I recommend removing it.


> +<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.

I just noticed that this, and the linux-dmabuf-unstable protocol have different
copyright notices from the rest of the protocols Wayland source. Not sure if
this matters or not.
	

> +  </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

surface_layer role to


> +      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.

to the surface_layer type? (This last phrase is a bit cumbersome to understand.)


> +    </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">

description.



> +        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">

description.


> +        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" />

Hm, what's the use case for a layer_surface to be interactive, but only via certain
modalities and not others?


> +    </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

implementation-dependent. (Consistent with other protocol text.)


> +        ask for will be passed along to other clients, also in an implementation
> +        defined way.

implementation-dependent. (Consistent with other protocol text.)


> +
> +        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"/>
> +      <entry name="center" value="9"/>

Consider ordering these to be congruent with some similar entries in
wayland.xml and xdg-shell-unstable. (Despite this, I'm a fan of clockwise from
the top, too.)


> +    </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

implementation-dependent (Consistent with other protocol text.)

Cheers,
yong


> +        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>
> -- 
> 2.11.0
> 
> _______________________________________________
> wayland-devel mailing list
> wayland-devel at lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/wayland-devel