From 8167913fff5a563a8d8deea0799442e9a269bd91 Mon Sep 17 00:00:00 2001
From: Frank Praznik <[EMAIL REDACTED]>
Date: Thu, 22 Oct 2026 22:22:12 -0400
Subject: [PATCH] wayland: Add SHM framebuffer support
This implements SHM framebuffer support for Wayland. It is the most basic way of getting pixels onto the display, and should work even if no GPU driver or libraries are available. It uses no extensions in the interest of simplicity and compatibility.
---
src/video/wayland/SDL_waylandframebuffer.c | 178 +++++++++++++++++++++
src/video/wayland/SDL_waylandframebuffer.h | 35 ++++
src/video/wayland/SDL_waylandshmbuffer.c | 10 --
src/video/wayland/SDL_waylandsym.h | 1 +
src/video/wayland/SDL_waylandvideo.c | 6 +
src/video/wayland/SDL_waylandwindow.h | 1 +
6 files changed, 221 insertions(+), 10 deletions(-)
create mode 100644 src/video/wayland/SDL_waylandframebuffer.c
create mode 100644 src/video/wayland/SDL_waylandframebuffer.h
diff --git a/src/video/wayland/SDL_waylandframebuffer.c b/src/video/wayland/SDL_waylandframebuffer.c
new file mode 100644
index 0000000000000..07bd9aee74fb2
--- /dev/null
+++ b/src/video/wayland/SDL_waylandframebuffer.c
@@ -0,0 +1,178 @@
+/*
+ Simple DirectMedia Layer
+ Copyright (C) 1997-2026 Sam Lantinga <slouken@libsdl.org>
+
+ This software is provided 'as-is', without any express or implied
+ warranty. In no event will the authors be held liable for any damages
+ arising from the use of this software.
+
+ Permission is granted to anyone to use this software for any purpose,
+ including commercial applications, and to alter it and redistribute it
+ freely, subject to the following restrictions:
+
+ 1. The origin of this software must not be misrepresented; you must not
+ claim that you wrote the original software. If you use this software
+ in a product, an acknowledgment in the product documentation would be
+ appreciated but is not required.
+ 2. Altered source versions must be plainly marked as such, and must not be
+ misrepresented as being the original software.
+ 3. This notice may not be removed or altered from any source distribution.
+*/
+
+#include "SDL_waylandframebuffer.h"
+#include "SDL_waylandshmbuffer.h"
+#include "SDL_waylandwindow.h"
+
+#define BUFFER_COUNT 3
+
+typedef struct Wayland_Buffer
+{
+ struct wl_buffer *wl_buffer;
+ void *mem;
+ bool busy;
+} Wayland_Buffer;
+
+struct Wayland_Framebuffer
+{
+ Wayland_Buffer buffer[BUFFER_COUNT];
+ Wayland_SHMPool *pool;
+ struct wl_event_queue *queue;
+ void *pixels;
+};
+
+static void buffer_handle_release(void *data, struct wl_buffer *wl_buffer)
+{
+ Wayland_Buffer *buffer = (Wayland_Buffer *)data;
+ buffer->busy = false;
+}
+
+static struct wl_buffer_listener buffer_listener = {
+ buffer_handle_release
+};
+
+bool Wayland_CreateWindowFramebuffer(SDL_VideoDevice *_this, SDL_Window *window, SDL_PixelFormat *format, void **pixels, int *pitch)
+{
+ SDL_WindowData *wind = window->internal;
+ if (wind->framebuffer) {
+ Wayland_DestroyWindowFramebuffer(_this, window);
+ }
+
+ const int w = wind->current.pixel_width;
+ const int h = wind->current.pixel_height;
+
+ Wayland_Framebuffer *framebuffer = SDL_calloc(1, sizeof(Wayland_Framebuffer));
+ if (!framebuffer) {
+ return false;
+ }
+
+ framebuffer->pixels = SDL_malloc(w * h * 4);
+ if (!framebuffer->pixels) {
+ goto failed;
+ }
+
+ framebuffer->pool = Wayland_AllocSHMPool(w * h * 4 * BUFFER_COUNT);
+ if (!framebuffer->pool) {
+ goto failed;
+ }
+
+ framebuffer->queue = Wayland_DisplayCreateQueue(_this->internal->display, "Wayland Framebuffer Queue");
+ for (int i = 0; i < BUFFER_COUNT; ++i) {
+ framebuffer->buffer[i].wl_buffer = Wayland_AllocBufferFromPool(framebuffer->pool, w, h, &framebuffer->buffer[i].mem);
+ WAYLAND_wl_proxy_set_queue((struct wl_proxy *)framebuffer->buffer[i].wl_buffer, framebuffer->queue);
+ wl_buffer_add_listener(framebuffer->buffer[i].wl_buffer, &buffer_listener, &framebuffer->buffer[i]);
+ }
+
+ // ARGB8888 is guaranteed to be supported on all compositors.
+ *format = SDL_PIXELFORMAT_ARGB8888;
+ *pixels = framebuffer->pixels;
+ *pitch = w * 4;
+
+ wind->framebuffer = framebuffer;
+
+ return true;
+
+failed:
+ for (int i = 0; i < BUFFER_COUNT; ++i) {
+ if (framebuffer->buffer[i].wl_buffer) {
+ wl_buffer_destroy(framebuffer->buffer[i].wl_buffer);
+ }
+ }
+
+ Wayland_ReleaseSHMPool(framebuffer->pool);
+ if (framebuffer->queue) {
+ WAYLAND_wl_event_queue_destroy(framebuffer->queue);
+ }
+ SDL_free(framebuffer->pixels);
+ SDL_free(framebuffer);
+
+ return false;
+}
+
+bool Wayland_UpdateWindowFramebuffer(SDL_VideoDevice *_this, SDL_Window *window, const SDL_Rect *rects, int numrects)
+{
+ SDL_VideoData *viddata = _this->internal;
+ SDL_WindowData *wind = window->internal;
+ Wayland_Framebuffer *framebuffer = wind->framebuffer;
+
+ // Process any queued buffer release events.
+ WAYLAND_wl_display_dispatch_queue_pending(viddata->display, framebuffer->queue);
+
+ // Find a free buffer.
+ Wayland_Buffer *buffer = NULL;
+ while (!buffer) {
+ for (int i = 0; i < BUFFER_COUNT; ++i) {
+ if (!framebuffer->buffer[i].busy) {
+ buffer = &framebuffer->buffer[i];
+ break;
+ }
+ }
+
+ if (buffer) {
+ break;
+ }
+
+ /* If nothing is free, wait for a buffer release event.
+ * Not all compositors flush on a release event, so use roundtrips, as they cause a flush.
+ */
+ if (WAYLAND_wl_display_roundtrip_queue(viddata->display, framebuffer->queue) < 0) {
+ return false;
+ }
+ }
+
+ // Copy the image data.
+ SDL_memcpy(buffer->mem, framebuffer->pixels, wind->current.pixel_width * wind->current.pixel_height * 4);
+
+ // Attach the buffer and commit the surface.
+ buffer->busy = true;
+ wl_surface_attach(wind->surface, buffer->wl_buffer, 0, 0);
+ if (wl_surface_get_version(wind->surface) >= WL_SURFACE_DAMAGE_BUFFER_SINCE_VERSION) {
+ wl_surface_damage_buffer(wind->surface, 0, 0, SDL_MAX_SINT32, SDL_MAX_SINT32);
+ } else {
+ wl_surface_damage(wind->surface, 0, 0, SDL_MAX_SINT32, SDL_MAX_SINT32);
+ }
+ wl_surface_commit(wind->surface);
+
+ WAYLAND_wl_display_flush(viddata->display);
+
+ return true;
+}
+
+void Wayland_DestroyWindowFramebuffer(SDL_VideoDevice *_this, SDL_Window *window)
+{
+ SDL_WindowData *wind = window->internal;
+ if (!wind || !wind->framebuffer) {
+ return;
+ }
+
+ Wayland_Framebuffer *framebuffer = wind->framebuffer;
+ wind->framebuffer = NULL;
+
+ for (int i = 0; i < BUFFER_COUNT; ++i) {
+ wl_buffer_destroy(framebuffer->buffer[i].wl_buffer);
+ }
+
+ Wayland_ReleaseSHMPool(framebuffer->pool);
+ WAYLAND_wl_event_queue_destroy(framebuffer->queue);
+ SDL_free(framebuffer->pixels);
+ SDL_free(framebuffer);
+}
diff --git a/src/video/wayland/SDL_waylandframebuffer.h b/src/video/wayland/SDL_waylandframebuffer.h
new file mode 100644
index 0000000000000..06389333b044d
--- /dev/null
+++ b/src/video/wayland/SDL_waylandframebuffer.h
@@ -0,0 +1,35 @@
+/*
+ Simple DirectMedia Layer
+ Copyright (C) 1997-2026 Sam Lantinga <slouken@libsdl.org>
+
+ This software is provided 'as-is', without any express or implied
+ warranty. In no event will the authors be held liable for any damages
+ arising from the use of this software.
+
+ Permission is granted to anyone to use this software for any purpose,
+ including commercial applications, and to alter it and redistribute it
+ freely, subject to the following restrictions:
+
+ 1. The origin of this software must not be misrepresented; you must not
+ claim that you wrote the original software. If you use this software
+ in a product, an acknowledgment in the product documentation would be
+ appreciated but is not required.
+ 2. Altered source versions must be plainly marked as such, and must not be
+ misrepresented as being the original software.
+ 3. This notice may not be removed or altered from any source distribution.
+*/
+
+#include "SDL_internal.h"
+
+#ifndef SDL_waylandframebuffer_h_
+#define SDL_waylandframebuffer_h_
+
+#include "SDL_waylandvideo.h"
+
+typedef struct Wayland_Framebuffer Wayland_Framebuffer;
+
+extern bool Wayland_CreateWindowFramebuffer(SDL_VideoDevice *_this, SDL_Window *window, SDL_PixelFormat *format, void **pixels, int *pitch);
+extern bool Wayland_UpdateWindowFramebuffer(SDL_VideoDevice *_this, SDL_Window *window, const SDL_Rect *rects, int numrects);
+extern void Wayland_DestroyWindowFramebuffer(SDL_VideoDevice *_this, SDL_Window *window);
+
+#endif // SDL_waylandframebuffer_h_
diff --git a/src/video/wayland/SDL_waylandshmbuffer.c b/src/video/wayland/SDL_waylandshmbuffer.c
index 9e355fd77a302..507ba565d45bf 100644
--- a/src/video/wayland/SDL_waylandshmbuffer.c
+++ b/src/video/wayland/SDL_waylandshmbuffer.c
@@ -106,15 +106,6 @@ static int CreateTempFD(off_t size)
return fd;
}
-static void buffer_handle_release(void *data, struct wl_buffer *wl_buffer)
-{
- // NOP
-}
-
-static struct wl_buffer_listener buffer_listener = {
- buffer_handle_release
-};
-
struct Wayland_SHMPool
{
struct wl_shm_pool *shm_pool;
@@ -171,7 +162,6 @@ struct wl_buffer *Wayland_AllocBufferFromPool(Wayland_SHMPool *shmPool, int widt
*data = (Uint8 *)shmPool->shm_pool_memory + shmPool->offset;
struct wl_buffer *buffer = wl_shm_pool_create_buffer(shmPool->shm_pool, shmPool->offset, width, height, width * 4, SHM_FMT);
- wl_buffer_add_listener(buffer, &buffer_listener, shmPool);
shmPool->offset += width * height * 4;
diff --git a/src/video/wayland/SDL_waylandsym.h b/src/video/wayland/SDL_waylandsym.h
index 2616cd90981d7..ed90d3e0d4ab3 100644
--- a/src/video/wayland/SDL_waylandsym.h
+++ b/src/video/wayland/SDL_waylandsym.h
@@ -61,6 +61,7 @@ SDL_WAYLAND_SYM(void, wl_display_cancel_read, (struct wl_display *))
SDL_WAYLAND_SYM(int, wl_display_get_error, (struct wl_display *))
SDL_WAYLAND_SYM(int, wl_display_flush, (struct wl_display *))
SDL_WAYLAND_SYM(int, wl_display_roundtrip, (struct wl_display *))
+SDL_WAYLAND_SYM(int, wl_display_roundtrip_queue, (struct wl_display *, struct wl_event_queue *))
SDL_WAYLAND_SYM(struct wl_event_queue *, wl_display_create_queue, (struct wl_display *))
SDL_WAYLAND_SYM(void, wl_event_queue_destroy, (struct wl_event_queue *))
SDL_WAYLAND_SYM(void, wl_log_set_handler_client, (wl_log_func_t))
diff --git a/src/video/wayland/SDL_waylandvideo.c b/src/video/wayland/SDL_waylandvideo.c
index 999bfe4dfa4f8..8ac21c9739d8a 100644
--- a/src/video/wayland/SDL_waylandvideo.c
+++ b/src/video/wayland/SDL_waylandvideo.c
@@ -35,6 +35,8 @@
#include "SDL_waylandmouse.h"
#include "SDL_waylandopengles.h"
#include "SDL_waylandvideo.h"
+
+#include "SDL_waylandframebuffer.h"
#include "SDL_waylandvulkan.h"
#include "SDL_waylandwindow.h"
@@ -757,6 +759,10 @@ static SDL_VideoDevice *Wayland_CreateDevice(bool require_preferred_protocols)
device->StopTextInput = Wayland_StopTextInput;
device->UpdateTextInputArea = Wayland_UpdateTextInputArea;
+ device->CreateWindowFramebuffer = Wayland_CreateWindowFramebuffer;
+ device->UpdateWindowFramebuffer = Wayland_UpdateWindowFramebuffer;
+ device->DestroyWindowFramebuffer = Wayland_DestroyWindowFramebuffer;
+
#ifdef SDL_VIDEO_VULKAN
device->Vulkan_LoadLibrary = Wayland_Vulkan_LoadLibrary;
device->Vulkan_UnloadLibrary = Wayland_Vulkan_UnloadLibrary;
diff --git a/src/video/wayland/SDL_waylandwindow.h b/src/video/wayland/SDL_waylandwindow.h
index 1df119ac64930..e22bd0e5861e0 100644
--- a/src/video/wayland/SDL_waylandwindow.h
+++ b/src/video/wayland/SDL_waylandwindow.h
@@ -128,6 +128,7 @@ struct SDL_WindowData
struct xdg_toplevel_session_v1 *xdg_toplevel_session;
struct Wayland_ColorInfoState *color_info_state;
+ struct Wayland_Framebuffer *framebuffer;
SDL_AtomicInt swap_interval_ready;