Basic API usage

[Jan Bruns]

Hallo Pekka,

thanks for that great reply. It made a lot of things much more clear to 
me, but I must admit I'll probably simply give up.

 > yes, the application used headers are generated by a bindings-specific
 > tool from the XML, like wayland-scanner for the traditional C bindings.

 > wayland.xml is actually the exception that ships with pre-generated
 > headers. All other protocol XML files (e.g. from wayland-protocols
 > repository) do not ship headers, but expect projects using the
 > protocol to use the appropriate language binding generator tools
 > themselves.

I see. So there is some "secret" but normative counting-order for 
elements of that XML, that many implementations could rely on, so that 
if someone modifies that XML will have that in mind?

 >> Could someone please outline how to use the API for the non-gcc case?

 > I suppose you mean a non-C/C++ case.

Well, the last time I've read some C-language specification many years 
ago, the one thing that it really made clear was you can count on 
everything is completely undefined.

 > You can write a whole protocol implementation from scratch without
 > depending on libwayland, if you have no need to use ready-made
 > libraries that already use libwayland. One of the most notable
 > ready-made libraries that use libwayland is Mesa EGL, so if you want to
 > be able to use EGL, you have no choice but to wrap libwayland.

Hmn, ah, so the C-interface *is* normative?
Wouldn't that already be a lot more lines of code and hidden 
implications than X11 including a bunch of extensions plus glx came upon?

 > libwayland is split into client and server parts, but you can also see
 > it being split into core and language bindings. The bindings for the C
 > language come built-in, but they are not the only bindings in
 > existence. The thing that may confuse you is that there are actually
 > two different APIs for writing language bindings: one very specific to
 > C (the one you found), and another better suited to other languages.

I see, so except for this obscure opcode counting mechanism, and some 
details about handling data sent through the unix domain socket, the XML 
defines some protocol.

 > Unfortunately there are many details that have not yet been written
 > down in a specification document, which means you need to compare with
 > how the C bindings actually work, e.g. what does wayland-scanner do
 > with the XML. The common catch is that a new_id argument without an
 > interface defined in the XML will expand into three arguments, not one.
 > Event and request opcodes are assigned independently and implicitly in
 > the order they appear inside an interface definition in the XML.

I didn't get to see a wayland-scanner. Where is it?

 > The wayland-*-core.h headers exist (as an afterthought, which explains
 > all this duplicity in the APIs as well) exactly so that programs using
 > non-C bindings would not need to pull in the C bindings.
 >
 > If I remember the right, the core of the alternate bindings API for
 > client side is formed from:
 > - wl_proxy_marshal_array
 > - wl_proxy_marshal_array_constructor
 > - wl_proxy_marshal_array_constructor_versioned
 > - wl_proxy_add_dispatcher

Ah, but this won't work for me.

To me it appears extremely strange (impossible!) to have open argument 
list functions exported, especially as essential parts for a project 
that aims to replace something X some day.

 > The main idea is that you wrap the "core" API of libwayland into your
 > preferred language, and then write a code generator tool similar to
 > wayland-scanner that generates the bindings from XML to your language,
 > using your wrapped libwayland calls. You have the freedom to design the
 > API produced by your code generator any way you want as long as it maps
 > correctly to the libwayland ABI.

Thanks.

Gruss

Jan Bruns