Introduce wtz-foreign protocol

wtz-foreign is a protocol meant to enable sharing wayland resources
between wayland clients. The only resource that clients are now able to
share with this protocol is a foreign shell. And the protocol may be
able to be extended in the future for sharing various resources.

The use case for foreign shell is out-of-process video playing surface.
For that, it provides a way to export and import a foreign shell.

Video playing application may export foreign shell with passing its
sub-surface, creating a handle for the foreign shell.
The handle, in form of a unique string, may be shared in some way with
other clients (for example, D-Bus) which can then import the foreign
shell with passing its surface. This gives the surface the role of a
foreign shell surface.

In this way, each client has a object. Which are named
wtz_exported_shell and wtz_foreign_shell.

The exporter may manipulate destination, transform, and position with
wl_subsurface and wtz_exported_shell interface.
The importer may attach and commit buffer with wl_surface without
care of its destination, transform, and position.
So final view by compositor will be determined by this combination.

Besides, the exporter may change the state of foreign shell along with
the changes of parent surface in an atomic manner using sub-surface
given when creating exported foreign shell.

Change-Id: I51ed03bcbe7740763895f09802ea249c061cef12

diff --git a/Makefile.am b/Makefile.am
index 57e8afa..7b3306d 100644 (file)
--- a/Makefile.am
+++ b/Makefile.am
@@ -366,6 +366,23 @@ liblinux_explicit_synchronization_unstable_v1_client_la_SOURCES = protocol/unsta
 liblinux_explicit_synchronization_unstable_v1_client_la_CFLAGS  = @WAYLAND_CLIENT_CFLAGS@
 liblinux_explicit_synchronization_unstable_v1_client_la_LIBADD  = @WAYLAND_CLIENT_LIBS@
 
+### wtz_foreign
+protocol_LTLIBRARIES += \
+               libwtz-foreign-server.la \
+               libwtz-foreign-client.la
+pkgconfig_DATA += \
+        src/wtz-foreign-server.pc \
+        src/wtz-foreign-client.pc
+protocolinclude_HEADERS += \
+               protocol/tizen/wtz-foreign-server-protocol.h \
+               protocol/tizen/wtz-foreign-client-protocol.h
+libwtz_foreign_server_la_SOURCES = protocol/tizen/wtz-foreign-protocol.c
+libwtz_foreign_server_la_CFLAGS  = @WAYLAND_SERVER_CFLAGS@
+libwtz_foreign_server_la_LIBADD  = @WAYLAND_SERVER_LIBS@
+libwtz_foreign_client_la_SOURCES = protocol/tizen/wtz-foreign-protocol.c
+libwtz_foreign_client_la_CFLAGS  = @WAYLAND_CLIENT_CFLAGS@
+libwtz_foreign_client_la_LIBADD  = @WAYLAND_CLIENT_LIBS@
+
 ### wayland-protocols
 unstable_protocols = \
        protocol/unstable/pointer-gestures/pointer-gestures-unstable-v1.xml \
@@ -413,6 +430,7 @@ tizen_protocols = \
         protocol/tizen/tizen-extension.xml \
         protocol/tizen/fullscreen-shell.xml \
         protocol/tizen/tizen-policy-ext.xml \
+               protocol/tizen/wtz-foreign.xml \
        $(NULL)
 
 nobase_dist_pkgdata_DATA = \

