Add basic Ubuntu Touch functions

This adds support for:
- System theme
- Sandbox detection
- Platform detection
- Device form factor detection

Author: Semphris

CMakeLists.txt

@@ -1790,6 +1790,7 @@ elseif(UNIX AND NOT APPLE AND NOT RISCOS AND NOT HAIKU)
     sdl_sources(
       "${SDL3_SOURCE_DIR}/src/core/linux/SDL_evdev_capabilities.c"
       "${SDL3_SOURCE_DIR}/src/core/linux/SDL_threadprio.c"
+      "${SDL3_SOURCE_DIR}/src/core/linux/SDL_ubuntu_touch.c"
     )
 
     # src/core/unix/*.c is included in a generic if(UNIX) section, elsewhere.

docs/README-ubuntu-touch.md

@@ -0,0 +1,42 @@
+# Ubuntu Touch / Lomiri
+
+Ubuntu Touch being similar to Ubuntu desktop, most features should be supported
+out-of-the-box with SDL.
+
+## Developing apps
+
+Ubuntu Touch apps are developed using [Clickable](https://clickable-ut.dev/).
+
+Clickable provides an SDL template. It is highly recommended to use the template
+as a starting point for both new and existing apps.
+
+## Considerations
+
+Ubuntu Touch is similar to the desktop version of Ubuntu, but presents some
+differences in behavior. Developers should be wary of the following:
+
+### SDL_GetPrefPath
+
+The only allowed writable folder is `~/.local/share/<appname>/`, where
+`<appname>` is the identifier string for the app. It can be found in the
+`manifest.json` file under the key `"name"`, and usually looks like
+`appname.yourname`.
+
+A future version of SDL may change how `SDL_GetPrefPath` operates on Ubuntu
+Touch to make it ignore its arguments and always choose the correct writable
+folder. For future-proof-ness, using `SDL_GetPrefPath("", "<appname>")` as a
+writable directory is a safe choice.
+
+### Video driver
+
+Currently, [a bug](https://github.com/libsdl-org/SDL/issues/12247) forces SDL to
+use the Wayland driver on Ubuntu Touch. No changes are needed in apps, but
+forcing the X11 driver won't work.
+
+### Extra functions
+
+Some extra functions are provided to help development with Ubuntu Touch. A full
+list can be found in the documentation; some of these are documented here:
+- `SDL_IsUbuntuTouch()` to differentiate between Ubuntu Touch and regular Unix.
+- `SDL_GetUbuntuTouchFormFactor()` to obtain what kind of device the app is
+  being ran on.

include/SDL3/SDL_system.h

@@ -631,7 +631,8 @@ typedef enum SDL_Sandbox
     SDL_SANDBOX_UNKNOWN_CONTAINER,
     SDL_SANDBOX_FLATPAK,
     SDL_SANDBOX_SNAP,
-    SDL_SANDBOX_MACOS
+    SDL_SANDBOX_MACOS,
+    SDL_SANDBOX_LOMIRI
 } SDL_Sandbox;
 
 /**
@@ -809,6 +810,49 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetGDKDefaultUser(XUserHandle *outUserHandl
 
 #endif
 
+/**
+ * The possible form factors for an Ubuntu Touch device.
+ *
+ * \since This enum is available since SDL 3.4.0.
+ *
+ * \sa SDL_GetUbuntuTouchFormFactor
+ */
+typedef enum SDL_UTFormFactor {
+    SDL_UTFORMFACTOR_UNKNOWN,
+    SDL_UTFORMFACTOR_PHONE,
+    SDL_UTFORMFACTOR_TABLET,
+    SDL_UTFORMFACTOR_LAPTOP,
+    SDL_UTFORMFACTOR_DESKTOP
+} SDL_UTFormFactor;
+
+/*
+ * Functions used only with Ubuntu Touch
+ */
+#ifdef SDL_PLATFORM_LINUX
+
+/**
+ * Detect whether the current platform is Ubuntu Touch.
+ *
+ * \returns true if the platform is Ubuntu Touch; false otherwise.
+ *
+ * \since This function is available since SDL 3.4.0.
+ */
+extern SDL_DECLSPEC bool SDLCALL SDL_IsUbuntuTouch(void);
+
+/**
+ * Get the form factor of the current device.
+ *
+ * \returns the form factor of the current device, or SDL_UTFORMFACTOR_UNKNOWN
+ *          on error or if the current platform isn't Ubuntu Touch.
+ *
+ * \since This function is available since SDL 3.4.0.
+ *
+ * \sa SDL_UTFormFactor
+ */
+extern SDL_DECLSPEC SDL_UTFormFactor SDLCALL SDL_GetUbuntuTouchFormFactor(void);
+
+#endif
+
 /* Ends C function definitions when using C++ */
 #ifdef __cplusplus
 }

src/SDL.c

