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}