[wayland-protocols,01/13] Add stereoscopy protocol

Submitted by Emmanuel Gil Peyrot on Nov. 14, 2017, 3:05 p.m.

Details

Message ID 20171114150600.1763-2-linkmauve@linkmauve.fr
State New
Headers show
Series "Add stereoscopy support" ( rev: 1 ) in Wayland

Not browsing as part of any series.

Commit Message

Emmanuel Gil Peyrot Nov. 14, 2017, 3:05 p.m.
From: Emmanuel Gil Peyrot <emmanuel.peyrot@collabora.com>

This protocols allows clients to describe the stereoscopic layout of
their surfaces, to make the compositor render all sides on 3DTVs or
HMDs.

It also gives a way for the compositor to describe the native stereo
layout of the current mode, so that clients can adapt their buffers to
do direct scanout.

Signed-off-by: Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
---
 Makefile.am                                      |   1 +
 unstable/stereoscopy/README                      |   4 +
 unstable/stereoscopy/stereoscopy-unstable-v1.xml | 187 +++++++++++++++++++++++
 3 files changed, 192 insertions(+)
 create mode 100644 unstable/stereoscopy/README
 create mode 100644 unstable/stereoscopy/stereoscopy-unstable-v1.xml

Patch hide | download patch | download mbox

diff --git a/Makefile.am b/Makefile.am
index 0296d5d..93cca5a 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -16,6 +16,7 @@  unstable_protocols =								\
 	unstable/xwayland-keyboard-grab/xwayland-keyboard-grab-unstable-v1.xml	\
 	unstable/keyboard-shortcuts-inhibit/keyboard-shortcuts-inhibit-unstable-v1.xml \
 	unstable/xdg-output/xdg-output-unstable-v1.xml				\
+	unstable/stereoscopy/stereoscopy-unstable-v1.xml			\
 	$(NULL)
 
 stable_protocols =								\