@@ -774,6 +774,11 @@ bool SDL_IsTablet(void)
 #elif defined(SDL_PLATFORM_IOS)
     extern bool SDL_IsIPad(void);
     return SDL_IsIPad();
+#elif defined(SDL_PLATFORM_LINUX)
+    if (SDL_IsUbuntuTouch()) {
+        return SDL_GetUbuntuTouchFormFactor() == SDL_UTFORMFACTOR_TABLET;
+    }
+    return false;
 #else
     return false;
 #endif
@@ -804,6 +809,12 @@ static SDL_Sandbox SDL_DetectSandbox(void)
         return SDL_SANDBOX_SNAP;
     }
 
+    /* Ubuntu Touch also supports Snap; check for classic sandboxing only if
+     * Snap hasn't been detected. */
+    if (SDL_getenv("LOMIRI_APPLICATION_ISOLATION") || SDL_getenv("CLICKABLE_DESKTOP_MODE")) {
+        return SDL_SANDBOX_LOMIRI;
+    }
+
     if (access("/run/host/container-manager", F_OK) == 0) {
         return SDL_SANDBOX_UNKNOWN_CONTAINER;
     }

src/core/SDL_core_unsupported.c

@@ -211,3 +211,19 @@ Sint32 JNI_OnLoad(void *vm, void *reserved)
     return -1; // JNI_ERR
 }
 #endif
+
+#ifndef SDL_PLATFORM_LINUX
+
+SDL_DECLSPEC bool SDLCALL SDL_IsUbuntuTouch(void);
+bool SDL_IsUbuntuTouch(void)
+{
+    return false;
+}
+
+SDL_DECLSPEC SDL_UTFormFactor SDLCALL SDL_GetUbuntuTouchFormFactor(void);
+SDL_UTFormFactor SDL_GetUbuntuTouchFormFactor(void)
+{
+    return SDL_UTFORMFACTOR_UNKNOWN;
+}
+
+#endif

src/core/linux/SDL_system_theme.c

@@ -24,6 +24,7 @@
 #include "SDL_system_theme.h"
 #include "../../video/SDL_sysvideo.h"
 
+#include <stdio.h>
 #include <unistd.h>
 
 #define PORTAL_DESTINATION "org.freedesktop.portal.Desktop"
@@ -150,7 +151,55 @@ bool SDL_SystemTheme_Init(void)
     return true;
 }
 
+SDL_SystemTheme UbuntuTouch_GetSystemTheme(void)
+{
+    SDL_SystemTheme theme = SDL_SYSTEM_THEME_UNKNOWN;
+    FILE *config_file = NULL;
+    char *line = NULL;
+    size_t line_alloc = 0;
+    ssize_t line_size = 0;
+    bool is_in_general_category = false;
+
+    // "Lomiri": Ubuntu Touch 20.04+
+    // "Ubuntu": Ubuntu Touch 16.04
+    config_file = fopen("/home/phablet/.config/lomiri-ui-toolkit/theme.ini", "r");
+    if (!config_file) {
+        config_file = fopen("/home/phablet/.config/ubuntu-ui-toolkit/theme.ini", "r");
+        if (!config_file) {
+            return SDL_SYSTEM_THEME_UNKNOWN;
+        }
+    }
+
+    while ((line_size = getline(&line, &line_alloc, config_file)) != -1) {
+        if (line_size >= 1 && line[0] == '[') {
+            is_in_general_category = SDL_strcmp(line, "[General]\n") == 0;
+        } else if (is_in_general_category && SDL_strncmp(line, "theme=", 6) == 0) {
+            if (SDL_strcmp(line, "theme=Lomiri.Components.Themes.SuruDark\n") == 0 ||
+                SDL_strcmp(line, "theme=Ubuntu.Components.Themes.SuruDark\n") == 0) {
+                theme = SDL_SYSTEM_THEME_DARK;
+            } else if (SDL_strcmp(line, "theme=Lomiri.Components.Themes.Ambiance\n") == 0 ||
+                       SDL_strcmp(line, "theme=Ubuntu.Components.Themes.Ambiance\n") == 0) {
+                theme = SDL_SYSTEM_THEME_LIGHT;
+            } else {
+                theme = SDL_SYSTEM_THEME_UNKNOWN;
+            }
+        }
+
+        free(line); // This should NOT be SDL_free()
+    }
+
+    fclose(config_file);
+
+    return theme;
+}
+
 SDL_SystemTheme SDL_SystemTheme_Get(void)
 {
+    if (system_theme_data.theme == SDL_SYSTEM_THEME_UNKNOWN) {
+        // TODO: Use inotify to watch for changes, so that the config file
+        // doesn't need to be checked each time.
+        return UbuntuTouch_GetSystemTheme();
+    }
+
     return system_theme_data.theme;
 }

src/core/linux/SDL_ubuntu_touch.c

