Skip to main content

damascene_ios/
lib.rs

1//! Native iOS host shell for Damascene wgpu apps.
2//!
3//! Verified on the iOS simulator (August 2026): the showcase builds
4//! through the Xcode project, renders full-screen at the right scale
5//! with safe-area insets honored, and touch, drags, animation,
6//! rotation, soft-keyboard text input (the keyboard lifts the focused
7//! field above itself), plots, and shader animations all work, and the
8//! accessibility tree reaches UIKit; a physical iPhone confirmed basic
9//! functionality. Known gaps: clipboard and link opening are not yet
10//! wired on iOS.
11//! `ios/README.md` has the run sequence and the full status list.
12//!
13//! iOS apps are packaged by Xcode. Downstream crates usually build a
14//! Rust `staticlib` with an exported C ABI function, then call that
15//! function from the app's Objective-C or Swift entry point. This crate
16//! keeps the Rust side aligned with the desktop and Android host APIs:
17//! application code owns `App`, while `damascene-winit-wgpu` owns the
18//! window, event loop, surface, device/queue, and input translation.
19
20use damascene_core::{App, Rect};
21pub use damascene_winit_wgpu::HostConfig;
22
23/// Minimal `log` backend writing to stderr.
24///
25/// On iOS, stderr is captured by Xcode's console (debugger attached)
26/// and by `xcrun simctl launch --console-pty`; a detached launch
27/// (tapping the app icon) discards it. Unified-logging (`os_log`)
28/// integration would cover detached launches too, but the existing
29/// binding crates compile a C shim against Apple SDK headers, which
30/// breaks this crate's Linux CI cross-check — revisit if detached
31/// logging becomes necessary.
32#[cfg(target_os = "ios")]
33struct StderrLogger;
34
35#[cfg(target_os = "ios")]
36impl log::Log for StderrLogger {
37    fn enabled(&self, metadata: &log::Metadata<'_>) -> bool {
38        metadata.level() <= log::Level::Info
39    }
40
41    fn log(&self, record: &log::Record<'_>) {
42        if self.enabled(record.metadata()) {
43            eprintln!(
44                "damascene [{} {}] {}",
45                record.level(),
46                record.target(),
47                record.args()
48            );
49        }
50    }
51
52    fn flush(&self) {}
53}
54
55/// Run an Damascene app in iOS's UIKit/winit event loop.
56///
57/// This is the iOS equivalent of `damascene_winit_wgpu::run`: app code
58/// owns state/build/events; the host owns the platform event loop,
59/// surface, device/queue, and input translation.
60#[cfg(target_os = "ios")]
61pub fn run<A: App + 'static>(
62    title: &'static str,
63    viewport: Rect,
64    app: A,
65) -> Result<(), Box<dyn std::error::Error>> {
66    run_with_config(title, viewport, app, HostConfig::default())
67}
68
69/// Run an Damascene app on iOS with explicit host configuration.
70///
71/// Routes the `log` facade to stderr at `Info` level before starting —
72/// the host reports GPU-setup failures (e.g. surface configuration
73/// errors behind a black first frame) through `log`, and without a
74/// backend those reports die invisibly. Apps that want their own
75/// logger can install it before calling this; an already-installed
76/// logger wins.
77#[cfg(target_os = "ios")]
78pub fn run_with_config<A: App + 'static>(
79    title: &'static str,
80    viewport: Rect,
81    app: A,
82    config: HostConfig,
83) -> Result<(), Box<dyn std::error::Error>> {
84    static LOGGER: StderrLogger = StderrLogger;
85    if log::set_logger(&LOGGER).is_ok() {
86        log::set_max_level(log::LevelFilter::Info);
87    }
88
89    damascene_winit_wgpu::run_with_config(title, viewport, app, config)
90}
91
92/// Non-iOS builds can type-check crates that depend on `damascene-ios`, but
93/// cannot start a UIKit application.
94#[cfg(not(target_os = "ios"))]
95pub fn run<A: App + 'static>(
96    _title: &'static str,
97    _viewport: Rect,
98    _app: A,
99) -> Result<(), Box<dyn std::error::Error>> {
100    Err("damascene-ios can only run on target_os = \"ios\"".into())
101}
102
103/// Non-iOS builds can type-check crates that depend on `damascene-ios`, but
104/// cannot start a UIKit application.
105#[cfg(not(target_os = "ios"))]
106pub fn run_with_config<A: App + 'static>(
107    _title: &'static str,
108    _viewport: Rect,
109    _app: A,
110    _config: HostConfig,
111) -> Result<(), Box<dyn std::error::Error>> {
112    Err("damascene-ios can only run on target_os = \"ios\"".into())
113}