cotis-layout 0.1.0-alpha

Flexbox-style layout engine for Cotis
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113

# cotis-layout

`cotis-layout` is the reference flexbox-style layout engine for [Cotis](https://docs.rs/cotis). It implements Cotis's layout traits, runs sizing and positioning over a configured element tree, and produces a stream of render commands for downstream pipes and renderers.

> **Status:** Early `0.1.0-alpha` release. APIs are still evolving alongside the core Cotis crates.

This repository contains the **layout engine** only. It does not open a window or draw pixels by itself. For a runnable desktop app, combine it with core Cotis crates, a pipe, and a renderer backend from the [ecosystem](#ecosystem) below.

## Architecture

Each frame flows through five stages. This crate owns the layout manager stage:

```mermaid
flowchart LR
    UI[UI_closure] --> LayoutMgr[CotisLayoutManager]
    LayoutMgr --> LayoutOut[RenderCommandOutput]
    LayoutOut --> Pipe[cotis-pipes]
    Pipe --> Renderer[CotisRenderer]
```

1. A layout manager prepares for the frame.
2. UI code builds the element tree through the configurator API.
3. The layout manager produces layout output items.
4. A pipe transforms those items into renderer commands.
5. A renderer draws the command stream.

## Installation

Add the layout engine and required core crates to your `Cargo.toml`:

```toml
cotis-layout = "0.1.0-alpha"
cotis = "0.1.0-alpha"
cotis-defaults = "0.1.0-alpha"
cotis-utils = "0.1.0-alpha"
```

A full desktop application also needs a pipe and a renderer. See [Quick start](#quick-start) and [Ecosystem](#ecosystem).

## Quick start

Clone a renderer backend and run its example:

```bash
git clone https://github.com/igna-778/cotis-wgpu
cd cotis-wgpu
cargo run --example basic_example -p cotis-wgpu
```

That example opens a resizable window, lays out UI with `cotis-layout` and `cotis-pipes`, and renders through wgpu.

### Typical app wiring

```rust
use cotis::cotis_app::CotisApp;
use cotis_layout::preamble::CotisLayoutManager;
use cotis_pipes::cotis_layout_pipes::CotisLayoutToRenderListPipeForGenerics;
use cotis_utils::math::Dimensions;
use cotis_wgpu::prelude::*;

let renderer = CotisWgpuRenderer::auto_start();
let manager = CotisLayoutManager::new(Dimensions::new(1000.0, 800.0));
let mut app = CotisApp::new(renderer, manager, CotisLayoutToRenderListPipeForGenerics);

while !app.render().window_should_close() {
    app.compute_frame(|root| {
        // Build your UI tree here.
    });
}
```

Swap `cotis-wgpu` for [`cotis-raylib`](https://github.com/igna-778/cotis-raylib) or another backend without changing layout or UI code.

### Local examples

This repository ships source examples under `examples/` (`basic_example`, `circle_example`, `gradients_example`). They use `cotis-raylib` as the renderer backend. Once the Cotis ecosystem crates are published to crates.io, you can run:

```bash
cargo run --example basic_example
```

Until then, use the runnable demos in [cotis-wgpu](https://github.com/igna-778/cotis-wgpu) or [cotis-raylib](https://github.com/igna-778/cotis-raylib).

## Ecosystem

Cotis is split across several repositories. This repo provides the layout engine; sibling repos provide core traits, pipes, and render backends.

| Repository | Role |
|------------|------|
| [`cotis`](https://github.com/igna-778/cotis) | Core traits and `CotisApp` orchestration |
| [**cotis-layout**](https://github.com/igna-778/cotis-layout) (this repo) | Flexbox-style layout engine (`CotisLayoutManager`) |
| [`cotis-pipes`](https://github.com/igna-778/cotis-pipes) | Layout output to render commands (`CotisLayoutToRenderListPipeForGenerics`) |
| [`cotis-wgpu`](https://github.com/igna-778/cotis-wgpu) | Desktop renderer (wgpu + winit + glyphon) |
| [`cotis-raylib`](https://github.com/igna-778/cotis-raylib) | Desktop renderer (raylib) |
| [`cotis-renderer-template`](https://github.com/igna-778/cotis-renderer-template) | Scaffold for authoring a custom render backend |
| [`cotis-cli`](https://github.com/igna-778/cotis-cli) | Plugin host for installable build and run routines |

Pick a renderer backend and swap it without changing layout or UI code. Use `cotis-renderer-template` to implement a new backend.

## Features

| Feature | Effect |
|---------|--------|
| `complex-color` | Meta-feature enabling both color features below |
| `complex_color` | Forwards to `cotis-defaults/complex_color` |
| `complex_colored_text` | Forwards to `cotis-defaults/complex_colored_text` |
| `serialization` | Enables `serde` on render output types and serialization in `cotis`, `cotis-defaults`, and `cotis-utils` |

## Documentation

- API reference: `cargo doc --open`
- Published docs: [cotis-layout](https://docs.rs/cotis-layout)
- Core crate docs: [cotis](https://docs.rs/cotis), [cotis-defaults](https://docs.rs/cotis-defaults), [cotis-utils](https://docs.rs/cotis-utils)