@@ -0,0 +1,68 @@
+/*
+  Simple DirectMedia Layer
+  Copyright (C) 1997-2025 Sam Lantinga <[email protected]>
+
+  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"
+
+#ifdef SDL_PLATFORM_LINUX
+#include <stdio.h>
+#include <unistd.h>
+
+bool SDL_IsUbuntuTouch(void)
+{
+    return access("/etc/ubuntu-touch-session.d/", F_OK) == 0;
+}
+
+// https://docs.ubports.com/en/latest/porting/configure_test_fix/Display.html#form-factor
+SDL_UTFormFactor SDL_GetUbuntuTouchFormFactor(void)
+{
+    SDL_UTFormFactor form_factor = SDL_UTFORMFACTOR_UNKNOWN;
+    FILE *config_file = NULL;
+    char *line = NULL;
+    size_t line_alloc = 0;
+    ssize_t line_size = 0;
+
+    config_file = fopen("/etc/ubuntu-touch-session.d/android.conf", "r");
+    if (!config_file) {
+        return form_factor;
+    }
+
+    while ((line_size = getline(&line, &line_alloc, config_file)) != -1) {
+        if (SDL_strncmp(line, "FORM_FACTOR=", 12) == 0) {
+            if (SDL_strcmp(line, "FORM_FACTOR=handset\n")) {
+                form_factor = SDL_UTFORMFACTOR_PHONE;
+            } else if (SDL_strcmp(line, "FORM_FACTOR=tablet\n")) {
+                form_factor = SDL_UTFORMFACTOR_TABLET;
+            } else if (SDL_strcmp(line, "FORM_FACTOR=laptop\n")) {
+                form_factor = SDL_UTFORMFACTOR_LAPTOP;
+            } else if (SDL_strcmp(line, "FORM_FACTOR=desktop\n")) {
+                form_factor = SDL_UTFORMFACTOR_DESKTOP;
+            } else {
+                form_factor = SDL_UTFORMFACTOR_UNKNOWN;
+            }
+        }
+
+        free(line); // This should NOT be SDL_free()
+    }
+
+    fclose(config_file);
+
+    return form_factor;
+}
+#endif

src/dynapi/SDL_dynapi.sym

@@ -1242,6 +1242,8 @@ SDL3_0.0.0 {
     SDL_SetGPURenderStateFragmentUniforms;
     SDL_SetRenderGPUState;
     SDL_DestroyGPURenderState;
+    SDL_IsUbuntuTouch;
+    SDL_GetUbuntuTouchFormFactor;
     # extra symbols go here (don't modify this line)
   local: *;
 };

src/dynapi/SDL_dynapi_overrides.h

@@ -1267,3 +1267,5 @@
 #define SDL_SetGPURenderStateFragmentUniforms SDL_SetGPURenderStateFragmentUniforms_REAL
 #define SDL_SetRenderGPUState SDL_SetRenderGPUState_REAL
 #define SDL_DestroyGPURenderState SDL_DestroyGPURenderState_REAL
+#define SDL_IsUbuntuTouch SDL_IsUbuntuTouch_REAL
+#define SDL_GetUbuntuTouchFormFactor SDL_GetUbuntuTouchFormFactor_REAL

src/dynapi/SDL_dynapi_procs.h

@@ -1275,3 +1275,5 @@ SDL_DYNAPI_PROC(SDL_GPURenderState*,SDL_CreateGPURenderState,(SDL_Renderer *a,SD
 SDL_DYNAPI_PROC(bool,SDL_SetGPURenderStateFragmentUniforms,(SDL_GPURenderState *a,Uint32 b,const void *c,Uint32 d),(a,b,c,d),return)
 SDL_DYNAPI_PROC(bool,SDL_SetRenderGPUState,(SDL_Renderer *a,SDL_GPURenderState *b),(a,b),return)
 SDL_DYNAPI_PROC(void,SDL_DestroyGPURenderState,(SDL_GPURenderState *a),(a),)
+SDL_DYNAPI_PROC(bool,SDL_IsUbuntuTouch,(void),(),return)
+SDL_DYNAPI_PROC(SDL_UTFormFactor,SDL_GetUbuntuTouchFormFactor,(void),(),return)

src/video/SDL_video.c

@@ -647,6 +647,12 @@ bool SDL_VideoInit(const char *driver_name)
     if (!driver_name) {
         driver_name = SDL_GetHint(SDL_HINT_VIDEO_DRIVER);
     }
+#ifdef SDL_PLATFORM_LINUX
+    // https://github.com/libsdl-org/SDL/issues/12247
+    if (SDL_IsUbuntuTouch()) {
+        driver_name = "wayland";
+    }
+#endif
     if (driver_name && *driver_name != 0) {
         const char *driver_attempt = driver_name;
         while (driver_attempt && *driver_attempt != 0 && !video) {