[PATCH wayland] protocol: add a note about the version bumps on wl_seat

[Jonas Ådahl]

On Fri, Mar 27, 2015 at 09:32:51AM +0200, Pekka Paalanen wrote:
> On Wed, 25 Mar 2015 08:18:11 +0800
> Jonas Ådahl <jadahl at gmail.com> wrote:
> 
> > On Wed, Mar 25, 2015 at 09:37:21AM +1000, Peter Hutterer wrote:
> > > See the explanation by Jonas here:
> > > http://lists.freedesktop.org/archives/wayland-devel/2015-March/020814.html
> > > 
> > > ---
> > > One thought while writing this: would it make sense to add a
> > > wl_seat.get_pointer_versioned request to request a specific wl_pointer
> > > version from the seat? or is that a solution waiting for a problem?
> > 
> > What would the point be of getting a pointer with a different version
> > than the seat? What if a new seat revision adds some feature that has a
> > corresponding event/request on wl_pointer? Should it be allowed to get
> > a partly non-working wl_pointer from that seat? I don't think it would
> > be worth it.
> 
> Agreed.
> 
> > > 
> > >  protocol/wayland.xml | 11 +++++++++++
> > >  1 file changed, 11 insertions(+)
> > > 
> > > diff --git a/protocol/wayland.xml b/protocol/wayland.xml
> > > index 880f90a..22606bb 100644
> > > --- a/protocol/wayland.xml
> > > +++ b/protocol/wayland.xml
> > > @@ -1329,6 +1329,14 @@
> > >      </request>
> > >     </interface>
> > >  
> > > +  <!-- Note regarding the wl_seat version:
> > > +       The wl_pointer, wl_touch, wl_keyboard must be identical to the
> > > +       wl_seat version. Bumping one requires bumping all of them.
> 
> This is not totally correct. Only the version of wl_seat must be the
> max(wl_pointer, wl_touch, wl_keyboard) version, and when any are
> bumped, the bumped to versio must be wl_seat version + 1.

My point was that it is less confusing by having the version in the XML
be the same version that would normally be created, even though no new
requests or events were added to that particular interface. Now in
various places it says <interface name="foo" version="3"> ...
</interface> but one would often create a foo object with version 4 if
its parent was created with that version, which is a bit confusing,
since it looks like the version one created was higher than the newest
in the protocol spec.

> 
> > > +       Reason: clients cannot specify a version in wl_seat.get_pointer,
> > > +       wl_seat.get_keyboard or wl_seat.get_touch, the returned object is
> > > +       always of the same version as the wl_seat.
> > > +   -->
> > 
> > I think this belongs in a more generic place, i.e. somewhere in
> > doc/publican/sources/, since this is not a "wl_seat" specific thing but
> > applies to any object tree where only the global binding decides the
> > version.
> 
> Yeah, this is just how Wayland protocol spec works for everything.
> 
> We actually do have this documented:
> http://wayland.freedesktop.org/docs/html/ch04.html#sect-Protocol-Versioning
> 
> *shock!* ;-)
> 

Oh! Should have checked that first :P


Jonas