Basic API usage

[Pekka Paalanen]

On Tue, 8 Sep 2020 22:24:16 +0200
Jan Bruns <code at abnuto.de> wrote:

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

Hi,

yes, the message opcode is determined implicitly by counting. Hence, if
you reorder two requests in an XML file, that's a breaking change
because the opcodes change. Also message argument order is significant.

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

Ha, yeah.

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

Depends on which interface you talk about, libwayland has two:
- the core ABI
- the wayland-scanner generated API from wayland.xml

It's nothing special to libwayland. If you have library A that
internally calls to library B, and types from library B are part of the
public interface of library A, then it is really really hard for the
user to use anything but library B specifically when calling library A.

EGL Wayland platform requires you to use the opaque C types struct
wl_display * and struct wl_surface * in the EGL Wayland API. These are
not just protocol object IDs, these are actual C structs with hidden
implementation. EGL implementation will call into libwayland with the
pointers you gave, so there is no room to use anything but libwayland
yourself.

However, this is the EGL implementation's decision to use libwayland,
but it stems from a practical necessity.

There have been talks about reimplementing libwayland in Rust while
offering the C ABI. Such implementation could also offer a native Rust
API without losing interoperability with libraries like EGL.

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

I'm not sure what you mean. With X11, you still have to use libX11 if
you want to use EGL X11 platform, because you pass a Display into EGL.
There exists libxcb now too, and AFAIU libX11 has been rewritten
internally to use libxcb, making the two co-operable. I just recently
saw someone working on a EGL XCB platform, allowing you to use EGL with
libxcb instead of libX11.

If you use libglx, then you must use libX11 too, I believe.

Mind the difference between a library and a protocol. Protocol is
implementation language agnostic, but when you start using multiple
libraries and expecting them to cooperate (call each other) in the same
process, that poses far more restrictions and details.

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

https://gitlab.freedesktop.org/wayland/wayland/-/blob/master/src/scanner.c

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

Those are not variadic functions. What do you mean?

You should not need to use a single variadic function to be able to
wrap libwayland correctly.

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

Thanks,
pq
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 833 bytes
Desc: OpenPGP digital signature
URL: <https://lists.freedesktop.org/archives/wayland-devel/attachments/20200909/2bc9b427/attachment.sig>