admin
20dc21448e
ltk ran on Wayland and Android only. Running crustace and its apps in a browser needs, first, ltk apps running there; a window manager for the page is the next step. The runtime was already split from Wayland by the platform layer, so what kept it out of a browser was what the core and the runtime took from the operating system: calloop's epoll loop, EGL, a monotonic clock, a file system, threads and environment variables. The core builds for wasm32-unknown-unknown. `ltk::ChannelSender` is ltk's own type instead of a re-export of calloop's `Sender`, with the same `send` and `Clone`, so apps that only send and clone it build unchanged. The runtime arms its timers and channels through `event_loop/sources.rs` instead of a calloop `LoopHandle`: calloop's natively, and in a browser a queue the backend runs, which takes the due timers out, runs them on `AppData` and hands them back, and does not arm again one removed meanwhile. calloop, khronos-egl and raw-window-handle are dependencies off wasm32 only, where `egl_context.rs`, `UiSurface::try_new_gles` and `from_current_gles_loader` and the native GL names of `BorrowedGlesTexture` are left out; `sub_canvas` clones the uniform locations, which are `Copy` natively and only `Clone` on wasm. The monotonic clock is `crate::time::Instant`, `web_time`'s on wasm32, where `chrono` takes its `wasmbind` feature; the one subtraction that could go below the clock's origin, a surface's first `last_draw`, saturates. Themes, fonts, keyboard layouts and images are read through `vfs.rs`, the file system natively and on wasm32 files held in memory, so a wallpaper or an `Image::from_path` is now decoded from the file's bytes and its format told from its contents rather than its extension. The text-scale watcher, which runs gsettings on a thread, is left out on wasm32, and the built-in keyboard takes its language from `platform::language()`, `LANG` or the page's. criterion is a dev-dependency off wasm32 only, since rayon does not build there. The browser backend is the `web` feature, `platform/web/`, with wasm-bindgen, wasm-bindgen-futures, js-sys and web-sys. `build.rs` refuses it with another backend or for another target. A page's main thread must not block, so `ltk::run` sets the app up and returns, and the browser drives the loop: `AppData` lives in a closure a thread-local loop holds, which a `setTimeout` runs for messages, timers and page events and a `requestAnimationFrame` runs to draw. Event listeners and `ChannelSender::send` only queue and schedule, never touching `AppData`, so nothing they set off runs inside an iteration. The app draws on a canvas laid over the whole page, or the one `ltk::web::set_canvas` gives, through WebGL2 with the GLES canvas unchanged, its frame kept in its FBO, or without WebGL2 through `putImageData`. A lost context drops the GPU canvases and draws nothing until it is restored on a new `glow::Context`, so the glyph atlas and the caches of the old one are not reused. The main surface's logical size is the canvas's CSS size; the window's `resize` refits it, and on ltk's own canvas a hidden element padded by `env( safe-area-inset-* )` gives the insets. Input comes from Pointer Events, a mouse as the pointer and fingers and pens as touches, the wheel, in detents when it scrolls lines, and keys, whose keysym comes from `KeyboardEvent.key` and code from `.code` as the Linux input code Wayland reports; keys repeat on the browser's clock, AltGr types its character, and on macOS Command is Ctrl. ltk takes every key the browser lets a page have, and while fullscreen those `navigator.keyboard.lock()` adds in Chromium. Copies go to `navigator.clipboard.writeText`; a page reads the clipboard only from a `paste` event, so Ctrl+V is let through to the browser and held until its `paste` has put the text in `AppData::clipboard`, and a paste from the browser's menu comes with a Ctrl+V of its own. The cursor's shape is the canvas's CSS `cursor`. The built-in keyboard serves text where the page is used by touch. Panics go to the browser's console. When the app exits, the listeners are removed, the canvas receives an `ltk-exit` event and the app is dropped. The new `RunError::NoDocument` is returned where there is no page, as in a worker. Resources are the tree an Android package carries. `scripts/web-assets.sh` builds it through `android-assets.sh`, and `ltk::web::load_resources( base ).await` fetches its `MANIFEST` and every file it lists, with the manifest's hash in their URLs so a changed tree is not served from the browser's cache, into memory under `/ltk`, which becomes the resource directory. The per-script fallback fonts are read through `resources::read_font`, so a path that does not exist is found by file name in the resource directory's `fonts/`, where a page bundles them. A surface's scale may be fractional. `SurfaceState::scale_factor` is an `f32`, which `Platform::prepare_canvas`, `Presentation::scale` and the paint path take as it is; a surface's physical size is its logical size times the scale, rounded once, and `buffer_scale()` gives the whole number Wayland's buffer scale and regions need. Wayland and Android still set whole scales, so nothing changes there; the browser backend sets the page's `devicePixelRatio`, so the canvas holds the display's own pixels at any zoom. `App::on_scale_changed` keeps its `u32`, the scale rounded, and `App::on_resize` gives the exact physical size. The fallback-theme banner placed its text as if `draw_text` took the top of the line rather than its baseline, so most of the text fell above the banner, out of the surface; it is now centred as the title bar's is. Building. `make web-check` typechecks the backend. `make web-deps` installs Debian's std for wasm32 and wasm-bindgen-cli, whose version must be the one of the wasm-bindgen crate in `Cargo.lock`: the crate is pinned to 0.2.117, the last whose CLI builds with Debian's rustc 1.85, and since the lock the CLI was published with needs a newer rustc and `cargo install` ignores rust-version when it resolves, the CLI is built from its sources with a lock resolved for the rust-version it declares, into `target/tools`, where the Makefile finds it. `make web-assets` builds the resources with the in-tree default theme and the fallback fonts `WEB_FONTS` names. `examples/web_hello.rs`, a counter and a text field, and `web/index.html` are the smoke test: `make web-example` builds them into `target/web/` and `make web-serve` serves them. `make install` now copies `web/` into the registry. `README.md`, `docs/architecture.md` and `CHANGELOG.md` describe the backend, and `docs/cookbook.md` points to `ChannelSender`'s new home. Not done. In a browser there are no overlays, secondary surfaces or subsurfaces, no dead keys or input methods, no accessibility tree and no primary selection, and a canvas that changes size while the window does not is not refitted. Pasting relies on the browser sending `paste` to a focused canvas, which Chrome and Firefox do. The page fetches its whole resource tree, about 7 MB, before the app starts. There are no tests for the browser backend, `Sources`' queue or `vfs.rs`'s in-memory files, and fractional scales may leave one-pixel artefacts where edges fall between pixels.
141 lines
7.0 KiB
Rust
141 lines
7.0 KiB
Rust
// SPDX-License-Identifier: LGPL-2.1-only
|
||
// Copyright (C) 2026 Liberux Labs, S. L. <info@liberux.net>
|
||
|
||
//! Platform backends: what ties the runtime to a windowing system.
|
||
//!
|
||
//! The runtime (`event_loop/`, `input/`, `draw/`) holds the app, the widget tree, focus, gestures, text editing and every `App` callback, and is the same on every platform. A backend feeds it input through the entry points of [`crate::input::event`], keeps its own half of every surface in `SurfaceState::platform`, and carries out the requests of [`Platform`].
|
||
//!
|
||
//! A backend also owns the run loop: it connects to the system, builds `AppData` with `AppData::new`, installs the shared event sources with `AppData::install_sources`, and on every wake-up calls `AppData::before_draw`, `AppData::draw_due` and `AppData::after_draw` around its own work.
|
||
//!
|
||
//! The backends are `wayland`, `android` and `web`, each behind the feature of its name; `build.rs` refuses more than one. Each backend sets the two aliases below and `run` / `try_run` under its own `cfg`, and `build.rs` sets `cfg( backend )`, which builds the runtime, when one is enabled.
|
||
|
||
#[ cfg( feature = "android" ) ]
|
||
pub( crate ) mod android;
|
||
#[ cfg( feature = "wayland" ) ]
|
||
pub( crate ) mod wayland;
|
||
#[ cfg( feature = "web" ) ]
|
||
pub( crate ) mod web;
|
||
#[ cfg( test ) ]
|
||
pub( crate ) mod mock;
|
||
|
||
#[ cfg( feature = "android" ) ]
|
||
pub( crate ) use android::run::{ run, try_run };
|
||
#[ cfg( feature = "wayland" ) ]
|
||
pub( crate ) use wayland::run::{ run, try_run };
|
||
#[ cfg( feature = "web" ) ]
|
||
pub( crate ) use web::run::{ run, try_run };
|
||
|
||
use crate::event_loop::SurfaceFocus;
|
||
use crate::event_loop::cursor_shape::ResizeEdge;
|
||
use crate::osk::Purpose;
|
||
use crate::render::Canvas;
|
||
use crate::types::{ Color, CursorShape, Rect };
|
||
|
||
/// The backend the runtime runs on, held by `AppData::platform`.
|
||
#[ cfg( feature = "wayland" ) ]
|
||
pub( crate ) type NativePlatform<A> = wayland::WaylandPlatform<A>;
|
||
#[ cfg( feature = "android" ) ]
|
||
pub( crate ) type NativePlatform<A> = android::AndroidPlatform<A>;
|
||
#[ cfg( feature = "web" ) ]
|
||
pub( crate ) type NativePlatform<A> = web::WebPlatform<A>;
|
||
|
||
/// The backend's half of every surface, held by `SurfaceState::platform`.
|
||
#[ cfg( feature = "wayland" ) ]
|
||
pub( crate ) type NativeSurface = wayland::WaylandSurfaceState;
|
||
#[ cfg( feature = "android" ) ]
|
||
pub( crate ) type NativeSurface = android::AndroidSurfaceState;
|
||
#[ cfg( feature = "web" ) ]
|
||
pub( crate ) type NativeSurface = web::WebSurfaceState;
|
||
|
||
/// The user's language as `LANG` gives it (`es_ES.UTF-8`), or in a browser as the page does (`es-ES`).
|
||
#[ cfg( not( feature = "web" ) ) ]
|
||
pub( crate ) fn language() -> String
|
||
{
|
||
std::env::var( "LANG" ).unwrap_or_default()
|
||
}
|
||
|
||
#[ cfg( feature = "web" ) ]
|
||
pub( crate ) fn language() -> String
|
||
{
|
||
web_sys::window().and_then( |w| w.navigator().language() ).unwrap_or_default()
|
||
}
|
||
|
||
/// What [`Platform::present`] needs to know about a painted frame. Rects are in physical pixels, top-left origin.
|
||
pub( crate ) struct Presentation<'a>
|
||
{
|
||
/// What changed since the last frame; empty for the whole surface.
|
||
pub damage: &'a [Rect],
|
||
/// The surface is opaque where `bg` is, and elsewhere over `opaque_region`.
|
||
pub bg: Color,
|
||
pub opaque_region: Option<&'a [Rect]>,
|
||
/// Where the surface takes input; `None` everywhere, empty nowhere.
|
||
pub input_region: Option<&'a [Rect]>,
|
||
/// Logical size and the physical pixels per logical one.
|
||
pub width: u32,
|
||
pub height: u32,
|
||
pub scale: f32,
|
||
/// Report the next frame to the runtime as one of this surface; `None` for a surface that is not paced by frames.
|
||
pub frame: Option<SurfaceFocus>,
|
||
}
|
||
|
||
/// What the runtime asks of the windowing system. `AppData::platform` implements it.
|
||
///
|
||
/// Drawing a surface takes three calls: [`Self::prepare_canvas`], then the runtime paints the widget tree on the canvas, then [`Self::present`]. The canvas is the surface's own and keeps its pixels between frames, so a partial repaint only touches the damaged rects, and presenting adds no copy beyond the one into the system's buffer that a software canvas always needs.
|
||
pub( crate ) trait Platform: 'static
|
||
{
|
||
/// The backend's half of a surface, held by `SurfaceState::platform`.
|
||
type Surface;
|
||
|
||
/// A display that one of `AppData::secondaries` covers.
|
||
type Output;
|
||
|
||
/// Whether a full repaint of `surface` should report the rects that changed rather than the whole surface.
|
||
fn precise_damage( &self, surface: &Self::Surface ) -> bool;
|
||
|
||
/// Make `canvas` ready to paint `surface` at `pw × ph` physical pixels, creating it on the first frame; `false` when the surface cannot be drawn now.
|
||
fn prepare_canvas( &self, surface: &mut Self::Surface, canvas: &mut Option<Canvas>, pw: u32, ph: u32, scale: f32 ) -> bool;
|
||
|
||
/// Show what was painted on `canvas` since [`Self::prepare_canvas`]; `false` when nothing reached the screen.
|
||
fn present( &self, surface: &mut Self::Surface, canvas: &mut Canvas, frame: &Presentation<'_> ) -> bool;
|
||
|
||
/// Offer `text`, which the runtime also keeps in `AppData::clipboard`, to other applications as the clipboard.
|
||
fn publish_clipboard( &mut self, text: &str );
|
||
|
||
/// Offer `text`, which the runtime also keeps in `AppData::primary_selection`, to other applications as the selection the middle button pastes; no-op where there is none.
|
||
fn publish_primary_selection( &mut self, text: &str );
|
||
|
||
/// Whether `main` is an application window the user can move, resize and minimise, rather than a shell or lock surface.
|
||
fn is_toplevel( &self, main: &Self::Surface ) -> bool;
|
||
|
||
/// Whether back with nothing left to go back to may minimise or close `main`, as [`crate::app::BackAtRoot`] says: an application's window or activity, not a shell or lock surface.
|
||
fn back_leaves( &self, main: &Self::Surface ) -> bool;
|
||
|
||
/// Let the system move the window with the pointer whose left button was just pressed.
|
||
fn begin_window_move( &self, main: &Self::Surface );
|
||
|
||
/// Let the system resize the window from `edge` with the pointer whose left button was just pressed.
|
||
fn begin_window_resize( &self, main: &Self::Surface, edge: ResizeEdge );
|
||
|
||
fn minimize_window( &self, main: &Self::Surface );
|
||
|
||
/// `false` when `main` is not a window, so the runtime asks again later.
|
||
fn set_fullscreen( &self, main: &Self::Surface, fullscreen: bool ) -> bool;
|
||
|
||
/// Ask for a frame of `surface`, reported as one of `focus`, without presenting a new buffer; `false` while the surface does not exist yet.
|
||
fn request_frame( &self, surface: &Self::Surface, focus: SurfaceFocus ) -> bool;
|
||
|
||
/// `false` when the system lets the app set no cursor shape.
|
||
fn set_cursor_shape( &mut self, shape: CursorShape ) -> bool;
|
||
|
||
/// Whether the input method is serving a text field or the app.
|
||
fn text_input_active( &self ) -> bool;
|
||
|
||
/// Ask the input method for text, or renew the request so a keyboard the system folded comes back.
|
||
fn activate_text_input( &mut self, secure: bool, purpose: Purpose );
|
||
|
||
fn deactivate_text_input( &mut self );
|
||
|
||
/// Send an active request again with a new purpose; no-op when none is active.
|
||
fn reenable_text_input( &self, secure: bool, purpose: Purpose );
|
||
}
|