[RFC wayland-protocols v2] Add screensaver inhibition protocol

[Michal Suchanek]

On 25 November 2015 at 08:24, Bryce Harrington <bryce at osg.samsung.com> wrote:
> On Wed, Nov 25, 2015 at 08:09:16AM +0100, Michal Suchanek wrote:
>> Hello
>>
>> On 25 November 2015 at 07:49, Bryce Harrington <bryce at osg.samsung.com> wrote:
>> > This interface allows disabling of screensaver/screenblanking on a
>> > per-surface basis.  As long as the surface remains visible and
>> > non-occluded it blocks the screensaver, etc. from activating on the
>> > output(s) that the surface is visible on.
>> >
>> > To uninhibit, simply destroy the inhibitor object.
>> >
>> > Signed-off-by: Bryce Harrington <bryce at osg.samsung.com>
>> > ---
>> >  Makefile.am                                        |  1 +
>> >  unstable/screensaver-inhibit/README                |  4 ++
>> >  .../screensaver-inhibit-unstable-v1.xml            | 80 ++++++++++++++++++++++
>> >  3 files changed, 85 insertions(+)
>> >  create mode 100644 unstable/screensaver-inhibit/README
>> >  create mode 100644 unstable/screensaver-inhibit/screensaver-inhibit-unstable-v1.xml
>> >
>> > diff --git a/Makefile.am b/Makefile.am
>> > index f1bac16..7af18c5 100644
>> > --- a/Makefile.am
>> > +++ b/Makefile.am
>> > @@ -5,6 +5,7 @@ nobase_dist_pkgdata_DATA =                                                      \
>> >         unstable/text-input/text-input-unstable-v1.xml                          \
>> >         unstable/input-method/input-method-unstable-v1.xml                      \
>> >         unstable/xdg-shell/xdg-shell-unstable-v5.xml                            \
>> > +       unstable/screensaver-inhibit/screensaver-inhibit-unstable-v1.xml        \
>> >         $(NULL)
>> >
>> >  pkgconfigdir = $(libdir)/pkgconfig
>> > diff --git a/unstable/screensaver-inhibit/README b/unstable/screensaver-inhibit/README
>> > new file mode 100644
>> > index 0000000..396e871
>> > --- /dev/null
>> > +++ b/unstable/screensaver-inhibit/README
>> > @@ -0,0 +1,4 @@
>> > +Screensaver inhibition protocol
>> > +
>> > +Maintainers:
>> > +Bryce Harrington <bryce at osg.samsung.com>
>> > diff --git a/unstable/screensaver-inhibit/screensaver-inhibit-unstable-v1.xml b/unstable/screensaver-inhibit/screensaver-inhibit-unstable-v1.xml
>> > new file mode 100644
>> > index 0000000..4252baf
>> > --- /dev/null
>> > +++ b/unstable/screensaver-inhibit/screensaver-inhibit-unstable-v1.xml
>> > @@ -0,0 +1,80 @@
>> > +<?xml version="1.0" encoding="UTF-8"?>
>> > +<protocol name="screensaver_inhibition_unstable_v1">
>> > +
>> > +  <copyright>
>> > +    Copyright © 2015 Samsung Electronics Co., Ltd
>> > +
>> > +    Permission is hereby granted, free of charge, to any person obtaining a
>> > +    copy of this software and associated documentation files (the "Software"),
>> > +    to deal in the Software without restriction, including without limitation
>> > +    the rights to use, copy, modify, merge, publish, distribute, sublicense,
>> > +    and/or sell copies of the Software, and to permit persons to whom the
>> > +    Software is furnished to do so, subject to the following conditions:
>> > +
>> > +    The above copyright notice and this permission notice (including the next
>> > +    paragraph) shall be included in all copies or substantial portions of the
>> > +    Software.
>> > +
>> > +    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
>> > +    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
>> > +    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
>> > +    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
>> > +    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
>> > +    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
>> > +    DEALINGS IN THE SOFTWARE.
>> > +  </copyright>
>> > +
>> > +  <interface name="zwp_screensaver_inhibition_v1" version="1">
>> > +    <description summary="screensaver inhibition">
>> > +      This interface is implemented by servers whose screensaver and/or screen
>> > +      blanking are able to be disabled by a given
>> > +
>> > +      An object to establish an inhibition on the screensaver and screen
>> > +      blanking of the output that the specified surface is shown on.
>> > +
>> > +      Warning! The protocol described in this file is experimental and
>> > +      backward incompatible changes may be made. Backward compatible changes
>> > +      may be added together with the corresponding interface version bump.
>> > +      Backward incompatible changes are done by bumping the version number in
>> > +      the protocol and interface names and resetting the interface version.
>> > +      Once the protocol is to be declared stable, the 'z' prefix and the
>> > +      version number in the protocol and interface names are removed and the
>> > +      interface version number is reset.
>> > +    </description>
>> > +
>> > +    <request name="create_inhibitor">
>> > +      <description summary="create a new inhibition object">
>> > +       Create a new inhibition object associated with the given surface.
>> > +      </description>
>> > +      <arg name="id" type="new_id" interface="zwp_screensaver_inhibition_inhibit_v1"/>
>> > +      <arg name="surface" type="object" interface="wl_surface"
>> > +          summary="the surface that inhibits the screensaver"/>
>> > +    </request>
>> > +  </interface>
>> > +
>> > +  <interface name="zwp_screensaver_inhibition_inhibit_v1" version="1">
>> > +    <description summary="inhibitor context">
>> > +      An inhibitor prevents the output that the surface is visible on from
>> > +      being blanked, dimmed, locked, set to power save, or otherwise obscuring
>> > +      the screen visuals due to lack of user interaction.  Any active
>> > +      screensaver processes are also temporarily blocked from displaying.
>>
>> The compositor may at its discretion prevent other outputs from
>> blanking as well. This should be configurable by user settings and it
>> might make sense to set different behavior for different applications.
>
> Sure, but that gets into compositor specific design choices.  I'm
> thinking we don't really need to spell this out in the protocol
> definition.  The wording doesn't prevent the compositor from inhibiting
> more than the required displays if it needs to for whatever reason.

And where else would it go?

Are you writing a separate writing a separate implementation manual
for the specification?

If not then it *should* go in the specification.

Just recently people complained that the wayland specification does
not have enough explanatory text leading to wrong or useless
implementation of the specification.

Thanks

Michal