Interfaces to objects

[Bill Spitzak]

This is my understanding. And this is one of the big confusing points 
when trying to figure out the Wayland api, but I think there are good 
reasons for it. The only real problem is that the auto-generated 
documentation is not handling this nicely:

A Wayland compositor has to support the functions in wl_surface, but 
does not need to support the functions described by wl_shell. If it does 
support wl_shell, inside it there is still only one data structure for 
each surface, containing both the wl_surface and the wl_shell state 
data. If a client does not use the wl_shell api then the default values 
are used, it's not like they don't exist.

The client needs to know whether the wl_shell functions are supported.

Rather than adding to the api a query that takes an object and says 
whether it supports some subset of functions, Wayland reuses the 
already-existing ability to create objects.

The client asks Wayland to create a wl_shell object, passing it an 
existing wl_surface object. If the compositor supports wl_shell, this 
will work. If it does not it will not work and the client gets an error.

This did not really create a new object. Instead it is more like the 
object was multiply inherited from wl_surface and wl_shell, and this 
does a dynamic cast from the wl_surface to wl_shell (apologies for that 
description if you hate C++, I think this is called mix-in or interface 
classes in other languages).

The advantage of this is that existing machinery in the Wayland API is 
reused, rather than adding an interface query api. Keeping the low-level 
api as simple as possible is a big win for IPC and for writing backends 
in multiple languages.

The disadvantage of this is that both the client and compositor have to 
keep track of several id's for the same object. This is going to make it 
difficult to provide Wayland utility functions that are not toolkit 
specific, though maybe everybody will agree on the id array, or the 
client lib can add support to quickly re-find an api id given a 
wl_surface id.

I sure hope the above is correct and I have not botched it and confused 
things worse...