Interfaces to objects

[Pekka Paalanen]

On Fri, 08 Aug 2014 16:06:04 -0700
Bill Spitzak <spitzak at gmail.com> wrote:

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

You may be confusing wl_shell with wl_shell_surface.

And in Weston's case, if a client does not create a
wl_shell_surface, the shell specific data for the wl_surface really
does not exist inside Weston, literally.

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

No. If the compositor does not support wl_shell, there is no
global of kind "wl_shell" advertized, and the client simply cannot
even attempt to use it. The error case does not exist.

> 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).

All that depends on what you mean by "object". It does create new
protocol objects. It does allocate new structs inside Weston. It
does not create a new conceptual object but just assigns more
meaning and methods to "a surface".

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

Yes, and the fundamental problem with query type of APIs is that it
requires a round-trip.

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

Again depends on what you mean by "object". The id's are always 1:1
corresponding to the protocol objects, and libwayland-server does
all the tracking for you. As a compositor developer, you do not
deal with ids in 99% of the cases, and people are looking to remove
even that remaining 1% in the libwayland-server API.


Thanks,
pq