diff --git a/protocol/tizen/wtz-foreign.xml b/protocol/tizen/wtz-foreign.xml
new file mode 100644 (file)
index 0000000..d7918f5
--- /dev/null
+++ b/protocol/tizen/wtz-foreign.xml
@@ -0,0 +1,224 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="wtz_foreign">
+
+  <copyright>
+    Copyright 2021 Samsung Electronics co., Ltd. All Rights Reserved.
+
+    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>
+
+  <description summary="Protocol for sharing waylad resources between wayland clients">
+    This protocol specifies a way for making it possible to share wayland
+    resources between wayland clients.
+
+    For that, this provides two globals, wtz_exporter and wtz_importer.
+    The wayland client may bind a wtz_exporter global if it wants to
+    export its resource, and may bind a wtz_importer global if it wants to
+    import resources exported by another wayland client.
+
+    In order for a client A to get a reference of a resource of client B,
+    client B must first export its resource using a specific request of
+    wtz_exporter.
+    Upon doing this, client B will receive a handle (a unique string) that
+    it may share with client A in some way (for example D-Bus).
+    After client A has received the handle from client B, it may use a
+    specific request of wtz_importer to create a reference to the resource
+    client B just exported.
+    See the corresponding requests for details.
+  </description>
+
+  <interface name="wtz_exporter" version="1">
+    <description summary="interface for exporting wayland resources">
+        A global interface used for exporting wayland resources that can later
+        be imported using wtz_importer.
+    </description>
+
+    <enum name="error">
+      <entry name="invalid_role" value="0"
+         summary="given surface has invalid role"/>
+      <entry name="already_exported" value="1"
+         summary="given resource may allow to be exported only once"/>
+    </enum>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy wtz_exporter object">
+       Notify the compositor that the wtz_exporter object will no longer be
+       used.
+      </description>
+    </request>
+
+    <request name="export_shell">
+      <description summary="export a sub-surface as a foreign shell">
+    The export_shell request exports the passed sub-surface as a foreign shell
+    so that it can later be imported via wtz_importer. When called, a new
+    wtz_exported_shell object will be created and wtz_exported_shell.handle
+    will be sent immediately. And the handle can be used to import foreign
+    shell later associated with this exported_shell.
+
+    Note that only sub-surface can be exported as a foreign shell. So, attempt
+    to export non sub-surface will raise a protocol error.
+
+    A sub-surface may be exported as a foreign shell only once, and each
+    exported handle may be used to create an wtz_foreign_shell once.
+    That is, multiple times exporting and importing is not allowed.
+    So attempt to export already exported sub-surface will raise a protocol
+    error.
+      </description>
+      <arg name="id" type="new_id" interface="wtz_exported_shell"
+       summary="the new wtz_exported_shell object"/>
+      <arg name="surface" type="object" interface="wl_surface"
+       summary="the wl_surface to be exported"/>
+    </request>
+  </interface>
+
+  <interface name="wtz_importer" version="1">
+    <description summary="interface for importing wayland resources">
+      A global interface used for importing resources exported by
+      wtz_exporter. With this interface, a client can create a reference
+      to a resource of another client.
+    </description>
+
+    <enum name="error">
+      <entry name="already_imported" value="0"
+         summary="given handle has been already imported"/>
+      <entry name="role" value="1" summary="given surface has another role"/>
+    </enum>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy the wtz_importer object">
+       Notify the compositor that the wtz_importer object will no longer be used.
+      </description>
+    </request>
+
+    <request name="import_shell">
+      <description summary="import an exported foreign shell">
+    The import_shell request imports a foreign shell from any client given a
+    handle created with wtz_exporter.export_shell.
+    When called, a new wtz_foreign_shell object will be created.
+
+    This gives the surface the role of a foreign shell surface. If the surface
+    already has another role like wl_shell_surface, sub-surfaces etc.,
+    it raises a protocol error.
+      </description>
+      <arg name="id" type="new_id" interface="wtz_foreign_shell"
+       summary="the new wtz_foreign_shell object"/>
+      <arg name="surface" type="object" interface="wl_surface"
+       summary="surface to be given the foreign shell surface role"/>
+      <arg name="handle" type="string"
+       summary="the exported foreign shell handle"/>
+    </request>
+  </interface>
+
+  <interface name="wtz_exported_shell" version="1">
+    <description summary="an exported shell handle">
+      A wtz_exported_shell object represents an exported reference to a
+      foreign shell associated with sub-surface.
+
+      The related wl_surface cannot no longer be used for attaching wl_buffer.
+      So, attaching a wl_buffer on this wl_surface would have no effect.
+      Instead, a wl_buffer for contents will be submitted by the wl_surface
+      associated with a wtz_foreign_shell.
+
+      With this interface, client may change map state, destination size and
+      transform value.
+    </description>
+
+    <enum name="error">
+      <entry name="bad_value" value="0"
+         summary="negative or zero values in width or height"/>
+      <entry name="invalid_transform" value="1"
+         summary="transform value is invalid"/>
+    </enum>
+
+    <enum name="transform">
+      <entry name="normal" value="0" summary="no transform"/>
+      <entry name="90" value="1" summary="90 degrees clockwise"/>
+      <entry name="180" value="2" summary="180 degrees clockwise"/>
+      <entry name="270" value="3" summary="270 degrees clockwise"/>
+    </enum>
+    <request name="destroy" type="destructor">
+      <description summary="unexport the exported surface">
+      </description>
+    </request>
+
+    <request name="set_destination">
+      <description summary="set the exported shell size for scaling">
+      </description>
+      <arg name="width" type="int" summary=""/>
+      <arg name="height" type="int" summary=""/>
+    </request>
+
+    <request name="set_transform">
+      <description summary="">
+      </description>
+      <arg name="transform" type="int" enum="transform"
+       summary=""/>
+    </request>
+
+    <request name="map">
+      <description summary="">
+      </description>
+    </request>
+
+    <request name="unmap">
+      <description summary="">
+      </description>
+    </request>
+
+    <event name="handle">
+      <description summary="the exported shell handle">
+      </description>
+      <arg name="handle" type="string"
+       summary="the exported shell handle"/>
+    </event>
+  </interface>
+
+  <interface name="wtz_foreign_shell" version="2">
+    <description summary="an imported shell handle">
+    </description>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy the wtz_imported_surface object">
+      </description>
+    </request>
+
+    <event name="destroyed">
+      <description summary="">
+      </description>
+    </event>
+
+    <event name="destination_changed">
+      <description summary="size changed">
+      </description>
+      <arg name="width" type="int"/>
+      <arg name="height" type="int"/>
+    </event>
+
+    <event name="transform_changed">
+      <description summary="">
+      </description>
+      <arg name="transform" type="int" enum="wtz_exported_shell.transform"
+       summary=""/>
+    </event>
+  </interface>
+
+</protocol>