[PATCHv2] Add surface-layers protocol

Submitted by Drew DeVault on Jan. 7, 2017, 7:27 p.m.

Details

Message ID 20170107192741.GA17032@homura
State Superseded
Headers show
Series "Add surface-layers protocol" ( rev: 2 ) in Wayland

Not browsing as part of any series.

Commit Message

Drew DeVault Jan. 7, 2017, 7:27 p.m.
Signed-off-by: Drew DeVault <sir@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

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

Comments

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@cmpwn.com> wrote:
> 
> Signed-off-by: Drew DeVault <sir@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@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@lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/wayland-devel
On 2017-01-20 , Yong Bakos wrote:
> Across the board, would be nice to have summary attributes where they
> are missing.

Will add those for the final patch. Omitted them where they seemed
superfluous.

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

I just copied this from another protocol, don't recall which. Could have
been an old version.

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

I should rework this anyway, this revision of the protocol doesn't have
the assumption that the size is the size of the output.

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

For example, a layer might provide the ability to bind gestures to
commands and only grab touch. A panel might want the pointer but not
need the keyboard - note that it would capture all keyboard input if it
asked for it.

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

I'm not sure that would be useful, though I'm not necessarily opposed.

--
Drew DeVault
On Fri, 20 Jan 2017 06:51:16 -0800
Yong Bakos <junk@humanoriented.com> wrote:

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

Hi,

is it really different text, or just different line wrapping?
How does it compare to Wayland source file licenses?

IIRC Weston does have some files with a different line wrapping but the
text should be identical across all files in a repository.

It's possible some files migrated before the license texts were
unified. I think it would be good to unify the remaining ones if there
are any.


Thanks,
pq
Hi Pekka,

> On Jan 23, 2017, at 12:42 AM, Pekka Paalanen <ppaalanen@gmail.com> wrote:
> 
> On Fri, 20 Jan 2017 06:51:16 -0800
> Yong Bakos <junk@humanoriented.com> wrote:
> 
>>> +<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.
> 
> Hi,
> 
> is it really different text, or just different line wrapping?
> How does it compare to Wayland source file licenses?
> 
> IIRC Weston does have some files with a different line wrapping but the
> text should be identical across all files in a repository.
> 
> It's possible some files migrated before the license texts were
> unified. I think it would be good to unify the remaining ones if there
> are any.

I'll check, standardize, and send patches.

yong


> 
> 
> Thanks,
> pq