cotis_pipes/lib.rs
1//! Layout-to-renderer pipe for [Cotis](https://crates.io/crates/cotis).
2//!
3//! `cotis-pipes` implements [`cotis::pipes::LayoutRenderPipe`] — the conversion layer between
4//! [`cotis-layout`](https://crates.io/crates/cotis-layout) output and
5//! [`cotis-defaults`](https://crates.io/crates/cotis-defaults) render commands. Each frame,
6//! layout produces a stream of [`RenderCommandOutput`](cotis_layout::layout_struct::RenderCommandOutput)
7//! values; this crate decodes them into a caller-chosen [`RenderTList`](cotis_defaults::render_commands::render_t_list::RenderTList)
8//! command stream for the renderer.
9//!
10//! # Frame pipeline
11//!
12//! ```text
13//! cotis-layout → cotis-pipes → renderer
14//! RenderCommandOutput RenderTList<…> CotisRenderer::draw
15//! ```
16//!
17//! 1. [`CotisLayoutManager`](cotis_layout::preamble::CotisLayoutManager) runs layout and yields
18//! [`RenderCommandOutput`](cotis_layout::layout_struct::RenderCommandOutput) per frame.
19//! 2. [`CotisLayoutToRenderListPipeForGenerics`](cotis_layout_pipes::CotisLayoutToRenderListPipeForGenerics)
20//! walks your `RenderTList` type and emits draw commands (`Rectangle`, `Text`, `Border`,
21//! `Image`, `ClipStart`, `ClipEnd`, plus any custom types you register).
22//! 3. The renderer consumes the flattened `RenderTList` stream.
23//!
24//! When layout output already matches what the renderer expects, pass [`()`] as the identity
25//! [`LayoutRenderPipe`](cotis::pipes::LayoutRenderPipe) instead (see
26//! [`CotisApp::new`](cotis::cotis_app::CotisApp::new)).
27//!
28//! # Quick start
29//!
30//! Define a [`RenderTList`](cotis_defaults::render_commands::render_t_list::RenderTList) type
31//! alias for your command stream, then wire the pipe into [`CotisApp`](cotis::cotis_app::CotisApp):
32//!
33//! ```rust,ignore
34//! use cotis::cotis_app::CotisApp;
35//! use cotis_layout::preamble::CotisLayoutManager;
36//! use cotis_pipes::cotis_layout_pipes::CotisLayoutToRenderListPipeForGenerics;
37//! use cotis_defaults::render_commands::render_t_list::RenderTList;
38//! use cotis_defaults::render_commands::{ClipStart, ClipEnd, Rectangle, Border, Text};
39//! use cotis_utils::math::Dimensions;
40//!
41//! type StandardRenderCmds = RenderTList<
42//! ClipStart<'static, ()>,
43//! RenderTList<
44//! ClipEnd,
45//! RenderTList<
46//! Rectangle<'static, ()>,
47//! RenderTList<Border<'static, ()>, RenderTList<Text<'static, ()>, ()>>,
48//! >,
49//! >,
50//! >;
51//!
52//! let dimensions = Dimensions::new(800.0, 600.0);
53//! let manager = CotisLayoutManager::new(dimensions);
54//! // let app = CotisApp::new(renderer, manager, CotisLayoutToRenderListPipeForGenerics);
55//! ```
56//!
57//! See [`cotis-layout` examples](https://github.com/igna-778/cotis-layout/tree/main/examples)
58//! — especially `support.rs` for a complete `StandardRenderCmds` alias and
59//! `circle_example.rs` for extending the pipeline with custom drawables.
60//!
61//! # Extending with custom drawables
62//!
63//! Append your type to the tail of a `RenderTList` and implement
64//! [`FromRenderCommandOutput`](cotis_layout_pipes::FromRenderCommandOutput). Return `Some(cmd)`
65//! to emit a draw command or `None` to skip. See
66//! [`cotis_layout_pipes`] for decode rules and the extension model.
67//!
68//! # Modules
69//!
70//! - [`cotis_layout_pipes`] — pipe implementation, decode traits, and built-in command decoders.
71
72pub mod cotis_layout_pipes;