--- /dev/null
+<?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>