From: Seunghun Lee Date: Fri, 19 Feb 2021 02:19:22 +0000 (+0900) Subject: Introduce wtz-foreign protocol X-Git-Tag: submit/tizen/20210331.060244~1 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=633414048f1482f81de142778ac0d72825abd72d;p=platform%2Fcore%2Fuifw%2Fwayland-extension.git 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 --- 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 index 0000000..c57fd14 --- /dev/null +++ b/protocol/tizen/wtz-foreign.xml @@ -0,0 +1,255 @@ + + + + + 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. + + + + 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. + + + + + A global interface used for exporting wayland surfaces that can + later be imported using wtz_importer. + + + + + + + + + + Notify the compositor that the wtz_exporter object will + no longer be used. + + + + + + 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. + + + + + + + + + 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. + + + + + + + + + + Notify the compositor that the wtz_importer object will no + longer be used. + + + + + + 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. + + + + + + + + + + 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. + + + + + 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. + + + + + + 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. + + + + + + + Sent whenever the viewport size of exported surface changes by + manipulating imported surface. + + + + + + + + Sent whenever the viewport orientation of exported surface + changes by manipulating imported surface. + + + + + + + + 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. + + + + + + + + + + Notify the compositor that it will no longer use the + wtz_imported_surface object. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +