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

[Pekka Paalanen]

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.

> > +       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!* ;-)


Thanks,
pq