logo

drewdevault.com

[mirror] blog and personal website of Drew DeVault git clone https://hacktivis.me/git/mirror/drewdevault.com.git

Writing-a-wayland-compositor-part-3.md (11060B)

    

  1. ---
  2. date: 2018-02-28
  3. layout: post
  4. title: "Writing a Wayland Compositor, Part 3: Rendering a window"
  5. tags: [wayland, wlroots, instructional]
  6. ---
  8. This is the third in a series of articles on the subject of writing a Wayland
  9. compositor from scratch using [wlroots](https://github.com/swaywm/wlroots).
  10. Check out [the first article](/2018/02/17/Writing-a-Wayland-compositor-1.html)
  11. if you haven't already. We left off with a Wayland server which accepts client
  12. connections and exposes a handful of globals, but does not do anything
  13. particularly interesting yet. Our goal today is to do something interesting -
  14. render a window!
  16. The commit that this article dissects is
  17. [342b7b6](https://github.com/SirCmpwn/mcwayland/commit/342b7b6).
  19. The first thing we have to do in order to render windows is establish the
  20. **compositor**. The wl_compositor global is used by clients to allocate
  21. `wl_surface`s, to which they attach `wl_buffer`s. These surfaces are just a
  22. generic mechanism for sharing buffers of pixels with compositors, and don't
  23. carry an implicit **role**, such as "application window" or "panel".
  25. wlroots provides an implementation of `wl_compositor`. Let's set aside a
  26. reference for it:
  28. ```diff
  29. struct mcw_server {
  30.         struct wl_display *wl_display;
  31.         struct wl_event_loop *wl_event_loop;
  32.  
  33.         struct wlr_backend *backend;
  34. +       struct wlr_compositor *compositor;
  35.  
  36.         struct wl_listener new_output;
  37. ```
  39. Then rig it up:
  41. ```diff
  42.         wlr_primary_selection_device_manager_create(server.wl_display);
  43.         wlr_idle_create(server.wl_display);
  44.  
  45. +       server.compositor = wlr_compositor_create(server.wl_display,
  46. +                       wlr_backend_get_renderer(server.backend));
  47. +
  48.         wl_display_run(server.wl_display);
  49.         wl_display_destroy(server.wl_display);
  50. ```
  52. If we run mcwayface now and check out the globals with `weston-info`, we'll see
  53. a wl_compositor and wl_subcompositor have appeared:
  55. ```
  56. interface: 'wl_compositor', version: 4, name: 8
  57. interface: 'wl_subcompositor', version: 1, name: 9
  58. ```
  60. You get a wl_subcompositor for free with the wlroots wl_compositor
  61. implementation. We'll discuss subcompositors in a later article. Speaking of
  62. things we'll discuss in another article, add this too:
  64. ```diff
  65.         wlr_primary_selection_device_manager_create(server.wl_display);
  66.         wlr_idle_create(server.wl_display);
  67.  
  68.         server.compositor = wlr_compositor_create(server.wl_display,
  69.                         wlr_backend_get_renderer(server.backend));
  70.  
  71. +       wlr_xdg_shell_v6_create(server.wl_display);
  72. +
  73.         wl_display_run(server.wl_display);
  74.         wl_display_destroy(server.wl_display);
  75.         return 0;
  76. ```
  78. Remember that I said earlier that surfaces are just globs of pixels with no
  79. role? xdg_shell is something that can give surfaces a role. We'll talk about it
  80. more in the next article. After adding this, many clients will be able to
  81. connect to your compositor and spawn a window. However, without adding anything
  82. else, these windows will never be shown on-screen. You have to render them!
  84. Something that distinguishes wlroots from libraries like wlc and libweston is
  85. that wlroots does not do any rendering for you. This gives you a lot of
  86. flexibility to render surfaces any way you like. The clients just gave you a
  87. pile of pixels, what you do with them is up to you - maybe you're making a
  88. desktop compositor, or maybe you want to draw them on an Android-style app
  89. switcher, or perhaps your compositor arranges windows in VR - all of this is
  90. possible with wlroots.
  92. Things are about to get complicated, so let's start with the easy part: in
  93. the output_frame handler, we have to get a reference to every wlr_surface we
  94. want to render. So let's iterate over every surface our `wlr_compositor` is
  95. keeping track of:
  97. ```diff
  98.         wlr_renderer_begin(renderer, wlr_output);
  100. +       struct wl_resource *_surface;
  101. +       wl_resource_for_each(_surface, &server->compositor->surfaces) {
  102. +               struct wlr_surface *surface = wlr_surface_from_resource(_surface);
  103. +               if (!wlr_surface_has_buffer(surface)) {
  104. +                       continue;
  105. +               }
  106. +               // TODO: Render this surface
  107. +       }
  109.         wlr_output_swap_buffers(wlr_output, NULL, NULL);
  110. ```
  112. The `wlr_compositor` struct has a member named `surfaces`, which is a list of
  113. `wl_resource`s. A helper method is provided to produce a `wlr_surface` from its
  114. corresponding `wl_resource`. The `wlr_surface_has_buffer` call is just to make
  115. sure that the client has actually given us pixels to display on this surface.
  117. wlroots might make you do the rendering yourself, but some tools *are* provided
  118. to help you write compositors with simple rendering requirements:
  119. **wlr_renderer**. We've already touched on this a little bit, but now we're
  120. going to use it for real. A little bit of OpenGL knowledge is required here. If
  121. you're a complete novice with OpenGL[^1], I can recommend [this
  122. tutorial](https://learnopengl.com/) to help you out. Since you're in a hurry,
  123. we'll do a quick crash course on the concepts necessary to utilize wlr_renderer.
  124. If you get lost, just skip to the next diff and treat it as magic incantations
  125. that make your windows appear.
  127. We have a pile of pixels, and we want to put it on the screen. We can do this
  128. with a **shader**. If you're using wlr_renderer (and mcwayface will be), shaders
  129. are provided for you. To use our shaders, we feed them a **texture** (the pile
  130. of pixels) and a **matrix**. If we treat every pixel coordinate on our surface
  131. as a vector from (0, 0); top left, to (1, 1); bottom right, our goal is to
  132. produce a matrix that we can multiply a vector by to find the final coordinates
  133. on-screen for the pixel to be drawn to. We must project pixel coordinates from
  134. this 0-1 system to the coordinates of our desired rectangle on screen.
  136. There's gotcha here, however: the coordinates on-screen *also* go from 0 to 1,
  137. instead of, for example, 0-1920 and 0-1080. To project coordinates like
  138. "put my 640x480 window at coordinates 100,100" to screen coordinates, we use an
  139. **orthographic projection matrix**. I know that sounds scary, but don't worry -
  140. wlroots does all of the work for you. Your `wlr_output` already has a suitable
  141. matrix called `transform_matrix`, which incorporates into it the current
  142. resolution, scale factor, and rotation of your screen.
  144. Okay, hopefully you're still with me. This sounds a bit complicated, but the
  145. manifestation of all of this nonsense is fairly straightforward. wlroots
  146. provides some tools to make it easy for you. First, we have to prepare a
  147. `wlr_box` that represents (in output coordinates) where we want the surface to
  148. show up.
  150. ```diff
  151.         struct wl_resource *_surface;
  152.         wl_resource_for_each(_surface, &server->compositor->surfaces) {
  153.                 struct wlr_surface *surface = wlr_surface_from_resource(_surface);
  154.                 if (!wlr_surface_has_buffer(surface)) {
  155.                         continue;
  156.                 }
  157. -               // TODO: Render this surface
  158. +               struct wlr_box render_box = {
  159. +                       .x = 20, .y = 20,
  160. +                       .width = surface->current->width,
  161. +                       .height = surface->current->height
  162. +               };
  163.         }
  164. ```
  166. Now, here's the great part: all of that fancy math I was just talking about can
  167. be done with a single helper function provided by wlroots: `wlr_matrix_project_box`.
  169. ```diff
  170.         struct wl_resource *_surface;
  171.         wl_resource_for_each(_surface, &server->compositor->surfaces) {
  172.                 struct wlr_surface *surface = wlr_surface_from_resource(_surface);
  173.                 if (!wlr_surface_has_buffer(surface)) {
  174.                         continue;
  175.                 }
  176.                 struct wlr_box render_box = {
  177.                         .x = 20, .y = 20,
  178.                         .width = surface->current->width,
  179.                         .height = surface->current->height
  180.                 };
  181. +               float matrix[16];
  182. +               wlr_matrix_project_box(&matrix, &render_box,
  183. +                               surface->current->transform,
  184. +                               0, &wlr_output->transform_matrix);
  185.         }
  186. ```
  188. This takes a reference to a `float[16]` to store the output matrix in, a box you
  189. want to project, some other stuff that isn't important right now, and the
  190. projection you want to use - in this case, we just use the one provided by
  191. `wlr_output`.
  193. The reason we make you understand and perform these steps is because it's
  194. entirely possible that you'll want to do them differently in the future. This
  195. is only the simplest case, but remember that wlroots is designed for *every*
  196. case. Now that we've obtained this matrix, we can finally render the surface:
  198. ```diff
  199.         struct wl_resource *_surface;
  200.         wl_resource_for_each(_surface, &server->compositor->surfaces) {
  201.                 struct wlr_surface *surface = wlr_surface_from_resource(_surface);
  202.                 if (!wlr_surface_has_buffer(surface)) {
  203.                         continue;
  204.                 }
  205.                 struct wlr_box render_box = {
  206.                         .x = 20, .y = 20,
  207.                         .width = surface->current->width,
  208.                         .height = surface->current->height
  209.                 };
  210.                 float matrix[16];
  211.                 wlr_matrix_project_box(&matrix, &render_box,
  212.                                 surface->current->transform,
  213.                                 0, &wlr_output->transform_matrix);
  214. +               wlr_render_with_matrix(renderer, surface->texture, &matrix, 1.0f);
  215. +               wlr_surface_send_frame_done(surface, &now);
  216.         }
  217. ```
  219. We also throw in a `wlr_surface_send_frame_done` for good measure, which lets
  220. the client know that we're done with it so they can send another frame. We're
  221. done! Run mcwayface now, then the following commands:
  223. ```
  224. $ WAYLAND_DISPLAY=wayland-1 weston-simple-shm &
  225. $ WAYLAND_DISPLAY=wayland-1 gnome-terminal -- htop
  226. ```
  228. To see the following beautiful image:
  230. ![](https://sr.ht/y_qN.png)
  232. Run any other clients you like - many of them will work!
  234. We used a bit of a hack today by simply rendering all of the surfaces the
  235. `wl_compositor` knew of. In practice, we're going to need to extend our
  236. xdg_shell support (and add some other shells, too) to do this properly. We'll
  237. cover this in the next article.
  239. Before you go, a quick note: after this commit, I reorganized things a bit -
  240. we're going to outgrow this single-file approach pretty quickly soon. Check out
  241. That commit [here](https://github.com/SirCmpwn/mcwayface/commit/e800facb371c42d844b858af5ced456ffd6e9d08).
  243. See you next time!
  245. <p>
  246.     Previous &mdash;
  247.     <a href="/2018/02/22/Writing-a-wayland-compositor-part-2.html">
  248.         Part 2: Rigging up the server
  249.     </a>
  250. </p>
  252. [^1]: If you're not a novice, we'll cover more complex rendering scenarios in the future. But the short of it is that you can implement your own `wlr_renderer` that wlr_compositor can use to bind textures to the GPU and then you can do whatever you want.