From 9f38ae78f96917096e009b11e6dcbbd04f2c5ad2 Mon Sep 17 00:00:00 2001 From: Alsey Coleman Miller Date: Sun, 15 Nov 2026 22:13:18 -0500 Subject: [PATCH 01/21] Loaded EGL and GLES 2.0 at run time for GL surfaces --- Sources/LinuxGraphics/GLLibrary.swift | 164 ++++++++++++++++++++++++++ 1 file changed, 164 insertions(+) create mode 100644 Sources/LinuxGraphics/GLLibrary.swift diff --git a/Sources/LinuxGraphics/GLLibrary.swift b/Sources/LinuxGraphics/GLLibrary.swift new file mode 100644 index 0000000..7a93111 --- /dev/null +++ b/Sources/LinuxGraphics/GLLibrary.swift @@ -0,0 +1,164 @@ +#if canImport(Glibc) +import Glibc +#elseif canImport(Darwin) +import Darwin +#endif + +/// EGL, and the few GLES 2.0 functions the host calls itself, looked up at +/// run time (`Plan.md` §7). +/// +/// The host links no GL: an app that draws has `libGLESv2` linked in by the +/// packager, for its own `gl*` calls, and the host opens the same libraries +/// by name. Without them, `Surface` is unavailable and the rest of the host +/// works as before. +struct GLLibrary { + + typealias EGLDisplay = UnsafeMutableRawPointer + typealias EGLConfig = UnsafeMutableRawPointer + typealias EGLSurface = UnsafeMutableRawPointer + typealias EGLContext = UnsafeMutableRawPointer + typealias EGLBoolean = UInt32 + typealias EGLint = Int32 + + // MARK: EGL + + let eglGetProcAddress: @convention(c) (UnsafePointer) -> UnsafeMutableRawPointer? + let eglGetDisplay: @convention(c) (UnsafeMutableRawPointer?) -> EGLDisplay? + let eglInitialize: @convention(c) (EGLDisplay?, UnsafeMutablePointer?, UnsafeMutablePointer?) -> EGLBoolean + let eglBindAPI: @convention(c) (UInt32) -> EGLBoolean + let eglChooseConfig: @convention(c) (EGLDisplay?, UnsafePointer?, UnsafeMutablePointer?, EGLint, UnsafeMutablePointer?) -> EGLBoolean + let eglCreatePbufferSurface: @convention(c) (EGLDisplay?, EGLConfig?, UnsafePointer?) -> EGLSurface? + let eglCreateContext: @convention(c) (EGLDisplay?, EGLConfig?, EGLContext?, UnsafePointer?) -> EGLContext? + let eglMakeCurrent: @convention(c) (EGLDisplay?, EGLSurface?, EGLSurface?, EGLContext?) -> EGLBoolean + let eglDestroySurface: @convention(c) (EGLDisplay?, EGLSurface?) -> EGLBoolean + let eglDestroyContext: @convention(c) (EGLDisplay?, EGLContext?) -> EGLBoolean + let eglGetError: @convention(c) () -> EGLint + let eglGetCurrentDisplay: @convention(c) () -> EGLDisplay? + let eglGetCurrentContext: @convention(c) () -> EGLContext? + let eglGetCurrentSurface: @convention(c) (EGLint) -> EGLSurface? + + /// EGL 1.5's, or `EGL_EXT_platform_base`'s; `nil` before either. + let eglGetPlatformDisplay: (@convention(c) (UInt32, UnsafeMutableRawPointer?, UnsafePointer?) -> EGLDisplay?)? + + // MARK: GLES 2.0 + + let glReadPixels: @convention(c) (Int32, Int32, Int32, Int32, UInt32, UInt32, UnsafeMutableRawPointer?) -> Void + let glGetIntegerv: @convention(c) (UInt32, UnsafeMutablePointer?) -> Void + let glBindFramebuffer: @convention(c) (UInt32, UInt32) -> Void + let glPixelStorei: @convention(c) (UInt32, Int32) -> Void + let glGetError: @convention(c) () -> UInt32 + let glClearColor: @convention(c) (Float, Float, Float, Float) -> Void + let glClear: @convention(c) (UInt32) -> Void + let glScissor: @convention(c) (Int32, Int32, Int32, Int32) -> Void + let glEnable: @convention(c) (UInt32) -> Void + let glDisable: @convention(c) (UInt32) -> Void + + /// The libraries, opened once; `nil` where they aren't installed. + static let shared: GLLibrary? = GLLibrary() + + private init?() { + guard let egl = Self.open(["libEGL.so.1", "libEGL.so"]), + let gles = Self.open(["libGLESv2.so.2", "libGLESv2.so"]) else { + return nil + } + func load(_ library: UnsafeMutableRawPointer, _ name: String, as type: T.Type = T.self) -> T? { + dlsym(library, name).map { unsafeBitCast($0, to: type) } + } + guard let eglGetProcAddress = load(egl, "eglGetProcAddress", as: (@convention(c) (UnsafePointer) -> UnsafeMutableRawPointer?).self), + let eglGetDisplay = load(egl, "eglGetDisplay", as: (@convention(c) (UnsafeMutableRawPointer?) -> EGLDisplay?).self), + let eglInitialize = load(egl, "eglInitialize", as: (@convention(c) (EGLDisplay?, UnsafeMutablePointer?, UnsafeMutablePointer?) -> EGLBoolean).self), + let eglBindAPI = load(egl, "eglBindAPI", as: (@convention(c) (UInt32) -> EGLBoolean).self), + let eglChooseConfig = load(egl, "eglChooseConfig", as: (@convention(c) (EGLDisplay?, UnsafePointer?, UnsafeMutablePointer?, EGLint, UnsafeMutablePointer?) -> EGLBoolean).self), + let eglCreatePbufferSurface = load(egl, "eglCreatePbufferSurface", as: (@convention(c) (EGLDisplay?, EGLConfig?, UnsafePointer?) -> EGLSurface?).self), + let eglCreateContext = load(egl, "eglCreateContext", as: (@convention(c) (EGLDisplay?, EGLConfig?, EGLContext?, UnsafePointer?) -> EGLContext?).self), + let eglMakeCurrent = load(egl, "eglMakeCurrent", as: (@convention(c) (EGLDisplay?, EGLSurface?, EGLSurface?, EGLContext?) -> EGLBoolean).self), + let eglDestroySurface = load(egl, "eglDestroySurface", as: (@convention(c) (EGLDisplay?, EGLSurface?) -> EGLBoolean).self), + let eglDestroyContext = load(egl, "eglDestroyContext", as: (@convention(c) (EGLDisplay?, EGLContext?) -> EGLBoolean).self), + let eglGetError = load(egl, "eglGetError", as: (@convention(c) () -> EGLint).self), + let eglGetCurrentDisplay = load(egl, "eglGetCurrentDisplay", as: (@convention(c) () -> EGLDisplay?).self), + let eglGetCurrentContext = load(egl, "eglGetCurrentContext", as: (@convention(c) () -> EGLContext?).self), + let eglGetCurrentSurface = load(egl, "eglGetCurrentSurface", as: (@convention(c) (EGLint) -> EGLSurface?).self), + let glReadPixels = load(gles, "glReadPixels", as: (@convention(c) (Int32, Int32, Int32, Int32, UInt32, UInt32, UnsafeMutableRawPointer?) -> Void).self), + let glGetIntegerv = load(gles, "glGetIntegerv", as: (@convention(c) (UInt32, UnsafeMutablePointer?) -> Void).self), + let glBindFramebuffer = load(gles, "glBindFramebuffer", as: (@convention(c) (UInt32, UInt32) -> Void).self), + let glPixelStorei = load(gles, "glPixelStorei", as: (@convention(c) (UInt32, Int32) -> Void).self), + let glGetError = load(gles, "glGetError", as: (@convention(c) () -> UInt32).self), + let glClearColor = load(gles, "glClearColor", as: (@convention(c) (Float, Float, Float, Float) -> Void).self), + let glClear = load(gles, "glClear", as: (@convention(c) (UInt32) -> Void).self), + let glScissor = load(gles, "glScissor", as: (@convention(c) (Int32, Int32, Int32, Int32) -> Void).self), + let glEnable = load(gles, "glEnable", as: (@convention(c) (UInt32) -> Void).self), + let glDisable = load(gles, "glDisable", as: (@convention(c) (UInt32) -> Void).self) + else { + return nil + } + self.eglGetProcAddress = eglGetProcAddress + self.eglGetDisplay = eglGetDisplay + self.eglInitialize = eglInitialize + self.eglBindAPI = eglBindAPI + self.eglChooseConfig = eglChooseConfig + self.eglCreatePbufferSurface = eglCreatePbufferSurface + self.eglCreateContext = eglCreateContext + self.eglMakeCurrent = eglMakeCurrent + self.eglDestroySurface = eglDestroySurface + self.eglDestroyContext = eglDestroyContext + self.eglGetError = eglGetError + self.eglGetCurrentDisplay = eglGetCurrentDisplay + self.eglGetCurrentContext = eglGetCurrentContext + self.eglGetCurrentSurface = eglGetCurrentSurface + self.eglGetPlatformDisplay = (dlsym(egl, "eglGetPlatformDisplay") ?? eglGetProcAddress("eglGetPlatformDisplayEXT")) + .map { unsafeBitCast($0, to: (@convention(c) (UInt32, UnsafeMutableRawPointer?, UnsafePointer?) -> EGLDisplay?).self) } + self.glReadPixels = glReadPixels + self.glGetIntegerv = glGetIntegerv + self.glBindFramebuffer = glBindFramebuffer + self.glPixelStorei = glPixelStorei + self.glGetError = glGetError + self.glClearColor = glClearColor + self.glClear = glClear + self.glScissor = glScissor + self.glEnable = glEnable + self.glDisable = glDisable + } + + private static func open(_ names: [String]) -> UnsafeMutableRawPointer? { + for name in names { + if let handle = dlopen(name, RTLD_NOW | RTLD_GLOBAL) { + return handle + } + } + return nil + } +} + +/// The EGL and GL constants the host uses. +enum GL { + // EGL + static let EGL_SUCCESS: Int32 = 0x3000 + static let EGL_CONTEXT_LOST: Int32 = 0x300E + static let EGL_ALPHA_SIZE: Int32 = 0x3021 + static let EGL_BLUE_SIZE: Int32 = 0x3022 + static let EGL_GREEN_SIZE: Int32 = 0x3023 + static let EGL_RED_SIZE: Int32 = 0x3024 + static let EGL_DEPTH_SIZE: Int32 = 0x3025 + static let EGL_STENCIL_SIZE: Int32 = 0x3026 + static let EGL_SURFACE_TYPE: Int32 = 0x3033 + static let EGL_NONE: Int32 = 0x3038 + static let EGL_RENDERABLE_TYPE: Int32 = 0x3040 + static let EGL_HEIGHT: Int32 = 0x3056 + static let EGL_WIDTH: Int32 = 0x3057 + static let EGL_DRAW: Int32 = 0x3059 + static let EGL_READ: Int32 = 0x305A + static let EGL_CONTEXT_CLIENT_VERSION: Int32 = 0x3098 + static let EGL_PBUFFER_BIT: Int32 = 0x0001 + static let EGL_OPENGL_ES2_BIT: Int32 = 0x0004 + static let EGL_OPENGL_ES_API: UInt32 = 0x30A0 + static let EGL_PLATFORM_SURFACELESS_MESA: UInt32 = 0x31DD + + // GLES 2.0 + static let GL_COLOR_BUFFER_BIT: UInt32 = 0x4000 + static let GL_SCISSOR_TEST: UInt32 = 0x0C11 + static let GL_PACK_ALIGNMENT: UInt32 = 0x0D05 + static let GL_RGBA: UInt32 = 0x1908 + static let GL_UNSIGNED_BYTE: UInt32 = 0x1401 + static let GL_FRAMEBUFFER: UInt32 = 0x8D40 + static let GL_FRAMEBUFFER_BINDING: UInt32 = 0x8CA6 +} From 857ad28ecb3991cf2b3785cf3e94517438bf8a6d Mon Sep 17 00:00:00 2001 From: Alsey Coleman Miller Date: Sun, 15 Nov 2026 22:13:18 -0500 Subject: [PATCH 02/21] Gave the app one GLES 2.0 context, with a pbuffer for each surface --- Sources/LinuxGraphics/GLDisplay.swift | 203 ++++++++++++++++++++++++++ 1 file changed, 203 insertions(+) create mode 100644 Sources/LinuxGraphics/GLDisplay.swift diff --git a/Sources/LinuxGraphics/GLDisplay.swift b/Sources/LinuxGraphics/GLDisplay.swift new file mode 100644 index 0000000..c1649b3 --- /dev/null +++ b/Sources/LinuxGraphics/GLDisplay.swift @@ -0,0 +1,203 @@ +import Foundation +import LinuxHost + +/// The app's one GL context, and a pbuffer for each surface on screen. +/// +/// Surfaces share the context, so the guest's GL objects are the app's, as +/// in one WebGL context per page, and the wasm shim's buffer bindings stay +/// right from one surface to the next. Drawing goes into the surface's +/// pbuffer, its default framebuffer, and is read back for the window, +/// which Cacao composites. Whatever context was current before, such as +/// SDL's renderer's on the same thread, is current again after. Main +/// thread only. +final class GLDisplay { + + /// Opened on first use; `nil` without EGL and GLES 2.0. + static let shared: GLDisplay? = GLDisplay() + + /// What `rt_gl_context_generation` returns: it changes whenever the + /// context is a new one, so the wasm2c shim forgets its bindings. + nonisolated(unsafe) static var generation: UInt32 = 0 + + let gl: GLLibrary + + let display: GLLibrary.EGLDisplay + + let config: GLLibrary.EGLConfig + + private(set) var context: GLLibrary.EGLContext? + + /// What was current before `makeCurrent`, for `restoreCurrent`. + private var previous: (display: GLLibrary.EGLDisplay, draw: GLLibrary.EGLSurface?, read: GLLibrary.EGLSurface?, context: GLLibrary.EGLContext)? + + private init?() { + guard let gl = GLLibrary.shared else { + HostLog.debug("graphics: no libEGL and libGLESv2") + return nil + } + self.gl = gl + // Without a window system first: Mesa's surfaceless platform needs + // no display server. Other drivers have their default display. + var display: GLLibrary.EGLDisplay? + var major: Int32 = 0, minor: Int32 = 0 + if let platformDisplay = gl.eglGetPlatformDisplay, + let surfaceless = platformDisplay(GL.EGL_PLATFORM_SURFACELESS_MESA, nil, nil), + gl.eglInitialize(surfaceless, &major, &minor) != 0 { + display = surfaceless + } else if let fallback = gl.eglGetDisplay(nil), gl.eglInitialize(fallback, &major, &minor) != 0 { + display = fallback + } + guard let display else { + HostLog.warning("graphics: no EGL display (0x\(String(gl.eglGetError(), radix: 16)))") + return nil + } + _ = gl.eglBindAPI(GL.EGL_OPENGL_ES_API) + let attributes: [Int32] = [ + GL.EGL_SURFACE_TYPE, GL.EGL_PBUFFER_BIT, + GL.EGL_RENDERABLE_TYPE, GL.EGL_OPENGL_ES2_BIT, + GL.EGL_RED_SIZE, 8, GL.EGL_GREEN_SIZE, 8, GL.EGL_BLUE_SIZE, 8, GL.EGL_ALPHA_SIZE, 8, + GL.EGL_DEPTH_SIZE, 24, GL.EGL_STENCIL_SIZE, 8, + GL.EGL_NONE, + ] + var config: GLLibrary.EGLConfig? + var count: Int32 = 0 + guard gl.eglChooseConfig(display, attributes, &config, 1, &count) != 0, count > 0, let config else { + HostLog.warning("graphics: no EGL config for GLES 2.0 pbuffers") + return nil + } + self.display = display + self.config = config + HostLog.debug("graphics: EGL \(major).\(minor)") + } + + /// Makes the context if there's none. `false` if EGL refuses. + func makeContext() -> Bool { + if context != nil { + return true + } + let attributes: [Int32] = [GL.EGL_CONTEXT_CLIENT_VERSION, 2, GL.EGL_NONE] + guard let context = gl.eglCreateContext(display, config, nil, attributes) else { + HostLog.warning("graphics: can't make a GLES 2.0 context (0x\(String(gl.eglGetError(), radix: 16)))") + return false + } + self.context = context + Self.generation &+= 1 + return true + } + + /// Destroys the context, with every GL object in it. + func destroyContext() { + guard let context else { return } + if gl.eglGetCurrentContext() == context { + _ = gl.eglMakeCurrent(display, nil, nil, nil) + } + _ = gl.eglDestroyContext(display, context) + self.context = nil + } + + func makeSurface(width: Int32, height: Int32) -> GLLibrary.EGLSurface? { + let attributes: [Int32] = [GL.EGL_WIDTH, max(1, width), GL.EGL_HEIGHT, max(1, height), GL.EGL_NONE] + let surface = gl.eglCreatePbufferSurface(display, config, attributes) + if surface == nil { + HostLog.warning("graphics: can't make a \(width) × \(height) pbuffer (0x\(String(gl.eglGetError(), radix: 16)))") + } + return surface + } + + func destroy(_ surface: GLLibrary.EGLSurface) { + _ = gl.eglDestroySurface(display, surface) + } + + /// Makes the context current on `surface`. Fails with + /// `EGL_CONTEXT_LOST` when the context is gone. + func makeCurrent(_ surface: GLLibrary.EGLSurface) -> Result { + guard let context else { + return .failure(EGLError(code: GL.EGL_CONTEXT_LOST)) + } + if let current = gl.eglGetCurrentContext(), current != context, let currentDisplay = gl.eglGetCurrentDisplay() { + previous = (currentDisplay, gl.eglGetCurrentSurface(GL.EGL_DRAW), gl.eglGetCurrentSurface(GL.EGL_READ), current) + } + if gl.eglMakeCurrent(display, surface, surface, context) == 0 { + let error = EGLError(code: gl.eglGetError()) + restoreCurrent() + return .failure(error) + } + return .success(()) + } + + /// Makes current again what was before `makeCurrent`, or nothing. + func restoreCurrent() { + if let previous { + self.previous = nil + if gl.eglMakeCurrent(previous.display, previous.draw, previous.read, previous.context) != 0 { + return + } + } + _ = gl.eglMakeCurrent(display, nil, nil, nil) + } + + /// The current surface's pixels, `width` × `height`, as 8-bit RGBA rows + /// top to bottom with premultiplied alpha: the default framebuffer, + /// whatever the guest left bound. + func readPixels(width: Int32, height: Int32) -> Data { + let rowBytes = Int(width) * 4 + var framebuffer: Int32 = 0 + var alignment: Int32 = 4 + gl.glGetIntegerv(GL.GL_FRAMEBUFFER_BINDING, &framebuffer) + gl.glGetIntegerv(GL.GL_PACK_ALIGNMENT, &alignment) + if framebuffer != 0 { + gl.glBindFramebuffer(GL.GL_FRAMEBUFFER, 0) + } + gl.glPixelStorei(GL.GL_PACK_ALIGNMENT, 4) + var bottomUp = [UInt8](repeating: 0, count: rowBytes * Int(height)) + bottomUp.withUnsafeMutableBytes { bytes in + gl.glReadPixels(0, 0, width, height, GL.GL_RGBA, GL.GL_UNSIGNED_BYTE, bytes.baseAddress) + } + gl.glPixelStorei(GL.GL_PACK_ALIGNMENT, alignment) + if framebuffer != 0 { + gl.glBindFramebuffer(GL.GL_FRAMEBUFFER, UInt32(framebuffer)) + } + return Self.topDown(bottomUp, rowBytes: rowBytes, height: Int(height)) + } + + /// GL's rows run bottom to top; the window's top to bottom. Its color is + /// taken as premultiplied, as WebGL's is by default, so no channel may + /// exceed alpha. + static func topDown(_ pixels: [UInt8], rowBytes: Int, height: Int) -> Data { + var data = Data(count: pixels.count) + data.withUnsafeMutableBytes { (output: UnsafeMutableRawBufferPointer) in + let output = output.bindMemory(to: UInt8.self) + for row in 0.. UInt32 { + GLDisplay.generation +} From 990e22135d76ec3fc88e00bb7cca2863ccf97151 Mon Sep 17 00:00:00 2001 From: Alsey Coleman Miller Date: Sun, 15 Nov 2026 22:13:19 -0500 Subject: [PATCH 03/21] Implemented the Surface contract over EGL pbuffers --- Sources/LinuxGraphics/LinuxSurface.swift | 280 +++++++++++++++++++++++ 1 file changed, 280 insertions(+) create mode 100644 Sources/LinuxGraphics/LinuxSurface.swift diff --git a/Sources/LinuxGraphics/LinuxSurface.swift b/Sources/LinuxGraphics/LinuxSurface.swift new file mode 100644 index 0000000..ff8aff9 --- /dev/null +++ b/Sources/LinuxGraphics/LinuxSurface.swift @@ -0,0 +1,280 @@ +import DynamicGraphics +import Foundation +import LinuxHost + +/// A surface's pixels after a frame: 8-bit RGBA, premultiplied, rows top to +/// bottom. +public struct SurfacePixels: Sendable { + + public var data: Data + + public var width: Int + + public var height: Int +} + +/// The `Surface` contract (`Graphics.md`): a GL drawable in the window, +/// where a `GLSurface` view with its identifier is. +/// +/// The player's view attaches it when it appears, with its size in pixels, +/// and detaches it when it goes. While it's attached, the display link +/// calls `frame` each refresh and hands the pixels to `display`, and the +/// view's pointer and key input goes to the delegate. Main thread only. +public final class LinuxSurface: Surface { + + public let delegate: any SurfaceDelegate + + private let id: Int32 + + /// Called with each frame's pixels, for the view to show. + public var display: ((SurfacePixels) -> Void)? + + /// The drawable's size in pixels, and pixels per point, while attached. + public private(set) var size: (width: Int32, height: Int32, scale: Float)? + + public var isAttached: Bool { size != nil } + + private var pbuffer: GLLibrary.EGLSurface? + + /// Moves since the last frame, one per pointer, in arrival order. + private var pendingMoves: [(id: Int32, kind: Int32, x: Float, y: Float, buttons: Int32, timestamp: Int64)] = [] + + /// Pointers in contact, by id: their kind and where they last were. + private var contacts: [Int32: (kind: Int32, x: Float, y: Float)] = [:] + + /// Keys down, which alone get key-ups: after focus is lost, none does. + private var pressedKeys: Set = [] + + private var isFocused = false + + private init(delegate: any SurfaceDelegate, id: Int32) { + self.delegate = delegate + self.id = id + } + + deinit { + if let pbuffer, let display = GLDisplay.shared { + display.destroy(pbuffer) + } + let id = self.id + Self.surfaces[id] = nil + } + + // MARK: Surface + + public static func make(_ delegate: any SurfaceDelegate) -> LinuxSurface { + let surface = LinuxSurface(delegate: delegate, id: nextID) + nextID &+= 1 + surfaces[surface.id] = Weak(surface) + return surface + } + + public func identifier() -> Int32 { + id + } + + /// There's no relative mouse mode in the window yet. + public func setPointerCaptured(_ captured: Bool) -> Bool { + false + } + + // MARK: Surfaces + + private struct Weak { + weak var surface: LinuxSurface? + init(_ surface: LinuxSurface) { self.surface = surface } + } + + nonisolated(unsafe) private static var surfaces: [Int32: Weak] = [:] + + nonisolated(unsafe) private static var nextID: Int32 = 1 + + /// The live surface whose `identifier()` a `GLSurface` node carries. + public static func surface(identifier: Int32) -> LinuxSurface? { + surfaces[identifier]?.surface + } + + /// Surfaces attached to a view, which get frames. + static var attached: [LinuxSurface] { + surfaces.values.compactMap(\.surface).filter(\.isAttached).sorted { $0.id < $1.id } + } + + // MARK: The view + + /// Puts the surface on screen at a size in pixels: it gets `resize`, + /// then frames and input. + public func attach(width: Int32, height: Int32, scale: Float) { + size = (max(1, width), max(1, height), scale) + makeDrawable() + delegate.resize(self, width: max(1, width), height: max(1, height), scale: scale) + DisplayLink.shared.update() + } + + /// The view's size or scale changed. + public func resize(width: Int32, height: Int32, scale: Float) { + guard let size else { return } + let width = max(1, width), height = max(1, height) + guard size.width != width || size.height != height || size.scale != scale else { return } + self.size = (width, height, scale) + if size.width != width || size.height != height { + destroyDrawable() + makeDrawable() + } + delegate.resize(self, width: width, height: height, scale: scale) + } + + /// The view is gone: pointers in contact are cancelled and focus lost, + /// and frames stop. + public func detach() { + guard isAttached else { return } + cancelContacts() + focus(false) + destroyDrawable() + size = nil + DisplayLink.shared.update() + } + + private func makeDrawable() { + guard pbuffer == nil, let size, let display = GLDisplay.shared, display.makeContext() else { return } + pbuffer = display.makeSurface(width: size.width, height: size.height) + } + + private func destroyDrawable() { + if let pbuffer, let display = GLDisplay.shared { + display.destroy(pbuffer) + } + pbuffer = nil + } + + // MARK: Frames + + /// Sends the moves since the last frame, makes the context current on + /// the surface, has the delegate draw, and reads the frame back. `nil` + /// without GL, or when the context was lost: the delegate has been told, + /// and the next frame is in a new one. + @discardableResult + public func frame(timestamp: Int64) -> SurfacePixels? { + guard let size else { return nil } + flushMoves() + guard let display = GLDisplay.shared, let pbuffer else { return nil } + switch display.makeCurrent(pbuffer) { + case .success: + break + case let .failure(error): + if error.isContextLost { + Self.replaceContext() + } else { + HostLog.warning("graphics: can't draw surface \(id): \(error)") + } + return nil + } + delegate.frame(self, timestamp: timestamp, width: size.width, height: size.height) + let pixels = SurfacePixels( + data: display.readPixels(width: size.width, height: size.height), + width: Int(size.width), + height: Int(size.height) + ) + display.restoreCurrent() + self.display?(pixels) + return pixels + } + + /// The context is gone: every surface's delegate hears so, a new + /// context replaces it, and they hear that too (`Graphics.md`, step 6). + static func replaceContext() { + guard let display = GLDisplay.shared else { return } + let surfaces = surfaces.values.compactMap(\.surface).sorted { $0.id < $1.id } + for surface in surfaces { + surface.delegate.contextLost(surface) + } + for surface in surfaces { + surface.destroyDrawable() + } + display.destroyContext() + guard display.makeContext() else { return } + for surface in surfaces where surface.isAttached { + surface.makeDrawable() + } + for surface in surfaces { + surface.delegate.contextRestored(surface) + } + } + + // MARK: Input + + /// A pointer event, in pixels of the drawable from its top left. Moves + /// wait for the next frame, one per pointer. + public func pointer(id pointer: Int32, kind: PointerKind, phase: PointerPhase, x: Float, y: Float, buttons: PointerButtons, timestamp: Int64) { + guard isAttached else { return } + if phase == .move { + contacts[pointer]?.x = x + contacts[pointer]?.y = y + let move = (pointer, kind.rawValue, x, y, buttons.rawValue, timestamp) + if let index = pendingMoves.firstIndex(where: { $0.id == pointer }) { + pendingMoves[index] = move + } else { + pendingMoves.append(move) + } + return + } + // Its own move comes first, so the delegate sees them in order. + if let index = pendingMoves.firstIndex(where: { $0.id == pointer }) { + let move = pendingMoves.remove(at: index) + delegate.pointer(self, id: move.id, kind: move.kind, phase: PointerPhase.move.rawValue, x: move.x, y: move.y, buttons: move.buttons, timestamp: move.timestamp) + } + switch phase { + case .down: contacts[pointer] = (kind.rawValue, x, y) + case .up, .cancel: contacts[pointer] = nil + case .move: break + } + delegate.pointer(self, id: pointer, kind: kind.rawValue, phase: phase.rawValue, x: x, y: y, buttons: buttons.rawValue, timestamp: timestamp) + } + + private func flushMoves() { + let moves = pendingMoves + pendingMoves.removeAll() + for move in moves { + delegate.pointer(self, id: move.id, kind: move.kind, phase: PointerPhase.move.rawValue, x: move.x, y: move.y, buttons: move.buttons, timestamp: move.timestamp) + } + } + + /// A wheel or trackpad scroll, in pixels. + public func scroll(x: Float, y: Float) { + guard isAttached else { return } + delegate.scroll(self, x: x, y: y) + } + + /// A key, by its USB HID usage ID. Only while focused; a key-up only + /// for a key that went down since focus came. + public func key(code: Int32, pressed: Bool, modifiers: KeyModifiers, isRepeat: Bool, timestamp: Int64) { + guard isAttached, isFocused else { return } + if pressed { + pressedKeys.insert(code) + } else if pressedKeys.remove(code) == nil { + return + } + delegate.key(self, code: code, pressed: pressed, modifiers: modifiers.rawValue, isRepeat: isRepeat, timestamp: timestamp) + } + + /// Keyboard focus came or went. Before it goes, pointers in contact + /// are cancelled; after, every key counts as released. + public func focus(_ focused: Bool) { + guard focused != isFocused else { return } + if !focused { + cancelContacts() + pressedKeys.removeAll() + } + isFocused = focused + delegate.focus(self, focused: focused) + } + + /// Cancels every pointer in contact, where it last was. + private func cancelContacts() { + pendingMoves.removeAll() + let timestamp = MainLoop.now() + for (pointer, contact) in contacts.sorted(by: { $0.key < $1.key }) { + delegate.pointer(self, id: pointer, kind: contact.kind, phase: PointerPhase.cancel.rawValue, x: contact.x, y: contact.y, buttons: 0, timestamp: timestamp) + } + contacts.removeAll() + } +} From 4e1623ebd1abdbaaaa201d2a311c5e3f7d627596 Mon Sep 17 00:00:00 2001 From: Alsey Coleman Miller Date: Sun, 15 Nov 2026 22:13:19 -0500 Subject: [PATCH 04/21] Drew surfaces on screen about 60 times a second on the main loop --- Sources/LinuxGraphics/DisplayLink.swift | 54 +++++++++++++++++++++++++ 1 file changed, 54 insertions(+) create mode 100644 Sources/LinuxGraphics/DisplayLink.swift diff --git a/Sources/LinuxGraphics/DisplayLink.swift b/Sources/LinuxGraphics/DisplayLink.swift new file mode 100644 index 0000000..ace46bf --- /dev/null +++ b/Sources/LinuxGraphics/DisplayLink.swift @@ -0,0 +1,54 @@ +import LinuxHost + +/// Calls `frame` on every attached surface about 60 times a second, on the +/// main loop, while any is attached (`Graphics.md`, step 4). +/// +/// Cacao has no display callback to hook, and its window refreshes at most +/// as often, so a timer on the loop that runs the guest stands in for one. +final class DisplayLink { + + nonisolated(unsafe) static let shared = DisplayLink() + + /// Nanoseconds between frames. + var interval: Int64 = 1_000_000_000 / 60 + + private var timer: MainLoop.TimerToken? + + private var deadline: Int64 = 0 + + /// Starts or stops with the surfaces attached. + func update() { + if LinuxSurface.attached.isEmpty { + if let timer { + MainLoop.shared.cancel(timer) + self.timer = nil + } + } else if timer == nil { + deadline = MainLoop.now() + schedule() + } + } + + private func schedule() { + deadline += interval + // A frame that took too long doesn't make the next ones hurry. + let now = MainLoop.now() + if deadline < now { + deadline = now + } + timer = MainLoop.shared.schedule(at: deadline) { [weak self] in + self?.tick() + } + } + + private func tick() { + timer = nil + let surfaces = LinuxSurface.attached + guard !surfaces.isEmpty else { return } + let timestamp = MainLoop.now() + for surface in surfaces { + surface.frame(timestamp: timestamp) + } + schedule() + } +} From 20036e755e71701c33344f9b2aa538f7f4fcf89d Mon Sep 17 00:00:00 2001 From: Alsey Coleman Miller Date: Sun, 15 Nov 2026 22:13:19 -0500 Subject: [PATCH 05/21] Added the graphics host module --- Sources/LinuxGraphics/LinuxGraphics.swift | 30 +++++++++++++++++++++++ 1 file changed, 30 insertions(+) create mode 100644 Sources/LinuxGraphics/LinuxGraphics.swift diff --git a/Sources/LinuxGraphics/LinuxGraphics.swift b/Sources/LinuxGraphics/LinuxGraphics.swift new file mode 100644 index 0000000..632ffd6 --- /dev/null +++ b/Sources/LinuxGraphics/LinuxGraphics.swift @@ -0,0 +1,30 @@ +import DynamicGraphics +import DynamicRuntime +import LinuxHost +import RuntimeABI + +/// The graphics contracts (`Graphics.md`, `Plan.md` §7): GL surfaces over +/// EGL, drawn into pbuffers and shown by the player's `GLSurface` view. +/// Main loop only. +public enum LinuxGraphics: HostModule { + + public static var contracts: [ContractDescriptor] { + [SurfaceProxy.descriptor, SurfaceDelegateProxy.descriptor] + } + + public static func register(in registrar: some ContractRegistrar) { + SurfaceProxy.register(LinuxSurface.self, in: registrar) + SurfaceDelegateProxy.registerInterface(in: registrar) + } + + /// `graphics` is granted where EGL and GLES 2.0 are installed, and + /// unavailable elsewhere. + public static func permissionProviders() -> [Capability: any PermissionProvider] { + [.graphics: isAvailable ? GrantedPermission() : UnavailablePermission()] + } + + /// Whether `libEGL` and `libGLESv2` load. + public static var isAvailable: Bool { + GLLibrary.shared != nil + } +} From 730ae4b2c4d9b2a32961249e6a33d26c8d201080 Mon Sep 17 00:00:00 2001 From: Alsey Coleman Miller Date: Sun, 15 Nov 2026 22:13:19 -0500 Subject: [PATCH 06/21] Tested surfaces' input, frames and lost contexts --- Tests/LinuxGraphicsTests/SurfaceTests.swift | 247 ++++++++++++++++++++ 1 file changed, 247 insertions(+) create mode 100644 Tests/LinuxGraphicsTests/SurfaceTests.swift diff --git a/Tests/LinuxGraphicsTests/SurfaceTests.swift b/Tests/LinuxGraphicsTests/SurfaceTests.swift new file mode 100644 index 0000000..0864b3a --- /dev/null +++ b/Tests/LinuxGraphicsTests/SurfaceTests.swift @@ -0,0 +1,247 @@ +import DynamicGraphics +import Foundation +import Testing +@testable import LinuxGraphics + +/// Records what a surface tells its delegate, and draws what `draw` says. +final class RecordingDelegate: SurfaceDelegate { + + var events: [String] = [] + + var draw: ((Int32, Int32) -> Void)? + + func frame(_ surface: Surface, timestamp: Int64, width: Int32, height: Int32) { + events.append("frame \(width)x\(height)") + draw?(width, height) + } + + func resize(_ surface: Surface, width: Int32, height: Int32, scale: Float) { + events.append("resize \(width)x\(height)@\(scale)") + } + + func contextLost(_ surface: Surface) { + events.append("lost") + } + + func contextRestored(_ surface: Surface) { + events.append("restored") + } + + func pointer(_ surface: Surface, id: Int32, kind: Int32, phase: Int32, x: Float, y: Float, buttons: Int32, timestamp: Int64) { + let name = ["down", "move", "up", "cancel"][Int(phase)] + events.append("pointer \(id) \(name) \(Int(x)),\(Int(y)) \(buttons)") + } + + func pointerDelta(_ surface: Surface, x: Float, y: Float, timestamp: Int64) { + events.append("delta") + } + + func scroll(_ surface: Surface, x: Float, y: Float) { + events.append("scroll \(Int(x)),\(Int(y))") + } + + func key(_ surface: Surface, code: Int32, pressed: Bool, modifiers: Int32, isRepeat: Bool, timestamp: Int64) { + events.append("key \(code) \(pressed ? "down" : "up")\(isRepeat ? " repeat" : "") \(modifiers)") + } + + func focus(_ surface: Surface, focused: Bool) { + events.append("focus \(focused)") + } + + func pointerCapture(_ surface: Surface, captured: Bool) { + events.append("capture \(captured)") + } +} + +/// Surfaces share the GL context and the display link: one at a time. +@Suite(.serialized) struct SurfaceTests { + + static var hasGL: Bool { + GLDisplay.shared != nil + } + + @Test func identifiersFindLiveSurfaces() { + let delegate = RecordingDelegate() + var first: LinuxSurface? = LinuxSurface.make(delegate) + let second = LinuxSurface.make(delegate) + let id = first!.identifier() + #expect(id != second.identifier()) + #expect(LinuxSurface.surface(identifier: id) === first) + first = nil + #expect(LinuxSurface.surface(identifier: id) == nil) + #expect(LinuxSurface.surface(identifier: second.identifier()) === second) + #expect(!second.setPointerCaptured(true)) + } + + @Test func noInputWithoutAView() { + let delegate = RecordingDelegate() + let surface = LinuxSurface.make(delegate) + surface.pointer(id: 0, kind: .mouse, phase: .down, x: 1, y: 1, buttons: .primary, timestamp: 0) + surface.scroll(x: 0, y: 10) + surface.focus(true) + surface.key(code: KeyCode.space.rawValue, pressed: true, modifiers: [], isRepeat: false, timestamp: 0) + #expect(!delegate.events.contains { $0.hasPrefix("pointer") || $0.hasPrefix("scroll") || $0.hasPrefix("key") }) + } + + @Test func movesWaitForTheFrameOnePerPointer() { + let delegate = RecordingDelegate() + let surface = LinuxSurface.make(delegate) + surface.attach(width: 8, height: 4, scale: 2) + defer { surface.detach() } + delegate.events.removeAll() + + surface.pointer(id: 0, kind: .mouse, phase: .move, x: 1, y: 1, buttons: [], timestamp: 1) + surface.pointer(id: 0, kind: .mouse, phase: .move, x: 2, y: 2, buttons: [], timestamp: 2) + surface.pointer(id: 1, kind: .touch, phase: .down, x: 5, y: 5, buttons: .primary, timestamp: 3) + surface.pointer(id: 1, kind: .touch, phase: .move, x: 6, y: 6, buttons: .primary, timestamp: 4) + surface.pointer(id: 0, kind: .mouse, phase: .move, x: 3, y: 3, buttons: [], timestamp: 5) + #expect(delegate.events == ["pointer 1 down 5,5 1"]) + + surface.frame(timestamp: 6) + #expect(Array(delegate.events.prefix(3)) == ["pointer 1 down 5,5 1", "pointer 0 move 3,3 0", "pointer 1 move 6,6 1"]) + + // A pointer's own move goes before its up. + delegate.events.removeAll() + surface.pointer(id: 1, kind: .touch, phase: .move, x: 7, y: 7, buttons: .primary, timestamp: 7) + surface.pointer(id: 1, kind: .touch, phase: .up, x: 7, y: 7, buttons: [], timestamp: 8) + #expect(delegate.events == ["pointer 1 move 7,7 1", "pointer 1 up 7,7 0"]) + } + + @Test func losingFocusCancelsContactsAndReleasesKeys() { + let delegate = RecordingDelegate() + let surface = LinuxSurface.make(delegate) + surface.attach(width: 8, height: 4, scale: 1) + defer { surface.detach() } + surface.focus(true) + delegate.events.removeAll() + + surface.pointer(id: 0, kind: .mouse, phase: .down, x: 2, y: 3, buttons: .primary, timestamp: 1) + surface.pointer(id: 0, kind: .mouse, phase: .move, x: 4, y: 3, buttons: .primary, timestamp: 2) + surface.key(code: KeyCode.w.rawValue, pressed: true, modifiers: [.shift], isRepeat: false, timestamp: 3) + surface.key(code: KeyCode.w.rawValue, pressed: true, modifiers: [.shift], isRepeat: true, timestamp: 4) + surface.focus(false) + // Every key counts as released: no key-up follows, nor any key. + surface.key(code: KeyCode.w.rawValue, pressed: false, modifiers: [], isRepeat: false, timestamp: 5) + surface.key(code: KeyCode.a.rawValue, pressed: true, modifiers: [], isRepeat: false, timestamp: 6) + #expect(delegate.events == [ + "pointer 0 down 2,3 1", + "key 26 down 1", + "key 26 down repeat 1", + "pointer 0 cancel 4,3 0", + "focus false", + ]) + } + + @Test func detachingCancelsContactsAndStopsFrames() { + let delegate = RecordingDelegate() + let surface = LinuxSurface.make(delegate) + surface.attach(width: 8, height: 4, scale: 1) + #expect(LinuxSurface.attached.contains { $0 === surface }) + surface.pointer(id: 0, kind: .mouse, phase: .down, x: 1, y: 1, buttons: .primary, timestamp: 1) + surface.detach() + #expect(delegate.events.last == "pointer 0 cancel 1,1 0") + #expect(!LinuxSurface.attached.contains { $0 === surface }) + #expect(surface.frame(timestamp: 2) == nil) + } + + @Test func resizeComesFirstAndOnChange() { + let delegate = RecordingDelegate() + let surface = LinuxSurface.make(delegate) + surface.attach(width: 8, height: 4, scale: 2) + defer { surface.detach() } + surface.resize(width: 8, height: 4, scale: 2) + surface.resize(width: 10, height: 6, scale: 2) + #expect(delegate.events.filter { $0.hasPrefix("resize") } == ["resize 8x4@2.0", "resize 10x6@2.0"]) + #expect(delegate.events.first == "resize 8x4@2.0") + } + + @Test func pixelsTurnTopDownAndPremultiplied() { + // Two rows bottom to top: green, then a red over-bright for its alpha. + let bottomUp: [UInt8] = [0, 255, 0, 255, 200, 10, 10, 128] + let data = GLDisplay.topDown(bottomUp, rowBytes: 4, height: 2) + #expect(Array(data) == [128, 10, 10, 128, 0, 255, 0, 255]) + } + + // MARK: On a real GL + + @Test(.enabled(if: SurfaceTests.hasGL)) func drawsAFrame() throws { + let gl = try #require(GLLibrary.shared) + let delegate = RecordingDelegate() + // Blue, with the top half red: GL's y runs up, so that's its upper + // rows, which come first in the frame. + delegate.draw = { width, height in + gl.glClearColor(0, 0, 1, 1) + gl.glClear(GL.GL_COLOR_BUFFER_BIT) + gl.glEnable(GL.GL_SCISSOR_TEST) + gl.glScissor(0, height / 2, width, height / 2) + gl.glClearColor(1, 0, 0, 1) + gl.glClear(GL.GL_COLOR_BUFFER_BIT) + gl.glDisable(GL.GL_SCISSOR_TEST) + } + let surface = LinuxSurface.make(delegate) + var shown: SurfacePixels? + surface.display = { shown = $0 } + surface.attach(width: 8, height: 4, scale: 1) + defer { surface.detach() } + + let pixels = try #require(surface.frame(timestamp: 1)) + #expect(shown?.data == pixels.data) + #expect(pixels.width == 8 && pixels.height == 4 && pixels.data.count == 8 * 4 * 4) + #expect(Array(pixels.data.prefix(4)) == [255, 0, 0, 255]) + #expect(Array(pixels.data.suffix(4)) == [0, 0, 255, 255]) + #expect(gl.glGetError() == 0) + #expect(delegate.events == ["resize 8x4@1.0", "frame 8x4"]) + + // A new size is a new drawable. + surface.resize(width: 6, height: 2, scale: 1) + let resized = try #require(surface.frame(timestamp: 2)) + #expect(resized.width == 6 && resized.height == 2 && resized.data.count == 6 * 2 * 4) + } + + /// SDL's renderer may draw with EGL on the same thread: its context is + /// current again after a frame. + @Test(.enabled(if: SurfaceTests.hasGL)) func theCurrentContextIsRestored() throws { + let display = try #require(GLDisplay.shared) + let gl = display.gl + let attributes: [Int32] = [GL.EGL_CONTEXT_CLIENT_VERSION, 2, GL.EGL_NONE] + let other = try #require(gl.eglCreateContext(display.display, display.config, nil, attributes)) + let otherSurface = try #require(display.makeSurface(width: 2, height: 2)) + defer { + _ = gl.eglMakeCurrent(display.display, nil, nil, nil) + display.destroy(otherSurface) + _ = gl.eglDestroyContext(display.display, other) + } + #expect(gl.eglMakeCurrent(display.display, otherSurface, otherSurface, other) != 0) + + let delegate = RecordingDelegate() + var drewIn: GLLibrary.EGLContext? + delegate.draw = { _, _ in drewIn = gl.eglGetCurrentContext() } + let surface = LinuxSurface.make(delegate) + surface.attach(width: 4, height: 4, scale: 1) + defer { surface.detach() } + #expect(surface.frame(timestamp: 1) != nil) + #expect(drewIn != nil && drewIn != other) + #expect(gl.eglGetCurrentContext() == other) + #expect(gl.eglGetCurrentSurface(GL.EGL_DRAW) == otherSurface) + } + + @Test(.enabled(if: SurfaceTests.hasGL)) func aLostContextIsReplaced() throws { + let gl = try #require(GLLibrary.shared) + let delegate = RecordingDelegate() + delegate.draw = { _, _ in + gl.glClearColor(0, 1, 0, 1) + gl.glClear(GL.GL_COLOR_BUFFER_BIT) + } + let surface = LinuxSurface.make(delegate) + surface.attach(width: 4, height: 4, scale: 1) + defer { surface.detach() } + #expect(surface.frame(timestamp: 1) != nil) + let generation = rt_gl_context_generation() + + LinuxSurface.replaceContext() + #expect(rt_gl_context_generation() != generation) + let pixels = try #require(surface.frame(timestamp: 2)) + #expect(Array(pixels.data.prefix(4)) == [0, 255, 0, 255]) + #expect(delegate.events == ["resize 4x4@1.0", "frame 4x4", "lost", "restored", "frame 4x4"]) + } +} From f2b9d0adb19b9de14d19eab940294600b3a0f903 Mon Sep 17 00:00:00 2001 From: Alsey Coleman Miller Date: Sun, 15 Nov 2026 22:13:19 -0500 Subject: [PATCH 07/21] Showed GLSurface nodes in the player, with their input --- Sources/LinuxUI/HostGLSurface.swift | 232 ++++++++++++++++++++++++++++ 1 file changed, 232 insertions(+) create mode 100644 Sources/LinuxUI/HostGLSurface.swift diff --git a/Sources/LinuxUI/HostGLSurface.swift b/Sources/LinuxUI/HostGLSurface.swift new file mode 100644 index 0000000..66ea87f --- /dev/null +++ b/Sources/LinuxUI/HostGLSurface.swift @@ -0,0 +1,232 @@ +// Node types this host draws itself, ahead of DarwinUI: `GLSurface`, a +// `LinuxSurface`'s frames and input (`Graphics.md`). Scripts/sync-darwinui.sh +// keeps this file and has NodeView ask `HostNodeViews` before it gives up +// on a type. +import DynamicGraphics +import DynamicUI +import Foundation +import LinuxGraphics +import LinuxHost +import SwiftUI + +/// The views of node types DarwinUI doesn't know. +enum HostNodeViews { + + @MainActor + static func view(for node: RenderNode, store: RenderStore) -> AnyView? { + switch node.type { + case "GLSurface": + #if os(Linux) + let identifier = Int32(clamping: node.props["surface"]?.int ?? 0) + return AnyView(GLSurfaceView(identifier: identifier)) + #else + // Apple's SwiftUI, for development: no GL here. + return AnyView(Color.black) + #endif + default: + return nil + } + } +} + +#if os(Linux) + +/// A surface's frames, with its pointer and key input going to it. +struct GLSurfaceView: View { + + let identifier: Int32 + + @StateObject private var model = GLSurfaceModel() + + @FocusState private var focused: Bool + + @Environment(\.displayScale) private var displayScale + + var body: some View { + GeometryReader { proxy in + frame + .frame(width: proxy.size.width, height: proxy.size.height) + .contentShape(Rectangle()) + .gesture( + DragGesture(minimumDistance: 0) + .onChanged { value in + focused = true + model.drag(to: value.location) + } + .onEnded { value in + model.endDrag(at: value.location) + } + ) + .onContinuousHover { phase in + if case let .active(location) = phase { + model.hover(at: location) + } + } + .focusable() + .focused($focused) + .onKeyPress(phases: .all) { press in + model.key(press) + } + .onChange(of: focused) { focused in + model.surface?.focus(focused) + } + .onAppear { + model.attach(identifier, size: proxy.size, scale: displayScale) + } + .onChange(of: proxy.size) { size in + model.resize(size, scale: displayScale) + } + .onDisappear { + model.detach() + } + } + } + + @ViewBuilder + private var frame: some View { + if let pixels = model.pixels { + Image(pixels: pixels.data, width: pixels.width, height: pixels.height, bytesPerRow: pixels.width * 4, scale: model.scale) + .resizable() + } else { + Color.black + } + } +} + +/// The view's surface and its latest frame. +final class GLSurfaceModel: ObservableObject { + + @Published private(set) var pixels: SurfacePixels? + + private(set) var surface: LinuxSurface? + + /// Pixels per point. + private(set) var scale: CGFloat = 1 + + private var isDragging = false + + func attach(_ identifier: Int32, size: CGSize, scale: CGFloat) { + guard surface == nil else { return } + guard let surface = LinuxSurface.surface(identifier: identifier) else { + HostLog.warning("graphics: no surface \(identifier) for a GLSurface") + return + } + self.surface = surface + self.scale = scale + surface.display = { [weak self] pixels in + self?.pixels = pixels + } + let (width, height) = Self.pixelSize(size, scale: scale) + surface.attach(width: width, height: height, scale: Float(scale)) + } + + func resize(_ size: CGSize, scale: CGFloat) { + guard let surface else { return } + self.scale = scale + let (width, height) = Self.pixelSize(size, scale: scale) + surface.resize(width: width, height: height, scale: Float(scale)) + } + + func detach() { + surface?.detach() + surface?.display = nil + surface = nil + isDragging = false + } + + static func pixelSize(_ size: CGSize, scale: CGFloat) -> (Int32, Int32) { + (Int32(clamping: Int((size.width * scale).rounded())), Int32(clamping: Int((size.height * scale).rounded()))) + } + + // MARK: Pointer + + func drag(to location: CGPoint) { + let phase: PointerPhase = isDragging ? .move : .down + isDragging = true + pointer(phase, at: location, buttons: .primary) + } + + func endDrag(at location: CGPoint) { + guard isDragging else { return } + isDragging = false + pointer(.up, at: location, buttons: []) + } + + func hover(at location: CGPoint) { + guard !isDragging else { return } + pointer(.move, at: location, buttons: []) + } + + /// The mouse, pointer 0, at a point in the view: pixels of the drawable. + private func pointer(_ phase: PointerPhase, at location: CGPoint, buttons: PointerButtons) { + surface?.pointer(id: 0, kind: .mouse, phase: phase, x: Float(location.x * scale), y: Float(location.y * scale), + buttons: buttons, timestamp: MainLoop.now()) + } + + // MARK: Keys + + func key(_ press: KeyPress) -> KeyPress.Result { + guard let surface, let code = HIDKeys.code(for: press.key.character) else { + return .ignored + } + surface.key(code: code, pressed: press.phase != .up, modifiers: HIDKeys.modifiers(press.modifiers), + isRepeat: press.phase == .repeat, timestamp: MainLoop.now()) + return .handled + } +} + +/// USB HID usage IDs (Keyboard/Keypad page) for the keys Cacao reports, +/// which come as characters: positions on a US layout. +enum HIDKeys { + + static func code(for character: Character) -> Int32? { + switch character { + case KeyEquivalent.return.character, "\n": return 0x28 + case KeyEquivalent.escape.character: return 0x29 + case KeyEquivalent.delete.character, "\u{7F}": return 0x2A + case KeyEquivalent.tab.character: return 0x2B + case KeyEquivalent.space.character: return 0x2C + case KeyEquivalent.rightArrow.character: return 0x4F + case KeyEquivalent.leftArrow.character: return 0x50 + case KeyEquivalent.downArrow.character: return 0x51 + case KeyEquivalent.upArrow.character: return 0x52 + case KeyEquivalent.home.character: return 0x4A + case KeyEquivalent.pageUp.character: return 0x4B + case KeyEquivalent.deleteForward.character: return 0x4C + case KeyEquivalent.end.character: return 0x4D + case KeyEquivalent.pageDown.character: return 0x4E + default: break + } + guard let scalar = character.unicodeScalars.first, character.unicodeScalars.count == 1, scalar.isASCII else { + return nil + } + let value = scalar.value + switch value { + case 0x61...0x7A: return Int32(value - 0x61 + 0x04) // a–z + case 0x41...0x5A: return Int32(value - 0x41 + 0x04) // A–Z, shifted + case 0x31...0x39: return Int32(value - 0x31 + 0x1E) // 1–9 + case 0x30: return 0x27 // 0 + default: break + } + return punctuation[character] + } + + /// Punctuation, and what Shift makes of it on a US layout. + private static let punctuation: [Character: Int32] = [ + "-": 0x2D, "_": 0x2D, "=": 0x2E, "+": 0x2E, "[": 0x2F, "{": 0x2F, "]": 0x30, "}": 0x30, + "\\": 0x31, "|": 0x31, ";": 0x33, ":": 0x33, "'": 0x34, "\"": 0x34, "`": 0x35, "~": 0x35, + ",": 0x36, "<": 0x36, ".": 0x37, ">": 0x37, "/": 0x38, "?": 0x38, + "!": 0x1E, "@": 0x1F, "#": 0x20, "$": 0x21, "%": 0x22, "^": 0x23, "&": 0x24, "*": 0x25, "(": 0x26, ")": 0x27, + ] + + static func modifiers(_ modifiers: EventModifiers) -> KeyModifiers { + var result: KeyModifiers = [] + if modifiers.contains(.shift) { result.insert(.shift) } + if modifiers.contains(.control) { result.insert(.control) } + if modifiers.contains(.option) { result.insert(.alt) } + if modifiers.contains(.command) { result.insert(.meta) } + return result + } +} + +#endif From 50979cabe4733f71f8fb9eaafaa6dc2ac6537eae Mon Sep 17 00:00:00 2001 From: Alsey Coleman Miller Date: Sun, 15 Nov 2026 22:13:19 -0500 Subject: [PATCH 08/21] Asked the host for node types DarwinUI doesn't know --- Sources/LinuxUI/NodeView.swift | 3 +++ 1 file changed, 3 insertions(+) diff --git a/Sources/LinuxUI/NodeView.swift b/Sources/LinuxUI/NodeView.swift index 29f1443..f3060f9 100644 --- a/Sources/LinuxUI/NodeView.swift +++ b/Sources/LinuxUI/NodeView.swift @@ -222,6 +222,9 @@ struct NodeView: View { return AnyView(LevelContent(level: model, store: store)) default: + if let view = HostNodeViews.view(for: node, store: store) { + return view + } UnknownTypes.log(node.type) return AnyView(EmptyView()) } From b7f41e36be9b325209e884fa37fe72f59cb9ef09 Mon Sep 17 00:00:00 2001 From: Alsey Coleman Miller Date: Sun, 15 Nov 2026 22:13:19 -0500 Subject: [PATCH 09/21] Kept the host's own player files and NodeView's hook when copying DarwinUI --- Scripts/sync-darwinui.sh | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/Scripts/sync-darwinui.sh b/Scripts/sync-darwinui.sh index 322a477..742e56d 100755 --- a/Scripts/sync-darwinui.sh +++ b/Scripts/sync-darwinui.sh @@ -6,7 +6,11 @@ # - `import DarwinHost`, which is `LinuxHost` here (LinuxUI's Host.swift # supplies the logger and bundle DarwinUI uses); # - `#if os(macOS)` code, which is for any platform but iOS: Linux is -# neither. +# neither; +# - NodeView, which asks `HostNodeViews` (HostGLSurface.swift) for a type +# it doesn't know before giving up on it: `GLSurface` is this host's. +# +# Files named Host*.swift are this host's own, and stay. # # RenderingTests hosts views in an NSHostingView; LinuxUI's own hosts them in # a Cacao view graph, as Cacao's Compatibility/DarwinUI does. One test is @@ -19,12 +23,15 @@ cd "$(dirname "$0")/.." source=${DARWIN_APP_RUNTIME_PATH:-../DarwinAppRuntime} revision=$(git -C "$source" rev-parse --short HEAD) mkdir -p Sources/LinuxUI Tests/LinuxUITests -find Sources/LinuxUI -name '*.swift' ! -name 'Host.swift' -delete +find Sources/LinuxUI -name '*.swift' ! -name 'Host*.swift' -delete find Tests/LinuxUITests -name '*.swift' ! -name 'RenderingTests.swift' -delete for file in "$source"/Sources/DarwinUI/*.swift; do sed -e 's/^import DarwinHost$/import LinuxHost/' -e 's/^#if os(macOS)$/#if !os(iOS)/' \ -e 's/^@testable import DarwinUI$/@testable import LinuxUI/' "$file" > "Sources/LinuxUI/$(basename "$file")" done +perl -0pi -e 's/(\n default:\n)( UnknownTypes\.log\(node\.type\)\n)/$1 if let view = HostNodeViews.view(for: node, store: store) {\n return view\n }\n$2/' \ + Sources/LinuxUI/NodeView.swift +grep -q 'HostNodeViews.view' Sources/LinuxUI/NodeView.swift || { echo "NodeView no longer has the default case to hook" >&2; exit 1; } for file in "$source"/Tests/DarwinUITests/*.swift; do case $(basename "$file") in RenderingTests.swift) continue ;; esac # On Linux, Swift Testing's main-actor tests don't run on the thread From 44b41c4b08ccefd4dfccc751f0feb9819c324da2 Mon Sep 17 00:00:00 2001 From: Alsey Coleman Miller Date: Sun, 15 Nov 2026 22:13:19 -0500 Subject: [PATCH 10/21] Registered the graphics module in the host app --- Sources/LinuxHostApp/HostApp.swift | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/Sources/LinuxHostApp/HostApp.swift b/Sources/LinuxHostApp/HostApp.swift index 8657544..4e2dfb8 100644 --- a/Sources/LinuxHostApp/HostApp.swift +++ b/Sources/LinuxHostApp/HostApp.swift @@ -4,6 +4,7 @@ import CLinuxHost import CacaoSDL import Foundation import LinuxBluetooth +import LinuxGraphics import LinuxUI /// The app's `main` (`Plan.md` §4): finds the app's bundle, checks and @@ -22,9 +23,9 @@ import LinuxUI /// Cacao's `CACAO_SCREENSHOT=path.png` saves the first frame and quits. public enum HostApp { - /// Every module this host has: the SwiftUI player (DarwinUI, on Cacao) - /// and Bluetooth. - public static let modules: [any HostModule.Type] = [DarwinUI.self, LinuxBluetooth.self] + /// Every module this host has: the SwiftUI player (DarwinUI, on Cacao), + /// Bluetooth, and GL surfaces, which the player shows. + public static let modules: [any HostModule.Type] = [DarwinUI.self, LinuxBluetooth.self, LinuxGraphics.self] /// The window's title: the app's name. nonisolated(unsafe) static var title = "" From d87ee11cd0369947e7974cf27d5450af0a058ccf Mon Sep 17 00:00:00 2001 From: Alsey Coleman Miller Date: Sun, 15 Nov 2026 22:13:19 -0500 Subject: [PATCH 11/21] Checked apps against the graphics contracts --- Sources/LinuxPackager/Validator.swift | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/Sources/LinuxPackager/Validator.swift b/Sources/LinuxPackager/Validator.swift index aaa4ad3..f3d6d51 100644 --- a/Sources/LinuxPackager/Validator.swift +++ b/Sources/LinuxPackager/Validator.swift @@ -1,6 +1,7 @@ import DynamicRuntime import Foundation import LinuxBluetooth +import LinuxGraphics import LinuxHost import DynamicUI import RuntimeABI @@ -9,15 +10,16 @@ import RuntimeABI public enum HostContracts { /// The modules `linux-app-host` registers (`HostApp.modules`): the - /// player's contracts, without building the player, and Bluetooth. - nonisolated(unsafe) public static let modules: [any HostModule.Type] = [PlayerContracts.self, LinuxBluetooth.self] + /// player's contracts, without building the player, Bluetooth and + /// graphics. + nonisolated(unsafe) public static let modules: [any HostModule.Type] = [PlayerContracts.self, LinuxBluetooth.self, LinuxGraphics.self] public static var provided: [String: ContractDescriptor] { AppCompatibility.providedContracts(modules) } /// Capabilities some contract here serves. - public static let capabilities: Set = [.bluetooth] + public static let capabilities: Set = [.bluetooth, .graphics] } /// How the guest's code gets into the app (`Packager.md` §2). From 53bee4a81acd562bec79c095322da5b003fbf064 Mon Sep 17 00:00:00 2001 From: Alsey Coleman Miller Date: Sun, 15 Nov 2026 22:13:19 -0500 Subject: [PATCH 12/21] Linked libGLESv2 into hosts for apps that draw --- Sources/LinuxPackager/HostPackage.swift | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/Sources/LinuxPackager/HostPackage.swift b/Sources/LinuxPackager/HostPackage.swift index 92027b8..2bb960c 100644 --- a/Sources/LinuxPackager/HostPackage.swift +++ b/Sources/LinuxPackager/HostPackage.swift @@ -22,11 +22,16 @@ public struct HostPackage { /// The app's `libapp.a`. public var library: URL - public init(directory: URL, hostPackage: URL, executable: String, library: URL) { + /// Whether the app calls GL (it declares `graphics`): its `gl*` calls + /// are `libGLESv2`'s, which the host then links. + public var linksGL: Bool + + public init(directory: URL, hostPackage: URL, executable: String, library: URL, linksGL: Bool = false) { self.directory = directory self.hostPackage = hostPackage self.executable = executable self.library = library + self.linksGL = linksGL } /// Where this package's source is: `--host-package`, then @@ -87,7 +92,7 @@ public struct HostPackage { name: "AppMain", dependencies: [.product(name: "LinuxHostApp", package: "LinuxAppRuntime")], swiftSettings: [.swiftLanguageMode(.v5)], - linkerSettings: [.unsafeFlags([\(literal(library.path))])] + linkerSettings: [.unsafeFlags([\(([library.path] + (linksGL ? ["-lGLESv2"] : [])).map(literal).joined(separator: ", "))])] ), ] ) From a0d8985030efa9605b49f7353266a1040ab03835 Mon Sep 17 00:00:00 2001 From: Alsey Coleman Miller Date: Sun, 15 Nov 2026 22:13:19 -0500 Subject: [PATCH 13/21] Linked GL for apps that declare graphics --- Sources/LinuxPackager/Packager.swift | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Sources/LinuxPackager/Packager.swift b/Sources/LinuxPackager/Packager.swift index 5a320d7..0010438 100644 --- a/Sources/LinuxPackager/Packager.swift +++ b/Sources/LinuxPackager/Packager.swift @@ -91,7 +91,8 @@ public struct Packager { func buildHost(library: URL) throws(PackagerError) -> URL { let directory = work.appendingPathComponent("host") let host = HostPackage(directory: directory, hostPackage: options.hostPackage, - executable: bundle.executable, library: try HostPackage.stage(library, in: directory)) + executable: bundle.executable, library: try HostPackage.stage(library, in: directory), + linksGL: bundle.info.capabilities.contains(.graphics)) return try host.build(configuration: options.configuration, staticSwift: options.staticSwift, extraArguments: options.buildArguments, runner: runner) } From 45a56510a55d600cfdd2366cfe78e52e54abd08a Mon Sep 17 00:00:00 2001 From: Alsey Coleman Miller Date: Sun, 15 Nov 2026 22:13:19 -0500 Subject: [PATCH 14/21] Added LinuxGraphics, and linked GLES into linux-app-host for apps that call it --- Package.swift | 27 +++++++++++++++++++++------ 1 file changed, 21 insertions(+), 6 deletions(-) diff --git a/Package.swift b/Package.swift index 3c14e19..cf8ca1e 100644 --- a/Package.swift +++ b/Package.swift @@ -14,8 +14,8 @@ import PackageDescription /// `CACAO_PATH` likewise for PureSwift/Cacao. /// - `LINUXAPPRUNTIME_APP_LIBRARY`: an app's `libapp.a` (a `linux-arm64` or /// `linux-x86_64` slice from `guest.py slice`), which `linux-app-host` -/// links. Without it, `linux-app-host` builds without an app and says so -/// when run. +/// links, with `libGLESv2` if the app calls GL. Without it, +/// `linux-app-host` builds without an app and says so when run. let environment = ProcessInfo.processInfo.environment let appRuntime: Package.Dependency = { @@ -70,6 +70,7 @@ let package = Package( .library(name: "LinuxHost", targets: ["LinuxHost"]), .library(name: "LinuxUI", targets: ["LinuxUI"]), .library(name: "LinuxBluetooth", targets: ["LinuxBluetooth"]), + .library(name: "LinuxGraphics", targets: ["LinuxGraphics"]), .library(name: "LinuxHostApp", targets: ["LinuxHostApp"]), .executable(name: "linux-app-host", targets: ["LinuxAppHost"]), .executable(name: "linux-app", targets: ["LinuxAppTool"]), @@ -100,7 +101,7 @@ let package = Package( // over Cacao's SwiftUI. .target( name: "LinuxUI", - dependencies: ["LinuxHost", runtime("DynamicUI"), runtime("DynamicRuntime"), runtime("RuntimeNative")] + swiftUI, + dependencies: ["LinuxHost", "LinuxGraphics", runtime("DynamicUI"), runtime("DynamicRuntime"), runtime("RuntimeNative")] + swiftUI, exclude: ["DARWINUI_REVISION"], swiftSettings: host ), @@ -117,13 +118,22 @@ let package = Package( swiftSettings: host ), + // MARK: - Graphics + + // GL surfaces over EGL, loaded at run time: the host links no GL. + .target( + name: "LinuxGraphics", + dependencies: ["LinuxHost", runtime("DynamicGraphics"), runtime("DynamicRuntime"), runtime("RuntimeABI")], + swiftSettings: host + ), + // MARK: - App // libc functions app slices need that older glibc lacks. .target(name: "CLinuxHost"), .target( name: "LinuxHostApp", - dependencies: ["LinuxHost", "LinuxUI", "LinuxBluetooth", "CLinuxHost", runtime("CRuntime"), + dependencies: ["LinuxHost", "LinuxUI", "LinuxBluetooth", "LinuxGraphics", "CLinuxHost", runtime("CRuntime"), .product(name: "CacaoSDL", package: "Cacao")], swiftSettings: host ), @@ -131,7 +141,11 @@ let package = Package( name: "LinuxAppHost", dependencies: ["LinuxHostApp"], swiftSettings: host + (appLibrary != nil ? [.define("APP_LINKED")] : []), - linkerSettings: appLibrary.map { [.unsafeFlags([$0])] } ?? [] + // The app's own `gl*` calls are libGLESv2's; it's needed only if + // it makes them. + linkerSettings: appLibrary.map { + [.unsafeFlags([$0, "-Xlinker", "--push-state", "-Xlinker", "--as-needed", "-lGLESv2", "-Xlinker", "--pop-state"])] + } ?? [] ), // MARK: - Packager @@ -141,7 +155,7 @@ let package = Package( // doesn't build Cacao. .target( name: "LinuxPackager", - dependencies: ["LinuxHost", "LinuxBluetooth", runtime("DynamicUI"), .product(name: "Crypto", package: "swift-crypto")] + dependencies: ["LinuxHost", "LinuxBluetooth", "LinuxGraphics", runtime("DynamicUI"), .product(name: "Crypto", package: "swift-crypto")] ), .executableTarget( name: "LinuxAppTool", @@ -157,6 +171,7 @@ let package = Package( swiftSettings: host ), .testTarget(name: "LinuxBluetoothTests", dependencies: ["LinuxBluetooth"], swiftSettings: host), + .testTarget(name: "LinuxGraphicsTests", dependencies: ["LinuxGraphics", runtime("DynamicGraphics")], swiftSettings: host), .testTarget(name: "LinuxPackagerTests", dependencies: ["LinuxPackager", "LinuxHostApp"]), ] ) From a831505e1378856bf8256fc104fc3777e9f1176e Mon Sep 17 00:00:00 2001 From: Alsey Coleman Miller Date: Sun, 15 Nov 2026 22:13:20 -0500 Subject: [PATCH 15/21] Added Mesa's EGL and GLES to the image --- Dockerfile | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/Dockerfile b/Dockerfile index d2e6760..c5d0b3f 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,12 +1,14 @@ # Linux environment for building and testing the host: Swift 6.4.2, SDL3, -# Cairo, FreeType, fontconfig and Wayland for Cacao, a font, Python -# for AppRuntime's scripts, and WABT for the packager's wasm2c engine. +# Cairo, FreeType, fontconfig and Wayland for Cacao, a font, Mesa's EGL and +# GLES 2.0 for GL surfaces (llvmpipe without a GPU), Python for AppRuntime's +# scripts, and WABT for the packager's wasm2c engine. FROM swift:6.4.2 RUN apt-get update \ && apt-get install -y --no-install-recommends \ libsdl3-dev libsdl3-ttf-dev libfontconfig-dev fonts-dejavu-core \ libcairo2-dev libfreetype-dev libwayland-dev wayland-protocols \ + libegl1 libegl-mesa0 libgles-dev libgl1-mesa-dri \ pkgconf python3 wabt curl ca-certificates \ && rm -rf /var/lib/apt/lists/* From 4560023b86b5ca6cf43fda7783f0252f60627f60 Mon Sep 17 00:00:00 2001 From: Alsey Coleman Miller Date: Sun, 15 Nov 2026 22:13:20 -0500 Subject: [PATCH 16/21] Installed Mesa's EGL and GLES in CI --- .github/workflows/swift.yml | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/.github/workflows/swift.yml b/.github/workflows/swift.yml index 09afc58..318cf6d 100644 --- a/.github/workflows/swift.yml +++ b/.github/workflows/swift.yml @@ -24,11 +24,12 @@ jobs: SDL_VIDEO_DRIVER: offscreen steps: - uses: actions/checkout@v4 - - name: Install SDL3, Cairo, FreeType, fontconfig and Wayland for Cacao + - name: Install SDL3, Cairo, FreeType, fontconfig and Wayland for Cacao, and Mesa for GL run: | apt-get update apt-get install -y --no-install-recommends libsdl3-dev libcairo2-dev libfreetype-dev \ - libfontconfig-dev libwayland-dev wayland-protocols fonts-dejavu-core + libfontconfig-dev libwayland-dev wayland-protocols fonts-dejavu-core \ + libegl1 libegl-mesa0 libgles-dev libgl1-mesa-dri - name: Build run: swift build --build-tests - name: Test From e4d6670344e4e7a46e9f43e5e5669c0b0103efb1 Mon Sep 17 00:00:00 2001 From: Alsey Coleman Miller Date: Sun, 15 Nov 2026 22:13:20 -0500 Subject: [PATCH 17/21] Mounted CACAO_PATH and passed the screenshot delay into the image --- Scripts/docker.sh | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/Scripts/docker.sh b/Scripts/docker.sh index 987f71f..c571092 100755 --- a/Scripts/docker.sh +++ b/Scripts/docker.sh @@ -1,12 +1,14 @@ #!/bin/sh # Runs a command in the Linux development image (Dockerfile), with this # checkout at /src and, if APPRUNTIME_PATH is set, that AppRuntime checkout at -# /AppRuntime. Builds go to .build/linux, apart from a Mac's .build. +# /AppRuntime; likewise CACAO_PATH at /Cacao. Builds go to .build/linux, apart +# from a Mac's .build. # # Scripts/docker.sh swift test --scratch-path .build/linux # APPRUNTIME_PATH=~/Developer/AppRuntime Scripts/docker.sh swift build --scratch-path .build/linux # -# LINUXAPPRUNTIME_APP_LIBRARY, a path inside the container, is passed through. +# LINUXAPPRUNTIME_APP_LIBRARY, a path inside the container, and +# CACAO_SCREENSHOT_DELAY are passed through. set -e root=$(cd "$(dirname "$0")/.." && pwd) image=linuxappruntime-dev @@ -16,13 +18,15 @@ if ! docker image inspect "$image" >/dev/null 2>&1; then fi command="$*" +set -- if [ -n "$APPRUNTIME_PATH" ]; then - set -- -v "$APPRUNTIME_PATH:/AppRuntime" -e APPRUNTIME_PATH=/AppRuntime -else - set -- + set -- "$@" -v "$APPRUNTIME_PATH:/AppRuntime" -e APPRUNTIME_PATH=/AppRuntime +fi +if [ -n "$CACAO_PATH" ]; then + set -- "$@" -v "$CACAO_PATH:/Cacao" -e CACAO_PATH=/Cacao fi exec docker run --rm \ -v "$root:/src" -w /src \ -v linuxappruntime-swiftpm:/root/.cache \ - -e LINUXAPPRUNTIME_APP_LIBRARY \ + -e LINUXAPPRUNTIME_APP_LIBRARY -e CACAO_SCREENSHOT_DELAY \ "$@" "$image" bash -c "$command" From 2984c37fd064d165a3ce085fef2a4fd48b20cc19 Mon Sep 17 00:00:00 2001 From: Alsey Coleman Miller Date: Sun, 15 Nov 2026 22:13:20 -0500 Subject: [PATCH 18/21] Documented the screenshot delay for GL surfaces --- Scripts/run-app.sh | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/Scripts/run-app.sh b/Scripts/run-app.sh index aa71483..47db391 100755 --- a/Scripts/run-app.sh +++ b/Scripts/run-app.sh @@ -1,7 +1,9 @@ #!/bin/sh # Builds linux-app-host linked with a universal bundle's Linux slice and runs # it in the development image, headless (SDL's offscreen driver), saving its -# first frame to SCREENSHOT (inside this checkout) and quitting. The bundle +# first frame to SCREENSHOT (inside this checkout) and quitting; with +# CACAO_SCREENSHOT_DELAY=seconds, the first after that, as for a GL surface, +# whose frames come after the window's first. The bundle # must be inside this checkout, such as .build/guest/.app from # AppRuntime's `guest.py bundle --target linux-arm64 --output .build/guest`. # From ef296e7bf0528a83a6d944bb12f3cb2258306e9b Mon Sep 17 00:00:00 2001 From: Alsey Coleman Miller Date: Sun, 15 Nov 2026 22:13:20 -0500 Subject: [PATCH 19/21] Showed ExampleGL on Linux --- Documentation/ExampleGL.png | Bin 0 -> 21318 bytes 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 Documentation/ExampleGL.png diff --git a/Documentation/ExampleGL.png b/Documentation/ExampleGL.png new file mode 100644 index 0000000000000000000000000000000000000000..491cc7de31c1cdeed332bf5adbe9ec57aaff9929 GIT binary patch literal 21318 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 Date: Sun, 15 Nov 2026 22:13:20 -0500 Subject: [PATCH 20/21] Documented GL surfaces --- Documentation/Plan.md | 54 ++++++++++++++++++++++++++++++++++++++----- 1 file changed, 48 insertions(+), 6 deletions(-) diff --git a/Documentation/Plan.md b/Documentation/Plan.md index 55f68f5..be994ec 100644 --- a/Documentation/Plan.md +++ b/Documentation/Plan.md @@ -28,6 +28,7 @@ into a Linux program: - the **SwiftUI player**: DarwinAppRuntime's renderer of the SwiftUI frontend's render IR, on Cacao's SwiftUI for Linux; - **Bluetooth** over BlueZ's D-Bus API; +- **GL surfaces**, OpenGL ES 2.0 over EGL, in the player's views; - the **packager**, `linux-app` ([Packager.md](Packager.md)). References like §7.6 are to `Documentation/DynamicRuntime.md` in AppRuntime; @@ -44,7 +45,7 @@ AppRuntime's contracts. | arm64 and x86_64 Linux with glibc (Debian 13, Ubuntu 24.04+) | armv7, musl | | Native slices linked into the host | wasm2c (AppRuntime's shim, as on Darwin); WasmKit for development | | Wayland and X11 through SDL3; a headless driver for tests | Multiple windows | -| `Renderer`, Bluetooth `Central` and friends, the built-ins | Location (GeoClue), Device (UPower, sysfs), Networking (libcurl), Formatting (ICU), Motion (iio-sensor-proxy), NFC (neard) | +| `Renderer`, Bluetooth `Central` and friends, GL surfaces, the built-ins | Location (GeoClue), Device (UPower, sysfs), Networking (libcurl), Formatting (ICU), Motion (iio-sensor-proxy), NFC (neard) | ## 2. Process model @@ -54,6 +55,7 @@ AppRuntime's contracts. │ ├── runtime core: RuntimeCore + RuntimeNative (rt_* symbols) │ │ ├── MainLoop: timers, jobs from other threads │ │ ├── LinuxBluetooth: BlueZ over D-Bus (NIO threads → MainLoop) │ +│ ├── LinuxGraphics: GL surfaces, EGL pbuffers read back │ │ ├── LinuxUI: DarwinUI, render IR → SwiftUI views → events │ │ │ └── Cacao: SwiftUI, Silica/Cairo, SDL3 windows and input │ │ └── libapp.a: the app's sealed linux-arm64 / linux-x86_64 slice│ @@ -86,8 +88,9 @@ timers for `schedule`. | `LinuxHost` | `AppHost` (built-ins, modules, `rt_main`), `MainLoop`, `MainLoopClock`, the `Bundle` built-in; over AppRuntime's `RuntimeHost`, which every host shares: `AppInfo` (the bundle's `Info.plist` keys), the compatibility checks, `HostModule`, and the `Permissions` and `Application` built-ins | | `LinuxUI` | The SwiftUI player: DarwinAppRuntime's `DarwinUI`, copied by `Scripts/sync-darwinui.sh`, over Cacao's `SwiftUI` and `Combine` modules; `Host.swift` gives it the logger and bundle it takes from its host | | `LinuxBluetooth` | `Central`, `Peripheral`, `Service`, `Characteristic`, `Descriptor`, `Advertisement` over BlueZ | +| `LinuxGraphics` | `Surface` over EGL and GLES 2.0, loaded at run time; the player's `GLSurface` view shows it (§7) | | `LinuxHostApp` | `main`: reads the app's keys, starts the host, and runs Cacao's SDL loop with one window showing the guest's first renderer | -| `LinuxPackager`, `linux-app` | The packager (§8, [Packager.md](Packager.md)) | +| `LinuxPackager`, `linux-app` | The packager (§9, [Packager.md](Packager.md)) | The package depends on AppRuntime without its `GuestExports` trait, like DarwinAppRuntime, so the slice's `rt_dispatch` and `rt_finalize` are the @@ -103,7 +106,8 @@ only ones linked (`HostRuntime.md` §8 in DarwinAppRuntime). contract this host lacks. 3. `NativeRuntime.shared.bindDirectly()`; set capabilities; set the clock. 4. Register the built-ins (`Permissions`, `Bundle`, `Application`) and each - module the app uses (`LinuxUI` for `Renderer`, `LinuxBluetooth`). + module the app uses (`LinuxUI` for `Renderer`, `LinuxBluetooth`, + `LinuxGraphics`). 5. Call `rt_main`. When the guest calls `Renderer.make`, the player adds its scene; the first tree is there before `rt_main` returns. 6. Run Cacao's loop until the window closes, the window showing the first @@ -167,18 +171,56 @@ errors map to `BluetoothError` (`org.bluez.Error.NotConnected` → `NotSupported` → `operationNotSupported`, `InProgress` / `Failed` with a connection → `connectionFailed`, …); anything else is `unknown`, and logged. -## 7. Testing +## 7. GL surfaces + +`LinuxGraphics` implements `Surface` (AppRuntime's `Graphics.md`), and the +player draws `GLSurface` nodes. Cacao composites the window itself, from +Cairo drawings and images, so a surface is drawn offscreen and shown as an +image: + +- **No GL at build time.** The host opens `libEGL.so.1` and + `libGLESv2.so.2` when it starts; without them `graphics` is + unavailable. An app that declares `graphics` has `libGLESv2` linked in by + the packager, for its own `gl*` calls, which are the same library's. +- **One context for the app**, GLES 2.0, on Mesa's surfaceless platform + where there is one, otherwise the driver's default display. Each surface + on screen has a pbuffer of its size in pixels, the default framebuffer + the guest draws in. Sharing the context keeps the wasm2c shim's buffer + bindings right from one surface to the next; `rt_gl_context_generation` + changes when the context is replaced. +- **Frames**: a timer on the main loop, about 60 times a second while a + surface is on screen, makes the context current on its pbuffer, calls + `frame`, and reads the pixels back, rows flipped and alpha + premultiplied, into Cacao's `Image(pixels:)`. Moves since the last frame + go first, one per pointer. If the context is lost, every surface hears + `contextLost`, then `contextRestored` with a new one. +- **The view** (`Sources/LinuxUI/HostGLSurface.swift`, which + `sync-darwinui.sh` keeps, hooked into NodeView's unknown types) attaches + the surface when it appears, with its size in pixels and `resize` before + the first frame, and detaches it when it goes, which cancels pointers in + contact and takes focus. A drag is the mouse, pointer 0, with the primary + button, and hovering moves it; a click focuses the surface, and keys go + to it as USB HID usage IDs from Cacao's key characters, a US layout's + positions. +- **Not yet**: pointer capture (`setPointerCaptured` returns `false`), + scrolling, touches as touches, other mouse buttons, and pausing while the + window is in the background. Reading back each frame costs a copy; a GL + backend for Cacao's compositor could show the pbuffer as a texture. + +## 8. Testing - `LinuxUI`: DarwinUI's tests, on Cacao (§5). - `LinuxBluetooth`: the contract against a fake `BlueZBus` that plays BlueZ's objects and signals. Runs on macOS and Linux. +- `LinuxGraphics`: a surface's input order, focus and size, and on Linux + frames drawn and read back with Mesa's llvmpipe, and a lost context. - End to end: AppRuntime's `ExampleUI` built as a `linux-arm64` slice, linked into `linux-app-host` and run headless with SDL's `offscreen` driver, its first frame saved with `CACAO_SCREENSHOT`. - Real BlueZ needs hardware: manual runs on a Raspberry Pi or a laptop with `bluetoothd`. -## 8. Phases +## 9. Phases 1. **Host runtime and player**: `LinuxHost`, `LinuxUI`, `LinuxBluetooth`, `LinuxHostApp`; `ExampleUI` runs in Docker. @@ -193,7 +235,7 @@ connection → `connectionFailed`, …); anything else is `unknown`, and logged. 4. **Player**: what DarwinUI and Cacao add: Cacao's AT-SPI bridge, input replay for end-to-end tests. -## 9. Open questions +## 10. Open questions - **Permissions.** Desktop Linux has no prompts for Bluetooth; Flatpak's portals cover location and the camera. `Permissions.request` answers from From ecb6654f8f15cf3fe0c58701903e2cd84671304a Mon Sep 17 00:00:00 2001 From: Alsey Coleman Miller Date: Sun, 15 Nov 2026 22:13:20 -0500 Subject: [PATCH 21/21] Described GL surfaces --- README.md | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 1638cde..d853c97 100644 --- a/README.md +++ b/README.md @@ -11,6 +11,7 @@ Linux program: frontend's render IR, on [Cacao](https://github.com/PureSwift/Cacao), SwiftUI for Linux; - **Bluetooth** LE central over BlueZ's D-Bus API; +- **GL surfaces**: OpenGL ES 2.0 in a SwiftUI view, over EGL; - the **packager**, `linux-app`, which turns a universal bundle into an installable app. @@ -25,6 +26,11 @@ through wasm2c, and the packaged app runs. See the ![ExampleUI on Linux](Documentation/ExampleUI.png) +`ExampleGL` draws its triangle in a `GLSurface` the same way, with Mesa's +llvmpipe: + +![ExampleGL on Linux](Documentation/ExampleGL.png) + ## Modules | Module | | @@ -32,17 +38,20 @@ through wasm2c, and the packaged app runs. See the | `LinuxHost` | `AppHost` (built-ins, modules, `rt_main`), `MainLoop` and its clock, and the `Bundle` built-in, over AppRuntime's shared `RuntimeHost` (`AppInfo`, compatibility checks, `HostModule`, `Permissions`, `Application`) | | `LinuxUI` | The SwiftUI player: DarwinAppRuntime's `DarwinUI`, copied by `Scripts/sync-darwinui.sh`, over Cacao's `SwiftUI` | | `LinuxBluetooth` | `Central`, `Peripheral`, `Service`, `Characteristic`, `Descriptor` and `Advertisement` over BlueZ, through `wendylabsinc/dbus` | +| `LinuxGraphics` | `Surface`: GLES 2.0 drawn in EGL pbuffers, loaded at run time, and read back into the player's `GLSurface` view ([plan](Documentation/Plan.md) §7) | | `LinuxHostApp`, `linux-app-host` | The app's `main`: the host, and Cacao's window and loop | | `LinuxPackager`, `linux-app` | The packager: validation, the host build, wasm2c, the install tree, PortMaster ports | ## Building -Swift 6.4.2 (`.swift-version`), and SDL3, Cairo, FreeType, fontconfig and -Wayland for Cacao: +Swift 6.4.2 (`.swift-version`); SDL3, Cairo, FreeType, fontconfig and +Wayland for Cacao; and EGL and GLES 2.0, which GL surfaces load at run time +and apps that draw link (Mesa's draw without a GPU): ```sh apt-get install libsdl3-dev libcairo2-dev libfreetype-dev libfontconfig-dev \ - libwayland-dev wayland-protocols fonts-dejavu-core + libwayland-dev wayland-protocols fonts-dejavu-core \ + libegl1 libegl-mesa0 libgles-dev libgl1-mesa-dri swift build swift test ``` @@ -55,7 +64,8 @@ Scripts/docker.sh swift test --scratch-path .build/linux ``` AppRuntime and Cacao (its `develop` branch) come from GitHub. -`APPRUNTIME_PATH` and `CACAO_PATH` point at local checkouts instead. +`APPRUNTIME_PATH` and `CACAO_PATH` point at local checkouts instead, and +`Scripts/docker.sh` mounts them. `Scripts/sync-darwinui.sh` updates the player from a DarwinAppRuntime checkout beside this one.