Introduce wtz-foreign protocol

wtz-foreign is a protocol meant to enable sharing wayland resources
between wayland clients.

For now, it provides a way to export and import a pure wl_surface.
(here 'pure' means that this wl_surface doesn't have any role.)
That is, this gives wl_surface a exported surface role.

The representative use case for exported surface is out-of-process video
playing surface.
For that, multimedia client may export its wl_surface, creating a handle
for the exported surface. 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 exported surface with a sub-surface as a proxy.
In this way, the client will be able to manipulate an exported surface
like a sub-surface. In other words, this exported surface will be stay
glued to given sub-surface like sub-surface to its parent.

Once a client imports a exported surface, the client may change the
attributes, such as geometry or map state, of exported surface with an
object(wtz_imported_surface) created by importing a surface.
Moreover, all this changes can be applied along with the changes of
parent surface in an atomic manner using sub-surface given when creating
imported surface. See wl_subsurface.set_sync for more detail to apply
changes in an atomic manner.

But note that using exported surface can put compositor at a
disadvantage for zero-copy video presentation path, because compositor
may supposed to scale up/down exported surface without hardware support.

Hopefully, any resources required to be shared between clients in the
future can be added into this protocol.

Change-Id: I742a1d70930bb3202fd705256c65c189f47fb889

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..c57fd14
--- /dev/null
+++ b/protocol/tizen/wtz-foreign.xml
@@ -0,0 +1,255 @@
+<?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 surfaces between wayland clients">
+        This protocol specifies a way for making it possible to share wayland
+        surfaces 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 wl_surface resource, and may bind a wtz_importer global if
+        it wants to import wl_surface exported by another wayland client.
+        In order for a client A to get a reference of a surface of client B,
+        client B must first export its surface 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 surface
+        client B just exported.
+        See the corresponding requests for details.
+
+        The current use case is out-of-process multimedia processing in the
+        Tizen platform. In Tizen platform, multimedia process creates its
+        own wl_surface for displaying decoded video buffer, but at the same
+        time application process needs a way to control the attributes,
+        such as geometry, of wl_surface created by multimedia process
+        synchronously.
+    </description>
+
+    <interface name="wtz_exporter" version="1">
+        <description summary="interface for exporting surfaces">
+            A global interface used for exporting wayland surfaces that can
+            later be imported using wtz_importer.
+        </description>
+
+        <enum name="error">
+            <entry name="role" value="0"
+                summary="surface that has another role cannot be exported"/>
+            <entry name="already_exported" value="1"
+                summary="surface 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_surface">
+            <description summary="export a wl_surface and assign the expored_surface surface role">
+                The export_surface request exports the passed surface so that
+                it can later be imported via wtz_importer. When called, a new
+                wtz_exported_surface object will be created and
+                wtz_exported.handle will be sent immediately.
+                See the corresponding interface and event for details.
+
+                A surface may be exported only one time, and exported handle
+                may be used to create an wtz_imported_surface only one time.
+                Attemting export a surface more than once will raise an
+                already_exported error.
+
+                Note that only a surface that doesn't have any role may be
+                exported. That is, this gives passed wl_surface the
+                exported_surface role. So if wl_surface that has another role,
+                such as wl_subsurface, is given, this protocol will raise a
+                role error.
+            </description>
+            <arg name="id" type="new_id" interface="wtz_exported_surface"
+                summary="the new wtz_imported_surface 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 surfaces">
+            A global interface used for importing surfaces exported by
+            wtz_exporter. With this interface, a client can create a reference
+            to a surface of another client.
+        </description>
+
+        <enum name="error">
+            <entry name="already_imported" value="0"
+                summary="given handle has been already imported"/>
+            <entry name="invalid_role" value="1"
+                summary="given surface has invalid 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_surface">
+            <description summary="import an exported surface">
+                The import_surface reuqest imports a surface that has been
+                exported from another client with an associated handle.
+
+                This request requires a surface created by on its own. And
+                for now, the surface must have sub-surface role. Otherwise,
+                an invalid_role error will be raised.
+
+                When this request is successfully made, the exported surface
+                become an integral part of given sub-surface, and stay glued
+                to the sub-surface. This is similar to sub-surface behavior
+                for its parent.
+
+                When called, a new wtz_imported_surface object will be created.
+                And imporing client can manipulate attributes - such as size,
+                orientation, and map state - of exported surface via
+                wtz_imported_surface interface. This state is double-buffered,
+                and is applied on the next wl_surface.commit.
+                That is, this all changes will be made atomically using
+                wl_subsurface.set_sync.
+                See wtz_imported_surface for details.
+            </description>
+            <arg name="id" type="new_id" interface="wtz_imported_surface"
+                summary="the new wtz_imported_surface object"/>
+            <arg name="surface" type="object" interface="wl_surface"
+                summary="the surface for exported_surface to live in"/>
+            <arg name="handle" type="string"
+                summary="the exported surface handle"/>
+        </request>
+    </interface>
+
+    <interface name="wtz_exported_surface" version="1">
+        <description summary="an exported surface handle">
+            An wtz_exported_surface object represents an exported reference to
+            a surface. The exported surface may be referenced as long as the
+            wtz_exported_surface object not destroyed. Destroying the
+            wtz_exported_surface invalidates any relationship the importer may
+            have established using wtz_imported_surface.
+
+            The viewport of exported surface will be changed by imported
+            surface.
+        </description>
+
+        <request name="destroy" type="destructor">
+            <description summary="unexport the exported surface">
+                Revoke the previously exported surface. This invalidates any
+                relationship the importer may have set up using the
+                wtz_imported_surface created given the handle sent via
+                wtz_exported.handle.
+            </description>
+        </request>
+
+        <event name="handle">
+            <description summary="the exported surface handle">
+                The handle event contains the unique handle of this exported
+                surface reference. It may be shared with any client, which then
+                can use it to import the surface by calling
+                wtz_importer.import_surface. A handle may be used to import
+                the surface only one time.
+            </description>
+            <arg name="handle" type="string" summary="the exported surface handle"/>
+        </event>
+
+        <event name="size_changed">
+            <description summary="size changed">
+                Sent whenever the viewport size of exported surface changes by
+                manipulating imported surface.
+            </description>
+            <arg name="width" type="int"/>
+            <arg name="height" type="int"/>
+        </event>
+
+        <event name="orientation_changed">
+            <description summary="">
+                Sent whenever the viewport orientation of exported surface
+                changes by manipulating imported surface.
+            </description>
+            <arg name="orientation" type="int" enum="wl_output.transform"
+                summary=""/>
+        </event>
+    </interface>
+
+    <interface name="wtz_imported_surface" version="1">
+        <description summary="an imported surface handle">
+            An wtz_imported_surface object represents an imported reference to
+            surface exported by some client. A client can use this interface
+            to manipulate destination size, orientation, and map state of
+            exported surface.
+        </description>
+
+        <enum name="error">
+            <entry name="invalid_size" value="0"
+                summary="negative or zero values in width or height"/>
+            <entry name="invalid_orientation" value="1"
+                summary="given orientation is invalid"/>
+        </enum>
+
+        <request name="destroy" type="destructor">
+            <description summary="destroy the wtz_imported_surface object">
+                Notify the compositor that it will no longer use the
+                wtz_imported_surface object.
+            </description>
+        </request>
+
+        <request name="set_size">
+            <description summary="set the exported surface size for scaling">
+            </description>
+            <arg name="width" type="int" summary="width of imported surface"/>
+            <arg name="height" type="int" summary="height of imported surface"/>
+        </request>
+
+        <request name="set_orientation">
+            <description summary="">
+            </description>
+            <arg name="orientation" type="int" enum="wl_output.transform" summary=""/>
+        </request>
+
+        <request name="map">
+            <description summary="">
+            </description>
+        </request>
+
+        <request name="unmap">
+            <description summary="">
+            </description>
+        </request>
+
+        <event name="destroyed">
+            <description summary="">
+            </description>
+        </event>
+    </interface>
+</protocol>