 Okay. Okay. Then I think we are good to go. Yeah. Good evening everybody. I'm Philip. And I'll be telling you something about using the new Welland protocol when programming client applications. First, a few words about me. I was participating in what? Okay. I was participating in the Google Summer of Code last year as a student for the project. And I implemented the Welland backend that will be in code version 18, which is the next version. And yeah, with this talk I want to share some of the experience I gained there with you. Like Lucas before me, this is actually my first time at FOSDEM and my first time giving a talk to such a big technical audience. So I am very grateful for the opportunity. I'm very happy to be here. So about the talk just very quickly. I'll give you an introduction to Welland but I will not go very deeply into that and I will be also not talking about Welland from a user perspective and also not for motivation behind the Welland design. Then I'll show you how the process works for getting a window on screen and showing something and getting some input done. And I'll give you some general hints for client development and practice like how do you go about testing and debugging this stuff before coming to the conclusion. Due to the time constraints we have here, I initially applied for a 60-minute talk. But we have 20 minutes now. I will be not giving too many hands-on and in-depth examples but I'll still give you the basics on Welland. So to start the big picture of Welland and X. So to get some key terms out of the way what actually is X I mean most of you probably know the question should rather be what is part of the X project and actually X is mostly X 11 which is version 11 of the X protocol which is a protocol for communication between graphical applications and displays over and like how many of you have used the phrase like oh no X crashed, just put your hands up. And that is technically not what you should be saying because X is a protocol. So what you are meaning is of course that the X.org server which is the canonical server side implementation of the X 11 protocol has crashed which used to happen from time to time and that is actually similar to what Welland is. It's like X 11 protocol that is intended to succeed X 11 and it's not actually a server it's also some supporting C libraries such as the Welland client which I'll be getting into later and part of the Welland project is also Western which is the reference server side implementation but it's not like on X where we have the X.org server which pretty much everyone is using. Western is really just for reference for some specific use cases or big desktop environments like Nome and KDE they have their own Welland server. So to sum up Welland is not a piece of software that you can run so you cannot say Welland has crashed but just does not make any sense from a technical point of view and it's also not quite like X 11 so why isn't it? The key difference is just listing them up which you usually refer to as compositors they do a lot of stuff actually. They combine the display server the window management and the compositing functions in one process which used to be separate with X 11 which has been possible because of lots of work in the Linux kernel on getting the graphics drivers into the kernel and out of the X.org server. So the scope of the protocol extends a bit beyond what X 11 is doing. We are not just looking at like general the desktop use case where we have windows and stuff but also other environments like in-vehicle infotainment which Welland also has protocols for and perhaps the difference that people talk most about or notice most is that the design has more security inherently than X 11 had. For example there are no general purpose interfaces for interfacing with other windows for example manipulating other windows stealing contents of other windows or injecting input into other windows and this is by design but it's not like we want to forbid all the stuff that was possible on X 11 it's just that you will have to be doing it differently because there should be protocols that support specific use cases and are not like the shotgun model that you have with X 11 where just any client can do pretty much anything and these use case specific protocols they are also designed by the Welland community but they are just not there yet because nobody has put enough effort to support these specific use cases and also the solutions that you end up could be radically different from what you would have done with X 11 because the circumstances are different. Last but not least there is also less craft in the protocol because it was designed from the ground up. For example there is no server side drawing at all and there is also no phone configuration, no phone rendering stuff. This is all done by the clients and not by the server. So if you are looking to implement a Welland client you have two basic options besides just saying I'm just not doing that. I will continue with X 11 because there is a transition layer which is called X Welland which works quite nice but I guess you are here because you want to hear about what you will do with Welland. You could go native which is what this talk is all about. You just program for Welland directly. It is an effort that is comparable to using Xlib or XCB for X if you've used that but there are some differences because Welland has client side decorations mostly which means that if you want to support window mode you want to throw your application in a window then you will also have to draw the window decorations and not only that you will also have to draw the buttons in the decorations and you must react to button clicks and you must support moving and resizing the window and showing the right cursor on resizing all that stuff. This might become less relevant in the future because there is an effort going on to standardize server side decorations on Welland kind of but it's not there yet and at the moment it's still a big problem if you want to have your application support window mode. So what my recommendation would be that in all cases that it's at all possible you should be using toolkits which is the second option. GTK, QT, EFL, GLFW they all have quite good Welland support and you just have to do a lot less effort. The toolkits have a lifting for you and you also get the benefit that your application will run on a lot of other platforms and it will also run on X because if you're doing a native Welland application with no kind of fallback then your application will just not be running on X11 but I do realize that using toolkits might not be an option for everyone if you're doing very specialized software or if you're just you want to write the toolkit. So this is what this talk is about. Okay after this introduction brief introduction of the Welland protocol actually how it works. It's an object oriented which means that you create new objects via the protocol and then you call methods on them which are called requests or you get events from the server and every function call is associated with an object. There are no like raw function calls. The protocol is defined in XML files which the main one is called Welland.xml which is shipped with Welland and there are some additional protocols for specific use cases like the in-vehicle environments that is part of another repository that's called Welland protocols. And from these XML files then the C code that you use to interface with Welland is actually generated. This is also modular which means that the set of interfaces that is available is easily extendable that's kind of similar to X11 protocol extensions and the biggest difference that you will notice at first is that it's completely asynchronous and method-based which is not really a request response anymore. The requests are completely fire and forget and you don't get you can't really ask the server for any state. The server will tell you when the state changes and you have to remember the state in the client. Some specific interfaces that you will have to use when using Welland is firstly WAL underscore display which is just the singleton interface that represents the connection to the WAL server and you get that just when connecting to a Welland socket and the other one is WAL underscore registry which you derive from WAL display and then that in turn provides access to all other global objects and global interfaces that you will be using so it is kind of the entry point for everything. And that's also what you see on the right side you get the WAL display then you call get registry on that, get a registry and then you get access to all those globals that are underneath and what those globals are will actually vary depending on what compositor you're using and what environment you are using it in. Most of these globals are singletons for example WAL compositeizing singleton and others for example WAL output which could be recently representing a physical monitor will appear multiple times if for example you have multiple manipulators connected you will get WAL output object that will give you the details on those monitors. So how do we use some of those globals to actually get a window on screen? It's not that easy of a process so I'll just give you the high level overview and it goes too much into the details. First you use the compositor global that I feel briefly speaking about and use it to create a surface and the surface is just a rectangular area of pixels that you can put some content in but if you just create a surface then it won't be displayed because all surfaces need a role and exactly one role that tells the compositor what it should do with the surface and what kind of way it should use it and display it and what you will use for that is if you just want a regular window on a desktop then there's an extension protocol for that that you should be using and it's called XDG underscore shell. It's just unstable at the moment and it's part of the WALen protocol repository that I mentioned before but it's the detailed factor of standard that you should be using and the one that is in core WALen which is called WAL underscore shell it's effectively deprecated and you shouldn't be really using it anymore. There's a stable version of XDG shell that's already there but not many servers are supporting it yet. So for the moment this is still your best bet you should be using XDG shell version 6. And if it's ever replaced by the stable version it's just a copy and paste job and you just remove the set prefix which means unstable and remove the version at the end and then you're good to go with the stable version. So how do you use that? You get the global, the XDG shell global, you use that to get an XDG surface object for the surface that you have created and then finally you get top level on the XDG surface and this top level object is then the role of your surface and top level in this case means just the top level window that the compositor will then put on screen. Not quite because the compositor will not put it on screen unless you put some content into the window. So how do you get the content? There are again two possibilities. You can render on the GPU or you can render on the CPU roughly speaking. If you render on the GPU and use Vulkan or EGL then you are pretty much covered because that is quite easy to do. The interoperability is great and you don't have to really set up much. If you use the CPU for rendering then it's a bit more complicated because you have to figure out how to get a shared memory buffer and how to share that with the compositor which is what I'm indicating here. You create a buffer and attach that to the surface and it's a bit more involved than the rendering on the GPU. And for rendering you could use either you already have your own renderer so when you are developing an OpenGL based game then you will just use that to render the game. Or for 2D drawing you could use a Kyro or the Skiar project which the Chromium guys have developed. Okay, that's it for the window. If you do all that then you will actually have a window screen and you want some interactivity probably. That means how do you get input. There is a concept called a seed which is a group of input devices, a pointer or a keyboard and a touch device. And each seed can have at most one of those devices. You register for the global then you take the seed and these seeds can actually be hot plugged at runtime so you should always be prepared that the seed appears or disappears and your application should handle that and not just fresh then which would be a very bad. And then via the seed you can get access to the point of the keyboard and the touch. And for the pointer there's a special thing that you have to take care of setting the cursor. As soon as the pointer enters your window you have to give the WailingCompositor an image that it has to use but there is the Wailing Client library which handles most of it and loads just the regular old methods of things. For the keyboard then the server sends you just simple key events when something is pressed but you have to decode them with a lab xkb common because the server will also send you the key map that the user is using. So you have to go through that to translate the keys to what actually was pressed. How do you set stuff actually in C because I've not shown you any code I guess. There's the C library which is called Wailing Client and all the other stuff is currently built on top of that. So it's like xkb or xlib. And if you're coding in C then you should be using that as not really an alternative. And you have to use the executable Wailing Scanner for any extra protocols that you might be using from XML files to generate the C code to interface. If you want to integrate this into your event loop then you should be taking care to use a proper API. So just see the documentation if you want to do that. And for starting out I recommend downloading the source for western the reference compositor and look at these files. Simple shm.c and simple lgl.c which are just demo clients that are very minimal but do enough that you can just show the window and get some input. So it's really the best way to start getting your hands dirty. If you want to use threads in your application then it is supported by a Wailing Client but you have to be careful and take some precautions which are again available in the documentation. There are some bindings to other languages if C is not your thing. I try to list the ones that are most stable at the moment which you can see here. In the slides that you download these are all links you can just click on if you're interested in that. But the state of maintenance is various between the bindings and the Wailing Client is actually your best bet if you want just something stable. So now you have written your client you want to actually test it and either you are lucky and you are already using Wailing on your desktop then you can just run your application and if not it's also not a problem because you can run a Wailing Compositor on top of X11 or on top of Wailing in nested mode which is kind of like XA here if you have used that on X11. This is just a list of compositor I would recommend you to test on with the recommended versions that you should be using and how to start them in nested mode. If you have an environment variable Wailing underscore display you can instruct the application to start on another Wailing display server it's like the X11 display environment variable so if you run GNOME normally and want to test on another compositor like Western then you can just start that in nested mode and start the application there. I would always advise you to test at least on Western because it is reference compositor most strict about the protocol. You might want to skip KDE and Enlightenment for the moment because they don't have a stable released version that supports XDG shell version 6 as far as I know at the moment but they are working on it. Very useful is setting the environment variable Wailing underscore debug 1 when starting application then you will just get on standard I think just a trace of all API calls that you are doing on the Wailing socket which is very useful. You see everything you send to the server you see everything sends you back and can look for problems and information. If you want to just see what kind of globals and your compositor supports you can use the Western info executable which is a part of Western even though it's called Western info you can actually use it with any compositor to just gather information on what kind of interfaces are available. Since many compositors and also the Vailer project in itself are not that well established like Excel 11 yet if you encounter really weird stuff like while testing like this then sometimes the bug is in the compositor and you have to be prepared for that. There's a lot more to this. We've only barely scratched the surface here due to time constraints. I haven't talked about stuff like clip or drag and drop subsurface or how to really use XTG underscore shell because it's a lot more complicated than on that slide and it also has more restrictions than using just XT11. For example if you maximize your window then the compositor will exactly tell you how big your window is and if you attach a buffer of any different size then your connection will just be killed. So if you're not very careful while implementing that then you're going to run into big problems. You have to design this in from the start that you never attach a buffer of the wrong size. You should be thinking twice before not using a toolkit because it really helps a lot and saves a lot of effort and for just some further resources you could be looking into the project home page of Wayland has the main protocol and the CEAPI documentation. If you want to use some extra product tools then these are documented just in the XML files. It's very human readable I think. The blog of Pekka Perlin has some interviews of some technical aspects of western and Wayland which I highly recommend for reading and if you have any specific questions or problems then the Wayland community are very eager to help. You can just ask on the HedgeWayland IRC General and FreeNode or at the mailing list and I also use that to great effect during my summer of code project and I really want to thank these guys because they have been really helpful so you should not be shy to just ask if you have any questions. And again in the slides these are just links so if that interests you you can just download them and click on it. Okay that's it from my side. Thank you for being here and just sing to me. Do you have any questions? Okay the question was what is the actual protocol between the Wayland client and server. It is a custom protocol and the wire format is documented on the web page and it basically just encodes the request that you send into numbers that are calculated from the XML description and it serializes that and de-serializes on the other side. But the documentation on that is very good if you want to look at the details it's on the home page. Okay the question was whether it's like X11 due to socket support yeah kind of you usually use a Unix domain socket on Linux but the difference to access mostly that it's not as network transparent so you usually can't just use that over a TCP socket because you are sharing file descriptors via the socket so you need to use a Unix socket. Okay the question was that in some project I think in the okay they got a patch for win support and in the patch they included the generated C code from Wayland scanner and the question was whether that is a good thing I think and it's not a good thing. You should always be generating the C code directly from the XML. The protocols are installed system wide or if you use custom ones then you can ship them with your project but you should not check them into source control because they are generated. You should always be using Wayland scanner to generate them. Any other questions? Okay then that's it thank you.