+++ /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>