diff --git a/unstable/stereoscopy/README b/unstable/stereoscopy/README
new file mode 100644
index 0000000..f092267
--- /dev/null
+++ b/unstable/stereoscopy/README
@@ -0,0 +1,4 @@ 
+Stereoscopy protocol
+
+Maintainers:
+Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
diff --git a/unstable/stereoscopy/stereoscopy-unstable-v1.xml b/unstable/stereoscopy/stereoscopy-unstable-v1.xml
new file mode 100644
index 0000000..8e7db23
--- /dev/null
+++ b/unstable/stereoscopy/stereoscopy-unstable-v1.xml
@@ -0,0 +1,187 @@ 
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="stereoscopy_unstable_v1">
+
+  <copyright>
+    Copyright © 2016-2017 Emmanuel Gil Peyrot
+    Copyright © 2017 Collabora, 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_stereoscopy_v1" version="1">
+    <description summary="factory for creating stereoscopy descriptors">
+      This interface exposes outputs’ ability to display an image for
+      both eyes to the client.  Displays can accept different kind of
+      layouts, which can be different per mode, and are sent with the
+      'layout' event.  The client then calls the 'create_description'
+      request and selects the layout they prefer.  This layout isn’t
+      required to be supported by the output the surface is on, but
+      otherwise the compositor will have to convert it, which is
+      possibly lossy depending on the source and destination layouts.
+
+      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="destroy" type="destructor">
+      <description summary="unbind this factory">
+        Informs the server that the client will not be using this
+        protocol object anymore.  Objects created through this
+        interface will remain valid.
+      </description>
+    </request>
+
+    <enum name="error">
+      <description summary="fatal errors">
+        These fatal protocol errors may be emitted in response to
+        illegal stereoscopy requests.
+      </description>
+      <entry name="stereoscopy_description_exists" value="0"
+             summary="the surface already has a stereoscopy description object associated"/>
+    </enum>
+
+    <enum name="layout">
+      <description summary="list of possible stereoscopy layouts">
+        This enum describes the list of possible stereoscopy layouts.
+
+	It is loosely based on the DRM flags from the Linux kernel.
+      </description>
+      <entry name="none" value="0"
+             summary="default one, single image"/>
+      <entry name="frame_packing" value="1"
+             summary="two full images separated by 1/24th of one height"/>
+      <entry name="top_and_bottom" value="2"
+             summary="two half-height images, top-bottom, in a same buffer"/>
+      <entry name="side_by_side" value="3"
+             summary="two half-width images, side-by-side, in a same buffer"/>
+      <!-- TODO: Add support for the rest (all of them?) of the formats specified in xf86drmMode.h. -->
+      <!--<entry name="twice_as_many_dmabuf" value="4"
+             summary="TODO: is this the right place for that?  How does a client attach more than one wl_buffer anyway?"/>-->
+    </enum>
+
+    <request name="create_description">
+      <description summary="extend surface interface for stereoscopy">
+        Instantiate an interface extension for the given wl_surface to
+        specify its stereoscopic layout.  If the given wl_surface
+        already has a zwp_stereoscopy_layout_v1 object associated, the
+        stereoscopy_description_exists protocol error is raised.
+      </description>
+      <arg name="surface" type="object" interface="wl_surface"
+           summary="surface for which to create a stereoscopy description"/>
+      <arg name="stereoscopy_description_id" type="new_id"
+           interface="zwp_stereoscopy_description_v1"
+           summary="the new stereoscopy_description object"/>
+    </request>
+
+    <event name="layout">
+      <description summary="supported stereoscopic layout">
+        This event advertises one stereoscopic layout the output
+        supports.  All the supported layouts are advertised once when
+        the client binds to this interface.  A roundtrip after binding
+        guarantees that the client has received all supported formats.
+      </description>
+
+      <arg name="output" type="object" interface="wl_output"
+           summary="the output supporting this specific stereoscopy layout"/>
+      <arg name="layout" type="uint" enum="layout"
+           summary="a layout supported by this output"/>
+    </event>
+  </interface>
+
+  <interface name="zwp_stereoscopy_description_v1" version="1">
+    <description summary="stereoscopy interface for a wl_surface">
+      A stereoscopy_description object allows the client to configure
+      the stereoscopy layout of a wl_surface, as well as the default
+      side being displayed on non-stereoscopic outputs.
+
+      The 'set_layout' request will change the way the buffer attached
+      to the surface is interpreted on every kind of output.
+
+      The 'set_default_side' request hints at which side will be
+      composited on outputs that don’t support stereoscopy.
+
+      Note: When interacting between this protocol and wp_viewporter, a
+      compositor should first apply the stereoscopy transforms and then
+      the viewport, to make sure the region displayed in the end is
+      sensible.
+    </description>
+
+    <request name="destroy" type="destructor">
+      <description summary="remove stereoscopy information from the surface">
+        Sets the layout of the associated wl_surface back to none.
+        The change is applied on the next wl_surface.commit.
+      </description>
+    </request>
+
+    <enum name="error">
+      <description summary="fatal errors">
+        These fatal protocol errors may be emitted in response to
+        illegal stereoscopy requests.
+      </description>
+      <entry name="invalid_layout" value="0"
+             summary="an unsupported layout has been set"/>
+      <entry name="invalid_default_side" value="1"
+             summary="an unsupported default side has been set"/>
+    </enum>
+
+    <request name="set_layout">
+      <description summary="set the specified stereoscopy layout for this surface">
+        This request tells the compositor to consider the wl_buffer
+        attached to this surface as a stereoscopic one.  It will only
+        be enabled on the next wl_surface.commit.
+      </description>
+      <arg name="layout" type="uint" enum="zwp_stereoscopy_v1.layout"
+           summary="stereoscopy layout to use"/>
+    </request>
+
+    <enum name="side">
+      <description summary="list of sides">
+        Which side to use on non-stereoscopic outputs.
+      </description>
+      <entry name="default" value="0"
+             summary="default one, as preferred by the compositor"/>
+      <entry name="left" value="1"
+             summary="left side"/>
+      <entry name="right" value="2"
+             summary="right side"/>
+    </enum>
+
+    <request name="set_default_side">
+      <description summary="set the default side for this surface, when displayed on a non-stereoscopic output">
+        This request is a hint asking the compositor to display either
+        the left side or the right side to the stereoscopy-enabled
+        buffer on a non-stereoscopic output, or just let it default to
+        its preference.
+      </description>
+      <arg name="default_side" type="uint" enum="side"
+           summary="which side to default to on non-stereoscopic outputs"/>
+    </request>
+
+  </interface>
+
+</protocol>