[PATCH weston-ivi-shell v3 02/10] ivi application protocol:
Nobuhiko Tanibata
nobuhiko_tanibata at xddp.denso.co.jp
Fri Mar 14 23:58:30 PDT 2014
2014-03-14 23:16 に 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.
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
More information about the wayland-devel
mailing list