From 97cfdd4b0972b3a743c1cfb0f085800a446f6324 Mon Sep 17 00:00:00 2001 From: Mads Marquart Date: Fri, 23 Feb 2024 15:35:18 +0100 Subject: [PATCH] Move some of our documentation to docs.rs (#3478) * Move platform-specific documentation to `winit::platform` module * Document cargo features in crate docs * Move version requirements to crate-level docs --- Cargo.toml | 2 + FEATURES.md | 11 +--- README.md | 124 +---------------------------------- src/lib.rs | 17 +++++ src/platform/android.rs | 66 +++++++++++++++++++ src/platform/ios.rs | 66 +++++++++++++++++++ src/platform/macos.rs | 16 +++++ src/platform/orbital.rs | 5 ++ src/platform/wayland.rs | 15 +++++ src/platform/web.rs | 40 +++++++---- src/platform/windows.rs | 4 ++ src/platform/x11.rs | 1 + src/platform_impl/ios/mod.rs | 57 ---------------- 13 files changed, 223 insertions(+), 201 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index 3b8ea544..d6170f23 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -42,6 +42,7 @@ targets = [ ] rustdoc-args = ["--cfg", "docsrs"] +# Features are documented in either `lib.rs` or under `winit::platform`. [features] default = ["rwh_06", "x11", "wayland", "wayland-dlopen", "wayland-csd-adwaita"] x11 = ["x11-dl", "bytemuck", "percent-encoding", "xkbcommon-dl/x11", "x11rb"] @@ -53,6 +54,7 @@ wayland-csd-adwaita-notitle = ["sctk-adwaita"] android-native-activity = ["android-activity/native-activity"] android-game-activity = ["android-activity/game-activity"] serde = ["dep:serde", "cursor-icon/serde", "smol_str/serde"] +mint = ["dep:mint"] rwh_04 = ["dep:rwh_04", "ndk/rwh_04"] rwh_05 = ["dep:rwh_05", "ndk/rwh_05"] rwh_06 = ["dep:rwh_06", "ndk/rwh_06"] diff --git a/FEATURES.md b/FEATURES.md index 2819b48e..df813490 100644 --- a/FEATURES.md +++ b/FEATURES.md @@ -3,8 +3,8 @@ Winit aims to expose an interface that abstracts over window creation and input handling and can be used to create both games and applications. It supports the following main graphical platforms: - Desktop - - Windows 7+ (10+ is tested regularly) - - macOS 10.7+ (10.14+ is tested regularly) + - Windows + - macOS - Unix - via X11 - via Wayland @@ -13,9 +13,6 @@ be used to create both games and applications. It supports the following main gr - iOS - Android - Web - - Chrome - - Firefox - - Safari 13.1+ Most platforms expose capabilities that cannot be meaningfully transposed onto others. Winit does not aim to support every single feature of every platform, but rather to abstract over the common features @@ -151,7 +148,6 @@ If your PR makes notable changes to Winit's features, please update this section * Setting the X11 parent window ### iOS -* `winit` has a minimum OS requirement of iOS 8 * Get the `UIScreen` object pointer * Setting the `UIView` hidpi factor * Valid orientations @@ -164,9 +160,6 @@ If your PR makes notable changes to Winit's features, please update this section ### Web * Get if the systems preferred color scheme is "dark" -## Usability -* `serde`: Enables serialization/deserialization of certain types with Serde. (Maintainer: @Osspial) - ## Compatibility Matrix Legend: diff --git a/README.md b/README.md index 79203cf7..7a7a2cb3 100644 --- a/README.md +++ b/README.md @@ -33,14 +33,6 @@ Winit is designed to be a low-level brick in a hierarchy of libraries. Consequen show something on the window you need to use the platform-specific getters provided by winit, or another library. -### Cargo Features - -Winit provides the following features, which can be enabled in your `Cargo.toml` file: -* `serde`: Enables serialization/deserialization of certain types with [Serde](https://crates.io/crates/serde). -* `x11` (enabled by default): On Unix platform, compiles with the X11 backend -* `wayland` (enabled by default): On Unix platform, compiles with the Wayland backend -* `mint`: Enables mint (math interoperability standard types) conversions. - ## MSRV Policy This crate's Minimum Supported Rust Version (MSRV) is **1.70**. Changes to @@ -71,118 +63,4 @@ same MSRV policy. ### Platform-specific usage -#### Wayland - -Note that windows don't appear on Wayland until you draw/present to them. - -#### Web - -To run the web example: `cargo run-wasm --example web` - -Winit supports compiling to the `wasm32-unknown-unknown` target with `web-sys`. - -On the web platform, a Winit window is backed by a `` element. You can -either [provide Winit with a `` element][web with_canvas], or [let Winit -create a `` element which you can then retrieve][web canvas getter] and -insert it into the DOM yourself. - -For the example code using Winit on Web, check out the [web example]. For -information on using Rust on WebAssembly, check out the [Rust and WebAssembly -book]. - -[web with_canvas]: https://docs.rs/winit/latest/wasm32-unknown-unknown/winit/platform/web/trait.WindowBuilderExtWebSys.html#tymethod.with_canvas -[web canvas getter]: https://docs.rs/winit/latest/wasm32-unknown-unknown/winit/platform/web/trait.WindowExtWebSys.html#tymethod.canvas -[web example]: ./examples/web.rs -[Rust and WebAssembly book]: https://rustwasm.github.io/book/ - -#### Android - -The Android backend builds on (and exposes types from) the [`ndk`](https://docs.rs/ndk/latest/ndk/) crate. - -Native Android applications need some form of "glue" crate that is responsible -for defining the main entry point for your Rust application as well as tracking -various life-cycle events and synchronizing with the main JVM thread. - -Winit uses the [android-activity](https://github.com/rib/android-activity) as a -glue crate (prior to `0.28` it used -[ndk-glue](https://github.com/rust-windowing/android-ndk-rs/tree/master/ndk-glue)). - -The version of the glue crate that your application depends on _must_ match the -version that Winit depends on because the glue crate is responsible for your -application's main entry point. If Cargo resolves multiple versions, they will -clash. - -`winit` glue compatibility table: - -| winit | ndk-glue | -| :---: | :--------------------------: | -| 0.29 | `android-activity = "0.5"` | -| 0.28 | `android-activity = "0.4"` | -| 0.27 | `ndk-glue = "0.7"` | -| 0.26 | `ndk-glue = "0.5"` | -| 0.25 | `ndk-glue = "0.3"` | -| 0.24 | `ndk-glue = "0.2"` | - -The recommended way to avoid a conflict with the glue version is to avoid explicitly -depending on the `android-activity` crate, and instead consume the API that -is re-exported by Winit under `winit::platform::android::activity::*` - -Running on an Android device needs a dynamic system library. Add this to Cargo.toml: - -```toml -[lib] -name = "main" -crate-type = ["cdylib"] -``` - -All Android applications are based on an `Activity` subclass, and the -`android-activity` crate is designed to support different choices for this base -class. Your application _must_ specify the base class it needs via a feature flag: - -| Base Class | Feature Flag | Notes | -| :--------------: | :---------------: | :-----: | -| `NativeActivity` | `android-native-activity` | Built-in to Android - it is possible to use without compiling any Java or Kotlin code. Java or Kotlin code may be needed to subclass `NativeActivity` to access some platform features. It does not derive from the [`AndroidAppCompat`] base class.| -| [`GameActivity`] | `android-game-activity` | Derives from [`AndroidAppCompat`], a defacto standard `Activity` base class that helps support a wider range of Android versions. Requires a build system that can compile Java or Kotlin and fetch Android dependencies from a [Maven repository][agdk_jetpack] (or link with an embedded [release][agdk_releases] of [`GameActivity`]) | - -[`GameActivity`]: https://developer.android.com/games/agdk/game-activity -[`GameTextInput`]: https://developer.android.com/games/agdk/add-support-for-text-input -[`AndroidAppCompat`]: https://developer.android.com/reference/androidx/appcompat/app/AppCompatActivity -[agdk_jetpack]: https://developer.android.com/jetpack/androidx/releases/games -[agdk_releases]: https://developer.android.com/games/agdk/download#agdk-libraries -[Gradle]: https://developer.android.com/studio/build - -For more details, refer to these `android-activity` [example applications](https://github.com/rust-mobile/android-activity/tree/main/examples). - -##### Converting from `ndk-glue` to `android-activity` - -If your application is currently based on `NativeActivity` via the `ndk-glue` crate and building with `cargo apk`, then the minimal changes would be: -1. Remove `ndk-glue` from your `Cargo.toml` -2. Enable the `"android-native-activity"` feature for Winit: `winit = { version = "0.29.10", features = [ "android-native-activity" ] }` -3. Add an `android_main` entrypoint (as above), instead of using the '`[ndk_glue::main]` proc macro from `ndk-macros` (optionally add a dependency on `android_logger` and initialize logging as above). -4. Pass a clone of the `AndroidApp` that your application receives to Winit when building your event loop (as shown above). - -#### MacOS - -A lot of functionality expects the application to be ready before you start -doing anything; this includes creating windows, fetching monitors, drawing, -and so on, see issues [#2238], [#2051] and [#2087]. - -If you encounter problems, you should try doing your initialization inside -`Event::Resumed`. - -#### iOS - -Similar to macOS, iOS's main `UIApplicationMain` does some init work that's required -by all UI-related code (see issue [#1705]). It would be best to consider creating your windows -inside `Event::Resumed`. - - -[#2238]: https://github.com/rust-windowing/winit/issues/2238 -[#2051]: https://github.com/rust-windowing/winit/issues/2051 -[#2087]: https://github.com/rust-windowing/winit/issues/2087 -[#1705]: https://github.com/rust-windowing/winit/issues/1705 - -#### Redox OS - -Redox OS has some functionality not yet present that will be implemented when -its orbital display server provides it. +Check out the [`winit::platform`](https://rust-windowing.github.io/winit/winit/platform/index.html) module for platform-specific usage. diff --git a/src/lib.rs b/src/lib.rs index fcf3de7c..dda10d2c 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -126,6 +126,23 @@ //! [`visible` set to `false`](crate::window::WindowAttributes::with_visible) and explicitly make the //! window visible only once you're ready to render into it. //! +//! # Cargo Features +//! +//! Winit provides the following Cargo features: +//! +//! * `x11` (enabled by default): On Unix platforms, enables the X11 backend. +//! * `wayland` (enabled by default): On Unix platforms, enables the Wayland +//! backend. +//! * `rwh_04`: Implement `raw-window-handle v0.4` traits. +//! * `rwh_05`: Implement `raw-window-handle v0.5` traits. +//! * `rwh_06`: Implement `raw-window-handle v0.6` traits. +//! * `serde`: Enables serialization/deserialization of certain types with +//! [Serde](https://crates.io/crates/serde). +//! * `mint`: Enables mint (math interoperability standard types) conversions. +//! +//! See the [`platform`] module for documentation on platform-specific cargo +//! features. +//! //! [`EventLoop`]: event_loop::EventLoop //! [`EventLoop::new()`]: event_loop::EventLoop::new //! [`EventLoop::run()`]: event_loop::EventLoop::run diff --git a/src/platform/android.rs b/src/platform/android.rs index e7f6697d..38cfd435 100644 --- a/src/platform/android.rs +++ b/src/platform/android.rs @@ -1,3 +1,69 @@ +//! # Android +//! +//! The Android backend builds on (and exposes types from) the [`ndk`](https://docs.rs/ndk/) crate. +//! +//! Native Android applications need some form of "glue" crate that is responsible +//! for defining the main entry point for your Rust application as well as tracking +//! various life-cycle events and synchronizing with the main JVM thread. +//! +//! Winit uses the [android-activity](https://docs.rs/android-activity/) as a +//! glue crate (prior to `0.28` it used +//! [ndk-glue](https://github.com/rust-windowing/android-ndk-rs/tree/master/ndk-glue)). +//! +//! The version of the glue crate that your application depends on _must_ match the +//! version that Winit depends on because the glue crate is responsible for your +//! application's main entry point. If Cargo resolves multiple versions, they will +//! clash. +//! +//! `winit` glue compatibility table: +//! +//! | winit | ndk-glue | +//! | :---: | :--------------------------: | +//! | 0.29 | `android-activity = "0.5"` | +//! | 0.28 | `android-activity = "0.4"` | +//! | 0.27 | `ndk-glue = "0.7"` | +//! | 0.26 | `ndk-glue = "0.5"` | +//! | 0.25 | `ndk-glue = "0.3"` | +//! | 0.24 | `ndk-glue = "0.2"` | +//! +//! The recommended way to avoid a conflict with the glue version is to avoid explicitly +//! depending on the `android-activity` crate, and instead consume the API that +//! is re-exported by Winit under `winit::platform::android::activity::*` +//! +//! Running on an Android device needs a dynamic system library. Add this to Cargo.toml: +//! +//! ```toml +//! [lib] +//! name = "main" +//! crate-type = ["cdylib"] +//! ``` +//! +//! All Android applications are based on an `Activity` subclass, and the +//! `android-activity` crate is designed to support different choices for this base +//! class. Your application _must_ specify the base class it needs via a feature flag: +//! +//! | Base Class | Feature Flag | Notes | +//! | :--------------: | :---------------: | :-----: | +//! | `NativeActivity` | `android-native-activity` | Built-in to Android - it is possible to use without compiling any Java or Kotlin code. Java or Kotlin code may be needed to subclass `NativeActivity` to access some platform features. It does not derive from the [`AndroidAppCompat`] base class.| +//! | [`GameActivity`] | `android-game-activity` | Derives from [`AndroidAppCompat`], a defacto standard `Activity` base class that helps support a wider range of Android versions. Requires a build system that can compile Java or Kotlin and fetch Android dependencies from a [Maven repository][agdk_jetpack] (or link with an embedded [release][agdk_releases] of [`GameActivity`]) | +//! +//! [`GameActivity`]: https://developer.android.com/games/agdk/game-activity +//! [`GameTextInput`]: https://developer.android.com/games/agdk/add-support-for-text-input +//! [`AndroidAppCompat`]: https://developer.android.com/reference/androidx/appcompat/app/AppCompatActivity +//! [agdk_jetpack]: https://developer.android.com/jetpack/androidx/releases/games +//! [agdk_releases]: https://developer.android.com/games/agdk/download#agdk-libraries +//! [Gradle]: https://developer.android.com/studio/build +//! +//! For more details, refer to these `android-activity` [example applications](https://github.com/rust-mobile/android-activity/tree/main/examples). +//! +//! ## Converting from `ndk-glue` to `android-activity` +//! +//! If your application is currently based on `NativeActivity` via the `ndk-glue` crate and building with `cargo apk`, then the minimal changes would be: +//! 1. Remove `ndk-glue` from your `Cargo.toml` +//! 2. Enable the `"android-native-activity"` feature for Winit: `winit = { version = "0.29.10", features = [ "android-native-activity" ] }` +//! 3. Add an `android_main` entrypoint (as above), instead of using the '`[ndk_glue::main]` proc macro from `ndk-macros` (optionally add a dependency on `android_logger` and initialize logging as above). +//! 4. Pass a clone of the `AndroidApp` that your application receives to Winit when building your event loop (as shown above). + use crate::{ event_loop::{ActiveEventLoop, EventLoop, EventLoopBuilder}, window::{Window, WindowAttributes}, diff --git a/src/platform/ios.rs b/src/platform/ios.rs index 3494cfa7..2d01628c 100644 --- a/src/platform/ios.rs +++ b/src/platform/ios.rs @@ -1,3 +1,69 @@ +//! # iOS / UIKit +//! +//! Winit has an OS requirement of iOS 8 or higher, and is regularly tested on +//! iOS 9.3. +//! +//! iOS's main `UIApplicationMain` does some init work that's required by all +//! UI-related code (see issue [#1705]). It is best to create your windows +//! inside `Event::Resumed`. +//! +//! [#1705]: https://github.com/rust-windowing/winit/issues/1705 +//! +//! ## Building app +//! +//! To build ios app you will need rustc built for this targets: +//! +//! - armv7-apple-ios +//! - armv7s-apple-ios +//! - i386-apple-ios +//! - aarch64-apple-ios +//! - x86_64-apple-ios +//! +//! Then +//! +//! ``` +//! cargo build --target=... +//! ``` +//! The simplest way to integrate your app into xcode environment is to build it +//! as a static library. Wrap your main function and export it. +//! +//! ```rust, ignore +//! #[no_mangle] +//! pub extern fn start_winit_app() { +//! start_inner() +//! } +//! +//! fn start_inner() { +//! ... +//! } +//! ``` +//! +//! Compile project and then drag resulting .a into Xcode project. Add winit.h to xcode. +//! +//! ```ignore +//! void start_winit_app(); +//! ``` +//! +//! Use start_winit_app inside your xcode's main function. +//! +//! +//! ## App lifecycle and events +//! +//! iOS environment is very different from other platforms and you must be very +//! careful with it's events. Familiarize yourself with +//! [app lifecycle](https://developer.apple.com/library/ios/documentation/UIKit/Reference/UIApplicationDelegate_Protocol/). +//! +//! This is how those event are represented in winit: +//! +//! - applicationDidBecomeActive is Resumed +//! - applicationWillResignActive is Suspended +//! - applicationWillTerminate is LoopExiting +//! +//! Keep in mind that after LoopExiting event is received every attempt to draw with +//! opengl will result in segfault. +//! +//! Also note that app may not receive the LoopExiting event if suspended; it might be SIGKILL'ed. + use std::os::raw::c_void; use crate::{ diff --git a/src/platform/macos.rs b/src/platform/macos.rs index 864cc1bb..4d74c94d 100644 --- a/src/platform/macos.rs +++ b/src/platform/macos.rs @@ -1,3 +1,19 @@ +//! # macOS / AppKit +//! +//! Winit has an OS requirement of macOS 10.11 or higher (same as Rust +//! itself), and is regularly tested on macOS 10.14. +//! +//! A lot of functionality expects the application to be ready before you +//! start doing anything; this includes creating windows, fetching monitors, +//! drawing, and so on, see issues [#2238], [#2051] and [#2087]. +//! +//! If you encounter problems, you should try doing your initialization inside +//! `Event::Resumed`. +//! +//! [#2238]: https://github.com/rust-windowing/winit/issues/2238 +//! [#2051]: https://github.com/rust-windowing/winit/issues/2051 +//! [#2087]: https://github.com/rust-windowing/winit/issues/2087 + use std::os::raw::c_void; #[cfg(feature = "serde")] diff --git a/src/platform/orbital.rs b/src/platform/orbital.rs index 7491c2e6..d8093503 100644 --- a/src/platform/orbital.rs +++ b/src/platform/orbital.rs @@ -1 +1,6 @@ +//! # Orbital / Redox OS +//! +//! Redox OS has some functionality not yet present that will be implemented +//! when its orbital display server provides it. + // There are no Orbital specific traits yet. diff --git a/src/platform/wayland.rs b/src/platform/wayland.rs index 48d63795..24301ee0 100644 --- a/src/platform/wayland.rs +++ b/src/platform/wayland.rs @@ -1,3 +1,18 @@ +//! # Wayland +//! +//! **Note:** Windows don't appear on Wayland until you draw/present to them. +//! +//! By default, Winit loads system libraries using `dlopen`. This can be +//! disabled by disabling the `"wayland-dlopen"` cargo feature. +//! +//! ## Client-side decorations +//! +//! Winit provides client-side decorations by default, but the behaviour can +//! be controlled with the following feature flags: +//! +//! * `wayland-csd-adwaita` (default). +//! * `wayland-csd-adwaita-crossfont`. +//! * `wayland-csd-adwaita-notitle`. use crate::{ event_loop::{ActiveEventLoop, EventLoopBuilder}, monitor::MonitorHandle, diff --git a/src/platform/web.rs b/src/platform/web.rs index ed8071f9..fd498270 100644 --- a/src/platform/web.rs +++ b/src/platform/web.rs @@ -1,12 +1,31 @@ -//! The web target does not automatically insert the canvas element object into the web page, to -//! allow end users to determine how the page should be laid out. Use the [`WindowExtWebSys`] trait -//! to retrieve the canvas from the Window. Alternatively, use the [`WindowAttributesExtWebSys`] trait -//! to provide your own canvas. +//! # Web +//! +//! The officially supported browsers are Chrome, Firefox and Safari 13.1+, +//! though forks of these should work fine. +//! +//! Winit supports compiling to the `wasm32-unknown-unknown` target with +//! `web-sys`. +//! +//! On the web platform, a Winit window is backed by a `` element. You +//! can either [provide Winit with a `` element][with_canvas], or +//! [let Winit create a `` element which you can then retrieve][get] +//! and insert it into the DOM yourself. +//! +//! Currently, there is no example code using Winit on Web, see [#3473]. For +//! information on using Rust on WebAssembly, check out the [Rust and +//! WebAssembly book]. +//! +//! [with_canvas]: WindowAttributesExtWebSys::with_canvas +//! [get]: WindowExtWebSys::canvas +//! [#3473]: https://github.com/rust-windowing/winit/issues/3473 +//! [Rust and WebAssembly book]: https://rustwasm.github.io/book/ +//! +//! ## CSS properties //! //! It is recommended **not** to apply certain CSS properties to the canvas: -//! - [`transform`] -//! - [`border`] -//! - [`padding`] +//! - [`transform`](https://developer.mozilla.org/en-US/docs/Web/CSS/transform) +//! - [`border`](https://developer.mozilla.org/en-US/docs/Web/CSS/border) +//! - [`padding`](https://developer.mozilla.org/en-US/docs/Web/CSS/padding) //! //! The following APIs can't take them into account and will therefore provide inaccurate results: //! - [`WindowEvent::Resized`] and [`Window::(set_)inner_size()`] @@ -16,16 +35,13 @@ //! - [`Window::set_outer_position()`] //! //! [`WindowEvent::Resized`]: crate::event::WindowEvent::Resized -//! [`Window::(set_)inner_size()`]: crate::window::Window::inner_size() +//! [`Window::(set_)inner_size()`]: crate::window::Window::inner_size //! [`WindowEvent::Occluded`]: crate::event::WindowEvent::Occluded //! [`WindowEvent::CursorMoved`]: crate::event::WindowEvent::CursorMoved //! [`WindowEvent::CursorEntered`]: crate::event::WindowEvent::CursorEntered //! [`WindowEvent::CursorLeft`]: crate::event::WindowEvent::CursorLeft //! [`WindowEvent::Touch`]: crate::event::WindowEvent::Touch -//! [`Window::set_outer_position()`]: crate::window::Window::set_outer_position() -//! [`transform`]: https://developer.mozilla.org/en-US/docs/Web/CSS/transform -//! [`border`]: https://developer.mozilla.org/en-US/docs/Web/CSS/border -//! [`padding`]: https://developer.mozilla.org/en-US/docs/Web/CSS/padding +//! [`Window::set_outer_position()`]: crate::window::Window::set_outer_position use std::error::Error; use std::fmt::{self, Display, Formatter}; diff --git a/src/platform/windows.rs b/src/platform/windows.rs index 456d064e..39e4ee01 100644 --- a/src/platform/windows.rs +++ b/src/platform/windows.rs @@ -1,3 +1,7 @@ +//! # Windows +//! +//! The supported OS version is Windows 7 or higher, though Windows 10 is +//! tested regularly. use std::{ffi::c_void, path::Path}; use crate::{ diff --git a/src/platform/x11.rs b/src/platform/x11.rs index 1e8b1080..afeb12c2 100644 --- a/src/platform/x11.rs +++ b/src/platform/x11.rs @@ -1,3 +1,4 @@ +//! # X11 #[cfg(feature = "serde")] use serde::{Deserialize, Serialize}; diff --git a/src/platform_impl/ios/mod.rs b/src/platform_impl/ios/mod.rs index 496ad359..84edcdba 100644 --- a/src/platform_impl/ios/mod.rs +++ b/src/platform_impl/ios/mod.rs @@ -1,60 +1,3 @@ -//! iOS support -//! -//! # Building app -//! To build ios app you will need rustc built for this targets: -//! -//! - armv7-apple-ios -//! - armv7s-apple-ios -//! - i386-apple-ios -//! - aarch64-apple-ios -//! - x86_64-apple-ios -//! -//! Then -//! -//! ``` -//! cargo build --target=... -//! ``` -//! The simplest way to integrate your app into xcode environment is to build it -//! as a static library. Wrap your main function and export it. -//! -//! ```rust, ignore -//! #[no_mangle] -//! pub extern fn start_winit_app() { -//! start_inner() -//! } -//! -//! fn start_inner() { -//! ... -//! } -//! ``` -//! -//! Compile project and then drag resulting .a into Xcode project. Add winit.h to xcode. -//! -//! ```ignore -//! void start_winit_app(); -//! ``` -//! -//! Use start_winit_app inside your xcode's main function. -//! -//! -//! # App lifecycle and events -//! -//! iOS environment is very different from other platforms and you must be very -//! careful with it's events. Familiarize yourself with -//! [app lifecycle](https://developer.apple.com/library/ios/documentation/UIKit/Reference/UIApplicationDelegate_Protocol/). -//! -//! -//! This is how those event are represented in winit: -//! -//! - applicationDidBecomeActive is Resumed -//! - applicationWillResignActive is Suspended -//! - applicationWillTerminate is LoopExiting -//! -//! Keep in mind that after LoopExiting event is received every attempt to draw with -//! opengl will result in segfault. -//! -//! Also note that app may not receive the LoopExiting event if suspended; it might be SIGKILL'ed. - #![cfg(ios_platform)] #![allow(clippy::let_unit_value)]