2014-03-14 23:16 に Pekka Paalanen さんは書きました:
On Wed, 12 Mar 2014 23:59:33 +0900
Nobuhiko Tanibata <[email protected]> wrote:
Add interface ivi_application, which creates ivi_surface objects tied
to a given wl_surface with a given id. The given id can be used in a
shell to identify which application is assigned to a wl_surface and
layout the surface wherever the shell wants. ivi_surface objects can
be used to receive status of wl_surface in the scenegraph of the
compositor.
Signed-off-by: Nobuhiko Tanibata <[email protected]>
---
Changes for v2:
- Rename "error" to "warning" because meaning of "error" in wayland
is fatal.
Changes for v3:
- Move "warning" from ivi_application to ivi_surface.
- Squash Makefile.
- Add description to ivi_surface:destroy.
- Update description of ivi_application:surface_create.
protocol/Makefile.am | 3 +-
protocol/ivi-application.xml | 96
++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 98 insertions(+), 1 deletion(-)
create mode 100644 protocol/ivi-application.xml
diff --git a/protocol/Makefile.am b/protocol/Makefile.am
index 5e331a7..9913f16 100644
--- a/protocol/Makefile.am
+++ b/protocol/Makefile.am
@@ -8,7 +8,8 @@ protocol_sources = \
text-cursor-position.xml \
wayland-test.xml \
xdg-shell.xml \
- scaler.xml
+ scaler.xml \
+ ivi-application.xml
if HAVE_XMLLINT
.PHONY: validate
diff --git a/protocol/ivi-application.xml
b/protocol/ivi-application.xml
new file mode 100644
index 0000000..8f5c23d
--- /dev/null
+++ b/protocol/ivi-application.xml
@@ -0,0 +1,96 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="ivi_application">
+
+ <copyright>
+ Copyright (C) 2013 DENSO CORPORATION
+ Copyright (c) 2013 BMW Car IT GmbH
+
+ Permission is hereby granted, free of charge, to any person
obtaining a copy
+ of this software and associated documentation files (the
"Software"), to deal
+ in the Software without restriction, including without limitation
the rights
+ to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell
+ copies of the Software, and to permit persons to whom the
Software is
+ furnished to do so, subject to the following conditions:
+
+ The above copyright notice and this permission notice shall be
included in
+ all copies or substantial portions of the Software.
+
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY,
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT
SHALL THE
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
OTHER
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
ARISING FROM,
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN
+ THE SOFTWARE.
+ </copyright>
+
+ <interface name="ivi_surface" version="1">
+ <description summary="application interface to surface in ivi
compositor"/>
+
+ <request name="destroy" type="destructor">
+ <description summary="destroy ivi_surface">
+ This removes link from surface_id to wl_surface.
However it doesn't
+ remove internal properties, e.g. position,
visibility, and so on, which
+ is set to the surface_id. This means when some issues
happen on clients
+ and a ivi_surface is destroyed, it can use previous
properties immediately
+ without setting it again if it restarts and attaches
new wl_surface to
+ the same surface_id.
This keeping of properties... why even mention it here? They are
nothing this client can affect, are they?
Otherwise I would ask, how would the client know if the properties are
already set, or if it needs to set them again, or if the client
actually needs to know some of them to function correctly.
Not a big deal.
Hi pq,
Yes, it doesn't affect client behavior so I will remove description
after "However...".
The decision shall be done in server side. So as you say, it should not
be mentioned here.
+ </description>
+ </request>
+
+ <event name="visibility">
+ <description summary="visibility of surface in ivi
compositor has changed">
+ The new visibility state is provided in argument
visibility.
+ If visibility is 0, the surface has become invisible.
+ If visibility is not 0, the surface has become
visible.
+ </description>
+ <arg name="visibility" type="int"/>
+ </event>
+
+ <enum name="warning_code">
+ <description summary="possible warning codes returned by
ivi compositor">
+ These warning codes define all possible warning codes
returned by ivi compositor
+ on server-side warnings.
+ invalid_wl_surface: invalid wl_surface is set. This
happen if wl_surface is destroy before this.
I guess you mean, that invalid_wl_surface is emitted, if the wl_surface
is destroyed before the ivi_surface, right?
Yes, you are right.
Usually we deal with these things by saying the ivi_surface would just
become inert, but I assume you really want the notification here.
Is invalid_wl_surface also for the case when the wl_surface already has
an ivi_surface associated?
In the above case, a code "surface_id_in_use" is used. But, I shall add
"wl_surface_in_use" to the warnings.
+ surface_id_in_use: surface_id is already assigned by
another application.
+ </description>
+ <entry name="invalid_wl_surface" value="1"
summary="wl_surface is invalid"/>
+ <entry name="surface_id_in_use" value="2"
summary="surface_id is in use and can not be shared"/>
+ </enum>
+
+ <event name="warning">
+ <description summary="server-side warning detected">
+ The ivi compositor encountered warning while
processing a request by this
+ application. The warning is defined by argument
warning_code and optional
+ warning_text. If the warning is detected, client
shall destroy the ivi_surface
+ object.
You still need to specify how the server handles this ivi_surface
object after sending the warning, but before it is destroyed. Does the
server ignore all requests referring to this ivi_surface, or the ID? Is
the ID immediately free again, or does the ivi_surface need to be
destroyed before the ID becomes available again?
Yes, the server ignore all requests.
In case of "surface_id_in_use", ivi_surface, e.g. "A" doesn't have to be
destroyed to use surface_id. the surface_id is tied only to the other
ivi_surface, e.g. "B" already. If the other ivi_surface "B" is
destroyed, client can use surface_id without destruction of ivi_surface
"A" because "A" doesn't have any link to the surface_ID.
I will add more description of correct behavior here.
+ </description>
+ <arg name="warning_code" type="int"/>
+ <arg name="warning_text" type="string"
allow-null="true"/>
+ </event>
+
+ </interface>
+
+ <interface name="ivi_application" version="1">
+ <description summary="interface for ivi applications to use
ivi compositor features"/>
+
+ <request name="surface_create">
+ <description summary="create ivi_surface with numeric ID
in ivi compositor">
+ surface_create will create a interface:ivi_surface
with numeric ID; surface_id in
+ ivi compositor. These surface_ids are defined as
unique in the system to identify
+ it inside of ivi compositor. The ivi compositor
implements business logic how to
+ set properties of the surface with surface_id
according to status of the system.
+ E.g. a unique ID for Car Navigation application is
used for implementing special
+ logic of the application about where it shall be
located. Created ivi_surface
+ notifies warnings when following situation happens,
+ - Invalid wl_surface is set. This happen if
wl_surface is destroy before this.
+ - surface_id is already assigned by another
application.
+ </description>
+ <arg name="id_surface" type="uint"/>
+ <arg name="surface" type="object"
interface="wl_surface"/>
+ <arg name="id" type="new_id" interface="ivi_surface"/>
Does this give the surface a role? E.g. what should happen if a client
registers the same wl_surface as both an ivi_surface and a pointer
image (wl_pointer.set_cursor).
If your weston implementation sets weston_surface::configure, it is a
strong indication that this gives a role, which excludes all other
roles. IOW, this request should fail, if weston_surface::configure is
already set, so you need a warning code for it.
You should probably look at all interfaces, where a wl_surface can be
an argument for a request, and check if those interfaces can exist in
an IVI environment, and if they can, how they interoperate with a
wl_surface that has a ivi_surface.
Good comments. I will check them and come back immediately.
Thanks,
Nobuhiko
+ </request>
+
+ </interface>
+
+</protocol>
This is a very simple interface, but there are many details to
get right anyway. You are doing good progress. :-)
Thanks,
pq
_______________________________________________
wayland-devel mailing list
[email protected]
http://lists.freedesktop.org/mailman/listinfo/wayland-devel
