cotis_wgpu/lib.rs
1//! wgpu-backed desktop renderer for the [Cotis](https://crates.io/crates/cotis) UI ecosystem.
2//!
3//! `cotis-wgpu` implements Cotis's [`cotis::renders::CotisRenderer`] and
4//! [`cotis::renders::CotisRendererAsync`] traits on top of [wgpu](https://crates.io/crates/wgpu) 24,
5//! [winit](https://crates.io/crates/winit) 0.30, and [glyphon](https://crates.io/crates/glyphon) 0.8.
6//! It is a drop-in alternative to other Cotis render backends such as `cotis-raylib`.
7//!
8//! # Quick start
9//!
10//! For interactive applications, create a [`CotisWgpuRenderer`] and wire it into
11//! [`CotisApp`](cotis::cotis_app::CotisApp) (from `cotis::cotis_app`) with a layout manager and pipe:
12//!
13//! ```rust,ignore
14//! use cotis::cotis_app::{CotisApp, RenderApp};
15//! use cotis_layout::preamble::CotisLayoutManager;
16//! use cotis_pipes::cotis_layout_pipes::CotisLayoutToRenderListPipeForGenerics;
17//! use cotis_utils::math::Dimensions;
18//! use cotis_wgpu::prelude::*;
19//!
20//! let renderer = CotisWgpuRenderer::auto_start();
21//! let manager = CotisLayoutManager::new(Dimensions::new(1000.0, 800.0));
22//! let mut app = CotisApp::new(renderer, manager, CotisLayoutToRenderListPipeForGenerics);
23//!
24//! while !app.render().window_should_close() {
25//! RenderApp::compute_frame(&mut app, |root| {
26//! // build UI on root
27//! });
28//! }
29//! ```
30//!
31//! For the full wiring pattern including a `StandardRenderCmds` type alias, see
32//! `examples/basic_example/support.rs` in this crate's source tree.
33//!
34//! Run the shipped example from the workspace root:
35//!
36//! ```text
37//! cargo run --example basic_example -p cotis-wgpu
38//! ```
39//!
40//! # Recommended imports
41//!
42//! Use [`prelude`] for the common entry-point types:
43//!
44//! ```rust,no_run
45//! use cotis_wgpu::prelude::*;
46//! ```
47//!
48//! # Rendering model
49//!
50//! [`CotisWgpuRenderer`] draws three kinds of command streams:
51//!
52//! - [`cotis_defaults::render_commands::render_t_list::RenderTList`] with a nested list type —
53//! typed heterogeneous command lists produced by layout pipes (primary path with `cotis-pipes`).
54//! - [`cotis_defaults::render_commands::render_t_list::RenderTList`] with `()` as the list tail —
55//! single-command lists.
56//! - [`Box<dyn drawable::WgpuDrawable>`] — type-erased custom commands; implement
57//! [`drawable::WgpuDrawable`] for types not covered by `cotis-defaults` commands.
58//!
59//! Each [`cotis::renders::CotisRenderer::draw_frame`] call pumps the winit event loop before presenting.
60//! [`CotisWgpuRenderer::window_should_close`] also pumps events, so the typical app loop calls
61//! `app.render()` (which invokes `draw_frame`) and then checks `window_should_close()`.
62//!
63//! Built-in drawing for standard `cotis-defaults` commands lives in [`default_drawables`].
64//! Custom commands can use the advanced [`pipeline`], [`surface`], and [`text`] modules directly.
65//!
66//! # Cotis trait implementations
67//!
68//! [`CotisWgpuRenderer`] also implements Cotis context and interactivity traits.
69//! See [`cotis_traits`] for the full list, including:
70//!
71//! - [`cotis_utils::traits::CotisWindowContext`] — physical window dimensions in pixels.
72//! - [`cotis_utils::traits::CotisFrameContext`] — frame delta time.
73//! - [`cotis_utils::traits::CotisRenderContext`] — render marker trait.
74//! - [`cotis_utils::text::RendererTextMeasuringProvider`] — glyphon text measurement.
75//! - [`cotis_utils::interactivity::mouse::MouseProvider`] and keyboard providers via [`input`].
76//!
77//! # Features
78//!
79//! | Feature | Effect |
80//! |---------|--------|
81//! | `complex-color` | Enables `cotis-defaults/complex_color` and `complex_colored_text`. Accepts `ColorLayer` types but **does not render gradients** — see [`default_drawables`]. |
82//!
83//! # Known limitations
84//!
85//! - **Fonts:** All text uses glyphon `Family::SansSerif`. `TextConfig::font_id` is ignored; there is
86//! no font-loading API.
87//! - **Images:** [`cotis_defaults::render_commands::Image`] commands render as colored rectangles;
88//! texture loading is not implemented.
89//! - **Geometry alpha:** The UI shader outputs opaque fragments; cotis color alpha is ignored for
90//! rectangles and borders (text alpha is preserved via glyphon).
91//! - **Async renderer:** [`cotis::renders::CotisRendererAsync`] delegates synchronously to
92//! [`cotis::renders::CotisRenderer`]; there is no async GPU work.
93//! - **Frame errors:** Present failures log a warning and skip the frame; the application continues.
94//!
95//! # Public modules
96//!
97//! | Module | Role |
98//! |--------|------|
99//! | [`prelude`] | Application entry-point re-exports |
100//! | [`renderer`] | [`CotisWgpuRenderer`], [`WindowConfig`], event loop |
101//! | [`error`] | [`WgpuBackendError`] |
102//! | [`drawable`] | [`drawable::WgpuDrawable`] extension trait |
103//! | [`default_drawables`] | Built-in `WgpuDrawable` impls for `cotis-defaults` commands |
104//! | [`cotis_traits`] | Cotis context/interactivity trait impls |
105//! | [`color`] | Cotis `Color` → wgpu conversions |
106//! | [`input`] | winit input snapshot |
107//! | [`pipeline`] | Advanced: UI geometry batch and WGSL pipeline |
108//! | [`surface`] | Advanced: swapchain and depth buffer |
109//! | [`text`] | Advanced: glyphon text batching |
110
111pub mod color;
112pub mod cotis_traits;
113pub mod default_drawables;
114pub mod drawable;
115pub mod error;
116pub mod input;
117pub mod pipeline;
118pub mod renderer;
119pub mod surface;
120pub mod text;
121
122mod device;
123
124pub use error::WgpuBackendError;
125pub use renderer::{CotisWgpuRenderer, WindowConfig};
126
127/// Convenient re-exports for application code.
128///
129/// Typical import:
130///
131/// ```rust,no_run
132/// use cotis_wgpu::prelude::*;
133/// ```
134pub mod prelude {
135 pub use crate::error::WgpuBackendError;
136 pub use crate::renderer::{CotisWgpuRenderer, WindowConfig};
137}