feat(lockscreen): add background image + optional blur

[raven2cz]

Description

Closes #401. Adds three lockscreen config options:

• lockscreen_bg_image: path to a wallpaper shown full-screen under the UI.
• lockscreen_bg_image_overlay: semi-transparent dim overlay (default #000000aa).
• lockscreen_bg_image_blur: optional, off by default. See below.

Without bg_image set, behavior is identical to the current solid-color path.

Implementation

Reply to @NilOmniscient in #401: took the wibox.container.background + bgimage path as suggested. Needed one small adjustment: the dim overlay has to sit on an inner background, not the outer one:

{
    {
        ui_content,
        bg = overlay_color,                 -- dim painted here
        widget = wibox.container.background,
    },
    bgimage = wallpaper_surface,            -- image painted here
    widget = wibox.container.background,
}

wibox.container.background paints bg before bgimage, so a single-layer variant (bg = overlay, bgimage = image on the same node) would place the overlay beneath the image and make it invisible. Children draw after the parent's bg+bgimage pass, so the overlay has to live on a child background to sit on top.

Multi-monitor cover screens follow the same two-layer pattern. The cover's inner background has no child widget (it only paints the overlay), so :fit() would return 0x0 and the dim would render at zero size; forced forced_width/forced_height on the inner pin it to the screen geometry.

Optional blur

Off by default; opt-in only:

-- Disabled (default)
lockscreen_bg_image_blur = false

-- Sensible defaults (radius 15, 3 passes)
lockscreen_bg_image_blur = true

-- Just a radius
lockscreen_bg_image_blur = 25

-- Full control
lockscreen_bg_image_blur = { radius = 30, passes = 5 }

-- Bring your own (custom shaders, SceneFX pipelines, etc.)
lockscreen_bg_image_blur = function(surface) return my_blur(surface) end

Built-in blur is a multi-pass bilinear downscale/upscale via cairo, visually close to a Gaussian, single allocation per pass. Radius/passes are clamped (1-100, 1-10) so a stray large value can't hang on allocation. lgi/cairo is loaded lazily (pcall) only when blur is requested. Intermediate cairo surfaces are :finish()'d after each pass to release backing memory synchronously rather than waiting for GC. Custom blur return values are duck-type validated; a throwing or malformed callback transparently falls back to the original surface. Blurred surfaces are cached per (path, spec signature) so the blur pipeline runs once, not once per monitor; custom function specs are intentionally not cached (may close over mutable state). lockscreen.invalidate_bg_cache() is exposed for explicit refresh.

Config merge uses explicit nil checks for bg_image / bg_image_blur / lock_screen so that opts.bg_image_blur = false correctly overrides a theme's lockscreen_bg_image_blur = true (the usual or chain would silently ignore the user's false).

Bug fix included

defaults.bg_image and defaults.lock_screen were nil, which pairs() silently skips, so the config resolver never visited those keys and beautiful.lockscreen_* values were never picked up. Changed to false.

Configuration example

-- theme.lua
theme.lockscreen_bg_image         = themes_path .. "wallpapers/1.jpg"
theme.lockscreen_bg_image_overlay = "#000000aa"   -- default
theme.lockscreen_bg_image_blur    = 15            -- opt-in

-- or directly
require("lockscreen").init({
    bg_image       = "/path/to/wallpaper.jpg",
    bg_image_blur  = { radius = 20, passes = 4 },
})

Test plan

• Plain color mode (no bg_image): unchanged
• bg_image only: wallpaper + default dim overlay
• bg_image + numeric blur: tested live with bg_image_blur = 15
• Multi-monitor covers: two-layer structure ensures overlay paints at full screen size
• Lua syntax check: lua5.1 -e 'assert(loadfile("lua/lockscreen.lua"))'

Config additions are all opt-in, existing themes keep behaving as before.

[JimmyCozza]

Sorry @raven2cz I have been in such a weird state with the layout branch (and my day job) that I have had a hard time getting these reviewed.

I'm taking a little trip for the next 4 days but when I get back I'm going to try to get these all merged.

Thanks for all your efforts and patience with me.

[raven2cz]

No worries. Better to be careful and do it gradually rather than all at once. After all, it is already quite a large project, and it will be better to always test things step by step.

This is not related to this issue, but it seems to me that something new is not working in GIMP when it is opened through XWayland. The menus somehow close by themselves. This will need some investigation, whether some fix is causing it, or whether it is yet another new Nvidia quirk...

Otherwise, I finally finished my whole project, so after 4 months I am fully on Wayland with SomeWM! It is already really nicely usable. I think that once you properly finish the full 2.0 version, we will have a really great compositor here, one that can basically be used for anything and, most importantly, customized however people need.