[PATCH wayland-protocols 01/13] Add stereoscopy protocol
Emmanuel Gil Peyrot
linkmauve at linkmauve.fr
Tue Nov 14 15:05:48 UTC 2017
From: Emmanuel Gil Peyrot <emmanuel.peyrot at 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 at 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
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 at 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>
--
2.15.0
More information about the wayland-devel
mailing list