Merge pull request 'Implement wallpapers for outputs' (#10) from wallpaper into main

Reviewed-on: https://codeberg.org/bwbuhse/beansprout/pulls/10

README.md

@@ -10,8 +10,10 @@ SPDX-License-Identifier: GPL-3.0-or-later
 
 These are in rough order of my priority, though no promises I do them in this order.
 
-- [ ] Support wallpapers
+- [ ] Switch all structs to idiomatic Zig init/deinit pattern (init returns value, caller decides stack/heap)
-- [ ] Support a bar
+- [ ] Implement runtime log levels
+- [ ] Support per-host config using properties
+- [ ] Support a basic bar
 - [ ] Support starting programs at WM launch
 - [ ] Support overriding config location
 - [ ] Add support for multimedia/brightness keys
@@ -21,4 +23,5 @@ These are in rough order of my priority, though no promises I do them in this or
 - [x] Support changeable primary ratio
 - [x] Support changeable primary count
 - [x] Support multiple outputs
-- [X] Support floating windows
+- [x] Support floating windows
+- [x] Support wallpapers

build.zig

@@ -18,16 +18,23 @@ pub fn build(b: *std.Build) void {
     // Rest of the deps
     const kdl = b.dependency("kdl", .{}).module("kdl");
     const known_folders = b.dependency("known_folders", .{}).module("known-folders");
+    const pixman = b.dependency("pixman", .{}).module("pixman");
     const xkbcommon = b.dependency("xkbcommon", .{}).module("xkbcommon");
+    const zigimg = b.dependency("zigimg", .{}).module("zigimg");
 
     scanner.addCustomProtocol(b.path("protocol/river-window-management-v1.xml"));
     scanner.addCustomProtocol(b.path("protocol/river-xkb-bindings-v1.xml"));
+    scanner.addCustomProtocol(b.path("protocol/river-layer-shell-v1.xml"));
+    scanner.addSystemProtocol("stable/xdg-shell/xdg-shell.xml"); // dep of wlr-layer-shell-unstable-v1
+    scanner.addCustomProtocol(b.path("protocol/wlr-layer-shell-unstable-v1.xml"));
 
     scanner.generate("wl_compositor", 4);
     scanner.generate("wl_shm", 1);
     scanner.generate("wl_output", 4);
     scanner.generate("river_window_manager_v1", 3);
     scanner.generate("river_xkb_bindings_v1", 2);
+    scanner.generate("river_layer_shell_v1", 1);
+    scanner.generate("zwlr_layer_shell_v1", 3);
 
     const exe = b.addExecutable(.{
         .name = "beansprout",
@@ -42,12 +49,15 @@ pub fn build(b: *std.Build) void {
 
     // Make sure to also add new imports to the exe_check step
     exe.root_module.addImport("wayland", wayland);
-    exe.root_module.addImport("xkbcommon", xkbcommon);
     exe.root_module.addImport("kdl", kdl);
     exe.root_module.addImport("known_folders", known_folders);
+    exe.root_module.addImport("pixman", pixman);
+    exe.root_module.addImport("xkbcommon", xkbcommon);
+    exe.root_module.addImport("zigimg", zigimg);
 
     exe.linkLibC();
     exe.linkSystemLibrary("wayland-client");
+    exe.linkSystemLibrary("pixman-1");
     exe.linkSystemLibrary("xkbcommon");
 
     b.installArtifact(exe);
@@ -90,14 +100,17 @@ pub fn build(b: *std.Build) void {
     });
 
     exe_check.root_module.addImport("wayland", wayland);
-    exe_check.root_module.addImport("xkbcommon", xkbcommon);
     exe_check.root_module.addImport("kdl", kdl);
     exe_check.root_module.addImport("known_folders", known_folders);
+    exe_check.root_module.addImport("pixman", pixman);
+    exe_check.root_module.addImport("xkbcommon", xkbcommon);
+    exe_check.root_module.addImport("zigimg", zigimg);
 
     exe_check.linkLibC();
     exe_check.linkSystemLibrary("wayland-client");
+    exe_check.linkSystemLibrary("pixman-1");
     exe_check.linkSystemLibrary("xkbcommon");
 
-    const check = b.step("check", "Check if beanbag compiles");
+    const check = b.step("check", "Check if beansprout compiles");
     check.dependOn(&exe_check.step);
 }

build.zig.zon

@@ -24,6 +24,14 @@
             .url = "https://github.com/ziglibs/known-folders/archive/83d39161eac2ed6f37ad3cb4d9dd518696ce90bb.tar.gz",
             .hash = "known_folders-0.0.0-Fy-PJv3LAAABBRVoZWVrKZdyLoUfl5VRY5fqRRRdnF5L",
         },
+        .pixman = .{
+            .url = "https://codeberg.org/ifreund/zig-pixman/archive/387f04a0289a69d159c88b5f70396ec12a8ddb00.tar.gz",
+            .hash = "pixman-0.4.0-dev-LClMn0eVAAAlXnMK-MVBZkOG0urNdOPGVQdaGecXPM5O",
+        },
+        .zigimg = .{
+            .url = "https://github.com/zigimg/zigimg/archive/fb74dfb7c6d83f2bd01a229826669451525a4ba8.tar.gz",
+            .hash = "zigimg-0.1.0-8_eo2kSGFwADIkeZYTgfnLOV-khh6ZRoGmK6F2-s_QbY",
+        },
     },
 
     .paths = .{

examples/config.kdl

@@ -4,6 +4,10 @@ attach_mode top
 focus_follows_pointer #true
 // Whether the focus should warp to the center of newly-focused windows
 pointer_warp_on_focus_change #true
+// Path to image to use as wallpaper
+// The same image is displayed on all outputs, but scaled separately
+// If this config is missing, then the background is blank black screen
+wallpaper_image_path "~/Pictures/the_valley.png"
 borders {
     width 2
     // 8 or 10 digit hex color

protocol/river-layer-shell-v1.xml

@@ -0,0 +1,192 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="river_layer_shell_v1">
+  <copyright>
+    SPDX-FileCopyrightText: © 2025 Isaac Freund
+    SPDX-License-Identifier: MIT
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy
+    of this software and associated documentation files (the "Software"), to
+    deal in the Software without restriction, including without limitation the
+    rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+    sell copies of the Software, and to permit persons to whom the Software is
+    furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in
+    all copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+    IN THE SOFTWARE.
+  </copyright>
+
+  <description summary="layer shell support for river">
+    This protocol allows the river-window-management-v1 window manager to
+    support the wlr-layer-shell-v1 protocol.
+
+    The key words "must", "must not", "required", "shall", "shall not",
+    "should", "should not", "recommended", "may", and "optional" in this
+    document are to be interpreted as described in IETF RFC 2119.
+
+    Warning! The protocol described in this file is currently in the testing
+    phase. Backward compatible changes may be added together with the
+    corresponding interface version bump. Backward incompatible changes can only
+    be done by creating a new major version of the extension.
+  </description>
+
+  <interface name="river_layer_shell_v1" version="1">
+    <description summary="river layer shell global interface">
+      This global interface should only be advertised to the client if the
+      river_window_manager_v1 global is also advertised. Binding this interface
+      indicates that the window manager supports layer shell.
+
+      If the window manager does not bind this interface, the compositor should
+      not allow clients to map layer surfaces. This can be achieved by
+      closing layer surfaces immediately.
+    </description>
+
+    <enum name="error">
+      <entry name="object_already_created" value="0"
+        summary="the layer_shell_output/seat object was already created."/>
+    </enum>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy the river_layer_shell_v1 object">
+        This request indicates that the client will no longer use the
+        river_layer_shell_v1 object.
+      </description>
+    </request>
+
+    <request name="get_output">
+      <description summary="get layer shell output state">
+        It is a protocol error to make this request more than once for a given
+        river_output_v1 object.
+      </description>
+      <arg name="id" type="new_id" interface="river_layer_shell_output_v1"/>
+      <arg name="output" type="object" interface="river_output_v1"/>
+    </request>
+
+    <request name="get_seat">
+      <description summary="get layer shell seat state">
+        It is a protocol error to make this request more than once for a given
+        river_seat_v1 object.
+      </description>
+      <arg name="id" type="new_id" interface="river_layer_shell_seat_v1"/>
+      <arg name="seat" type="object" interface="river_seat_v1"/>
+    </request>
+  </interface>
+
+  <interface name="river_layer_shell_output_v1" version="1">
+    <description summary="layer shell output state">
+      The lifetime of this object is tied to the corresponding river_output_v1.
+      This object is made inert when the river_output_v1.removed event is sent
+      and should be destroyed.
+    </description>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy the object">
+        This request indicates that the client will no longer use the
+        river_layer_shell_output_v1 object and that it may be safely destroyed.
+
+        This request should be made after the river_output_v1.removed event is
+        received to complete destruction of the output.
+      </description>
+    </request>
+
+    <event name="non_exclusive_area">
+      <description summary="area left after subtracting exclusive zones">
+        This event indicates the area of the output remaining after subtracting
+        the exclusive zones of layer surfaces. Exclusive zones are a hint, the
+        window manager is free to ignore this area hint if it wishes.
+
+        The x and y values are in the global coordinate space, not relative to
+        the position of the output.
+
+        This event will be followed by a manage_start event after all other new
+        state has been sent by the server.
+      </description>
+      <arg name="x" type="int"/>
+      <arg name="y" type="int"/>
+      <arg name="width" type="int"/>
+      <arg name="height" type="int"/>
+    </event>
+
+    <request name="set_default">
+      <description summary="Set default output for layer surfaces">
+        Mark this output as the default for new layer surfaces which do not
+        request a specific output themselves. This request overrides any
+        previous set_default request on any river_layer_shell_output_v1 object.
+
+        If no set_default request is made or if the default output is destroyed,
+        the default output is undefined until the next set_default request.
+
+        This request modifies window management state and may only be made as
+        part of a manage sequence, see the river_window_manager_v1 description.
+      </description>
+    </request>
+  </interface>
+
+  <interface name="river_layer_shell_seat_v1" version="1">
+    <description summary="layer shell seat state">
+      The lifetime of this object is tied to the corresponding river_seat_v1.
+      This object is made inert when the river_seat_v1.removed event is sent and
+      should be destroyed.
+    </description>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy the object">
+        This request indicates that the client will no longer use the
+        river_layer_shell_seat_v1 object and that it may be safely destroyed.
+
+        This request should be made after the river_seat_v1.removed event is
+        received to complete destruction of the seat.
+      </description>
+    </request>
+
+    <event name="focus_exclusive">
+      <description summary="">
+        A layer shell surface will be given exclusive keyboard focus at the end
+        of the manage sequence in which this event is sent. The window manager
+        may want to update window decorations or similar to indicate that no
+        window is focused.
+
+        Until the focus_non_exclusive or focus_none event is sent, all window
+        manager requests to change focus are ignored.
+
+        This event will be followed by a manage_start event after all other new
+        state has been sent by the server.
+      </description>
+    </event>
+
+    <event name="focus_non_exclusive">
+      <description summary="">
+        A layer shell surface will be given non-exclusive keyboard focus at the
+        end of the manage sequence in which this event is sent. The window
+        manager may want to update window decorations or similar to indicate
+        that no window is focused.
+
+        The window manager continues to control focus and may choose to focus a
+        different window/shell surface at any time. If the window manager sets
+        focus during the same manage sequence in which this event is sent, the
+        layer surface will not be focused.
+
+        This event will be followed by a manage_start event after all other new
+        state has been sent by the server.
+      </description>
+    </event>
+
+    <event name="focus_none">
+      <description summary="">
+        No layer shell surface will have keyboard focus at the end of the manage
+        sequence in which this event is sent. The window manager may want to
+        return focus to whichever window last had focus, for example.
+
+        This event will be followed by a manage_start event after all other new
+        state has been sent by the server.
+      </description>
+    </event>
+  </interface>
+</protocol>

protocol/wlr-layer-shell-unstable-v1.xml

@@ -0,0 +1,390 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="wlr_layer_shell_unstable_v1">
+  <copyright>
+    Copyright © 2017 Drew DeVault
+
+    Permission to use, copy, modify, distribute, and sell this
+    software and its documentation for any purpose is hereby granted
+    without fee, provided that the above copyright notice appear in
+    all copies and that both that copyright notice and this permission
+    notice appear in supporting documentation, and that the name of
+    the copyright holders not be used in advertising or publicity
+    pertaining to distribution of the software without specific,
+    written prior permission.  The copyright holders make no
+    representations about the suitability of this software for any
+    purpose.  It is provided "as is" without express or implied
+    warranty.
+
+    THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS
+    SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+    FITNESS, IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY
+    SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+    WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
+    AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
+    ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
+    THIS SOFTWARE.
+  </copyright>
+
+  <interface name="zwlr_layer_shell_v1" version="4">
+    <description summary="create surfaces that are layers of the desktop">
+      Clients can use this interface to assign the surface_layer role to
+      wl_surfaces. Such surfaces are assigned to a "layer" of the output and
+      rendered with a defined z-depth respective to each other. They may also be
+      anchored to the edges and corners of a screen and specify input handling
+      semantics. This interface should be suitable for the implementation of
+      many desktop shell components, and a broad number of other applications
+      that interact with the desktop.
+    </description>
+
+    <request name="get_layer_surface">
+      <description summary="create a layer_surface from a surface">
+        Create a layer surface for an existing surface. This assigns the role of
+        layer_surface, or raises a protocol error if another role is already
+        assigned.
+
+        Creating a layer surface from a wl_surface which has a buffer attached
+        or committed is a client error, and any attempts by a client to attach
+        or manipulate a buffer prior to the first layer_surface.configure call
+        must also be treated as errors.
+
+        After creating a layer_surface object and setting it up, the client
+        must perform an initial commit without any buffer attached.
+        The compositor will reply with a layer_surface.configure event.
+        The client must acknowledge it and is then allowed to attach a buffer
+        to map the surface.
+
+        You may pass NULL for output to allow the compositor to decide which
+        output to use. Generally this will be the one that the user most
+        recently interacted with.
+
+        Clients can specify a namespace that defines the purpose of the layer
+        surface.
+      </description>
+      <arg name="id" type="new_id" interface="zwlr_layer_surface_v1"/>
+      <arg name="surface" type="object" interface="wl_surface"/>
+      <arg name="output" type="object" interface="wl_output" allow-null="true"/>
+      <arg name="layer" type="uint" enum="layer" summary="layer to add this surface to"/>
+      <arg name="namespace" type="string" summary="namespace for the layer surface"/>
+    </request>
+
+    <enum name="error">
+      <entry name="role" value="0" summary="wl_surface has another role"/>
+      <entry name="invalid_layer" value="1" summary="layer value is invalid"/>
+      <entry name="already_constructed" value="2" summary="wl_surface has a buffer attached or committed"/>
+    </enum>
+
+    <enum name="layer">
+      <description summary="available layers for surfaces">
+        These values indicate which layers a surface can be rendered in. They
+        are ordered by z depth, bottom-most first. Traditional shell surfaces
+        will typically be rendered between the bottom and top layers.
+        Fullscreen shell surfaces are typically rendered at the top layer.
+        Multiple surfaces can share a single layer, and ordering within a
+        single layer is undefined.
+      </description>
+
+      <entry name="background" value="0"/>
+      <entry name="bottom" value="1"/>
+      <entry name="top" value="2"/>
+      <entry name="overlay" value="3"/>
+    </enum>
+
+    <!-- Version 3 additions -->
+
+    <request name="destroy" type="destructor" since="3">
+      <description summary="destroy the layer_shell object">
+        This request indicates that the client will not use the layer_shell
+        object any more. Objects that have been created through this instance
+        are not affected.
+      </description>
+    </request>
+  </interface>
+
+  <interface name="zwlr_layer_surface_v1" version="4">
+    <description summary="layer metadata interface">
+      An interface that may be implemented by a wl_surface, for surfaces that
+      are designed to be rendered as a layer of a stacked desktop-like
+      environment.
+
+      Layer surface state (layer, size, anchor, exclusive zone,
+      margin, interactivity) is double-buffered, and will be applied at the
+      time wl_surface.commit of the corresponding wl_surface is called.
+
+      Attaching a null buffer to a layer surface unmaps it.
+
+      Unmapping a layer_surface means that the surface cannot be shown by the
+      compositor until it is explicitly mapped again. The layer_surface
+      returns to the state it had right after layer_shell.get_layer_surface.
+      The client can re-map the surface by performing a commit without any
+      buffer attached, waiting for a configure event and handling it as usual.
+    </description>
+
+    <request name="set_size">
+      <description summary="sets the size of the surface">
+        Sets the size of the surface in surface-local coordinates. The
+        compositor will display the surface centered with respect to its
+        anchors.
+
+        If you pass 0 for either value, the compositor will assign it and
+        inform you of the assignment in the configure event. You must set your
+        anchor to opposite edges in the dimensions you omit; not doing so is a
+        protocol error. Both values are 0 by default.
+
+        Size is double-buffered, see wl_surface.commit.
+      </description>
+      <arg name="width" type="uint"/>
+      <arg name="height" type="uint"/>
+    </request>
+
+    <request name="set_anchor">
+      <description summary="configures the anchor point of the surface">
+        Requests that the compositor anchor the surface to the specified edges
+        and corners. If two orthogonal edges are specified (e.g. 'top' and
+        'left'), then the anchor point will be the intersection of the edges
+        (e.g. the top left corner of the output); otherwise the anchor point
+        will be centered on that edge, or in the center if none is specified.
+
+        Anchor is double-buffered, see wl_surface.commit.
+      </description>
+      <arg name="anchor" type="uint" enum="anchor"/>
+    </request>
+
+    <request name="set_exclusive_zone">
+      <description summary="configures the exclusive geometry of this surface">
+        Requests that the compositor avoids occluding an area with other
+        surfaces. The compositor's use of this information is
+        implementation-dependent - do not assume that this region will not
+        actually be occluded.
+
+        A positive value is only meaningful if the surface is anchored to one
+        edge or an edge and both perpendicular edges. If the surface is not
+        anchored, anchored to only two perpendicular edges (a corner), anchored
+        to only two parallel edges or anchored to all edges, a positive value
+        will be treated the same as zero.
+
+        A positive zone is the distance from the edge in surface-local
+        coordinates to consider exclusive.
+
+        Surfaces that do not wish to have an exclusive zone may instead specify
+        how they should interact with surfaces that do. If set to zero, the
+        surface indicates that it would like to be moved to avoid occluding
+        surfaces with a positive exclusive zone. If set to -1, the surface
+        indicates that it would not like to be moved to accommodate for other
+        surfaces, and the compositor should extend it all the way to the edges
+        it is anchored to.
+
+        For example, a panel might set its exclusive zone to 10, so that
+        maximized shell surfaces are not shown on top of it. A notification
+        might set its exclusive zone to 0, so that it is moved to avoid
+        occluding the panel, but shell surfaces are shown underneath it. A
+        wallpaper or lock screen might set their exclusive zone to -1, so that
+        they stretch below or over the panel.
+
+        The default value is 0.
+
+        Exclusive zone is double-buffered, see wl_surface.commit.
+      </description>
+      <arg name="zone" type="int"/>
+    </request>
+
+    <request name="set_margin">
+      <description summary="sets a margin from the anchor point">
+        Requests that the surface be placed some distance away from the anchor
+        point on the output, in surface-local coordinates. Setting this value
+        for edges you are not anchored to has no effect.
+
+        The exclusive zone includes the margin.
+
+        Margin is double-buffered, see wl_surface.commit.
+      </description>
+      <arg name="top" type="int"/>
+      <arg name="right" type="int"/>
+      <arg name="bottom" type="int"/>
+      <arg name="left" type="int"/>
+    </request>
+
+    <enum name="keyboard_interactivity">
+      <description summary="types of keyboard interaction possible for a layer shell surface">
+        Types of keyboard interaction possible for layer shell surfaces. The
+        rationale for this is twofold: (1) some applications are not interested
+        in keyboard events and not allowing them to be focused can improve the
+        desktop experience; (2) some applications will want to take exclusive
+        keyboard focus.
+      </description>
+
+      <entry name="none" value="0">
+        <description summary="no keyboard focus is possible">
+          This value indicates that this surface is not interested in keyboard
+          events and the compositor should never assign it the keyboard focus.
+
+          This is the default value, set for newly created layer shell surfaces.
+
+          This is useful for e.g. desktop widgets that display information or
+          only have interaction with non-keyboard input devices.
+        </description>
+      </entry>
+      <entry name="exclusive" value="1">
+        <description summary="request exclusive keyboard focus">
+          Request exclusive keyboard focus if this surface is above the shell surface layer.
+
+          For the top and overlay layers, the seat will always give
+          exclusive keyboard focus to the top-most layer which has keyboard
+          interactivity set to exclusive. If this layer contains multiple
+          surfaces with keyboard interactivity set to exclusive, the compositor
+          determines the one receiving keyboard events in an implementation-
+          defined manner. In this case, no guarantee is made when this surface
+          will receive keyboard focus (if ever).
+
+          For the bottom and background layers, the compositor is allowed to use
+          normal focus semantics.
+
+          This setting is mainly intended for applications that need to ensure
+          they receive all keyboard events, such as a lock screen or a password
+          prompt.
+        </description>
+      </entry>
+      <entry name="on_demand" value="2" since="4">
+        <description summary="request regular keyboard focus semantics">
+          This requests the compositor to allow this surface to be focused and
+          unfocused by the user in an implementation-defined manner. The user
+          should be able to unfocus this surface even regardless of the layer
+          it is on.
+
+          Typically, the compositor will want to use its normal mechanism to
+          manage keyboard focus between layer shell surfaces with this setting
+          and regular toplevels on the desktop layer (e.g. click to focus).
+          Nevertheless, it is possible for a compositor to require a special
+          interaction to focus or unfocus layer shell surfaces (e.g. requiring
+          a click even if focus follows the mouse normally, or providing a
+          keybinding to switch focus between layers).
+
+          This setting is mainly intended for desktop shell components (e.g.
+          panels) that allow keyboard interaction. Using this option can allow
+          implementing a desktop shell that can be fully usable without the
+          mouse.
+        </description>
+      </entry>
+    </enum>
+
+    <request name="set_keyboard_interactivity">
+      <description summary="requests keyboard events">
+        Set how keyboard events are delivered to this surface. By default,
+        layer shell surfaces do not receive keyboard events; this request can
+        be used to change this.
+
+        This setting is inherited by child surfaces set by the get_popup
+        request.
+
+        Layer surfaces receive pointer, touch, and tablet events normally. If
+        you do not want to receive them, set the input region on your surface
+        to an empty region.
+
+        Keyboard interactivity is double-buffered, see wl_surface.commit.
+      </description>
+      <arg name="keyboard_interactivity" type="uint" enum="keyboard_interactivity"/>
+    </request>
+
+    <request name="get_popup">
+      <description summary="assign this layer_surface as an xdg_popup parent">
+        This assigns an xdg_popup's parent to this layer_surface.  This popup
+        should have been created via xdg_surface::get_popup with the parent set
+        to NULL, and this request must be invoked before committing the popup's
+        initial state.
+
+        See the documentation of xdg_popup for more details about what an
+        xdg_popup is and how it is used.
+      </description>
+      <arg name="popup" type="object" interface="xdg_popup"/>
+    </request>
+
+    <request name="ack_configure">
+      <description summary="ack a configure event">
+        When a configure event is received, if a client commits the
+        surface in response to the configure event, then the client
+        must make an ack_configure request sometime before the commit
+        request, passing along the serial of the configure event.
+
+        If the client receives multiple configure events before it
+        can respond to one, it only has to ack the last configure event.
+
+        A client is not required to commit immediately after sending
+        an ack_configure request - it may even ack_configure several times
+        before its next surface commit.
+
+        A client may send multiple ack_configure requests before committing, but
+        only the last request sent before a commit indicates which configure
+        event the client really is responding to.
+      </description>
+      <arg name="serial" type="uint" summary="the serial from the configure event"/>
+    </request>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy the layer_surface">
+        This request destroys the layer surface.
+      </description>
+    </request>
+
+    <event name="configure">
+      <description summary="suggest a surface change">
+        The configure event asks the client to resize its surface.
+
+        Clients should arrange their surface for the new states, and then send
+        an ack_configure request with the serial sent in this configure event at
+        some point before committing the new surface.
+
+        The client is free to dismiss all but the last configure event it
+        received.
+
+        The width and height arguments specify the size of the window in
+        surface-local coordinates.
+
+        The size is a hint, in the sense that the client is free to ignore it if
+        it doesn't resize, pick a smaller size (to satisfy aspect ratio or
+        resize in steps of NxM pixels). If the client picks a smaller size and
+        is anchored to two opposite anchors (e.g. 'top' and 'bottom'), the
+        surface will be centered on this axis.
+
+        If the width or height arguments are zero, it means the client should
+        decide its own window dimension.
+      </description>
+      <arg name="serial" type="uint"/>
+      <arg name="width" type="uint"/>
+      <arg name="height" type="uint"/>
+    </event>
+
+    <event name="closed">
+      <description summary="surface should be closed">
+        The closed event is sent by the compositor when the surface will no
+        longer be shown. The output may have been destroyed or the user may
+        have asked for it to be removed. Further changes to the surface will be
+        ignored. The client should destroy the resource after receiving this
+        event, and create a new surface if they so choose.
+      </description>
+    </event>
+
+    <enum name="error">
+      <entry name="invalid_surface_state" value="0" summary="provided surface state is invalid"/>
+      <entry name="invalid_size" value="1" summary="size is invalid"/>
+      <entry name="invalid_anchor" value="2" summary="anchor bitfield is invalid"/>
+      <entry name="invalid_keyboard_interactivity" value="3" summary="keyboard interactivity is invalid"/>
+    </enum>
+
+    <enum name="anchor" bitfield="true">
+      <entry name="top" value="1" summary="the top edge of the anchor rectangle"/>
+      <entry name="bottom" value="2" summary="the bottom edge of the anchor rectangle"/>
+      <entry name="left" value="4" summary="the left edge of the anchor rectangle"/>
+      <entry name="right" value="8" summary="the right edge of the anchor rectangle"/>
+    </enum>
+
+    <!-- Version 2 additions -->
+
+    <request name="set_layer" since="2">
+      <description summary="change the layer of the surface">
+        Change the layer that the surface is rendered on.
+
+        Layer is double-buffered, see wl_surface.commit.
+      </description>
+      <arg name="layer" type="uint" enum="zwlr_layer_shell_v1.layer" summary="layer to move this surface to"/>
+    </request>
+  </interface>
+</protocol>

src/Buffer.zig

@@ -0,0 +1,128 @@
+// SPDX-FileCopyrightText: 2026 Ben Buhse <me@benbuhse.email>
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+const Buffer = @This();
+
+width: u31,
+height: u31,
+stride: u31,
+
+busy: bool,
+size: u31,
+data: ?[]align(std.heap.page_size_min) u8,
+
+wl_buffer: *wl.Buffer,
+pixman_image: *pixman.Image,
+
+/// Used to add Buffers to a BufferPool
+node: std.DoublyLinkedList.Node = .{},
+
+pub fn init(shm: *wl.Shm, width: u31, height: u31) !Buffer {
+    // We use argb8888
+    const stride = width * 4;
+    const size: u31 = height * stride;
+
+    log.debug("initializing a new buffer with size {d}", .{size});
+
+    // Open a memory-backed file with sealing enabled
+    const fd = switch (builtin.target.os.tag) {
+        .linux => try posix.memfd_createZ("beansprout-shm-buffer", os.linux.MFD.CLOEXEC | os.linux.MFD.ALLOW_SEALING),
+        .freebsd => try posix.memfd_createZ("beansprout-shm-buffer", std.c.MFD.CLOEXEC | std.c.MFD.ALLOW_SEALING),
+        else => @compileError("target OS not supported"),
+    };
+    defer posix.close(fd);
+
+    // Try to allocate it to the desired size
+    try posix.ftruncate(fd, size);
+
+    // mmap the memory file for the pixman image
+    const data = mem.bytesAsSlice(
+        u8,
+        try posix.mmap(null, size, posix.PROT.READ | posix.PROT.WRITE, .{ .TYPE = .SHARED }, fd, 0),
+    );
+    errdefer posix.munmap(data);
+
+    // Seal the fd to prevent size changes. The compositor maps the same fd,
+    // so without sealing it could access invalid memory if the client resized it.
+    _ = try posix.fcntl(fd, seal.F_ADD_SEALS, seal.SEAL_GROW | seal.SEAL_SHRINK | seal.SEAL_SEAL);
+
+    // Create a Wayland shm buffer for the same memory file.
+    const pool = try shm.createPool(fd, size);
+    defer pool.destroy();
+
+    const wl_buffer = try pool.createBuffer(0, width, height, stride, .argb8888);
+    errdefer wl_buffer.destroy();
+
+    // Create the pixman image.
+    const pixman_image = pixman.Image.createBitsNoClear(
+        .a8r8g8b8,
+        @as(c_int, @intCast(width)),
+        @as(c_int, @intCast(height)),
+        @as([*c]u32, @ptrCast(data)),
+        @as(c_int, @intCast(stride)),
+    ) orelse return error.NoPixmanImage;
+
+    // The pixman image and the Wayland buffer now share the same memory.
+    return .{
+        .width = width,
+        .height = height,
+        .stride = stride,
+        .busy = true,
+        .size = size,
+        .wl_buffer = wl_buffer,
+        .data = data,
+        .pixman_image = pixman_image,
+    };
+}
+
+pub fn deinit(buffer: *Buffer) void {
+    _ = buffer.pixman_image.unref();
+    buffer.wl_buffer.destroy();
+    if (buffer.data) |data| posix.munmap(data);
+}
+
+// We have to do this later because of the way init() works
+pub fn setListener(buffer: *Buffer) void {
+    buffer.wl_buffer.setListener(*Buffer, buffer_listener, buffer);
+}
+
+fn buffer_listener(_: *wl.Buffer, event: wl.Buffer.Event, buffer: *Buffer) void {
+    switch (event) {
+        .release => buffer.busy = false,
+    }
+}
+
+const std = @import("std");
+const builtin = @import("builtin");
+const mem = std.mem;
+const os = std.os;
+const posix = std.posix;
+
+const wayland = @import("wayland");
+const wl = wayland.client.wl;
+const pixman = @import("pixman");
+
+const utils = @import("utils.zig");
+
+/// Sealing constants for memfd. Prevents the compositor from accessing
+/// invalid memory by locking the fd's size after setup.
+const seal = switch (builtin.target.os.tag) {
+    .linux => struct {
+        // Linux values are missing from stdlib right now,
+        // just take the values from fcntl.h
+        const F_ADD_SEALS: i32 = 1033;
+        const SEAL_SEAL: usize = 0x0001;
+        const SEAL_SHRINK: usize = 0x0002;
+        const SEAL_GROW: usize = 0x0004;
+    },
+    .freebsd => struct {
+        const F_ADD_SEALS = std.c.F.ADD_SEALS;
+        const SEAL_SEAL = std.c.F.SEAL_SEAL;
+        const SEAL_SHRINK = std.c.F.SEAL_SHRINK;
+        const SEAL_GROW = std.c.F.SEAL_GROW;
+    },
+    else => @compileError("target OS not supported"),
+};
+
+const log = std.log.scoped(.Buffer);

src/BufferPool.zig

@@ -0,0 +1,124 @@
+// SPDX-FileCopyrightText: 2026 Ben Buhse <me@benbuhse.email>
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+// Borrowed and adapted from https://git.sr.ht/~leon_plickat/wayprompt
+const BufferPool = @This();
+
+/// The amount of buffers per surface we consider the reasonable upper limit.
+/// Some compositors sometimes tripple-buffer, so three seems to be ok.
+/// Note that we can absolutely work with higher buffer numbers if needed,
+/// however we consider that to be an anomaly and therefore do not want to
+/// keep all those extra buffers around if we can avoid it, as to not have
+/// unecessary memory overhead.
+const max_buffer_multiplicity = 3;
+
+/// The buffers. This is a linked list and not an array list, because we
+/// need stable pointers for the listener of the wl_buffer object.
+buffers: DoublyLinkedList = .{},
+len: usize = 0,
+
+/// Number of surfaces sharing this pool, used to determine when to cull extra buffers.
+/// Each surface is allowed up to max_buffer_multiplicity buffers.
+surface_count: usize = 0,
+
+/// Deinit the buffer pool, destroying all buffers and freeing all memory.
+pub fn deinit(buffer_pool: *BufferPool) void {
+    var it = buffer_pool.buffers.first;
+    while (it) |node| {
+        // Advance before destroying, since node is embedded in buffer
+        it = node.next;
+        const buffer: *Buffer = @fieldParentPtr("node", node);
+        buffer.deinit();
+        utils.allocator.destroy(buffer);
+    }
+}
+
+/// Get a buffer with the specified dimensions. If possible, an idle buffer is
+/// reused, otherwise a new one is created.
+pub fn nextBuffer(buffer_pool: *BufferPool, wl_shm: *wl.Shm, width: u31, height: u31) !*Buffer {
+    log.debug("looking for buffer with dimensions {}x{}, total existing buffers: {}", .{ width, height, buffer_pool.len });
+    defer {
+        // Clear up extra buffers
+        if (buffer_pool.len > max_buffer_multiplicity * buffer_pool.surface_count) {
+            buffer_pool.cullBuffers();
+        }
+    }
+    if (try buffer_pool.findSuitableBuffer(wl_shm, width, height)) |buffer| {
+        return buffer;
+    } else {
+        return try buffer_pool.newBuffer(wl_shm, width, height);
+    }
+}
+
+/// Get the first free buffer with the specified dimensions.
+/// If there are no free buffers with the right dimensions, re-init a free buffer that
+/// has other dimensions. If no free buffer exists at all, return null.
+fn findSuitableBuffer(buffer_pool: *BufferPool, wl_shm: *wl.Shm, width: u31, height: u31) !?*Buffer {
+    var it = buffer_pool.buffers.first;
+    var first_unbusy_buffer: ?*Buffer = null;
+    while (it) |node| : (it = node.next) {
+        const buffer: *Buffer = @fieldParentPtr("node", node);
+        if (buffer.busy) continue;
+        if (buffer.width == width and buffer.height == height) {
+            buffer.busy = true;
+            return buffer;
+        } else {
+            first_unbusy_buffer = buffer;
+        }
+    }
+
+    // No buffer has matching dimensions, however we do have an unbusy
+    // buffer which we can just re-init.
+    if (first_unbusy_buffer) |buffer| {
+        buffer.deinit();
+        buffer.* = try Buffer.init(wl_shm, width, height);
+        buffer.setListener();
+        return buffer;
+    }
+
+    return null;
+}
+
+fn newBuffer(buffer_pool: *BufferPool, wl_shm: *wl.Shm, width: u31, height: u31) !*Buffer {
+    log.debug("creating new buffer {}x{}", .{ width, height });
+    const buffer = try utils.allocator.create(Buffer);
+    errdefer utils.allocator.destroy(buffer);
+    buffer.* = try Buffer.init(wl_shm, width, height);
+    buffer.setListener();
+    buffer_pool.buffers.append(&buffer.node);
+    buffer_pool.len += 1;
+    return buffer;
+}
+
+fn cullBuffers(buffer_pool: *BufferPool) void {
+    log.debug("culling extra buffers", .{});
+    var overhead = buffer_pool.len - max_buffer_multiplicity * buffer_pool.surface_count;
+    var it = buffer_pool.buffers.first;
+    while (it) |node| {
+        if (overhead == 0) break;
+        // Advance before destroying, since node is embedded in buffer
+        it = node.next;
+        const buffer: *Buffer = @fieldParentPtr("node", node);
+        if (!buffer.busy) {
+            buffer.deinit();
+            buffer_pool.buffers.remove(node);
+            utils.allocator.destroy(buffer);
+            buffer_pool.len -= 1;
+            overhead -= 1;
+        }
+    }
+    log.debug(" -> new buffer count: {}", .{buffer_pool.len});
+}
+
+const std = @import("std");
+const DoublyLinkedList = std.DoublyLinkedList;
+
+const wayland = @import("wayland");
+const wl = wayland.client.wl;
+
+const Buffer = @import("Buffer.zig");
+
+const utils = @import("utils.zig");
+
+const log = std.log.scoped(.BufferPool);

src/Config.zig

@@ -20,6 +20,10 @@ focus_follows_pointer: bool = true,
 /// Should the pointer warp to the center of newly-focused windows
 pointer_warp_on_focus_change: bool = true,
 
+// TODO: Implement a color when this is null
+/// Path to the wallpaper image
+wallpaper_image_path: ?[]const u8 = null,
+
 /// Tag bind entries parsed from config (tag_bind nodes in keybinds block)
 tag_binds: std.ArrayList(Keybind) = .{},
 keybinds: std.ArrayList(Keybind) = .{},
@@ -51,6 +55,7 @@ const NodeName = enum {
     attach_mode,
     focus_follows_pointer,
     pointer_warp_on_focus_change,
+    wallpaper_image_path,
     borders,
     keybinds,
     pointer_binds,
@@ -101,6 +106,9 @@ pub fn create() !*Config {
             config.keybinds.clearAndFree(utils.allocator);
             config.tag_binds.clearAndFree(utils.allocator);
             config.pointer_binds.clearAndFree(utils.allocator);
+            if (config.wallpaper_image_path) |path| {
+                utils.allocator.free(path);
+            }
             config.* = .{};
         };
     }
@@ -121,6 +129,9 @@ pub fn destroy(config: *Config) void {
     config.keybinds.deinit(utils.allocator);
     config.tag_binds.deinit(utils.allocator);
     config.pointer_binds.deinit(utils.allocator);
+    if (config.wallpaper_image_path) |path| {
+        utils.allocator.free(path);
+    }
     utils.allocator.destroy(config);
 }
 
@@ -175,6 +186,19 @@ fn load(config: *Config, reader: *Io.Reader) !void {
                                 continue;
                             }
                         },
+                        .wallpaper_image_path => {
+                            if (node.argcount() < 1) {
+                                logWarnMissingNodeArg(name, "image path");
+                                continue;
+                            }
+
+                            const path_str = utils.stripQuotes(node.arg(&parser, 0) orelse unreachable);
+                            config.wallpaper_image_path = expandTilde(path_str) catch {
+                                logWarnInvalidNodeArg(name, path_str);
+                                continue;
+                            };
+                            logDebugSettingNode(name, path_str);
+                        },
                         .borders => {
                             next_child_block = .borders;
                         },
@@ -543,6 +567,7 @@ fn logWarnInvalidNodeArg(node_name: anytype, node_value: []const u8) void {
 fn logWarnMissingNodeArg(node_name: anytype, comptime arg: []const u8) void {
     const node_name_type = @TypeOf(node_name);
     switch (node_name_type) {
+        NodeName => log.warn("\"{s}\" missing " ++ arg ++ " argument. Ignoring", .{@tagName(node_name)}),
         KeybindNodeName => log.warn("\"keybind.{s}\" missing " ++ arg ++ " argument. Ignoring", .{@tagName(node_name)}),
         PointerBindNodeName => log.warn("\"pointer_binds.{s}\" missing " ++ arg ++ " argument. Ignoring", .{@tagName(node_name)}),
         else => @compileError("This function does not (yet) support type \"" ++ @typeName(node_name_type) ++ "\""),
@@ -570,6 +595,14 @@ fn logDebugSettingNode(node_name: anytype, node_value: []const u8) void {
     }
 }
 
+fn expandTilde(path: []const u8) ![]const u8 {
+    if (path.len > 0 and path[0] == '~') {
+        const home = std.posix.getenv("HOME") orelse return error.HomeNotSet;
+        return std.fmt.allocPrint(utils.allocator, "{s}{s}", .{ home, path[1..] });
+    }
+    return utils.allocator.dupe(u8, path);
+}
+
 const std = @import("std");
 const fmt = std.fmt;
 const fs = std.fs;

src/Context.zig

@@ -10,14 +10,25 @@ const Context = @This();
 initialized: bool,
 
 // Wayland globals
+wl_compositor: *wl.Compositor,
 wl_display: *wl.Display,
 wl_registry: *wl.Registry,
-wl_compositor: *wl.Compositor,
+wl_shm: *wl.Shm,
+wl_outputs: *std.AutoHashMapUnmanaged(u32, *wl.Output),
 
-// Wayland globals that we have structs for
+zwlr_layer_shell_v1: *zwlr.LayerShellV1,
+
+// Wayland globals that we have special structs for
 wm: *WindowManager,
 xkb_bindings: *XkbBindings,
 
+/// Pool of Buffers used for rendering wallpapers
+buffer_pool: BufferPool = .{},
+
+/// Holds a pixman.Image (and its raw pixels) for the wallpaper
+/// (same image on all outputs, but scaled separately)
+wallpaper_image: ?*WallpaperImage,
+
 // WM Configuration
 config: *Config,
 
@@ -28,25 +39,39 @@ pub const PendingManage = struct {
     config: ?*Config = null,
 };
 
-pub fn create(
+// I use this because otherwise create() takes
+// a LOT of arguments.
+pub const Options = struct {
+    wl_compositor: *wl.Compositor,
     wl_display: *wl.Display,
     wl_registry: *wl.Registry,
-    wl_compositor: *wl.Compositor,
+    wl_shm: *wl.Shm,
+    wl_outputs: *std.AutoHashMapUnmanaged(u32, *wl.Output),
+
+    river_layer_shell_v1: *river.LayerShellV1, // TODO
     river_window_manager_v1: *river.WindowManagerV1,
     river_xkb_bindings_v1: *river.XkbBindingsV1,
+
+    zwlr_layer_shell_v1: *zwlr.LayerShellV1,
     config: *Config,
-) !*Context {
+};
+
+pub fn create(options: Options) !*Context {
     const context = try utils.allocator.create(Context);
     errdefer context.destroy();
 
     context.* = .{
         .initialized = false,
-        .wl_display = wl_display,
+        .wl_compositor = options.wl_compositor,
-        .wl_registry = wl_registry,
+        .wl_display = options.wl_display,
-        .wl_compositor = wl_compositor,
+        .wl_registry = options.wl_registry,
-        .wm = try WindowManager.create(context, river_window_manager_v1),
+        .wl_shm = options.wl_shm,
-        .xkb_bindings = try XkbBindings.create(context, river_xkb_bindings_v1),
+        .wl_outputs = options.wl_outputs,
-        .config = config,
+        .zwlr_layer_shell_v1 = options.zwlr_layer_shell_v1,
+        .wallpaper_image = loadWallpaperImage(options.config),
+        .wm = try WindowManager.create(context, options.river_window_manager_v1),
+        .xkb_bindings = try XkbBindings.create(context, options.river_xkb_bindings_v1),
+        .config = options.config,
     };
 
     return context;
@@ -56,6 +81,11 @@ pub fn destroy(context: *Context) void {
     context.xkb_bindings.destroy();
     context.wm.destroy();
 
+    if (context.wallpaper_image) |wallpaper_image| {
+        wallpaper_image.destroy();
+    }
+    context.buffer_pool.deinit();
+
     utils.allocator.destroy(context);
 }
 
@@ -69,20 +99,66 @@ pub fn manage(context: *Context) void {
             binding.link.remove();
             binding.destroy();
         }
+
+        // Check if wallpaper path changed before destroying old config
+        const wallpaper_changed = !pathsEqual(
+            context.config.wallpaper_image_path,
+            new_config.wallpaper_image_path,
+        );
+
         context.config.destroy();
         context.config = new_config;
         context.initialized = false;
+
+        if (wallpaper_changed) {
+            if (context.wallpaper_image) |img| img.destroy();
+            context.wallpaper_image = loadWallpaperImage(new_config);
+
+            var out_it = context.wm.outputs.iterator(.forward);
+            while (out_it.next()) |output| {
+                if (context.wallpaper_image == null) {
+                    output.deinitWallpaperLayerSurface();
+                } else if (output.wl_surface != null) {
+                    output.renderWallpaper() catch |err| {
+                        log.err("Wallpaper re-render failed: {}", .{err});
+                    };
+                } else {
+                    output.initWallpaperLayerSurface() catch |err| {
+                        log.err("Failed to init wallpaper surface: {}", .{err});
+                    };
+                }
+            }
+        }
     }
 }
 
+fn loadWallpaperImage(config: *Config) ?*WallpaperImage {
+    const image_path = config.wallpaper_image_path orelse return null;
+    if (image_path.len == 0) return null;
+    return WallpaperImage.create(image_path) catch |e| {
+        log.err("Failed to load wallpaper image from path \"{s}\": {s}", .{ image_path, @errorName(e) });
+        return null;
+    };
+}
+
+fn pathsEqual(a: ?[]const u8, b: ?[]const u8) bool {
+    const a_val = a orelse return b == null;
+    const b_val = b orelse return false;
+    return mem.eql(u8, a_val, b_val);
+}
+
 const std = @import("std");
+const mem = std.mem;
 
 const wayland = @import("wayland");
 const river = wayland.client.river;
 const wl = wayland.client.wl;
+const zwlr = wayland.client.zwlr;
 
 const utils = @import("utils.zig");
 const Config = @import("Config.zig");
+const BufferPool = @import("BufferPool.zig");
+const WallpaperImage = @import("WallpaperImage.zig");
 const WindowManager = @import("WindowManager.zig");
 const XkbBindings = @import("XkbBindings.zig");
 

src/Output.zig

@@ -8,11 +8,22 @@ context: *Context,
 
 river_output_v1: *river.OutputV1,
 
-width: i32 = 0,
+// We have to wait for the rwm.wl_output event to get this
-height: i32 = 0,
+wl_output: ?*wl.Output = null,
+
+// Output geometry
+scale: u31 = 1,
+width: u31 = 0,
+height: u31 = 0,
 x: i32 = 0,
 y: i32 = 0,
 
+// Information for this Output's wallpaper
+render_width: u31 = 0,
+render_height: u31 = 0,
+wl_surface: ?*wl.Surface = null,
+layer_surface: ?*zwlr.LayerSurfaceV1 = null,
+
 /// Proportion of output width taken by the primary stack
 primary_ratio: f32 = 0.55,
 
@@ -25,13 +36,19 @@ tags: u32 = 0x0001,
 /// State consumed in manage() phase, reset at end of manage().
 pending_manage: PendingManage = .{},
 
+// Friendly name of this output
+name: ?[]const u8 = null,
+
+/// Used for wallpaper rendering management
+configured: bool = false,
+
 windows: wl.list.Head(Window, .link),
 
 link: wl.list.Link,
 
 pub const PendingManage = struct {
-    width: ?i32 = null,
+    width: ?u31 = null,
-    height: ?i32 = null,
+    height: ?u31 = null,
     x: ?i32 = null,
     y: ?i32 = null,
 
@@ -53,7 +70,7 @@ pub fn create(context: *Context, river_output_v1: *river.OutputV1) !*Output {
 
     output.windows.init();
 
-    output.river_output_v1.setListener(*Output, outputListener, output);
+    output.river_output_v1.setListener(*Output, riverOutputListener, output);
 
     return output;
 }
@@ -65,6 +82,7 @@ pub fn destroy(output: *Output) void {
         window.destroy();
     }
 
+    output.deinitWallpaperLayerSurface();
     output.river_output_v1.destroy();
     utils.allocator.destroy(output);
 }
@@ -85,7 +103,8 @@ pub fn prevWindow(output: *Output, current: *Window) ?*Window {
     return @fieldParentPtr("link", prev_link);
 }
 
-fn outputListener(river_output_v1: *river.OutputV1, event: river.OutputV1.Event, output: *Output) void {
+// Used for the river_output_v1 interface
+fn riverOutputListener(river_output_v1: *river.OutputV1, event: river.OutputV1.Event, output: *Output) void {
     assert(output.river_output_v1 == river_output_v1);
     switch (event) {
         .removed => {
@@ -136,21 +155,245 @@ fn outputListener(river_output_v1: *river.OutputV1, event: river.OutputV1.Event,
             output.destroy();
         },
         .wl_output => |ev| {
-            log.debug("initializing new river_output_v1 corresponding to wl_output: {d}", .{ev.name});
+            // It's guaranteed for the wl_output global to advertised before this event happens
+            output.wl_output = output.context.wl_outputs.get(ev.name) orelse unreachable;
+            output.wl_output.?.setListener(*Output, wlOutputListener, output);
+
+            // The wl_output's initial events (mode, scale, name, done) were likely
+            // already delivered during the initial roundtrip before we set our
+            // listener, so the .done event that triggers wallpaper init was lost.
+            // Explicitly init the wallpaper surface here.
+            output.initWallpaperLayerSurface() catch |err| {
+                const output_name = output.name orelse "some output";
+                log.err("failed to add a surface to {s}: {}", .{ output_name, err });
+            };
         },
         .dimensions => |ev| {
-            output.pending_manage.width = ev.width;
+            // Protocol guarantees that width and height are strictly greater than zero
-            output.pending_manage.height = ev.height;
+            assert(ev.width > 0 and ev.height > 0);
-            output.context.wm.river_window_manager_v1.manageDirty();
+            output.pending_manage.width = @intCast(ev.width);
+            output.pending_manage.height = @intCast(ev.height);
         },
         .position => |ev| {
             output.pending_manage.x = ev.x;
             output.pending_manage.y = ev.y;
-            output.context.wm.river_window_manager_v1.manageDirty();
         },
     }
 }
 
+// Used for the wl_output global interface that corresponds to the river_output_v1
+fn wlOutputListener(_: *wl.Output, event: wl.Output.Event, output: *Output) void {
+    switch (event) {
+        .mode => |ev| {
+            if (ev.width < 0 or ev.height < 0) {
+                // I'm not actually sure if this is possible, but just to be safe
+                log.warn("Received wl_output.mode event with a negative width or height ({d}x{d})", .{ ev.width, ev.height });
+                return;
+            }
+
+            output.width = @intCast(ev.width);
+            output.height = @intCast(ev.height);
+        },
+        .done => {
+            output.initWallpaperLayerSurface() catch |err| {
+                const output_name = output.name orelse "some output";
+                log.err("failed to add a surface to {s}: {}", .{ output_name, err });
+                return;
+            };
+        },
+        .scale => |ev| {
+            if (ev.factor < 0) {
+                // I'm not actually sure if this is possible, but just to be safe
+                log.warn("Received wl_output.scale event with a negative factor ({d})", .{ev.factor});
+                return;
+            }
+            output.scale = @intCast(ev.factor);
+        },
+        .name => |ev| {
+            output.name = utils.allocator.dupe(u8, mem.span(ev.name)) catch @panic("Out of memory");
+        },
+        else => {},
+    }
+}
+
+pub fn initWallpaperLayerSurface(output: *Output) !void {
+    if (output.context.wallpaper_image == null) {
+        // No wallpaper image, so we don't need any surfaces
+        return;
+    }
+
+    if (output.wl_surface) |_| {
+        // This output already has a layer surface, we can exit early
+        return;
+    }
+
+    const context = output.context;
+
+    const wl_surface: *wl.Surface = try context.wl_compositor.createSurface();
+
+    // We don't want our surface to have any input region (default is infinite)
+    const empty_region: *wl.Region = try context.wl_compositor.createRegion();
+    defer empty_region.destroy();
+    wl_surface.setInputRegion(empty_region);
+
+    // Full surface should be opaque
+    const opaque_region: *wl.Region = try context.wl_compositor.createRegion();
+    defer opaque_region.destroy();
+    wl_surface.setOpaqueRegion(opaque_region);
+
+    const layer_surface: *zwlr.LayerSurfaceV1 = try context.zwlr_layer_shell_v1.getLayerSurface(wl_surface, output.wl_output, .background, "beansprout");
+    layer_surface.setExclusiveZone(-1);
+    layer_surface.setAnchor(.{ .top = true, .right = true, .bottom = true, .left = true });
+
+    output.wl_surface = wl_surface;
+    output.layer_surface = layer_surface;
+    context.buffer_pool.surface_count += 1;
+
+    layer_surface.setListener(*Output, wallpaperLayerSurfaceListener, output);
+    wl_surface.commit();
+}
+
+pub fn deinitWallpaperLayerSurface(output: *Output) void {
+    if (output.layer_surface) |layer_surface| {
+        layer_surface.destroy();
+    }
+    if (output.wl_surface) |wl_surface| {
+        wl_surface.destroy();
+        output.context.buffer_pool.surface_count -= 1;
+    }
+
+    output.layer_surface = null;
+    output.wl_surface = null;
+    output.configured = false;
+}
+
+fn wallpaperLayerSurfaceListener(layer_surface: *zwlr.LayerSurfaceV1, event: zwlr.LayerSurfaceV1.Event, output: *Output) void {
+    switch (event) {
+        .configure => |ev| {
+            layer_surface.ackConfigure(ev.serial);
+
+            if (ev.width < 0 or ev.height < 0) {
+                // I'm not actually sure if this is possible, but just to be safe
+                log.warn("Received zwlr_layer_surface_v1.configure event with a negative width or height ({d}x{d})", .{ ev.width, ev.height });
+                return;
+            }
+            const width: u31 = @intCast(ev.width);
+            const height: u31 = @intCast(ev.height);
+
+            if (output.configured and output.render_width == width and output.render_height == height) {
+                if (output.wl_surface) |wl_surface| {
+                    wl_surface.commit();
+                } else {
+                    log.warn("Output is marked as configured but is missing a layer_surface for the wallpaper", .{});
+                }
+                return;
+            }
+
+            log.debug("configuring wallpaper surface with width {} and height {}", .{ width, height });
+            output.render_width = width;
+            output.render_height = height;
+            output.configured = true;
+
+            output.renderWallpaper() catch |err| {
+                fatal("Wallpaper render failed: E{}", .{err});
+            };
+        },
+        .closed => {
+            output.deinitWallpaperLayerSurface();
+        },
+    }
+}
+
+/// Calculates image_dimension / (output_dimension * scale)
+fn calculate_scale(image_dimension: c_int, output_dimension: u31, scale: u31) f64 {
+    const numerator: f64 = @floatFromInt(image_dimension);
+    const denominator: f64 = @floatFromInt(output_dimension * scale);
+
+    return numerator / denominator;
+}
+
+/// Calculates (image_dimension / dimension_scale - output_dimension) / 2 / dimension_scale;
+fn calculate_transform(image_dimension: c_int, output_dimension: u31, dimension_scale: f64) f64 {
+    const numerator1: f64 = @floatFromInt(image_dimension);
+    const denominator1: f64 = dimension_scale;
+    const subtruend: f64 = @floatFromInt(output_dimension);
+    const numerator2: f64 = numerator1 / denominator1 - subtruend;
+
+    return numerator2 / 2 / dimension_scale;
+}
+
+/// Render the wallpaper image onto the layer surface
+pub fn renderWallpaper(output: *Output) !void {
+    const context = output.context;
+    const width = output.render_width;
+    const height = output.render_height;
+    const scale = output.scale;
+
+    // Don't have anything to render
+    if (width == 0 or height == 0 or scale == 0) {
+        return;
+    }
+    // Scale our loaded image and then copy it into the Buffer's pixman.Image
+    const wallpaper_image = context.wallpaper_image orelse return;
+    const image = wallpaper_image.image;
+    const image_data = image.getData();
+    const image_width = image.getWidth();
+    const image_height = image.getHeight();
+    const image_stride = image.getStride();
+    const image_format = image.getFormat();
+
+    const buffer: *Buffer = try context.buffer_pool.nextBuffer(context.wl_shm, width * scale, height * scale);
+
+    const pix = pixman.Image.createBitsNoClear(image_format, image_width, image_height, image_data, image_stride) orelse {
+        log.err("Failed to copy the wallpaper image for rendering", .{});
+        return error.ImageCopyError;
+    };
+    defer _ = pix.unref();
+
+    // Calculate image scale
+    var sx: f64 = @as(f64, @floatFromInt(image_width)) / @as(f64, @floatFromInt(width * scale));
+    var sy: f64 = calculate_scale(image_height, height, scale);
+
+    const s = if (sx > sy) sy else sx;
+    sx = s;
+    sy = s;
+
+    // Calculate translation offsets to center the image on the output.
+    // If the scaled image is larger than the output, the offset crops equally from both sides.
+    const tx: f64 = calculate_transform(image_width, width, sx);
+    const ty: f64 = calculate_transform(image_height, height, sy);
+
+    // Build a combined source-to-destination transform matrix.
+    // Pixman transforms map destination pixels back to source pixels, so:
+    //   t_scale: maps a destination pixel to the corresponding source pixel (scaling)
+    //   t_trans: shifts the sampling point to center the image
+    //   t = t_trans * t_scale: first scale, then translate (in source space)
+    var t_scale: pixman.FTransform = undefined;
+    var t_trans: pixman.FTransform = undefined;
+    var t: pixman.FTransform = undefined;
+    // t2 is the fixed-point version of t, which is what pixman actually uses internally
+    var t2: pixman.Transform = undefined;
+
+    pixman.FTransform.initScale(&t_scale, sx, sy);
+    pixman.FTransform.initTranslate(&t_trans, tx, ty);
+    pixman.FTransform.multiply(&t, &t_trans, &t_scale);
+    _ = pixman.Transform.fromFTransform(&t2, &t);
+    _ = pix.setTransform(&t2);
+    _ = pix.setFilter(.best, &[_]pixman.Fixed{}, 0);
+
+    // Combine the transformed source image into the buffer.
+    pixman.Image.composite32(.src, pix, null, buffer.pixman_image, 0, 0, 0, 0, 0, 0, width * scale, height * scale);
+
+    log.info("render: {}x{} (scaled from {}x{})", .{ width * scale, height * scale, image_width, image_height });
+
+    // Attach the buffer to the surface
+    const wl_surface = output.wl_surface.?;
+    wl_surface.setBufferScale(scale);
+    wl_surface.attach(buffer.wl_buffer, 0, 0);
+    wl_surface.damageBuffer(0, 0, width * scale, height * scale);
+    wl_surface.commit();
+}
+
 pub fn manage(output: *Output) void {
     defer output.pending_manage = .{};
 
@@ -316,13 +559,18 @@ fn calculatePrimaryStackLayout(output: *Output) void {
 
 const std = @import("std");
 const assert = std.debug.assert;
+const fatal = std.process.fatal;
+const mem = std.mem;
 const DoublyLinkedList = std.DoublyLinkedList;
 
 const wayland = @import("wayland");
 const wl = wayland.client.wl;
 const river = wayland.client.river;
+const zwlr = wayland.client.zwlr;
+const pixman = @import("pixman");
 
 const utils = @import("utils.zig");
+const Buffer = @import("Buffer.zig");
 const Context = @import("Context.zig");
 const Window = @import("Window.zig");
 

src/WallpaperImage.zig

@@ -0,0 +1,60 @@
+// SPDX-FileCopyrightText: 2026 Ben Buhse <me@benbuhse.email>
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+const WallpaperImage = @This();
+
+image: *pixman.Image,
+pixels: std.ArrayList(u32),
+
+// TODO: Make image_path nullable, if null, do a single color with a single_pixel_buffer instead(?)
+pub fn create(image_path: []const u8) !*WallpaperImage {
+    var wallpaper_image = try utils.allocator.create(WallpaperImage);
+    errdefer utils.allocator.destroy(wallpaper_image);
+
+    var read_buf: [zigimg.io.DEFAULT_BUFFER_SIZE]u8 = undefined;
+    var image = try zigimg.Image.fromFilePath(utils.allocator, image_path, &read_buf);
+    defer image.deinit(utils.allocator);
+
+    // We don't want to deal with all the possible formats,
+    // so let's just convert to one we can use with pixman.
+    if (image.pixelFormat() != .rgba32) {
+        try image.convert(utils.allocator, .rgba32);
+    }
+
+    log.debug("image loaded ({}x{})", .{ image.width, image.height });
+
+    const pixels = image.pixels.rgba32;
+    // We have to manually convert to argb --
+    // It's only guaranteed that Wayland compositors will have xrgb and argb support but zigimg doesn't have either of those.
+    wallpaper_image.pixels = try std.ArrayList(u32).initCapacity(utils.allocator, pixels.len);
+    errdefer wallpaper_image.pixels.deinit(utils.allocator);
+    for (0..pixels.len) |i| {
+        const a: u32 = @intCast(pixels[i].a);
+        const r: u32 = @intCast(pixels[i].r);
+        const g: u32 = @intCast(pixels[i].g);
+        const b: u32 = @intCast(pixels[i].b);
+        const new_val: u32 = (a << 24) + (r << 16) + (g << 8) + b;
+        wallpaper_image.pixels.appendAssumeCapacity(new_val);
+    }
+
+    wallpaper_image.image = pixman.Image.createBits(.a8r8g8b8, @intCast(image.width), @intCast(image.height), @ptrCast(@alignCast(wallpaper_image.pixels.items.ptr)), @intCast(image.width * image.pixelFormat().pixelStride())) orelse return error.FailedToCreatePixmanImage;
+
+    return wallpaper_image;
+}
+
+pub fn destroy(wallpaper_image: *WallpaperImage) void {
+    _ = wallpaper_image.image.unref();
+    wallpaper_image.pixels.deinit(utils.allocator);
+
+    utils.allocator.destroy(wallpaper_image);
+}
+
+const std = @import("std");
+
+const pixman = @import("pixman");
+const zigimg = @import("zigimg");
+
+const utils = @import("utils.zig");
+
+const log = std.log.scoped(.WallpaperImage);

src/Window.zig

@@ -35,8 +35,7 @@ pending_manage: PendingManage = .{},
 /// State consumed in render() phase, reset at end of render().
 pending_render: PendingRender = .{},
 
-/// Used to put Windows into a list in
+/// Used to put Windows into a list in calculatePrimaryStackLayout()
-/// WindowManager.calculatePrimaryStackLayout()
 active_list_node: DoublyLinkedList.Node = .{},
 
 link: wl.list.Link,
@@ -141,10 +140,10 @@ fn windowListener(river_window_v1: *river.WindowV1, event: river.WindowV1.Event,
             window.destroy();
         },
         .dimensions => |ev| {
-            // The protocol requires these are strictly greater than zero.
+            // Protocol guarantees that width and height are strictly greater than zero
             assert(ev.width > 0 and ev.height > 0);
-            window.width = @intCast(ev.width);
+            window.pending_manage.width = @intCast(ev.width);
-            window.height = @intCast(ev.height);
+            window.pending_manage.height = @intCast(ev.height);
         },
         .dimensions_hint => {
             // TODO: Maybe could use this for floating windows

src/WindowManager.zig

@@ -179,10 +179,12 @@ fn windowManagerV1Listener(window_manager_v1: *river.WindowManagerV1, event: riv
             const output = Output.create(context, ev.id) catch @panic("Out of memory");
             wm.outputs.append(output);
             // If there was already a seat, but no outputs, set this new output as focused
-            const seat = wm.seats.first() orelse return;
+            const first_seat = wm.seats.first();
+            if (first_seat) |seat| {
                 if (seat.focused_output == null and seat.pending_manage.output == null) {
                     seat.pending_manage.output = .{ .output = output };
                 }
+            }
 
             // If there are orphan windows, send them to the new output
             var it = wm.orphan_windows.iterator(.forward);
@@ -210,7 +212,9 @@ fn windowManagerV1Listener(window_manager_v1: *river.WindowManagerV1, event: riv
             wm.seats.append(seat);
 
             // If there was already an output, but no seats, set the first output as focused
-            seat.pending_manage.output = .{ .output = wm.outputs.first() orelse return };
+            if (wm.outputs.first()) |output| {
+                seat.pending_manage.output = .{ .output = output };
+            }
         },
         .window => |ev| {
             // TODO: Support multiple seats

src/main.zig

@@ -2,11 +2,25 @@
 //
 // SPDX-License-Identifier: GPL-3.0-or-later
 
-/// Wayland globals that we need to bind to
+/// Wayland globals that we need to bind listen in alphabetical order
 const Globals = struct {
-    wl_compositor: ?*wl.Compositor = null,
+    river_layer_shell_v1: ?*river.LayerShellV1 = null,
     river_window_manager_v1: ?*river.WindowManagerV1 = null,
     river_xkb_bindings_v1: ?*river.XkbBindingsV1 = null,
+
+    wl_compositor: ?*wl.Compositor = null,
+    wl_shm: ?*wl.Shm = null,
+    wl_outputs: std.AutoHashMapUnmanaged(u32, *wl.Output) = .empty,
+
+    zwlr_layer_shell_v1: ?*zwlr.LayerShellV1 = null,
+
+    fn deinit(globals: *Globals) void {
+        var it = globals.wl_outputs.valueIterator();
+        while (it.next()) |output| {
+            output.*.release();
+        }
+        globals.wl_outputs.deinit(utils.allocator);
+    }
 };
 
 pub fn main() !void {
@@ -23,6 +37,7 @@ pub fn main() !void {
     const wl_registry = try wl_display.getRegistry();
 
     var globals: Globals = .{};
+    defer globals.deinit();
     wl_registry.setListener(*Globals, registryListener, &globals);
 
     const errno = wl_display.roundtrip();
@@ -31,19 +46,30 @@ pub fn main() !void {
     }
 
     const wl_compositor = globals.wl_compositor orelse utils.interfaceNotAdvertised(wl.Compositor);
+    const wl_shm = globals.wl_shm orelse utils.interfaceNotAdvertised(wl.Shm);
+    // We can theoretically start with zero wl_outputs; don't panic if it's empty.
+    const wl_outputs = &globals.wl_outputs;
+
+    const river_layer_shell_v1 = globals.river_layer_shell_v1 orelse utils.interfaceNotAdvertised(river.LayerShellV1);
     const river_window_manager_v1 = globals.river_window_manager_v1 orelse utils.interfaceNotAdvertised(river.WindowManagerV1);
     const river_xkb_bindings_v1 = globals.river_xkb_bindings_v1 orelse utils.interfaceNotAdvertised(river.XkbBindingsV1);
 
+    const zwlr_layer_shell_v1 = globals.zwlr_layer_shell_v1 orelse utils.interfaceNotAdvertised(zwlr.LayerShellV1);
+
     const config = try Config.create();
     defer config.destroy();
-    const context = try Context.create(
+    const context = try Context.create(.{
-        wl_display,
+        .wl_compositor = wl_compositor,
-        wl_registry,
+        .wl_display = wl_display,
-        wl_compositor,
+        .wl_outputs = wl_outputs,
-        river_window_manager_v1,
+        .wl_registry = wl_registry,
-        river_xkb_bindings_v1,
+        .wl_shm = wl_shm,
-        config,
+        .river_layer_shell_v1 = river_layer_shell_v1,
-    );
+        .river_window_manager_v1 = river_window_manager_v1,
+        .river_xkb_bindings_v1 = river_xkb_bindings_v1,
+        .zwlr_layer_shell_v1 = zwlr_layer_shell_v1,
+        .config = config,
+    });
     defer context.destroy();
 
     while (true) {
@@ -61,20 +87,50 @@ fn registryListener(registry: *wl.Registry, event: wl.Registry.Event, globals: *
             if (mem.orderZ(u8, ev.interface, wl.Compositor.interface.name) == .eq) {
                 if (ev.version < 4) utils.versionNotSupported(wl.Compositor, ev.version, 4);
                 globals.wl_compositor = registry.bind(ev.name, wl.Compositor, 4) catch |e| {
-                    fatal("Failed to bind to compositor: {any}", .{@errorName(e)});
+                    fatal("Failed to bind to wl_compositor: {any}", .{@errorName(e)});
+                };
+            } else if (mem.orderZ(u8, ev.interface, wl.Output.interface.name) == .eq) {
+                if (ev.version < 4) utils.versionNotSupported(wl.Output, ev.version, 4);
+
+                const wl_output = registry.bind(ev.name, wl.Output, 4) catch |e| {
+                    fatal("Failed to bind to wl_output: {any}", .{@errorName(e)});
+                };
+
+                // We can get multiple wl_outputs, so we have to try add them to our HashMap
+                // instead of just keeping the one
+                globals.wl_outputs.put(utils.allocator, ev.name, wl_output) catch |e| {
+                    fatal("Failed to add wl_output to hashmap: {any}", .{@errorName(e)});
+                };
+            } else if (mem.orderZ(u8, ev.interface, wl.Shm.interface.name) == .eq) {
+                globals.wl_shm = registry.bind(ev.name, wl.Shm, 1) catch |e| {
+                    fatal("Failed to bind to wl_shm: {any}", .{@errorName(e)});
+                };
+            } else if (mem.orderZ(u8, ev.interface, river.LayerShellV1.interface.name) == .eq) {
+                globals.river_layer_shell_v1 = registry.bind(ev.name, river.LayerShellV1, 1) catch |e| {
+                    fatal("Failed to bind to river_layer_shell_v1: {any}", .{@errorName(e)});
                 };
             } else if (mem.orderZ(u8, ev.interface, river.WindowManagerV1.interface.name) == .eq) {
                 globals.river_window_manager_v1 = registry.bind(ev.name, river.WindowManagerV1, 3) catch |e| {
-                    fatal("Failed to bind to window_manager_v1: {any}", .{@errorName(e)});
+                    fatal("Failed to bind to river_window_manager_v1: {any}", .{@errorName(e)});
                 };
             } else if (mem.orderZ(u8, ev.interface, river.XkbBindingsV1.interface.name) == .eq) {
                 globals.river_xkb_bindings_v1 = registry.bind(ev.name, river.XkbBindingsV1, 2) catch |e| {
-                    fatal("Failed to bind to xkb_bindings_v1: {any}", .{@errorName(e)});
+                    fatal("Failed to bind to river_xkb_bindings_v1: {any}", .{@errorName(e)});
+                };
+            } else if (mem.orderZ(u8, ev.interface, zwlr.LayerShellV1.interface.name) == .eq) {
+                if (ev.version < 3) utils.versionNotSupported(zwlr.LayerShellV1, ev.version, 3);
+                globals.zwlr_layer_shell_v1 = registry.bind(ev.name, zwlr.LayerShellV1, 3) catch |e| {
+                    fatal("Failed to bind to zwlr_layer_shell_v1: {any}", .{@errorName(e)});
                 };
             }
         },
         // We don't need .global_remove
-        .global_remove => {},
+        .global_remove => |ev| {
+            // The only remove we care about is for wl_outputs
+            if (!globals.wl_outputs.remove(ev.name)) {
+                log.debug("Received a global_remove event for something other than a wl_output", .{});
+            }
+        },
     }
 }
 
@@ -86,6 +142,7 @@ const process = std.process;
 const wayland = @import("wayland");
 const river = wayland.client.river;
 const wl = wayland.client.wl;
+const zwlr = wayland.client.zwlr;
 
 const utils = @import("utils.zig");
 const Config = @import("Config.zig");