[PATCH weston-ivi-shell v3 02/10] ivi application protocol:

[Pekka Paalanen]

On Wed, 12 Mar 2014 23:59:33 +0900
Nobuhiko Tanibata <NOBUHIKO_TANIBATA at xddp.denso.co.jp> 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 <NOBUHIKO_TANIBATA at xddp.denso.co.jp>
> ---
> 
> 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.

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

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?

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

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

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